## 1. Introduction

The UNIX filesystem is built with a system of permissions which defines user-level access for every file and directory. These permissions can be tailored to restrict or allow whatever access rights are desired.

There are three types of access permissions, with different implications for files and directories:

|  Access Right |  Files                |     Directories |
| ------------- | --------------------- | --------------- |
|  Read         | allow opening the file for reading     | allow listing of the contents of a directory |
|  Write        | allow edits and deletion               | allow modification of the contents in a directory (delete, create, rename) |
|  Execute      | allow executing the file as a program |  allow navigation into the directory |

And there are three defined realms of users:

|  User Realm  | Description |
| ------------ | --------------- |
|  `user`     | any individual UNIX account |
|  `group`    |  a defined set of users with common rights as a `group` |
|  `other`    |  all other users who are not the user or group owner. a.k.a. world |

## 2. Understanding Permissions Notation on the Command Line

**Example:** using the long list command on a theoretical directory `/home/bob/`:

| command | output |
| ------- | ------ |
|  `ls -l /home/bob`  |  `-rwxr-xr-x   1   bob   bobsgroup   1093  Nov 21 12:14   file.txt` |

There are 10 symbols in the left column describing permissions: `-rwxr-xr-x`

Using positions `0123456789` for `-rwxr-xr-x` , here's how it breaks down:

|  symbol |  character |  description |
| ------- | ---------- | -----------  |
|  0      | `-`      |   describes the type of file. - is a plain file. d is a directory. There are other types, as well. |
|  1      | `r`     |   user `read enabled` |
|  2      | `w`     |   user `write enabled` |
|  3      | `x`     |   user `execute enabled` |            
|  4      | `r`     |   group `read enabled`   |
|  5      | `-`     |   group `write disabled` |
|  6      | `x`     |   group `execute enabled` |
|  7      | `r`     |   other `read enabled` |
|  8      | `-`     |   other `write disabled` |
|  9      | `x`     |    other `execute enabled` |

To sum up, a file with permissions `-rwxr-xr-x` is a plain file with the following permission bits set: 
read/write/execute for user read/execute for group read/execute for other

## 3. Octal (numeric) Permissions Notation

The read/write/execute permissions can also be described using an octal numeric method:

|  number |  binary value |  character |          permissions
| -------- | ------------- | ----------- | ------------------- |
|  0      |  000          | `---`         |     `all disabled` |
|  1      | 001          | `--x`         |          `execute` |
|  2      | 010          | `-w-`         |            `write` |
|  3      | 011          | `-wx`         |    `write,execute` |
|  4      | 100          | `r--`         |             `read` |
|  5      | 101          | `r-x`         |     `read,execute` |
|  6      | 110          | `rw-`         |       `read,write` |
|  7      | 111          |  `rwx`        | `read,write,execute` |

With 3 sets of `rwx` for user/group/other, this translates to a single 3-digit number. So, using the earlier example, a file with permissions `-rwxr-xr-x` would be: 755

| number | character          | permissions |
| ------  | ----------------- | ----------- |
|  755    |  `rwxr-xr-x`   |  `user`: read,write,execute `group`: read,execute `other`: read,execute |

## 4. Setuid, Setgid, and the Sticky Bit

### Definitions

|  Access Right  | Files          | Directories |
| -------------- | -----------    | ----------- |
|  `setuid`      |  executed with the rights of the file's owner, not the user starting the job does not apply | does not apply | 
|  `setgid`      |   executed with the rights of the group owner, not the group of the user starting the job |  Files created within setgid directories inherit that directory's group ownership (GID). |
|  `sticky bit` |  does not apply  | In a "sticky" directory, users can only delete files they own, regardless of group/other permissions settings on the directory |

Actually, the 3-digit number representing permissions in the previous section is a bit of a hoax. It's really a 4-digit number, with an implied 0 at the beginning. So, 755 is actually 0755. Huh?

This prefix number refers to special permissions bits for setuid, setgid, and the sticky bit. These are disabled by default (hence the default 0), but can be enabled in the same manner as the `rwx` bits.

### Octal/Symbolic representation

|  number |  character   |           permissions |
|  ------ | ------------ | --------------------- |
|  0000   | `---------`  |           `all disabled` |
|  1000   | `--------t`  |                `sticky` |
|  2000   | `-----s---`  |                `setgid` |
|  3000   | `-----s--t`  |         `setgid,sticky` |
|  4000   | `--s------`  |                `setuid` |
|  5000   | `--s-----t`  |         `setuid.sticky` |
|  6000   | `--s--s---`  |         `setuid,setgid` |
|  7000   | `--s--s--t`  |  `setuid,setgid,sticky` |

