diff --git a/Backends.md b/Backends.md new file mode 100644 index 0000000..f33a69f --- /dev/null +++ b/Backends.md @@ -0,0 +1,94 @@ +## `docker` + +The Docker backend integrates with a docker daemon running on your system to provide shell access into containers. + +### Settings + +- **command** (optional, []string): The command to run inside the container. Default is `["/bin/sh"]`. +- **privileged** (optional, bool): If `true`, the command will run in privileged mode. Default is `false`. +- **user** (optional, string): The user to run the command as inside the container. + +### Permissions + +The docker backend exposes container names to the permissions system. For example, if you wanted to allow `group1` access to all containers beginning with `g1`, you could do: + +```hcl +permissions = { + group1 = { + allow = ["g1*"] + } +} +``` + +## `nomad` + +The Nomad backend integrates with a [Nomad](https://nomadproject.io) server to provide shell access into Nomad allocations. + +### Settings + +- **server** (string): The Nomad server address. +- **delimiter** (optional, string): The delimiter used for the Seashell argument . Default is `"."`. +- **region** (optional, string): The Nomad region. +- **namespace** (optional, string): The Nomad namespace. +- **auth_token** (optional, string): The authentication token for Nomad. +- **command** (optional, []string): The command to run within the Nomad allocation. Default is `["/bin/sh"]`. + +### Permissions + +The nomad backend exposes job, task, and task group names to the permissions system. For example, if you wanted to allow `group1` to access the `hello-world` job and the `hello` task group, but not the `hello1` task within that task group, you could do: + +```hcl +permissions = { + group1 = { + allow = ["job:hello-world", "group:hello"] + deny = ["task:hello1"] + } +} +``` + +## `serial` + +The Serial backend provides shell access over serial connections. + +### Settings + +- **directory** (optional, string): The directory where serial files are located (e.g. `/dev`). Either **directory** or **file** must be provided. +- **file** (optional, string): The specific serial file to use. This setting overrides **directory**. +- **delimiter** (optional, string): The delimiter used for the Seashell argument . Default is `"."`. +- **baud_rate** (optional, int): The baud rate for the serial connection. If this is not set, the user will have to provide the baud rate in their `ssh` command. +- **config** (optional, string): The mode string for the serial connection (e.g. `8n1`). If this is not set, the user will have to provide the mode string in their `ssh` command. + +### Permissions + +If the **directory** setting is used, the serial backend will expose filenames to the permissions system. For example, to only allow `group1` access to `ttyUSB0`, you could use: + +```hcl +permissions = { + group1 = { + allow = ["ttyUSB0"] + } +} +``` + +## `proxy` + +The Proxy backend allows SSH connections to be proxied through another server. + +### Settings + +- **server** (string): The target server's address. +- **user** (optional, string): The user to connect as on the proxy server. If this is not set, **userMap** will be used to determine the right user, or the seashell username will be used if the user doesn't exist in the map. +- **privkey** (optional, string): The path to the private key for authentication. If this is not provided, users will be asked for the target server's password when they attempt to connect. +- **userMap** (optional, map[string]string): A map from seashell usernames to target server usernames. + +### Permissions + +The proxy backend doesn't expose any items to the permissions system. You can allow or deny access to the entire route using a wildcard: + +```hcl +permissions = { + admins = { + allow = ["*"] + } +} +``` \ No newline at end of file