File Permissions

This page briefly describes PmWiki's settings for file and directory permissions in a typical Unix environment.

First, let's look at PmWiki 2 without any cookbook scripts loaded. PmWiki needs to be able to write into the wiki.d/ directory to be able to save pages. And it needs to be able to write into the uploads/ directory to save uploads. Those are the *only* directories that need to be writable by the webserver. It doesn't matter to PmWiki who owns or creates those directories, as long as it has write permission to them.

All other directories should be owned by the account holder, and be accessible by the webserver (but normally not writable by the webserver).

That's it -- everything else depends on the specific PHP configuration and running environment, which is detailed below (and which is why there isn't a definitive answer that applies to every situation). But the above two rules are absolute and answer 95% of the questions about directory permissions.

In the example of "What ownerships should a pub/css/ directory have?", we simply ask "Does PmWiki need to create files in that directory?" The answer is "no", so the directory can (should) be owned by the administrator and only have basic read permissions (r-x) to the webserver. This means PmWiki shouldn't be responsible for creating the directory, because then the webserver would own the directory and not the administrator.

Okay, with that out of the way, here are some configuration specific details. If someone is on a Unix host, then the webserver typically runs with a userid and groupid that is different from the account holder (e.g, "apache", "www", or "httpd"). Thus, if the account holder creates the wiki.d/ and uploads/ directories, then they must also to set the directories to be world-writable (rwx) permissions in order for PmWiki (running as the webserver account) to create files there.

$ pwd
/home/pmichaud/public_html/pmwiki
$ mkdir uploads
$ mkdir wiki.d
$ chmod 777 uploads wiki.d        
$ ls -ld . uploads wiki.d
drwxr-xr-x   12 pmichaud pmichaud     1024 Feb 10 11:51 .         
drwxrwxrwx    8 pmichaud pmichaud     1024 Jan 23 11:58 uploads             
drwxrwxrwx    2 pmichaud pmichaud    54272 Feb 10 15:29 wiki.d      

However, lots of people don't like having those world-writable (rwx) permissions on directories. Thus, one way to get around that is to let the webserver own the directory directly, so that world-writable permissions aren't needed to save files there. However, most unix systems don't allow normal users to change file ownerships, so the way to get the webserver to own the directories is to let PmWiki create them, by temporarily granting write permissions to the parent and then running the pmwiki.php script to create the needed directories:

$ pwd
/home/pmichaud/public_html/pmwiki
$ chmod 777 .  
$ ls -ld .
drwxrwxrwx   12 pmichaud pmichaud     1024 Feb 10 11:51 .
# <-- execute pmwiki.php script from web browser -->
$ ls -ld . uploads wiki.d
drwxrwxrwx   12 pmichaud pmichaud     1024 Feb 10 11:51 .
drwxrwxr-x    8 apache   apache       1024 Jan 23 11:58 uploads
drwxrwxr-x    2 apache   apache      54272 Feb 10 15:29 wiki.d    
$ chmod 755 .
$ ls -ld . uploads wiki.d
drwxr-xr-x   12 pmichaud pmichaud     1024 Feb 10 11:51 .
drwxrwsr-x    8 apache   pmichaud     1024 Jan 23 11:58 uploads       
drwxrwsr-x    2 apache   pmichaud    54272 Feb 10 15:29 wiki.d         

Now the two directories are owned by apache and we don't have world-writable permissions on them, but pmichaud still has write permissions to the files and directories by virtue of the group ownership and permissions. The setgid bit also ensures that any files or subdirectories created within uploads/ or wiki.d/ will belong to the same (pmichaud) group.

HOWEVER, if a site is running in PHP's "safe_mode", then the "let PmWiki create the directories" solution doesn't work, as PHP will only create files in directories that are owned by the same user that owns the pmwiki.php script itself. Thus, PmWiki (apache) cannot create the directories in this case, or safe_mode will complain when PmWiki attempts to write a file into those directories. The *only* way for things to work in safe_mode is to manually create the needed directories and set their permissions to 777, as outlined at the beginning of this section.

And for those select webservers/PHP installations that are configured such that the PmWiki script runs with the same identity as the account holder, then everything "just works" without doing anything manually. PmWiki creates any directories as needed (each owned by the account holder), and permissions aren't generally an issue at all.

Okay, now let's look at cookbook scripts. If a cookbook script has files that it wants to make available to browsers, such files should generally be placed somewhere within the 'pub/' hierarchy and referenced via '$PubDirUrl'.

If a cookbook recipe needs to *write* files to disk, then the same rules apply to that directory as for the wiki.d/ and uploads/ directories above, with the exact ownerships and permissions depending on the webserver and PHP configuration. In general the cookbook recipe should do the same as PmWiki, and just call PmWiki's mkdirp($dir) function. PmWiki will then take care of creating the directory (if it can) or prompting for its creation as appropriate.

For example, if cookbook recipe 'frobot' wants to distribute a .css file, then that file should go somewhere like pub/css/frobot.css or pub/frobot/frobot.css. The directories and files in this case should be created and owned by the account owner, since the cookbook recipe doesn't need to create or modify any of the files when it runs.

As an alternate example, the Cookbook:MimeTeX recipe wants to be able to create cached images for the math markup, and those images need to be available to the browser. Thus, MimeTeX uses a pub/cache/ directory, which should be created in whatever manner was used to create the wiki.d/ and uploads/ directories (i.e., according to the webserver and PHP configuration). Again, Cookbook:MimeTeX just solves this by calling mkdirp("pub/cache"), and letting that function create the directory or prompt the administrator for the appropriate action based upon the server settings encountered.