mirror of
https://github.com/gravitational/teleport
synced 2024-10-19 16:53:57 +00:00
Docs: Add Datadog guide. (#21950)
* tighten existing audit title in nav * Move plugin install and config to partials This move not only consolidates these instructions to a single source of truth, but also takes the divergent updates from these instructions across multiple docs. * init datadog guide * Update docs/pages/includes/configure-event-handler.mdx Co-authored-by: Michael Wilson <mike@mdwn.dev> * respond to review feedback * add context for Logstash * add context for Splunk * update page titles See https://github.com/gravitational/teleport/pull/21950/files\#r1110311232 for details * Apply suggestions from code review Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com> * move link to next steps * Apply suggestions from code review * adjust prereqs * Apply suggestions from code review * Update docs/pages/management/export-audit-events/datadog.mdx Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com> * appease pointless linter rule --------- Co-authored-by: Michael Wilson <mike@mdwn.dev> Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
This commit is contained in:
Alex Fornuto
GitHub
parent
9e1f53d33a
commit
39f15f322d
|
|
@ -589,17 +589,22 @@
|
|||
"slug": "/management/export-audit-events/",
|
||||
"entries": [
|
||||
{
|
||||
"title": "Exporting Audit Events to Fluentd",
|
||||
"title": "Export Audit Events to Fluentd",
|
||||
"slug": "/management/export-audit-events/fluentd/",
|
||||
"forScopes": ["enterprise", "cloud"]
|
||||
},
|
||||
{
|
||||
"title": "Monitoring Audit Events with the Elastic Stack",
|
||||
"title": "Export Audit Events to Datadog",
|
||||
"slug": "/management/export-audit-events/datadog/",
|
||||
"forScopes": ["enterprise", "cloud"]
|
||||
},
|
||||
{
|
||||
"title": "Export Audit Events to the Elastic Stack",
|
||||
"slug": "/management/export-audit-events/elastic-stack/",
|
||||
"forScopes": ["enterprise", "cloud"]
|
||||
},
|
||||
{
|
||||
"title": "Monitoring Audit Events with Splunk",
|
||||
"title": "Export Audit Events to Splunk",
|
||||
"slug": "/management/export-audit-events/splunk/",
|
||||
"forScopes": ["enterprise", "cloud"]
|
||||
}
|
||||
|
|
|
|||
BIN
docs/img/management/datadog-flowchart.png
Normal file
BIN
docs/img/management/datadog-flowchart.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 35 KiB |
BIN
docs/img/management/datadog-generate-api.png
Normal file
BIN
docs/img/management/datadog-generate-api.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 146 KiB |
BIN
docs/img/management/datadog-logs.png
Normal file
BIN
docs/img/management/datadog-logs.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 282 KiB |
84
docs/pages/includes/configure-event-handler.mdx
Normal file
84
docs/pages/includes/configure-event-handler.mdx
Normal file
|
|
@ -0,0 +1,84 @@
|
|||
<Tabs>
|
||||
<TabItem scope={["cloud"]} label="Teleport Enterprise Cloud">
|
||||
|
||||
Run the `configure` command to generate a sample configuration. Replace
|
||||
`mytenant.teleport.sh` with the DNS name of your Teleport Enterprise Cloud tenant:
|
||||
|
||||
```code
|
||||
$ ./teleport-event-handler configure . mytenant.teleport.sh:443
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem scope={["oss", "enterprise"]} label="Self-Hosted">
|
||||
|
||||
Run the `configure` command to generate a sample configuration. Replace
|
||||
`teleport.example.com:443` with the DNS name and HTTPS port of Teleport's Proxy
|
||||
Service:
|
||||
|
||||
```code
|
||||
$ ./teleport-event-handler configure . teleport.example.com:443
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem scope={["oss", "enterprise", "cloud"]} label="Helm Chart">
|
||||
|
||||
Run the `configure` command to generate a sample configuration. Assign
|
||||
`TELEPORT_CLUSTER_ADDRESS` to the DNS name and port of your Teleport Auth
|
||||
Service or Proxy Service:
|
||||
|
||||
```code
|
||||
$ TELEPORT_CLUSTER_ADDRESS=mytenant.teleport.sh:443
|
||||
$ docker run -v `pwd`:/opt/teleport-plugin -w /opt/teleport-plugin public.ecr.aws/gravitational/teleport-plugin-event-handler:(=teleport.plugin.version=) configure . ${TELEPORT_CLUSTER_ADDRESS?}
|
||||
```
|
||||
|
||||
In order to export audit events, you'll need to have the root certificate and the
|
||||
client credentials available as a secret. Use the following command to create
|
||||
that secret in Kubernetes:
|
||||
|
||||
```code
|
||||
$ kubectl create secret generic teleport-event-handler-client-tls --from-file=ca.crt=ca.crt,client.crt=client.crt,client.key=client.key
|
||||
```
|
||||
|
||||
This will pack the content of `ca.crt`, `client.crt`, and `client.key` into the
|
||||
secret so the Helm chart can mount them to their appropriate path.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
You'll see the following output:
|
||||
|
||||
```txt
|
||||
Teleport event handler 0.0.1 07617b0ad0829db043fe779faf1669defdc8d84e
|
||||
|
||||
[1] mTLS Fluentd certificates generated and saved to ca.crt, ca.key, server.crt, server.key, client.crt, client.key
|
||||
[2] Generated sample teleport-event-handler role and user file teleport-event-handler-role.yaml
|
||||
[3] Generated sample fluentd configuration file fluent.conf
|
||||
[4] Generated plugin configuration file teleport-event-handler.toml
|
||||
|
||||
Follow-along with our getting started guide:
|
||||
|
||||
https://goteleport.com/setup/guides/fluentd
|
||||
```
|
||||
|
||||
The plugin generates several setup files:
|
||||
|
||||
```code
|
||||
$ ls -l
|
||||
# -rw------- 1 bob bob 1038 Jul 1 11:14 ca.crt
|
||||
# -rw------- 1 bob bob 1679 Jul 1 11:14 ca.key
|
||||
# -rw------- 1 bob bob 1042 Jul 1 11:14 client.crt
|
||||
# -rw------- 1 bob bob 1679 Jul 1 11:14 client.key
|
||||
# -rw------- 1 bob bob 541 Jul 1 11:14 fluent.conf
|
||||
# -rw------- 1 bob bob 1078 Jul 1 11:14 server.crt
|
||||
# -rw------- 1 bob bob 1766 Jul 1 11:14 server.key
|
||||
# -rw------- 1 bob bob 260 Jul 1 11:14 teleport-event-handler-role.yaml
|
||||
# -rw------- 1 bob bob 343 Jul 1 11:14 teleport-event-handler.toml
|
||||
```
|
||||
|
||||
| File(s) | Purpose |
|
||||
|------------------------------------|---------------------------------------------------------------------|
|
||||
| `ca.crt` and `ca.key` | Self-signed CA certificate and private key for Fluentd |
|
||||
| `server.crt` and `server.key` | Fluentd server certificate and key |
|
||||
| `client.crt` and `client.key` | Fluentd client certificate and key, all signed by the generated CA |
|
||||
| `teleport-event-handler-role.yaml` | `user` and `role` resource definitions for Teleport's event handler |
|
||||
| `fluent.conf` | Fluentd plugin configuration |
|
||||
85
docs/pages/includes/install-event-handler.mdx
Normal file
85
docs/pages/includes/install-event-handler.mdx
Normal file
|
|
@ -0,0 +1,85 @@
|
|||
<Tabs>
|
||||
<TabItem label="Linux">
|
||||
|
||||
```code
|
||||
$ curl -L -O https://get.gravitational.com/teleport-event-handler-v(=teleport.plugin.version=)-linux-amd64-bin.tar.gz
|
||||
$ tar -zxvf teleport-event-handler-v(=teleport.plugin.version=)-linux-amd64-bin.tar.gz
|
||||
```
|
||||
|
||||
We currently only build the Event Handler plugin for amd64 machines. For ARM
|
||||
architecture, you can build from source.
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem label="macOS">
|
||||
|
||||
```code
|
||||
$ curl -L -O https://get.gravitational.com/teleport-event-handler-v(=teleport.plugin.version=)-darwin-amd64-bin.tar.gz
|
||||
$ tar -zxvf teleport-event-handler-v(=teleport.plugin.version=)-darwin-amd64-bin.tar.gz
|
||||
```
|
||||
|
||||
We currently only build the event handler plugin for amd64 machines. If your
|
||||
macOS machine uses Apple silicon, you will need to [install
|
||||
Rosetta](https://support.apple.com/en-us/HT211861) before you can run the
|
||||
event handler plugin. You can also build from source.
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem label="Docker">
|
||||
Ensure that you have Docker installed and running.
|
||||
|
||||
```code
|
||||
$ docker pull public.ecr.aws/gravitational/teleport-plugin-event-handler:(=teleport.plugin.version=)
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem label="Helm">
|
||||
|
||||
To allow Helm to install charts that are hosted in the Teleport Helm repository, use `helm repo add`:
|
||||
|
||||
```code
|
||||
$ helm repo add teleport (=teleport.helm_repo_url=)
|
||||
```
|
||||
|
||||
To update the cache of charts from the remote repository, run `helm repo update`:
|
||||
|
||||
```code
|
||||
$ helm repo update
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem label="Build via Docker">
|
||||
Ensure that you have Docker installed and running.
|
||||
|
||||
Run the following commands to build the plugin:
|
||||
|
||||
```code
|
||||
$ git clone https://github.com/gravitational/teleport-plugins.git --depth 1
|
||||
$ cd teleport-plugins/event-handler/build.assets
|
||||
$ make build
|
||||
```
|
||||
|
||||
You can find the compiled binary within your clone of the `teleport-plugins`
|
||||
repo, with the file path, `event-handler/build/teleport-event-handler`.
|
||||
|
||||
</TabItem>
|
||||
<TabItem label="Build via Go">
|
||||
|
||||
You will need Go >= (=teleport.golang=) installed.
|
||||
|
||||
Run the following commands on your Universal Forwarder host:
|
||||
|
||||
```code
|
||||
$ git clone https://github.com/gravitational/teleport-plugins.git --depth 1
|
||||
$ cd teleport-plugins/event-handler
|
||||
$ go build
|
||||
```
|
||||
|
||||
The resulting executable will have the name `event-handler`. To follow the
|
||||
rest of this guide, rename this file to `teleport-event-handler` and move it
|
||||
to `/usr/local/bin`.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
409
docs/pages/management/export-audit-events/datadog.mdx
Normal file
409
docs/pages/management/export-audit-events/datadog.mdx
Normal file
|
|
@ -0,0 +1,409 @@
|
|||
---
|
||||
title: Export Teleport Audit Events with Datadog
|
||||
description: How to configure the Teleport Event Handler plugin and Fluentd to send audit logs to Datadog
|
||||
---
|
||||
|
||||
Datadog is a SAAS monitoring and security platform. In this guide, we'll explain
|
||||
how to forward Teleport audit events to Datadog using Fluentd.
|
||||
|
||||
The Teleport Event Handler is designed to communicate with Fluentd using mTLS
|
||||
to establish a secure channel. In this setup, the Event Handler sends events to Fluentd, which forwards them to Datadog using an API key to authenticate.
|
||||
|
||||
{/*
|
||||
The Graph below is made with this mermaidjs logic:
|
||||
graph LR
|
||||
style e fill: #a379ff,color: #ffffff
|
||||
style f fill: #a379ff,color: #ffffff
|
||||
style c fill: #a379ff,color: #ffffff
|
||||
style g fill: #a379ff,color: #ffffff
|
||||
style i fill: #a379ff,color: #ffffff
|
||||
style e fill: #844cff,color: #ffffff
|
||||
style monitor fill:#a8afb1,stroke: #000000
|
||||
|
||||
a(User)
|
||||
a-->e
|
||||
|
||||
subgraph local [Local Network]
|
||||
style local fill:#C0C0C0,stroke: #000000
|
||||
direction LR
|
||||
subgraph teleport [ ]
|
||||
direction TB
|
||||
style teleport fill:none,stroke:none
|
||||
e(Teleport Proxy)
|
||||
e<-->f(Teleport Auth)
|
||||
e<-->g(Teleport Service)
|
||||
e<-->i(Teleport Service)
|
||||
g<-->j([Infrastructure])
|
||||
i<-->k([Infrastructure])
|
||||
end
|
||||
|
||||
subgraph monitor [Monitoring]
|
||||
c(teleport-event-handler)
|
||||
d(fluentd)
|
||||
end
|
||||
c-->d
|
||||
end
|
||||
e-->c
|
||||
d-->h(Datadog)
|
||||
*/}
|
||||
|
||||
|
||||
|
||||
## Prerequisites
|
||||
|
||||
(!docs/pages/includes/commercial-prereqs-tabs.mdx!)
|
||||
|
||||
- A [Datadog](https://www.datadoghq.com/) account.
|
||||
- A server, virtual machine, Kubernetes cluster, or Docker environment to run the
|
||||
Event Handler. The instructions below assume a local Docker container for testing.
|
||||
- Fluentd version v(=fluentd.version=) or greater. The Teleport Event Handler
|
||||
will create a new `fluent.conf` file you can integrate into an existing Fluentd
|
||||
system, or use with a fresh setup.
|
||||
|
||||
The instructions below demonstrate a local test of the Event Handler plugin on your
|
||||
workstation. You will need to adjust paths, ports, and domains for other environments.
|
||||
|
||||
(!docs/pages/includes/tctl.mdx!)
|
||||
|
||||
## Step 1/6. Install the Event Handler plugin
|
||||
|
||||
The Teleport event handler runs alongside the Fluentd forwarder, receives events
|
||||
from Teleport's events API, and forwards them to Fluentd.
|
||||
|
||||
(!docs/pages/includes/install-event-handler.mdx!)
|
||||
|
||||
## Step 2/6. Configure the plugin
|
||||
|
||||
(!docs/pages/includes/configure-event-handler.mdx!)
|
||||
|
||||
## Step 3/6. Create a user and role for reading audit events
|
||||
|
||||
The `configure` command generates a file called `teleport-event-handler-role.yaml`
|
||||
that defines a `teleport-event-handler` role and a user with read-only access
|
||||
to the `event` API:
|
||||
|
||||
```yaml
|
||||
kind: role
|
||||
metadata:
|
||||
name: teleport-event-handler
|
||||
spec:
|
||||
allow:
|
||||
rules:
|
||||
- resources: ['event']
|
||||
verbs: ['list','read']
|
||||
version: v5
|
||||
---
|
||||
kind: user
|
||||
metadata:
|
||||
name: teleport-event-handler
|
||||
spec:
|
||||
roles: ['teleport-event-handler']
|
||||
version: v2
|
||||
```
|
||||
|
||||
Use `tctl` to create the role and the user:
|
||||
|
||||
```code
|
||||
$ tctl create -f teleport-event-handler-role.yaml
|
||||
# user "teleport-event-handler" has been created
|
||||
# role 'teleport-event-handler' has been created
|
||||
```
|
||||
|
||||
## Step 4/6. Create teleport-event-handler credentials
|
||||
|
||||
### Enable impersonation of the Event Handler user
|
||||
|
||||
In order for the Teleport Event Handler plugin to forward events from your Teleport
|
||||
cluster, it needs a signed identity file from the cluster's certificate authority.
|
||||
The `teleport-event-handler` user cannot request this itself, and requires another
|
||||
user to **impersonate** this account in order to request a certificate.
|
||||
|
||||
Create a role that enables your user to impersonate the Fluentd user. First,
|
||||
paste the following YAML document into a file called
|
||||
`teleport-event-handler-impersonator.yaml`:
|
||||
|
||||
```yaml
|
||||
kind: role
|
||||
version: v5
|
||||
metadata:
|
||||
name: teleport-event-handler-impersonator
|
||||
spec:
|
||||
# SSH options used for user sessions
|
||||
options:
|
||||
# max_session_ttl defines the TTL (time to live) of SSH certificates
|
||||
# issued to the users with this role.
|
||||
max_session_ttl: 10h
|
||||
|
||||
# allow section declares a list of resource/verb combinations that are
|
||||
# allowed for the users of this role. by default nothing is allowed.
|
||||
allow:
|
||||
impersonate:
|
||||
users: ["teleport-event-handler"]
|
||||
roles: ["teleport-event-handler"]
|
||||
```
|
||||
|
||||
Next, create the role:
|
||||
|
||||
```code
|
||||
$ tctl create -f teleport-event-handler-impersonator.yaml
|
||||
```
|
||||
|
||||
(!docs/pages/includes/add-role-to-user.mdx role="teleport-event-handler-impersonator"!)
|
||||
|
||||
### Export an identity file for the Event Handler plugin user
|
||||
|
||||
The Teleport Event Handler plugin uses the `teleport-event-handler` role and user to
|
||||
read events. We export an identity file for the user with the `tctl auth sign`
|
||||
command.
|
||||
|
||||
<Tabs>
|
||||
<TabItem label="Executable" scope={["oss","enterprise"]}>
|
||||
```code
|
||||
$ tctl auth sign --user=teleport-event-handler --out=identity
|
||||
```
|
||||
|
||||
This command creates one PEM-encoded file, `identity`. The identity file
|
||||
includes both TLS and SSH credentials. The Event Handler plugin uses the SSH
|
||||
credentials to connect to the Proxy Service, which establishes a reverse tunnel
|
||||
connection to the Auth Service. The plugin uses this reverse tunnel, along with
|
||||
your TLS credentials, to connect to the Auth Service's gRPC endpoint.
|
||||
|
||||
</TabItem>
|
||||
<TabItem label="Helm Chart" scope={["cloud"]}>
|
||||
|
||||
If you are planning to use the Helm Chart, you'll need to generate the keys
|
||||
with the `file` format, then create a secret in Kubernetes.
|
||||
|
||||
Create the identity using the following command:
|
||||
|
||||
```code
|
||||
$ tctl auth sign --format=file --user=teleport-event-handler --out=identity
|
||||
```
|
||||
|
||||
Then create the Kubernetes secret:
|
||||
|
||||
```code
|
||||
$ kubectl create secret generic teleport-event-handler-identity --from-file=auth_id=identity
|
||||
```
|
||||
|
||||
These commands should result in a PEM-encoded file, `identity`, and a secret
|
||||
in Kubernetes with the name `teleport-event-handler-identity`.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Step 5/6. Install Fluentd output plugin for Datadog
|
||||
|
||||
In order for Fluentd to communicate with Datadog, it requires the [Fluentd output
|
||||
plugin for Datadog](https://github.com/DataDog/fluent-plugin-datadog). Install
|
||||
the plugin on your Fluentd host using either `gem` or the `td-agent`, if installed:
|
||||
|
||||
```code
|
||||
# Using Gem
|
||||
$ gem install fluent-plugin-datadog
|
||||
|
||||
# Using td-agent
|
||||
$ /usr/sbin/td-agent-gem install fluent-plugin-datadog
|
||||
```
|
||||
|
||||
<Admonition type="tip" title="Testing Locally?">
|
||||
|
||||
If you're running Fluentd in a local Docker container for testing, you can adjust
|
||||
the entrypoint to an interactive shell as the root user, so you can install the
|
||||
plugin before starting Fluentd:
|
||||
|
||||
```code
|
||||
$ docker run -u $(id -u root):$(id -g root) -p 8888:8888 -v $(pwd):/keys -v \
|
||||
$(pwd)/fluent.conf:/fluentd/etc/fluent.conf --entrypoint=/bin/sh -i --tty fluent/fluentd:edge
|
||||
# From the container shell:
|
||||
$ gem install fluent-plugin-datadog
|
||||
$ fluentd -c /fluentd/etc/fluent.conf
|
||||
```
|
||||
|
||||
</Admonition>
|
||||
|
||||
### Configure Fluentd for Datadog
|
||||
|
||||
From the Datadog web UI, generate an API key for Fluentd. From **Organization Settings** -> Access -> **API Keys**, click on **+ New Key**:
|
||||
|
||||
|
||||
|
||||
Copy the API key, and use it to add a new `<match>` block to `fluent.conf`:
|
||||
|
||||
```ini
|
||||
<match test.log>
|
||||
|
||||
@type datadog
|
||||
@id awesome_agent
|
||||
api_key (=presets.tokens.first=)
|
||||
|
||||
host http-intake.logs.us5.datadoghq.com
|
||||
|
||||
# Optional parameters
|
||||
dd_source teleport
|
||||
|
||||
</match>
|
||||
```
|
||||
|
||||
- Add your API key to the `api_key` field.
|
||||
- Adjust the `host` value to match your Datadog site. See their [Log Collection
|
||||
and Integrations](https://docs.datadoghq.com/logs/log_collection/?tab=host) guide
|
||||
to determine the correct value.
|
||||
- `dd_source` is an optional field you can use to filter these logs in the
|
||||
Datadog UI.
|
||||
- Adjust `ca_path`, `cert_path` and `private_key_path` to point to the credential
|
||||
files generated earlier. If you're testing locally, the Docker command above
|
||||
already mounted the current working directory to `keys/` in the container.
|
||||
|
||||
Restart Fluentd after saving the changes to `fluent.conf`.
|
||||
|
||||
## Step 6/6. Start the event handler plugin
|
||||
|
||||
Earlier, we generated a file called `teleport-event-handler.toml` to configure
|
||||
the Fluentd event handler. This file includes setting similar to the following:
|
||||
|
||||
<Tabs>
|
||||
<TabItem scope={["cloud"]} label="Teleport Cloud">
|
||||
|
||||
```toml
|
||||
storage = "./storage"
|
||||
timeout = "10s"
|
||||
batch = 20
|
||||
namespace = "default"
|
||||
|
||||
[forward.fluentd]
|
||||
ca = "/home/sasha/scripts/event-handler/ca.crt"
|
||||
cert = "/home/sasha/scripts/event-handler/client.crt"
|
||||
key = "/home/sasha/scripts/event-handler/client.key"
|
||||
url = "https://localhost:8888/test.log"
|
||||
|
||||
[teleport]
|
||||
addr = "mytenant.teleport.sh:443"
|
||||
identity = "identity"
|
||||
```
|
||||
|
||||
To start the event handler, run the following command:
|
||||
|
||||
```code
|
||||
$ ./teleport-event-handler start --config teleport-event-handler.toml
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem scope={["oss", "enterprise"]} label="Self-Hosted">
|
||||
|
||||
```toml
|
||||
storage = "./storage"
|
||||
timeout = "10s"
|
||||
batch = 20
|
||||
namespace = "default"
|
||||
|
||||
[forward.fluentd]
|
||||
ca = "/home/sasha/scripts/event-handler/ca.crt"
|
||||
cert = "/home/sasha/scripts/event-handler/client.crt"
|
||||
key = "/home/sasha/scripts/event-handler/client.key"
|
||||
url = "https://localhost:8888/test.log"
|
||||
|
||||
[teleport]
|
||||
addr = "teleport.example.com:443"
|
||||
identity = "identity"
|
||||
```
|
||||
|
||||
To start the event handler, run the following command:
|
||||
|
||||
```code
|
||||
$ ./teleport-event-handler start --config teleport-event-handler.toml
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem scope={["oss", "enterprise"]} label="Helm Chart">
|
||||
|
||||
Use the following template to create `teleport-plugin-event-handler-values.yaml`:
|
||||
|
||||
```yaml
|
||||
eventHandler:
|
||||
storagePath: "./storage"
|
||||
timeout: "10s"
|
||||
batch: 20
|
||||
namespace: "default"
|
||||
|
||||
teleport:
|
||||
address: "example.teleport.com:443"
|
||||
identitySecretName: teleport-event-handler-identity
|
||||
|
||||
fluentd:
|
||||
url: "https://fluentd.fluentd.svc.cluster.local/events.log"
|
||||
sessionUrl: "https://fluentd.fluentd.svc.cluster.local/session.log"
|
||||
certificate:
|
||||
secretName: "teleport-event-handler-client-tls"
|
||||
caPath: "ca.crt"
|
||||
certPath: "client.crt"
|
||||
keyPath: "client.key"
|
||||
|
||||
persistentVolumeClaim:
|
||||
enabled: true
|
||||
```
|
||||
|
||||
To start the event handler in Kubernetes, run the following command:
|
||||
|
||||
```code
|
||||
$ helm install teleport-plugin-event-handler teleport/teleport-plugin-event-handler \
|
||||
--values teleport-plugin-event-handler-values.yaml \
|
||||
--version (=teleport.plugin.version=)
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
<Admonition type="note">
|
||||
|
||||
This example will start exporting from `May 5th 2021`:
|
||||
|
||||
```code
|
||||
$ ./teleport-event-handler start --config teleport-event-handler.toml --start-time "2022-02-02T00:00:00Z"
|
||||
```
|
||||
|
||||
The start time can be set only once, on the first run of the tool.
|
||||
|
||||
If you want to change the time frame later, remove the plugin state directory
|
||||
that you specified in the `storage` field of the handler's configuration file.
|
||||
|
||||
</Admonition>
|
||||
|
||||
Once the handler starts, you will see notifications in Fluentd about scanned and forwarded events:
|
||||
|
||||
```txt
|
||||
INFO[0046] Event sent id=0b5f2a3e-faa5-4d77-ab6e-362bca0994fc ts="2021-06-08 11:00:56.034 +0000 UTC" type=user.login
|
||||
...
|
||||
```
|
||||
|
||||
The Logs view in Datadog should now report your Teleport cluster events:
|
||||
|
||||
|
||||
|
||||
## Troubleshooting connection issues
|
||||
|
||||
If the Teleport Event Handler is displaying error logs while connecting to your
|
||||
Teleport Cluster, ensure that:
|
||||
|
||||
- The certificate the Teleport Event Handler is using to connect to your
|
||||
Teleport cluster is not past its expiration date. This is the value of the
|
||||
`--ttl` flag in the `tctl auth sign` command, which is 12 hours by default.
|
||||
- Ensure that in your Teleport Event Handler configuration file
|
||||
(`teleport-event-handler.toml`), you have provided the correct host *and* port
|
||||
for the Teleport Proxy Service or Auth Service.
|
||||
|
||||
## Next steps
|
||||
|
||||
- Read more about
|
||||
[impersonation](https://goteleport.com/docs/access-controls/guides/impersonation/)
|
||||
here.
|
||||
- While this guide uses the `tctl auth sign` command to issue credentials for the
|
||||
Teleport Event Handler, production clusters should use Machine ID for safer,
|
||||
more reliable renewals. Read [our guide](../../machine-id/getting-started.mdx)
|
||||
to getting started with Machine ID.
|
||||
- To see all of the options you can set in the values file for the
|
||||
`teleport-plugin-event-handler` Helm chart, consult our [reference
|
||||
guide](../../reference/helm-reference/teleport-plugin-event-handler.mdx).
|
||||
- Review the Fluentd output plugin for Datadog [README
|
||||
file](https://github.com/DataDog/fluent-plugin-datadog/blob/master/README.md)
|
||||
to learn how to customize the log format entering Datadog.
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
title: "Monitor Teleport Audit Events with the Elastic Stack"
|
||||
title: "Export Teleport Audit Events with to Elastic Stack"
|
||||
description: "How to configure Teleport's Event Handler plugin to send audit events to the Elastic Stack"
|
||||
---
|
||||
|
||||
|
|
@ -43,63 +43,7 @@ will use for authentication.
|
|||
Follow the instructions for your environment to install the Event Handler
|
||||
plugin on your Logstash host:
|
||||
|
||||
<Tabs dropdownCaption="Method" dropdownSelected="Executable">
|
||||
<TabItem options="Executable" label="Latest Release">
|
||||
|
||||
On the host where you are running Logstash, execute the following commands:
|
||||
|
||||
```code
|
||||
$ curl -L -O https://get.gravitational.com/teleport-event-handler-v(=teleport.plugin.version=)-linux-amd64-bin.tar.gz
|
||||
$ tar -zxvf teleport-event-handler-v(=teleport.plugin.version=)-linux-amd64-bin.tar.gz
|
||||
```
|
||||
|
||||
Move the `teleport-event-handler` binary into your `PATH`.
|
||||
</TabItem>
|
||||
|
||||
<TabItem options="Docker" label="Latest Release ">
|
||||
|
||||
On the host where you are running Logstash, execute the following command:
|
||||
|
||||
```code
|
||||
$ docker pull public.ecr.aws/gravitational/teleport-plugin-event-handler:(=teleport.plugin.version=)
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem options="Docker" label="From Source">
|
||||
You must have Docker Desktop installed on your Logstash host.
|
||||
|
||||
Log in to the host and execute the following commands to build the plugin:
|
||||
|
||||
```code
|
||||
$ git clone https://github.com/gravitational/teleport-plugins.git --depth 1
|
||||
$ cd teleport-plugins/event-handler/build.assets
|
||||
$ make build
|
||||
```
|
||||
|
||||
You can find the compiled binary within your clone of the `teleport-plugins`
|
||||
repo, with the file path, `event-handler/build/teleport-event-handler`. Move
|
||||
this into your `PATH`.
|
||||
|
||||
</TabItem>
|
||||
<TabItem options="Executable" label="From Source ">
|
||||
|
||||
You will need Go >= (=teleport.golang=) installed.
|
||||
|
||||
Run the following commands on your Logstash host:
|
||||
|
||||
```code
|
||||
$ git clone https://github.com/gravitational/teleport-plugins.git --depth 1
|
||||
$ cd teleport-plugins/event-handler
|
||||
$ go build
|
||||
```
|
||||
|
||||
The resulting executable will have the name `event-handler`. To follow the
|
||||
rest of this guide, rename this file to `teleport-event-handler` and move it
|
||||
into your `PATH`.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
(!docs/pages/includes/install-event-handler.mdx!)
|
||||
|
||||
### Generate a starter config file
|
||||
|
||||
|
|
@ -107,29 +51,9 @@ 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.
|
||||
|
||||
On the host where you are running Logstash and the Event Handler plugin, execute
|
||||
the following command to generate a sample configuration that we will edit
|
||||
later. Replace `mytenant.teleport.sh` with the DNS name of your Teleport Proxy
|
||||
Service or Teleport Cloud tenant:
|
||||
|
||||
```code
|
||||
$ teleport-event-handler configure . mytenant.teleport.sh
|
||||
```
|
||||
|
||||
The `teleport-event-handler configure` command generates several files that you
|
||||
will refer to when generating credentials for the plugin and configuring a
|
||||
Logstash pipeline:
|
||||
|
||||
|File(s)|Purpose|
|
||||
|---|---|
|
||||
| `ca.crt` | Self-signed CA certificate that the Event Handler plugin and Logstash will use to validate one another's TLS certificates.|
|
||||
| `server.crt` and `server.key`| TLS certificate and key for the Logstash server.|
|
||||
| `client.crt` and `client.key`| TLS certificate and key for the Event Handler plugin.|
|
||||
| `teleport-event-handler-role.yaml`| `user` and `role` resource definitions for the Event Handler plugin.|
|
||||
| `fluent.conf`| Fluentd configuration file. We will use parts of this to define a Logstash pipeline.|
|
||||
| `teleport-event-handler.toml` | Starter configuration file for the Event Handler plugin.|
|
||||
| `ca.key` | Not used in this setup. |
|
||||
(!docs/pages/includes/configure-event-handler.mdx!)
|
||||
|
||||
We'll re-purpose the files generated for Fluentd in our Logstash configuration.
|
||||
|
||||
### Define RBAC resources
|
||||
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
title: Forwarding Events with Fluentd
|
||||
title: Export Events with Fluentd
|
||||
description: Forwarding events with Fluentd and Teleport event handler
|
||||
videoBanner: HAqxs4rBv2c
|
||||
---
|
||||
|
|
@ -60,134 +60,14 @@ to integrate with your infrastructure.
|
|||
The Teleport event handler runs alongside the Fluentd forwarder, receives events
|
||||
from Teleport's events API, and forwards them to Fluentd.
|
||||
|
||||
<Tabs>
|
||||
<TabItem label="Linux">
|
||||
```code
|
||||
$ curl -L -O https://get.gravitational.com/teleport-event-handler-v(=teleport.plugin.version=)-linux-amd64-bin.tar.gz
|
||||
$ tar -zxvf teleport-event-handler-v(=teleport.plugin.version=)-linux-amd64-bin.tar.gz
|
||||
```
|
||||
</TabItem>
|
||||
|
||||
<TabItem label="macOS">
|
||||
|
||||
```code
|
||||
$ curl -L -O https://get.gravitational.com/teleport-event-handler-v(=teleport.plugin.version=)-darwin-amd64-bin.tar.gz
|
||||
$ tar -zxvf teleport-event-handler-v(=teleport.plugin.version=)-darwin-amd64-bin.tar.gz
|
||||
```
|
||||
|
||||
We currently only build the event handler plugin for amd64 machines. If your
|
||||
macOS machine uses Apple silicon, you will need to [install
|
||||
Rosetta](https://support.apple.com/en-us/HT211861) before you can run the
|
||||
event handler plugin. You can also build from source.
|
||||
</TabItem>
|
||||
|
||||
<TabItem label="Docker">
|
||||
```code
|
||||
$ docker pull public.ecr.aws/gravitational/teleport-plugin-event-handler:(=teleport.plugin.version=)
|
||||
```
|
||||
</TabItem>
|
||||
|
||||
<TabItem label="Helm">
|
||||
(!docs/pages/kubernetes-access/helm/includes/helm-repo-add.mdx!)
|
||||
</TabItem>
|
||||
<TabItem label="From Source">
|
||||
Ensure that you have Docker installed and running.
|
||||
|
||||
Run the following commands to build the plugin:
|
||||
|
||||
```code
|
||||
$ git clone https://github.com/gravitational/teleport-plugins.git --depth 1
|
||||
$ cd teleport-plugins/event-handler/build.assets
|
||||
$ make build
|
||||
```
|
||||
|
||||
You can find the compiled binary within your clone of the `teleport-plugins`
|
||||
repo, with the file path, `event-handler/build/teleport-event-handler`.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
(!docs/pages/includes/install-event-handler.mdx!)
|
||||
|
||||
## Step 2/6. Configure the plugin
|
||||
|
||||
<Tabs>
|
||||
<TabItem scope={["cloud"]} label="Teleport Cloud">
|
||||
(!docs/pages/includes/configure-event-handler.mdx!)
|
||||
|
||||
Run the `configure` command to generate a sample configuration. Replace
|
||||
`mytenant.teleport.sh` with the DNS name of your Teleport Cloud tenant:
|
||||
|
||||
```code
|
||||
$ ./teleport-event-handler configure . mytenant.teleport.sh
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem scope={["oss", "enterprise"]} label="Self-Hosted">
|
||||
|
||||
Run the `configure` command to generate a sample configuration. Replace
|
||||
`teleport.example.com:443` with the DNS name and HTTPS port of Teleport's Proxy
|
||||
Service:
|
||||
|
||||
```code
|
||||
$ ./teleport-event-handler configure . teleport.example.com:443
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem scope={["oss", "enterprise", "cloud"]} label="Helm Chart">
|
||||
|
||||
Run the `configure` command to generate a sample configuration. Assign `TELEPORT_CLUSTER_ADDRESS` to the DNS name and port of your Teleport Auth Service or Proxy Service:
|
||||
|
||||
```code
|
||||
$ TELEPORT_CLUSTER_ADDRESS=mytenant.teleport.sh:443
|
||||
$ docker run -v `pwd`:/opt/teleport-plugin -w /opt/teleport-plugin public.ecr.aws/gravitational/teleport-plugin-event-handler:(=teleport.plugin.version=) configure . ${TELEPORT_CLUSTER_ADDRESS?}
|
||||
```
|
||||
|
||||
In order to connect to Fluentd, you'll need to have the root certificate and the client credentials available as a secret. Use the following command to create that secret in Kubernetes:
|
||||
|
||||
```code
|
||||
$ kubectl create secret generic teleport-event-handler-client-tls --from-file=ca.crt=ca.crt,client.crt=client.crt,client.key=client.key
|
||||
```
|
||||
|
||||
This will pack the content of `ca.crt`, `client.crt`, and `client.key` into the secret, so the Helm Chart can mount them to their appropriate path.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
You'll see the following output:
|
||||
|
||||
```txt
|
||||
Teleport event handler 0.0.1 07617b0ad0829db043fe779faf1669defdc8d84e
|
||||
|
||||
[1] mTLS Fluentd certificates generated and saved to ca.crt, ca.key, server.crt, server.key, client.crt, client.key
|
||||
[2] Generated sample teleport-event-handler role and user file teleport-event-handler-role.yaml
|
||||
[3] Generated sample fluentd configuration file fluent.conf
|
||||
[4] Generated plugin configuration file teleport-event-handler.toml
|
||||
|
||||
Follow-along with our getting started guide:
|
||||
|
||||
https://goteleport.com/setup/guides/fluentd
|
||||
```
|
||||
|
||||
The plugin generates several setup files:
|
||||
|
||||
```code
|
||||
$ ls -l
|
||||
# -rw------- 1 bob bob 1038 Jul 1 11:14 ca.crt
|
||||
# -rw------- 1 bob bob 1679 Jul 1 11:14 ca.key
|
||||
# -rw------- 1 bob bob 1042 Jul 1 11:14 client.crt
|
||||
# -rw------- 1 bob bob 1679 Jul 1 11:14 client.key
|
||||
# -rw------- 1 bob bob 541 Jul 1 11:14 fluent.conf
|
||||
# -rw------- 1 bob bob 1078 Jul 1 11:14 server.crt
|
||||
# -rw------- 1 bob bob 1766 Jul 1 11:14 server.key
|
||||
# -rw------- 1 bob bob 260 Jul 1 11:14 teleport-event-handler-role.yaml
|
||||
# -rw------- 1 bob bob 343 Jul 1 11:14 teleport-event-handler.toml
|
||||
```
|
||||
|
||||
| File(s) | Purpose |
|
||||
|------------------------------------|---------------------------------------------------------------------|
|
||||
| `ca.crt` and `ca.key` | Self-signed CA certificate and private key for Fluentd |
|
||||
| `server.crt` and `server.key` | Fluentd server certificate and key |
|
||||
| `client.crt` and `client.key` | Fluentd client certificate and key, all signed by the generated CA |
|
||||
| `teleport-event-handler-role.yaml` | `user` and `role` resource definitions for Teleport's event handler |
|
||||
| `fluent.conf` | Fluentd plugin configuration |
|
||||
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.
|
||||
|
||||
## Step 3/6. Create a user and role for reading audit events
|
||||
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
title: Monitor Teleport Audit Events with Splunk
|
||||
title: Export Teleport Audit Events to Splunk
|
||||
description: How to configure the Teleport Event Handler plugin to send audit logs to Splunk
|
||||
---
|
||||
|
||||
|
|
@ -53,89 +53,15 @@ and generate credentials that the plugin will use for authentication.
|
|||
Follow the instructions for your environment to install the Teleport Event
|
||||
Handler plugin on your Universal Forwarder host:
|
||||
|
||||
<Tabs dropdownCaption="Version" dropdownSelected="Latest Release">
|
||||
<TabItem options="Latest Release" label="Download the Binary">
|
||||
|
||||
On the host where you are running the Universal Forwarder, execute the
|
||||
following commands:
|
||||
|
||||
```code
|
||||
$ curl -L -O https://get.gravitational.com/teleport-event-handler-v(=teleport.plugin.version=)-linux-amd64-bin.tar.gz
|
||||
$ tar -zxvf teleport-event-handler-v(=teleport.plugin.version=)-linux-amd64-bin.tar.gz
|
||||
```
|
||||
|
||||
Move the `teleport-event-handler` binary to `/usr/local/bin`.
|
||||
</TabItem>
|
||||
|
||||
<TabItem options="Latest Release" label="Pull via Docker">
|
||||
|
||||
On the host where you are running the Universal Forwarder, execute the
|
||||
following command:
|
||||
|
||||
```code
|
||||
$ docker pull public.ecr.aws/gravitational/teleport-plugin-event-handler:(=teleport.plugin.version=)
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem options="From Source" label="Build via Docker">
|
||||
You must have Docker installed on your Universal Forwarder host.
|
||||
|
||||
Log in to the host and execute the following commands to build the plugin:
|
||||
|
||||
```code
|
||||
$ git clone https://github.com/gravitational/teleport-plugins.git --depth 1
|
||||
$ cd teleport-plugins/event-handler/build.assets
|
||||
$ make build
|
||||
```
|
||||
|
||||
You can find the compiled binary within your clone of the `teleport-plugins`
|
||||
repo, with the file path, `event-handler/build/teleport-event-handler`. Move
|
||||
this to `/usr/local/bin`.
|
||||
|
||||
</TabItem>
|
||||
<TabItem options="From Source" label="Build via Go">
|
||||
|
||||
You will need Go >= (=teleport.golang=) installed.
|
||||
|
||||
Run the following commands on your Universal Forwarder host:
|
||||
|
||||
```code
|
||||
$ git clone https://github.com/gravitational/teleport-plugins.git --depth 1
|
||||
$ cd teleport-plugins/event-handler
|
||||
$ go build
|
||||
```
|
||||
|
||||
The resulting executable will have the name `event-handler`. To follow the
|
||||
rest of this guide, rename this file to `teleport-event-handler` and move it
|
||||
to `/usr/local/bin`.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
(!docs/pages/includes/install-event-handler.mdx!)
|
||||
|
||||
### Generate a starter config file
|
||||
|
||||
On the host where you are running the Universal Forwarder and the Teleport Event
|
||||
Handler plugin, execute the following command to generate a sample configuration
|
||||
that we will edit later:
|
||||
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.
|
||||
|
||||
```code
|
||||
$ teleport-event-handler configure . <Var name="teleport-cluster-name"/>
|
||||
```
|
||||
(!docs/pages/includes/configure-event-handler.mdx!)
|
||||
|
||||
The `teleport-event-handler configure` command generates several files that you
|
||||
will refer to when generating credentials for the Teleport Event Handler plugin
|
||||
and configuring the Universal Forwarder:
|
||||
|
||||
|File(s)|Purpose|
|
||||
|---|---|
|
||||
| `ca.crt` | Self-signed CA certificate that the Teleport Event Handler plugin and the Universal Forwarder will use to validate one another's TLS certificates.|
|
||||
| `server.crt` and `server.key`| TLS certificate and key for the Universal Forwarder.|
|
||||
| `client.crt` and `client.key`| TLS certificate and key for the Teleport Event Handler plugin.|
|
||||
| `teleport-event-handler-role.yaml`| `user` and `role` resource definitions for the Teleport Event Handler plugin.|
|
||||
| `fluent.conf`| Fluentd configuration file. We will use parts of this to configure the Universal Forwarder.|
|
||||
| `teleport-event-handler.toml` | Starter configuration file for the Teleport Event Handler plugin.|
|
||||
| `ca.key` | Not used in this setup. |
|
||||
We'll re-purpose the files generated for Fluentd in our Universal Forwarder configuration.
|
||||
|
||||
### Define RBAC resources
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue