From 78e6eb71a256f3eb42ec95e9299d6e7b3dd33339 Mon Sep 17 00:00:00 2001 From: Jesse Luehrs Date: Wed, 23 Oct 2019 03:22:43 -0400 Subject: config file documentation --- README.md | 107 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 107 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index c9866c7..51b9436 100644 --- a/README.md +++ b/README.md @@ -80,6 +80,113 @@ session to a file at once by running `tt stream tt record`. You can play back previously recorded ttyrec files by using `tt play`. +## Configuration + +Besides command line flags (which have documentation available via `tt help`), +`teleterm` also optionally reads configuration from a configuration file. This +file should be in [TOML](https://en.wikipedia.org/wiki/TOML) format, and stored +either in `~/.config/teleterm/config.toml` or `/etc/teleterm/config.toml`. If a +configuration file does not exist, `tt stream` and `tt watch` will offer to +create one for you automatically. The configuration has several sections: + +### `[server]` (used by `tt server`) + +* `listen_address` + * Local address for the server to listen on, in the format `HOST:PORT`. + * Default: `127.0.0.1:4144` +* `buffer_size` + * Maximum size of the per-connection buffer to maintain, which will be sent + when a new client connects (in order to be able to fully redraw the + current terminal state). + * Default: `4194304` +* `read_timeout` + * Amount of time in seconds to wait without receiving data from a client + before disconnecting that client. Note that besides sending data on + terminal output, clients also send a heartbeat message every 30 seconds + in order to keep the connection alive. + * Default: `120` +* `tls_identity_file` + * If this option is specified, the server will use TLS to encrypt incoming + connections (and clients connecting to this server must enable the `tls` + client option). The value of this option should be the path to a file + containing the TLS private key along with a certificate chain up to a + trusted root, in PKCS #12 format. This file can be generated from an + existing private key and cert chain using a command like this: + ``` + openssl pkcs12 -export -out identity.pfx -inkey key.pem -in cert.pem -certfile chain_certs.pem + ``` + * Default: unset (the server will accept plaintext TCP connections) +* `allowed_login_methods` + * List of login methods to allow from incoming connections. Must be + non-empty. Valid login methods are: + * `plain`: The client supplies a username, which the server uses + directly. Allows impersonation, but can be fine if that's not an + issue for you. + * `recurse_center`: The client authenticates via the + [Recurse Center](https://www.recurse.com/)'s OAuth flow, and + retrieves the user's name from the Recurse Center API. + * Default: `["plain", "recurse_center"]` +* `uid` + * If set and the server is run as `root`, the server will switch to this + username or uid after binding to a port and reading the TLS key. This + allows you to use a low-numbered port or a `root`-owned TLS key without + requiring the server itself to handle connection requests as `root`. + * Default: unset +* `gid` + * Same as `uid`, except sets the user's primary group. + * Default: unset + +### `[oauth.]` (used by `tt server`) + +`` corresponds to an OAuth-using login method - for instance, a section +would be named something like `[oauth.recurse_center]`. Note that OAuth login +methods are required to use `http://localhost:44141` as their redirect URL. + +* `client_id` + * OAuth client id. +* `client_secret` + * OAuth client secret. + +### `[client]` (used by `tt stream` and `tt watch`) + +* `auth` + * Login method to use (must be one of the methods that the server has been + configured to accept). + * Default: `plain` +* `username` + * If using the `plain` login method, the username to log in as. + * Default: the local username that the `tt` process is running under + (fetched from the `$USER` environment variable) +* `connect_address` + * Address to connect to, in `HOST:PORT` form. Note that when connecting to + a TLS-using server, the `HOST` component must correspond to a name on the + TLS certificate used by the server. + * Default: `127.0.0.1:4144` +* `tls` + * Whether to connect to the server using TLS. + * Default: `false` + +### `[command]` (used by `tt stream` and `tt record`) + +* `buffer_size` + * Maximum size of the buffer to maintain, which will be sent to the server + when reconnecting after a connection drops (in order to be able to fully + redraw the current terminal state). + * Default: `4194304` +* `command` + * Command to execute. + * Default: the currently running shell (fetched from the `$SHELL` + environment variable) +* `args` + * List of arguments to pass to `command`. + * Default: `[]` + +### `[ttyrec]` (used by `tt record` and `tt play`) + +* `filename` + * Name of the TTYrec file to save to or read from. + * Default: `teleterm.ttyrec` + ## Contributing I'm very interested in contributions! I have a list of todo items in this -- cgit v1.2.3-54-g00ecf