config file documentation

1 files changed, 107 insertions, 0 deletions

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.<method>]` (used by `tt server`)
+
+`<method>` 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