Add README for API

USTC-vlab · Aug 12, 2024 · fd16ad1 · fd16ad1
1 parent a3892f0
commit fd16ad1
Showing 1 changed file with 38 additions and 9 deletions.
diff --git a/README.md b/README.md
@@ -29,12 +29,41 @@ The table below shows the available options for `sshmux`:
 
 The table below shows extra options for `sshmux`, mainly for authentication with Vlab backends:
 
-| Key                        | Type       | Description                                                      | Example                      |
-|----------------------------|------------|------------------------------------------------------------------|------------------------------|
-| `token`                    | `string`   | Token used to authenticate with the recovery backend.            | `"long-and-random-token"`    |
-| `recovery-server`          | `string`   | SSH host and port of the recovery server.                        | `"172.30.0.101:2222"`        |
-| `recovery-username`        | `[]string` | Usernames dedicated to the recovery server.                      | `["recovery", "console"]`    |
-| `all-username-nopassword`  | `bool`     | If set to `true`, all users will not be asked for UNIX password. | `true`                       |
-| `username-nopassword`      | `[]string` | Usernames that won't be asked for UNIX password.                 | `["vlab", "ubuntu", "root"]` |
-| `invalid-username`         | `[]string` | Usernames that are known to be invalid.                          | `["user"]`                   |
-| `invalid-username-message` | `string`   | Message to display when the requested username is invalid.       | `"Invalid username %s."`     |
+| Key                        | Type       | Description                                                 | Example                      |
+|----------------------------|------------|-------------------------------------------------------------|------------------------------|
+| `token`                    | `string`   | Token used to authenticate with the recovery backend.       | `"long-and-random-token"`    |
+| `recovery-server`          | `string`   | SSH host and port of the recovery server.                   | `"172.30.0.101:2222"`        |
+| `recovery-username`        | `[]string` | Usernames dedicated to the recovery server.                 | `["recovery", "console"]`    |
+| `all-username-nopassword`  | `bool`     | If set to `true`, no users will be asked for UNIX password. | `true`                       |
+| `username-nopassword`      | `[]string` | Usernames that won't be asked for UNIX password.            | `["vlab", "ubuntu", "root"]` |
+| `invalid-username`         | `[]string` | Usernames that are known to be invalid.                     | `["user"]`                   |
+| `invalid-username-message` | `string`   | Message to display when the requested username is invalid.  | `"Invalid username %s."`     |
+
+All of these options can be left empty or unset, if the corresponding feature is not intended to be used.
+
+## API server
+
+`sshmux` requires an API server to perform authentication and authorization for a user.
+
+The API accepts JSON input with the following keys:
+
+| Key               | Type     | Description                                                                                            |
+|-------------------|----------|--------------------------------------------------------------------------------------------------------|
+| `auth_type`       | `string` | The authentication type. Always set to `"key"` at the moment.                                          |
+| `username`        | `string` | Vlab username. Unset if the user is authenticating with public key.                                    |
+| `password`        | `string` | Vlab password. Unset if the user is authenticating with public key.                                    |
+| `unix_username`   | `string` | UNIX username the user is requesting access to.                                                        |
+| `public_key_type` | `string` | SSH public key type. Unset if the user is authenticating with username and password.                   |
+| `public_key_data` | `string` | Base64-encoded SSH public key payload. Unset if the user is authenticating with username and password. |
+| `token`           | `string` | Token used to authenticate with the recovery backend.                                                  |
+
+The API responds with JSON output with the following keys:
+
+| Key              | Type      | Description                                                                                                          |
+|------------------|-----------|----------------------------------------------------------------------------------------------------------------------|
+| `status`         | `string`  | The authentication status. Should be `"ok"` if the user is authorized.                                               |
+| `address`        | `string`  | TCP host and port of the downstream SSH server the user is requesting for.                                           |
+| `private_key`    | `string`  | SSH private key to authenticate for the downstream.                                                                  |
+| `cert`           | `string`  | The certificate associated with the SSH private key.                                                                 |
+| `vmid`           | `integer` | ID of the requested VM. Only used for recovery access.                                                               |
+| `proxy_protocol` | `integer` | PROXY protocol version to use for the downstream. Should be `1`, `2` or null values (which disables PROXY protocol). |