diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 00000000..71a76b60 --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,323 @@ +Configuration +============= + + +Master Configuration +-------------------- + +### master.database_directory + +Directory used to store cluster data to. Needs to be writeable by the +master server. This is also used by plugins to store its data. + +Defaults to "database". + + +### master.http_port + +Port to host HTTP server on. If set to null no HTTP server will be +exposed. At least one of this and master.https_port needs to be set to +a port. + +Defaults to null. + + +### master.https_port + +Port to host HTTPS server on. Uses master.tls_certificate and +master.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 master.http_port needs to be set to a port. + +Defaults to 8443. + + +### master.external_address + +External address the master server is accessible on. Currently only +used for `clusteriomaster bootstrap create-ctl-config` in order to give +the right url to connect to. This should be a full URL ending with a /. + +Defaults to null meaning assume localhost. + + +### master.tls_certificate + +TLS certificate to use for the HTTPS server when master.https_port is +configured. If neither this nor the configured master.tls_private_key +exists a self signed certificate is automatically created. + +Defaults to "database/certificates/cert.crt". + + +### master.tls_private_key + +TLS private key to use for the HTTPS server when master.https_port is +configured. If neither this nor the configured master.tls_certificate +exists a self signed certificate is automatically created. + +Defaults to "database/certificates/cert.key". + + +### master.tls_bits + +Number of bits to use when creating a self signed certificate. + +Defaults to 2048. + + +### master.auth_secret + +Base64 encoded authentication secret used to verify tokens issued to +slaves, 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. + +Defaults to null which means generate a secure secret on startup. + + +### master.heartbeat_interval + +Interval in seconds heartbeats are sent out at for WebSocket +connections. If a 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. + +Defaults to 60 + + +### master.connector_shutdown_timeout + +Timeout in seconds to use while shutting down the master server for link +sessions that currently don't have an active connection and haven't been +closed down properly. This happens when the network between a slave and +the master server goes down unexpectedly, or the slave goes down without +closing the connection properly either do to crashing or the machine +it's hosted on going down. If the timeout expires the session is +terminated and data loss may occur, if the slave went down this is +unavoidable. + +Defaults to 30. + + +### master.default_role_id + +Role to automatically grant to new users. If null no role is granted. + +Defaults to 1 which correspond to the default Player role. + + +### .enabled + +Whether to enable the given plugin on the master server. Plugins +disabled on the master server will not be loaded on instances. + +Defaults to true. + + +Slave Configuration +------------------- + +### slave.name + +Name of the slave. Shows up in slave lists and is used to reference +this slave in the clusterioctl command line interface. + +Defaults to "New Slave". + + +### slave.id + +Imutable numeric id of the slave which uniquely identifies this slave in +the cluster. + +Defaults to a random 31 bit number. + + +### slave.factorio_directory + +Directory to look for the Factorio server(s) in. This can either point +to a Factorio server directory, or to a directory containing multiple +versions of the Factorio server. + +Defaults to "factorio". + + +### slave.instances_directory + +Directory to store instances in. One sub-directory will be created in +it for each instance assigned to this slave and these sub-directories +will contain logs, saves, and various auto generated configuration files +for the instances. + +Defaults to "instances". + + +### slave.master_url + +URL to connect to the master server to. + +Defaults to "https://localhost:8443/". + + +### slave.master_token + +Access token used for authenticating with the master server. You can +generate an access token with `clusterioctl slave generate-token +--id `, or use the `clusterioctl slave create-config` to +create a new slave config with the correct url and token in it. + +Defaults to "enter token here". + + +### slave.public_address + +External address instances hosted on this slave can be accessed on. +This is used by plugins like Server Select to give the correct address +to switch between instances in-game. + +Defaults to "localhost". + + +### slave.reconnect_delay + +Delay in seconds to wait after connection to the master server 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 slaves trying to reconnect at the same time. + +Defaults to 5. + + +Instance Configuration +====================== + +### instance.name + +Name of the instance, shown in instance lists and used to reference to this +instance in the clusterioctl command line interface. + +Defaults to "New Instance" + + +### instance.id + +Imutable numeric id of the instance which uniquely identifies this +instance in the cluster. + +Defaluts to a random 31 bit integer. + + +### instance.assigned_slave + +Slave this instance is assigned to. To change this you need to use the +separate assign instance interface. After being assigned to a slave the +directory for the instance is created on the slave. + +Defaults to null meaning not assigned. + + +### 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 slave. + +Defaults to "latest" + + +### 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. + +Defaults to null + + +### 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. + +Defaults to null + + +### factorio.rcon_password + +Password to use for the RCON interafec. If null a random secure +password is generated and used each time the instance starts. + +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. + +Defaults to true + + +### factorio.enable_whitelist + +Turn on the whitelist on the server. + +Defaults to false + + +### factorio.settings + +Object with the settings to put into `server-settings.json` for the +Factorio server. The settings in `data/server-settings.example.json` of +the Factorio installation is used as the base and properties specified +here overrides the properties there. + +Defaults to {"tags":["clusterio"],"auto_pause":false}. + + +### factorio.sync_adminlist + +Synchronize in-game admin list with admin status of the users in +cluster. 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. + +Defaults to true + + +### factorio.sync_whitelist + +Synchronize in-game whitelist with the whitelisted status of the users +in the cluster. 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. + +Defaults to true + + +### factorio.sync_banlist + +Synchronize in-game banlist with the banned status of users in the +cluster. 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. + +Defaults to true + + +### .enabled + +Whether to enable the given plugin on the instance. Note that plugins +need to be enabled on the master server in order for them to be loaded +on instances. + +Defaults to true diff --git a/packages/ctl/README.md b/packages/ctl/README.md new file mode 100644 index 00000000..8bae7719 --- /dev/null +++ b/packages/ctl/README.md @@ -0,0 +1,108 @@ +Clusterio Command Line Interface +================================ + +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. + + +Usage +----- + + npx clusterioctl + +Common options: + + * `--plugin-list ` JSON file to use for storing the list of + plugins that are available to ctl. Defaults to `plugin-list.json` + and will be created if it does not exist. See the `plugin` command + for managing this list. + + * `--config ` JSON file to use for storing configuration for + ctl. Defaults to `config-control.json` and will be created if it + does not exist. See the `config` command for inspecting and + modifying the configuration. + + +### `plugin ` + +Configure plugins available to be loaded by ctl. The available plugins +will be automatically loaded and the commands they provide will be added +to the ctl utility. + + +#### `plugin add ` + +Add plugin either by require path or relative/absolute path to the +plugin directory. A relative path must start with ./ or ../ (or .\ and +..\ on Windows) otherwise it will be assumed to be a require path for an +installed package in node_modules. + +For example, installing the Subspace Storage plugin: + + npm install @clusterio/plugin-subspace_storage + npx clusterioctl plugin add @clusterio/plugin-subspace_storage + +Since the `plugin-list.json` is shared between master, slave and ctl you +usually only need to do this once per machine. + + +#### `plugin remove ` + +Remove a plugin by its name. This should be done before uninstalling +the plugin, otherwise there will be an error when Clusterio tries to +load the info from the plugin. Removing and unistalling a plugin is +usually not neccessary as the functions provided by the plugin can be +disabled in the config. + +For example, uninstalling the Subspace Storage plugin: + + npx clusterioctl plugin remove subspace_storage + npm uninstall @clusterio/plugin-subspace_storage + +Since the `plugin-list.json` is shared between master, slave and ctl you +usually only need to do this once per machine. + + +#### `plugin list` + +Lists the plugins set up to be available by name followed by path. + + +### `config-control` + +Manage the ctl configuration. This allows setting the url and token to +the master server to manage. + + +#### `config-control set [value]` + +Set a config entry to the given value. If value is not provided the +entry is set to null. If the config entry is of type object the value +must be a valid JSON serialization of an object. + +See docs/configuration.md in the main repositiory for the available +configuration. + + +#### `config-control show ` + +Shows the value for a single config entry. + + +#### `config-control list` + +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. + +[The Clusterio +repository](https://github.com/clusterio/factorioClusterio) +for instructions on how to set up a cluster. diff --git a/packages/lib/README.md b/packages/lib/README.md new file mode 100644 index 00000000..db7a33ed --- /dev/null +++ b/packages/lib/README.md @@ -0,0 +1,8 @@ +Common Library for Clusterio +============================ + +This package contains functionality shared between master, slave, ctl +and/or plugins of Clusterio. + +See [the Clusterio repository](https://github.com/clusterio/factorioClusterio) +for more inforation on Clusterio. diff --git a/packages/master/README.md b/packages/master/README.md new file mode 100644 index 00000000..99e76433 --- /dev/null +++ b/packages/master/README.md @@ -0,0 +1,128 @@ +Clusterio Master Server +======================= + +Communication hub for Clusterio clusters. The master server forwards +data between Clusterio slaves connected to it and allows the cluster to +be remotely managed through WebSocket connections to it either by using +the included web interface or the Clusterio ctl command line utility. + + +Usage +----- + + npx clusteriomaster + +Common options: + + * `--plugin-list ` JSON file to use for storing the list of + plugins that are available to the master server. Defaults to + `plugin-list.json` and will be created if it does not exist. See the + `plugin` command for managing this list. + + * `--config ` JSON file to use for storing configuration for the + master server. Defaults to `config-master.json` and will be created + if it does not exist. See the `config` command for inspecting and + modifying the configuration. + + +### `plugin ` + +Configure plugins available to be loaded by the master server. The +available plugins will be loaded unless they have been disabled in the +configuration, see the config command for disabling plugins. + + +#### `plugin add ` + +Add plugin either by require path or relative/absolute path to the +plugin directory. A relative path must start with ./ or ../ (or .\ and +..\ on Windows) otherwise it will be assumed to be a require path for an +installed package in node_modules. + +For example, installing the Subspace Storage plugin: + + npm install @clusterio/plugin-subspace_storage + npx clusteriomaster plugin add @clusterio/plugin-subspace_storage + +Since the `plugin-list.json` is shared between master, slave and ctl you +usually only need to do this once per machine. + + +#### `plugin remove ` + +Remove a plugin by its name. This should be done before uninstalling +the plugin, otherwise there will be an error when Clusterio tries to +load the info from the plugin. Removing and unistalling a plugin is +usually not neccessary as the functions provided by the plugin can be +disabled in the config. + +For example, uninstalling the Subspace Storage plugin: + + npx clusteriomaster plugin remove subspace_storage + npm uninstall @clusterio/plugin-subspace_storage + +Since the `plugin-list.json` is shared between master, slave and ctl you +usually only need to do this once per machine. + + +#### `plugin list` + +Lists the plugins set up to be available by name followed by path. + + +### `config` + +Manage the master server configuration offline. This should only be +used when the master server is stopped, otherwise the config read might +be out of date and config changes will be overwritten when the master +server shuts down. + + +#### `config set [value]` + +Set a config entry to the given value. If value is not provided the +entry is set to null. If the config entry is of type object the value +must be a valid JSON serialization of an object. + +See docs/configuration.md in the main repositiory for the available +configuration entries. + + +#### `config show ` + +Shows the value for a single config entry. + + +#### `config list` + +Lists up all configuration entries with their currently configured values. + + +### `bootstrap` + +Commands for setting up initial admin acount and access to the cluster. + + +#### `bootstrap create-admin ` + +Creates a new user account with the given name if it does not already +exist in the cluster and grant it full cluster admin permission. You +should be using your own Factorio multiplayer username here. + + +#### `bootstrap create-ctl-config ` + +Creates a clusterioctl config for the given user with url and token set +up for connecting to the cluster. + + +### `run` + +Runs the master server. + + +## See Also + +[The Clusterio +repository](https://github.com/clusterio/factorioClusterio) +for instructions on how to set up a cluster. diff --git a/packages/slave/README.md b/packages/slave/README.md new file mode 100644 index 00000000..da8271aa --- /dev/null +++ b/packages/slave/README.md @@ -0,0 +1,111 @@ +Clusterio Slave +=============== + +Node hosting Factorio servers in a Clusterio cluster. Clusterio slaves +connect to the master server and waits for commands from the master +server to start up and stop instances. A cluster can have any number of +slaves in it located on different computers, and each slave can host any +number of instances each of which is a Factorio server that talks with +the rest of the cluster. + + +Usage +----- + + npx clusterioslave + +Common options: + + * `--plugin-list ` JSON file to use for storing the list of + plugins that are available to the slave. Defaults to + `plugin-list.json` and will be created if it does not exist. See the + `plugin` command for managing this list. + + * `--config ` JSON file to use for storing configuration for the + slave. Defaults to `config-slave.json` and will be created if it + does not exist. See the `config` command for inspecting and + modifying the configuration. + + +### `plugin ` + +Configure plugins available to be loaded by the slave. The available +plugins will be loaded unless they have been disabled in the +configuration, see the config command for disabling plugins. + + +#### `plugin add ` + +Add plugin either by require path or relative/absolute path to the +plugin directory. A relative path must start with ./ or ../ (or .\ and +..\ on Windows) otherwise it will be assumed to be a require path for an +installed package in node_modules. + +For example, installing the Subspace Storage plugin: + + npm install @clusterio/plugin-subspace_storage + npx clusterioslave plugin add @clusterio/plugin-subspace_storage + +Since the `plugin-list.json` is shared between master, slave and ctl you +usually only need to do this once per machine. + + +#### `plugin remove ` + +Remove a plugin by its name. This should be done before uninstalling +the plugin, otherwise there will be an error when Clusterio tries to +load the info from the plugin. Removing and unistalling a plugin is +usually not neccessary as the functions provided by the plugin can be +disabled in the config. + +For example, uninstalling the Subspace Storage plugin: + + npx clusterioslave plugin remove subspace_storage + npm uninstall @clusterio/plugin-subspace_storage + +Since the `plugin-list.json` is shared between master, slave and ctl you +usually only need to do this once per machine. + + +#### `plugin list` + +Lists the plugins set up to be available by name followed by path. + + +### `config` + +Manage the slave configuration offline. This should only be used when +the slave is stopped, otherwise the config read might be out of date and +config changes will be overwritten when the slave shuts down. + + +#### `config set [value]` + +Set a config entry to the given value. If value is not provided the +entry is set to null. If the config entry is of type object the value +must be a valid JSON serialization of an object. + +See docs/configuration.md in the main repositiory for the available +configuration. + + +#### `config show ` + +Shows the value for a single config entry. + + +#### `config list` + +Lists up all configuration entries with their currently configured values. + + +### `run` + +Runs the slave. + + +## See Also + +[The Clusterio +repository](https://github.com/clusterio/factorioClusterio) +for instructions on how to set up a cluster. diff --git a/plugins/global_chat/README.md b/plugins/global_chat/README.md new file mode 100644 index 00000000..df66f9f5 --- /dev/null +++ b/plugins/global_chat/README.md @@ -0,0 +1,16 @@ +Clusterio Global Chat Plugin +============================ + +Plugin sharing the in-game chat between instances. + + +Installation +============ + +Run the following commands in the folder Clusterio is installed to: + + npm install @clusterio/plugin-global_chat + npx clusteriomaster plugin add @clusterio/plugin-global_chat + +Substitute clusteriomaster with clusterioslave or clusterioctl if this a +dedicate slave or ctl installation respectively. diff --git a/plugins/research_sync/README.md b/plugins/research_sync/README.md new file mode 100644 index 00000000..6c13adf0 --- /dev/null +++ b/plugins/research_sync/README.md @@ -0,0 +1,17 @@ +Clusterio Research Sync Plugin +============================== + +Plugin synchronizing research progress between instances and the +cluster. + + +Installation +============ + +Run the following commands in the folder Clusterio is installed to: + + npm install @clusterio/plugin-research_sync + npx clusteriomaster plugin add @clusterio/plugin-research_sync + +Substitute clusteriomaster with clusterioslave or clusterioctl if this a +dedicate slave or ctl installation respectively. diff --git a/plugins/statistics_exporter/README.md b/plugins/statistics_exporter/README.md new file mode 100644 index 00000000..42b6b81a --- /dev/null +++ b/plugins/statistics_exporter/README.md @@ -0,0 +1,18 @@ +Clusterio Statistics Exporter Plugin +==================================== + +Plugin exporting item production, fluid production, kill count, entity +build and poluttion statistics to the Prometheus integration to +Clusterio. + + +Installation +============ + +Run the following commands in the folder Clusterio is installed to: + + npm install @clusterio/plugin-statistics_exporter + npx clusteriomaster plugin add @clusterio/plugin-statistics_exporter + +Substitute clusteriomaster with clusterioslave or clusterioctl if this a +dedicate slave or ctl installation respectively. diff --git a/plugins/subspace_storage/README.md b/plugins/subspace_storage/README.md new file mode 100644 index 00000000..dd4ba2ee --- /dev/null +++ b/plugins/subspace_storage/README.md @@ -0,0 +1,16 @@ +Clusterio Subspace Storage Plugin +================================= + +Plugin for the Subpsace Storage mod. + + +Installation +============ + +Run the following commands in the folder Clusterio is installed to: + + npm install @clusterio/plugin-subspace_storage + npx clusteriomaster plugin add @clusterio/plugin-subspace_storage + +Substitute clusteriomaster with clusterioslave or clusterioctl if this a +dedicate slave or ctl installation respectively.