Composr Tutorial: Linux file permissions
Written by Chris Graham (ocProducts)Most Composr sites are hosted on Linux web servers. Linux uses the traditional file permission scheme from Unix, which is actually a very simple scheme in terms of what can be done, but technically complex to understand. Composr requires special file permissions for any uploaded file or directory that it needs to write to.
This tutorial is intended to cover the theory behind the permissions Composr needs on most webhosts, and give practical explanations on how to work with them. It is not intended as a discussion on the relative merits of different server configurations, which is covered in the Security tutorial. The Advanced installation tutorial covers the permissions Composr needs.
How Linux file permissions workEach file and directory on Linux has three numbers associated with it:
- the number of the user that 'owns' it
- the number of the group that 'group owns' it
- the number that stores the file permissions
The file permission number (basically) is a number consisting of 3 parts (not 3 digits but 3 octets, as they can only be 0-7, not 0-9). From left-to-right, the numbers signify:
- permissions that the 'owner' user has for it
- permissions that the 'group owner' group has for it
- permissions that anyone ('everyone') on the system has, irrespective of what groups they are in or what user they are
Each of these parts has a number range from 0-7, that is made up by a process of addition:
- start with the number zero
- if execute permission is needed, add 1
- if write permission is needed, add 2
- if read permission is needed, add 4
Execute permission is never needed in Composr for files as even the PHP files that are executed aren't done so directory (except on some unusual server configurations). However, execute permission for a directory actually signifies permission to list the contents of the directory, so this should always be present, and in Composr, is present for 'everyone'.
Permissions can actually be written out in a more human readable form in the following format as 'rwx rwx rwx' where any of those symbols are replaced with a dash if a permission is not given, and each triplet of symbols represents one of the numeric parts.
Common file permissions are:
- 777 (rwx rwx rwx) – directories that everyone can write to
- 755 (rwx r-x r-x) – directories that everyone can read but only the owner can write files into
- 666 (rw- rw- rw-) – files that everyone can write to
- 644 (rw- r-- r--) – files that everyone can read but only the owner can write to
The process of setting file permissions is often referred to as 'chmodding', as the Linux command to change file permissions is 'chmod'.
PHP Web applicationsMost web servers run PHP scripts with the credentials of a user named nobody. Therefore the user nobody needs to be able to do everything Composr needs to do. Unfortunately the main problem with permissions that make them so tricky with PHP web applications is that the user used to upload files is not nobody, and nobody is not in the same primary group as the FTP user either. There is usually no convenient way to change ownership of a file so as to assign them to nobody, and if it was done, it would be a security problem anyway (as the entire installation directory would be writable to by any PHP script on the server). Therefore, if Composr is to write to any uploaded file, it must be possible for any user to do so – and hence permissions must be set as such.
Consider these situations:
- Composr needs to run – it therefore needs to be able to list the contents of all its directories and read all its files – this means there must be 'world read permission' (permission for anyone to read the file/directory) for all files and directories, and 'world execute permission' for all directories – this is almost always provided by default fortunately, so does not need to be set
- Composr needs to add a file to collaboration/pages/comcode_custom/FR – to make a file into a directory, there must be write permission for that directory – therefore either the directory must have been made by Composr automatically, or the directory needs 'world write permission' (permission for anyone to write to the directory)
- Composr needs to add a file to collaboration/pages/comcode_custom/EN – as above, however the Composr quick installer would have given this directory the necessary permissions during installation
- Composr needs to modify a file themes/mytheme/templates_custom/GLOBAL_HTML_WRAP.tpl – usually this would not be a problem, as it would have been created by PHP when the GLOBAL_HTML_WRAP.tpl was overridden from that of the default theme, and hence owned by nobody – however, if the theme was uploaded manually then the file would need to be given 'world write' permission
- Composr needs to delete themes/mytheme/templates_cached/EN/GLOBAL_HTML_WRAP.tcp (this happens a lot when editing things and Composr tries to clear caches) – as above, normally there would be no problem, but if a webmaster uploads new templates it is often useful for them to delete the .tcp files themselves manually and allow Composr to regenerate them
The gist of these situations is quite simple:
If Composr made something itself, it can write to/into it, without problem, but it also needs to be writable by the webmaster via FTP so is given 'world write' permissions. If a file was uploaded and Composr needs to write to/into it, and the quick installer couldn't set permissions for it (usually because it was added after installation), then 'world write' permissions need setting manually.
A typical file permission issue is shown in the screen-shot.
File permissions that Composr requires are listed in the install guide.
How to set Linux file permissions using FTP
The screen-shots show how to set file permissions for:
- a file that needs to be world writable
- a directory that needs to be world writable
Please rate this tutorial:
Have a suggestion? Report an issue on the tracker.