====== Setting up file permissions ======

[[..:DokuWiki]] stores its data in plain text files. To be able to do this, DokuWiki needs sufficient permissions to write to these files. At the same time, leaving the permissions too loose can introduce security risks.

DokuWiki is executed by PHP, so the PHP process needs to be able to write to these files.  The PHP process usually runs with the permissions of the webserver, so the webserver needs to be able to write to these files.

The following permissions must be modified for the respective DokuWiki functions to work:
  * ''data/'' and ''data/tmp/'' directory: All files in and below these directories must be writable by the web process for DokuWiki to work.
  * ''lib/plugins/'' directory: This directory must be writable by the web process for the [[plugin:plugin]]-Manager to work
  * ''lib/'' directory: This directory must be readable by the public for style sheets to display. 755 works fine.

The following files are copied by the installer.php from the respective *.dist files and given the correct permissions for the web process automatically:
  * ''conf/'' directory, following files must be writable by the web process: 
     * ''local.php'' for the [[..:installer]] and for subsequent web configuration to work.
     * ''users.auth.php'' and ''acl.auth.php'' for the [[..:ACL]] web configuration and [[plugin:usermanager]] to work.
===== Windows (using Microsoft IIS) =====

To make the files in the ''data'' and ''conf'' directory writable you need to give "Write" access to the
Internet Guest Account (''IUSR_//computername//'') or the appropriate web server group (like ''IIS_WPG''). This is done through the right-click context menu on folders and files choosing "Properties" and selecting the "security" tab.

A good description with screenshots is available [[http://www.enewsletterpro.com/support/permissions.asp|here]].

Note: If you are running PHP under IIS6 with the FastCGI module [[http://www.microsoft.com/downloads/details.aspx?FamilyID=2d481579-9a7c-4632-b6e6-dee9097f9dc5&DisplayLang=en|FastCGI Extension for IIS 6.0]] the user account that needs the permissions will most likely be "NETWORK SERVICE" rather than the Internet Guest Account

For IIS 7/7.5 this will be the application pools account. You can't add this via the GUI, you must use the 'icacls' command line tool: icacls c:\pathtodirectory /grant "IIS AppPool\yourAppPoolName":(OI)(CI)F  --This will grant full control with propogation to the specified directory. For more info, google ICACLS.

Note: Check out the web platform installer v3.0 for the necessary components and add IIS:IP and Domain Restrictions (under products)

===== Unix =====

This will apply if you install DokuWiki on a Linux, MacOS X or other Unix-like system. It is most probably also true for rented web space.

Note: under Linux additional file system ACLs (FACL) may apply, confer the commands "getfacl" and "setfacl" -- file permissions as described below may be meaningless if there are no rights according to FACLs.


==== File Permissions, a short reminder ====

This is not the place to explain the UNIX file permission system in detail. See [[wp>File_system_permissions|Wikipedia]]  for this. Here is just a short refresher:

  * Permissions for a file are dependent of the file's owner and group and the user who tries to access the file
  * There are permissions for read, write and execute
  * Each UNIX process runs with the permissions of an OS user and his groups
  * The web server is a UNIX process
  * PHP usually runs as part of the web server
  * DokuWiki will run with the permissions of the PHP processor
  * DokuWiki needs read, write and execute permissions for directories it needs to create files in
  * DokuWiki needs read and write permissions for files it needs to write to
  * DokuWiki needs read only permissions for files and directories it doesn't need to write to

To find the user and group your PHP process (web server) run under you could try to run the following PHP script:

<code php>
<?php

if(function_exists('posix_geteuid')){
    // use posix to get current uid and gid
    $uid   = posix_geteuid();
    $usr   = posix_getpwuid($uid);
    $user  = $usr['name'];
    $gid   = posix_getegid();
    $grp   = posix_getgrgid($gid);
    $group = $grp['name'];
}else{
    // try to create a file and read it's ids
    $tmp = tempnam ('/tmp', 'check');
    $uid = fileowner($tmp);
    $gid = filegroup($tmp);

    // try to run ls on it
    $out = `ls -l $tmp`;
    $lst = explode(' ',$out);
    $user  = $lst[2];
    $group = $lst[3];
    unlink($tmp);
}

echo "Your PHP process seems to run with the UID $uid ($user) and the GID $gid ($group)\n"; ?>
</code>

Alternatively, you can use short script with phpinfo(), see section User/Group in output:
<code php>
<?php
phpinfo();
?>
</code>

=== Common Permissions ===

Here are the most commonly used values for setting permissions on directories and files.

^ directories ^ files    ^ result ^
| ''0700'' | ''0600'' | read/write for owner only. Owner must be the same as the PHP process user. |
| ''0770'' | ''0660'' | read/write for owner and group. The PHP process user needs to be in the used group |
| ''0777'' | ''0666'' | read/write for everyone. **Dangerous** everybody with access to the server may write and delete your files. Use only as last resort on trusted machines. |

==== Which permissions to set? ====

So, how should you set the permissions of the directories mentioned above? In general you should try to set the permissions as restrictive as possible, but there is no general rule which permissions you need to set for your system.

If you have root (super user rights) you can change the owner of files and directories. This means you can change the owner of the DokuWiki files to the web server user (e.g. ''www-data'' or ''nobody'') and set the permissions to webserver only access. E.g. ''0600'' for files and ''0700'' for directories.

If you are a normal user you may be a member of the web server group and can change the files to be owned by this group. Then set the files and directories to be writable by this group. E.g. ''0660'' for files and ''0770'' for directories.

If you are alone on the server or running in a completely trusted environment you can simply change the permissions to give everyone access. E.g. ''0666'' for files and ''0777'' for directories.

If you're running on a shared web server it is recommended to contact your web server administrator or hosting support and ask for help and recommendations. Point them to this page and they should know what you need to do.

Note: When you found the correct settings for your directories you should change the [[config:fmode]] and [[config:dmode]] settings to reflect these settings.

==== How to set permissions? ====

On the command line use [[man>chmod]] for changing permissions, [[man>chown]] for changing the owner of files and dirs and [[man>chgrp]] for changing the group.  (Note that chown and chgrp may not be available or function as expected if you use a shared web hosting provider.)

When accessing your server through FTP, consult the manual of your FTP tool. Most graphical FTP tools have a dialog to set permissions (often to be found in the right-click context menu).

On some UN*X-like systems, you may be able to use filesystem ACLs to allow the PHP user to write to the files as well.  For Sun's ZFS, see the [[http://docs.sun.com/app/docs/doc/819-5461?l=en|Solaris ZFS Administrator's guide]]  for details.  For POSIX-draft compliant filesystems, like Linux ext2/3 or Sun's UFS on Solaris 8 or later, see the man pages for [[man>setfacl]] and [[man>getfacl]].  

Check with your system administrator -- some backup systems will ignore ACLs on files.  If available, ACLs are more secure than adding the PHP user to your group, giving away the files to the PHP user, or making the files world-writable.


==== If things go wrong ====

In certain situations, you may find that you are unable to delete or modify files created
by DokuWiki.  See [[tips:fixperms.php]] for a possible solution.



==== Tip: Using the setgid Bit ====
If you have commandline access to your server, you can use the ''setgid'' bit to retain permissions to delete files below the ''data/'' directory although they were created by the web server. On directories where the ''setgid'' bit is set, newly created files/directories belong to the same group the directory with the ''setgid'' belongs to. The following example shows how to achieve such a setup for the user ''foo'' who belongs to the group ''foo'':

  * data directory:
    * ''yourwiki> chmod -R 775 data/''
    * ''yourwiki> chown -R www-data:foo data/''
  * everything below the data directory:
    * ''yourwiki/data> chmod 2775 {attic,cache,index,locks,media,meta,pages,tmp}''
    * ''yourwiki/data> chown www-data:foo {attic,cache,index,locks,media,meta,pages,tmp}''

In order to fully retain correct permissions, you must also change [[config:dmode|dmode]] to 02775 or similar so that newly created directories will also get the ''setgid'' bit set correctly.
===== How do I make specific pages in the wiki read-only? =====

See [[faq:pageprotect|this FAQ entry]].