PERMISSIONS(5)
==============

NAME
----
permissions - manage system wide file permission settings

SYNOPSIS
--------
The `permctl(8)` program sets permissions and ownerships of files according to
the permission configuration files described in this manual page.

DESCRIPTION
-----------

=== File Format

The files /usr/share/permissions/permissions.* are line based and space
delimited. Lines starting with `'#'` are comments. A file entry consists of a
line of the format

----
/path/to/file user:group 0755
 +capabilities cap_net_admin=ep
 +acl user:somebody:rwx
----

- The first column specifies the file name. Directory names must end with a slash.
- The second column specifies the file owner and group delimited by a `':'` character.
- The third column specifies the file mode in octal.

Basic file entries can be extended by immediately following lines starting
with `+<keyword>`. The following keywords are supported:

*+capabilities*:: grant Linux capabilities to the file. The
  string specified here must conform to the rules found in __cap_from_text(3)__.
*+acl*:: grant additional access control list (ACL) entries to the file. The
  string specified here must conform to the rules found in __acl(5)__ (section
  ACL TEXT FORMS). The ACL entries will be merged with the basic octal file
  mode, therefore they must not contain any permissions for the file owner,
  group or other. If a file has extended ACL entries assigned, but none are
  configured in the permissions configuration, the extended ACL entries will
  be removed by `permctl(8)`.

The file name in the first column of the base entry can contain contain
variables as defined in the __variables.conf__ file. A variable expands to one
or more alternative path segments that relate to the same program or file.
permctl will look in each possible path resulting from the variable expansion
and apply the permissions accordingly.

The variables.conf file will ignore empty lines, whitespace only lines or
comment lines starting with `'#'`. All other lines must contain variable
definitions that follow the syntax **myvar = /path/1 /path/2**. This
example will declare a variable identified as `myvar` that will expand to
both specified path segments.

Path segments appearing in variable assignments need to be separated by
whitespace characters. The path values cannot contain whitespace themselves.
The variable identifier is limited to alphanumeric characters and the
underscore character.

To reference a variable in a permissions file, it needs to be dereferenced
using the `%{myvar}` syntax. The variable needs to appear as a single path
component and cannot be mixed with other literal characters. Multiple
variables per path are allowed. The following are valid uses of variables:

----
- %{myvar}/sub/path
- /parent/path/%{myvar}
- /parent/path/%{myvar}/sub/path
- %{var1}/path/%{var2}
----

While the following are invalid:

----
- /prefix/pre%{myvar}suf/suffix
- /%{var}text/path
- /path/text%{var}
----

=== Configuration File Locations

The `permctl` program, when run in `--system` mode, will assemble a set of
configuration entries depending on the profiles configured in
__/etc/sysconfig/security__. The order of files parsed (with increasing
priority) is as follows:

*/usr/share/permissions/permissions*:: contains fixed entries independent of the active profile.
*/usr/share/permissions/permissions.<profile>*:: contains the per-profile configuration of files.
*/usr/share/permissions/packages.d/**:: contains per-package drop-in configuration files, which can also exist in fixed or in different profile variants.
*/etc/permissions.local*:: contains local per-system extra entries or overrides managed by the system administrator.

=== Available Predefined Profiles

The permissions package ships the following predefines profiles:

*easy*:: security settings targeted towards single user workstations, where
  the only user is also the administrator. This profile is tailored towards more
  simplicity (less configuration and authorization requirements) at the possible
  expense of security in some areas.
*secure*:: this is a balanced profile for servers or multi-user workstations
  that contains more secure settings at the expense of additional
  configuration or authorization requirements in some areas.
*paranoid*:: this is a profile that disables all `setuid` and `setgid` bits and
  most capabilities. It is intended for power users that want to add back
  individual `setuid` bits via the __/etc/permissions.local__ file. This
  profile is not intended to be used as-is, as it will likely break the system
  without careful tuning.

EXAMPLES
--------

This is a demonstration of the use of variable expansion:

----
# in variables.conf
lib_dirs = /lib /lib64
sub_dirs = prog_v1 prog_v2

# in a permissions profile
%{lib_dirs}/%{sub_dirs}/libsomething.so root:root 04755
----

This will cause `permctl `to try and apply the given permission to all of the
following paths, if existing:

 /lib/prog_v1/libsomething.so
 /lib64/prog_v1/libsomething.so
 /lib/prog_v2/libsomething.so
 /lib64/prog_v2/libsomething.so

FILES
-----

 /usr/share/permissions/permissions
 /usr/share/permissions/permissions.easy
 /usr/share/permissions/permissions.secure
 /usr/share/permissions/permissions.paranoid
 /usr/share/permissions/packages.d/*
 /usr/share/permissions/permissions.d/* (deprecated)
 /usr/share/permissions/variables.conf
 /etc/permissions.local

SEE ALSO
--------

permctl(8)

AUTHORS
-------

Written by Ludwig Nussel.

REPORTING BUGS
--------------

Report bugs to https://bugzilla.suse.com/ or to https://github.com/openSUSE/permissions/.
