mirror of
https://github.com/clusterio/clusterio.git
synced 2026-11-17 15:33:12 +09:00
Replace host tokens with host pairing
Hosts join the cluster by running the installer, which shows a code and waits until the request is approved under Hosts > Add host in the web interface or with clusterioctl host approve. An admin can pass their user token to the installer to approve the host right away. The token is only used for that and is not saved. The controller only accepts hosts that have a record, and only approving a host creates one. Revoking a host deletes its record, so its token can no longer be used to reconnect. Hosts that have connected before keep working. Removes host generate-token, revoke-token and create-config from clusterioctl, bootstrap generate-host-token, the host token messages and the core.host.generate_token, revoke_token and create_config permissions, which are also stripped from stored roles. Adds clusterioctl host pending, approve, reject and revoke, and the core.host.approve and core.host.revoke permissions. Standalone installs add the host to the controller database directly, since the controller is not running during the install.
This commit is contained in:
49 files changed
+4855
-473
No files matched your search
@@ -93,7 +93,7 @@ Defaults to null meaning the header is never trusted.
|
||||
### controller.public_url
|
||||
|
||||
Public address the controller is accessible on.
|
||||
Used as the URL in configs generated with `clusteriocontroller bootstrap create-ctl-config` and `clusterioctl host create-config`, and by plugins like Player Auth that need to show the address of the web interface in-game.
|
||||
Used as the URL in configs generated with `clusteriocontroller bootstrap create-ctl-config`, and by plugins like Player Auth that need to show the address of the web interface in-game.
|
||||
This should be a full URL ending with a /.
|
||||
|
||||
Defaults to null meaning assume localhost.
|
||||
@@ -277,6 +277,7 @@ Defaults to 1000.
|
||||
|
||||
Whether the `controller update` command in clusterioctl and the update button in the web interface are allowed to update the `@clusterio/controller` package with npm.
|
||||
For security reasons this can only be changed locally with `clusteriocontroller config set` while the controller is stopped, and it is hidden in the web interface.
|
||||
The installer sets this, controller.allow_plugin_updates and controller.allow_plugin_install from one question about remote updates and plugin installs.
|
||||
See [Managing a Cluster](/docs/managing-a-cluster.md) for details on remote updates.
|
||||
|
||||
Defaults to true.
|
||||
@@ -326,6 +327,7 @@ Defaults to "New Host".
|
||||
### host.id
|
||||
|
||||
Immutable numeric id of the host which uniquely identifies this host in the cluster.
|
||||
The controller picks the id when the host is approved and the installer writes it here, the controller does not accept hosts with an id it has not approved.
|
||||
Hidden in the web interface.
|
||||
|
||||
Defaults to a random 31 bit number.
|
||||
@@ -365,7 +367,8 @@ Defaults to "http://localhost:8080/".
|
||||
### host.controller_token
|
||||
|
||||
Access token used for authenticating with the controller.
|
||||
You can generate an access token with `clusterioctl host generate-token --id <host-id>`, or use the `clusterioctl host create-config` to create a new host config with the correct url and token in it.
|
||||
The installer writes it together with host.id when the host is approved, see [Setting up remote hosts](/README.md#setting-up-remote-hosts).
|
||||
The token only works while the host exists on the controller, if the host is revoked run the installer again in the host directory to get it approved again.
|
||||
The value can only be read and changed from the host itself.
|
||||
|
||||
Defaults to "enter token here".
|
||||
@@ -418,6 +421,7 @@ Defaults to 60.
|
||||
|
||||
Whether the `host update` command in clusterioctl and the update button in the web interface are allowed to update the `@clusterio/host` package with npm.
|
||||
For security reasons this can only be changed locally with `clusteriohost config set` while the host is stopped, and it is hidden in the web interface.
|
||||
The installer sets this, host.allow_plugin_updates and host.allow_plugin_install from one question about remote updates and plugin installs.
|
||||
See [Managing a Cluster](/docs/managing-a-cluster.md) for details on remote updates.
|
||||
|
||||
Defaults to true.
|
||||
|
||||
@@ -59,3 +59,23 @@ Imports of `assert`, `buffer`, `events`, `os`, `path`, `process`, `stream`, `uti
|
||||
The `container` property of `WebPluginContext` is now the plugin's ES module namespace, `await container.get("./web")` returns the module instead of a factory function.
|
||||
|
||||
`lib.PluginWebpackEnvInfo` is renamed to `lib.PluginWebEnvInfo`.
|
||||
|
||||
|
||||
## Host pairing
|
||||
|
||||
Host tokens are no longer generated by users.
|
||||
A host joins the cluster by running the installer and having the code it shows approved, see [Host pairing](protocol.md#host-pairing) for the HTTP endpoints it uses.
|
||||
|
||||
- `HostGenerateTokenRequest` and `HostConfigCreateRequest` are removed.
|
||||
Pending requests are listed with `HostPairingListRequest`, approved with `HostPairingApproveRequest` and rejected with `HostPairingRejectRequest`, and changes to them are sent to subscribers of `HostPairingUpdatesEvent`.
|
||||
- `HostRevokeTokensRequest` is replaced by `HostRevokeRequest`, which deletes the host instead of only invalidating its tokens.
|
||||
It throws `ConflictError` while instances are assigned to the host.
|
||||
- The permissions `core.host.generate_token`, `core.host.revoke_token` and `core.host.create_config` are removed.
|
||||
Check `core.host.approve` and `core.host.revoke` instead.
|
||||
- `clusteriocontroller bootstrap generate-host-token` is removed, scripts that set up hosts should run the installer with `--controller-token` to approve the host with a user token.
|
||||
|
||||
Host records are no longer created when a host connects, only by approving it, and the controller rejects hosts it has no record of.
|
||||
Revoking a host deletes its record and note.
|
||||
Plugins that keep data per host should remove it when the host is deleted.
|
||||
On the controller the `update` event of `controller.hosts` gives the record with `isDeleted` set to true, and subscribers of `HostUpdatesEvent` receive the host with `isDeleted` set to true.
|
||||
A host that is revoked and installed again gets a new id.
|
||||
@@ -32,6 +32,63 @@ The [send-buffer setting](../configuration.md#controllermax_send_buffer_size) co
|
||||

|
||||
|
||||
|
||||
## Host pairing
|
||||
|
||||
The host id and token sent in `registerHost` come from the installer, which gets them from the controller over HTTP before the host is started.
|
||||
Hosts are only added to the controller by approving a pairing request, and `registerHost` is rejected with close code 3000 (Unauthorized) for a host id the controller has no record of.
|
||||
Revoking a host deletes its record, so its token stops working and the installer has to pair it again, which gives it a new id.
|
||||
See [Setting up remote hosts](/README.md#setting-up-remote-hosts) for how this looks to the user.
|
||||
|
||||
The endpoints below take and return JSON bodies and are sent with `Cache-Control: no-store`.
|
||||
The `POST` endpoints return errors as `{"error": "<message>"}` and respond with 503 while the controller is in recovery mode.
|
||||
A request body that is not valid JSON or is larger than 4 kB is rejected with 400 or 413 before it reaches the endpoint, without a JSON body.
|
||||
`GET /api/host-pairing/check` also works in recovery mode, and responds to a token that is not valid with a plain 401 without a JSON body.
|
||||
A user or host token is sent in either an `Authorization: Bearer <token>` header or an `X-Access-Token` header.
|
||||
|
||||
### `POST /api/host-pairing`
|
||||
|
||||
Creates a request for a host to join the cluster.
|
||||
|
||||
- `name: string` - Name of the host, at most 100 characters after trimming whitespace, without control characters.
|
||||
- `version: string` (optional) - Version of the installer.
|
||||
|
||||
Responds with 202 and `{"requestId": string, "code": string}`.
|
||||
The `code` is shown to the user to approve the request with, formatted as six characters like `ABC-DEF`.
|
||||
Codes are matched ignoring case and anything that is not a letter or digit, so `abcdef` matches `ABC-DEF`.
|
||||
The `requestId` is a secret used to poll for the result, it is never shown to users.
|
||||
|
||||
If a user token is sent and the user has the `core.host.approve` permission the host is created right away and the response is 200 with the same body as an approved poll.
|
||||
An invalid token gives 401 and a user without the permission gives 403, a token is never ignored to create a pending request instead.
|
||||
|
||||
A missing or too long name gives 400.
|
||||
Too many requests from the same address or in total gives 429 with a `Retry-After` header in seconds.
|
||||
|
||||
### `POST /api/host-pairing/poll`
|
||||
|
||||
- `requestId: string` - Id returned when the request was created.
|
||||
|
||||
Responds with 202 and `{"status": "pending"}` while the request is waiting for approval.
|
||||
Once approved it responds with 200 and `{"hostId": integer, "token": string, "name": string}`, where `name` is the name the host was approved with, which can differ from the one asked for.
|
||||
Rejected requests give 403, and unknown or expired requests give 404.
|
||||
The result of an approved or rejected request is only returned once, after which the request is gone.
|
||||
|
||||
A pending request expires 30 seconds after it was last polled, and after an hour of waiting.
|
||||
The installer polls every 2 seconds.
|
||||
|
||||
### `POST /api/host-pairing/cancel`
|
||||
|
||||
- `requestId: string` - Id returned when the request was created.
|
||||
|
||||
Removes a pending request, sent by the installer when it stops waiting.
|
||||
Responds with 204 whether or not the request existed.
|
||||
|
||||
### `GET /api/host-pairing/check`
|
||||
|
||||
Checks a host token.
|
||||
Responds with 200 and `{"valid": true}` if the token is valid and the host it was issued to still exists, and with 401 otherwise.
|
||||
The installer uses this to tell whether an existing host config still works when it is run again.
|
||||
|
||||
|
||||
## Connector flow
|
||||
|
||||
To manage the complexity of connecting, reconnecting, resuming or invalidating dropped sessions the WebSocket connection for a `Link` class is managed by a connector.
|
||||
@@ -119,6 +176,10 @@ Host handshake for establishing a new connection session.
|
||||
- `plugins: Object<string, string>` -
|
||||
Object mapping plugin names to plugin version for plugins that are available on the host.
|
||||
|
||||
The controller closes the connection with code 3000 (Unauthorized) if the token is invalid, was issued for another id, or if there is no host with this id, see [Host pairing](#host-pairing).
|
||||
If this happens when the host starts it exits with code 8, and the run scripts created by the installer do not restart it.
|
||||
A host that is revoked while connected is disconnected, is rejected when it tries to connect again, and shuts down.
|
||||
|
||||
#### `registerControl`
|
||||
|
||||
Control handshake for enstablishing a new connection session.
|
||||
|
||||
@@ -16,17 +16,40 @@ The easiest way to do this is to run `npx clusteriocontroller bootstrap create-c
|
||||
|
||||
Lists all hosts.
|
||||
|
||||
### Generate token
|
||||
Hosts are added to the cluster by running the installer on the computer the host runs on and approving the code it shows, see [Setting up remote hosts](/README.md#setting-up-remote-hosts).
|
||||
Listing, approving and rejecting installers waiting for approval needs the `core.host.approve` permission.
|
||||
|
||||
ctl> host generate-token [--id <host id>]
|
||||
### List pending hosts
|
||||
|
||||
Generate a token for a host. `--id` is the host id.
|
||||
ctl> host pending
|
||||
|
||||
### Create config
|
||||
Lists installers waiting for approval with the code they show, the name they asked for, the address they connected from and how long they have been waiting.
|
||||
A request goes away when its installer stops waiting, and after waiting for an hour.
|
||||
|
||||
ctl> host create-config [--id <host id>] [--name <host name>] [--generate-token <bool>] [--output <path to output>]
|
||||
### Approve host
|
||||
|
||||
Create a host config. `--id` id the host id. `--name` is the host name. `--generate-token` decides whether to also generate a token, defaulting to `0`. `--output` is the filename for the output of the config; Default is "config-host.json", "-" for stdout.
|
||||
ctl> host approve <code> [--name <host name>]
|
||||
|
||||
Approves the installer showing the code and prints the id of the new host.
|
||||
The code is not case sensitive and the dash can be left out.
|
||||
`--name` gives the host a different name than the one entered in the installer.
|
||||
Approving gives the host full access to the cluster, check with `host pending` that the name and address match the computer you are setting up.
|
||||
|
||||
### Reject host
|
||||
|
||||
ctl> host reject <code>
|
||||
|
||||
Rejects the installer showing the code, the installer then exits with an error.
|
||||
|
||||
### Revoke host
|
||||
|
||||
ctl> host revoke <host>
|
||||
|
||||
Specify the host by name or ID.
|
||||
Removes the host from the cluster, disconnects it and makes its token stop working.
|
||||
Instances assigned to the host have to be unassigned first.
|
||||
Requires the `core.host.revoke` permission.
|
||||
To add the computer back to the cluster, run the installer again in the directory the host is installed in.
|
||||
|
||||
### Update Clusterio
|
||||
|
||||
@@ -270,9 +293,11 @@ To be written.
|
||||
|
||||
## Plugins (Remote)
|
||||
|
||||
By default, remote updates are enabled unless you selected "no" during installation.
|
||||
Remote updates allow ctl and the web UI to update plugins on machines within the cluster.
|
||||
However, remote installations are disabled by default to prevent the risk of arbitrary code execution through the installation of malicious npm packages onto the machine. See below if you wish to enable this feature.
|
||||
The installer asks "Allow remote updates and plugin installs from the web interface?" and the answer sets `allow_remote_updates`, `allow_plugin_updates` and `allow_plugin_install` together on that machine, pass `--remote-npm` or `--no-remote-npm` to answer it from the command line.
|
||||
Remote updates allow ctl and the web UI to update Clusterio and plugins on machines within the cluster.
|
||||
Remote installs allow them to install any package from npm onto the machine, which is a risk of arbitrary code execution through malicious npm packages, so only allow them if you trust everyone with access to install plugins.
|
||||
In a config created without the installer remote updates are enabled and remote installs are disabled by default.
|
||||
See below for changing these settings after installing.
|
||||
|
||||
### List
|
||||
|
||||
|
||||
@@ -63,7 +63,7 @@ This creates a private key file named `key.pem` and a public certificate file na
|
||||
npx clusteriocontroller config set controller.tls_certificate cert.pem
|
||||
npx clusteriocontroller config set controller.tls_private_key key.pem
|
||||
|
||||
Additionally you will need copy the `cert.pem` file to all of the computers you want to set up as hosts and configure node to trust it by setting the `NODE_EXTRA_CA_CERTS` environment variable to a path to this file before the host is started. You can do this by passing `--self-signed-cert path/to/cert` to the installer when setting up a host, or manually by editing run-host.cmd, run-host.sh and/or clusteriohost.service by adding the following line next to the one setting `NODE_OPTIONS`:
|
||||
Additionally you will need copy the `cert.pem` file to all of the computers you want to set up as hosts and configure node to trust it by setting the `NODE_EXTRA_CA_CERTS` environment variable to a path to this file before the host is started. You can do this by passing `--self-signed-cert path/to/cert` to the installer when setting up a host, which also makes the installer trust the certificate when it asks the controller to approve the host, or manually by editing run-host.cmd, run-host.sh and/or clusteriohost.service by adding the following line next to the one setting `NODE_OPTIONS`:
|
||||
|
||||
**For run-host.cmd**
|
||||
|
||||
|
||||
Reference in new issue
Block a user