Fork me on GitHub

Audit Events and Records


Teleport logs every SSH event into its audit log. There are two components of the audit log:

  1. Cluster Events: Teleport logs events like successful user logins along with the metadata like remote IP address, time, and the session ID.
  2. Recorded Sessions: Every SSH or Kubernetes shell session is recorded and can be replayed later. The recording is done by the nodes themselves, by default, but can be configured to be done by the proxy.
  3. Optional: BPF Session Recording

Refer to the "Audit Log" chapter in the Teleport Architecture to learn more about how the Audit Log and Session Recording are designed.


Teleport supports multiple storage back-ends for storing the SSH, Application, and Kubernetes events. The section below uses the dir backend as an example. dir backend uses the local filesystem of an auth server using the configurable data_dir directory.

For High Availability configurations, users can refer to our DynamoDB or Firestore chapters for information on how to configure the SSH events and recorded sessions to be stored on network storage. It is even possible to store the audit log in multiple places at the same time - see audit_events_uri setting in the sample configuration file above for how to do that.

Let's examine the Teleport audit log using the dir backend. The event log is stored in data_dir under log directory, usually /var/lib/teleport/log . Each day is represented as a file:

ls -l /var/lib/teleport/log/

total 104

-rw-r----- 1 root root 31638 Jan 22 20:00 2017-01-23.00:00:00.log

-rw-r----- 1 root root 91256 Jan 31 21:00 2017-02-01.00:00:00.log

-rw-r----- 1 root root 15815 Feb 32 22:54 2017-02-03.00:00:00.log

The log files use JSON format. They are human-readable but can also be programmatically parsed. Each line represents an event and has the following format:

    // Event type. See below for the list of all possible event types
    "event": "session.start",
    // uid: A unique ID for the event log. Useful for  deduplication.
    "uid": "59cf8d1b-7b36-4894-8e90-9d9713b6b9ef",
    // Teleport user name
    "user": "ekontsevoy",
    // OS login
    "login": "root",
    // Server namespace. This field is reserved for future use.
    "namespace": "default",
    // Unique server ID.
    "server_id": "f84f7386-5e22-45ff-8f7d-b8079742e63f",
    // Server Labels.
    "server_labels": {
      "datacenter": "us-east-1",
      "label-b": "x"
    // Session ID. Can be used to replay the session.
    "sid": "8d3895b6-e9dd-11e6-94de-40167e68e931",
    // Address of the SSH node
    "addr.local": "10.5.l.15:3022",
    // Address of the connecting client (user)
    "addr.remote": "",
    // Terminal size
    "size": "80:25",
    // Timestamp
    "time": "2017-02-03T06:54:05Z"

The possible event types are:

Event TypeDescription
authAuthentication attempt. Adds the following fields: {"success": "false", "error": "access denied"}
session.startStarted an interactive shell session.
session.endAn interactive shell session has ended.
session.joinA new user has joined the existing interactive shell session.
session.leaveA user has left the session.
session.diskA list of files opened during the session. Requires Enhanced Session Recording.
session.networkA list of network connections made during the session. Requires Enhanced Session Recording.
session.commandA list of commands ran during the session. Requires Enhanced Session Recording.
execRemote command has been executed via SSH, like tsh ssh [email protected] ls /. The following fields will be logged: {"command": "ls /", "exitCode": 0, "exitError": ""}
scpRemote file copy has been executed. The following fields will be logged: {"path": "/path/to/file.txt", "len": 32344, "action": "read" }
resizeTerminal has been resized.
user.loginA user logged into web UI or via tsh. The following fields will be logged: {"user": "[email protected]", "method": "local"} .
app.session.startA user accessed an application
app.session.chunkA record of activity during an app session

Recorded sessions

In addition to logging session.start and session.end events, Teleport also records the entire stream of bytes going to/from standard input and standard the output of an SSH session.

Teleport can store the recorded sessions in an AWS S3 bucket or in a local filesystem (including NFS).

The recorded sessions are stored as raw bytes in the sessions directory under log. Each session is a binary protobuf-encoded stream of data.

You can decode events using tsh play or the Web UI to replay it.

For example, replay a session via CLI:

tsh --proxy=proxy play 4c146ec8-eab6-11e6-b1b3-40167e68e931

Print the session events in json to stdout:

tsh --proxy=proxy play 4c146ec8-eab6-11e6-b1b3-40167e68e931 --format=json
Have a suggestion or can’t find something?