teleport CLI Reference
The CLI tool that supports the Teleport Access Platform is called teleport, and allows Teleport services to be managed
over the command line:
The primary commands for the teleport CLI are as follows:
| Command | Description |
|---|---|
teleport app start | Starts the Teleport Application Service. |
teleport configure | Generates and writes a configuration YAML file for the Teleport service. This file should be customized in production to suit the needs of your environment, and the default output should only be used when testing. |
teleport db configure aws create-iam | Generates, creates, and attaches desired IAM policies to a Teleport-managed database. |
teleport db configure aws print-iam | Generates and outputs current IAM policies for a Teleport-managed database. |
teleport db configure bootstrap | Used to bootstrap a configuration to the Teleport Database Service by reading a provided configuration. |
teleport db configure create | Generates a configuration YAML file for the Database Service. This file should be customized in production to suit the needs of your environment, and the default output should only be used when testing. |
teleport db start | Starts the Teleport Database Service. |
teleport help | Outputs guidance for using Teleport commands. |
teleport install systemd | Creates a systemd unit file, used to configure and install a teleport service daemon. |
teleport join openssh | Registers an OpenSSH server with Teleport. |
teleport node configure | Generates a configuration YAML file for a Teleport Node accessed via SSH. This file should be customized in production to suit the needs of your environment, and the default output should only be used when testing. |
teleport start | Starts the teleport process in the foreground using the current shell session, including any services configured by the configuration YAML file. |
teleport status | Prints the status of the current active Teleport SSH session. |
teleport version | Prints the current release version of the Teleport binary installed on your system. |
teleport debug set-log-level | Changes instance log level. |
teleport debug get-log-level | Fetches instance current log level. |
teleport debug debug profile | Export the application profiles (pprof format). |
tip
For more information on subcommands when working with the teleport cli, use the --help option or teleport <subcommand> --help.
teleport start
The teleport start command includes a large number of optional configuration flags.
While configuration flags for teleport start can be used to set parameters for Teleport's configuration,
we recommend using a configuration file in production.
Flags
| Name | Default Value(s) | Allowed Value(s) | Description |
|---|---|---|---|
-d, --debug | none | none | enable verbose logging to stderr |
--insecure-no-tls | false | true or false | Tells proxy to not generate default self-signed TLS certificates. This is useful when running Teleport on kubernetes (behind reverse proxy) or behind things like AWS ELBs, GCP LBs or Azure Load Balancers where SSL termination is provided externally. |
-r, --roles | proxy, node, auth | string comma-separated list of proxy, node, auth, db, or app | start listed services/roles. These roles are explained in the Core Concepts document. |
--pid-file | none | string filepath | create a PID file at the path |
--advertise-ip | none | string IP | advertise IP to clients, often used behind NAT |
-l, --listen-ip | 0.0.0.0 | net. IP | binds services to IP |
--auth-server | none | string IP | proxy attempts to connect to a specified auth server instead of local auth, disables --roles=auth if set |
--token | none | string | set invitation token to register with an auth server on start, used once and ignored afterwards. Obtain it by running tctl nodes add on the auth server.We recommend to use tools like pwgen to generate sufficiently random tokens of 32+ byte length. |
--ca-pin | none | string sha256:<hash> | set CA pin to validate the Auth Server. Generated by tctl status |
--nodename | value returned by the hostname command on the machine | string | assigns an alternative name for the node which can be used by clients to log in. |
-c, --config | /etc/teleport.yaml | string .yaml filepath | starts services with config specified in the YAML file, overrides CLI flags if set |
--apply-on-startup | none | string .yaml filepath | On startup, always apply resources described in the file at the given path. Only supports the following kinds: token, role, user, cluster-auth-preference, cluster-networking-config. |
--bootstrap | none | string .yaml filepath | bootstrap configured YAML resources |
--labels | none | string comma-separated list | assigns a set of labels to a node, for example env=dev,app=web. See the explanation of labeling mechanism in the Labeling Nodes section. |
--insecure | none | none | disable certificate validation on Proxy Service, validation still occurs on Auth Service. |
--fips | none | none | start Teleport in FedRAMP/FIPS 140-2 mode. |
--skip-version-check | false | true or false | Skips version checks between the Auth Server this Teleport instance |
--diag-addr | none | none | Enable diagnostic endpoints |
--permit-user-env | none | none | flag reads in environment variables from ~/.tsh/environment when creating a session. |
--app-name | none | none | Name of the application to start |
--app-uri | none | none | Internal address of the application to proxy |
--app-public-addr | none | none | Public address fo the application to proxy |
teleport start --roles
The --roles flag when used with teleport --start instructs Teleport on which specific Teleport services to start. Below is a more cohesive table of roles and their associated services that teleport start supports:
| Service | Role Name | Description |
|---|---|---|
| Node | node | Allows SSH connections from authenticated clients. |
| Auth | auth | Authenticates and authorizes hosts and users who want access to Teleport-managed resources or information about a cluster. |
| Proxy | proxy | The gateway that clients use to connect to the Auth Service or resources managed by Teleport. |
| App | app | Provides access to applications. |
| Database | db | Provides access to databases. |
tip
Teleport Cloud manages Teleport instances with the auth and proxy roles. Use
the remaining roles to manage access to specific resources and other Teleport
clusters.
Examples
# By default without any configuration, teleport starts running as a single-node
# cluster. It's the equivalent of running with --roles=node,proxy,auth
sudo teleport start
# Starts a node named 'db' running in strictly SSH mode role, joining the cluster
# serviced by the auth server running on 10.1.0.1
sudo teleport start --roles=node --auth-server=10.1.0.1 --token=xyz --nodename=db
# Same as the above, but the node runs with db=master label and can be connected
# to using that label in addition to its name.
sudo teleport start --roles=node --auth-server=10.1.0.1 --labels=db=master
# Starts an app server that proxies the application "example-app" running at http://localhost:8080.
sudo teleport start --roles=app --token=xyz --auth-server=proxy.example.com:3080 \
--app-name="example-app" \
--app-uri="http://localhost:8080" \
--labels=group=dev