Contents
When BRLTTY starts executing as the super user (root), i.e. when its initial effective user identifier is 0, it has unrestricted access to all of the privileged operations that the host has to offer. While we always endeavour to ensure that BRLTTY isn't abusing this freedom, we also don't feel that it's worth risking the possibility that our code might be hacked. To reduce this possibility, therefore, BRLTTY first establishes a safer execution environment within which It only has access to those privileged host operations that it actually needs. This is a best security practice known as least privilege.
BRLTTY takes a number of steps to establish a safer execution environment:
When BRLTTY starts executing as the super user (root), one of the first things it does is switch to executing as an unprivileged user. The user is selected as follows:
This method is only allowed when BRLTTY was started as the super user (root). It may be specified via the user privilege parameter. If it isn't explicitly specified, or if there's a problem:
then the default user is selected.
The default unprivileged user is the one specified at build time via the lx:user= parameter of the --with-privilege-parameters option of BRLTTY's configure command. If there's a problem:
then BRLTTY continues to execute as the super user (root).
This is the last resort! In this case:
After having successfully switched to executing as an unprivileged user, the following is done:
Ensure that all of the user identifiers (real, effective, saved, filesystem) are set to the selected user.
Ensure that all of the group identifiers (real, effective, saved, filesystem) are set to the primary group of the selected user.
If any of the following environment variables is set then reset it to the name of the selected user:
Ensure that the following environment variables aren't set:
Change the XDG runtime directory (set the XDG_RUNTIME_DIR environment variable) to that of the selected user.
Extend the supplementary group list with the needed group memberships.
If the selected user's home directory is defined then switch to it by:
The updatable directory (usually /var/lib/brltty/) is used instead if:
A state directory is one which a program needs to be able to write data to. BRLTTY's state directories are:
This directory is where BRLTTY creates BrlAPI's local (UNIX domain) server sockets. It needs to be world writable, and, as such, should also have its sticky bit set. So:
chmod ugo=rwx,o+t path
This directory is where BRLTTY saves user data. This includes:
The actual locations of these directories can be specified in a number of ways. From highest to lowest precedence, they are:
| Directory | Option | Config Directive | Environment Variable | Default Location |
| Sockets | /var/lib/BrlAPI/ | |||
| Updatable | -U | updatable-directory | BRLTTY_UPDATABLE_DIRECTORY | /var/lib/brltty/ |
| Writable | -W | writable-directory | BRLTTY_WRITABLE_DIRECTORY | /var/run/brltty/ |
After having successfully switched to executing as the unprivileged user, BRLTTY attempts to gain full access to its state directories. The most common case where this is necessary is to automate the transition from an older release of BRLTTY from the days when it had to execute as the super user (root). Another (much rarer) case would be when transitioning from one unprivileged user to another.
The main reason that BRLTTY does this job is that it's extremely difficult for a blind user to figure out what's wrong before his/her braille device is up and running. Put another way, it can be near impossible for a braille user to figure out why BRLTTY is having problems while BRLTTY is having problems.
The following actions are taken for each of the state directories:
Gaining full access to a state directory is only attempted if the last component of its path is its expected name:
| Directory | Expected Name |
| Sockets | BrlAPI |
| Updatable | brltty |
| Writable | brltty |
This is a protective measure, given that command line options, etc can be used to change the location of a state directory to a non-BRLTTY-specific location. It prevents BRLTTY from Attempting to gain full access to another program's data, or, even worse, to a public directory. If it's really necessary to use such a directory then it's far better to let a human being take care of it.
BRLTTY, as of release 6.2, can be started by an unprivileged user (not root). Use cases for this include system administrators or users who'd like BRLTTY to be startable by any user, by users who belong to a specific group, etc.
In order for an unprivileged user to successfully start BRLTTY, the environment needs to be prepared as follows:
Assign the required capabilities to BRLTTY's executable.
Give the user that's to be able to start BRLTTY the needed group memberships. This isn't necessary, i.e. BRLTTY will join them by itself, if the cap_setgid (temporary) capability has also been assigned to its executable. In this case, BRLTTY will extend the supplementary group list that it inherited from the user with any needed groups that are missing.
Install the needed kernel modules. This isn't necessary, i.e. BRLTTY will install them by itself, if the cap_sys_module (temporary) capability has also been assigned to its executable.
Ensure that BRLTTY's state directories have been created, have the correct ownership, and have the correct permissions. Each of these prerequisites isn't necessary, i.e. BRLTTY will take care of it by itself, if the associated (temporary) capability has also been assigned to its executable. They are:
| Prerequisite | Temporary Capability |
| creation | cap_dac_override |
| ownership | cap_chown |
| permissions | cap_fowner |
Privilege parameters control how BRLTTY establishes its safer execution environment. From highest to lowest precedence, they can be specified via:
Each of these takes a comma-separated list of parameters in the form:
platform:name=value
The platform: part is optional - if it's omitted then the parameter setting applies on all platforms. It's best, therefore, to always include it. The platform code for Linux is lx.
The command line option can be specified any number of times. Likewise, the configuration directive can be specified any number of times. Additional specifications extend, rather than replace, the parameter list. The same parameter specified later at the same level of precedence, or at a higher level of precedence, overrides its earlier setting.
The following privilege parameters are supported for Linux:
This parameter sets the mode of the system call filter. The supported modes are:
If the --stay-privileged (or -Z) command line option is specified then BRLTTY will retain all of the privileges that it had when it was invoked. It won't:
A safe command search path is established by setting the PATH environment variable to a system-configured set of safe directories. You can find out which ones they are by running this command:
getconf PATH
If, for some reason, the system-configured path isn't available then /usr/sbin:/sbin:/usr/bin:/bin is used.
The path can be explicitly set via the path privilege parameter.
A safe default shell for external software to assume is established by setting the SHELL environment variable to /bin/sh. On many systems, this is the Bourne Shell. On others, it's a symbolic link to some other shell. To find out what it is on your system, run this command:
ls -l /bin/sh
Note that scripts usually internally specify which shell is to be used.
The default shell can be explicitly set via the shell privilege parameter.
BRLTTY isolates some of the kernel namespaces that are associated with its process. The namespaces that it currently isolates are:
The kernel provides a system call filter, known as seccomp (secure computing), that verifies that only an approved set of system calls is being used. The default is that BRLTTY doesn't actually use it because, by nature, using a system call filter makes a program somewhat fragile. Reasons for this include:
Even though the default is that BRLTTY doesn't use the filter, access to it is still provided for those users or administrators who prefer to avail themselves of the additional protection that it offers. Use the scfmode privilege parameter to specify how BRLTTY uses it.
Installing the filter also includes configuring BRLTTY's process so that no external command that it subsequently invokes will be able to acquire any additional privileges. See the PR_SET_NO_NEW_PRIVS section of the man page for prctl for details. The quick summary is that, when executing any host command:
The current list of approved system calls is in the syscalls_linux.h header, which is in the Programs/ subdirectory of BRLTTY's source tree. BRLTTY must be rebuilt in order for changes to the list to become effective. Please let us know if you discover any system calls that are missing and should be added.
We recommend that the unprivileged user be named brltty, and that it be a system user.
The user's primary group should be user-specific. Ideally, it should have the same name as the user.
The user's supplementary group list should include all of the groups that own the various system resources that BRLTTY needs access to in order for it to do its job properly. See Needed Group Memberships for details.
The user should have a home directory. It should be on a local file system so that BRLTTY can start properly when there are network problems.
There's normally no need for anyone to log into the user. This can be enforced by setting its login shell to /sbin/nologin.
The user information (gecos) field should be set to a user-friendly description of why it exists. We recommend something like:
Braille Device Daemon
The host command to create a user is:
useradd option ... name
It must be run as the super user (root).
It accepts a lot of options. For all of the details, run this command:
man useradd
Unless there are special and/or unusual considerations, its most important options are:
| Option | Action |
| --system | create a system user |
| --user-group | create a user-specific primary group |
| --gid group | set the primary group |
| --groups group,... | set the supplementary group list |
| --no-create-home | don't create the home directory |
| --create-home | create the home directory |
| --home path | the absolute path for the home directory |
| --comment text | set the user information (gecos) field |
| --shell path | set the login shell |
The top-level directory of BRLTTY's source tree contains a script named brltty-mkuser that simplifies the job of Creating and making changes to the unprivileged user. For details, run this command:
brltty-mkuser -h
The following options require special mention:
Note that this script is safe to accidentally invoke because both creating a new user (-N) and making changes to an existing user (-E) must be explicitly allowed. These options aren't mutually exclusive - both may be specified.
The user's supplementary group list is used to establish the needed group memberships. Each of the following options removes a group from the full list, and, therefore, also removes that group's associated functionality from BRLTTY. If a group's name is shown in italics then it's only our recommendation as its actual name isn't defined by any standard or convention.
| Option | Removes Group | Lost Functionality |
| -a | audio | playing sound via the ALSA framework |
| -b | brlapi | reading BrlAPI's authorization key file (usually /etc/brlapi.key) |
| -c | tty | access to the virtual consoles |
| -k | input | keyboard monitoring |
| -p | pulse-access | playing sound via the Pulse Audio server |
| -s | dialout | access to serial devices |
| -u | usually root | access to USB devices |
The following options are for configuring the basic (password file) fields of the user:
| Option | Operand | Sets / Changes |
| -d | path | the home directory |
| -g | group | the primary group |
| -i | text | the user information (gecos) field |
| -l | path | the login shell |
If any of these options isn't specified, then:
When making changes to an existing user, it has no effect. Its associated field isn't changed.
When creating a new user, the defaults are:
| Option | Default When creating a New User |
| -d | the updatable directory (/var/lib/brltty/) |
| -g | a new group with the same name as the user |
| -i | Braille Device Daemon |
| -l | /sbin/nologin |
The following options are primarily for developers:
| Option | Description |
| -S | use sudo to execute the commands as root |
| -T | test mode - show the commands that would be executed |
Don't do this if you only want BRLTTY to execute successfully `when started as the super user`_.
First, here's a summary of all of the capabilities that BRLTTY needs when started by an unprivileged user.
| Capability | Reason |
| cap_chown | claiming ownership of the state directories |
| cap_dac_override | creating missing state directories |
| cap_fowner | adding group permissions to the state directories |
| cap_mknod | creating needed but missing device files |
| cap_setgid | switching to the primary group of the unprivileged user and establishing the needed group memberships |
| cap_sys_admin | injecting input characters |
| cap_sys_module | installing the needed kernel modules |
| cap_sys_tty_config | using the built-in PC speaker |
The host command to assign all of the capabilities, i.e. both the required capabilities and the temporary capabilities, to BRLTTY's executable so that it'll be fully functional when started by an unprivileged user, without requiring any additional administrator configuration, is:
setcap cap_setgid,cap_chown,cap_fowner,cap_dac_override,cap_sys_module,cap_sys_admin,cap_sys_tty_config,cap_mknod+p /path/to/brltty
It must be run as the super user (root).
The top-level directory of BRLTTY's source tree contains a script named brltty-setcaps that simplifies the job of assigning capabilities to the executable. Its default is to assign all of them. For details, run this command:
brltty-setcaps -h
It requires one positional argument - the path to BRLTTY's executable. It also accepts a number of options (which must precede that path). In particular, each of the following options removes a capability from the full set, and, therefore, also removes the functionality that that capability grants from BRLTTY.
| Option | Removes Capability | Lost Functionality |
| -c | cap_dac_override | creating missing state directories |
| -d | cap_mknod | creating needed but missing device files |
| -g | cap_setgid | switching to the primary group of the unprivileged user and establishing the needed group memberships |
| -i | cap_sys_admin | injecting input characters |
| -m | cap_sys_module | installing the needed kernel modules |
| -o | cap_chown | claiming ownership of the state directories |
| -p | cap_fowner | adding group permissions to the state directories |
| -s | cap_sys_tty_config | using the built-in PC speaker |
The following options are primarily for developers:
| Option | Description |
| -C | don't set the capabilities |
| -G | set group root execution |
| -S | use sudo to execute the commands as root |
| -T | test mode - show the commands that would be executed |
| -U | set user root execution |
The privileged host operations that BRLTTY needs to be able to perform in order to be fully functional are:
BRLTTY relies on functionality provided by these kernel modules:
BRLTTY relies on file system and server (daemon) access granted via membership in the following owning user groups.
For serial I/O via these /dev/ devices:
For:
Note that this is the root group - not the root user.
For:
BRLTTY uses the privileged kernel operations that are granted via these capabilities throughout its execution. They are retained within its permitted and effective sets, but not within its inheritable and ambient sets. In other words, they're for BRLTTY itself and aren't passed along to any host command that it runs.
BRLTTY only uses the privileged kernel operations that are granted via these capabilities when started by an unprivileged user. They allow it to configure itself, thus not relying so heavily on explicit administrator configuration, and are relinquished right after this has been done.
The SYSFS virtual file system (usually mounted at /sys/) contains some files that BRLTTY occasionally needs to write to. While they can be read by anyone, they can only be written to by the super user (root). BRLTTY needs to be able to write to these files for (at least) the following reasons:
A possible approach might be to add Udev rules.
The uinput device (/dev/uinput or /dev/input/uinput) is usually only readable and writable by the super user (root). Without any group and/or others access, it's impossible for BRLTTY to access it after having switched to the unprivileged user.
This situation could be easily resolved by granting group read and write permissions to the device. This shouldn't be problematic because its owned by the root group. Even better, of course, would be to give the device its own group (e.g. named uinput).
BRLTTY currently gets around this problem by including the following Udev rule to add an ACL (access control list) entry to the device:
KERNEL=="uinput", ACTION=="add", TEST=="/usr/bin/setfacl", RUN+="/usr/bin/setfacl -m u:brltty:rw /dev/$name"
If BRLTTY finds that it isn't permitted to open the device (perhaps because the Udev rule isn't present) then its fallback method Is to create a private copy of the device file within its writable directory (usually /var/run/brltty/). This requires the cap_mknod capability.
Other alternatives include:
Being able to create virtual devices is a very important ability for BRLTTY to have. It's used for:
The default location of the writable directory (usually /var/run/brltty/) on a modern system is usually on a memory-resident file system that has been mounted with the nodev option. This prevents a device file within that file system from being opened, even if its permissions (mode, acl, etc) allow it. The good news is that this isn't usually a problem on a well-configured system because it's extremely rare for a needed device file to be missing. If it is, then the best solution is to change the writable directory to a better location (see State Directories for how to do that).