View source for Unix File Permission Primer

Most of the [[:Category:Computers Available on the CS Network|computers available on our network]] run Linux, which uses the standard Unix file permission system.  Understanding file permissions can help when you want to share files with others or use our webserver to [[:Category:Webpages and Webservices|host your own webpages]].

The first thing to know is that you don't need to do anything special if you don't want anyone else to see your files.  By default, files that you create will only be accessible by you and no one else.

That said, let's get started.

== Viewing File Permissions ==

You can view file permissions from the Unix command line with the command <code>ls -l</code> .  That will show you something like the following:

<pre>
drwx------. 2 account users    3 Sep 12 15:47 Desktop
drwx------. 4 account users    4 Aug 26  2008 Mail
-rw-------. 1 account users 4153 Apr 16  2013 README
drwx---r-x. 3 account users    4 Sep 12 15:47 public_html
</pre>

The last column gives you the name of the file or directory.  The first column shows the permissions.  The third and fourth columns ("account" and "users" in this example) give the owning account and group, respectively.  (We're going to ignore the other columns, since they don't have anything to do with file permissions.)

== The Basics ==

In Unix, every file (and directory) belongs to one account and one group.  That gives three sets of permissions: one for the owning account (often shortened to "u", for ''u''ser), one for members of the file's group ("g"), and one for everyone else ("o", for ''o''ther).

There are three basic permissions in each set: '''r'''ead, '''w'''rite, and e'''x'''ecute.  For files, those are pretty straightforward: "read" lets you see the file's contents; "write" lets you change the file's contents; and "execute" lets you run the file as a program.  For directories, the meanings are a little less obvious: "read" lets you see what the contents of the directory are; "write" lets you add and remove (and rename) files in the directory; and "execute" lets you access files in the directory.

'''Note''': There are a couple of common but not necessarily obvious combinations of permissions here.  First, in order to read a file, you must have read permission for the file ''and'' execute permission for the directory containing the file (and for the directory containing that directory, and so on).  Second, you can have a directory that gives you execute permission but not read permission.  In that case, you could access files in the directory, but only if you already knew what the files' names were, since you couldn't get a list of files in the directory.

