About Sawtooth Configuration Files
Each Sawtooth component, such as the validator or the REST API, has an optional configuration file that controls the component’s behavior. These configuration files provide an alternative to specifying Sawtooth command options when starting a component.
Note
Using configuration files is an example of off-chain configuration. Changes are made on the local system only. For more information, see Configuring Validator and Transactor Permissions.
When a Sawtooth component starts, it looks for a
TOML-format configuration file in
the config directory, /etc/sawtooth/
(by default).
By default (when Sawtooth is installed), no configuration files are created. However, Sawtooth includes example configuration files that can be customized for your system. See Changing Off-chain Settings with Configuration Files for this procedure.
Important
After changing a configuration file for a component, you must restart that component in order to load the changes.
Sawtooth also supports several non-component configuration files:
- The Log Configuration File allows you to configure the log output for each component.
- The Path Configuration File controls the
location of Sawtooth directories, such as the configuration directory
(
config_dir
) and log directory (log_dir
). This file also lets you set an optional$SAWTOOTH_HOME
environment variable to change the base location of Sawtooth files and directories.
Validator Configuration File
The validator configuration file specifies network information that allows the validator to advertise itself properly and search for peers. This file also contains settings for optional authorization roles and transactor permissions.
If the config directory contains a file named validator.toml
, the
configuration settings are applied when the validator starts. Specifying
an option on the command line overrides the setting in the configuration
file.
An example configuration file is in
/sawtooth-core/packaging/validator.toml.example
.
Note
By default, the config directory is
/etc/sawtooth/
. See Path Configuration File for more information.
To create a validator configuration file, copy the example file to the
config directory and name it validator.toml
. Important: Copy with
cp -a
to preserve the file’s ownership and permissions (or change
after copying to owner root
, group sawtooth
, and permissions 640
).
Then edit the file to change the example configuration options as
necessary for your system.
Note
For the procedures that show how to change configuration settings in this file, see Off-chain Settings with Configuration Files and Using Sawtooth with PoET-SGX.
The validator.toml
configuration file has the following options:
-
bind = [ "network:{endpoint}", "component:{endpoint}", "consensus:{endpoint}", ]
Sets the network, component, and consensus endpoints. The default values are:
bind = [ "network:tcp://127.0.0.1:8800", "component:tcp://127.0.0.1:4004", "consensus:tcp://127.0.0.1:5050" ]
-
peering = "{static,dynamic}"
Specifies the type of peering the validator should use: static or dynamic. Default:
static
.Static peering attempts to peer only with the candidates provided with the peers option. For example:
peering = "static"
Dynamic peering first processes any static peers, starts topology buildouts, then uses the URLs specified by the seeds option for the initial connection to the Sawtooth network.
peering = "dynamic"
-
endpoint = "URL"
Sets the advertised network endpoint URL. Default: tcp://127.0.0.1:8800. Replace the external interface and port values with either the publicly addressable IP address and port or with the NAT values for your validator. For example:
endpoint = "tcp://127.0.0.1:8800"
-
seeds
= [URI
](Dynamic peering only.) Specifies the URI or URIs for the initial connection to the Sawtooth network. Specify multiple URIs in a comma-separated list; each URI must be enclosed in double quotes. Default: none.
Note that this option is not needed in static peering mode.
Replace the seed address and port values with either the publicly addressable IP address and port or with the NAT values for the other nodes in your network. For example:
seeds = ["tcp://127.0.0.1:8801"]
-
peers
= [“URL”]Specifies a static list of peers to attempt to connect to. Default: none.
peers = ["tcp://127.0.0.1:8801"]
-
scheduler
= “type”Determines the type of scheduler to use: serial or parallel. Default:
parallel
. For example:scheduler = 'parallel'
-
network_public_key
andnetwork_private_key
Specifies the curve ZMQ key pair used to create a secured network based on side-band sharing of a single network key pair to all participating nodes. Default: none.
Enclose the key in single quotes; for example:
network_public_key = 'wFMwoOt>yFqI/ek.G[tfMMILHWw#vXB[Sv}>l>i)' network_private_key = 'r&oJ5aQDj4+V]p2:Lz70Eu0x#m%IwzBdP(}&hWM*'
Important
If these options are not set or the configuration file does not exist, the network will default to being insecure.
-
opentsdb_url
= “value”Sets the host and port for an Open TSDB database (used for metrics). Default: none.
For example of using the
opentsdb_
settings, see Using Grafana to Display Sawtooth Metrics. -
opentsdb_db
= “name”Sets the name of the Open TSDB database. Default: none.
-
opentsdb_username
= usernameSets the username for the Open TSDB database. Default: none.
-
opentsdb_password
= passwordSets the password for the Open TSDB database. Default: none.
-
network = "{trust,challenge}"
Specifies the type of authorization that must be performed for the different type of authorization roles on the network: trust or challenge. Default: trust.
This option must be in the
[roles]
section of the file. For example:[roles] network = "trust"
For more information, see Authorization Types.
-
“role” = “policy”
Sets the off-chain transactor permissions for the role or roles that specify which transactors are allowed to sign batches on the system. Multiple roles can be defined, using one “role” = “policy” entry per line. Default: none.
The role names specified in this config file must match the roles stored in state for transactor permissioning. For example:
transactor
transactor.transaction_signer
transactor.transaction_signer.{tp_name}
transactor.batch_signer
For policy, specify a policy file in
policy_dir
(by default,/etc/sawtooth/
). Each policy file contains permit and deny rules for the transactors; see Off-chain Transactor Permissioning.Because transactor roles and policy files can have a period in the name, use double-quotes so that TOML can process these settings. For example:
[permissions] "transactor" = "policy.example" "transactor.transaction_signer" = "policy.example"
Note
The
default
role cannot be set in the configuration file. Use thesawtooth identity
command to change this on-chain-only setting.See Configuring Validator and Transactor Permissions for more information on roles and permissions.
-
minimum_peer_connectivity
= minThe minimum number of peers required before stopping peer search. Default: 3 For example:
minimum_peer_connectivity = 3
-
maximum_peer_connectivity
= maxThe maximum number of peers that will be accepted. Default: 10. For example:
maximum_peer_connectivity = 10
REST API Configuration File
The REST API configuration file specifies network connection settings and an optional timeout value.
If the config directory contains a file named rest_api.toml
, the
configuration settings are applied when the REST API starts. Specifying
a command-line option will override the setting in the configuration
file.
Note
By default, the config directory is
/etc/sawtooth/
. See Path Configuration File for more information.
An example configuration file is in the sawtooth-core
repository at
/sawtooth-core/rest_api/packaging/rest_api.toml.example
. To create a
REST API configuration file, download this example file to the config
directory and name it rest_api.toml
. Set the ownership and permissions
to owner root
, group sawtooth
, and permissions 640
. Then edit the
file to change the example configuration options as necessary for your
system.
The rest_api.toml
configuration file has the following options:
-
bind
= [“HOST:PORT”]Sets the port and host for the REST API to run on. Default:
127.0.0.1:8008
. For example:bind = ["127.0.0.1:8008"]
-
connect
= “URL”Identifies the URL of a running validator. Default:
tcp://localhost:4004
. For example:connect = "tcp://localhost:4004"
-
timeout
= valueSpecifies the time, in seconds, to wait for a validator response. Default: 300. For example:
timeout = 900
-
client_max_size
= valueSpecifies the size, in bytes, that the REST API will accept for the body of requests. If the body is larger a
413: Request Entity Too Large
will be returned Default: 10485760 (or 10 MB). For example:client_max_size = 10485760
-
opentsdb_url
= “value”Sets the host and port for Open TSDB database (used for metrics).
-
opentsdb_db
= “name”Sets the name of the Open TSDB database. Default: none.
-
opentsdb_username
= usernameSets the username for the Open TSDB database. Default: none.
-
opentsdb_password
= passwordSets the password for the Open TSDB database. Default: none.
Sawtooth CLI Configuration File
The Sawtooth CLI configuration file specifies arguments to be used by
the sawtooth
command and its subcommands. For example, you can use
this file to set the URL of the REST API once, rather than entering the
--url
option for each subcommand.
If the config directory contains a file named cli.toml
, the
configuration settings are applied when the sawtooth
command is run.
Specifying command-line options will override the settings in the
configuration file.
Note
By default, the config directory is
/etc/sawtooth/
. See Path Configuration File for more information.
An example configuration file is in the sawtooth-core
repository at
/sawtooth-core/cli/cli.toml.example
. To create a CLI configuration
file, download this example file to the config directory and name it
cli.toml
. Set the ownership and permissions to owner root
, group
sawtooth
, and permissions 640
.
The example file shows the format of the url
option. To use it,
uncomment the line and replace the default value with the actual URL for
the REST API.
# The REST API URL
# url = "http://localhost:8008"
PoET SGX Enclave Configuration File
This configuration file specifies configuration settings for a PoET SGX enclave.
If the config directory contains a file named poet_enclave_sgx.toml
,
the configuration settings are applied when the component starts.
Specifying a command-line option will override the setting in the
configuration file.
Note
By default, the config directory is
/etc/sawtooth/
. See Path Configuration File for more information.
An example configuration file is in the sawtooth-core
repository at
/sawtooth-core/consensus/poet/sgx/packaging/poet_enclave_sgx.toml.example
.
To create a PoET SGX enclave configuration file, download this example
file to the config directory and name it poet_enclave_sgx.toml
. Set
the ownership and permissions to owner root
, group sawtooth
, and
permissions 640
. Then edit the file to change the example
configuration options as necessary for your system.
Note
See Using Sawtooth with PoET SGX for an example of changing settings in
poet_enclave_sgx.toml
when configuring Sawtooth with the SGX implementation of PoET.
The poet_enclave_sgx.toml
configuration file has the following
options:
-
spid
= ‘string’Specifies the Service Provider ID (SPID), which is linked to the key pair used to authenticate with the attestation service. Default: none. The SPID value is a 32-digit hex string tied to the enclave implementation; for example:
spid = 'DEADBEEF00000000DEADBEEF00000000'
-
ias_url
= ‘URL’Specifies the URL of the Intel Attestation Service (IAS) server. Default: none. Note that the URL shown in
poet_enclave_sgx.toml.example
is an example server for debug enclaves only:ias_url = 'https://test-as.sgx.trustedservices.intel.com:443'
-
spid_cert_file
= ‘/full/path/to/certificate.pem’Identifies the PEM-encoded certificate file that was submitted to Intel in order to obtain a SPID. Default: none. Specify the full path to the certificate file. This pem file can be created from
cert.crt
andcert.key
files with this command:$ cat cert.crt cert.key > cert.pem
Or from
cert.pfx
file with following command:$ openssl pkcs12 -in cert.pfx -out cert.pem -nodes
Identity Transaction Processor Configuration File
The Identity transaction processor configuration file specifies the validator endpoint connection to use.
If the config directory contains a file named identity.toml
, the
configuration settings are applied when the transaction processor
starts. Specifying a command-line option will override the setting in
the configuration file.
Note
By default, the config directory is
/etc/sawtooth/
. See Path Configuration File for more information.
An example configuration file is in the sawtooth-core
repository at
/sawtooth-core/families/identity/sawtooth_identity/packaging/identity.toml.example
.
To create an Identity transaction processor configuration file, download
this example file to the config directory and name it identity.toml
.
Set the ownership and permissions to owner root
, group sawtooth
, and
permissions 640
. Then edit the file to change the example
configuration options as necessary for your system.
The identity.toml
configuration file has the following option:
-
connect
= “URL”Identifies the URL of a running validator. Default:
tcp://localhost:4004
. For example:connect = "tcp://localhost:4004"
Settings Transaction Processor Configuration File
The Settings transaction processor configuration file specifies the validator endpoint connection to use.
If the config directory contains a file named settings.toml
, the
configuration settings are applied when the transaction processor
starts. Specifying a command-line option will override the setting in
the configuration file.
Note
By default, the config directory is
/etc/sawtooth/
. See Path Configuration File for more information.
An example configuration file is in the sawtooth-core
repository at
/sawtooth-core/families/settings/packaging/settings.toml.example
. To
create a Settings transaction processor configuration file, download
this example file to the config directory and name it settings.toml
.
Set the ownership and permissions to owner root
, group sawtooth
, and
permissions 640
. Then edit the file to change the example
configuration options as necessary for your system.
The settings.toml
configuration file has the following option:
-
connect
= “URL”Identifies the URL of a running validator. Default:
tcp://localhost:4004
. For example:connect = "tcp://localhost:4004"
XO Transaction Processor Configuration File
The XO transaction processor configuration file specifies the validator endpoint connection to use.
If the config directory contains a file named xo.toml
, the
configuration settings are applied when the transaction processor
starts. Specifying a command-line option will override the setting in
the configuration file.
Note
By default, the config directory is
/etc/sawtooth/
. See Path Configuration File for more information.
An example configuration file is in the sawtooth-sdk-python
repository
at
https://github.com/hyperledger/sawtooth-sdk-python/blob/master/examples/xo_python/packaging/xo.toml.example
.
To create a XO transaction processor configuration file, download this
example file to the config directory and name it xo.toml
. Set the
ownership and permissions to owner root
, group sawtooth
, and
permissions 640
. Then edit the file to change the example
configuration options as necessary for your system.
The xo.toml
configuration file has the following option:
-
connect
= “URL”Identifies the URL of a running validator. Default:
tcp://localhost:4004
. For example:connect = "tcp://localhost:4004"
Path Configuration File
Important
Changing the path settings in this file is usually unnecessary. For non-standard directory paths, use the
SAWTOOTH_HOME
environment variable instead of this configuration file.
The path.toml
configuration changes the Sawtooth data_dir
directory.
This file should be used only when installing on an operating system
distribution where the default paths are not appropriate. For example,
some Unix-based operating systems do not use /var/lib
, so it would be
appropriate to use this file to set data_dir
to the natural operating
system default path for application data.
An example file is in /etc/sawtooth/path.toml.example
. To create a
path configuration file, copy the example file to the config directory
and name it path.toml
. Important: Copy with cp -a
to preserve the
file's ownership and permissions (or change after copying to owner
root
, group sawtooth
, and permissions 640
). Then edit the file to
change the example configuration options as necessary for your system.
This file configures the following settings:
-
key_dir
= pathDirectory path to use when loading key files
-
data_dir
= pathDirectory path for storing data files such as the block store
-
log_dir
= pathDirectory path to use to write log files (by default, an error log and a debug log; see Log Configuration File.
-
policy_dir
= pathDirectory path for storing policies
The default directory paths depend on whether the SAWTOOTH_HOME
environment variable is set. When SAWTOOTH_HOME
is set, the default
paths are:
-
key_dir
=SAWTOOTH_HOME/keys/
-
data_dir
=SAWTOOTH_HOME/data/
-
log_dir
=SAWTOOTH_HOME/logs/
-
policy_dir
=SAWTOOTH_HOME/policy/
For example, if SAWTOOTH_HOME
is set to /tmp/testing
, the default
path for data_dir
is /tmp/testing/data/
.
When SAWTOOTH_HOME
is not set, the operating system defaults are used.
On Linux, the default path settings are:
-
key_dir
=/etc/sawtooth/keys
-
data_dir
=/var/lib/sawtooth
-
log_dir
=/var/log/sawtooth
-
policy_dir
=/etc/sawtooth/policy
Sawtooth also uses config_dir
to determine the directory path
containing the configuration files. Note that this directory is fixed;
it cannot be changed in the path.toml
configuration file.
- If
SAWTOOTH_HOME
is set,conf_dir
=SAWTOOTH_HOME/etc/
- If
SAWTOOTH_HOME
is not set,conf_dir
=/etc/sawtooth