From ebc3406ebb7bac4e58a142f8445ef0045f8776ab Mon Sep 17 00:00:00 2001 From: Russell Jones Date: Sun, 13 Mar 2022 00:42:05 +0000 Subject: [PATCH] Added Machine ID CLI and configuration references. Added Machine ID CLI and configuration references. Co-authored-by: Paul Gottschling --- docs/config.json | 14 +++ docs/pages/machine-id/reference.mdx | 8 ++ docs/pages/machine-id/reference/cli.mdx | 90 +++++++++++++++++ .../machine-id/reference/configuration.mdx | 99 +++++++++++++++++++ tool/tbot/config/config.go | 2 +- tool/tbot/main.go | 34 +++---- 6 files changed, 225 insertions(+), 22 deletions(-) create mode 100644 docs/pages/machine-id/reference.mdx create mode 100644 docs/pages/machine-id/reference/cli.mdx create mode 100644 docs/pages/machine-id/reference/configuration.mdx diff --git a/docs/config.json b/docs/config.json index 2f11419913c54..4eca8f0c3181a 100644 --- a/docs/config.json +++ b/docs/config.json @@ -564,6 +564,20 @@ "title": "Getting Started", "slug": "/machine-id/getting-started/" }, + { + "title": "Reference", + "slug": "/machine-id/reference/", + "entries": [ + { + "title": "Configuration", + "slug": "/machine-id/reference/configuration/" + }, + { + "title": "CLI", + "slug": "/machine-id/reference/cli/" + } + ] + }, { "title": "Guides", "slug": "/machine-id/guides/", diff --git a/docs/pages/machine-id/reference.mdx b/docs/pages/machine-id/reference.mdx new file mode 100644 index 0000000000000..e309faec20f4e --- /dev/null +++ b/docs/pages/machine-id/reference.mdx @@ -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) diff --git a/docs/pages/machine-id/reference/cli.mdx b/docs/pages/machine-id/reference/cli.mdx new file mode 100644 index 0000000000000..bc5276be2a147 --- /dev/null +++ b/docs/pages/machine-id/reference/cli.mdx @@ -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. + +
+```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 +``` +
+
+```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 +``` +
+ +| 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 +``` diff --git a/docs/pages/machine-id/reference/configuration.mdx b/docs/pages/machine-id/reference/configuration.mdx new file mode 100644 index 0000000000000..2ed552960e6ac --- /dev/null +++ b/docs/pages/machine-id/reference/configuration.mdx @@ -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 +``` diff --git a/tool/tbot/config/config.go b/tool/tbot/config/config.go index 70d2f2943440d..a5a1523086f3b 100644 --- a/tool/tbot/config/config.go +++ b/tool/tbot/config/config.go @@ -103,7 +103,7 @@ type OnboardingConfig struct { Token string `yaml:"token"` // CAPath is an optional path to a CA certificate. - CAPath string + CAPath string `yaml:"ca_path"` // CAPins is a list of certificate authority pins, used to validate the // connection to the Teleport auth server. diff --git a/tool/tbot/main.go b/tool/tbot/main.go index 9fbf339d00778..461754b4aa0e3 100644 --- a/tool/tbot/main.go +++ b/tool/tbot/main.go @@ -70,36 +70,28 @@ func Run(args []string) error { app := utils.InitCLIParser("tbot", "tbot: Teleport Machine ID").Interspersed(false) app.Flag("debug", "Verbose logging to stdout").Short('d').BoolVar(&cf.Debug) - app.Flag("config", "tbot.yaml path").Short('c').StringVar(&cf.ConfigPath) + app.Flag("config", "Path to a configuration file. Defaults to `/etc/tbot.yaml` if unspecified.").Short('c').StringVar(&cf.ConfigPath) versionCmd := app.Command("version", "Print the version") startCmd := app.Command("start", "Starts the renewal bot, writing certificates to the data dir at a set interval.") - startCmd.Flag("auth-server", "Specify the Teleport auth server host").Short('a').Envar(authServerEnvVar).StringVar(&cf.AuthServer) + startCmd.Flag("auth-server", "Address of the Teleport Auth Server (On-Prem installs) or Proxy Server (Cloud installs).").Short('a').Envar(authServerEnvVar).StringVar(&cf.AuthServer) startCmd.Flag("token", "A bot join token, if attempting to onboard a new bot; used on first connect.").Envar(tokenEnvVar).StringVar(&cf.Token) - startCmd.Flag("ca-pin", "A repeatable auth server CA hash to pin; used on first connect.").StringsVar(&cf.CAPins) - startCmd.Flag("data-dir", "Directory to store internal bot data.").StringVar(&cf.DataDir) - startCmd.Flag("destination-dir", "Directory to write generated certificates").StringVar(&cf.DestinationDir) - startCmd.Flag("certificate-ttl", "TTL of generated certificates").Default("60m").DurationVar(&cf.CertificateTTL) - startCmd.Flag("renewal-interval", "Interval at which certificates are renewed; must be less than the certificate TTL.").DurationVar(&cf.RenewalInterval) - startCmd.Flag("join-method", "Method to use to join the cluster.").Default(config.DefaultJoinMethod).EnumVar(&cf.JoinMethod, "token", "iam") + startCmd.Flag("ca-pin", "CA pin to validate the Teleport Auth Server; used on first connect.").StringsVar(&cf.CAPins) + startCmd.Flag("data-dir", "Directory to store internal bot data. Access to this directory should be limited.").StringVar(&cf.DataDir) + startCmd.Flag("destination-dir", "Directory to write short-lived machine certificates.").StringVar(&cf.DestinationDir) + startCmd.Flag("certificate-ttl", "TTL of short-lived machine certificates.").Default("60m").DurationVar(&cf.CertificateTTL) + startCmd.Flag("renewal-interval", "Interval at which short-lived certificates are renewed; must be less than the certificate TTL.").DurationVar(&cf.RenewalInterval) + startCmd.Flag("join-method", "Method to use to join the cluster, can be \"token\" or \"iam\".").Default(config.DefaultJoinMethod).EnumVar(&cf.JoinMethod, "token", "iam") startCmd.Flag("oneshot", "If set, quit after the first renewal.").BoolVar(&cf.Oneshot) initCmd := app.Command("init", "Initialize a certificate destination directory for writes from a separate bot user.") - initCmd.Flag("destination-dir", "If NOT using a config file, specify the destination directory.").StringVar(&cf.DestinationDir) - initCmd.Flag("init-dir", "If using a config file and multiple destinations are configured, specify which to initialize.").StringVar(&cf.InitDir) + initCmd.Flag("destination-dir", "Directory to write short-lived machine certificates to.").StringVar(&cf.DestinationDir) + initCmd.Flag("owner", "Defines Linux \"user:group\" owner of \"--destination-dir\". Defaults to the Linux user running tbot if unspecified.").StringVar(&cf.Owner) + initCmd.Flag("bot-user", "Enables POSIX ACLs and defines Linux user that can read/write short-lived certificates to \"--destination-dir\".").StringVar(&cf.BotUser) + initCmd.Flag("reader-user", "Enables POSIX ACLs and defines Linux user that will read short-lived certificates from \"--destination-dir\".").StringVar(&cf.ReaderUser) + initCmd.Flag("init-dir", "If using a config file and multiple destinations are configured, controls which destination dir to configure.").StringVar(&cf.InitDir) initCmd.Flag("clean", "If set, remove unexpected files and directories from the destination.").BoolVar(&cf.Clean) - initCmd.Flag("reader-user", "If ACLs are in use, name of the Unix user "+ - "that will read from the destination.", - ).StringVar(&cf.ReaderUser) - initCmd.Flag("bot-user", "If ACLs are in use, name of the bot Unix user "+ - "which should have write access to the destination.", - ).StringVar(&cf.BotUser) - initCmd.Flag("owner", "Name of the user:group that will own the "+ - "destination. If ACLs are in use, must be different from the reader "+ - "user and defaults to the bot user. Otherwise, assumes the current "+ - "user.", - ).StringVar(&cf.Owner) configCmd := app.Command("config", "Parse and dump a config file").Hidden()