Document missing config options (#995)

configuration.md was missing most options added over the last few years. Add the controller, host and instance options that weren't listed, mark the internal ones, note the validation rule under each field that has one, and fix entries that had gone stale: the tls defaults, the proxy_stream_timeout name, game port assignment from host.factorio_port_range, the three sync list modes, and the player_online_autosave_slots heading.

Plugin options live in the plugin READMEs, so add the missing ones for inventory_sync, player_auth and subspace_storage there. config-system.md gets the field definition properties it didn't list yet.

Co-authored-by: bbassie <fqv4b97f@bastiaanbreemer.nl>
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>

docs/config-system.md

@@ -3,10 +3,10 @@
 <sub>This document describes the implementation and inner working of the configuration system in Clusterio, and unless you're developing Clusterio it's probably not going to be very useful for you.</sub>
 
 Clusterio uses a field based configuration system to manage settings for the controller, instances, hosts, and the clusterioctl utility.
-Plugins can add their own config fields for the controller and instances configs.
+Plugins can add their own config fields for the controller, host and instance configs.
 The fields are defined early in the startup, and fields for disabled plugins will still be created.
 
-The built-in config fields are defined in [packages/lib/src/config/definitions.ts](/packages/lib/src/config/definitions.ts) while plugins can add their own config field definitions to the `controllerConfigFields` and `instanceConfigFields` properties of the `plugin` export.
+The built-in config fields are defined in [packages/lib/src/config/definitions.ts](/packages/lib/src/config/definitions.ts) while plugins can add their own config field definitions to the `controllerConfigFields`, `hostConfigFields` and `instanceConfigFields` properties of the `plugin` export.
 A `<plugin_name>.load_plugin` field is automatically created for each plugin and it's used to enable/disable the loading plugins on startup.
 
 
@@ -46,6 +46,45 @@ For plugins the group name is the name of the plugin, e.g., the `level` field of
     Value this config field should take in a newly initialized config.
     This can also be an async function returning the value to use.
 
+**validator** (optional):
+    Function called with the value being set and the config it belongs to.
+    It should throw an error if the value is not acceptable, and the message of the error is passed on to whoever tried to set it.
+    Common validators such as `greaterThanZero`, `greaterThanEqualZero`, `integer` and `filePath` are available on `Config.validators`, along with `optional` to skip null and `all` to combine several.
+    The config is read only while the validator runs.
+
+**dependsOn** (optional):
+    Names of other fields the validator reads the value of.
+    When one of those fields is changed the validator of this field is run again against the new value, and the change is rejected if it fails.
+
+**restartRequired** (optional):
+    True if a restart of the controller, host or instance the config belongs to is needed for changes to take effect.
+    Changing such a field sets the `restartRequired` flag on the config, which the web interface uses to show that a restart is pending.
+    Defaults to false.
+
+**restartRequiredProps** (optional):
+    For object fields, names of properties that have the opposite of `restartRequired`.
+    Only used by the web interface to show which properties need a restart, `factorio.settings` uses it to mark the settings that are applied live.
+
+**credential** (optional):
+    Locations allowed to read the value of this field.
+    Other locations can still change the value if allowed by `access`, which is what you want for tokens and passwords.
+
+**readonly** (optional):
+    Locations allowed to change the value of this field.
+    Other locations can still read the value if allowed by `access`.
+
+**hidden** (optional):
+    True if the web interface should not show this field.
+    Used for internal values that are managed by Clusterio.
+
+**autoComplete** (optional):
+    Value for the autocomplete attribute of the input in the web interface, e.g. `section-factorio new-password`.
+    Only used for string and number fields.
+
+**inputComponent** (optional):
+    Name of the input component the web interface should render for this field instead of the default for its type.
+    Plugins can add their own components through `inputComponents` on their web plugin class.
+
 If the value for a field stored in on disk somehow ends up being invalid the field will take on the initial\_value instead when the config is loaded.
 
 

docs/configuration.md

@@ -1,5 +1,15 @@
 # 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.
+
+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.
+Setting a value that fails a check is rejected with an error and the old value is kept.
+
+A few fields are internal to Clusterio.
+These are managed by Clusterio itself, hidden in the web interface and should not be modified by hand.
+
 
 ## Controller Configuration
 
@@ -20,11 +30,30 @@ This is also used by plugins to store its data.
 Defaults to "database".
 
 
+### controller.mods_directory
+
+Directory where mods shared with the cluster are stored.
+Mods uploaded through the web interface or downloaded from the mod portal end up here, and hosts fetch the mods they need for their instances from here.
+Needs to be writeable by the controller.
+
+Defaults to "mods".
+
+
+### controller.autosave_interval
+
+Interval in seconds the controller saves the data it holds in memory, such as users, instances, mod packs and plugin data, to controller.database_directory.
+The data is also saved on shutdown.
+Must be greater than 0.
+
+Defaults to 60.
+
+
 ### controller.http_port
 
 Port to host HTTP server on.
 If set to null no HTTP server will be exposed.
 At least one of this and controller.https_port needs to be set to a port.
+Must be a whole number greater than 0.
 
 Defaults to 8080.
 
@@ -35,6 +64,7 @@ Port to host HTTPS server on.
 Uses controller.tls_certificate and controller.tls_private_key as the certificate and private key for the HTTPS server.
 If set to null no HTTPS server will be exposed.
 At least one of this and controller.http_port needs to be set to a port.
+Must be a whole number greater than 0.
 
 See the [Setting up TLS](/docs/setting-up-tls.md) document for a guide to setting up HTTPS with Clusterio.
 
@@ -51,10 +81,19 @@ interfaces.
 Defaults to null.
 
 
+### controller.trusted_proxies
+
+Comma separated list of IP addresses and/or CIDR blocks of reverse proxies in front of the controller to trust the `X-Forwarded-For` header from.
+When a connection comes from one of these addresses the last address in the `X-Forwarded-For` header is used as the remote address of the connection instead of the address of the proxy.
+Entries that are not valid IP addresses are logged as errors and ignored.
+
+Defaults to null meaning the header is never trusted.
+
+
 ### controller.public_url
 
 Public address the controller is accessible on.
-Currently only used for `clusteriocontroller bootstrap create-ctl-config` in order to give the right url to connect to.
+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.
 This should be a full URL ending with a /.
 
 Defaults to null meaning assume localhost.
@@ -64,25 +103,34 @@ Defaults to null meaning assume localhost.
 
 Used to override where static assets such as the web bundle is loaded from.
 This can be used if you want to put the static assets on a separate cdn url like `https://cdn.example.com/static/` while keeping the API hosted directly by clusterio.
-Due to a limitation on how the webpack assets are built the pathname component of the url have to be `/static/`.
+Due to a limitation on how the webpack assets are built the pathname component of the url have to be `/static/`, values with any other path are rejected.
 
 See also the `clusteriocontroller copy-static` command for how to obtain the static asset files that need to be hosted.
 
 Defaults to null meaning use the internally hosted assets.
 
 
+### controller.grafana_url
+
+URL of a Grafana dashboard to link to from the overview page of the web interface, including the protocol.
+If null no link is shown.
+
+Defaults to null.
+
+
 ### controller.tls_certificate
 
 Path to TLS certificate to use for the HTTPS server when controller.https_port is configured.
+Both this and controller.tls_private_key have to be set for the controller to start with controller.https_port configured.
 
-Defaults to "database/certificates/cert.crt".
+Defaults to null.
 
 
 ### controller.tls_private_key
 
 Path to TLS private key to use for the HTTPS server when controller.https_port is configured.
 
-Defaults to "database/certificates/cert.key".
+Defaults to null.
 
 
 ### controller.auth_secret
@@ -90,6 +138,7 @@ Defaults to "database/certificates/cert.key".
 Base64 encoded authentication secret used to verify tokens issued to hosts, users, and sessions.
 This should contain 256 bytes of random data, and if changed will cause all tokens become invalid.
 Keep this secret if leaked an attacker could easily compromise the cluster.
+The value can only be read and changed from the controller itself, it is not available through clusterioctl or the web interface.
 
 Defaults to null which means generate a secure secret on startup.
 
@@ -99,6 +148,7 @@ Defaults to null which means generate a secure secret on startup.
 Interval in seconds heartbeats are sent out at for WebSocket connections.
 If a WebSocket connection hasn't received a heartbeat in 2 times the heartbeat interval it will be considered stale and closed.
 A lower value means less time between connections going stale and them being closed.
+Must be greater than 0.
 
 Defaults to 15.
 
@@ -110,6 +160,8 @@ A higher timeout gives more time for a client to recconect and resume an active
 In the case of the controller or client crashing the data loss is unavoidable.
 
 Value should not be less than the configured `max_reconnect_delay` of the clients and it should be greater than 2 times `controller.heartbeat_interval`.
+Must be greater than 0.
+
 Defaults to 60.
 
 
@@ -117,18 +169,64 @@ Defaults to 60.
 
 Timeout in seconds before a call to gather metrics from a host times out.
 This should be less than both the timeout and collection interval configured for the collection job in Prometheus.
+Must be greater than 0.
 
 Defaults to 8.
 
 
-### controller.stream_timeout
+### controller.system_metrics_interval
+
+Interval in seconds the controller gathers CPU, memory and disk usage from itself and every connected host for display in the web interface.
+Whether the controller needs a restart to apply an update is also checked on this interval.
+If 0 system metrics are not gathered.
+Must be 0 or greater.
+
+Defaults to 10.
+
+
+### controller.proxy_stream_timeout
 
 Timeout in seconds for proxy streams through the controller that has been created but is not yet sending data to be automatically closed.
 Streams that have started sending data before this timeout is not affected.
+Must be greater than 0.
 
 Defaults to 15.
 
 
+### controller.factorio_username
+
+Username of the Factorio.com account to authenticate with the Factorio API with.
+Together with controller.factorio_token this is used by the controller to download mods from the mod portal, and if controller.share_factorio_credentials_with_hosts is enabled, as the credentials in the server settings of instances.
+
+Defaults to null.
+
+
+### controller.factorio_token
+
+Token of the Factorio.com account to authenticate with the Factorio API with, see controller.factorio_username.
+This is the token shown on your profile page on factorio.com, not your password.
+The value is treated as a credential, it can be set from anywhere but only read back from the controller itself.
+
+Defaults to null.
+
+
+### controller.share_factorio_credentials_with_hosts
+
+If enabled hosts get controller.factorio_username and controller.factorio_token from the controller when they start an instance and put them in the server settings of that instance.
+Credentials set on the host with host.factorio_username and host.factorio_token, or on the instance through `username` and `token` in factorio.settings, take precedence over the ones from the controller.
+Disable this if you don't want the controller's credentials to be sent to the hosts.
+
+Defaults to true.
+
+
+### controller.default_mod_pack_id
+
+ID of the mod pack to use for instances that don't have factorio.mod_pack_id set.
+Instances without a mod pack of their own fail to start if this is null.
+
+Defaults to null.
+
+
 ### controller.default_role_id
 
 Role to automatically grant to new users.
@@ -137,6 +235,55 @@ If null no role is granted.
 Defaults to 1 which correspond to the default Player role.
 
 
+### controller.mod_portal_cache_duration_minutes
+
+Time in minutes the controller caches the list of mods fetched from the Factorio mod portal when browsing it from the web interface.
+Set to 0 to disable the cache and fetch the list on every request.
+Must be 0 or greater.
+
+Defaults to 30.
+
+
+### controller.mod_portal_page_size
+
+Number of results to request per page when fetching the list of mods from the Factorio mod portal.
+Must be greater than 0.
+
+Defaults to 1000.
+
+
+### controller.allow_remote_updates
+
+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.
+See [Managing a Cluster](/docs/managing-a-cluster.md) for details on remote updates.
+
+Defaults to true.
+
+
+### controller.allow_plugin_updates
+
+Whether remote requests to update plugins installed on the controller with npm are allowed.
+Like controller.allow_remote_updates this can only be changed locally.
+
+Defaults to true.
+
+
+### controller.allow_plugin_install
+
+Whether remote requests to install new plugins on the controller with npm are allowed.
+Like controller.allow_remote_updates this can only be changed locally.
+
+Defaults to false.
+
+
+### controller.version
+
+Version of the controller package that last loaded this config.
+Set automatically on startup and used to detect when the controller has been updated or downgraded.
+Internal, hidden in the web interface and should not be changed.
+
+
 ### <plugin_name>.load_plugin
 
 Whether to load the plugin on the controller.
@@ -158,6 +305,7 @@ Defaults to "New Host".
 ### host.id
 
 Immutable numeric id of the host which uniquely identifies this host in the cluster.
+Hidden in the web interface.
 
 Defaults to a random 31 bit number.
 
@@ -170,6 +318,14 @@ This can either point to a Factorio server directory, or to a directory containi
 Defaults to "factorio".
 
 
+### host.mods_directory
+
+Directory the host stores mods downloaded from the controller in.
+When an instance starts the mods in its mod pack are downloaded here if missing and then linked into the mods directory of the instance.
+
+Defaults to "mods".
+
+
 ### host.instances_directory
 
 Directory to store instances in.
@@ -189,6 +345,7 @@ Defaults to "http://localhost:8080/".
 
 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 value can only be read and changed from the host itself.
 
 Defaults to "enter token here".
 
@@ -201,14 +358,82 @@ This is used by plugins like Server Select to give the correct address to switch
 Defaults to "localhost".
 
 
+### host.factorio_port_range
+
+UDP ports the host hands out to instances that don't have factorio.game_port set.
+Written as a comma separated list of ports and/or ranges of ports separated with a dash, for example "34100-34199" or "34100, 34200-34210".
+A port is picked when the instance is started and remembered in factorio.host_assigned_game_port, so an instance keeps the same port as long as it is still free.
+Starting an instance fails if all ports in the range are taken.
+
+Defaults to "34100-34199".
+
+
+### host.factorio_username
+
+Username of the Factorio.com account to put in the server settings of instances on this host.
+If set this takes precedence over the credentials shared by the controller, but not over `username` set in factorio.settings of an instance.
+
+Defaults to null.
+
+
+### host.factorio_token
+
+Token of the Factorio.com account to go with host.factorio_username.
+The value is treated as a credential, it can be set from anywhere but only read back from the host itself.
+
+Defaults to null.
+
+
 ### host.max_reconnect_delay
 
 Maximum delay in seconds to wait after connection to the controller is dropped before attempting to reconnect to it.
 The actual delay on each reconnect will be a random number between 0 and this configured value to avoid all clients trying to reconnect at the same time.
+Must be greater than 0.
 
 Defaults to 60.
 
 
+### host.allow_remote_updates
+
+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.
+See [Managing a Cluster](/docs/managing-a-cluster.md) for details on remote updates.
+
+Defaults to true.
+
+
+### host.allow_plugin_updates
+
+Whether remote requests to update plugins installed on the host with npm are allowed.
+Like host.allow_remote_updates this can only be changed locally.
+
+Defaults to true.
+
+
+### host.allow_plugin_install
+
+Whether remote requests to install new plugins on the host with npm are allowed.
+Like host.allow_remote_updates this can only be changed locally.
+
+Defaults to false.
+
+
+### host.version
+
+Version of the host package that last loaded this config.
+Set automatically on startup and used to detect when the host has been updated or downgraded.
+Internal, hidden in the web interface and should not be changed.
+
+
+### <plugin_name>.load_plugin
+
+Whether to load the plugin on the host.
+Only plugins with a host or instance part have this field in the host config.
+Plugins not loaded on the host will not be loaded on the instances it hosts.
+
+Defaults to true.
+
+
 ## Instance Configuration
 
 ### instance.name
@@ -221,6 +446,7 @@ Defaults to "New Instance".
 ### instance.id
 
 Imutable numeric id of the instance which uniquely identifies this instance in the cluster.
+Hidden in the web interface.
 
 Defaluts to a random 31 bit integer.
 
@@ -230,6 +456,7 @@ Defaluts to a random 31 bit integer.
 Host this instance is assigned to.
 To change this you need to use the separate assign instance interface.
 After being assigned to a host the directory for the instance is created on the host.
+Internal and hidden in the web interface.
 
 Defaults to null meaning not assigned.
 
@@ -253,23 +480,52 @@ Defaults to false.
 ### factorio.version
 
 Version of Factorio to use for this instance.
-Can be a version like "1.0.0" or special string "latest" meaning the latest version of Factorio found on the host.
+Can be a specific version like "2.0" or "2.0.15", a release channel like "stable" or "experimental", or the special string "latest" meaning the latest version of Factorio found on the host.
+A release channel is resolved to a version through the latest releases data the controller keeps, and the instance fails to start if that is unavailable.
+Values that don't match one of these forms are rejected.
 
 Defaults to "latest".
 
 
+### factorio.executable_path
+
+Path relative to the Factorio installation directory of the executable to run.
+If null the path is auto detected, which is `bin/x64/factorio` on Linux and Windows and `MacOS/factorio` on macOS.
+Only needed in special setups.
+
+Defaults to null.
+
+
+### factorio.shutdown_timeout
+
+Time in seconds to wait for the Factorio server to exit after asking it to stop before the process is killed.
+Set to 0 to wait forever.
+Changing this while the instance is stopping restarts the timer with the new value.
+Must be 0 or greater.
+
+Defaults to 300.
+
+
 ### factorio.game_port
 
 UDP port to run the Factorio server on.
-If null a random port in the dynamyc range assigned each time the instance starts.
+If null a port from host.factorio_port_range on the host is assigned to the instance.
+Negative values are rejected.
 
 Defaults to null.
 
 
+### factorio.host_assigned_game_port
+
+Port from host.factorio_port_range the host has assigned to this instance while factorio.game_port is null.
+Internal, set by the host and only accessible from the host.
+
+
 ### factorio.rcon_port
 
 TCP port to start the RCON interface on the Factorio server on.
 If null a random port in the dynamic range is assigned each time the instance starts.
+Negative values are rejected.
 
 Defaults to null.
 
@@ -278,16 +534,18 @@ Defaults to null.
 
 Password to use for the RCON interafec.
 If null a random secure password is generated and used each time the instance starts.
+The value is treated as a credential and can only be read back by the controller and the host.
 
 Defaults to null.
 
 
-### player_online_autosave_slots
+### factorio.player_online_autosave_slots
 
 Keeps a separate pool for autosaves where at least on player has been online since the previous autosave was done.
 This requires regular autosaving to be enabled and will rename autosaves to `_autosave_poN.zip` (where N is a slot number) whenever a player has been online for that save.
 The slot numbers start at 1, are incremented by 1 after each autosave that is renamed and reset back to 1 whenever this value is exceeded.
-Note that this value should be set to a higher value than the value of `autosave_slots` in `factorio.settings`.
+Setting this to a value lower than `autosave_slots` in factorio.settings is rejected, unless it is 0.
+The same check is done when factorio.settings is changed.
 Useful for preventing the loss of all progress when nobody is around on always online servers with auto pause disabled.
 
 If 0 no autosave renaming takes place.
@@ -295,12 +553,34 @@ If 0 no autosave renaming takes place.
 Defaults to 5.
 
 
+### factorio.mod_pack_id
+
+ID of the mod pack to use on this instance.
+The mods in the pack are linked into the mods directory of the instance every time it starts, and any other files in that directory are removed.
+If null the mod pack set in controller.default_mod_pack_id is used.
+
+Defaults to null.
+
+
 ### factorio.enable_save_patching
 
 Whether to use save patching or not.
 When enabled lua code is patched into the game save before starting it.
 Most plugins require the use of save patching to function.
 Turning it off makes it possible to use Clusterio to run and manage regular vanilla games and scenarios not compatible with Clusterio.
+Plugins that need save patching can't be loaded on the instance while this is disabled.
+Disabling it while such a plugin is loaded is rejected, and so is loading such a plugin while it is disabled.
+
+Defaults to true.
+
+
+### factorio.enable_script_commands
+
+Allow Clusterio and plugins to send commands that disable achievements to the server over RCON, that is `/c`, `/sc`, `/mc`, `/cheat`, `/editor` and their long forms.
+Clusterio integrations and most plugins need this, and when enabled achievements are disabled on the server at startup.
+When disabled attempts to send such a command fail with an error.
+This does not stop players from using these commands themselves.
+Like factorio.enable_save_patching, plugins that need script commands can't be loaded on the instance while this is disabled.
 
 Defaults to true.
 
@@ -312,6 +592,13 @@ Turn on the whitelist on the server.
 Defaults to false.
 
 
+### factorio.enable_authserver_bans
+
+Pass the `--use-authserver-bans` flag to Factorio, which makes the server check connecting players against the multiplayer bans on Factorio.com and report bans and unbans done on the server back to it.
+
+Defaults to false.
+
+
 ### factorio.settings
 
 Object with the settings to put into `server-settings.json` for the Factorio server.
@@ -319,7 +606,7 @@ The settings in `data/server-settings.example.json` of the Factorio installation
 
 Changes to the following properties will be applied live if the instance is running while it is changed: `afk_autokick_interval`, `allow_commands`, `autosave_interval`, `autosave_only_on_server`, `description`, `ignore_player_limit_for_returning_players`, `max_players`, `max_upload_slots`, `max_upload_in_kilobytes_per_second`, `name`, `only_admins_can_pause_the_game`, `game_password`, `require_user_verification`, `tags`, `visibility`.
 
-Defaults to {"tags":["clusterio"],"auto_pause":false}.
+Defaults to a set of common settings filled in when the instance is created, such as `"tags": ["clusterio"]`, `"auto_pause": false` and a `name` and `description` based on the cluster and instance names.
 
 
 ### factorio.verbose_logging
@@ -330,6 +617,14 @@ This prints more messages to the log.
 Defaults to false.
 
 
+### factorio.console_logging
+
+Pass the `--console-log` flag to Factorio to make it write the console output, such as chat, commands and player joins, to `console.log` in the instance directory.
+Useful for 3rd party tools that read the console log of the server.
+
+Defaults to false.
+
+
 ### factorio.strip_paths
 
 Strip down absolute paths in the server log going to files inside the instance directory such that they are relative to the instance directory.
@@ -352,25 +647,35 @@ Defaults to true.
 ### factorio.sync_adminlist
 
 Synchronize in-game admin list with admin status of the users in cluster.
+One of "disabled", "enabled" or "bidirectional".
 If enabled Clusterio will generate a new `server-adminlist.json` on instance startup based on the users in the cluster with admin status set to true, and keep the admins in sync with the users that have admin status while the instance is running.
+With "bidirectional" players promoted or demoted in-game with `/promote` and `/demote` are also updated in the cluster, and from there on the other instances.
+Configs from before this became a choice are migrated from true and false to "enabled" and "disabled".
 
-Defaults to true.
+Defaults to "bidirectional".
 
 
 ### factorio.sync_whitelist
 
 Synchronize in-game whitelist with the whitelisted status of the users in the cluster.
+One of "disabled", "enabled" or "bidirectional".
 If enabled Clusterio will generate a new `server-whitelist.json` on instance startup based on the users in the cluster with whitelisted status set to true, and keep the whitelisted users in sync with the users that have whitelisted status while the instance in running.
+With "bidirectional" changes made in-game with `/whitelist` are picked up by watching `server-whitelist.json` for changes and updated in the cluster as well.
+This requires factorio.enable_whitelist to be on, as Factorio doesn't write the file otherwise.
+Configs from before this became a choice are migrated from true and false to "enabled" and "disabled".
 
-Defaults to true.
+Defaults to "bidirectional".
 
 
 ### factorio.sync_banlist
 
 Synchronize in-game banlist with the banned status of users in the cluster.
+One of "disabled", "enabled" or "bidirectional".
 If enabled Clusterio will generate a new `server-banlist.json` on instance startup based on users in the cluster with banned status set to true, and keep the banned users in sync with the users that have the banned status while the instance is running.
+With "bidirectional" players banned or unbanned in-game with `/ban` and `/unban` are also updated in the cluster, and from there on the other instances.
+Configs from before this became a choice are migrated from true and false to "enabled" and "disabled".
 
-Defaults to true.
+Defaults to "bidirectional".
 
 
 ### factorio.max_concurrent_commands
@@ -387,6 +692,7 @@ This means a high number of concurrent commands can amplify resends due to packe
 
 Prior to 0.18.7 the maximum practical size of game update sent where arround 8 kB due to the UDP receive buffer on windows defaulting to this value, larger updates would not get through the receive buffer and cause the connection to drop.
 To stay below the 8 kB limit the maximum safe value for this option would be around 7000 / (3 * game_speed * maximum_segment_size), which is around 20 in normal circumstances.
+Must be greater than 0.
 
 Defaults to 5.
 
@@ -394,7 +700,8 @@ Defaults to 5.
 ### <plugin_name>.load_plugin
 
 Whether to load the given plugin on the instance.
-Note that plugins need to be loaded on the controller in order for them to be loaded on instances.
+Note that plugins need to be loaded on the controller and the host in order for them to be loaded on instances.
+Loading a plugin that requires save patching or script commands is rejected while factorio.enable_save_patching or factorio.enable_script_commands respectively is disabled on the instance.
 
 Defaults to true.
 
@@ -420,5 +727,6 @@ Defaults to null meaning complain about it not being set and exit.
 
 Max duration in seconds to wait before attempting to reconnect with the controller after the connection is dropped.
 The actual delay on each reconnect will be a random number between 0 and this configured value to avoid all clients trying to reconnect at the same time.
+Must be 0 or greater.
 
 Defaults to 60.

plugins/inventory_sync/README.md

@@ -43,3 +43,24 @@ Should an error occur during this process the player is given the option to use
 Communication between the server and instance goes over stdout or rcon, depending on the size of the data.
 Communication between the instance and the controller goes over websockets.
 Overall, we are able to achieve a latency between 3 and infinite ticks from server join, depending on the size of the inventory. The major limiter is rcon transfer speeds with larger inventories, especially if they contain blueprints.
+
+
+## Controller Configuration
+
+### inventory_sync.player_lock_timeout
+
+Time in seconds before the exclusive access an instance holds on a player's inventory expires after the instance stops or its host disconnects.
+Until it expires the player is told the inventory is in use on that instance when joining another one.
+The timeout is cancelled if the instance comes back before it runs out.
+
+Defaults to `60`.
+
+
+## Instance Configuration
+
+### inventory_sync.rcon_chunk_size
+
+Size in characters of the chunks the serialized inventory is split into when sent to the game over RCON.
+Smaller chunks take more commands to transfer an inventory but hold up the RCON command pipe for less time each.
+
+Defaults to `1000`.

plugins/player_auth/README.md

@@ -29,3 +29,10 @@ Time in seconds the first code generated stays valid.
 The login must be completed in less than this time starting from when the login dialog is opened in-game.
 
 Defaults to `120`.
+
+#### player_auth.show_connect_address
+
+Show the address to connect to for each server in the server list on the login page of the web interface, made up of host.public_address and the game port of the instance.
+This list is visible to anyone who can reach the web interface, so leave it off if you don't want unauthenticated users to see where the servers are.
+
+Defaults to `false`.

plugins/subspace_storage/README.md

@@ -11,3 +11,32 @@ Run the following commands in the folder Clusterio is installed to:
     npx clusteriocontroller plugin add @clusterio/plugin-subspace_storage
 
 Substitute clusteriocontroller with clusteriohost or clusterioctl if this a dedicate host or ctl installation respectively.
+
+
+## Controller Configuration
+
+### subspace_storage.division_method
+
+How to divide items between instances when there isn't enough in storage to give everyone what they ask for.
+One of `simple`, `dole` or `neural_dole`.
+With `simple` requests are served in full on a first come first served basis until the storage runs out.
+With `dole` a per item division factor is kept that halves the amount handed out each time a request can't be met and slowly recovers when requests succeed, which spreads the remaining items between instances at the cost of draining the last of an item slowly.
+`neural_dole` does the same with a small neural network estimating a fair share from the recent request history.
+
+Defaults to `simple`.
+
+
+### subspace_storage.log_item_transfers
+
+Log every item transfer in and out of the storage to the controller console at verbose level.
+
+Defaults to `false`.
+
+
+## Instance Configuration
+
+### subspace_storage.log_item_transfers
+
+Log every item transfer in and out of the storage to the host console at verbose level.
+
+Defaults to `false`.