In the output of <code>ls -l</code>, the permissions column is a string of ten characters that might look something like "<tt>drwx---r-x</tt>".  The first character isn't really a permission--it's an indication of the type of file. ("'''-'''" means it's a regular file.  Other types include (with their signifying characters in bold) '''b'''lock special file, '''c'''haracter special file, '''d'''irectory, symbolic '''l'''ink, named '''p'''ipe, and '''s'''ocket. Anything else gets a "'''?'''", but you'll probably never see that character.)  The remaining characters are in three groups of three.  Each group corresponds, from left to right, to the user, group, and other permission sets.  Within each group, the first character is an "'''r'''" if that set contains the read permission and a "'''-'''" if it does not.  The next two characters are either "'''w'''" or "'''-'''" for the write permission and "'''x'''" or "'''-'''" for the execute permission.

Putting all of that together lets us explain these permissions: "<tt>drwx---r-x</tt>".  That's a directory that gives all three permissions to the owning account, no access to members of the owning group, and read and execute permission to everyone else.

It can sometimes help to think of the permissions in terms of a matrix, like this:

{|class="wikitable" style="text-align: center"
|-
!!!read!!write!!execute
|-
!user
|r||w||x
|-
!group
| -||-||-
|-
!other
|r||-||x
|}

'''Note''': When the system checks permissions on a file (or directory), it first checks to see if you're the owner of the file; if so, it uses the "user" permissions.  Otherwise, it checks to see if you're a member of the file's group; if so, it uses the group permissions.  Otherwise, it uses the global permissions.  This means that you can have a situation like the above example where members of a particular group actually have ''fewer'' permissions than people who are not members of the group.

== Permission Representations ==

<tt>ls -l</tt> is the most common way to ''view'' file permissions.  Unfortunately, when you want to change permissions, the programs for that use completely different ways of writing permissions.  There are two different ways to describe permissions; most programs will accept either way and we'll cover both of them here.

=== Symbolic Representation ===

In the symbolic representation, each permission and permission set is shortened to a single character; the "r", "w", and "x" you might expect for the permissions, and "u", "g", and "o" for the "user", "group", and "other" sets.  You can either specify permissions as a change from an existing value with "+" or "-", or you can specify them exactly with "=".  Different sets are separated by commas.  As a special case, you can use the "a" character to represent "all" sets; it will apply its permissions to all three of the "user", "group", and "other" permission sets.

Here are some examples:

* <tt>u=rwx,g=,o=rx</tt> - This specifies all of the permissions exactly and would be shown by <tt>ls -l</tt> as "<tt>-rwx---r-x</tt>".  The owning account has full permissions, members of the owning group have no permissions, and everyone else has read and execute permissions.
* <tt>g-w,o-rwx</tt> - This is a modification of an existing set of permissions.  Write permission is being removed from the "group" permission set and all three permissions are being removed from the "other" set.
* <tt>u-w,g+r</tt> - Also a modification of an existing set of permissions.  The owner no longer has write access, but members of the owning group can now read the file.
* <tt>a+r,a-w</tt> - Another modification of an existing set of permissions.  Anyone can now read the file, but no one (not even the owner) can write to it.

=== Octal Representation ===

The symbolic representation for permissions is generally easy to read, but it can get a little long.  The octal representation is the opposite: it's short, but harder to read until you get used to it.

Octal representations of the basic permissions are three digits long and look something like this: "<tt>705</tt>".  The first digit represents the user permissions, the second digit is the group permissions, and the third digit shows the "other" permissions.  Each digit is the sum of up to three numbers: 4 for read permission, 2 for write permission, and 1 for execute permission.  The digit zero means that no permissions are given to that set.

Thus, the permissions with the octal representation "<tt>705</tt>" are the same as the symbolic representation "<tt>u=rwx,g=,o=rx</tt>" and would be shown by <tt>ls -l</tt> as "<tt>-rwx---r-x</tt>".  To put that into our matrix representation:

{|class="wikitable" style="text-align: center"
|-
!!!read<br>(4)!!write<br>(2)!!execute<br>(1)|| !!sum
|-
!user
|4||2||1|| ||7
|-
!group
|0||0||0|| ||0
|-
!other
|4||0||1|| ||5
|}

Here are some other example octal modes:

{|class="wikitable" style="text-align: center"
!Octal!!Symbolic!!<tt>ls -l</tt>
|-
|<tt>000</tt>||<tt>u=,g=,o=</tt>||<tt>----------</tt>
|-
|<tt>644</tt>||<tt>u=rw,g=r,o=r</tt>||<tt>-rw-r--r--</tt>
|-
|<tt>750</tt>||<tt>u=rwx,g=rx,o=</tt>||<tt>-rwxr-x---</tt>
|}

== Default Permissions ==

On ''our'' systems, the default permissions for files are <tt>600</tt> (<tt>u=rw,g=,o=</tt>) and the default permissions for directories are <tt>700</tt> (<tt>u=rwx,g=,o=</tt>).  Here's how those defaults are set (and how you can change them):

When you log in to a system, your default permissions are set by your shell's ''umask''.  The umask serves as a kind of limit on the permissions given to new files and directories.  Without a umask, files would all have permissions <tt>666</tt> (<tt>a=rw</tt> or <tt>u=rw,g=rw,o=rw</tt>) and directories would all have permissions <tt>777</tt> (<tt>a=rwx</tt> or <tt>u=rwx,g=rwx,o=rwx</tt>).  In actuality, when a file or directory is created, the system ''starts'' with those values (<tt>666</tt> for files and <tt>777</tt> for directories), but then applies the umask, which removes some of those starting permissions to arrive at the actual defaults.

You can view your umask with the <tt>umask</tt> command, which will show the umask in its octal representation.  Many shells (but not <tt>tcsh</tt>, which is used by many accounts on our systems) also support running <tt>umask -S</tt> to show the umask in symbolic representation.

Unfortunately, the meaning of the umask is different between the octal and symbolic representation.  (Unix is full of such unfortunate contradictions.)  The symbolic representation works as a limit on the permissions.  In symbolic terms, our default umask is <tt>u=rwx,g=,o=</tt>.  The process of applying the symbolic umask is ''logical intersection''; only permissions that are in the starting set ''and'' the umask will be applied to the file or directory being created.

For example, a file (starting permissions: <tt>a=rw</tt> (<tt>666</tt>)) plus a umask of <tt>u=rwx,g=rx,o=</tt> will give actual permissions of <tt>u=rw,g=r,o=</tt> (<tt>640</tt>).

The octal representation for the umask works as a list of permissions that will be ''taken away'' from the starting permissions.  In octal terms, our default umask is <tt>077</tt>.  The process of applying an octal umask is ''logical difference''; any permissions in the umask are removed from the starting permissions to arrive at the final permissions.

For example, a directory (starting permissions: <tt>777</tt> (<tt>a=rwx</tt>)) plus a umask of <tt>027</tt> will give actual permissions of <tt>750</tt> (<tt>u=rwx,g=rx,o=</tt>).

To change your umask, you use the <tt>umask</tt> command like this:

 umask ''new-permissions''

To make the change permanent, you'll have to add that command to your shell's initialization file.  On our systems, if you haven't changed your shell, that file will be <tt>~/.bashrc</tt> .

'''Warning''': The default shell on our systems used to be <tt>tcsh</tt>, which ''only'' understands octal notation for permissions.  ''Symbolic notation will not work.''  Many of our accounts still use <code>tcsh</code>.  To determine which shell you're using please see [[Shells Available for CS Accounts (bash, tcsh, etc.)|our shells page]].

== Changing Permissions ==

The <tt>chmod</tt> program is used to change permissions on a file or directory.  Its invocation looks roughly like this:

 chmod ''permissions'' ''file'' [''file'' ...]

The "''permissions''" parameter can be in either octal or symbolic representation.  If you use symbolic representation, you can use the "+" and "-" characters to add and remove permissions from the file without having to specify the full permissions.  For example, if you just want to add execute permission to a file for yourself, and not worry about the other particular permissions on the file, you can run:

 chmod u+x ''file''

When using octal notation, you muct specify the full permissions for the file every time.

== Advanced Topics ==

Most people won't need to delve too deeply into these topics, but they're here for completeness.

=== Extra Properties ===

In addition to the basic permissions mentioned above, there are three other properties that can be applied to files or directories in the same way as the basic permissions.  Those are:

* '''Set UID'''
** On a file: When the file is run as a program, it runs under the account of the file owner, not the account of the person running it.  This is often used for controlled access to things with restricted permissions.
*** e.g. Only <tt>root</tt> can edit the password database (otherwise you could change someone else's password), but the <tt>passwd</tt> program is set UID to <tt>root</tt> so that it can change your password (and only ''your'' password) for you.
** On a directory: Any file created in the directory (by someone who has write access to the directory) will be owned by the account that owns the directory.  (Under normal circumstances, when you create a file, ''your'' account will automatically own that file.)
* '''Set GID'''
** On a file: When the file is run as a program, it runs under the group of the file, not the group of the person running it.  Obviously, this is analogous to the set UID property, but for groups.
** On a directory: Files created in the directory are owned by the directory's group.  (Under normal circumstances, when you create a file, it will, by default, belong to your primary group.  On our systems, every person's primary group is the <tt>users</tt> group.)
*** This is often used when collaborating with others.  The way it works is that the sysadmins will create a system group for the collaboration and add all of the collaborators to it.  Then one of the collaborators creates a directory, changes its group (with <tt>chgrp</tt>) to the collaboration group, gives the directory group write permission, and adds the set GID property.  Then any files created in the directory will belong to the collaboration group.
* '''Sticky bit'''
** On a file: Basically not used.  It used to do some things on old versions of Unix, but it has no effect on our Linux systems.
** On a directory: Without the sticky bit, if you have write access to a directory, you can delete any file in that directory (alongside being able to create files in the directory).  ''With'' the sticky bit, if you have write access to a directory you can only delete files that you own.
*** This is used for directories like <tt>/tmp</tt> where everyone should be able to create files as needed but people shouldn't be able to mess with other people's files.

==== Extra Property Representations ====

In <tt>ls -l</tt> output, set UID and set GID are represented by putting an "'''s'''" in place of the user or group "'''x'''" character.  (If for some reason the object has set UID or set GID without the corresponding execute permission--which is almost always a mistake--the character used is a capital "'''S'''".)  The sticky bit is represented with a "'''t'''" in place of the "other" execute permission.  (Like the other properties, an object with the sticky bit but without "other" execute permission will have a capital "'''T'''".) For example:

* <tt>-rw-r-----</tt> is an ordinary file with no extra properties.
* <tt>-rwsr-xr-x</tt> is a set UID program.  (This is what <tt>passwd</tt> looks like on our systems.)
* <tt>-rwxr-sr-x</tt> is a set GID program.  (This is what <tt>screen</tt> looks like on our systems.)
* <tt>drwxrwxrwt</tt> is a directory with the sticky bit.  (This is what <tt>/tmp</tt> looks like on our systems.)

In octal notation, a fourth digit is added at the beginning of the permission string.  The constituent numbers for that fourth digit are: '''4''' for set UID, '''2''' for set GID, and '''1''' for the sticky bit.  A three digit number is assumed to have a zero for the extra fourth digit.  Examples:

* <tt>0640</tt> (or <tt>640</tt>) is our ordinary file with no extra properties again.
* <tt>4755</tt> is a set UID program.  (This is <tt>passwd</tt> again.)
* <tt>2755</tt> is a set GID program.  (This is <tt>screen</tt> again.)
* <tt>1777</tt> is a directory with the sticky bit.  (This is <tt>/tmp</tt> again.)

In symbolic notation, set UID and set GID are given by using an "'''s'''" with either the "u" or "g" sets.  The sticky bit is given by using a "'''t'''" with the "o" set.  Using the "s" with "o" or using the "t" with "u" or "g" isn't an error, but won't have any effect either.  Examples:

* <tt>u=rw,g=r,o=</tt> is our ordinary file with no extra properties again.
* <tt>u=rwxs,g=rx,o=rx</tt> is a set UID program.  (This is <tt>passwd</tt> again.)
* <tt>u=rwx,g=rxs,o=rx</tt> is a set GID program.  (This is <tt>screen</tt> again.)
* <tt>u=rwx,g=rwx,o=rwxt</tt> (or <tt>a=rwxt</tt>) is a directory with the sticky bit.  (This is <tt>/tmp</tt> again.)

=== Access Control Lists ===

Access Control Lists (ACLs) are a more complex way of managing permissions that work in addition to the standard permissions described above.  They are capable of handing certain situations that are simply not possible with the standard permissions.  Unfortunately, they add a significant amount of complexity, so we don't recommend using them unless there's no other way to accomplish your goals.  (And remember, when in doubt, you can always email [mailto:support@cs.jhu.edu support@cs.jhu.edu] for help with our systems.)

That said, we do have a limited amount of documentation about using ACLs on our systems.  Please see our page on [[NFSv4 Access Control Lists]].

=== SELinux ===

Keen-eyed viewers might have noticed that the output of <tt>ls -l</tt> includes a "." at the end of the permission listing.  (Except for files with ACLs, where the ACL "+" takes precedence over the ".".)  That dot serves as an indication that the file has an SELinux ''security context''.

Fortunately, you should never need to worry about SELinux.  We use it on our systems, but the systems should be configured in such a way that SELinux never prevents you from doing something that you should be allowed to do.  (We're mentioning it here just so you know what that little dot means.)

[[Category:Reference Material]]