From 2a7a333b95acf8e46ecd5c05d57e8046a747a2e6 Mon Sep 17 00:00:00 2001 From: bbassie <17990055+bbassie@users.noreply.github.com> Date: Sun, 22 Nov 2026 00:00:06 +0000 Subject: [PATCH 1/5] Rename managing-a-cluster.md to clusterioctl.md The document is a reference for the clusterioctl commands. The name is freed up for a guide to managing a cluster. Part of #1254 Co-Authored-By: Claude Opus 5.5 --- docs/{managing-a-cluster.md => clusterioctl.md} | 2 +- docs/configuration.md | 6 +++--- packages/ctl/README.md | 6 +++--- 3 files changed, 7 insertions(+), 7 deletions(-) rename docs/{managing-a-cluster.md => clusterioctl.md} (99%) diff --git a/docs/managing-a-cluster.md b/docs/clusterioctl.md similarity index 99% rename from docs/managing-a-cluster.md rename to docs/clusterioctl.md index 2cd6508b..fce1dd95 100644 --- a/docs/managing-a-cluster.md +++ b/docs/clusterioctl.md @@ -1,4 +1,4 @@ -# Managing a Cluster +# Clusterioctl Clusterio clusters are managed through the controller by using the `clusterioctl` command line interface which is invoked by running `npx clusterioctl ` in the clusterio directory. This document uses the shorthand `ctl> foo` to indicate `npx clusterioctl foo` should be executed. diff --git a/docs/configuration.md b/docs/configuration.md index 90465063..31978e1e 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,7 +1,7 @@ # Configuration Config values are changed with the `config set` commands of clusterioctl, clusteriocontroller and clusteriohost, or from the settings pages in the web interface. -See [Managing a Cluster](/docs/managing-a-cluster.md) for the commands. +See [Clusterioctl](/docs/clusterioctl.md) for the commands. All values are checked against the type of the field when set. Some fields have additional rules on top of that, such as a number having to be greater than 0, and these are listed under the field. @@ -322,7 +322,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. +See [Plugins (Remote)](/docs/clusterioctl.md#plugins-remote) for details on remote updates. Defaults to true. @@ -477,7 +477,7 @@ Defaults to 30. 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. +See [Plugins (Remote)](/docs/clusterioctl.md#plugins-remote) for details on remote updates. Defaults to true. diff --git a/packages/ctl/README.md b/packages/ctl/README.md index cf9fc7be..23060170 100644 --- a/packages/ctl/README.md +++ b/packages/ctl/README.md @@ -3,7 +3,7 @@ Provides a command line interface for managing a Clusterio cluster. -Note that this document only describes the options and commands for managing clusterioctl itself, see [Managing a cluster](/docs/managing-a-cluster.md) for the available commands used for managing a cluster. +Note that this document only describes the options and commands for managing clusterioctl itself, see [Clusterioctl](/docs/clusterioctl.md) for the available commands used for managing a cluster. ## Usage @@ -25,7 +25,7 @@ Common options: * `--output ` Format to print the results of cluster commands in. Defaults to `human`. - See [Output format](/docs/managing-a-cluster.md#output-format) for what `json` and `wire` print. + See [Output format](/docs/clusterioctl.md#output-format) for what `json` and `wire` print. The `plugin` and `config` commands described below always print human readable text. @@ -112,6 +112,6 @@ Lists up all configuration entries with their currently configured values. ## See Also -[Managing a cluster](/docs/managing-a-cluster.md) for the available commands used for managing a cluster. +[Clusterioctl](/docs/clusterioctl.md) for the available commands used for managing a cluster. [The Clusterio repository](https://github.com/clusterio/clusterio) for instructions on how to set up a cluster. From fb93962972c835e2520e5cdd913b646a67b48e7a Mon Sep 17 00:00:00 2001 From: bbassie <17990055+bbassie@users.noreply.github.com> Date: Sun, 22 Nov 2026 00:00:06 +0000 Subject: [PATCH 2/5] Document clusterioctl setup and the missing commands Adds a setup section covering the installer, create-ctl-config, a hand-made config and self-signed certificates. Documents the commands that were missing or marked "To be written": controller and host stop, restart and config, instance start, restart, stop, start-all, stop-all, load-scenario, delete, send-rcon and export-data, saves, config set-prop, mods, mod packs, user show and revoke-token, roles, permissions and logs. Part of #1254 Co-Authored-By: Claude Opus 5.5 --- docs/clusterioctl.md | 442 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 435 insertions(+), 7 deletions(-) diff --git a/docs/clusterioctl.md b/docs/clusterioctl.md index fce1dd95..59746aa1 100644 --- a/docs/clusterioctl.md +++ b/docs/clusterioctl.md @@ -1,11 +1,46 @@ # Clusterioctl -Clusterio clusters are managed through the controller by using the `clusterioctl` command line interface which is invoked by running `npx clusterioctl ` in the clusterio directory. +Clusterio clusters can be managed from the command line with `clusterioctl`, which is invoked by running `npx clusterioctl ` in the clusterio directory. +It connects to the controller the same way the web interface does, and what it is allowed to do depends on the roles of the user it logs in as. +See [Managing a Cluster](managing-a-cluster.md) for a guide to the day to day tasks. This document uses the shorthand `ctl> foo` to indicate `npx clusterioctl foo` should be executed. Mandatory parameters are shown in `` and optional pameters are in `[square brackets]`. +Hosts, instances, roles and mod packs can be given by name or by ID. -Before `clusterioctl` can be used it needs to be configured for the cluster it will connect to. -The easiest way to do this is to run `npx clusteriocontroller bootstrap create-ctl-config ` on the controller, which creates the necessary `config-ctl.json` for managing the cluster as the given user. +Run `npx clusterioctl --help` for the list of commands and `npx clusterioctl --help` for the options of a command. +Plugins may add their own commands, these are documented in the plugin's README. + + +## Setting up + +clusterioctl is installed separately from the controller and host. +Run the installer as described in the [README](/README.md#installation) and choose "Ctl only" as the operating mode, either in the same directory as the controller or on another computer. +The installer asks for the controller URL and an authentication token, these are the same as you would use to log in to the web interface, and saves them to `config-ctl.json`. + +When clusterioctl is installed in the same directory as the controller, `npx clusteriocontroller bootstrap create-ctl-config ` writes `config-ctl.json` for managing the cluster as the given user. +The config created this way connects to `localhost`, so it only works on the controller computer. + +To set it up by hand, generate a token for the user on the controller: + + npx clusteriocontroller bootstrap generate-user-token + +Then create the config and set the URL and token on the computer you run clusterioctl on: + + npx clusterioctl config create + npx clusterioctl config set ctl.controller_url https://example.com/ + npx clusterioctl config set ctl.controller_token + +The `config` command works offline and is described in the [readme for @clusterio/ctl](/packages/ctl/README.md), along with the other command line options. +See [Ctl Configuration](configuration.md#ctl-configuration) for the available settings. + +The token logs in as the user it was generated for and gives the same access as that user's roles. +Anyone holding it can manage the cluster as that user, so keep `config-ctl.json` private. +A token stops working when it is revoked with [`user revoke-token`](#revoke-user-token). + +If the controller uses a self-signed certificate, Node.js has to be told to trust it before clusterioctl can connect, see [Setting up TLS](setting-up-tls.md#creating-and-using-a-self-signed-certificate). +For example on Linux: + + NODE_EXTRA_CA_CERTS=path/to/cert.pem npx clusterioctl instance list ## Output Format @@ -26,6 +61,56 @@ The `json` format uses the property names shown in the tables of the human forma The default is `--output human`, which prints `Command ran successfully` for commands that have no result. +## Controller + +### Stop controller + + ctl> controller stop + +Stops the controller. +The run scripts and systemd services created by the installer do not start it again. + +### Restart controller + + ctl> controller restart + +Restarts the controller. +This only works if the controller was started with `run --can-restart`, which the run scripts and systemd services created by the installer do, otherwise the request is refused. +It is also refused while a plugin install or update is running. + +### Controller config + +The controller config can be changed while the controller runs, unlike `npx clusteriocontroller config set` which must only be used while it is stopped. +See [Controller Configuration](configuration.md#controller-configuration) for the available fields. + +#### List controller config + + ctl> controller config list + +Lists the config of the controller. + +#### Set controller config value + + ctl> controller config set [value] [--stdin] + +Sets a field in the controller config. +If `value` is left out the field is cleared, `--stdin` reads the value from stdin instead. +Some fields, like `controller.allow_remote_updates`, can not be changed remotely and have to be set on the controller computer while it is stopped. + +#### Set controller config property + + ctl> controller config set-prop [value] [--stdin] + +Sets one property of an object field in the controller config, see [Set config property of field](#set-config-property-of-field). + +#### Edit controller config + + ctl> controller config edit [editor] + +Opens the controller config in a text editor and applies the changed values once the editor exits. +If `editor` is not given the `EDITOR` or `VISUAL` environment variable is used. + + ## Hosts ### List hosts @@ -69,6 +154,52 @@ Instances assigned to the host become unassigned, their files stay on the comput Requires the `core.host.revoke` permission. To add the computer back to the cluster, start the host again and approve it. +### Stop host + + ctl> host stop + +Stops the host and the instances running on it. +The run scripts and systemd services created by the installer do not start it again, it has to be started on the computer it runs on. + +### Restart host + + ctl> host restart + +Restarts the host. +Like the controller, this only works if the host was started with `run --can-restart`. + +### Host config + +The config of a connected host can be changed from clusterioctl. +See [Host Configuration](configuration.md#host-configuration) for the available fields. + +#### List host config + + ctl> host config list + +Lists the config of the host given by name or ID. + +#### Set host config value + + ctl> host config set [value] [--stdin] + +Sets a field in the host config. +If `value` is left out the field is cleared, `--stdin` reads the value from stdin instead. +Some fields, like `host.allow_remote_updates`, can not be changed remotely and have to be set on the host computer while it is stopped. + +#### Set host config property + + ctl> host config set-prop [value] [--stdin] + +Sets one property of an object field in the host config, see [Set config property of field](#set-config-property-of-field). + +#### Edit host config + + ctl> host config edit [editor] + +Opens the host config in a text editor and applies the changed values once the editor exits. +If `editor` is not given the `EDITOR` or `VISUAL` environment variable is used. + ### Update Clusterio ctl> host update [--all] [--restart] @@ -108,6 +239,71 @@ Templates are only listed if `--templates` is passed. Create a new instance. `name` is the instance name. `--id` is the optional id. `--from` copies the config of an existing instance. `--template` makes the new instance inherit all config values from the given template. `--as-template` creates the instance as a template, see `instance.is_template` in the [configuration docs](configuration.md). Use `--as-template --from ` to make a template out of an existing instance. +### Delete instance + + ctl> instance delete + +Deletes the instance and all its files, including saves, from the host it is assigned to. +The instance must be stopped, and can not be deleted while it is the template of other instances. + +### Start instance + + ctl> instance start [--save ] [--keep-open] + +Starts the instance, which must be assigned to a host. +Loads the given save, or the most recently modified save if `--save` is not passed. +`--keep-open` keeps clusterioctl running and prints the log of the instance until it is stopped with Ctrl+C. + +### Restart instance + + ctl> instance restart [--save ] [--keep-open] + +Stops the instance if it is running and starts it again, takes the same options as `start`. + +### Load scenario + + ctl> instance load-scenario [--seed ] [--map-exchange-string ] [--map-gen-settings ] [--map-settings ] [--keep-open] + +Starts the instance with a new game from the given scenario, for example `base/freeplay`. +This only works with save patching turned off for the instance with `factorio.enable_save_patching`, see [Save Patching](how-it-works.md#save-patching). +`--map-exchange-string` sets the map generation from a map exchange string copied from Factorio. +`--map-gen-settings` and `--map-settings` take paths to the JSON files Factorio uses for these, and `--seed` overrides the seed in them. + +### Stop instance + + ctl> instance stop + +Saves the game and stops the instance. + +### Start all instances + + ctl> instance start-all [--force] + +Starts every stopped instance that is assigned to a host. +Instances with `instance.exclude_from_start_all` set are skipped unless `--force` is passed. + +### Stop all instances + + ctl> instance stop-all + +Stops every running instance. + +### Send RCON command + + ctl> instance send-rcon + +Sends a command to the Factorio server of a running instance and prints the reply, for example `ctl> instance send-rcon "My World" /players`. +Quote the command if it contains spaces. + +### Export data + + ctl> instance export-data + +Exports the item icons, names and mod settings from Factorio for the mod pack the instance uses, and uploads them to the controller. +The instance must be stopped. +The web interface needs this data to show icons and names of items, and to show the settings of the mods in a mod pack. +See [Exporting data](managing-a-cluster.md#exporting-data) for when to run it. + ### Kill instance ctl> instance kill @@ -149,7 +345,15 @@ Set field in instance config. `instance` is instance to set. `field` is field to #### Set config property of field -To be written. + ctl> instance config set-prop [value] [--stdin] + +Set one property of an object field, like `factorio.settings`, without replacing the rest of the object. +`value` is parsed as JSON if it can be, otherwise it is used as a string. +If `value` is left out the property is removed. +For example, to set the max player count and remove the game password: + + ctl> instance config set-prop "My World" factorio.settings max_players 16 + ctl> instance config set-prop "My World" factorio.settings game_password #### Inherit config value @@ -169,6 +373,62 @@ Edit instance config in a text editor. Once file is saved and editor has been ex Assigns instance to host. `instance` is instance to assign, `host` is host to assign to. If `host` is not provided, instance will be unassigned. +### Saves + +Saves are stored on the host the instance is assigned to. +The commands below need the instance to be assigned, and the host to be connected. + +#### List saves + + ctl> instance save list + +Lists the saves of the instance. +`loadByDefault` marks the save that is loaded when the instance is started without `--save`. + +#### Create save + + ctl> instance save create [name] [--seed ] [--map-exchange-string ] [--map-gen-settings ] [--map-settings ] + +Creates a new save with a freshly generated map without starting the server. +The name defaults to `world.zip`. +The map options work the same as for [load-scenario](#load-scenario). + +#### Upload save + + ctl> instance save upload [--name ] + +Uploads a save from this computer to the instance. +`--name` gives it a different name on the host, the name must end with `.zip`. +If a save with the same name exists the upload is stored under a new name. + +#### Download save + + ctl> instance save download + +Downloads a save from the instance to the current directory. + +#### Rename save + + ctl> instance save rename + +#### Copy save + + ctl> instance save copy + +Copies a save within the same instance. + +#### Transfer save + + ctl> instance save transfer [target-save] [--copy] + +Moves a save to another instance, which can be on a different host. +`--copy` leaves the original in place. +If a save with the target name exists the transferred save is stored under a new name, which is printed. + +#### Delete save + + ctl> instance save delete + ## Users Clusterio automatically creates user accounts for all players that join an instance when save patching is enabled. @@ -176,9 +436,17 @@ These accounts are used to store per player data shared between instances, like ### List users - ctl> user list + ctl> user list [--attributes] [--stats] Lists all user accounts in the cluster along with some data for each. +`--attributes` adds the admin, whitelisted and banned status, and `--stats` adds online time and join counts. + +### Show user + + ctl> user show [--instance-stats] + +Shows the account data of one user. +`--instance-stats` adds the online time and join count for each instance. ### Create User @@ -271,6 +539,14 @@ Calling with an empty roles argument will remove all roles from the user. By default there's a roled named Cluster Admin which grants access to everything and a role named Player which grants a limited read access to the cluster, see [the section on roles](#roles) for more information about setting up roles and permissions. +### Revoke user token + + ctl> user revoke-token + +Makes every authentication token issued to the user stop working, including the one used by the web interface and clusterioctl. +The user has to log in again, or be given a new token with `npx clusteriocontroller bootstrap generate-user-token `. +Revoking the token of another user needs the `core.user.revoke_other_token` permission. + ### Delete user ctl> user delete @@ -284,7 +560,139 @@ Note: If the player joins the cluster again a new account will be made for them ## Roles -To be written. +Access to manage the cluster is granted through roles. +A role is a named set of permissions, and a user has the permissions of all the roles they have. +By default there are two roles: Cluster Admin, which has the `core.admin` permission that grants everything, and Player, which can view most of the cluster but not change it. +New users get the Player role, this is set by `controller.default_role_id`. +Use [`user set-roles`](#set-cluster-roles) to give roles to a user. + +### List roles + + ctl> role list + +Lists the roles with their ID, description and permissions. + +### Create role + + ctl> role create [--description ] [--permissions ]... + +Creates a new role and prints its ID. +Pass `--permissions` once for each permission the role should grant, for example: + + ctl> role create "Instance Operator" --permissions core.instance.start --permissions core.instance.stop + +### Edit role + + ctl> role edit [--name ] [--description ] [--set-perms ] [--add-perms ] [--remove-perms ] [--grant-default] + +Changes the name, description or permissions of a role. +`--set-perms` replaces the permissions of the role, `--add-perms` and `--remove-perms` change them, and these take several permissions separated by spaces. +`--grant-default` adds the permissions shown as granted by default in [`permission list`](#list-permissions), which are the ones the Player role starts with. + +### Delete role + + ctl> role delete + +Deletes the role, users that had it lose the permissions it granted. + + +## Permissions + +### List permissions + + ctl> permission list + +Lists all permissions with their name, title, description and whether they are granted by default. +Plugins can add their own permissions, these show up here when the plugin is loaded on the controller. + + +## Mods + +Mods are stored on the controller and sent to hosts when an instance needs them. + +### List mods + + ctl> mod list [--fields ] + +Lists the mods stored on the controller. +`--fields` picks the columns to show, `--fields all` shows every field. + +### Search mods + + ctl> mod search [query] [--page ] [--page-size ] [--sort ] [--sort-order asc|desc] [--fields ] + +Searches the mods stored on the controller that work with the given major version of Factorio, for example `2.0`. +This does not search the Factorio Mod Portal, use the Mods page of the web interface for that. + +### Show mod + + ctl> mod show + +Shows the details of a stored mod. + +### Upload mod + + ctl> mod upload + +Uploads a mod zip file to the controller. + +### Download mod + + ctl> mod download + +Downloads a stored mod to the current directory. + +### Delete mod + + ctl> mod delete + +Deletes a stored mod from the controller. + + +## Mod Packs + +A mod pack is a list of mods with their versions and mod settings, see [Mod packs](managing-a-cluster.md#mod-packs). + +### List mod packs + + ctl> mod-pack list + +### Show mod pack + + ctl> mod-pack show + +Shows the mods and settings of a mod pack. + +### Create mod pack + + ctl> mod-pack create [--description ] [--mods ] [--disabled-mods ] [--bool-setting ] ... + +Creates a mod pack for the given version of Factorio and prints its ID. +The built in mods of Factorio, like `base` and `space-age`, are added automatically with only `base` enabled. +Mods are given as `name:version`, and optionally `name:version:sha1`. +`--disabled-mods` takes the names of mods from `--mods` that should be in the pack but not enabled. +Mod settings are set with `--bool-setting`, `--int-setting`, `--double-setting`, `--string-setting` and `--color-setting`, which each take a scope, a setting name and a value. +The scope is one of `startup`, `runtime-global` or `runtime-per-user`, and a color is given as JSON like `{"r":1,"g":0,"b":0,"a":1}`. + +### Edit mod pack + + ctl> mod-pack edit [--name ] [--description ] [--factorio-version ] [--add-mods ] [--enable-mods ] [--disable-mods ] [--remove-mods ] [---setting ] [--remove-setting ] + +Changes a mod pack, the options work the same as for `create`. +`--add-mods` also replaces the version of a mod already in the pack. +Mods are not checked against the mods stored on the controller, make sure the mods you add have been uploaded. + +### Export and import mod packs + + ctl> mod-pack export + ctl> mod-pack import + +`export` prints the mod pack as a string, and `import` creates a new mod pack from such a string. +This is the same string as the Import string button and the Export to string action in the web interface use. + +### Delete mod pack + + ctl> mod-pack delete ## Notes @@ -319,9 +727,29 @@ Removes the note of a resource. Notes are also removed when the resource they are attached to is deleted. +## Logs + +### Query log + + ctl> log query [--all] [--controller] [--host ] [--instance ] [--max-level ] [--limit ] [--start] + +Prints entries from the cluster log stored on the controller. +At least one of `--all`, `--controller`, `--host` and `--instance` must be passed to pick which logs to read. +`--max-level` leaves out entries less important than the given level, for example `warn`. +Prints the last 1000 entries by default, `--limit` changes the number and `--start` takes them from the start of the log instead. + +### Follow log + + ctl> log follow [--all] [--controller] [--host ] [--instance ] + +Prints new log entries as they come in until stopped with Ctrl+C. +Takes the same options for picking logs as `query`. + + ## Plugins (Local) -To be written. +The plugins loaded by clusterioctl are managed with the `plugin` command, which works without a connection to the controller. +See the [readme for @clusterio/ctl](/packages/ctl/README.md#plugin-command). ## Plugins (Remote) From 3c035741060c0d30a3df03ae5eb67f78f38dbc77 Mon Sep 17 00:00:00 2001 From: bbassie <17990055+bbassie@users.noreply.github.com> Date: Sun, 22 Nov 2026 00:00:06 +0000 Subject: [PATCH 3/5] Add a guide for managing a cluster docs/managing-a-cluster.md goes through the day to day tasks in the web interface: logging in, hosts, instances, saves, mod packs, users and roles, plugins and logs, each linking to the matching ctl commands. It explains the data export needed for item icons, names and mod settings, including that a host with only the headless build exports no base game icons. The mod section of the README moves into the guide so there is one copy of it, and the README points to the guide and the ctl docs. Part of #1254 Co-Authored-By: Claude Opus 5.5 --- README.md | 28 ++---- docs/managing-a-cluster.md | 194 +++++++++++++++++++++++++++++++++++++ 2 files changed, 201 insertions(+), 21 deletions(-) create mode 100644 docs/managing-a-cluster.md diff --git a/README.md b/README.md index 57a9f85d..e91618f9 100644 --- a/README.md +++ b/README.md @@ -223,21 +223,9 @@ See the [readme for @clusterio/controller](/packages/controller/README.md) for m ## Managing Factorio mods -Mods in Clusterio are managed as parts of mod packs. -On the Mods page of the web interface, use **Search** to browse the Factorio Mod Portal and download mods to the controller, or upload mod zip files directly. -Mod Portal downloads require the controller's [Factorio account credentials](docs/configuration.md#controllerfactorio_username) to be configured. -Use **Create** in the Mod Packs section to create a mod pack, then add the mods you want to use. -Assign the mod pack to an instance under Instance config -> Factorio -> Mod pack, or set a default mod pack for new instances in the controller settings. - -![Select mod pack for instance](docs/assets/config_select_mod_pack.png) - -Mod settings can be managed under the modpack configuration page in the web UI. For mod settings to show, you first need to run an export. This is done by creating an instance with the modpack assigned, opening the instance page and pressing More -> Export data. - -![Export mod configuration data](docs/assets/export_mod_config_data.png) - -Once this is done, the mod settings will show up under the modpack configuration page. - -![Mod settings configuration in web interface](docs/assets/mod_settings_configuration.png) +Mods in Clusterio are managed as parts of mod packs, which are set up on the Mods page of the web interface and assigned to instances. +See [Mod Packs](docs/managing-a-cluster.md#mod-packs) in the Managing a Cluster guide. +To see item icons and names and to edit mod settings in the web interface, data has to be exported from Factorio first, see [Exporting data](docs/managing-a-cluster.md#exporting-data). ## Setting up shared storage @@ -258,6 +246,7 @@ Once the controller process is running you can log into the web interface which The first time a host starts it prints a link for approving it, open the link and click Approve. The basics of setting up a Factorio server from the web interface is to create an instance, assign it to a host and then click start. You can also use the "Connect via Steam" button to launch Factorio directly and connect to the server using Steam's protocol handler. +See [Managing a Cluster](docs/managing-a-cluster.md) for a guide to the day to day tasks, like managing saves and mod packs and giving other users access. ### Running via Systemd @@ -298,12 +287,9 @@ To add the computer back to the cluster start the host again, it asks for approv ## Setting up clusterioctl -There's a command line interface available for Clusterio which is installed separately with the same installer as for the controller and host. -Run the installer as described in the installation section and choose "Ctl only" as the operating mode to install, you can do this in the same directory as you have installed other Clusterio component(s) to. -The installer will ask for a controller URL and an authentication token, these are the same as you would use to connect to the web interface. -If you want to use a different user for the command line interface, you can generate an authentication token for an existing user with - - npx clusteriocontroller bootstrap generate-user-token +There's a command line interface available for Clusterio called clusterioctl. +It is installed separately with the same installer as for the controller and host, by choosing "Ctl only" as the operating mode, you can do this in the same directory as you have installed other Clusterio component(s) to. +See [Clusterioctl](docs/clusterioctl.md#setting-up) for how to set it up and the commands it has. ## Known Issues diff --git a/docs/managing-a-cluster.md b/docs/managing-a-cluster.md new file mode 100644 index 00000000..c75abeec --- /dev/null +++ b/docs/managing-a-cluster.md @@ -0,0 +1,194 @@ +# Managing a Cluster + +This guide goes through the day to day tasks of running a cluster from the web interface. +It assumes Clusterio is installed and running, see the [README](/README.md#installation) for how to get there. +Each section ends with the clusterioctl commands for the same task, see [Clusterioctl](clusterioctl.md) for the details of these. + + +## Logging in + +The web interface is hosted by the controller, by default on port 8080. +Log in with an authentication token, the installer prints one for the admin account it creates. +Other users can log in by joining one of the Factorio servers in the cluster if the [Player Auth](/plugins/player_auth/README.md) plugin is installed. +Otherwise a token for a user can be generated on the controller computer with + + npx clusteriocontroller bootstrap generate-user-token + +A token gives full access to the account it is for until it is revoked with the Revoke token button on the page of the user. + +What a user can see and do in the web interface depends on their roles, see [Users and Permissions](#users-and-permissions). + + +## Hosts + +A host is a computer that runs Factorio servers for the cluster. +See [Setting up remote hosts](/README.md#setting-up-remote-hosts) for how to add one. + +The Hosts page lists the hosts with their CPU, memory and disk usage. +The page of a host shows the instances assigned to it, its log and its config. +From there it can be restarted, updated, or removed from the cluster with Revoke host access. + +ctl: [Hosts](clusterioctl.md#hosts). + + +## Instances + +An instance is a Factorio server along with its config and saves. +Instances are assigned to a host, which is where the server runs and the saves are stored. + +### Creating an instance + +Click Create on the Instances page and give the instance a name. +Leave Start after creation unticked for now, as the instance needs a host before it can start. +Then open the instance and assign it to a host with the Assign button. + +The instance uses the default mod pack set on the Controller page, which is the base game of the newest Factorio version unless changed. +To use a different one pick it under Config -> Factorio -> Mod pack on the instance page, see [Mod Packs](#mod-packs) for setting them up. + +ctl: [Create instance](clusterioctl.md#create-instance), [Assign instance to host](clusterioctl.md#assign-instance-to-host). + +### Starting and stopping + +Click Start on the instance page. +The instance loads the save that was modified last, or creates a new map if it has no saves. +To load a different save, click it in the saves list and use Load save, see [Saves](#saves). +Players connect to the address shown under Public address, or with the Connect via Steam button. + +Stop saves the game and shuts the server down. +Start all and Stop all on the Instances page do the same for every instance, start all skips instances with `instance.exclude_from_start_all` set. + +An instance can be started automatically when its host starts with `instance.auto_start`, and restarted after a crash with `instance.restart_after_crash`. + +ctl: [Start instance](clusterioctl.md#start-instance), [Stop instance](clusterioctl.md#stop-instance), [Start all instances](clusterioctl.md#start-all-instances). + +### Changing settings + +The Config section at the bottom of the instance page holds the instance settings. +The server name, description, password, player limit and other options from Factorio's server-settings.json are under Factorio -> Settings. +Most of these, like the name, password and player limit, are applied to a running server right away. +See [Instance Configuration](configuration.md#instance-configuration) for every setting. + +To share settings between instances, make one instance into a template with Create template and create the other instances from it. +Instances created from a template take every setting they don't set themselves from it, and follow changes made to the template. + +ctl: [Config management](clusterioctl.md#config-management). + +### Running commands + +The Console section on the instance page shows the log of the instance, and commands typed into it are sent to the Factorio server. +This works like the in-game console with admin rights, so `/c` runs Lua and disables achievements. + +ctl: [Send RCON command](clusterioctl.md#send-rcon-command). + + +## Saves + +The saves list on the instance page shows the saves stored on the host for that instance. +Click a save to show the actions for it. +Load save starts the instance with that save, and Download, Rename, Copy and Delete do what they say. +Transfer moves or copies the save to another instance, which can be on a different host. + +New saves can be made with Create save, which generates a new map, optionally from a seed or a map exchange string. +Saves can also be uploaded with Upload save or by dropping a save file onto the list. + +Several saves can be selected at once with the checkboxes to download, transfer or delete them together. + +The `_autosave` saves are written by Factorio. +Loading one starts the instance from a copy of it, so the autosave isn't overwritten. + +ctl: [Saves](clusterioctl.md#saves). + + +## Mod Packs + +Mods in Clusterio are managed as parts of mod packs. +A mod pack is a list of mods with their versions, and the mod settings to use with them. +Every instance uses one mod pack, and hosts download the mods in it from the controller when the instance starts. + +On the Mods page, use Search to browse the Factorio Mod Portal and download mods to the controller, or upload mod zip files with Upload. +Mod Portal downloads require the controller's [Factorio account credentials](configuration.md#controllerfactorio_username) to be configured. + +Use Create in the Mod Packs section to create a mod pack, then add the mods you want to use. +Assign the mod pack to an instance under Instance config -> Factorio -> Mod pack, or set a default mod pack for new instances on the Controller page. + +![Select mod pack for instance](assets/config_select_mod_pack.png) + +Mod settings are changed on the page of the mod pack. +The settings only show up after data has been exported for the mod pack, see the next section. + +![Mod settings configuration in web interface](assets/mod_settings_configuration.png) + +Mod packs can be shared between clusters with Export to string on the mod pack page and Import string on the Mods page. + +ctl: [Mods](clusterioctl.md#mods), [Mod Packs](clusterioctl.md#mod-packs). + +### Exporting data + +The web interface does not know the names and icons of items, or which settings mods have, until they have been exported from Factorio. +Until then items are shown by their internal name without an icon, and the mod pack page has no settings to edit. +This affects every page that shows items, including the plugin pages of Subspace Storage and Player Sync, which use the export of the default mod pack. + +To export the data, assign the mod pack to an instance, stop the instance, and click More -> Export data on the instance page. +The export belongs to the mod pack the instance uses, so do this once for each mod pack. +Run it again after adding or updating mods in the pack. + +![Export mod configuration data](assets/export_mod_config_data.png) + +The icons of the base game are read from the Factorio install on the host. +The headless build of Factorio has no graphics, so on a host that only has the headless build the export has the names but none of the base game icons, and the host logs a warning about it. +To get the icons, put a full install of the same Factorio version into the `host.factorio_directory` of the host, or export from a host that has one. +Icons from mods are read from the mod files and are exported either way. + +The Icon reference link under Inspect exported data on the mod pack page shows everything in the export. + +ctl: [Export data](clusterioctl.md#export-data). + + +## Users and Permissions + +### Players + +Clusterio creates a user account for every player that joins an instance with save patching enabled. +The Users page lists them with their online time. +The page of a user shows their stats per instance, and has switches for making them an in-game admin, whitelisting them, and banning them. +These lists are shared between all instances that have `factorio.sync_adminlist`, `factorio.sync_whitelist` and `factorio.sync_banlist` turned on, which they are by default. +The whitelist is only enforced on instances with `factorio.enable_whitelist` turned on. + +Existing Factorio admin, ban and whitelist files can be imported with Bulk Actions on the Users page, which can also export them. + +ctl: [Users](clusterioctl.md#users). + +### Granting access to the cluster + +Being an in-game admin does not give any access to manage the cluster. +Access to the web interface and clusterioctl is controlled by roles, which are sets of permissions. +There are two roles by default: Cluster Admin, which can do everything, and Player, which can view most of the cluster but not change anything. +New users get the Player role. + +To let someone manage part of the cluster, create a role on the Roles page and tick the permissions it should grant. +For example, a role for starting and stopping servers needs `core.instance.start` and `core.instance.stop`, along with the permissions the Player role has for viewing instances. +Then add the role to the user under Roles on the page of the user. +Use the Cluster Admin role for people who should have full control. + +The user can then log in as described in [Logging in](#logging-in). + +ctl: [Roles](clusterioctl.md#roles), [Set Cluster Roles](clusterioctl.md#set-cluster-roles). + + +## Plugins and Updates + +The Plugins page lists the plugins installed on the controller and each host, with their versions. +If remote updates are enabled, Clusterio and plugins installed from npm can be updated from here, and the Controller and host pages have an Update Clusterio button. +Browse plugins searches npm for plugins, installing them from the web interface needs remote installs to be enabled on the computer. +Installs and updates take effect after a restart, the Plugins page shows which computers are waiting for one. +See [Plugins (Remote)](clusterioctl.md#plugins-remote) for turning remote updates and installs on or off. + +Plugins can also be installed on the computer itself, see [Installing Plugins](/README.md#installing-plugins). + + +## Logs + +The Controller page shows the log of the controller, the page of a host the log of that host, and the instance page the log of the instance and its Factorio server. +The log files are stored in the `logs` folder of the controller and are kept for `controller.log_retention_days` days. + +ctl: [Logs](clusterioctl.md#logs). From af97b1b789ed91800d3a975baa16f686cbb1107c Mon Sep 17 00:00:00 2001 From: bbassie <17990055+bbassie@users.noreply.github.com> Date: Sun, 22 Nov 2026 00:39:47 +0000 Subject: [PATCH 4/5] Address review of the cluster management docs - Explain the host field and Start after creation in the create modal - Mention Restart and listing in the in-game server browser - Say where the Factorio credentials come from and what sharing them with hosts means - Explain that built in mods can be disabled but not removed - Accounts are created for joining players with or without save patching, the host falls back to reading joins from the server log - Roles only need permissions on top of Player, and warn about dangerous permissions and role self-assignment - clusterioctl can live in any directory on any computer, and the web interface can download its config Co-Authored-By: Claude Opus 5.5 --- docs/clusterioctl.md | 12 ++++++++---- docs/managing-a-cluster.md | 23 ++++++++++++++++++++--- 2 files changed, 28 insertions(+), 7 deletions(-) diff --git a/docs/clusterioctl.md b/docs/clusterioctl.md index 59746aa1..990149b4 100644 --- a/docs/clusterioctl.md +++ b/docs/clusterioctl.md @@ -1,6 +1,6 @@ # Clusterioctl -Clusterio clusters can be managed from the command line with `clusterioctl`, which is invoked by running `npx clusterioctl ` in the clusterio directory. +Clusterio clusters can be managed from the command line with `clusterioctl`, which is invoked by running `npx clusterioctl ` in the directory it was installed in. It connects to the controller the same way the web interface does, and what it is allowed to do depends on the roles of the user it logs in as. See [Managing a Cluster](managing-a-cluster.md) for a guide to the day to day tasks. This document uses the shorthand `ctl> foo` to indicate `npx clusterioctl foo` should be executed. @@ -14,12 +14,16 @@ Plugins may add their own commands, these are documented in the plugin's README. ## Setting up clusterioctl is installed separately from the controller and host. -Run the installer as described in the [README](/README.md#installation) and choose "Ctl only" as the operating mode, either in the same directory as the controller or on another computer. +It only needs to reach the controller over the network, so it can be installed on any computer, in any directory, including next to a controller or host. +Run the installer as described in the [README](/README.md#installation) in the directory you want it in and choose "Ctl only" as the operating mode. The installer asks for the controller URL and an authentication token, these are the same as you would use to log in to the web interface, and saves them to `config-ctl.json`. When clusterioctl is installed in the same directory as the controller, `npx clusteriocontroller bootstrap create-ctl-config ` writes `config-ctl.json` for managing the cluster as the given user. The config created this way connects to `localhost`, so it only works on the controller computer. +The web interface can also make this file, click your user name in the top right of the page and pick Ctl Config. +This downloads a `config-ctl.json` for your account that connects to the same address as the web interface, place it in the directory clusterioctl is installed in. + To set it up by hand, generate a token for the user on the controller: npx clusteriocontroller bootstrap generate-user-token @@ -431,7 +435,7 @@ If a save with the target name exists the transferred save is stored under a new ## Users -Clusterio automatically creates user accounts for all players that join an instance when save patching is enabled. +Clusterio automatically creates user accounts for all players that join an instance. These accounts are used to store per player data shared between instances, like if the player should be whitelisted, admin or banned. ### List users @@ -455,7 +459,7 @@ Shows the account data of one user. Creates a new empty user account for the given Factorio player. Note that case matters here. -This is usually not required as user accounts are created automatically for players that join instances with save patching enabled. +This is usually not required as user accounts are created automatically for players that join instances. ### Promote User to Server Admin diff --git a/docs/managing-a-cluster.md b/docs/managing-a-cluster.md index c75abeec..1572d5f5 100644 --- a/docs/managing-a-cluster.md +++ b/docs/managing-a-cluster.md @@ -39,7 +39,8 @@ Instances are assigned to a host, which is where the server runs and the saves a ### Creating an instance Click Create on the Instances page and give the instance a name. -Leave Start after creation unticked for now, as the instance needs a host before it can start. +The Host field assigns it to a host straight away, and once a host is picked the Start after creation box starts the instance as soon as it is created. +In this example leave the host unassigned and the box unticked, so the instance can be set up before it starts. Then open the instance and assign it to a host with the Assign button. The instance uses the default mod pack set on the Controller page, which is the base game of the newest Factorio version unless changed. @@ -53,8 +54,11 @@ Click Start on the instance page. The instance loads the save that was modified last, or creates a new map if it has no saves. To load a different save, click it in the saves list and use Load save, see [Saves](#saves). Players connect to the address shown under Public address, or with the Connect via Steam button. +If Factorio credentials are available to the instance and it is set to public, which it is by default, it is also listed in the in-game server browser. +Credentials are taken from the controller, see [Mod Packs](#mod-packs), or set on the host or the instance. Stop saves the game and shuts the server down. +Restart, in the menu next to Stop, stops the instance and starts it again with the latest save. Start all and Stop all on the Instances page do the same for every instance, start all skips instances with `instance.exclude_from_start_all` set. An instance can be started automatically when its host starts with `instance.auto_start`, and restarted after a crash with `instance.restart_after_crash`. @@ -107,8 +111,14 @@ Every instance uses one mod pack, and hosts download the mods in it from the con On the Mods page, use Search to browse the Factorio Mod Portal and download mods to the controller, or upload mod zip files with Upload. Mod Portal downloads require the controller's [Factorio account credentials](configuration.md#controllerfactorio_username) to be configured. +The username and token are on your profile page on factorio.com, use the token there and not your password. +By default the controller also sends these credentials to the hosts, which put them in the server settings of every instance they start. +This is needed for instances to be listed in the in-game server browser, but it means anyone with access to a host computer can read the token. +Turn off `controller.share_factorio_credentials_with_hosts` if you don't trust the hosts with it. Use Create in the Mod Packs section to create a mod pack, then add the mods you want to use. +The built in mods of Factorio, like `space-age`, `quality` and `elevated-rails`, are part of every mod pack for a Factorio version that has them. +They can't be removed, but they can be disabled, and only `base` is enabled in a new mod pack. Assign the mod pack to an instance under Instance config -> Factorio -> Mod pack, or set a default mod pack for new instances on the Controller page. ![Select mod pack for instance](assets/config_select_mod_pack.png) @@ -148,7 +158,7 @@ ctl: [Export data](clusterioctl.md#export-data). ### Players -Clusterio creates a user account for every player that joins an instance with save patching enabled. +Clusterio creates a user account for every player that joins an instance. The Users page lists them with their online time. The page of a user shows their stats per instance, and has switches for making them an in-game admin, whitelisting them, and banning them. These lists are shared between all instances that have `factorio.sync_adminlist`, `factorio.sync_whitelist` and `factorio.sync_banlist` turned on, which they are by default. @@ -166,10 +176,17 @@ There are two roles by default: Cluster Admin, which can do everything, and Play New users get the Player role. To let someone manage part of the cluster, create a role on the Roles page and tick the permissions it should grant. -For example, a role for starting and stopping servers needs `core.instance.start` and `core.instance.stop`, along with the permissions the Player role has for viewing instances. +Every user keeps the Player role, so a new role only needs the permissions on top of it. +For example, a role for starting and stopping servers needs only `core.instance.start` and `core.instance.stop`. Then add the role to the user under Roles on the page of the user. Use the Cluster Admin role for people who should have full control. +Be careful with what a role grants, some permissions give much more control than their name suggests. +The Roles page marks the permissions that stop, kill, delete, revoke or update things as dangerous. +For example `core.controller.stop` and `core.host.stop` shut down Clusterio on that computer, and it can only be started again by someone with access to the computer. +`core.user.update_roles` and `core.role.update` are not marked, but they are as powerful as Cluster Admin. +Setting roles has no restrictions, so a user who can do it can give themselves the Cluster Admin role. + The user can then log in as described in [Logging in](#logging-in). ctl: [Roles](clusterioctl.md#roles), [Set Cluster Roles](clusterioctl.md#set-cluster-roles). From 834f8472dfd44f65ce36c52abfcbefe27ad5d6cb Mon Sep 17 00:00:00 2001 From: Cooldude2606 <25043174+Cooldude2606@users.noreply.github.com> Date: Sun, 22 Nov 2026 01:00:13 +0000 Subject: [PATCH 5/5] Clarify role permission warnings in documentation Rephrase warnings about role permissions for clarity. --- docs/managing-a-cluster.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/managing-a-cluster.md b/docs/managing-a-cluster.md index 1572d5f5..e79859d7 100644 --- a/docs/managing-a-cluster.md +++ b/docs/managing-a-cluster.md @@ -181,11 +181,10 @@ For example, a role for starting and stopping servers needs only `core.instance. Then add the role to the user under Roles on the page of the user. Use the Cluster Admin role for people who should have full control. -Be careful with what a role grants, some permissions give much more control than their name suggests. -The Roles page marks the permissions that stop, kill, delete, revoke or update things as dangerous. +Be careful with what a role grants, some permissions give much more control than their name first suggests. +The Roles page marks these permissions that can stop, kill, delete, revoke or update things as dangerous. For example `core.controller.stop` and `core.host.stop` shut down Clusterio on that computer, and it can only be started again by someone with access to the computer. -`core.user.update_roles` and `core.role.update` are not marked, but they are as powerful as Cluster Admin. -Setting roles has no restrictions, so a user who can do it can give themselves the Cluster Admin role. +Or `core.user.update_roles` and `core.role.update` which are as powerful as Cluster Admin because setting roles has no restrictions, so a user can give themselves the Cluster Admin role. The user can then log in as described in [Logging in](#logging-in).