Notice how the symbloic `s` and `t` take the place of `X` in the character description. Because of this, the state is the execute bit is hidden, but there is a convention built in to help with this. Whenever the `s/t` bit is in lower-case that implies that the execute bit is turned ON. When capitalized, execute is OFF.

#### Examples

|  number |  character   |                    permissions |
|  ------ | -----------  | ------------------------------ |
|  4755   |  `-rwsr-xr-x` |     setuid is ON, and user execute is ON |
|  2760   | `drwxrwS---`  |  setgid is ON, and group execute is OFF |
|  1777   | `drwxrwxrwT`  |  sticky is ON, and other execute is OFF |

## 5. Using the `chmod` command

### Usage

`chmod [-R] changes filename(s)`

-   The `-R` option performs recursive changes down through the filesystem tree.

### Symbol Reference Table

|  Symbol |  Meaning |
|  ------ | -------  |
|  `u`    |  user |
|  `g`    | group |
|  `o`    | other |
|  `a`    | all |
|  `+`    | adds a permission |
|  `-`    | removes a permission |
|  `=`    | assigns an absolute permission |
|  `r`    | read |
|  `w`    | write |
|  `x`    | execute |
|  `s,S`  | setuid / setgid |
|  `t,T`  | sticky bit |

#### Examples

| `chmod` command syntax   |   new permissions |
|  ---------------------   | ------------------- |
|  `chmod 755 file.txt`       |  `rwxr-xr-x` |
|  `chmod a=rwx work`         |  `rwxrwxrwx` |
|  `chmod 1777 work`          |  `rwxrwxrwt` (sticky bit set) |
|  `chmod ug+x,o-w file.txt`  |  e.g. from `rw-rw-rw-`, to `rwxrwxr--` |
|  `chmod u+s,o-rwx file.txt` |  e.g. from `rw-r-xrwx`, to `rwSr-x---` |
|  `chmod -R 700 work`      |    changes `work` and everything beneath to `rwx------` |

## 6. `umask`

`umask` is a command to set the default mask for new files, which means disabling specified permission bits.

-   The `umask` DOES NOT ENABLE any permissions!

-   Note that different types of applications (compilers, text editors) will create new files with different default permissions settings. `umask` is typically defined in the acount's startup file (`e.g.` .profile .cshrc .bash\_profile). Note that running a `umask` command will not change the permissions of any existing files, only how permissions are set in the creation of new files.

### Syntax

`umask [mask]`

### Examples

|  default setting | `umask` command  |   new permissions |
|  --------------- |  --------------- | ----------------- |
|        `rwxr-xr-x` | `umask 077`     |        `rwx------` |
|        `rw-rw-rw-` | `umask 022`     |        `rw-r--r--` |
|        `rwxrwxrwt` | `umask 002`     |        `rwxrwxr-t` |
|        `rwxr-x-w-` | `umask 777`     |        `---------` |

## 7. Recommended settings for a shared directory

When a group is sharing a directory, setting permissions properly will allow multiple users to work in the same space effectively, but also securely.

**Note:** This example below will have all rights disabled for `other` to make things easier to look at. When setting up a shared directory, `write` access for `other` should be disabled, but `read/execute` may be enabled depending upon who needs access to the directory.

**Example:**

There are three user accounts named:

-   `arnie`
-   `brenna`
-   `cathy`

who all belong to a defined UNIX group:

-   `support`

and use a common directory:

-   `/users/project/`

The goal is for all members of the group `support` to have write access to `/users/project` and to have all new files they create in that directory be automatically writable by the group.

Now, let's say that each user's default group is NOT `support`. Typically in Linux, for example, each user is assigned a unique default group for better security (e.g. `user: arnie`, `default group: arnie` ). This convention of **Single User Group** is the topic for another discussion, however.

`/users/support/`: to setgid or not to setgid...




| property | **setgid OFF** | **setgid ON** |
| -------- | -------------- | ------------- |
| **permissions on `/users/project/`** | `drwxrwx---` | `drwxrws---` |
| **octal** | 0770 | 2770 |
| **ownership of new files created in `/users/project/` (e.g. by `arnie`)** | user: `arnie`, group: **arnie** | user: `arnie`, group: **support** |


Having `root` own `/users/project` is not required. It could realistically be owned by any of the 3 users, but a privileged user like root is often more appropriate (e.g. If the `arnie` account is removed, it's awkward if `arnie` also owns the shared directory).

To sum up the chart above, all new files created by `arnie` in `/users/project` will be owned by the group **support** when `setgid` is on (note: enabling `default group write` depends on the `umask` setting). By default, in other directories without `setgid`, `arnie` can create files and retain exclusive ownership. So, `setgid` is a convenient tool for enabling group sharing, though it should still be used carefully.