[][src]Crate exonum_cli

Helper crate for secure and convenient configuration of the Exonum nodes.

exonum-cli supports multi-stage configuration process made with safety in mind. It involves 4 steps (or stages) and allows to configure and run multiple blockchain nodes without need in exchanging private keys between administrators.

How to Run the Network

  1. Generate common (template) part of the nodes configuration using generate-template command. Generated .toml file must be spread among all the nodes and must be used in the following configuration step.
  2. Generate public and secret (private) parts of the node configuration using generate-config command. At this step, Exonum will generate master key from which consensus and service validator keys are derived. Master key is stored in the encrypted file. Consensus secret key is used for communications between the nodes, while service secret key is used mainly to sign transactions generated by the node. Both secret keys may be encrypted with a password. The public part of the node configuration must be spread among all nodes, while the secret part must be only accessible by the node administrator only.
  3. Generate final node configuration using finalize command. Exonum combines secret part of the node configuration with public configurations of every other node, producing a single configuration file with all the necessary node and network settings.
  4. Use run command and provide it with final node configuration file produced at the previous step. If the secret keys are protected with passwords, the user need to enter the password. Running node will automatically connect to other nodes in the network using IP addresses from public parts of the node configurations.

Additional Commands

exonum-cli also supports additional CLI commands for performing maintenance actions by node administrators and easier debugging.

  • run-dev command automatically generates network configuration with a single node and runs it. This command can be useful for fast testing of the services during development process.
  • maintenance command allows to clear node's consensus messages with clear-cache, and restart node's service migration script with restart-migration.

How to Extend Parameters

exonum-cli allows to extend the list of the parameters for any command and even add new CLI commands with arbitrary behavior. To do so, you need to implement a structure with a list of additional parameters and use flatten macro attribute of serde and structopt libraries.

use exonum_cli::command::{Run, ExonumCommand};
use serde::{Deserialize, Serialize};
use structopt::StructOpt;

#[derive(Serialize, Deserialize, StructOpt)]
struct MyRunCommand {
    #[serde(flatten)]
    #[structopt(flatten)]
    inner: Run,

    /// My awesome parameter.
    #[structopt(name = "secret", long, default_value = "0")]
    secret_number: i32,
}

// Usage. We use `StructOpt::from_iter` for testing purposes;
// the real app should use `StructOpt::from_args`.
let command = MyRunCommand::from_iter(vec![
    "executable",
    "-c", "./node.toml",
    "--db-path", "./db",
    "--secret", "42",
]);
assert_eq!(command.secret_number, 42);
command.inner.execute()?;

You can also create own list of commands by implementing an enum with a similar principle:

use exonum_cli::command::Run;
use structopt::StructOpt;

// `MyRunCommand` defined as in the previous example...

#[derive(StructOpt)]
pub enum MyCommands {
    #[structopt(name = "run")]
    DefaultRun(Run),
    #[structopt(name = "my-run")]
    MyAwesomeRun(MyRunCommand),
}

While implementing custom behavior for your commands, you may use StandardResult enum for accessing node configuration files created and filled by the standard Exonum commands.

Re-exports

pub use structopt;

Modules

command

Standard Exonum CLI node configuration commands.

config

Contains various config structures used during configuration process.

password

This module contains utilities for passphrase entry.

Structs

DefaultConfigManager

Structure that handles work with config file at runtime.

NodeBuilder

Rust-specific node builder used for constructing a node with a list of provided services.

Spec

Deploy specification for a Rust artifact. The spec can include zero or more instantiated services.

Functions

load_config_file

Loads TOML-encoded file.

save_config_file

Saves TOML-encoded file.