diff --git a/charts/access/email/README.md b/charts/access/email/README.md index dd3f24d51..5818a9e8b 100644 --- a/charts/access/email/README.md +++ b/charts/access/email/README.md @@ -4,108 +4,9 @@ This chart sets up and configures a Deployment for the Access Request Email plug ## Installation -### Prerequisites +See the [Access Requests with Email guide](https://goteleport.com/docs/access-controls/access-request-plugins/ssh-approval-email/). -First, you'll need to create a Teleport user and role for the plugin. The following file contains a minimal user that's needed for the plugin to work: - -```yaml ---- -kind: role -version: v6 -metadata: - name: teleport-plugin-email -spec: - allow: - logins: - - teleport-plugin-email - rules: - - resources: - - access_request - verbs: - - list - - read - - update - options: - forward_agent: false - max_session_ttl: 8760h0m0s - port_forwarding: false ---- -kind: user -version: v2 -metadata: - name: teleport-plugin-email -spec: - roles: - - teleport-plugin-email -``` - -You can either create the user and the roles by putting the YAML above into a file and issuing the following command (you must be logged in with `tsh`): - -``` -tctl create user.yaml -``` - -or by navigating to the Teleport Web UI under `https:///web/users` and `https:///web/roles` respectively. You'll also need to create a password for the user by either clicking `Options/Reset password...` under `https:///web/users` on the UI or issuing `tctl users reset teleport-plugin-email` in the command line. - -The next step is to create an identity file, which contains a private/public key pair and a certificate that'll identify us as the user above. To do this, log in with the newly created credentials and issue a new certificate (525600 and 8760 are both roughly a year in minutes and hours respectively): - -``` -tsh login --proxy=proxy.example.com --auth local --user teleport-plugin-email --ttl 525600 -``` - -``` -tctl auth sign --user teleport-plugin-email --ttl 8760h --out teleport-plugin-email-identity -``` - -Alternatively, you can execute the command above on one of the `auth` instances/pods. - -The last step is to create the secret. The following command will create a Kubernetes secret with the name `teleport-plugin-email-identity` with the key `auth_id` in it holding the contents of the file `teleport-plugin-email-identity`: - -``` -kubectl create secret generic teleport-plugin-email-identity --from-file=auth_id=teleport-plugin-email-identity -``` - -### Installing the plugin - -``` -helm repo add teleport https://charts.releases.teleport.dev/ -``` - -```shell -helm install teleport-plugin-email teleport/teleport-plugin-email --values teleport-plugin-email-values.yaml -``` - -Example `teleport-plugin-email-values.yaml` for using MailGun: - -```yaml -teleport: - address: teleport.example.com:443 - identitySecretName: teleport-plugin-email-identity - -mailgun: - enabled: true - domain: sandboxbd81caddef744a69be0e5b544ab0c3bd.mailgun.org - privateKey: supersecretprivatekey - -roleToRecipients: - '*': ["access-requests@example.com"] -``` - -Alternatively, you can pass arguments from the command line (useful for one-liners or scripts): - -``` -helm install teleport-plugin-email teleport/teleport-plugin-email \ - --set 'teleport.address=teleport.example.com:443' \ - --set 'teleport.identitySecretName=teleport-plugin-email-identity' \ - --set 'mailgun.enabled=true' \ - --set 'mailgun.domain=sandboxbd81caddef744a69be0e5b544ab0c3b'd.mailgun.org \ - --set 'mailgun.privateKey=supersecretprivatekey' \ - --set 'roleToRecipients.*=access-requests@example.com' -``` - -See [Settings](#settings) for more details. - -## Settings +## Values The following values can be set for the Helm chart: diff --git a/charts/access/jira/README.md b/charts/access/jira/README.md index 3120550aa..c58b02966 100644 --- a/charts/access/jira/README.md +++ b/charts/access/jira/README.md @@ -4,133 +4,9 @@ This chart sets up and configures a Deployment for the Access Request Jira plugi ## Installation -### Prerequisites +See the [Access Requests with JIRA guide](https://goteleport.com/docs/access-controls/access-request-plugins/ssh-approval-jira/). -First, you'll need to create a Teleport user and role for the plugin. The following file contains a minimal user that's needed for the plugin to work: - -```yaml ---- -kind: role -version: v6 -metadata: - name: teleport-plugin-jira -spec: - allow: - logins: - - teleport-plugin-jira - rules: - - resources: - - access_request - verbs: - - list - - read - - update - options: - forward_agent: false - max_session_ttl: 8760h0m0s - port_forwarding: false ---- -kind: user -version: v2 -metadata: - name: teleport-plugin-jira -spec: - roles: - - teleport-plugin-jira -``` - -You can either create the user and the roles by putting the YAML above into a file and issuing the following command (you must be logged in with `tsh`): - -``` -tctl create user.yaml -``` - -or by navigating to the Teleport Web UI under `https:///web/users` and `https:///web/roles` respectively. You'll also need to create a password for the user by either clicking `Options/Reset password...` under `https:///web/users` on the UI or issuing `tctl users reset teleport-plugin-jira` in the command line. - -The next step is to create an identity file, which contains a private/public key pair and a certificate that'll identify us as the user above. To do this, log in with the newly created credentials and issue a new certificate (525600 and 8760 are both roughly a year in minutes and hours respectively): - -``` -tsh login --proxy=teleport.example.com --auth local --user teleport-plugin-jira --ttl 525600 -``` - -``` -tctl auth sign --user teleport-plugin-jira --ttl 8760h --out teleport-plugin-jira-identity -``` - -Alternatively, you can execute the command above on one of the `auth` instances/pods. - -The last step is to create the secret. The following command will create a Kubernetes secret with the name `teleport-plugin-jira-identity` with the key `auth_id` in it holding the contents of the file `teleport-plugin-jira-identity`: - -``` -kubectl create secret generic teleport-plugin-jira-identity --from-file=auth_id=teleport-plugin-jira-identity -``` - -### Attaching the certificate - -You'll need both a certificate and it's private key to secure the WebHook connections coming from Jira Server or Jira Cloud. Once you have them, create a Kubernetes secret similar to the one below: - -```yaml -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: teleport-plugin-jira-tls -data: - tls.crt: LS0... - tls.key: LS0... -``` - -Make sure you apply base64 on the value (or use Kubernetes Secret's `stringData` field instead of `data`). - -### Installing the plugin - -``` -helm repo add teleport https://charts.releases.teleport.dev/ -``` - -```shell -helm install teleport-plugin-jira teleport/teleport-plugin-jira --values teleport-plugin-jira-values.yaml -``` - -Example `teleport-plugin-jira-values.yaml`: - -```yaml -teleport: - address: teleport.example.com:443 - identitySecretName: teleport-plugin-jira-identity - -jira: - url: "https://jira.example.net" - username: "user@example.com" - apiToken: "exampleapitoken" - project: "REQS" - issueType: "Task" - -http: - publicAddress: "teleport-plugin-jira.example.com" - tlsFromSecret: "teleport-plugin-jira-tls" - # Uncomment and change the following lines if your secret is structured - # differently then the example above - # tlsKeySecretPath: "tls.key" - # tlsCertSecretPath: "tls.crt" - - basicAuth: - user: "basicauthuser" - password: "basicauthpassword" - -# Uncomment the following line on AWS -# chartMode: "aws" -``` - -Make sure you protect the endpoint by setting a strong basic auth password in the `http` section! - -See [Settings](#settings) for more details. - -### Set up the Jira project - -[Follow these instructions](https://goteleport.com/docs/enterprise/workflow/ssh-approval-jira-cloud/#setting-up-your-jira-project) to set up a Jira project for the incoming access requests. - -## Settings +## Values The following values can be set for the Helm chart: diff --git a/charts/access/mattermost/README.md b/charts/access/mattermost/README.md index 3245ddd7e..f18c02893 100644 --- a/charts/access/mattermost/README.md +++ b/charts/access/mattermost/README.md @@ -4,91 +4,7 @@ This chart sets up and configures a Deployment for the Access Request Mattermost ## Installation -### Prerequisites - -First, you'll need to create a Teleport user and role for the plugin. The following file contains a minimal user that's needed for the plugin to work: - -```yaml ---- -kind: role -version: v6 -metadata: - name: teleport-plugin-mattermost -spec: - allow: - logins: - - teleport-plugin-mattermost - rules: - - resources: - - access_request - verbs: - - list - - read - - update - options: - forward_agent: false - max_session_ttl: 8760h0m0s - port_forwarding: false ---- -kind: user -version: v2 -metadata: - name: teleport-plugin-mattermost -spec: - roles: - - teleport-plugin-mattermost -``` - -You can either create the user and the roles by putting the YAML above into a file and issuing the following command (you must be logged in with `tsh`): - -```console -tctl create user.yaml -``` - -or by navigating to the Teleport Web UI under `https:///web/users` and `https:///web/roles` respectively. You'll also need to create a password for the user by either clicking `Options/Reset password...` under `https:///web/users` on the UI or issuing `tctl users reset teleport-plugin-mattermost` in the command line. - -The next step is to create an identity file, which contains a private/public key pair and a certificate that'll identify us as the user above. To do this, log in with the newly created credentials and issue a new certificate (525600 and 8760 are both roughly a year in minutes and hours respectively): - -```console -tsh login --proxy proxy.example.com --auth local --user teleport-plugin-mattermost --ttl 525600 -``` - -```console -tctl auth sign --user teleport-plugin-mattermost --ttl 8760h --out teleport-plugin-mattermost-identity -``` - -Alternatively, you can execute the command above on one of the `auth` instances/pods. - -The last step is to create the secret. The following command will create a Kubernetes secret with the name `teleport-plugin-mattermost-identity` with the key `auth_id` in it holding the contents of the file `teleport-plugin-mattermost-identity`: - -```console -kubectl create secret generic teleport-plugin-mattermost-identity --from-file=auth_id=teleport-plugin-mattermost-identity -``` - -### Installing the plugin - -```console -helm repo add teleport https://charts.releases.teleport.dev/ -``` - -```console -helm install teleport-plugin-mattermost teleport/teleport-plugin-mattermost --values teleport-plugin-mattermost-values.yaml -``` - -Example `teleport-plugin-mattermost-values.yaml`: - -```yaml -teleport: - address: teleport.example.com:443 - identitySecretName: teleport-plugin-mattermost-identity - -mattermost: - url: https://mattermost.example.com/ - token: mattermosttoken - recipients: [access-requests@example.com, "#example-channel"] -``` - -See [Settings](#settings) for more details. +See the [Access Requests with Mattermost guide](https://goteleport.com/docs/access-controls/access-request-plugins/ssh-approval-mattermost/). ## Settings diff --git a/charts/access/msteams/README.md b/charts/access/msteams/README.md index 8cb8c18f4..a427a6fdf 100644 --- a/charts/access/msteams/README.md +++ b/charts/access/msteams/README.md @@ -4,69 +4,4 @@ This chart sets up and configures a Deployment for the Access Request MsTeams pl ## Installation -### Prerequisites - -As the MsTeams setup requires to download the plugin locally to generate assets to load in MsTeams, -you must follow [the MsTeams access request guide](https://goteleport.com/docs/access-controls/access-request-plugins/ssh-approval-msteams/). -When generating the identity file, choose the "Connect to the Proxy Service" tab that generates a single file `auth.pem`. - -Once the guide in finished, you should have a working `teleport-msteams.toml` configuration file. - -Recover the following values from it: -- msapi.appID -- msapi.appSecret -- msapi.teamsAppID -- msapi.tenantID -- teleport.addr - -Recover also the `auth.pem` identity file generated during the guide. - -### Add the Teleport Helm repo - -Run the command: -```shell -helm repo add teleport https://charts.releases.teleport.dev/ -``` - -### Creating the identity secret - -The identity file is not provided through the Helm chart, it should be already existing present in the cluster. - -Run the following command to create the secret from the `auth.pem` file recovered earlier: - -```shell -export NAMESPACE="your-namespace" #The namespace should already exist -kubectl create -n "$NAMESPACE" secret generic teleport-plugin-msteams-identity --from-file=auth_id=./auth.pem -``` - -### Installing the chart - -Create the value file `teleport-plugin-msteams-values.yaml` with the following content: - -```yaml -teleport: - address: "YOUR-TELEPORT-ADDRESS" - identitySecretName: "teleport-plugin-msteams-identity" - -msTeams: - appID: "YOUR-APPID" - appSecret: "YOUR-APP-SECRET" - tenantID: "YOUR-TENANT" - teamsAppID: "YOUR-TEAMS-APP-ID" - -roleToRecipients: - "*": "YOUR.EMAIL@EXAMPLE.COM" - "editor": ["YOUR.EMAIL@EXAMPLE.COM", "https://CHANNEL URL"] -``` - -_Note: If you prefer to keep `appSecret` off your values you can put it in a Kubernetes secret and specify the secret -name and secret key with the values `msTeams.appSecretFromSecret` and `msTeams.appSecretFromSecretKey`._ - -Replace the placeholders by the values you recovered during the guide. -The `roleToRecipient` map controls which channels and users will be notified if a role is requested. - -Finally, create a release from the Helm chart with the values: - -```shell -helm install teleport-plugin-msteams teleport/teleport-plugin-msteams --values teleport-plugin-msteams-values.yaml -n "$NAMESPACE" -``` +See the [Access Requests with Microsoft Teams guide](https://goteleport.com/docs/access-controls/access-request-plugins/ssh-approval-msteams/). \ No newline at end of file diff --git a/charts/access/pagerduty/README.md b/charts/access/pagerduty/README.md index 25ab3b66e..a02ad36e4 100644 --- a/charts/access/pagerduty/README.md +++ b/charts/access/pagerduty/README.md @@ -4,100 +4,9 @@ This chart sets up and configures a Deployment for the Access Request PagerDuty ## Installation -### Prerequisites +See the [Access Requests with PagerDuty guide](https://goteleport.com/docs/access-controls/access-request-plugins/ssh-approval-pagerduty/). -First, you'll need to create a Teleport user and role for the plugin. The following file contains a minimal user that's needed for the plugin to work: - -```yaml ---- -kind: role -version: v6 -metadata: - name: teleport-plugin-pagerduty -spec: - allow: - logins: - - teleport-plugin-pagerduty - rules: - - resources: - - access_request - verbs: - - list - - read - - update - options: - forward_agent: false - max_session_ttl: 8760h0m0s - port_forwarding: false ---- -kind: user -version: v2 -metadata: - name: teleport-plugin-pagerduty -spec: - roles: - - teleport-plugin-pagerduty -``` - -You can either create the user and the roles by putting the YAML above into a file and issuing the following command (you must be logged in with `tsh`): - -```console -tctl create user.yaml -``` - -or by navigating to the Teleport Web UI under `https:///web/users` and `https:///web/roles` respectively. You'll also need to create a password for the user by either clicking `Options/Reset password...` under `https:///web/users` on the UI or issuing `tctl users reset teleport-plugin-pagerduty` in the command line. - -The next step is to create an identity file, which contains a private/public key pair and a certificate that'll identify us as the user above. To do this, log in with the newly created credentials and issue a new certificate (525600 and 8760 are both roughly a year in minutes and hours respectively): - -```console -tsh login --proxy proxy.example.com --auth local --user teleport-plugin-pagerduty --ttl 525600 -``` - -```console -tctl auth sign --user teleport-plugin-pagerduty --ttl 8760h --out teleport-plugin-pagerduty-identity -``` - -Alternatively, you can execute the command above on one of the `auth` instances/pods. - -The last step is to create the secret. The following command will create a Kubernetes secret with the name `teleport-plugin-pagerduty-identity` with the key `auth_id` in it holding the contents of the file `teleport-plugin-pagerduty-identity`: - -```console -kubectl create secret generic teleport-plugin-pagerduty-identity --from-file=auth_id=teleport-plugin-pagerduty-identity -``` - -### Installing the plugin - -```console -helm repo add teleport https://charts.releases.teleport.dev/ -``` - -```console -helm install teleport-plugin-pagerduty teleport/teleport-plugin-pagerduty --values teleport-plugin-pagerduty-values.yaml -``` - -Example `teleport-plugin-pagerduty-values.yaml`: - -```yaml -teleport: - address: teleport.example.com:443 - identitySecretName: teleport-plugin-pagerduty-identity - -pagerduty: - apiKey: pagerdutyapikey - userEmail: pagerduty-bot-user@example.com - notifyService: "request approvals" - servies: - - on-call - - support -``` - -See [Settings](#settings) for more details. - -### Setting up roles - -After the PagerDuty plugin has been set up correctly, you'll need to adjust the roles you'd like to set up with it by adding the proper annotations based on your use case. For more information, visit [Setting up Pagerduty notification alerts](../../../access/pagerduty/README.md#setting-up-pagerduty-notification-alerts) in the plugin's documentation. - -## Settings +## Values The following values can be set for the Helm chart: diff --git a/charts/access/slack/README.md b/charts/access/slack/README.md index f4d031f2b..634f3c23d 100644 --- a/charts/access/slack/README.md +++ b/charts/access/slack/README.md @@ -4,105 +4,9 @@ This chart sets up and configures a Deployment for the Access Request Slack plug ## Installation -### Prerequisites +See the [Access Requests with Slack guide](https://goteleport.com/docs/access-controls/access-request-plugins/ssh-approval-slack/). -First, you'll need to create a Teleport user and role for the plugin. The following file contains a minimal user that's needed for the plugin to work: - -```yaml ---- -kind: role -version: v6 -metadata: - name: teleport-plugin-slack -spec: - allow: - logins: - - teleport-plugin-slack - rules: - - resources: - - access_request - verbs: - - list - - read - - update - options: - forward_agent: false - max_session_ttl: 8760h0m0s - port_forwarding: false ---- -kind: user -version: v2 -metadata: - name: teleport-plugin-slack -spec: - roles: - - teleport-plugin-slack -``` - -You can either create the user and the roles by putting the YAML above into a file and issuing the following command (you must be logged in with `tsh`): - -``` -tctl create user.yaml -``` - -or by navigating to the Teleport Web UI under `https:///web/users` and `https:///web/roles` respectively. You'll also need to create a password for the user by either clicking `Options/Reset password...` under `https:///web/users` on the UI or issuing `tctl users reset teleport-plugin-slack` in the command line. - -The next step is to create an identity file, which contains a private/public key pair and a certificate that'll identify us as the user above. To do this, log in with the newly created credentials and issue a new certificate (525600 and 8760 are both roughly a year in minutes and hours respectively): - -``` -tsh login --proxy=proxy.example.com --auth local --user teleport-plugin-slack --ttl 525600 -``` - -``` -tctl auth sign --user teleport-plugin-slack --ttl 8760h --out teleport-plugin-slack-identity -``` - -Alternatively, you can execute the command above on one of the `auth` instances/pods. - -The last step is to create the secret. The following command will create a Kubernetes secret with the name `teleport-plugin-slack-identity` with the key `auth_id` in it holding the contents of the file `teleport-plugin-slack-identity`: - -``` -kubectl create secret generic teleport-plugin-slack-identity --from-file=auth_id=teleport-plugin-slack-identity -``` - -### Installing the plugin - -``` -helm repo add teleport https://charts.releases.teleport.dev/ -``` - -```shell -helm install teleport-plugin-slack teleport/teleport-plugin-slack --values teleport-plugin-slack-values.yaml -``` - -Example `teleport-plugin-slack-values.yaml`: - -```yaml -teleport: - address: teleport.example.com:443 - identitySecretName: teleport-plugin-slack-identity - -slack: - token: xoxb-testtoken - -roleToRecipients: - '*': [access-requests@example.com] -``` - -Alternatively, you can pass arguments from the command line (useful for one-liners or scripts): - -``` -helm install teleport-plugin-slack teleport/teleport-plugin-slack \ - --set 'teleport.address=teleport.example.com:443' \ - --set 'teleport.identitySecretName=teleport-plugin-slack-identity' \ - --set 'slack.token=xoxb-testtoken' \ - --set 'roleToRecipients.*[0]=access-requests@example.com' -``` - -See [Settings](#settings) for more details. - - -## Settings +## Values The following values can be set for the Helm chart: diff --git a/charts/event-handler/README.md b/charts/event-handler/README.md index f537f9f43..8b38b5c5e 100644 --- a/charts/event-handler/README.md +++ b/charts/event-handler/README.md @@ -4,118 +4,7 @@ This chart sets up and configures a Deployment for the Event Handler plugin. ## Installation -### Prerequisites - -First, you'll need to create a Teleport user and role for the plugin. The following file contains a minimal user that's needed for the plugin to work: - -```yaml ---- -kind: role -version: v6 -metadata: - name: teleport-plugin-event-handler -spec: - allow: - logins: - - teleport-plugin-event-handler - rules: - - resources: - - event - verbs: - - list - - read - options: - forward_agent: false - max_session_ttl: 8760h0m0s - port_forwarding: false ---- -kind: user -version: v2 -metadata: - name: teleport-plugin-event-handler -spec: - roles: - - teleport-plugin-event-handler -``` - -You can either create the user and the roles by putting the YAML above into a file and issuing the following command (you must be logged in with `tsh`): - -```console -tctl create user.yaml -``` - -or by navigating to the Teleport Web UI under `https:///web/users` and `https:///web/roles` respectively. You'll also need to create a password for the user by either clicking `Options/Reset password...` under `https:///web/users` on the UI or issuing `tctl users reset teleport-plugin-event-handler` in the command line. - -The next step is to create an identity file, which contains a private/public key pair and a certificate that'll identify us as the user above. To do this, log in with the newly created credentials and issue a new certificate (525600 and 8760 are both roughly a year in minutes and hours respectively): - -```console -tsh login --proxy=proxy.example.com --auth local --user teleport-plugin-event-handler --ttl 525600 -``` - -```console -tctl auth sign --user teleport-plugin-event-handler --ttl 8760h --out teleport-plugin-event-handler-identity -``` - -Alternatively, you can execute the command above on one of the `auth` instances/pods. - -The last step is to create the secret. The following command will create a Kubernetes secret with the name `teleport-plugin-event-handler-identity` with the key `auth_id` in it holding the contents of the file `teleport-plugin-event-handler-identity`: - -```console -kubectl create secret generic teleport-plugin-event-handler-identity --from-file=auth_id=teleport-plugin-event-handler-identity -``` - -### Mounting Fluentd client certificate - -See the [plugin's documentation](../../event-handler/README.md#mtls_advanced) about how to generate the certificates using fluentd's CA certificate and private key. - -Once the files `client.key` and `client.crt` were created successfully, the following command can be used to create a new secret (`ca.crt` is also included since we'll need it to verify we are connecting to the right fluentd): - -```console -kubectl create secret generic teleport-plugin-event-handler-client-tls --from-file="ca.crt=ca.crt,client.key=client.key,client.crt=client.crt" -``` - -### Storage - -The `event-handler` plugin stores it's current state on the disk, so to avoid accidentally sending any events twice, it's a good idea to create a PersistentVolumeClaim to ensure those files are retained. The Chart contains a default implementation (see the example values file below). Check out [Settings](#settings) for more options! - -For more information, check out [Persistent Volumes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) in the Kubernetes Documentation. - -### Installing the plugin - -```console -helm repo add teleport https://charts.releases.teleport.dev/ -``` - -```console -helm install teleport-plugin-event-handler teleport/teleport-plugin-event-handler --values teleport-plugin-event-handler-values.yaml -``` - -Example `teleport-plugin-event-handler-values.yaml`: - -```yaml -teleport: - address: teleport.example.com:443 - identitySecretName: teleport-plugin-event-handler-identity - -eventHandler: - storagePath: "/var/lib/teleport/plugins/event-handler/storage" - timeout: "10s" - batch: 20 - -fluentd: - url: "https://fluentd.fluentd.svc.cluster.local/events.log" - sessionUrl: "https://fluentd.fluentd.svc.cluster.local/session.log" - certificate: - secretName: "teleport-plugin-event-handler-client-tls" - caPath: "ca.crt" - certPath: "client.crt" - keyPath: "client.key" - -persistentVolumeClaim: - enabled: true -``` - -See [Settings](#settings) for more details. +See the [Access Requests with Slack guide](https://goteleport.com/docs/access-controls/access-request-plugins/ssh-approval-slack/). ## Settings diff --git a/event-handler/README.md b/event-handler/README.md index ca169a838..881e35150 100644 --- a/event-handler/README.md +++ b/event-handler/README.md @@ -2,270 +2,9 @@ This plugin is used to export Audit Log events to Fluentd service. -## Setup +## Usage -### Prerequisites - -This guide assumes that you have: -* Teleport 6.2 or newer -* Admin privileges to access tctl -* Docker to build plugin from source and run fluentd example instance - -The required Fluentd version for production setup is v1.12.4 or newer. Lower versions do not support TLS. - -## Install the plugin - -There are several methods to installing and using the Teleport Event Handler Plugin: - -1. Use a [precompiled binary](#precompiled-binary) - -2. Use a [docker image](#docker-image) - -3. Install from [source](#building-from-source) - -### Precompiled Binary - -Get the plugin distribution. - -```bash -$ curl -L https://get.gravitational.com/teleport-event-handler-v7.0.2-linux-amd64-bin.tar.gz -$ tar -xzf teleport-event-handler-v7.0.2-linux-amd64-bin.tar.gz -$ cd teleport-event-handler -$ ./install -``` - -### Docker Image -```bash -$ docker pull public.ecr.aws/gravitational/teleport-plugin-event-handler:9.0.2 -``` - -```bash -$ docker run public.ecr.aws/gravitational/teleport-plugin-event-handler:9.0.2 version -Teleport event handler v9.0.2 git:teleport-event-handler-v9.0.2-0-g9e149895 go1.17.8 -``` - -For a list of available tags, visit [Amazon ECR Public Gallery](https://gallery.ecr.aws/gravitational/teleport-plugin-event-handler) - -### Building from source - -Please ensure that Docker is running! - -```sh -$ git clone https://github.com/gravitational/teleport-plugins.git --depth 1 -$ cd teleport-plugins/event-handler/build.assets -$ make install -``` - -This command will build `build/teleport-event-handler` executable and place it to `/usr/local/bin` folder. The following error means that you do not have write permissions on target folder: - -```sh -cp: /usr/local/bin/teleport-event-handler: Operation not permitted -``` - -To fix this, you can either set target folder to something listed in your `$PATH`: - -```sh -$ make install BINDIR=/tmp/test-fluentd-setup -``` - -or copy binary file manually with `sudo`: - -```sh -$ sudo cp build/teleport-event-handler /usr/local/bin -``` - -## Generate example configuration - -Run: - -```sh -$ teleport-event-handler configure . -``` - -You'll see the following output: - -```sh -Teleport event handler 9.0.2 teleport-event-handler-v9.0.2-0-g9e149895 - -[1] Generated mTLS Fluentd certificates 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/docs/setup/guides/fluentd -``` - -Where `ca.crt` and `ca.key` would be Fluentd self-signed CA certificate and private key, `server.crt` and `server.key` would be fluentd server certificate and key, `client.crt` and `client.key` would be Fluentd client certificate and key, all signed by the generated CA. - -Check ```teleport-event-handler configure --help``` usage instructions. You may set several configuration options, including key/cert file names, server key encryption password and Teleport auth proxy address. - -## Create user and role for access audit log events - -The generated `teleport-event-handler-role.yaml` would contain the following content: - -```yaml -kind: user -metadata: - name: teleport-event-handler -spec: - roles: ['teleport-event-handler'] -version: v2 ---- -kind: role -metadata: - name: teleport-event-handler -spec: - allow: - rules: - - resources: ['event','session'] - verbs: ['list','read'] -version: v6 -``` - -It defines `teleport-event-handler` role and user which has read-only access to the `event` API. - -Log into Teleport Authentication Server, this is where you normally run `tctl`. Run `tctl` to create role and user: - -```sh -tctl create -f teleport-event-handler-role.yaml -``` - -## Export teleport-event-handler identity file - -Teleport Plugin use the fluentd role and user to read the events. We export the identity files, using tctl auth sign. - -```sh -tctl auth sign --out identity --user teleport-event-handler -``` - -This will generate `identity` which contains TLS certificates and will be used to connect plugin to your Teleport instance. - -## Run fluentd - -The plugin will send events to the fluentd instance using keys generated on the previous step. Generated `fluent.conf` file would contain the following content: - -``` - - @type http - port 8888 - - - client_cert_auth true - - # We are going to run fluentd in Docker. /keys will be mounted from the host file system. - ca_path /keys/ca.crt - cert_path /keys/server.crt - private_key_path /keys/server.key - private_key_passphrase ********** # Passphrase generated along with the keys - - - - @type json - json_parser oj - - # This time format is used by the plugin. This field is required. - time_type string - time_format %Y-%m-%dT%H:%M:%S - - - # If the number of events is high, fluentd will start failing the ingestion - # with the following error message: buffer space has too many data errors. - # The following configuration prevents data loss in case of a restart and - # overcomes the limitations of the default fluentd buffer configuration. - # This configuration is optional. - # See https://docs.fluentd.org/configuration/buffer-section for more details. - - @type file - flush_thread_count 8 - flush_interval 1s - chunk_limit_size 10M - queue_limit_length 16 - retry_max_interval 30 - retry_forever true - - - -# Events sent to test.log will be dumped to STDOUT. - - @type stdout - - -# Events sent to session.*.log will be dumped to STDOUT. - - @type stdout - -``` - -Start fluentd instance: - -```sh -docker run -p 8888:8888 -v $(pwd):/keys -v $(pwd)/fluent.conf:/fluentd/etc/fluent.conf fluent/fluentd:edge -``` - -## Configure the plugin - -The generated `teleport-event-handler.toml` would contain the following plugin configuration: - -```toml -storage = "./storage" # Plugin will save it's state here -timeout = "10s" -batch = 20 - -[forward.fluentd] -cert = "client.crt" -key = "client.key" -ca = "ca.crt" -url = "https://localhost:8888/test.log" -session-url = "https://localhost:8888/session" # ..log will be appended to this URL - -[teleport] -addr = "localhost:3025" # Default local Teleport instance address -identity = "identity" # Identity file exported on previous step -``` - -## Start the plugin - -```sh -$ teleport-event-handler start --config teleport-event-handler.toml --start-time 2021-01-01T00:00:00Z -``` - -or with docker: - -```sh -$ docker run -v :/etc/teleport-event-handler public.ecr.aws/gravitational/teleport-plugin-event-handler:9.0.2 start --config /etc/teleport-event-handler/teleport-event-handler.toml --start-time 2021-01-01T00:00:00Z -``` - -Note that here we used start time at the beginning of year 2021. Supposedly you have some events at the Teleport instance you are connecting to. Otherwise, you can omit `--start-time` flag, start the service and generate an events using `tctl create -f teleport-event-handler.yaml` then from the first step. `teleport-event-handler` will wait for that new events to appear and will send them to the fluentd. - -You should see something like this: - -```sh -INFO[0046] Event sent id=0b5f2a3e-faa5-4d77-ab6e-362bca0994fc ts="2021-06-08 11:00:56.034 +0000 UTC" type=user.login -INFO[0046] Event sent id=8a435f89-a70a-4bb4-9b0f-2818da51a62b ts="2021-06-08 12:09:11.344 +0000 UTC" type=user.create -INFO[0046] Event sent id=04734bc5-f8d8-493f-8109-680b8df76ce9 ts="2021-06-08 12:09:11.783 +0000 UTC" type=role.created -INFO[0046] Event sent id=2a3ac443-5e32-41c7-9b3e-da45d53f27b2 ts="2021-06-08 12:09:43.892 +0000 UTC" type=user.update -INFO[0046] Event sent id=af9c0777-7f02-4ec4-a682-3896a6960ce5 ts="2021-06-08 12:09:44.329 +0000 UTC" type=role.created -``` - -## Do not forget to set time range - -By default, all events starting from the current moment will be exported. If you want to export previous events, you have to pass `--start-time` CLI arg. - -This will start an export from May 5 2021: - -```sh -teleport-event-handler start --config teleport-event-handler.toml --start-time "2021-05-05T00:00:00Z" -``` - -This will export new events from a moment the service did start: - -```sh -teleport-event-handler start --config teleport-event-handler.toml -``` - -Note that start time can be set only once, on the first run of the tool. If you want to change the time frame later, remove plugin state dir which you had specified in `storage-dir` argument.s +See the [Export Events with FluentD Guide](https://goteleport.com/docs/management/export-audit-events/fluentd/). ## How it works @@ -307,25 +46,9 @@ You could use `--dry-run` argument if you want event handler to simulate event e `--skip-session-types` is `['print']` by default. Please note that if you enable forwarding of print events (`--skip-session-types=''`) the `Data` field would also be sent. -## Using with Teleport Cloud - -### Login to Teleport cloud: - -```sh -$ tsh login --proxy test.teleport.sh:443 --user test@evilmartians.com -``` - -### Generate sample configuration using the cloud address: - -```sh -$ teleport-event-handler configure . test.teleport.sh:443 -``` - -Then follow the manual starting at ["Export teleport-event-handler identity file"](#export) section. - ## Advanced topics -### Generate mTLS certificates using OpenSSL/LibreSSL +### Generate mTLS certificates using OpenSSL/LibreSSL For the purpose of security, we require mTLS to be enabled on the fluentd side. You are going to need [OpenSSL configuration file](example/ssl.conf). Put the following contents to `ssl.conf`: