Node Setup and Configuration Tools
The setup
command provides functions for creating and managing node
configuration and data, including:
- performing quick setup of a standalone Kwil node (
init
) and Kwil test networks (testnet
) - updating genesis config with initial SQLite files (
genesis-hash
) - resetting node state and all data files (
reset
)
Quick Setup of a Single Kwil Node
The init
command facilitates quick setup of an isolated Kwil node on a fresh
network in which that node is the single validator. This permits rapid
prototyping and evaluation of Kwil DB functionality.
For example, to create a node configuration for a new network in a node root
folder at ~/.kwild-new
:
$ kwil-admin setup init -o ~/.kwild-new
Generated genesis file /home/user/.kwild-new/abci/config/genesis.json
Successfully initialized node directory: /home/user/.kwild-new
The above command also generated a new config.toml
and private_key
file in
the node directory.
Additional nodes may join this new network by specifying the existing node as a
persistent peer in kwild
's configuration and in the validators section of the
genesis configuration. See Kwil Daemon Configuration for
more information on node setup.
Creating a New Test Network of Several Nodes
The setup testnet
command is used to create multiple node configurations, all
with the same genesis config, and pre-configured to connect to each other. This
command has several options:
kwil-admin setup testnet [--validators V] [--non-validators N] [--config FILE]
[--output-dir DIR] [--node-dir-prefix PRE] [--hostname-prefix PRE]
[--hostname-suffix SUF] [--starting-ip IP] [--hostnames HOSTNAMES] [--p2p-port PORT]
There are defaults for each flag, with the output writing to a folder called
.testnet
in the current folder. For example, the following command creates a
new test network with 8 total nodes comprising 4 validators and 4 non-validators:
$ kwil-admin setup testnet -o ~/.kwild-testnet-xyz
Successfully initialized 3 node directories: /home/jon/.kwild-testnet-xyz
$ tree ~/.kwild-testnet-xyz
/home/user/.kwild-testnet-xyz
├── node0
│ ├── abci
│ │ ├── config
│ │ │ └── genesis.json
│ │ └── data
│ ├── config.toml
│ └── private_key
├── node1
│ ├── abci
│ │ ├── config
│ │ │ └── genesis.json
...
The config files for each of the nodes will specify all of the other nodes as persistent peers so that they will connect to each other on startup. This is generally only practical for small test networks with fewer than 12 nodes.
The following options may be used to control what is generated:
--validators
or-v
is the number of validators [default: 4]--non-validators
or-n
is the number of non-validators [default: 4]--config
is a template config file to use, default is none--output-dir
or-o
is the parent directory for all of generated node folders [default: ".testnet"]--node-dir-prefix
is the prefix for the node directories (node results in node0, node1, ...) [default: "node"]--hostname-prefix
is the prefix for node host names e.g. node results in node0, node1, etc.--hostname-suffix
is the suffix for node host names e.g. .example.com results in node0.example.com, node1.example.com, etc.--starting-ip
is the starting IP address of the first network node, with subsequent nodes on the next address in the subnet--hostnames
overrides all hostnames of the nodes--p2p-port
or-p
is the TCP port on which each node listens for P2P connections
Updating Genesis Config with Initial SQLite Data
If preparing a network with initial databases, it is required to update the "app
hash" in kwild
's genesis configuration to reflect the initial state that
includes one or more SQLite files. The syntax is:
kwil-admin setup genesis-hash [--genesis GENESIS] [DBDIR]
Both inputs are optional, using default paths. GENESIS
is the path to the
genesis file to patch, which is ~/.kwild/abci/config/genesis.json
by default.
The DBDIR
argument is the directory containing all of kwild
's SQLite files
to be hashed, which is ~/.kwild/data/kwil.db/
by default.
Resetting All Application Data
To delete all of a Kwil node's data files, use the reset
command.
WARNING: This command should not be used on production systems. This should only be used to reset disposable test nodes.
kwil-admin setup reset [--root_dir DIR] [--force] [--sqlpath DIR] [--snappath DIR]
This command only requires one: (a) --root_dir
to specify a node root
directory containing the files to reset, or (b) --force
to automatically reset
the files in the default node root directory at ~/.kwild
.
The paths to the SQLite files (--sqlpath
) and snapshots (--snappath
) are
optional, but provided here since they are configurable on the node.