mirror of
https://github.com/gravitational/teleport
synced 2024-10-20 01:03:40 +00:00
Added Machine ID CLI and configuration references.
Added Machine ID CLI and configuration references. Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
This commit is contained in:
Russell Jones
Russell Jones
parent
0aa6855c8f
commit
70474d9871
|
|
@ -560,6 +560,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/",
|
||||
|
|
|
|||
8
docs/pages/machine-id/reference.mdx
Normal file
8
docs/pages/machine-id/reference.mdx
Normal file
|
|
@ -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)
|
||||
90
docs/pages/machine-id/reference/cli.mdx
Normal file
90
docs/pages/machine-id/reference/cli.mdx
Normal file
|
|
@ -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
|
||||
```
|
||||
99
docs/pages/machine-id/reference/configuration.mdx
Normal file
99
docs/pages/machine-id/reference/configuration.mdx
Normal file
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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()
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue