diff --git a/doc/book/admin/start_stop_instance.rst b/doc/book/admin/start_stop_instance.rst index 759e16f784..c85416a9ef 100644 --- a/doc/book/admin/start_stop_instance.rst +++ b/doc/book/admin/start_stop_instance.rst @@ -124,6 +124,8 @@ With a single ``tt`` call, you can: * connect to a specific instance of an application * stop a specific instance of an application or all its instances +.. _admin-start_stop_instance-multi-instance-layout: + Application layout ~~~~~~~~~~~~~~~~~~ diff --git a/doc/code_snippets/snippets/config/README.md b/doc/code_snippets/snippets/config/README.md new file mode 100644 index 0000000000..2e2586e964 --- /dev/null +++ b/doc/code_snippets/snippets/config/README.md @@ -0,0 +1,11 @@ +# Configuration + +A sample application demonstrating various features related to Tarantool [configuration](https://www.tarantool.io/en/doc/latest/concepts/configuration/). + +## Running + +To run applications placed in [instances.enabled](instances.enabled), go to the `config` directory in the terminal and execute the `tt start` command, for example: + +```console +$ tt start application +``` diff --git a/doc/code_snippets/snippets/config/instances.enabled/application/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/application/config.yaml new file mode 100644 index 0000000000..e51dddc6c4 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/application/config.yaml @@ -0,0 +1,13 @@ +app: + file: 'myapp.lua' + cfg: + greeting: 'Hello' + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: "3301" \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/application/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/application/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/application/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/application/myapp.lua b/doc/code_snippets/snippets/config/instances.enabled/application/myapp.lua new file mode 100644 index 0000000000..81322b1ead --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/application/myapp.lua @@ -0,0 +1,4 @@ +-- myapp.lua -- +local log = require('log').new("myapp") +local config = require('config') +log.info("%s from app, %s!", config:get('app.cfg.greeting'), box.info.name) diff --git a/doc/code_snippets/snippets/config/instances.enabled/etcd/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/etcd/config.yaml new file mode 100644 index 0000000000..e38344ebd9 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/etcd/config.yaml @@ -0,0 +1,5 @@ +config: + etcd: + endpoints: + - http://localhost:2379 + prefix: /example \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/etcd/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/etcd/instances.yml new file mode 100644 index 0000000000..6c765b2e67 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/etcd/instances.yml @@ -0,0 +1,3 @@ +instance001: +instance002: +instance003: \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/etcd_full/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/etcd_full/config.yaml new file mode 100644 index 0000000000..479314e097 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/etcd_full/config.yaml @@ -0,0 +1,12 @@ +config: + etcd: + endpoints: + - http://localhost:2379 + prefix: /example + username: testuser + password: foobar + ssl: + ca_file: ca.crt + http: + request: + timeout: 3 \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/etcd_full/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/etcd_full/instances.yml new file mode 100644 index 0000000000..6c765b2e67 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/etcd_full/instances.yml @@ -0,0 +1,3 @@ +instance001: +instance002: +instance003: \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/global_scope/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/global_scope/config.yaml new file mode 100644 index 0000000000..fbb6edb7de --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/global_scope/config.yaml @@ -0,0 +1,9 @@ +iproto: + listen: "3301" + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: {} \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/global_scope/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/global_scope/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/global_scope/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/group_scope/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/group_scope/config.yaml new file mode 100644 index 0000000000..8a226fd4db --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/group_scope/config.yaml @@ -0,0 +1,8 @@ +groups: + group001: + iproto: + listen: "3301" + replicasets: + replicaset001: + instances: + instance001: {} \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/group_scope/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/group_scope/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/group_scope/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/instance_scope/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/instance_scope/config.yaml new file mode 100644 index 0000000000..b2ecb4cafa --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/instance_scope/config.yaml @@ -0,0 +1,8 @@ +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: "3301" \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/instance_scope/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/instance_scope/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/instance_scope/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/replicaset_scope/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/replicaset_scope/config.yaml new file mode 100644 index 0000000000..52ecedf244 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/replicaset_scope/config.yaml @@ -0,0 +1,8 @@ +groups: + group001: + replicasets: + replicaset001: + iproto: + listen: "3301" + instances: + instance001: {} \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/replicaset_scope/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/replicaset_scope/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/replicaset_scope/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/templating/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/templating/config.yaml new file mode 100644 index 0000000000..5df487e662 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/templating/config.yaml @@ -0,0 +1,10 @@ +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + snapshot: + dir: ./var/{{ instance_name }}/snapshots + wal: + dir: ./var/{{ instance_name }}/wals \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/templating/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/templating/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/templating/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/tt.yaml b/doc/code_snippets/snippets/config/tt.yaml new file mode 100644 index 0000000000..66f9f7f7e1 --- /dev/null +++ b/doc/code_snippets/snippets/config/tt.yaml @@ -0,0 +1,63 @@ +tt: + modules: + # Directory where the external modules are stored. + directory: "modules" + + app: + # Directory that stores various instance runtime + # artifacts like console socket, PID file, etc. + run_dir: "var/run" + + # Directory that stores log files. + log_dir: var/log + + # The maximum size in MB of the log file before it gets rotated. + log_maxsize: 100 + + # The maximum number of days to retain old log files. + log_maxage: 8 + + # The maximum number of old log files to retain. + log_maxbackups: 10 + + # Restart instance on failure. + restart_on_failure: false + + # Directory where write-ahead log (.xlog) files are stored. + wal_dir: "var/lib" + + # Directory where memtx stores snapshot (.snap) files. + memtx_dir: "var/lib" + + # Directory where vinyl files or subdirectories will be stored. + vinyl_dir: "var/lib" + + # Directory that stores binary files. + bin_dir: "bin" + + # Directory that stores Tarantool header files. + inc_dir: "include" + + # Path to directory that stores all applications. + # The directory can also contain symbolic links to applications. + instances_enabled: "instances.enabled" + + # Tarantoolctl artifacts layout compatibility: if set to true tt will not create application + # sub-directories for control socket, pid files, log files, etc.. Data files (wal, vinyl, + # snap) and multi-instance applications are not affected by this option. + tarantoolctl_layout: false + + # Path to file with credentials for downloading Tarantool Enterprise Edition. + # credential_path: /path/to/file + ee: + credential_path: "" + + templates: + # The path to templates search directory. + - path: "templates" + + repo: + # Directory where local rocks files could be found. + rocks: "" + # Directory that stores installation files. + distfiles: "distfiles" diff --git a/doc/code_snippets/snippets/replication/instances.enabled/auto_leader/config.yaml b/doc/code_snippets/snippets/replication/instances.enabled/auto_leader/config.yaml new file mode 100644 index 0000000000..d5b42eed83 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/auto_leader/config.yaml @@ -0,0 +1,31 @@ +credentials: + users: + replicator: + password: 'topsecret' + roles: [replication] + +iproto: + advertise: + peer: replicator@ + +replication: + failover: election + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: 127.0.0.1:3301 + instance002: + iproto: + listen: 127.0.0.1:3302 + instance003: + iproto: + listen: 127.0.0.1:3303 + +# Load sample data +app: + file: 'data.lua' \ No newline at end of file diff --git a/doc/code_snippets/snippets/replication/instances.enabled/auto_leader/data.lua b/doc/code_snippets/snippets/replication/instances.enabled/auto_leader/data.lua new file mode 100644 index 0000000000..27b0b6bbf6 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/auto_leader/data.lua @@ -0,0 +1,32 @@ +function create_space() + box.schema.space.create('bands') + box.space.bands:format({ + { name = 'id', type = 'unsigned' }, + { name = 'band_name', type = 'string' }, + { name = 'year', type = 'unsigned' } + }) + box.space.bands:create_index('primary', { parts = { 'id' } }) +end + +function create_sync_space() + box.schema.space.create('bands', { is_sync = true }) + box.space.bands:format({ + { name = 'id', type = 'unsigned' }, + { name = 'band_name', type = 'string' }, + { name = 'year', type = 'unsigned' } + }) + box.space.bands:create_index('primary', { parts = { 'id' } }) +end + +function load_data() + box.space.bands:insert { 1, 'Roxette', 1986 } + box.space.bands:insert { 2, 'Scorpions', 1965 } + box.space.bands:insert { 3, 'Ace of Base', 1987 } + box.space.bands:insert { 4, 'The Beatles', 1960 } + box.space.bands:insert { 5, 'Pink Floyd', 1965 } + box.space.bands:insert { 6, 'The Rolling Stones', 1962 } + box.space.bands:insert { 7, 'The Doors', 1965 } + box.space.bands:insert { 8, 'Nirvana', 1987 } + box.space.bands:insert { 9, 'Led Zeppelin', 1968 } + box.space.bands:insert { 10, 'Queen', 1970 } +end diff --git a/doc/code_snippets/snippets/replication/instances.enabled/auto_leader/instances.yml b/doc/code_snippets/snippets/replication/instances.enabled/auto_leader/instances.yml new file mode 100644 index 0000000000..6c765b2e67 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/auto_leader/instances.yml @@ -0,0 +1,3 @@ +instance001: +instance002: +instance003: \ No newline at end of file diff --git a/doc/code_snippets/snippets/replication/instances.enabled/manual_leader/config.yaml b/doc/code_snippets/snippets/replication/instances.enabled/manual_leader/config.yaml new file mode 100644 index 0000000000..d4f315a1d4 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/manual_leader/config.yaml @@ -0,0 +1,35 @@ +credentials: + users: + replicator: + password: 'topsecret' + roles: [replication] + client: + password: 'secret' + roles: [super] + +iproto: + advertise: + peer: replicator@ + +replication: + failover: manual + +groups: + group001: + replicasets: + replicaset001: + leader: instance001 + instances: + instance001: + iproto: + listen: 127.0.0.1:3301 + instance002: + iproto: + listen: 127.0.0.1:3302 + instance003: + iproto: + listen: 127.0.0.1:3303 + +# Load sample data +app: + file: 'myapp.lua' \ No newline at end of file diff --git a/doc/code_snippets/snippets/replication/instances.enabled/manual_leader/instances.yml b/doc/code_snippets/snippets/replication/instances.enabled/manual_leader/instances.yml new file mode 100644 index 0000000000..6c765b2e67 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/manual_leader/instances.yml @@ -0,0 +1,3 @@ +instance001: +instance002: +instance003: \ No newline at end of file diff --git a/doc/code_snippets/snippets/replication/instances.enabled/manual_leader/myapp.lua b/doc/code_snippets/snippets/replication/instances.enabled/manual_leader/myapp.lua new file mode 100644 index 0000000000..27b0b6bbf6 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/manual_leader/myapp.lua @@ -0,0 +1,32 @@ +function create_space() + box.schema.space.create('bands') + box.space.bands:format({ + { name = 'id', type = 'unsigned' }, + { name = 'band_name', type = 'string' }, + { name = 'year', type = 'unsigned' } + }) + box.space.bands:create_index('primary', { parts = { 'id' } }) +end + +function create_sync_space() + box.schema.space.create('bands', { is_sync = true }) + box.space.bands:format({ + { name = 'id', type = 'unsigned' }, + { name = 'band_name', type = 'string' }, + { name = 'year', type = 'unsigned' } + }) + box.space.bands:create_index('primary', { parts = { 'id' } }) +end + +function load_data() + box.space.bands:insert { 1, 'Roxette', 1986 } + box.space.bands:insert { 2, 'Scorpions', 1965 } + box.space.bands:insert { 3, 'Ace of Base', 1987 } + box.space.bands:insert { 4, 'The Beatles', 1960 } + box.space.bands:insert { 5, 'Pink Floyd', 1965 } + box.space.bands:insert { 6, 'The Rolling Stones', 1962 } + box.space.bands:insert { 7, 'The Doors', 1965 } + box.space.bands:insert { 8, 'Nirvana', 1987 } + box.space.bands:insert { 9, 'Led Zeppelin', 1968 } + box.space.bands:insert { 10, 'Queen', 1970 } +end diff --git a/doc/code_snippets/snippets/replication/instances.enabled/master_master/config.yaml b/doc/code_snippets/snippets/replication/instances.enabled/master_master/config.yaml new file mode 100644 index 0000000000..85c7ee76dc --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/master_master/config.yaml @@ -0,0 +1,28 @@ +credentials: + users: + replicator: + password: 'topsecret' + roles: [replication] + +iproto: + advertise: + peer: replicator@ + +replication: + failover: off + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + database: + mode: rw + iproto: + listen: 127.0.0.1:3301 + instance002: + database: + mode: rw + iproto: + listen: 127.0.0.1:3302 \ No newline at end of file diff --git a/doc/code_snippets/snippets/replication/instances.enabled/master_master/instances.yml b/doc/code_snippets/snippets/replication/instances.enabled/master_master/instances.yml new file mode 100644 index 0000000000..75e286d69c --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/master_master/instances.yml @@ -0,0 +1,2 @@ +instance001: +instance002: \ No newline at end of file diff --git a/doc/code_snippets/snippets/replication/tt.yaml b/doc/code_snippets/snippets/replication/tt.yaml new file mode 100644 index 0000000000..66f9f7f7e1 --- /dev/null +++ b/doc/code_snippets/snippets/replication/tt.yaml @@ -0,0 +1,63 @@ +tt: + modules: + # Directory where the external modules are stored. + directory: "modules" + + app: + # Directory that stores various instance runtime + # artifacts like console socket, PID file, etc. + run_dir: "var/run" + + # Directory that stores log files. + log_dir: var/log + + # The maximum size in MB of the log file before it gets rotated. + log_maxsize: 100 + + # The maximum number of days to retain old log files. + log_maxage: 8 + + # The maximum number of old log files to retain. + log_maxbackups: 10 + + # Restart instance on failure. + restart_on_failure: false + + # Directory where write-ahead log (.xlog) files are stored. + wal_dir: "var/lib" + + # Directory where memtx stores snapshot (.snap) files. + memtx_dir: "var/lib" + + # Directory where vinyl files or subdirectories will be stored. + vinyl_dir: "var/lib" + + # Directory that stores binary files. + bin_dir: "bin" + + # Directory that stores Tarantool header files. + inc_dir: "include" + + # Path to directory that stores all applications. + # The directory can also contain symbolic links to applications. + instances_enabled: "instances.enabled" + + # Tarantoolctl artifacts layout compatibility: if set to true tt will not create application + # sub-directories for control socket, pid files, log files, etc.. Data files (wal, vinyl, + # snap) and multi-instance applications are not affected by this option. + tarantoolctl_layout: false + + # Path to file with credentials for downloading Tarantool Enterprise Edition. + # credential_path: /path/to/file + ee: + credential_path: "" + + templates: + # The path to templates search directory. + - path: "templates" + + repo: + # Directory where local rocks files could be found. + rocks: "" + # Directory that stores installation files. + distfiles: "distfiles" diff --git a/doc/concepts/configuration.rst b/doc/concepts/configuration.rst new file mode 100644 index 0000000000..2ad7e15c20 --- /dev/null +++ b/doc/concepts/configuration.rst @@ -0,0 +1,676 @@ +.. _configuration: + +Configuration +============= + +Tarantool provides the ability to configure the full topology of a cluster and set parameters specific for concrete instances, such as connection settings, memory used to store data, logging, and snapshot settings. +Each instance uses this configuration during :ref:`startup ` to organize the cluster. + +There are two approaches to configuring Tarantool: + +* *Since version 3.0*: In the YAML format. + + YAML configuration allows you to provide the full cluster topology and specify all configuration options. + You can use local configuration in a YAML file for each instance or store configuration data in one reliable place using :ref:`etcd `. + +* *In version 2.11 and earlier*: :ref:`In code ` using the ``box.cfg`` API. + + In this case, configuration is provided in a Lua initialization script. + + .. NOTE:: + + Starting with the 3.0 version, configuring Tarantool in code is considered a legacy approach. + + +.. _configuration_overview: + +Configuration overview +---------------------- + +YAML configuration describes the full topology of a Tarantool cluster. +A cluster's topology includes the following elements, starting from the lower level: + +.. code-block:: yaml + :emphasize-lines: 1,3,5 + + groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + # ... + instance002: + # ... + +- ``instances`` + + An *instance* represents a single running Tarantool instance. + It stores data or might act as a router for handling CRUD requests in a :ref:`sharded ` cluster. +- ``replicasets`` + + A *replica set* is a pack of instances that operate on same data sets. + :ref:`Replication ` provides redundancy and increases data availability. +- ``groups`` + + A *group* provides the ability to organize replica sets. + For example, in a sharded cluster, one group can contain :ref:`storage ` instances and another group can contain :ref:`routers ` used to handle CRUD requests. + +You can flexibly configure a cluster's settings on different levels: from global settings applied to all groups to parameters specific for concrete instances. + + +.. _configuration_file: + +Configuration in a file +~~~~~~~~~~~~~~~~~~~~~~~ + +This section provides an overview on how to configure Tarantool in a YAML file. + +.. _configuration_instance_basic: + +Basic instance configuration +**************************** + +The example below shows a sample configuration of a single Tarantool instance: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/instance_scope/config.yaml + :language: yaml + :dedent: + +- The ``instances`` section includes only one instance named *instance001*. + The ``iproto.listen`` option sets a port used to listen for incoming requests. +- The ``replicasets`` section contains one replica set named *replicaset001*. +- The ``groups`` section contains one group named *group001*. + + +.. _configuration_scopes: + +Configuration scopes +******************** + +This section shows how to control a scope the specified configuration option is applied to. +Most of the configuration options can be applied to a specific instance, replica set, group, or to all instances globally. + +- *Instance* + + To apply specific configuration options to a concrete instance, + specify such options for this instance only. + In the example below, ``iproto.listen`` is applied to *instance001* only. + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/instance_scope/config.yaml + :language: yaml + :emphasize-lines: 7-8 + :dedent: + +- *Replica set* + + In this example, ``iproto.listen`` is in effect for all instances in *replicaset001*. + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/replicaset_scope/config.yaml + :language: yaml + :emphasize-lines: 5-6 + :dedent: + +- *Group* + + In this example, ``iproto.listen`` is in effect for all instances in *group001*. + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/group_scope/config.yaml + :language: yaml + :emphasize-lines: 3-4 + :dedent: + +- *Global* + + In this example, ``iproto.listen`` is applied to all instances of the cluster. + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/global_scope/config.yaml + :language: yaml + :emphasize-lines: 1-2 + :dedent: + + +.. NOTE:: + + The :ref:`Configuration reference ` contains information about scopes to which each configuration option can be applied. + + +.. _configuration_replica_set_scopes: + +Configuration scopes: Replica set example +***************************************** + +The example below shows how specific configuration options work in different configuration scopes for a replica set with a manual failover. +You can learn more about configuring replication from :ref:`Replication tutorials `. + +.. literalinclude:: /code_snippets/snippets/replication/instances.enabled/manual_leader/config.yaml + :language: yaml + :end-before: Load sample data + :dedent: + +- ``credentials`` (*global*) + + This section is used to create the *replicator* and *client* users and assign them the specified roles. + These options are applied globally to all instances. + +- ``iproto`` (*global*, *instance*) + + The ``iproto`` section is specified on both global and instance levels. + The ``iproto.advertise.peer`` option specifies a URI used by an instance to connect to another instance as a replica. + In the example above, the URI includes a user name only. + A host value is taken from ``iproto.listen`` that is set on the instance level. + +- ``replication``: (*global*) + + The ``replication.failover`` global option sets a manual failover for all replica sets. + +- ``leader``: (*replica set*) + + The ``.leader`` option sets a :ref:`master ` instance for *replicaset001*. + + + +.. _configuration_application: + +Loading an application +********************** + +Using Tarantool as an application server, you can run your own Lua applications. +In the ``app`` section, you can load the application and provide a custom application configuration in the ``cfg`` section. + +In the example below, the application is loaded from the ``myapp.lua`` file placed next to the YAML configuration file: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/application/config.yaml + :language: yaml + :dedent: + +To get a value of the custom ``greeting`` property in the application code, +use the ``config:get()`` function provided by the :ref:`config ` module. + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/application/myapp.lua + :language: lua + :dedent: + +As a result of :ref:`starting ` the *instance001*, a log should contain the following line: + +.. code-block:: console + + main/103/interactive/myapp I> Hello from app, instance001! + +The ``app`` section can be placed in any :ref:`configuration scope `. +As an example use case, you can provide different applications for storages and routers in a sharded cluster: + +.. code-block:: yaml + + groups: + storages: + app: + module: storage + # ... + routers: + app: + module: router + # ... + +Learn more about using Tarantool as the application server from :ref:`Developing applications with Tarantool `. + + + +.. _configuration_predefined_variables: + +Predefined variables +******************** + +In a configuration file, you can use the following predefined variables that are replaced with actual values at runtime: + +- ``instance_name`` +- ``replicaset_name`` +- ``group_name`` + +To reference these variables in a configuration file, enclose them in double curly braces with whitespaces. +In the example below, ``{{ instance_name }}`` is replaced with *instance001*. + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/templating/config.yaml + :language: yaml + :dedent: + +As a result, the :ref:`paths to snapshots and write-ahead logs ` differ for different instances. + + + +.. _configuration_environment_variable: + +Environment variables +~~~~~~~~~~~~~~~~~~~~~ + +For each configuration parameter, Tarantool provides two sets of predefined environment variables: + +* ``TT_``. These variables are used to substitute parameters specified in a configuration file. + This means that these variables have a higher :ref:`priority ` than the options specified in a configuration file. + +* ``TT__DEFAULT``. These variables are used to specify default values for parameters missing in a configuration file. + These variables have a lower :ref:`priority ` than the options specified in a configuration file. + +For example, ``TT_IPROTO_LISTEN`` and ``TT_IPROTO_LISTEN_DEFAULT`` correspond to the ``iproto.listen`` option. +``TT_SNAPSHOT_DIR`` and ``TT_SNAPSHOT_DIR_DEFAULT`` correspond to the ``snapshot.dir`` option. +To see all the supported environment variables, execute the ``tarantool`` command with the ``--help-env-list`` :ref:`option `. + +.. code-block:: console + + $ tarantool --help-env-list + +Below are a few examples that show how to set environment variables of different types, like *string*, *number*, *array*, or *map*: + +* String. In the example below, ``TT_IPROTO_LISTEN`` is used to specify a :ref:`listening host and port ` values: + + .. code-block:: console + + $ export TT_IPROTO_LISTEN='127.0.0.1:3311' + + To specify several listening addresses, separate them by a comma without space: + + .. code-block:: console + + $ export TT_IPROTO_LISTEN='127.0.0.1:3311,127.0.0.1:3312' + +* Number. In this example, ``TT_LOG_LEVEL`` is used to set a logging level to 3 (``CRITICAL``): + + .. code-block:: console + + $ export TT_LOG_LEVEL=3 + +* Array. The examples below show how to set the ``TT_SHARDING_ROLES`` variable that accepts an array value. + Arrays can be passed in two ways: using a *simple* ... + + .. code-block:: console + + $ export TT_SHARDING_ROLES=router,storage + + ... or *JSON* format: + + .. code-block:: console + + $ export TT_SHARDING_ROLES='["router", "storage"]' + + The *simple* format is applicable only to arrays containing scalar values. + +* Map. To assign map values to environment variables, you can also use *simple* or *JSON* formats. + In the example below, ``TT_LOG_MODULES`` sets different logging levels for different modules using a *simple* format: + + .. code-block:: console + + $ export TT_LOG_MODULES=module1=info,module2=error + + In the next example, ``TT_APP_CFG`` is used to specify the value of a custom configuration property for a :ref:`loaded application ` using a *JSON* format: + + .. code-block:: console + + $ export TT_APP_CFG='{"greeting":"Hi"}' + + The *simple* format is applicable only to maps containing scalar values. + + +.. NOTE:: + + There are also special ``TT_INSTANCE_NAME`` and ``TT_CONFIG`` environment variables that can be used to :ref:`start ` the specified Tarantool instance with configuration from the given file. + + + + + + +.. _configuration_etcd_overview: + +Configuration in etcd +~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /concepts/configuration/configuration_etcd.rst + :start-after: ee_note_etcd_start + :end-before: ee_note_etcd_end + +Tarantool enables you to store configuration data in one reliable place using `etcd `_. +To achieve this, you need to: + +1. Provide a local YAML configuration with an etcd endpoint address and key prefix in the ``config`` section: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/etcd/config.yaml + :language: yaml + :dedent: + +2. Publish a cluster's configuration to an etcd server. + +Learn more from the following guide: :ref:`Storing configuration in etcd `. + + +.. _configuration_precedence: + +Configuration precedence +~~~~~~~~~~~~~~~~~~~~~~~~ + +Tarantool configuration options are applied from multiple sources with the following precedence, from highest to lowest: + +- `TT_*` :ref:`environment variables `. +- Configuration from a :ref:`local YAML file `. +- :ref:`Centralized configuration ` stored in etcd. +- `TT_*_DEFAULT` :ref:`environment variables `. + +If the same option is defined in two or more locations, the option with the highest precedence is applied. + + + +.. _configuration_options_overview: + +Configuration options overview +------------------------------ + +This section gives an overview of some useful configuration options. +All the available options are documented in the :ref:`Configuration reference `. + +.. _configuration_options_connection: + +Connection settings +~~~~~~~~~~~~~~~~~~~ + +To configure an address used to listen for incoming requests, use the ``iproto.listen`` option. +Below are a few examples on how to do this: + +* Set a listening port to ``3301``: + + .. code-block:: yaml + + iproto: + listen: "3301" + +* Set a listening address to ``127.0.0.1:3301``: + + .. code-block:: yaml + + iproto: + listen: "127.0.0.1:3301" + + +* Configure several listening addresses: + + .. code-block:: yaml + + iproto: + listen: "127.0.0.1:3301,127.0.0.1:3303" + +* Enables :ref:`traffic encryption ` for a connection using corresponding URI parameters: + + .. code-block:: yaml + + iproto: + listen: "127.0.0.1:3301?transport=ssl&ssl_key_file=localhost.key&ssl_cert_file=localhost.crt&ssl_ca_file=ca.crt" + + Note that traffic encryption is supported by the `Enterprise Edition `_ only. + + +* Use a Unix domain socket: + + .. code-block:: yaml + + iproto: + listen: "unix/:./var/run/{{ instance_name }}/tarantool.iproto" + + +.. _configuration_options_access_control: + +Access control +~~~~~~~~~~~~~~ + +The ``credentials`` section allows you to create users and grant them the specified privileges. +In the example below, there are two users: + +* The *replicator* user is used for replication and has a corresponding role. +* The *client* user has the ``super`` role and can perform any action on Tarantool instances. + +.. literalinclude:: /code_snippets/snippets/replication/instances.enabled/manual_leader/config.yaml + :language: yaml + :lines: 1-8 + :dedent: + +To learn more, see the :ref:`Access control ` section. + + +.. _configuration_options_memory: + +Memory +~~~~~~ + +The ``memtx.memory`` option specifies how much :ref:`memory ` Tarantool allocates to actually store data. + +.. code-block:: yaml + + memtx: + memory: 100000000 + +When the limit is reached, ``INSERT`` or ``UPDATE`` requests fail with :ref:`ER_MEMORY_ISSUE `. + + +.. _configuration_options_directories: + +Snapshots and write-ahead logs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``snapshot.dir`` and ``wal.dir`` options can be used to configure directories for storing snapshots and write-ahead logs. +For example, you can place snapshots and write-ahead logs on different hard drives for better reliability. + +.. code-block:: yaml + + instance001: + snapshot: + dir: '/media/drive1/snapshots' + wal: + dir: '/media/drive2/wals' + +To learn more about the persistence mechanism in Tarantool, see the :ref:`Persistence ` section. + + +.. _configuration_run_instance: + +Starting Tarantool instances +---------------------------- + +.. _configuration_run_instance_tt: + +Starting instances using the tt utility +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The :ref:`tt ` utility is the recommended way to start Tarantool instances. + +Instance files or directories are organized into applications in the ``instances_enabled`` directory. +The example below shows how a :ref:`layout ` of the application called ``app`` might look: + +.. code-block:: none + + ├── tt.yaml + └── instances.enabled + └── app + ├── config.yaml + ├── myapp.lua + └── instances.yml + +* ``config.yaml`` is a :ref:`configuration file `. +* ``myapp.lua`` is a Lua script containing an :ref:`application to load `. +* ``instances.yml`` specifies :ref:`instances ` to run in the current environment. + This file might look as follows: + + .. literalinclude:: /code_snippets/snippets/replication/instances.enabled/manual_leader/instances.yml + :language: yaml + :dedent: + +To start all instances, use the ``tt start app`` command: + + .. code-block:: console + + $ tt start app + • Starting an instance [app:instance001]... + • Starting an instance [app:instance002]... + • Starting an instance [app:instance003]... + +Then, you can connect to Tarantool instances by its names using the ``tt connect`` command. +You can learn more from the :ref:`Starting and stopping instances ` section. + + + +.. _configuration_run_instance_tarantool: + +Starting an instance using the tarantool command +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``tarantool`` command provides additional :ref:`options ` that might be helpful for development purposes. +Below is the syntax for starting a Tarantool instance configured in a file: + +.. code-block:: console + + $ tarantool [OPTION ...] --name INSTANCE_NAME --config CONFIG_FILE_PATH + +The command below starts ``instance001`` configured in the ``config.yaml`` file: + +.. code-block:: console + + $ tarantool --name instance001 --config config.yaml + + +.. _configuration_command_options: + +Command-line options +******************** + +Options that can be passed when :ref:`starting a Tarantool instance `: + +.. option:: -h, --help + + Print an annotated list of all available options and exit. + +.. option:: --help-env-list + + **Since:** :doc:`3.0.0 `. + + Show a list of :ref:`environment variables ` that can be used to configure Tarantool. + +.. _index-tarantool_version: + +.. option:: -v, -V, --version + + Print the product name and version. + + **Example** + + .. code-block:: console + + % tarantool --version + Tarantool 3.0.0-entrypoint-746-g36ef3fb43 + Target: Darwin-arm64-Release + ... + + In this example: + + * ``3.0.0`` is a Tarantool version. + Tarantool follows semantic versioning, which is described in the :ref:`Tarantool release policy ` section. + + * ``Target`` is the platform Tarantool is built on. + Platform-specific details may follow this line. + + +.. option:: -c, --config PATH + + **Since:** :doc:`3.0.0 `. + + Set a path to a :ref:`YAML configuration file `. + You can also configure this value using the ``TT_CONFIG`` environment variable. + + See also: :ref:`Starting an instance using the tarantool command ` + +.. option:: -n, --name INSTANCE + + **Since:** :doc:`3.0.0 `. + + Set the name of an instance to run. + You can also configure this value using the ``TT_INSTANCE_NAME`` environment variable. + + See also: :ref:`Starting an instance using the tarantool command ` + + +.. option:: -i + + Enter an :ref:`interactive mode `. + + **Example** + + .. code-block:: console + + % tarantool -i + + +.. option:: -e EXPR + + Execute the 'EXPR' string. See also: `lua man page `_. + + **Example** + + .. code-block:: console + + % tarantool -e "print('Hello, world!')" + Hello, world! + +.. option:: -l NAME + + Require the 'NAME' library. See also: `lua man page `_. + + **Example** + + .. code-block:: console + + % tarantool -l luatest.coverage script.lua + +.. option:: -j cmd + + Perform a LuaJIT control command. See also: `Command Line Options `_. + + **Example** + + .. code-block:: console + + % tarantool -j off app.lua + +.. option:: -b ... + + Save or list bytecode. See also: `Command Line Options `_. + + **Example** + + .. code-block:: console + + % tarantool -b test.lua test.out + +.. option:: -d SCRIPT + + Activate a debugging session for 'SCRIPT'. See also: `luadebug.lua `_. + + **Example** + + .. code-block:: console + + % tarantool -d app.lua + + +.. option:: -- + + Stop handling options. See also: `lua man page `_. + + +.. option:: - + + Stop handling options and execute the standard input as a file. See also: `lua man page `_. + + + + +.. toctree:: + :hidden: + + configuration/configuration_etcd + configuration/configuration_code + configuration/configuration_migrating diff --git a/doc/concepts/configuration/configuration_code.rst b/doc/concepts/configuration/configuration_code.rst new file mode 100644 index 0000000000..09263fea9f --- /dev/null +++ b/doc/concepts/configuration/configuration_code.rst @@ -0,0 +1,340 @@ +.. _configuration_code: + +Configuration in code +===================== + +.. box_cfg_legacy_note_start + +.. NOTE:: + + Starting with the 3.0 version, the recommended way of configuring Tarantool is using a :ref:`configuration file `. + Configuring Tarantool in code is considered a legacy approach. + +.. box_cfg_legacy_note_end + +This topic covers the specifics of configuring Tarantool in code using the ``box.cfg`` API. +In this case, a configuration is stored in an :ref:`initialization file ` - a Lua script with the specified configuration options. +You can find all the available options in the :ref:`Configuration reference `. + + +.. _index-init_label: + +Initialization file +------------------- + +If the command to :ref:`start Tarantool ` includes an instance file, then +Tarantool begins by invoking the Lua program in the file, which may have the name ``init.lua``. +The Lua program may get further arguments +from the command line or may use operating-system functions, such as ``getenv()``. +The Lua program almost always begins by invoking ``box.cfg()``, if the database +server will be used or if ports need to be opened. For example, suppose +``init.lua`` contains the lines + +.. _index-init-example: + +.. code-block:: lua + + #!/usr/bin/env tarantool + box.cfg{ + listen = os.getenv("LISTEN_URI"), + memtx_memory = 33554432, + pid_file = "tarantool.pid", + wal_max_size = 2500 + } + print('Starting ', arg[1]) + +and suppose the environment variable ``LISTEN_URI`` contains 3301, +and suppose the command line is ``tarantool init.lua ARG``. +Then the screen might look like this: + +.. code-block:: console + + $ export LISTEN_URI=3301 + $ tarantool init.lua ARG + ... main/101/init.lua C> Tarantool 2.8.3-0-g01023dbc2 + ... main/101/init.lua C> log level 5 + ... main/101/init.lua I> mapping 33554432 bytes for memtx tuple arena... + ... main/101/init.lua I> recovery start + ... main/101/init.lua I> recovering from './00000000000000000000.snap' + ... main/101/init.lua I> set 'listen' configuration option to "3301" + ... main/102/leave_local_hot_standby I> ready to accept requests + Starting ARG + ... main C> entering the event loop + +If you wish to start an interactive session on the same terminal after +initialization is complete, you can pass the ``-i`` :ref:`command-line option `. + + +.. _box-cfg-params-env: + +Environment variables +--------------------- + +Starting from version :doc:`2.8.1 `, you can specify configuration parameters via special environment variables. +The name of a variable should have the following pattern: ``TT_``, +where ```` is the uppercase name of the corresponding :ref:`box.cfg parameter `. + +For example: + +* ``TT_LISTEN`` -- corresponds to the :ref:`box.cfg.listen ` option. +* ``TT_MEMTX_DIR`` -- corresponds to the :ref:`box.cfg.memtx_dir ` option. + +In case of an array value, separate the array elements by a comma without space: + +.. code-block:: console + + export TT_REPLICATION="localhost:3301,localhost:3302" + +If you need to pass :ref:`additional parameters for URI `, use the ``?`` and ``&`` delimiters: + +.. code-block:: console + + export TT_LISTEN="localhost:3301?param1=value1¶m2=value2" + +An empty variable (``TT_LISTEN=``) has the same effect as an unset one, meaning that the corresponding configuration parameter won't be set when calling ``box.cfg{}``. + + + +.. _index-local_hot_standby: +.. _index-replication_port: +.. _index-slab_alloc_arena: +.. _index-replication_source: +.. _index-snap_dir: +.. _index-wal_dir: +.. _index-wal_mode: +.. _index-checkpoint daemon: + +.. _box_cfg_params: + + +Configuration parameters +------------------------ + +Configuration parameters have the form: + +:extsamp:`{**{box.cfg}**}{[{*{key = value}*} [, {*{key = value ...}*}]]}` + +Configuration parameters can be set in a Lua :ref:`initialization file `, +which is specified on the Tarantool command line. + +Most configuration parameters are for allocating resources, opening ports, and +specifying database behavior. All parameters are optional. +Most of the parameters are dynamic, that is, they can be changed at runtime by calling ``box.cfg{}`` a second time. +For example, the command below sets the :ref:`listen port ` to ``3301``. + +.. code-block:: tarantoolsession + + tarantool> box.cfg{ listen = 3301 } + 2023-05-10 13:28:54.667 [31326] main/103/interactive I> tx_binary: stopped + 2023-05-10 13:28:54.667 [31326] main/103/interactive I> tx_binary: bound to [::]:3301 + 2023-05-10 13:28:54.667 [31326] main/103/interactive/box.load_cfg I> set 'listen' configuration option to 3301 + --- + ... + + +To see all the non-null parameters, execute ``box.cfg`` (no parentheses). + +.. code-block:: tarantoolsession + + tarantool> box.cfg + --- + - replication_skip_conflict: false + wal_queue_max_size: 16777216 + feedback_host: https://feedback.tarantool.io + memtx_dir: . + memtx_min_tuple_size: 16 + -- other parameters -- + ... + +To see a particular parameter value, call a corresponding ``box.cfg`` option. +For example, ``box.cfg.listen`` shows the specified :ref:`listen address `. + +.. code-block:: tarantoolsession + + tarantool> box.cfg.listen + --- + - 3301 + ... + + + +.. _index-uri: + +Listen URI +---------- + +Some configuration parameters and some functions depend on a URI (Universal Resource Identifier). +The URI string format is similar to the +`generic syntax for a URI schema `_. +It may contain (in order): + +* user name for login +* password +* host name or host IP address +* port number +* query parameters + +Only a port number is always mandatory. A password is mandatory if a user +name is specified unless the user name is 'guest'. + +Formally, the URI +syntax is ``[host:]port`` or ``[username:password@]host:port``. +If a host is omitted, then "0.0.0.0" or "[::]" is assumed, +meaning respectively any IPv4 address or any IPv6 address +on the local machine. +If ``username:password`` is omitted, then the "guest" user is assumed. Some examples: + +.. container:: table + + .. rst-class:: left-align-column-1 + .. rst-class:: left-align-column-2 + + +-----------------------------+------------------------------+ + | URI fragment | Example | + +=============================+==============================+ + | port | 3301 | + +-----------------------------+------------------------------+ + | host:port | 127.0.0.1:3301 | + +-----------------------------+------------------------------+ + | username:password@host:port | notguest:sesame@mail.ru:3301 | + +-----------------------------+------------------------------+ + +In code, the URI value can be passed as a number (if only a port is specified) or a string: + +.. code-block:: lua + + box.cfg { listen = 3301 } + + box.cfg { listen = "127.0.0.1:3301" } + +In certain circumstances, a Unix domain socket may be used +where a URI is expected, for example, ``unix/:/tmp/unix_domain_socket.sock`` or +simply ``/tmp/unix_domain_socket.sock``. + +The :ref:`uri ` module provides functions that convert URI strings into their +components or turn components into URI strings. + +.. _index-uri-several: + +Specifying several URIs +~~~~~~~~~~~~~~~~~~~~~~~ + +Starting from version 2.10.0, a user can open several listening iproto sockets on a Tarantool instance +and, consequently, can specify several URIs in the configuration parameters +such as :ref:`box.cfg.listen ` and :ref:`box.cfg.replication `. + +URI values can be set in a number of ways: + +* As a string with URI values separated by commas. + + .. code-block:: lua + + box.cfg { listen = "127.0.0.1:3301, /unix.sock, 3302" } + +* As a table that contains URIs in the string format. + + .. code-block:: lua + + box.cfg { listen = {"127.0.0.1:3301", "/unix.sock", "3302"} } + +* As an array of tables with the ``uri`` field. + + .. code-block:: lua + + box.cfg { listen = { + {uri = "127.0.0.1:3301"}, + {uri = "/unix.sock"}, + {uri = 3302} + } + } + +* In a combined way -- an array that contains URIs in both the string and the table formats. + + .. code-block:: lua + + box.cfg { listen = { + "127.0.0.1:3301", + { uri = "/unix.sock" }, + { uri = 3302 } + } + } + +.. _index-uri-several-params: + +Also, starting from version 2.10.0, it is possible to specify additional parameters for URIs. +You can do this in different ways: + +* Using the ``?`` delimiter when URIs are specified in a string format. + + .. code-block:: lua + + box.cfg { listen = "127.0.0.1:3301?p1=value1&p2=value2, /unix.sock?p3=value3" } + +* Using the ``params`` table: a URI is passed in a table with additional parameters in the "params" table. + Parameters in the "params" table overwrite the ones from a URI string ("value2" overwrites "value1" for ``p1`` in the example below). + + .. code-block:: lua + + box.cfg { listen = { + "127.0.0.1:3301?p1=value1", + params = {p1 = "value2", p2 = "value3"} + } + } + +* Using the ``default_params`` table for specifying default parameter values. + + In the example below, two URIs are passed in a table. + The default value for the ``p3`` parameter is defined in the ``default_params`` table + and used if this parameter is not specified in URIs. + Parameters in the ``default_params`` table are applicable to all the URIs passed in a table. + + .. code-block:: lua + + box.cfg { listen = { + "127.0.0.1:3301?p1=value1", + { uri = "/unix.sock", params = { p2 = "value2" } }, + default_params = { p3 = "value3" } + } + } + +The recommended way for specifying URI with additional parameters is the following: + +.. code-block:: lua + + box.cfg { listen = { + {uri = "127.0.0.1:3301", params = {p1 = "value1"}}, + {uri = "/unix.sock", params = {p2 = "value2"}}, + {uri = 3302, params = {p3 = "value3"}} + } + } + +In case of a single URI, the following syntax also works: + +.. code-block:: lua + + box.cfg { listen = { + uri = "127.0.0.1:3301", + params = { p1 = "value1", p2 = "value2" } + } + } + + + +.. _configuration_code_run_instance_tarantool: + +Starting a Tarantool instance +----------------------------- + +Below is the syntax for starting a Tarantool instance configured in a Lua initialization script: + +.. code-block:: console + + $ tarantool LUA_INITIALIZATION_FILE [OPTION ...] + +The ``tarantool`` command also provides a set of :ref:`options ` that might be helpful for development purposes. + +The command below starts a Tarantool instance configured in the ``init.lua`` file: + +.. code-block:: console + + $ tarantool init.lua diff --git a/doc/concepts/configuration/configuration_etcd.rst b/doc/concepts/configuration/configuration_etcd.rst new file mode 100644 index 0000000000..37ad8dcbe3 --- /dev/null +++ b/doc/concepts/configuration/configuration_etcd.rst @@ -0,0 +1,173 @@ +.. _configuration_etcd: + +Storing configuration in etcd +============================= + +.. ee_note_etcd_start + +.. admonition:: Enterprise Edition + :class: fact + + Storing configuration in etcd is supported by the `Enterprise Edition `_ only. + +.. ee_note_etcd_end + +Tarantool enables you to store configuration data in one place using `etcd `_. +To achieve this, you need to define how to access etcd and publish a cluster's :ref:`YAML configuration ` to an etcd server. + + +.. _etcd_local_configuration: + +Local etcd configuration +------------------------ + +To store a cluster's configuration in etcd, you need to provide etcd connection settings in a local configuration file. +These settings are used to :ref:`publish ` a cluster's configuration and :ref:`show ` it. + +Connection options for etcd should be specified in the ``config.etcd`` section of the configuration file. +At least, the following options should be specified: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/etcd/config.yaml + :language: yaml + :dedent: + +- :ref:`config.etcd.endpoints ` specifies the list of etcd endpoints. +- :ref:`config.etcd.prefix ` sets a key prefix used to search a configuration. Tarantool searches keys by the following path: ``/config/*``. Note that ```` should start with a slash (``/``). + +You can also provide additional etcd connection options. +In the example below, the following options are configured in addition to an endpoint and key prefix: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/etcd_full/config.yaml + :language: yaml + :dedent: + +- :ref:`config.etcd.username ` and :ref:`config.etcd.password ` specify credentials used for authentication. +- :ref:`config.etcd.ssl.ca_file ` specifies a path to a trusted certificate authorities (CA) file. +- :ref:`config.etcd.http.request.timeout ` configures a request timeout for an etcd server. + +You can find all the available configuration options in the :ref:`etcd ` section. + + + +.. _etcd_publishing_configuration: + +Publishing a cluster's configuration to etcd +-------------------------------------------- + +.. _etcd_publishing_configuration_tt: + +Publishing configuration using the tt utility +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The tt utility provides the :ref:`tt cluster ` command for managing a cluster's configuration. +The ``tt cluster publish`` command can be used to publish a cluster's configuration to etcd. + +The example below shows how a :ref:`layout ` of the application called ``app`` might look: + +.. code-block:: none + + ├── tt.yaml + └── instances.enabled + └── app + ├── config.yaml + ├── cluster.yaml + └── instances.yml + +* ``config.yaml`` contains a :ref:`local configuration ` used to connect to etcd. +* ``cluster.yaml`` contains a cluster's configuration to be published. +* ``instances.yml`` specifies :ref:`instances ` to run in the current environment. ``tt cluster publish`` ignores the configured instances. + +To publish a cluster's configuration (``cluster.yaml``) to an etcd server, execute ``tt cluster publish`` as follows: + +.. code-block:: console + + $ tt cluster publish "http://localhost:2379/example" instances.enabled/app/cluster.yaml + +.. NOTE:: + + You can see a cluster's configuration using the :ref:`tt cluster show ` command. + + +.. _etcd_publishing_configuration_etcdctl: + +Publishing configuration using etcdctl +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To publish a cluster's configuration using the ``etcdctl`` utility, use the ``put`` command: + +.. code-block:: console + + $ etcdctl put /example/config/all < cluster.yaml + + + + +.. _etcd_starting_instances: + +Starting Tarantool instances +---------------------------- + +The :ref:`tt ` utility is the recommended way to start Tarantool instances. +You can learn how to do this from the :ref:`Starting instances using the tt utility ` section. + +You can also use the ``tarantool`` command to :ref:`start a Tarantool instance `. +In this case, you can eliminate creating a :ref:`local etcd configuration ` and provide etcd connection settings using the ``TT_CONFIG_ETCD_ENDPOINTS`` and ``TT_CONFIG_ETCD_PREFIX`` :ref:`environment variables `. + +.. code-block:: console + + $ export TT_CONFIG_ETCD_ENDPOINTS=http://localhost:2379 + $ export TT_CONFIG_ETCD_PREFIX=/example + + $ tarantool --name instance001 + $ tarantool --name instance002 + $ tarantool --name instance003 + + + + +.. _etcd_reloading_configuration: + +Reloading configuration +----------------------- + +By default, Tarantool watches etcd keys with the :ref:`specified prefix ` for changes in a cluster's configuration and reloads a changed configuration automatically. +If necessary, you can set the :ref:`config.reload ` option to ``manual`` to turn off configuration reloading: + +.. code-block:: yaml + + config: + reload: 'manual' + etcd: + # ... + +In this case, you can reload a configuration in an :ref:`admin console ` or :ref:`application code ` using the ``reload()`` function provided by the :ref:`config ` module: + +.. code-block:: lua + + require('config'):reload() + + + + + + + + + +.. + Generating certificates for testing: + 1) openssl genrsa -out ca.key 2048 + 2) openssl req -new -x509 -days 365 -key ca.key -subj "/C=CN/ST=GD/L=SZ/O=Acme, Inc./CN=Acme Root CA" -out ca.cr + 3) openssl req -newkey rsa:2048 -nodes -keyout server.key -subj "/C=CN/ST=GD/L=SZ/O=Acme, Inc./CN=localhost" -out server.csr + 4) openssl x509 -req -extfile <(printf "subjectAltName=DNS:localhost,IP:127.0.0.1") -days 365 -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt + 5) sudo cp server.crt /etc/ssl/certs + 6) sudo cp server.key /etc/ssl/private + + Starting etcd: + etcd --cert-file=ssl/server.crt --key-file=ssl/server.key --advertise-client-urls=https://localhost:2379 --listen-client-urls=https://localhost:2379 + + Get keys: + etcdctl get /tt/config/all --cert=ssl/server.crt --key=ssl/server.key + + Test using curl: + curl --cacert ssl/ca.crt https://localhost:2379/v2/keys/foo -XPUT -d value=bar -v \ No newline at end of file diff --git a/doc/concepts/configuration/configuration_migrating.rst b/doc/concepts/configuration/configuration_migrating.rst new file mode 100644 index 0000000000..c557d741ae --- /dev/null +++ b/doc/concepts/configuration/configuration_migrating.rst @@ -0,0 +1,9 @@ +.. _configuration_migrating_declarative: + +Migrating to declarative configuration +====================================== + +.. TODO + https://github.com/tarantool/doc/issues/3661 + 1) Configuration applying idempotence: how the config's 'target state' approach differs from the 'state changes' box.cfg() approach. + 2) How non-dynamic box.cfg() options are applied (no error, wait for restart). diff --git a/doc/concepts/index.rst b/doc/concepts/index.rst index 6d87c220f2..46bcfe065a 100644 --- a/doc/concepts/index.rst +++ b/doc/concepts/index.rst @@ -111,6 +111,7 @@ For details, check the :ref:`Storage engines ` section. .. toctree:: :hidden: + configuration data_model/index coop_multitasking atomic diff --git a/doc/reference/configuration/configuration_reference.rst b/doc/reference/configuration/configuration_reference.rst new file mode 100644 index 0000000000..2fa2ad79f6 --- /dev/null +++ b/doc/reference/configuration/configuration_reference.rst @@ -0,0 +1,226 @@ +.. _configuration_reference: + +Configuration reference +======================= + +This topic describes all :ref:`configuration parameters ` provided by Tarantool. + +.. _configuration_reference_config: + +config +------ + +* :ref:`config.reload ` +* :ref:`config.version ` +* :ref:`config.etcd.* ` + +.. _configuration_reference_config_reload: + +.. confval:: config.reload + + **Since:** :doc:`3.0.0 `. + + Specify how the configuration is reloaded. + This option accepts the following values: + + - ``auto``: configuration is reloaded automatically when it is changed. + - ``manual``: configuration should be reloaded manually. In this case, you can reload the configuration in the application code using :ref:`config:reload() `. + + See also: :ref:`Reloading configuration `. + + | Type: string + | Possible values: 'auto', 'manual' + | Default: 'auto' + | Environment variable: TT_CONFIG_RELOAD + + +.. _configuration_reference_config_version: + +.. confval:: config.version + + **Since:** :doc:`3.0.0 `. + + A configuration version. + + | Type: string + | Default: nil + | Environment variable: TT_CONFIG_VERSION + + + +.. _configuration_reference_config_etcd: + +etcd +~~~~ + +.. include:: /concepts/configuration/configuration_etcd.rst + :start-after: ee_note_etcd_start + :end-before: ee_note_etcd_end + +This section describes options related to :ref:`storing configuration in etcd `. + +* :ref:`config.etcd.endpoints ` +* :ref:`config.etcd.prefix ` +* :ref:`config.etcd.username ` +* :ref:`config.etcd.password ` +* :ref:`config.etcd.ssl.ca_file ` +* :ref:`config.etcd.ssl.ca_path ` +* :ref:`config.etcd.ssl.ssl_key ` +* :ref:`config.etcd.ssl.verify_host ` +* :ref:`config.etcd.ssl.verify_peer ` +* :ref:`config.etcd.http.request.timeout ` +* :ref:`config.etcd.http.request.unix_socket ` + + + +.. _config_etcd_endpoints: + +.. confval:: config.etcd.endpoints + + **Since:** :doc:`3.0.0 `. + + The list of endpoints used to access an etcd server. + + See also: :ref:`Local etcd configuration `. + + | Type: array + | Default: nil + | Environment variable: TT_CONFIG_ETCD_ENDPOINTS + + +.. _config_etcd_prefix: + +.. confval:: config.etcd.prefix + + **Since:** :doc:`3.0.0 `. + + A key prefix used to search a configuration on an etcd server. + Tarantool searches keys by the following path: ``/config/*``. + Note that ```` should start with a slash (``/``). + + See also: :ref:`Local etcd configuration `. + + | Type: string + | Default: nil + | Environment variable: TT_CONFIG_ETCD_PREFIX + +.. _config_etcd_username: + +.. confval:: config.etcd.username + + **Since:** :doc:`3.0.0 `. + + A username used for authentication. + + | Type: string + | Default: nil + | Environment variable: TT_CONFIG_ETCD_USERNAME + +.. _config_etcd_password: + +.. confval:: config.etcd.password + + **Since:** :doc:`3.0.0 `. + + A password used for authentication. + + | Type: string + | Default: nil + | Environment variable: TT_CONFIG_ETCD_PASSWORD + + +.. _config_etcd_ssl_ca_file: + +.. confval:: config.etcd.ssl.ca_file + + **Since:** :doc:`3.0.0 `. + + A path to a trusted certificate authorities (CA) file. + + | Type: string + | Default: nil + | Environment variable: TT_CONFIG_ETCD_SSL_CA_FILE + + +.. _config_etcd_ssl_ca_path: + +.. confval:: config.etcd.ssl.ca_path + + **Since:** :doc:`3.0.0 `. + + A path to a directory holding certificates to verify the peer with. + + | Type: string + | Default: nil + | Environment variable: TT_CONFIG_ETCD_SSL_CA_PATH + + +.. _config_etcd_ssl_ssl_key: + +.. confval:: config.etcd.ssl.ssl_key + + **Since:** :doc:`3.0.0 `. + + A path to a private SSL key file. + + | Type: string + | Default: nil + | Environment variable: TT_CONFIG_ETCD_SSL_SSL_KEY + + +.. _config_etcd_ssl_verify_host: + +.. confval:: config.etcd.ssl.verify_host + + **Since:** :doc:`3.0.0 `. + + Enable verification of the certificate's name (CN) against the specified host. + + | Type: boolean + | Default: nil + | Environment variable: TT_CONFIG_ETCD_SSL_VERIFY_HOST + + +.. _config_etcd_ssl_verify_peer: + +.. confval:: config.etcd.ssl.verify_peer + + **Since:** :doc:`3.0.0 `. + + Enable verification of the peer's SSL certificate. + + | Type: boolean + | Default: nil + | Environment variable: TT_CONFIG_ETCD_SSL_VERIFY_PEER + + +.. _config_etcd_http_request_timeout: + +.. confval:: config.etcd.http.request.timeout + + **Since:** :doc:`3.0.0 `. + + A time period required to process an HTTP request to an etcd server: from sending a request to receiving a response. + + | Type: number + | Default: nil + | Environment variable: TT_CONFIG_ETCD_HTTP_REQUEST_TIMEOUT + +.. _config_etcd_http_request_unix_socket: + +.. confval:: config.etcd.http.request.unix_socket + + **Since:** :doc:`3.0.0 `. + + A Unix domain socket used to connect to an etcd server. + + | Type: string + | Default: nil + | Environment variable: TT_CONFIG_ETCD_HTTP_REQUEST_UNIX_SOCKET + + + + +.. TODO + https://github.com/tarantool/doc/issues/3664 + diff --git a/doc/reference/configuration/index.rst b/doc/reference/configuration/index.rst index be2a510d02..1840ce5ecc 100644 --- a/doc/reference/configuration/index.rst +++ b/doc/reference/configuration/index.rst @@ -1,503 +1,71 @@ -.. _index-book_cfg: - -================================================================================ -Configuration reference -================================================================================ - -This reference covers all options and parameters which can be set for Tarantool -on the command line or in an :ref:`initialization file `. - -Tarantool is started by entering either of the following command: - -.. cssclass:: highlight -.. parsed-literal:: - - $ **tarantool** - - $ **tarantool** *options* - - $ **tarantool** *lua-initialization-file* **[** *arguments* **]** - --------------------------------------------------------------------------------- -Command options --------------------------------------------------------------------------------- - -.. option:: -h, --help - - Print an annotated list of all available options and exit. - -.. _index-tarantool_version: - -.. option:: -v, -V, --version - - Print the product name and version. - - **Example** - - .. code-block:: console - - % tarantool --version - Tarantool 2.11.1-0-g96877bd - Target: Darwin-arm64-Release - ... - - In this example: - - * ``2.11.1`` is a Tarantool version. - Tarantool follows semantic versioning, which is described in the :ref:`Tarantool release policy ` section. - - * ``Target`` is the platform Tarantool is built on. - Platform-specific details may follow this line. - - -.. option:: -e EXPR - - Execute the 'EXPR' string. See also: `lua man page `_. - - **Example** - - .. code-block:: console - - % tarantool -e "print('Hello, world!')" - Hello, world! - -.. option:: -l NAME - - Require the 'NAME' library. See also: `lua man page `_. - - **Example** - - .. code-block:: console - - % tarantool -l luatest.coverage script.lua - -.. option:: -j cmd - - Perform a LuaJIT control command. See also: `Command Line Options `_. - - **Example** - - .. code-block:: console - - % tarantool -j off app.lua - -.. option:: -b ... - - Save or list bytecode. See also: `Command Line Options `_. - - **Example** - - .. code-block:: console - - % tarantool -b test.lua test.out - -.. option:: -d SCRIPT - - Activate a debugging session for 'SCRIPT'. See also: `luadebug.lua `_. - - **Example** - - .. code-block:: console - - % tarantool -d app.lua - - -.. option:: -i [SCRIPT] - - Enter an :ref:`interactive mode ` after executing 'SCRIPT'. - - **Example** - - .. code-block:: console - - % tarantool -i - - -.. option:: -- - - Stop handling options. See also: `lua man page `_. - - -.. option:: - - - Stop handling options and execute the standard input as a file. See also: `lua man page `_. - - -.. _index-uri: - --------------------------------------------------------------------------------- -URI --------------------------------------------------------------------------------- - -Some configuration parameters and some functions depend on a URI (Universal Resource Identifier). -The URI string format is similar to the -`generic syntax for a URI schema `_. -It may contain (in order): - -* user name for login -* password -* host name or host IP address -* port number. - -Only a port number is always mandatory. A password is mandatory if a user -name is specified, unless the user name is 'guest'. - -Formally, the URI -syntax is ``[host:]port`` or ``[username:password@]host:port``. -If host is omitted, then "0.0.0.0" or "[::]" is assumed -meaning respectively any IPv4 address or any IPv6 address -on the local machine. -If ``username:password`` is omitted, then the "guest" user is assumed. Some examples: - -.. container:: table - - .. rst-class:: left-align-column-1 - .. rst-class:: left-align-column-2 - - +-----------------------------+------------------------------+ - | URI fragment | Example | - +=============================+==============================+ - | port | 3301 | - +-----------------------------+------------------------------+ - | host:port | 127.0.0.1:3301 | - +-----------------------------+------------------------------+ - | username:password@host:port | notguest:sesame@mail.ru:3301 | - +-----------------------------+------------------------------+ - -In code, the URI value can be passed as a number (if only a port is specified) or a string: - -.. code-block:: lua - - box.cfg { listen = 3301 } - - box.cfg { listen = "127.0.0.1:3301" } - -In certain circumstances, a Unix domain socket may be used -where a URI is expected, for example, "unix/:/tmp/unix_domain_socket.sock" or -simply "/tmp/unix_domain_socket.sock". - -The :ref:`uri ` module provides functions that convert URI strings into their -components, or turn components into URI strings. - -.. _index-uri-several: - -Specifying several URIs -~~~~~~~~~~~~~~~~~~~~~~~ - -Starting from version 2.10.0, a user can open several listening iproto sockets on a Tarantool instance -and, consequently, can specify several URIs in the configuration parameters -such as :ref:`box.cfg.listen ` and :ref:`box.cfg.replication `. - -URI values can be set in a number of ways: - -* As a string with URI values separated by commas. - - .. code-block:: lua - - box.cfg { listen = "127.0.0.1:3301, /unix.sock, 3302" } - -* As a table that contains URIs in the string format. - - .. code-block:: lua - - box.cfg { listen = {"127.0.0.1:3301", "/unix.sock", "3302"} } - -* As an array of tables with the ``uri`` field. - - .. code-block:: lua - - box.cfg { listen = { - {uri = "127.0.0.1:3301"}, - {uri = "/unix.sock"}, - {uri = 3302} - } - } - -* In a combined way -- an array that contains URIs in both the string and the table formats. - - .. code-block:: lua - - box.cfg { listen = { - "127.0.0.1:3301", - { uri = "/unix.sock" }, - { uri = 3302 } - } - } - -.. _index-uri-several-params: - -Also, starting from version 2.10.0, it is possible to specify additional parameters for URIs. -You can do this in different ways: - -* Using the ``?`` delimiter when URIs are specified in a string format. - - .. code-block:: lua - - box.cfg { listen = "127.0.0.1:3301?p1=value1&p2=value2, /unix.sock?p3=value3" } - -* Using the ``params`` table: a URI is passed in a table with additional parameters in the "params" table. - Parameters in the "params" table overwrite the ones from a URI string ("value2" overwrites "value1" for ``p1`` in the example below). - - .. code-block:: lua - - box.cfg { listen = { - "127.0.0.1:3301?p1=value1", - params = {p1 = "value2", p2 = "value3"} - } - } - -* Using the ``default_params`` table for specifying default parameter values. - - In the example below, two URIs are passed in a table. - The default value for the ``p3`` parameter is defined in the ``default_params`` table - and used if this parameter is not specified in URIs. - Parameters in the ``default_params`` table are applicable to all the URIs passed in a table. - - .. code-block:: lua - - box.cfg { listen = { - "127.0.0.1:3301?p1=value1", - { uri = "/unix.sock", params = { p2 = "value2" } }, - default_params = { p3 = "value3" } - } - } - -The recommended way for specifying URI with additional parameters is the following: - -.. code-block:: lua - - box.cfg { listen = { - {uri = "127.0.0.1:3301", params = {p1 = "value1"}}, - {uri = "/unix.sock", params = {p2 = "value2"}}, - {uri = 3302, params = {p3 = "value3"}} - } - } - -In case of a single URI, the following syntax also works: - -.. code-block:: lua - - box.cfg { listen = { - uri = "127.0.0.1:3301", - params = { p1 = "value1", p2 = "value2" } - } - } - -.. _index-init_label: - --------------------------------------------------------------------------------- -Initialization file --------------------------------------------------------------------------------- - -If the command to start Tarantool includes :codeitalic:`lua-initialization-file`, then -Tarantool begins by invoking the Lua program in the file, which by convention -may have the name "``script.lua``". The Lua program may get further arguments -from the command line or may use operating-system functions, such as ``getenv()``. -The Lua program almost always begins by invoking ``box.cfg()``, if the database -server will be used or if ports need to be opened. For example, suppose -``script.lua`` contains the lines - -.. _index-init-example: - -.. code-block:: lua - - #!/usr/bin/env tarantool - box.cfg{ - listen = os.getenv("LISTEN_URI"), - memtx_memory = 33554432, - pid_file = "tarantool.pid", - wal_max_size = 2500 - } - print('Starting ', arg[1]) - -and suppose the environment variable LISTEN_URI contains 3301, -and suppose the command line is ``~/tarantool/src/tarantool script.lua ARG``. -Then the screen might look like this: - -.. code-block:: console - - $ export LISTEN_URI=3301 - $ ~/tarantool/src/tarantool script.lua ARG - ... main/101/script.lua C> Tarantool 2.8.3-0-g01023dbc2 - ... main/101/script.lua C> log level 5 - ... main/101/script.lua I> mapping 33554432 bytes for memtx tuple arena... - ... main/101/script.lua I> recovery start - ... main/101/script.lua I> recovering from './00000000000000000000.snap' - ... main/101/script.lua I> set 'listen' configuration option to "3301" - ... main/102/leave_local_hot_standby I> ready to accept requests - Starting ARG - ... main C> entering the event loop - -If you wish to start an interactive session on the same terminal after -initialization is complete, you can use :ref:`console.start() `. - -.. _index-local_hot_standby: -.. _index-replication_port: -.. _index-slab_alloc_arena: -.. _index-replication_source: -.. _index-snap_dir: -.. _index-wal_dir: -.. _index-wal_mode: -.. _index-checkpoint daemon: - -.. _box_cfg_params: - --------------------------------------------------------------------------------- -Configuration parameters --------------------------------------------------------------------------------- - -Configuration parameters have the form: - -:extsamp:`{**{box.cfg}**}{[{*{key = value}*} [, {*{key = value ...}*}]]}` - -Since ``box.cfg`` may contain many configuration parameters and since some of the -parameters (such as directory addresses) are semi-permanent, it's best to keep -``box.cfg`` in a Lua file. Typically this Lua file is the initialization file -which is specified on the Tarantool command line. - -Most configuration parameters are for allocating resources, opening ports, and -specifying database behavior. All parameters are optional. -A few parameters are dynamic, that is, they can be changed at runtime by calling ``box.cfg{}`` a second time. -For example, the command below sets the :ref:`listen port ` to ``3301``. - -.. code-block:: tarantoolsession - - tarantool> box.cfg{ listen = 3301 } - 2023-05-10 13:28:54.667 [31326] main/103/interactive I> tx_binary: stopped - 2023-05-10 13:28:54.667 [31326] main/103/interactive I> tx_binary: bound to [::]:3301 - 2023-05-10 13:28:54.667 [31326] main/103/interactive/box.load_cfg I> set 'listen' configuration option to 3301 - --- - ... - - -To see all the non-null parameters, execute ``box.cfg`` (no parentheses). - -.. code-block:: tarantoolsession - - tarantool> box.cfg - --- - - replication_skip_conflict: false - wal_queue_max_size: 16777216 - feedback_host: https://feedback.tarantool.io - memtx_dir: . - memtx_min_tuple_size: 16 - -- other parameters -- - ... - -To see a particular parameter value, call a corresponding ``box.cfg`` option. -For example, ``box.cfg.listen`` shows the specified :ref:`listen address `. - -.. code-block:: tarantoolsession - - tarantool> box.cfg.listen - --- - - 3301 - ... - - -.. _box-cfg-params-prior: - -Methods of setting and priorities -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Tarantool configuration parameters can be specified in different ways. -The priority of parameter sources is the following, from higher to lower: - -* ``box.cfg`` options -* :ref:`environment variables ` -* :ref:`tt configuration ` -* default values. - -.. _box-cfg-params-env: - -Setting via environment variables -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Starting from version :doc:`2.8.1 `, you can specify configuration parameters via special environment variables. -The name of a variable should have the following pattern: ``TT_``, -where ```` is the uppercase name of the corresponding :ref:`box.cfg parameter `. - -For example: - -* ``TT_LISTEN`` -- corresponds to the ``box.cfg.listen`` option. -* ``TT_MEMTX_DIR`` -- corresponds to the ``box.cfg.memtx_dir`` option. - -In case of an array value, separate the array elements by comma without space: - -.. code-block:: console - - export TT_REPLICATION="localhost:3301,localhost:3302" - -If you need to pass :ref:`additional parameters for URI `, use the ``?`` and ``&`` delimiters: - -.. code-block:: console - - export TT_LISTEN="localhost:3301?param1=value1¶m2=value2" +.. _index-book_cfg: +.. _box-cfg-params-ref: -An empty variable (``TT_LISTEN=``) has the same effect as an unset one meaning that the corresponding configuration parameter won't be set when calling ``box.cfg{}``. +Configuration reference (box.cfg) +================================= -.. _box-cfg-params-ref: +.. include:: /concepts/configuration/configuration_code.rst + :start-after: box_cfg_legacy_note_start + :end-before: box_cfg_legacy_note_end -Reference -~~~~~~~~~ -The sections that follow describe all configuration parameters for basic operations, storage, -binary logging and snapshots, replication, networking, logging, and feedback. +This topic describes all configuration parameters +that can be specified :ref:`in code ` using the ``box.cfg`` API. .. contents:: :local: :depth: 1 Basic parameters -^^^^^^^^^^^^^^^^ +---------------- .. include:: cfg_basic.rst Configuring the storage -^^^^^^^^^^^^^^^^^^^^^^^ +----------------------- .. include:: cfg_storage.rst .. _book_cfg_checkpoint_daemon: Checkpoint daemon -^^^^^^^^^^^^^^^^^ +----------------- .. include:: cfg_snapshot_daemon.rst Binary logging and snapshots -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +---------------------------- .. include:: cfg_binary_logging_snapshots.rst .. _index-hot_standby: Hot standby -^^^^^^^^^^^ +----------- .. include:: cfg_hot_standby.rst Replication -^^^^^^^^^^^ +----------- .. include:: cfg_replication.rst Networking -^^^^^^^^^^ +---------- .. include:: cfg_networking.rst Logging -^^^^^^^ +------- .. include:: cfg_logging.rst Feedback -^^^^^^^^ +-------- .. include:: cfg_feedback.rst Deprecated parameters -^^^^^^^^^^^^^^^^^^^^^ +--------------------- .. include:: cfg_deprecated.rst diff --git a/doc/reference/index.rst b/doc/reference/index.rst index eb61be86a6..ae8a1cfce6 100644 --- a/doc/reference/index.rst +++ b/doc/reference/index.rst @@ -10,6 +10,7 @@ Reference .. toctree:: :maxdepth: 2 + configuration/configuration_reference configuration/index tooling/index reference_sql/index diff --git a/doc/reference/reference_lua/config.rst b/doc/reference/reference_lua/config.rst new file mode 100644 index 0000000000..9ddacc11df --- /dev/null +++ b/doc/reference/reference_lua/config.rst @@ -0,0 +1,8 @@ +.. _config-module: + +Module config +============= + +**Since:** :doc:`3.0.0 ` + +.. TODO: https://github.com/tarantool/doc/issues/3662 diff --git a/doc/reference/reference_lua/index.rst b/doc/reference/reference_lua/index.rst index f09443274d..2002f75e4f 100644 --- a/doc/reference/reference_lua/index.rst +++ b/doc/reference/reference_lua/index.rst @@ -25,6 +25,7 @@ This reference covers Tarantool's built-in Lua modules. checks clock compat + config console crypto csv diff --git a/doc/reference/tooling/tt_cli/cluster.rst b/doc/reference/tooling/tt_cli/cluster.rst new file mode 100644 index 0000000000..0236893038 --- /dev/null +++ b/doc/reference/tooling/tt_cli/cluster.rst @@ -0,0 +1,10 @@ +.. _tt-cluster: + +Managing a cluster's configuration +================================== + +.. code-block:: console + + $ tt cluster + +.. TODO: https://github.com/tarantool/doc/issues/3725 diff --git a/doc/reference/tooling/tt_cli/commands.rst b/doc/reference/tooling/tt_cli/commands.rst index 5c68092f1b..61fc3506c0 100644 --- a/doc/reference/tooling/tt_cli/commands.rst +++ b/doc/reference/tooling/tt_cli/commands.rst @@ -26,6 +26,8 @@ help for the given command. - Check an application file for syntax errors * - :doc:`clean ` - Clean instance files + * - :doc:`cluster ` + - Manage a cluster's configuration * - :doc:`completion ` - Generate completion for a specified shell * - :doc:`connect ` @@ -83,6 +85,7 @@ help for the given command. cfg check clean + cluster completion connect coredump