# 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. 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/ver/17.x/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:

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

     **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/ver/17.x/installation.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
     ```

* A running Teleport Agent instance. See the [getting started guide](https://goteleport.com/docs/ver/17.x/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 (optional).
* 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\@example.com to your Teleport username:
  ```
  $ tsh login --proxy=teleport.example.com --user=email@example.com
  $ tctl status
  Cluster  teleport.example.com
  Version  17.7.20
  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.

## Step 1/4. 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/4. 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.

---

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. You can verify that by calling `cat /proc/$(pidof teleport)/loginuid`. The value should be set to 4294967295.

---

## Step 3/4. Enable the PAM integration (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 system generates 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/ver/17.x/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.

## Step 4/4. 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 by using the `-ua` switch. You can check the UID of a user by using the `id` command:

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

```

Then you can 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=bob

```

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

```