Composr Tutorial: Linux file permissions

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 work

Each file and directory on Linux has three numbers associated with it:

1. the number of the user that 'owns' it
2. the number of the group that 'group owns' it
3. 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:

1. permissions that the 'owner' user has for it
2. permissions that the 'group owner' group has for it
3. 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 applications

Most 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:

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

See also

• Installation
• Advanced installation
• Security

Feedback

Have a suggestion? Report an issue on the tracker.