diff --git a/Configuration.md b/Configuration.md new file mode 100644 index 0000000..505e7de --- /dev/null +++ b/Configuration.md @@ -0,0 +1,113 @@ +## Settings + +The `settings` block contains settings for the SSH server itself. + +### Fields + +- `ssh_dir` (optional, string): Directory where SSH keys are stored. Default is `~/.ssh`. +- `listen_addr` (optional, string): Address on which the SSH server listens. Default is `:2222`. +- `debug` (optional, bool): Enables or disables debug logging. Default is `false`. + +### Example +```hcl +settings { + ssh_dir = "/home/user/.ssh" + listen_addr = "0.0.0.0:22" + debug = true +} +``` + +## Route + +The `route` block represents a virtual host configuration. + +### Fields + +- `name` (label, string): The name of the virtual host. +- `backend` (string): The backend to use for the route (e.g., `docker`, `serial`). +- `match` (string): The regular expression to match for routing. The first capture group in the regular expression will be passed to the backend as the argument. If there's a named capture group with the name `arg`, that will be used as the argument instead. If there are no capture groups, the whole routing path will be used as the argument. +- `settings` (object): Additional settings for the backend. These are different for each backend. +- `permissions` (optional, object): Permissions map for the route. If this is missing, all users will be allowed to access all resources. + +### Example +```hcl +route "example" { + backend = "docker" + match = "docker\\.(.+)" + settings = { + command = ["/bin/bash"] + } + permissions = { + admins = { + allow = ["*"] + } + group1 = { + allow = ["container1", "container2"] + deny = ["container3", "admin_container*"] + } + } +} +``` + +## Auth + +The `auth` block contains the authentication settings. + +### Fields + +- [`fail2ban`](#fail2ban) (block): Fail2Ban rate limiter settings. +- [`user`](#user) (block, multiple): List of virtual users. + +### Example +```hcl +auth { + fail2ban { + limit = "10m" + attempts = 5 + } + + user "user1" { + password = "$argon2id..." + groups = ["admins"] + pubkeys = ["ssh-ed25519 AAA..."] + } +} +``` + +## Fail2Ban + +The `fail2ban` block contains the Fail2Ban rate limiter settings. + +### Fields + +- `limit` (string): Time interval (e.g., `1h2m3s`). +- `attempts` (int): Number of allowed attempts before banning. + +### Example +```hcl +# Allows 5 failed login attempts per 10 minute interval +fail2ban { + limit = "10m" + attempts = 5 +} +``` + +## User + +The `user` block contains the configuration for a virtual user. + +### Fields + +- `name` (label, string): The username. +- `password` (optional, string): The argon2id hash of the user's password (can be generated using `seashell --gen-hash`). +- `groups` (optional, []string): The groups to which the user belongs. +- `pubkeys` (optional, []string): Public keys for the user. + +### Example +```hcl +user "admin" { + password = "$argon2id..." + groups = ["admins"] + pubkeys = ["ssh-ed25519 AAA..."] +} +``` \ No newline at end of file