# Node Configuration¶

The Tezos node can be configured in flexible ways to control various aspects of its behavior, such as RPC, P2P, or shell parameters, the directory for storing data, logging levels, and so on. These aspects can be customized in two different ways:

• by supplying options on the command line when running the node

• by specifying parameters in a configuration file for the node

When the same parameter is set both in the configuration file and using a command line option, the value on the command line is taken into account (and the configuration file is not updated).

The list of configurable options on the command line interface (CLI) can be obtained using the following command:

tezos-node run --help


## Configuration file¶

Parameters in the configuration file can be specified in two different ways:

• by creating and updating the configuration file using the config command of tezos-node. This covers a subset of the CLI of the run command of tezos-node mentioned above.

• by directly editing the configuration file. This allows to specify all the available configuration parameters, including some that cannot be set using the options of the config and run commands of tezos-node, for example network parameters such as connection or authentication timeouts.

The list of configurable options and parameters for the node can be obtained using the following command:

tezos-node config --help


This command also explains the role of each option and parameter and the range of possible values.

### The config command¶

./tezos-node config init


This will initialize a configuration file for the node in $HOME/.tezos-node/config.json, using default values. It only specifies that the node will listen to incoming connections on socket address [::]:9732. The easiest way to amend this default configuration is to use # Update the config file ./tezos-node config update <…> # Start from an empty cfg file ./tezos-node config reset <…>  However, note that the network configuration parameter, needed to run the node on a network other than the default one (Mainnet), can only be defined when the configuration file is initialized (using init), and cannot be updated later (using update). See the instructions for running the node in test networks. For example, the following script initializes and fills a configuration file using many command-line options: # [remove config file if exists] rm -f tmp/config.json # [initialize config file] ../tezos-node config --config-file=tmp/config.json --network=sandbox init # [update config file] ../tezos-node config --config-file=tmp/config.json --data-dir=tmp \ --expected-pow=24.5 --peer="[::]:10732" --peer="192.168.1.3:9733" \ --private-mode --disable-mempool \ --rpc-addr="localhost:8733" --net-addr="1.2.3.4" \ --connections=100 --max-download-speed=1024 --max-upload-speed=1024 \ --cors-origin="*" --cors-header="Content-Type" \ --rpc-tls="tezos-node.crt,tezos-node.key" \ --log-output="tezos-node.log" \ --synchronisation-threshold=5 --sync-latency=120 --history-mode=full \ update # [show config file] ../tezos-node config --data-dir=tmp show  ### Editing the configuration file¶ All blockchain data is stored under $HOME/.tezos-node/. You can change this by doing ./tezos-node config update –data-dir </somewhere/in/your/disk>.

To run multiple nodes on the same machine, you can duplicate and edit $HOME/.tezos-node/config.json while making sure they don’t share the same data-dir. Then run your node with ./tezos-node run --config-file=</path/to/alternate_cfg>. Here is an example configuration file with many parameters specified. Most of the time it uses default values, except for cases where the default is not explanatory enough (i.e. bootstrap-peers is an empty list by default). Comments are not allowed in JSON, so this configuration file would not parse. They are just provided here to help writing your own configuration file if needed. { /* Location of the data dir on disk. */ "data-dir": "tmp", "rpc": /* Configuration of rpc parameters */ { /* Host to listen to. If the port is not specified, the default port 8732 will be assumed. */ "listen-addrs": [ "localhost:8733" ], /* Cross Origin Resource Sharing parameters, see https://en.wikipedia.org/wiki/Cross-origin_resource_sharing. */ "cors-origin": [ "*" ], "cors-headers": [ "Content-Type" ], /* Certificate and key files (necessary when TLS is used). */ "crt": "tezos-node.crt", "key": "tezos-node.key" }, "p2p": /* Configuration of network parameters */ { /* Floating point number between 0 and 256 that represents a difficulty, 24 signifies for example that at least 24 leading zeroes are expected in the binary hash. More generally, for a real value x it means that the hash is lower than max_hash / 2^x */ "expected-proof-of-work": 24.5, /* Initial list of nodes to connect to. Tezos can connect to both IPv6 and IPv4 hosts. If the port is not specified, default port 9732 will be assumed. */ "bootstrap-peers": [ "boot.tzbeta.net", "116.202.172.21", "[::]:10732", "192.168.1.3:9733" ], /* List of address/ports to listen to. Tezos can connect to both IPv6 and IPv4 hosts. If the port is not specified, default port 9732 will be assumed. */, "listen-addr": "95.216.45.62:9733", /* Specify if the node is in private mode or not. A node in private mode only opens outgoing connections to peers whose addresses are in [trusted_peers] and only accepts incoming connections from trusted peers. In addition, it informs these peers that the identity of the node should not be revealed to the rest of the network. */ "private-mode": true, "limits": /* Network limits */ { /* Delay granted to a peer to perform authentication, in seconds. */ "authentication-timeout": 5, /* Strict minimum number of connections (triggers an urgent maintenance). */ "min-connections": 50, /* Targeted number of connections to reach when bootstrapping / maintaining. */ "expected-connections": 100, /* Maximum number of connections (exceeding peers are disconnected). */ "max-connections": 150, /* Number above which pending incoming connections are immediately rejected. */ "backlog": 20, /* Maximum allowed number of incoming connections that are pending authentication. */ "max-incoming-connections": 20, /* Maximum download and upload speeds in KiB/s. */ "max-download-speed": 1024, "max-upload-speed": 1024, /* Size of the buffer passed to read(2). */ "read-buffer-size": 16384, /* Delay acceptable when initiating a connection to a new peer, in seconds. */, "connection-timeout": 10, /* Maximum and target size for the known address table. */ "max_known_points": [ 800, 600 ], "max_known_peer_ids": [ 800, 600 ] }, /* If set to [true], the node will not participate in the propagation of pending operations (mempool). Default value is [false]. It can be used to decrease the memory and computation footprints of the node. */, "disable_mempool": true }, "log": { /* Configuration of log parameters */ /* Output for the logging function. Either "stdout", "stderr" or the name of a log file . */ "output": "tezos-node.log", /* Verbosity level: one of 'fatal', 'error', 'warn', 'notice', 'info', 'debug'. */ "level": "info", /* Fine-grained logging instructions. Same format as described in tezos-node run --help, DEBUG section. In the example below, sections "net" and all sections starting by "client" will have their messages logged up to the debug level, whereas the rest of log sections will be logged up to the notice level. */ "rules": "client* -> debug; net -> debug; * -> notice", /* Format for the log file, see https://github.com/ocsigen/lwt_log/blob/1.1.1/src/core/lwt_log_core.mli#L229. */ "template": "$(date) - $(section):$(message)"
},

"shell": /* Configuration of shell parameters */
{ "chain_validator": {
/* The number of peers to synchronize with
before declaring the node 'bootstrapped'. */
"synchronisation_threshold": 4,

/* Latency in seconds used for the synchronisation
heuristic. */
"latency": 120
},

/* The history mode configuration you want to run. */
"history_mode": "full"
},
}


## RPC parameters¶

RPC parameters allow to customize the JSON/RPC interface, by defining for instance hosts to listen for RPC requests, or a certificate/key file necessary when TLS is used.

## P2P parameters¶

P2P parameters allow to customize aspects related to the peer-to-peer network layer, such as:

• defining the bootstrap peers (and ports),

• setting the greylist timeout,

• running the node in private mode.

### Private node¶

The node can be set in private mode with the option --private-mode so that:

• it doesn’t connect to any peer other than those provided with --peer or in bootstrap-peers

• the peers connected to a private node don’t advertise it in the list of peers sent to their neighborhood

This feature is especially useful to hide a sensitive node that signs operations.

For example we could have a set up with two nodes, a private one connected uniquely with a public one. The public node runs on a VPS, connects normally to the network and keeps an up to date state of the network while the private node runs at your home and is in charge of injecting and signing operations with a hardware wallet.

tezos-node run --rpc-addr [::] --private-mode \
--no-bootstrap-peers \
--synchronisation-threshold=1 \
--connections 1 \
--peer <public-node-ip>


## Logging¶

It is possible to set independent log levels for different components in the Tezos node, as well as to specify an output file for logging. This can be done in two different ways:

• by defining log parameters in the configuration file (see Configuration file)

• by setting the environment variable TEZOS_LOG before starting the node.

The list of the Tezos components that can be logged and the syntax for the logging options can be found in the DEBUG section displayed by tezos-node run --help:

       The environment variable TEZOS_LOG is used to fine-tune what is going
to be logged. The syntax is TEZOS_LOG='<section> -> <level> [ ;
...]' where section is one of 000-Ps9mPmXa 001-PtCJ7pwo 002-PsYLVpVv
003-PsddFKi3 004-Pt24m4xi 005-PsBABY5H 005-PsBabyM1 006-PsCARTHA
007-PsDELPH1 008-PtEdo2Zk 008-PtEdoTez 009-PsFLoren alpha db
demo-counter demo-noops external_block_validator external_validator
genesis genesis-carthagenet node node.chain_validator
node.protocol_store node.reconstruction node.replay
node.requester.scheduler node.shutdown node.snapshots node.state
node.storage_consistency node.store node.validator
node.validator.bootstrap_pipeline node_data_version p2p p2p.conn
p2p.connect_handler p2p.discovery p2p.fd p2p.io-scheduler
p2p.maintenance p2p.pool p2p.protocol p2p.socket p2p.welcome
protocol_updater proxy.context sequential_block_validator
validator.block validator.chain validator.peer and level is one of
fatal, error, warn, notice, info or debug. A * can be used as a
wildcard in sections, i.e. node* -> debug. The rules are matched
left to right, therefore the leftmost rule is highest priority .



### Event-based logging¶

A more advanced interface for logging, based on events generated by the different components, is available using the environment variable TEZOS_EVENTS_CONFIG. Its value must be a list of URIs separated by spaces. Each URI defines a sink for log events consisting in a Unix output stream and possibly some logging options, and has one of the following forms:

• file-descriptor-path://<path>

• file-descriptor-stdout://

• file-descriptor-stderr://

The URIs may further append options in the form of a query ?<opt1>=<val1>&<opt2>=<val2>....

For example, the following definition sends all the events to file /the/path/to/write.log, formatted as one event per line:

export TEZOS_EVENTS_CONFIG=file-descriptor-path:///the/path/to/write.log?format=one-per-line


You may find all the available options in the file descriptor sink API.

Note

Note that, as the Tezos codebase is in the process of moving from the legacy logging framework to the events-based logging framework, some interferences are observed between the two. In particular, the configuration option level-at-least documented in the above API does not currently work as expected, so you should avoid using it.

## Shell parameters¶

Configuration options/parameters for the shell allow tuning the working of the validation subsystem.

In particular, the synchronization heuristics implemented by the chain validator can be controlled using parameters such as the synchronization threshold or the latency, described in the documentation of the synchronization heuristics.