SELinux Customization

Workbench | Preview

WarningPreview feature

This feature is in preview. Preview features are unsupported and may face breaking changes in a future release. Any issues found in the feature will be addressed during the regular release schedule; they will not result in immediate patches or hotfixes.

We encourage customers to try these features and we welcome any feedback via Posit Support, but we recommend that the feature not be used in production until it is in general availability (i.e., officially released as a full feature). To provide feedback, please email your Posit Customer Success representative or and specify that you are trialing this feature.

When SELinux is in enforcing mode, applications can only access files and directories with explicit permission from the installed policy. The Posit Workbench policy module manages permissions for the standard paths that a default Workbench installation typically uses. If you use other locations, such as a shared team directory or a mounted data volume, then you must create an additional policy module to grant permission to those paths.

Important

This procedure assumes that the Workbench SELinux policy module (workbench) is already installed and loaded. The workbench_can_* macros are defined by that module and are unavailable until it is installed. See SELinux Configuration for instructions on installing the policy module.

Prerequisites

Before you begin, install the SELinux development tools for your distribution:

Terminal
sudo yum install selinux-policy-devel
Terminal
sudo apt install -y selinux-policy-dev

Additionally, ensure that the Workbench policy module is already installed and loaded. See SELinux Configuration for more information about the Workbench policy module.

Step 1: Create a new policy module project

Choose a name for your policy module. The examples on this page use my_shared_data.

Create a directory with that name and move into it:

Terminal
mkdir my_shared_data
cd my_shared_data

Step 2: Declare a new file label

SELinux policy rules are defined using type enforcement (.te) files. A full explanation of how to write a .te file is beyond the scope of this document. See Red Hat’s Quick start to write a custom SELinux policy article for an overview.

For most use cases, you can use a simple .te file that defines a new type and uses the interface macros provided by the Workbench policy module:

my_shared_data.te
policy_module(my_shared_data, 1.0.0)

########################################
#
# Declarations
#

# Declare a new type and register it as a general-purpose file type.
# Omit these lines if you are granting Workbench permission to access an existing file type.
type my_shared_data_t;
files_type(my_shared_data_t)

########################################
#
# my_shared_data policy rules
#

# Give Workbench full permission over files, directories, and sockets labeled with my_shared_data_t.
workbench_can_manage_files(my_shared_data_t)
workbench_can_execute_files(my_shared_data_t)
workbench_can_manage_sockets(my_shared_data_t)

In general, choose the most restrictive permissions that satisfy your needs. You can create multiple types within a single policy module to define more granular permissions.

Interface macros

When the Workbench policy module is installed, it provides a set of interface macros to simplify the creation of .te files.

workbench_can_read_files($1)

Grants Workbench permission to read and memory-map files and directories and follow symlinks that are labeled with the specified type.

Example Usage
workbench_can_read_files(example_file_t)

workbench_can_manage_files($1)

Grants Workbench permission to read, write, create, rename, and delete files, directories, and symlinks that are labeled with the specified type.

Example Usage
workbench_can_manage_files(example_file_t)

workbench_can_execute_files($1)

In addition to the permissions granted by workbench_can_read_files above, grants Workbench permission to execute files labeled with the specified type.

Example Usage
workbench_can_execute_files(example_file_t)

workbench_can_manage_sockets($1)

Grants Workbench permission to create, delete, and use Unix sockets and FIFOs (named pipes) labeled with the specified type.

Example Usage
workbench_can_manage_sockets(example_file_t)

Step 3: Select the files to label

File context (.fc) files determine the label applied to newly-created files and directories.

Each line in an .fc file contains a regular expression that identifies paths, an optional flag specifying the type of object (file, directory, etc.), and a security context to be applied to matching paths. By default, newly-created files and directories inherit the security context of the parent directory.

To target a directory and all existing files within it, use the regular expression (/.*)?.

A simple .fc file that assigns the my_shared_data_t label to /mnt/shared_data/ and all of its children would contain:

my_shared_data.fc
/mnt/shared_data(/.*)?    gen_context(system_u:object_r:my_shared_data_t,s0)

Step 4: Compile and install the policy module

Compile the source into a loadable policy package (.pp) using the Makefile provided by the SELinux development tools:

Terminal
make -f /usr/share/selinux/devel/Makefile NAME=devel my_shared_data.pp

If the compilation is successful, this command creates my_shared_data.pp in the current working directory. A syntax error about one of the workbench_can_ macros might indicate that the Workbench policy module is not installed.

After compiling the module, install it:

Terminal
sudo semodule -i my_shared_data.pp

Step 5: Relabel files

Installing the module registers the file-context mapping, but it does not relabel files that already exist.

To apply the new label to the target directory:

Terminal
sudo restorecon -R -v /mnt/shared_data

The -Z flag to ls includes SELinux labels alongside the listed files. You can use this to verify that files have the expected labels:

Terminal
ls -Zl /mnt/shared_data

Updating or removing the module

If you make changes to the files in your policy module, then repeat the compile and install step to apply the modified policy. Be sure to relabel the files as well if you made changes to the .fc file.

To remove your custom policy, unload the module and restore the default label for the affected paths:

Terminal
sudo semodule -r my_shared_data
sudo restorecon -R -v /opt/shared-projects
Back to top