ocPortal Tutorial: Linux file permissions
Written by Chris Graham, ocProducts
Most ocPortal 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. ocPortal 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 ocPortal needs on most web hosts, 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.
Table of contents
How Linux file permissions work
Each 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 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 ocPortal 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 ocPortal, 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
A typical error that is due to bad file permissions (on the 'FR' directory in this case) |
Consider these situations:
- ocPortal needs to run - it therefore needs to be able to list the contents of all it's directories and read all it's 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
- ocPortal 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 ocPortal automatically, or the directory needs "world write permission" (permission for anyone to write to the directory)
- ocPortal needs to add a file to collaboration/pages/comcode_custom/EN - as above, however the ocPortal quick installer would have given this directory the necessary permissions during installation
- ocPortal needs to modify a file themes/mytheme/templates_custom/HEADER.tpl - usually this would not be a problem, as it would have been created by PHP when the HEADER.tpl was overrode 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
- ocPortal needs to delete themes/mytheme/templates_cached/EN/HEADER.tcd [happens a lot when editing things and ocPortal tries to clear caches] - as above, normally there would be no problem but if uploaded, it would be best to just delete the .tcd files manually and allow ocPortal to regenerate them (they're only cache files)
Changing permissions of a directory using FTP |
If ocPortal made something itself, it can write to/into it, without problem. However if it was uploaded and ocPortal 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 ocPortal requires are listed in the install guide.
How to set Linux file permissions using FTP
Changing permissions of a file using FTP |
The screen-shots show how to set file permissions for:
- a file that needs to be world writeable
- a directory that needs to be world writeable