## 1.4 I/O Restrictions

I/O Restrictions is a feature that was introduced in POV-Ray for Unix 3.5. The purpose of this feature is to attempt to at least partially protect a machine running POV-Ray from having files read or written outside of a given set of directories.

The need for this is related to the fact that the POV-Ray scene language has, over the years, become something more akin to a scripting language combined with a scene-description model. It is now possible to write obfuscated POV-Ray code, and to open, create, read and write arbitrary files anywhere on the target system's hard disk, subject to operating system permission.

The basic idea of I/O Restrictions is to attempt to protect the user from a script that may have been downloaded from an untrusted source, and which may attempt to create or modify files that it should not.

The I/O Restriction facility hooks the file open and creation functions in the core POV-Ray renderer code, and allows the Unix version to allow or deny any particular file operation.

Note: We do not guarantee that the I/O Restriction facility will actually stop anything from happening. There is always the chance that, like almost all software, it could have a bug in it that causes it to malfunction. Therefore, the onus is on the person who chooses to load an INI or scene file into POV-Ray to ensure that it does not do anything that it should not do. Please consider I/O Restrictions just a sometimes-helpful backup for manual checks.

Please read this section in full so that you understand the caveats and conditions of the facility, as some directories are allowed by default.

### 1.4.1 Configuration file format

The I/O Restrictions are configured by two separate configuration files. This can be a system-wide configuration, or a user configuration file located in the following places, on most systems `$PREFIX` is `/usr/local`.

- `$PREFIX/etc/povray/3.7/povray.conf`
- `$HOME/.povray/3.7/povray.conf`

POV-Ray will always use the most strict version of what is specified; user settings can only make security more strict.

The general syntax of these files is:

    ;Comment

    [Section]
    setting

Warning: If neither of these files exists I/O Restrictions are deactivated!

### 1.4.2 File I/O Security

The `[File I/O Security]` section only contains a single setting which is either `none`, `read-only` or `restricted`.

- `none` means that there are no restrictions other than those enforced by the file system.
- `read-only` means that files may be read without restriction.
- `restricted` means that files access is subject to restrictions as specified in the rest of this file. See below for details.

### 1.4.3 Shellout Security

The `[Shellout Security]` section determines whether POV-Ray will be allowed to call scripts.

This section contains a single setting which is either `allowed` or `forbidden`.

- `allowed` means that shellout will work as specified in the documentation.
- `forbidden` means that shellout will be disabled.

See the section Shell-out to Operating System for more details.

### 1.4.4 Permitted Paths

The `[Permitted Paths]` section contains a list of directories which are specifically allowed for either reading or reading and writing. These paths are only used when the setting for `[File I/O Security]` is either `read-only` or `restricted`.

- Directories that are only allowed for reading are added with `read=directory`.
- For allowing reading and writing use `read+write=directory`.
- If `[File I/O Security]` is set to `read-only`, any directory can be used to read in a file, and `read+write` entries must specify which directories are allowed for writing.
- If `[File I/O Security]` is set to `restricted`, reading and writing is allowed only in the directories given by the `read` and `read+write` entries.

If the directory name contains spaces it has to be quoted or doubly-quoted. There can be spaces before and after the equal sign. Read-only and read/write entries can be specified in any order.

If you want the permissions for a specified directory to also extend to all of its subdirectories wildcards are permitted.

For example:

    read*=directory
    read+write*=directory

Both relative and absolute paths are permitted, so the dot character can be especially useful. The install directory, typically `/usr/local/share/povray-3.7` or `/usr/share/povray-3.7`, can be specified with `%INSTALLDIR%`, the user home directory with `%HOME%`. The install directory and its descendents are typically only writable by root; therefore it does not make sense to have `%INSTALLDIR%` in read/write directory paths.

Note: Since user-level permissions are at least as strict as system-level restrictions, any paths specified in the system-wide `povray.conf` will also need to be specified in `~/.povray/3.7/povray.conf` if this file exists.

#### 1.4.4.1 Examples for path settings

    [Permitted Paths]
    read=%INSTALLDIR%

Would permit reading from the directory where the POV-Ray supplementary files are installed.

Note that the installdir location does not relate to where the binary is run from - it relates to the information defined at compile-time. Relative paths are legal as well, and will be resolved only once at load time (but relative to the current directory, not the installdir). For example, a relative path like the following ...

    [Permitted Paths]
    read+write=../output

Would be resolved with relation to the current directory at the time POV-Ray for Unix was started, so if you started povray while in the directory `~/myscenes/newscene`, then the above path would be resolved as `~/myscenes/output`. Please note that the actual location of the povray binary is not relevent here - it is the current directory that matters, which is typically not that of the program.

### 1.4.5 Example configuration file

Here is a complete example for a `povray.conf` file:

    [File I/O Security]
    ; none
    ; read-only
    restricted

    [Shellout Security]
    allowed
    ; forbidden

    [Permitted Paths]
    read*=%INSTALLDIR%/include
    read*=%INSTALLDIR%/scenes
    read=%INSTALLDIR%/../../etc
    read+write=.
    read+write*=/tmp