Skip to main content

Set up the Teleport Event Handler Plugin

Report an Issue

In this guide, we will set up the Teleport Event Handler plugin with credentials to authenticate to the Teleport Auth Service and access the events API.

How it works​

The Event Handler plugin is a binary that runs independently of your Teleport cluster. It authenticates to your Teleport cluster using mutual TLS to begin forwarding events.

Prerequisites​

  • 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.

Recommended: Configure Machine & Workload Identity to provide short-lived Teleport credentials to the plugin. Before following this guide, follow a Machine & Workload Identity deployment guide to run the tbot binary on your infrastructure.

  • A server, virtual machine, Kubernetes cluster, or Docker environment to run the Teleport Event Handler plugin.

  • 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  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.

  • On your workstation, create a folder called event-handler, to hold configuration files and plugin state:

    mkdir -p event-handler
    cd event-handler

Step 1/2. Install the Event Handler plugin​

The Event Handler plugin is provided in amd64 and arm64 binaries for downloading. Replace ARCH with your required version.

curl -L -O https://cdn.teleport.dev/teleport-event-handler-v19.0.0-dev-linux-ARCH-bin.tar.gz
tar -zxvf teleport-event-handler-v19.0.0-dev-linux-ARCH-bin.tar.gz
sudo ./teleport-event-handler/install

Step 2/2. Set up the Event Handler plugin​

In this section, you will set up the Teleport Event Handler plugin and generate credentials that the plugin will use for authentication.

Generate a starter config file​

Generate a configuration file with placeholder values for the Teleport Event Handler plugin. Later in this guide, we will edit the configuration file for your environment.

Run the configure command to generate a sample configuration. Assign teleport.example.com:443 to the DNS name and port of your Teleport Enterprise Cloud account. Assign localhost to the DNS name of your log forwarder.

teleport-event-handler configure . teleport.example.com:443 --dns-names=localhost

The plugin generates several setup files:

File(s)Purpose
ca.crt and ca.keySelf-signed CA certificate and private key for Fluentd
server.crt and server.keyFluentd server certificate and key
client.crt and client.keyFluentd client certificate and key, all signed by the generated CA
teleport-event-handler-role.yamluser and role resource definitions for Teleport's event handler
teleport-event-handler.tomlExample event handler configuration
fluent.confFluentd plugin configuration
Running the Event Handler separately from the log forwarder

This guide assumes that you are running the Event Handler on the same host or Kubernetes pod as your log forwarder. If you are not, you will need to instruct the Event Handler to generate mTLS certificates for subjects besides localhost. To do this, use the --dns-names flag of the teleport-event-handler configure command.

For example, if your log forwarder is addressable at fluentd.example.com, you would run the following configure command:

teleport-event-handler configure --dns-names=fluentd.example.com

The --dns-names flag accepts a comma-separated list of DNS names. It will append subject alternative names (SANs) to the server certificate (the one you will provide to your log forwarder) for each DNS name in the list.

If you have an existing Fluentd setup with TLS, issue a client certificate and key from the same certificate authority for the Teleport Event Handler to use.

Define the Event Handler role​

The teleport-event-handler configure command generated a file called teleport-event-handler-role.yaml. This file defines a teleport-event-handler role and a user with read-only access to the event API:

kind: role
metadata:
  name: teleport-event-handler
spec:
  allow:
    rules:
      - resources: ['event', 'session']
        verbs: ['list','read']
version: v5
---
kind: user
metadata:
  name: teleport-event-handler
spec:
  roles: ['teleport-event-handler']
version: v2

Move this file to your workstation (or recreate it by pasting the snippet above) and use tctl on your workstation to create the role and the user:

tctl create -f teleport-event-handler-role.yaml
user "teleport-event-handler" has been created
role 'teleport-event-handler' has been created
tip

You can also create and edit roles using the Web UI. Go to Access -> Roles and click Create New Role or pick an existing role to edit.

Enable issuing of credentials for the Event Handler role​

With the role created, you now need to allow the Machine & Workload Identity bot to produce credentials for this role.

This can be done with tctl, replacing my-bot with the name of your bot:

tctl bots update my-bot --add-roles teleport-event-handler

Export an identity file for the Event Handler user​

Give the plugin access to a Teleport identity file. We recommend using Machine ID for this in order to produce short-lived identity files that are less dangerous if exfiltrated, though in demo deployments, you can generate longer-lived identity files with tctl:

Configure tbot with an output that will produce the credentials needed by the plugin. As the plugin will be accessing the Teleport API, the correct output type to use is identity.

For this guide, the directory destination will be used. This will write these credentials to a specified directory on disk. Ensure that this directory can be written to by the Linux user that tbot runs as, and that it can be read by the Linux user that the plugin will run as.

Modify your tbot configuration to add an identity output.

If running tbot on a Linux server, use the directory output to write identity files to the /opt/machine-id directory:

services:
- type: identity
  destination:
    type: directory
    # For this guide, /opt/machine-id is used as the destination directory.
    # You may wish to customize this. Multiple outputs cannot share the same
    # destination.
    path: /opt/machine-id

If running tbot on Kubernetes, write the identity file to Kubernetes secret instead:

services:
  - type: identity
    destination:
      type: kubernetes_secret
      name: teleport-event-handler-identity

If operating tbot as a background service, restart it. If running tbot in one-shot mode, execute it now.

You should now see an identity file under /opt/machine-id or a Kubernetes secret named teleport-event-handler-identity. This contains the private key and signed certificates needed by the plugin to authenticate with the Teleport Auth Service.

Next steps​

You have now configured the Teleport Event Handler plugin with credentials to access the Teleport events API.

If you are new to exporting audit events with Teleport, read Forwarding Events with Fluentd to learn the basics of how our Event Handler plugin works. While this guide focuses on Fluentd, the Event Handler plugin can export audit events to any endpoint that ingests JSON messages via HTTP.

Next, read our guides to setting up the Event Handler plugin to export audit events to your solution of choice: