mirror of
https://github.com/gravitational/teleport.git
synced 2026-11-03 07:40:28 +08:00
241 lines
12 KiB
Plaintext
241 lines
12 KiB
Plaintext
---
|
|
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.
|
|
|
|
<ScopedBlock scope={["cloud"]}>
|
|
|
|
```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
|
|
```
|
|
|
|
</ScopedBlock>
|
|
|
|
<ScopedBlock scope={["oss","enterprise"]}>
|
|
|
|
```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
|
|
```
|
|
|
|
</ScopedBlock>
|
|
|
|
| Flag | Description |
|
|
|----------------------|------------------------------------------------------------------------------------------------|
|
|
| `-d/--debug` | Enable verbose logging to stderr. |
|
|
| `-c/--config` | Path to a configuration file. |
|
|
| `-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. Can also be an absolute path to a file containing the token. |
|
|
| `--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`. |
|
|
| `--oneshot` | 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. |
|
|
| `--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
|
|
```
|
|
## `tbot configure`
|
|
|
|
Writes a configuration file with the options specified using the commandline
|
|
parameters to STDOUT or a path on disk. This file can then be used to control
|
|
the behaviour of `tbot`.
|
|
|
|
It is preferable to generate a configuration, and then use this with `tbot`
|
|
rather than directly providing parameters to `tbot start`.
|
|
|
|
| Flag | Description |
|
|
|----------------------|--------------------------------------------------------------------------------------------------------|
|
|
| `-d/--debug` | Enable verbose logging to stderr. |
|
|
| `-o/--output` | Path to write configuration file to. If not provided, the generated configuration is output to STDOUT. |
|
|
| `-a/--auth-server` | Address of the Teleport Auth Server (on-prem installs) or Teleport Cloud tenant. |
|
|
| `--ca-pin` | CA pin to validate the Teleport Auth Server; used on first connect. |
|
|
| `--certificate-ttl` | TTL of short-lived machine certificates. |
|
|
| `--data-dir` | Directory to store internal bot data. Access to this directory should be limited. |
|
|
| `--join-method` | Method to use to join the cluster. Can be `token` or `iam`. |
|
|
| `--oneshot` | If set, quit after the first renewal. |
|
|
| `--renewal-interval` | Interval at which short-lived certificates are renewed; must be less than the certificate TTL. |
|
|
| `--token` | A bot join token, if attempting to onboard a new bot; used on first connect. Can also be an absolute path to a file containing the token. |
|
|
|
|
## `tbot db`
|
|
|
|
Retrieves basic information about and connects to databases using native
|
|
clients.
|
|
|
|
This is best used for testing and validation purposes; most
|
|
users will likely prefer to connect their own databases to a local proxy
|
|
using `tbot proxy db` as described below.
|
|
|
|
Note that `tsh` must also be installed to make use of this command.
|
|
|
|
| Flag | Description |
|
|
|---------------------|----------------------------------------------------------------------------------------------------------|
|
|
| `-d/--debug` | Enable verbose logging to stderr. |
|
|
| `-c/--config` | Path to a configuration file. |
|
|
| `--destination-dir` | Path to the Machine ID destination dir that should be used for authentication. Required. |
|
|
| `--proxy` | The `host:port` of the Teleport Proxy Service to use to access resources. Required. |
|
|
| `--cluster` | The name of the cluster on which resources should be accessed. Extracted from the bot identity if unset. |
|
|
|
|
All other flags and arguments are passed directly to `tsh db ...`, along
|
|
with authentication parameters to use the Machine ID identity to skip `tsh`'s
|
|
login steps.
|
|
|
|
Note that certain CLI parameters, for example `--help`, may be captured by
|
|
`tbot` even if intended to be passed to the wrapped `tsh`. A `--` argument can
|
|
be used to ensure all following arguments are passed to `tsh` and ignored by
|
|
`tbot`:
|
|
|
|
```code
|
|
# This shows `--help` for `tbot db`:
|
|
$ tbot db --proxy=example.com --destination-dir=./tbot-user/ --help
|
|
|
|
# This shows `--help` for `tsh db`:
|
|
$ tbot db --proxy=example.com --destination-dir=./tbot-user/ -- --help
|
|
```
|
|
|
|
Additionally, be aware of the following limitations of `tbot db`:
|
|
- `tbot db connect` requires a `tbot db login` for certain database types,
|
|
like MySQL, so that additional connection parameters can be written to a
|
|
local configuration file.
|
|
- `tbot db env` is not fully supported.
|
|
|
|
## `tbot proxy`
|
|
|
|
If you want to access Teleport resources on a cluster using
|
|
[TLS Routing](../../management/operations/tls-routing.mdx), you'll need to
|
|
run a local ALPN/SNI proxy to access the resources. The `tbot proxy` command
|
|
wraps `tsh proxy` to provide local proxy functionality for various protocols,
|
|
including SSH and database access.
|
|
|
|
Note that `tsh` must also be installed to make use of this command.
|
|
|
|
| Flag | Description |
|
|
|---------------------|----------------------------------------------------------------------------------------------------------|
|
|
| `-d/--debug` | Enable verbose logging to stderr. |
|
|
| `-c/--config` | Path to a configuration file. |
|
|
| `--destination-dir` | Path to the Machine ID destination dir that should be used for authentication. Required. |
|
|
| `--proxy` | The `host:port` of the Teleport Proxy Service through which resources will be accessed. Required. |
|
|
| `--cluster` | The name of the cluster on which resources should be accessed. Extracted from the bot identity if unset. |
|
|
|
|
All other flags and arguments are passed directly to `tsh proxy ...`, along
|
|
with authentication parameters to use the Machine ID identity to skip `tsh`'s
|
|
login step.
|
|
|
|
Note that certain CLI parameters, for example `--help`, may be captured by
|
|
`tbot` even if intended to be passed to the wrapped `tsh`. A `--` argument can
|
|
be used to ensure all following arguments are passed to `tsh` and ignored by
|
|
`tbot`:
|
|
|
|
```code
|
|
# This shows `--help` for `tbot proxy`:
|
|
$ tbot proxy --proxy=example.com --destination-dir=./tbot-user/ --help
|
|
|
|
# This shows `--help` for `tsh proxy`:
|
|
$ tbot proxy --proxy=example.com --destination-dir=./tbot-user/ -- --help
|
|
```
|
|
|
|
### `tbot proxy ssh` for SSH access
|
|
|
|
This forwards standard input and output over a proxy suitable for use as an
|
|
OpenSSH `ProxyCommand`.
|
|
|
|
```code
|
|
$ tbot proxy --destination-dir=./tbot-user --proxy=proxy.example.com:3080 ssh alice@node:3022
|
|
```
|
|
|
|
In this case:
|
|
- `alice` is the remote username
|
|
- `node` is the Teleport Node name
|
|
- `3022` is the remote SSH port, which is 3022 for Nodes running the Teleport
|
|
SSH service.
|
|
|
|
You can also refer to Machine ID's generated `ssh_config` for a proxy usage
|
|
example.
|
|
|
|
### `tbot proxy db` for database access
|
|
|
|
This opens a local proxy server to the given database. Your database client
|
|
must still be configured with client TLS certificates
|
|
|
|
```code
|
|
$ tbot proxy --destination-dir=./tbot-user --proxy=proxy.example.com:3080 db --port=1234 example
|
|
```
|
|
|
|
In this case:
|
|
- `example` is the name of the database server as it exists in Teleport
|
|
- `1234` is an arbitrary port on which to run the proxy
|
|
|
|
Though not recommended, to avoid the need for additional client authentication,
|
|
the `--tunnel` flag may be used to perform authentication at the local proxy
|
|
rather than within your client:
|
|
|
|
```code
|
|
$ tbot proxy --destination-dir=./tbot-user --proxy=proxy.example.com:3080 db --tunnel --port=1234 example
|
|
```
|
|
|
|
Note that this decreases security:
|
|
- It allows any user on the system to access the database via `localhost`.
|
|
- Your connection to the database will be unencrypted until it reaches the
|
|
`tbot` proxy running on `localhost`.
|
|
|
|
Refer to the [database guide](../guides/databases.mdx) for more information on
|
|
using database proxies.
|