-
Notifications
You must be signed in to change notification settings - Fork 1.8k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Added Machine ID CLI and configuration references.
Added Machine ID CLI and configuration references. Co-authored-by: Paul Gottschling <[email protected]>
- Loading branch information
Showing
6 changed files
with
225 additions
and
22 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,8 @@ | ||
| --- | ||
| title: Machine ID Reference | ||
| description: Configuration and CLI reference for Teleport Machine ID. | ||
| --- | ||
|
|
||
|
|
||
| - [Configuration](./reference/configuration.mdx) | ||
| - [CLI](./reference/cli.mdx) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,90 @@ | ||
| --- | ||
| title: Machine ID CLI Reference | ||
| description: CLI reference for Teleport Machine ID. | ||
| --- | ||
|
|
||
| ## `tbot start` | ||
|
|
||
| Starts the Machine ID client `tbot`, fetching and writing certificates to disk | ||
| at a set interval. | ||
|
|
||
| <Details scope={["cloud"]} scopeOnly={true}> | ||
| ```code | ||
| $ tbot start \ | ||
| --data-dir=/var/lib/teleport/bot \ | ||
| --destination-dir=/opt/machine-id \ | ||
| --token=00000000000000000000000000000000 \ | ||
| --join-method=token \ | ||
| --ca-pin=sha256:1111111111111111111111111111111111111111111111111111111111111111 \ | ||
| --auth-server=example.teleport.sh:443 | ||
| ``` | ||
| </Details> | ||
| <Details scope={["oss","enterprise"]} scopeOnly={true}> | ||
| ```code | ||
| $ tbot start \ | ||
| --data-dir=/var/lib/teleport/bot \ | ||
| --destination-dir=/opt/machine-id \ | ||
| --token=00000000000000000000000000000000 \ | ||
| --join-method=token \ | ||
| --ca-pin=sha256:1111111111111111111111111111111111111111111111111111111111111111 \ | ||
| --auth-server=auth.example.com:3025 | ||
| ``` | ||
| </Details> | ||
|
|
||
| | Flag | Description | | ||
| |----------------------|------------------------------------------------------------------------------------------------| | ||
| | `-d/--debug` | Enable verbose logging to stderr. | | ||
| | `-c/--config` | Path to a configuration file. Defaults to `/etc/tbot.yaml` if unspecified. | | ||
| | `-a/--auth-server` | Address of the Teleport Auth Server (On-Prem installs) or Teleport Cloud tenant. | | ||
| | `--token` | A bot join token, if attempting to onboard a new bot; used on first connect. | | ||
| | `--ca-pin` | CA pin to validate the Teleport Auth Server; used on first connect. | | ||
| | `--data-dir` | Directory to store internal bot data. Access to this directory should be limited. | | ||
| | `--destination-dir` | Directory to write short-lived machine certificates. | | ||
| | `--certificate-ttl` | TTL of short-lived machine certificates. | | ||
| | `--renewal-interval` | Interval at which short-lived certificates are renewed; must be less than the certificate TTL. | | ||
| | `--join-method` | Method to use to join the cluster. Can be `token` or `iam`. | | ||
| | `--one-shot` | If set, quit after the first renewal. | | ||
|
|
||
| ## `tbot init` | ||
|
|
||
| If you want to write certificates to disk as a different user than the Machine | ||
| ID client, you can use `tbot init` to configure either file or POSIX ACLs | ||
| permissions. This allows you to lock down access to Machine ID's short-lived | ||
| certificates from other users or applications on the system. | ||
|
|
||
| | Flag | Description | | ||
| |---------------------|--------------------------------------------------------------------------------------------------------------------| | ||
| | `-d/--debug` | Enable verbose logging to stderr. | | ||
| | `-c/--config` | Path to a configuration file. Defaults to `/etc/tbot.yaml` if unspecified. | | ||
| | `--destination-dir` | Directory to write short-lived machine certificates to. | | ||
| | `--owner` | Defines the Linux `user:group` owner of `--destination-dir`. Defaults to the Linux user running `tbot` if unspecified. | | ||
| | `--bot-user` | Enables POSIX ACLs and defines the Linux user that can read/write short-lived certificates to `--destination-dir`. | | ||
| | `--reader-user` | Enables POSIX ACLs and defines the Linux user that will read short-lived certificates from `--destination-dir`. | | ||
| | `--init-dir` | If using a config file and multiple destinations are configured, controls which destination dir to configure. | | ||
| | `--clean` | If set, remove unexpected files and directories from the destination. | | ||
|
|
||
| ### `tbot init` with file permissions | ||
|
|
||
| If running `tbot` as the Linux user `root`, use the following invocation of | ||
| `tbot init` to initialize the short-lived certificate directory | ||
| `/opt/machine-id` with owner `jenkins:jenkins`. | ||
|
|
||
| ```code | ||
| $ tbot init \ | ||
| --destination-dir=/opt/machine-id \ | ||
| --owner=jenkins:jenkins | ||
| ``` | ||
|
|
||
| ### `tbot init` with POSIX ACLs | ||
|
|
||
| If running `tbot` as the Linux user `teleport`, use the following invocation of | ||
| `tbot init` to initialize the short-lived certificate directory | ||
| `/opt/machine-id` with owner `teleport:teleport` but allow `jenkins` to read | ||
| from `/opt/machine-id`. | ||
|
|
||
| ```code | ||
| $ tbot init \ | ||
| --destination-dir=/opt/machine-id \ | ||
| --bot-user=teleport \ | ||
| --reader-user=jenkins | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,99 @@ | ||
| --- | ||
| title: Machine ID Configuration Reference | ||
| description: Configuration reference for Teleport Machine ID. | ||
| --- | ||
|
|
||
| The following snippet shows full YAML configuration of the Machine ID client | ||
| `tbot` which by default is loaded from `/etc/tbot.yaml`. | ||
|
|
||
| ```yaml | ||
| # Debug enables verbose logging to stderr. | ||
| debug: true | ||
|
|
||
| # Address of the Teleport Auth Server (on-prem installs) or Teleport Cloud tenant. | ||
| auth_server: "auth.example.com:3025" # or "example.teleport.sh:443" for Teleport Cloud | ||
|
|
||
| # TTL of short-lived machine certificates. | ||
| certificate_ttl: "5m" | ||
|
|
||
| # Interval at which short-lived certificates are renewed; must be less than | ||
| # the certificate TTL. | ||
| renewal_interval: "1m" | ||
|
|
||
| # If set, quit after the first renewal. | ||
| oneshot: true | ||
|
|
||
| # Onboarding values are only used on first connect. | ||
| onboarding: | ||
| # Cluster join method. Can be "token" or "iam". | ||
| join_method: "token" | ||
|
|
||
| # Token used to join the cluster. (only required for join_method: token) | ||
| token: "00000000000000000000000000000000" | ||
|
|
||
| # CA Path used to validate the identity of the Teleport Auth Server on first connect. | ||
| ca_path: "/path/to/ca.pem" | ||
|
|
||
| # CA Pins used to validate the identity of the Teleport Auth Server on first connect. | ||
| ca_pins: | ||
| - "sha256:1111111111111111111111111111111111111111111111111111111111111111" | ||
| - "sha256:2222222222222222222222222222222222222222222222222222222222222222" | ||
|
|
||
| # Storage defines where Machine ID internal data is stored. | ||
| storage: | ||
| # Directory to store internal bot data. Access to this directory should be | ||
| # limited. | ||
| directory: /var/lib/teleport/bot | ||
|
|
||
| # Alternatively, internal data can be stored in memory. "directory" and | ||
| # "memory" are mutually exclusive. | ||
| memory: true | ||
|
|
||
| # Destinations specifies where short-lived certificates are stored. | ||
| destinations: | ||
| # Directory specifies where short-lived certificates are stored. | ||
| - directory: /opt/machine-id | ||
| # Configure symlink attack prevention. Requires Linux 5.6+. | ||
| # Possible values: | ||
| # * try-secure (default): Attempt to securely read and write certificates | ||
| # without symlinks, but fall back (with a warning) to insecure read | ||
| # and write if the host doesn't support this. | ||
| # * secure: Attempt to securely read and write certificates, with a hard error | ||
| # if unsupported. | ||
| # * insecure: Quietly allow symlinks in paths. | ||
| symlinks: try-secure | ||
|
|
||
| # Configure ACL use. Requires Linux with a file system that supports ACLs. | ||
| # Possible values: | ||
| # * try (default on Linux): Attempt to use ACLs, warn at runtime if ACLs | ||
| # are configured but invalid. | ||
| # * off (default on non-Linux): Do not attempt to use ACLs. | ||
| # * required: Always use ACLs, produce a hard error at runtime if ACLs | ||
| # are invalid. | ||
| acls: try | ||
|
|
||
| # One of more roles to grant to the bot. It must have been granted (at | ||
| # least) these roles with `tctl bots add --roles=...` | ||
| # By default, all possible roles are included. | ||
|
|
||
| # Subset of roles allowed during creation via `tctl bots add --roles=...`. Can | ||
| # be used to write short-lived certificates with different roles to | ||
| # different directories. | ||
| roles: [a, b, c] | ||
|
|
||
| # Which types of certificates to generate. `[ssh]` is the default. | ||
| kinds: [ssh, tls] | ||
|
|
||
| # A list of configuration templates to generate and write to the | ||
| # destination directory. | ||
| configs: | ||
| # ssh_client generates known_hosts and an ssh_config that can be | ||
| # included. We can ensure the correct certificate kinds are generated | ||
| # while generating the config templates. | ||
| - ssh_client | ||
|
|
||
| # Alternatively, proxy port can be set on ssh_client to override the | ||
| # defaults. Useful for Telport Cloud. | ||
| - ssh_client: | ||
| proxy_port: 443 | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters