Skip to main content
Version: 19.x (unreleased)

SELinux Module for Teleport SSH Service

Report an IssueView as Markdown
note

This feature is currently under active development. Future releases will extend SELinux policy to support more Teleport features, and integration with Teleport Managed Updates.

The Teleport SSH Service SELinux module allows SELinux to confine the Teleport SSH Service. It ensures that Teleport SSH Service processes can only perform explicitly allowed operations, reducing the attack surface and preventing unauthorized actions even if the Teleport binary were compromised.

Prerequisites​

Before installing the SELinux module, ensure the following requirements are met:

  • A running Teleport cluster. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

  • The tctl and tsh clients.

    Installing tctl and tsh clients

    1. Determine the version of your Teleport cluster. The tctl and tsh clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at /v1/webapi/find and use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service:

      TELEPORT_DOMAIN=teleport.example.com:443
      TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"

    2. Follow the instructions for your platform to install tctl and tsh clients:

      Download the signed macOS .pkg installer for Teleport, which includes the tctl and tsh clients:

      curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg

      In Finder double-click the pkg file to begin installation.

      danger

      Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security.

Service SELinux module is officially supported on these platforms only.

  • Root or sudo access on the host. The install-selinux.sh script must be run as root.
  • SELinux enabled on the host (either permissive or enforcing mode). The module can be installed in either mode, but enforcing mode is recommended for production use. See [SELinux modes] (#selinux-modes) for the difference between the two.
  • The selinux-policy-devel package installed on the host, which provides the toolchain used to compile the module. The Installation section covers this.
  • A Teleport configuration file on the host (/etc/teleport.yaml by default). The install script reads this file to customize the module and label files correctly.
  • A Teleport SSH Service agent configured to point at your cluster and enrolled by following SSH getting started. This agent has three SELinux-specific requirements:
    • Tarball installation only. The install-selinux.sh script and SELinux module ship only in the Linux tarball. Package-manager and container installs are not supported.
    • SSH Service only. The agent must run only the SSH Service. Teleport exits with an error if --enable-selinux is set while other services are enabled or the SSH Service is disabled.
    • Runs as a systemd service. Teleport is expected to run as a systemd service. SELinux enforcement relies on Teleport running under the teleport_ssh_t domain, which typically only occurs when Teleport is started by systemd.

To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials.

For example, run the following command, assigning teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and [email protected] to your Teleport username:

tsh login --proxy=teleport.example.com --user=[email protected]
tctl status
Cluster  teleport.example.com
Version  19.0.0-dev
CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

Supported features​

The Teleport SSH Service SELinux module supports the following Teleport SSH Service features:

  • handling SSH connections
  • PAM support
  • SSH agent forwarding
  • auditd logging
  • enhanced session recording

Supported platforms​

The SELinux policy module for Teleport SSH Service is officially supported on Red Hat Enterprise Linux (RHEL) 8 and 9 only.

Installation​

Before installing the SELinux module ensure that the selinux-policy-devel package is installed:

sudo dnf install selinux-policy-devel

To install the SELinux module, run the install-selinux.sh script included in Linux tarballs as root:

sudo ./install-selinux.sh
if teleport is not in your PATH
sudo ./install-selinux.sh -t /path/to/teleport

This script performs the following:

  1. Extracts the SELinux module from the installed Teleport binary.
  2. Customizes the module based on the Teleport configuration.
  3. Compiles and installs the teleport_ssh SELinux module into the system policy.
  4. Labels any existing Teleport SSH Service binaries and directories.

The script needs to read the configuration file of Teleport SSH Service in order to customize the module and label files and directories correctly. It will read /etc/teleport.yaml by default, but you can specify a different location for the configuration file using the -c flag:

sudo ./install-selinux.sh -c /path/to/teleport.yaml
note

You must re-run install-selinux.sh whenever your Teleport SSH Service agents are updated. This ensures the SELinux module matches the version of the binaries in use.

Future versions of Teleport will make managed updates with teleport-update the primary way to manage the SELinux module.

SELinux modes​

SELinux can operate in three modes:

ModeDescription
EnforcingSELinux policy is enforced. Violations are blocked and logged.
PermissiveSELinux policy is not enforced, but violations are logged (allowed).
DisabledSELinux is turned off entirely; no policy is loaded or logged.

Use getenforce or sestatus to check the current mode. To change the mode, use setenforce or semanage. Teleport SSH Service will work if SELinux is in permissive mode, but this is not recommended for production use. Permissive mode is only recommended for testing and development, as it only logs policy violations and does not enforce them. For production use, SELinux should be set to the enforcing mode.

Enforcing Teleport SSH Service with SELinux​

Once the module is installed, Teleport must be explicitly told to enable SELinux support by adding the --enable-selinux flag when starting:

teleport start --enable-selinux
note

Only the SSH service supports SELinux enforcement, if you try and start Teleport with --enable-selinux passed with other services enabled or the SSH service not enabled, Teleport will exit with an error.

When --enable-selinux is passed, Teleport will exit with an error if:

  • SELinux is not installed on the system.
  • SELinux is disabled.
  • The teleport_ssh module is not installed or is disabled.
  • Teleport is not running under the correct SELinux domain.

Teleport's binary must have the teleport_ssh_exec_t type. The install script will label the Teleport binary with the correct type if it is not already. If you copy or move the binary the label will need to be updated. You can simply re-run the install script to update the label, or you can update the label manually:

sudo semanage fcontext -a -t teleport_ssh_exec_t /path/to/teleport
note

Teleport will probably not run under the correct teleport_ssh_t domain and not be enforced by SELinux unless it is running as a systemd service. For more information on SELinux domains refer to the Red Hat article Getting started with SELinux.

The optional --ensure-selinux-enforcing flag causes Teleport to exit with an error if:

  • SELinux is in permissive mode.
  • The required teleport_ssh module is permissive.

This provides a safety check to guarantee that Teleport SSH Service is always running under the protection of SELinux policy enforcement. It may be necessary to run Teleport without this flag when testing SELinux configuration or diagnosing issues.

Inspecting the SELinux module source​

The module source consists of two files, the type enforcement file and the file contexts file.

The type enforcement file is the heart of the module and contains statements that define what Teleport SSH Service processes are allowed to do.

The file contexts file maps files and directories Teleport SSH Service uses to the appropriate SELinux labels. For more information on SELinux labels refer to the Red Hat article SELinux Contexts - Labeling Files.

The customized module source can be printed using Teleport:

print type enforcement file
teleport selinux-ssh module-source
print file contexts file
teleport selinux-ssh file-contexts

Customizing the SELinux module​

If you need to grant additional permissions beyond the defaults, you can create and install your own SELinux policy module targeting the teleport_ssh_t domain (used by the official module).

warning

The official Teleport SSH Service module is named teleport_ssh. The install script will overwrite any module of that name. Be sure to name your custom policy module something else (e.g., my_teleport_ssh_extras).

  1. Write a new .te file defining the extra rules for teleport_ssh_t.

  2. Compile and package your module:

    make -f /usr/share/selinux/devel/Makefile my_teleport_ssh_extras.pp

  3. Install it:

    semodule -i my_teleport_ssh_extras.pp

For detailed guidance on writing SELinux modules, refer to the Red Hat article How to write SELinux policy modules

Troubleshooting SELinux and Teleport SSH Service​

When Teleport SSH Service is blocked by SELinux, use the following tools to diagnose and resolve policy issues:

  1. sealert (from the setroubleshoot-server package):

    sudo sealert -a /var/log/audit/audit.log

    This generates a human-readable report of SELinux denials and recommendations for policy adjustments.

  2. audit2why (from the policycoreutils-python-utils package):

    ausearch -m AVC -c teleport | audit2why

    This explains why a denial occurred and suggests which policy rules are missing.

  3. audit2allow (to generate a custom policy module):

    ausearch -m AVC -c teleport | audit2allow -M my_teleport_fix

    Use this approach to create a small, targeted module to grant the necessary permissions.

If Teleport fails to start with --enable-selinux --ensure-selinux-enforcing, check:

  • That SELinux is in enforcing mode (getenforce).

  • That the teleport_ssh module is listed:

    semodule -l | grep teleport_ssh

  • The audit log (/var/log/audit/audit.log) for detailed AVC messages.