{"token_count": 2958}

# Configure SSH with the Linux Auditing System

You can configure Teleport's SSH Service to integrate with the Linux Auditing System (auditd).

## Prerequisites

- A running Teleport cluster accessible at a hostname with a valid TLS certificate. If you want to get started with Teleport, [sign up](https://goteleport.com/signup) for a free trial or [set up a demo environment](https://goteleport.com/docs/get-started/deploy-community.md).

- 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:

     **Mac/Linux**

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

     **Windows - Powershell**

     ```
     $ $TELEPORT_DOMAIN = "teleport.example.com:443"
     $ $TELEPORT_VERSION = (Invoke-RestMethod -Uri "https://${TELEPORT_DOMAIN}/v1/webapi/find").server_version
     ```

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

     **Mac**

     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.

     ---

     **Windows - Powershell**

     ```
     $ curl.exe -O https://cdn.teleport.dev/teleport-v$TELEPORT_VERSION-windows-amd64-bin.zip
     Unzip the archive and move the `tctl` and `tsh` clients to your %PATH%
     NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP.
     Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\<username>) instead.
     ```

     **Linux**

     All of the Teleport binaries in Linux installations include the `tctl` and `tsh` clients. For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) see our [installation page](https://goteleport.com/docs/installation/single-machine.md).

     ```
     $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ cd teleport
     $ sudo ./install
     Teleport binaries have been copied to /usr/local/bin
     ```

  Connecting with TLS routing disabled

  This guide's commands assume your Teleport cluster uses TLS routing (`proxy_listener_mode: multiplex`), where the `tctl` and `tsh` clients reach every Teleport service through the Proxy Service's web address on port `443`. If you're not sure whether this applies to your cluster, check with whoever manages it.

  If your cluster uses separate listener ports instead, adjust ports as follows:

  - **`tsh` commands** (e.g., `tsh login --proxy=...`): continue using the Proxy Service web address on port `3080` (or `443` if behind a load balancer). Do not change these to port `3025`.

  - **Direct `tctl` or Auth Service API commands**: use port `3025` for the Auth Service gRPC listener:

    ```
    $ tctl status --auth-server=teleport.example.com:3025
    ```

* A running Teleport SSH Service instance. See the [getting started guide](https://goteleport.com/docs/enroll-resources/server-access/getting-started.md) for how to add an agent to your Teleport cluster. On the agent, `teleport` must be running as a systemd service with root permissions.

* Linux kernel 2.6.6+ compiled with `CONFIG_AUDIT`. Most Linux distributions have this option enabled by default.

* `auditctl` to check auditd status. You must install the `auditd` package to follow the command examples in this guide.

* Check that you can connect to your Teleport cluster and verify that you can run `tctl` and `tsh` commands using your current credentials.

  1. Assign teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and email\@example.com to your Teleport username.

  2. Authenticate to your Teleport cluster. This depends on whether your shell is interactive or not.

     **In an interactive shell:** Run the following command. By default, this triggers a multi-factor authentication prompt:

     ```
     $ tsh login --proxy=teleport.example.com --user=email@example.com
     $ tctl status
     Cluster  teleport.example.com
     Version  18.10.0
     CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
     ```

     **On non-interactive environments:** If you are running `tsh` and `tctl` as an AI agent, in a CI/CD environment, or similar, make sure the `TELEPORT_IDENTITY_FILE` environment variable is assigned to a valid file path with credentials for your cluster. `tsh` and `tctl` read the file path from the environment variable and do not require a separate authentication step. If there is no identity file available, we recommend that you [set up Machine ID](https://goteleport.com/docs/machine-workload-identity/getting-started.md) to provision one automatically.

     When executing `tctl` commands with an identity file, you must pass the `--auth-server` flag to provide the Teleport Auth Service address, which is not included in the identity file. If you provide the Proxy Service address, `tctl` connects to the Proxy Service, which forwards traffic to and from the Teleport Auth Service. Update 443 to `3025` if you are contacting the Auth Service directly with `tctl`:

     ```
     $ tctl status --auth-server=teleport.example.com:443
     ```

     For `tsh` commands that read an identity file, you must pass the `--proxy` flag, which points `tsh` to the address of the Teleport Proxy Service:

     ```
     $ tsh status --proxy=teleport.example.com
     ```

     Ensure client commands can access your identity file. Replace path/to/identity/file with the path to your identity file:

     ```
     $ export TELEPORT_IDENTITY_FILE="${TELEPORT_IDENTITY_FILE:-path/to/identity/file}"
     ```

     Add the `--auth-server` or `--proxy` flags to all subsequent `tctl` and `tsh` commands.

  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.

## Step 1/3. Check system configuration

Teleport automatically sends auditd events when it discovers that auditd is enabled in the system. You can verify that by calling `auditctl -s` as root.

Here is an example output from that command:

```
$ sudo auditctl -s
enabled 1
failure 1
pid 879
rate_limit 0
backlog_limit 8192
lost 0
backlog 0
backlog_wait_time 60000
backlog_wait_time_actual 0
loginuid_immutable 0 unlocked
```

The first line `enabled 1` indicates that auditd is enabled, and Teleport will send events.

All events are generated on a Teleport Node. `invalid user` events are also generated on the Proxy Service when a Teleport user fails to authenticate.

## Step 2/3. Configure and start Teleport

It's important to run Teleport as a system service (systemd service, for example) with root permissions. Otherwise, Teleport won't send any events to auditd due to lack of permissions.

1. \[Optional] Auditd can generate additional events when PAM (Pluggable Authentication Modules) is enabled.

   To enable the PAM integration in Teleport, add the following `pam` section to the configuration file on your Teleport Node (`/etc/teleport.yaml` by default):

   ```
   ssh_service:
     # Enabled SSH Service
     enabled: true
     # Enable PAM integration
     pam:
       # "no" by default
       enabled: true
       # use /etc/pam.d/sshd configuration (the default)
       service_name: "sshd"

   ```

   PAM-generated events depend on your `sshd` configuration when the integration is enabled. Most systems generate events like `USER_ACCT` or `USER_START`. Additionally, TTY input can be logged by enabling the `pam_tty_audit.so` module.

   For more details please refer to [PAM](https://goteleport.com/docs/enroll-resources/server-access/guides/ssh-pam.md#set-up-pam-on-a-linux-machine-running-teleport) or your operating system documentation.

   When PAM integration is enabled, auditd events should closely match events generated by OpenSSH.

2. Start your Teleport instance. The instructions depend on how you installed your Teleport instance and whether your system supports systemd:

   **Package Manager**

   Configure your Teleport instance to start automatically when the host boots up by creating a systemd service for it. On the host where you will run your Teleport instance, enable and start Teleport:

   ```
   $ sudo systemctl enable teleport
   $ sudo systemctl start teleport
   ```

   You can check the status of your Teleport instance with `systemctl status teleport` and view its logs with `journalctl -fu teleport`.

   **TAR Archive**

   Configure your Teleport instance to start automatically when the host boots up by creating a systemd service for it. On the host where you will run your Teleport instance, create a systemd service configuration for Teleport, enable the Teleport service, and start Teleport:

   ```
   $ sudo teleport install systemd -o /etc/systemd/system/teleport.service
   $ sudo systemctl enable teleport
   $ sudo systemctl start teleport
   ```

   You can check the status of your Teleport instance with `systemctl status teleport` and view its logs with `journalctl -fu teleport`.

   **No systemd**

   On the host where you will run your Teleport instance, start Teleport:

   ```
   $ sudo teleport start --config=/etc/teleport.yaml
   ```

   Teleport runs in the foreground and outputs logs for the services it is running.

   ---

   WARNING

   Make sure that the Teleport process has its login UID unset. Otherwise, a session ID won't be set correctly in the emitted events, since all sessions inherit the login UID of the Teleport process. You can verify this by running the following command:

   ```
   $ cat /proc/$(pidof teleport)/loginuid
   ```

   The value should be set to `4294967295`. If you start the Teleport process as a systemd service, its login UID will be unset.

   ---

## Step 3/3. Trace SSH sessions with auditd

There are a few ways to trace SSH sessions in Teleport. To interact with auditd events, we will use `ausearch`. If your system is missing that tool, consult your distribution documentation to check how to install it.

### Search by a system user

You can search events when logging in as a system user.

1. List available servers to access:

   ```
   $ tsh ls
   ```

2. Pick a server from the list and SSH into it. Replace myuser with your login name and myhost with your server name.

   ```
   $ tsh ssh myuser@myhost
   ```

3. On the server, check the UID of a user by using the `id` command:

   ```
   $ id myuser
   uid=1000(bob) gid=1000(bob) groups=1000(bob)
   ```

4. On the server, use `uid` to search auditd logs:

   ```
   $ ausearch -ua 1000 -m USER_LOGIN
   ```

### Search by Teleport user

Events sent to auditd by Teleport are augmented by the `teleportUser` field, which contains the name of the Teleport user. `ausearch` doesn't let you search by custom fields, but you can use `grep` for that:

```
$ ausearch -m USER_LOGIN | grep teleportUser=myuser
```

### Search by session ID

If you want to find all events generated by a specific session, first, you need to find the session ID. You can do that by using:

```
$ ausearch  -m USER_LOGIN -x teleport --just-one
```

Then search events only related to that one session:

```
$ ausearch --session 42
```