mirror of
https://github.com/clusterio/clusterio.git
synced 2026-11-12 15:04:52 +09:00
Hornwitser
5e410a6ac3
Include the packages/ component in paths referenced in the documentation to make it clear where the files are located in the repository. [skip travis]
103 lines
4.0 KiB
Markdown
103 lines
4.0 KiB
Markdown
Configuration System
|
|
====================
|
|
|
|
<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 group based configuration system to manage settings for
|
|
the master server, instances, slaves, and the clusterioctl utility.
|
|
Plugins get their own config group for the master server and instances
|
|
which they can add their own fields to. The fields are defined early in
|
|
the startup, and the groups and their fields for disabled plugins will
|
|
still be created.
|
|
|
|
The built-in config groups and their fields are defined in
|
|
[packages/lib/config/definitions.js](/packages/lib/config/definitions.js)
|
|
while plugins can add their own config groups to the `MasterConfigGroup`
|
|
and `InstanceConfigGroup` properties of the `info.js` export using
|
|
subclasses of `PluginConfigGroup`. The plugin group has the enabled
|
|
field pre-defined on it, and it's used to enable/disable plugins.
|
|
|
|
|
|
Defing Fields
|
|
-------------
|
|
|
|
Fields are defined using the `define` class method on group classes
|
|
after the groupName have been set and before the class has been
|
|
finalized. The `define` method takes an object as argument with the
|
|
following properties:
|
|
|
|
**type**:
|
|
The type of config value this field will support. The supported
|
|
values are boolean, string, number, and object, and if an attept is
|
|
made to set the field to a value that is not of the right type it
|
|
will be reject unless it's a string that can be converted to the
|
|
right type.
|
|
|
|
**name**:
|
|
Name of the configuration field, this is the primary way the field
|
|
is accessed, both in code and on the command line. As such it
|
|
should follow the lower\_case\_underscore style and not contain any
|
|
spaces or dots.
|
|
|
|
**title** (optional):
|
|
Text used to identify the config field in user interfaces.
|
|
|
|
**description** (optional):
|
|
Text used to describe the config field in user interfaces.
|
|
|
|
**enum** (optional):
|
|
Array of acceptable values this field can have. Attempts to set a
|
|
value not in this array will be rejected, which makes it useful for
|
|
making enumareted list of choices.
|
|
|
|
**optional** (optional):
|
|
True if this field can be set to null. Defaults to false.
|
|
|
|
**initial_value** (optional if optional is true):
|
|
Value this config field should take in a newly initialized config.
|
|
This can also be an async function returning the value to use.
|
|
|
|
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.
|
|
|
|
|
|
Accessing Fields
|
|
----------------
|
|
|
|
On the Config instance there's two ways to access fields: through the
|
|
set and get methods using dot notation. E.g.:
|
|
|
|
let value = configInstance.get("group.field");
|
|
|
|
Or by getting the group first and then calling set or get on that.
|
|
E.g.:
|
|
|
|
let value = configInstance.group("group").get("field")
|
|
|
|
The set method takes an extra argument, which is the value to set the
|
|
field to. If the value is not valid this will throw an InvalidValue
|
|
exception, if the group or field doesn't exist it will throw an
|
|
InvalidField exception.
|
|
|
|
|
|
Config Lifecycle
|
|
----------------
|
|
|
|
Values for all config fields are created when the config is initialized,
|
|
as well as for any fields with missing values when a config is loaded.
|
|
Once a field has a value it is never automatically removed, even if the
|
|
field or group it was part of no longer exists. This ensures that
|
|
plugin configuration is not lost should the server be started up without
|
|
the plugins that defined the configuration installed.
|
|
|
|
For instance configs, they are kept on the master server and serialized
|
|
and sent over to the relevant slaves on startup. This makes it possible
|
|
to edit instance configs when the slave the instance is on is offline.
|
|
A copy is also stored in the instance directory on the slave, and this
|
|
config will be deliverd to the master server on slave startup, which
|
|
enables instances to be copied between clusters as long as their IDs are
|
|
unique.
|