Hyperledger Besu starts and is controlled through the command line interface (CLI) of your computer. For example, when a Hyperledger Besu node is started up to connect to mainnet, this is done by opening the command line and running the command:
besu
This command is actually calling default options and subcommands that tell the client software how to set up the node. When we call the above command, behind the scenes we are actually calling:
besu --network=mainnet --datapath=besu --api-gas-price-blocks=100 --api-gas-price-max=500000000000 --api-gas-price-percentile=50.0 --bootnodes=enode://[email protected]:30303,enode://[email protected]:30303 --config-file=none --discovery-enabled=true --miner-coinbase=<Your Ethereum account address> --min-gas-price=1000
This is quite a bit longer than running the besu command! What we are trying to illustrate is the fact that besu is very customizable, but we have to use specific syntax (options and subcommands) in the command line in order to customize the node(s) and network created upon starting up Besu.
The above is an example of the options and subcommands that apply to creating a full node running proof of work (PoW) consensus for mainnet Ethereum. However, these options and subcommands can also be used to create private and consortium networks. The same customizations that we discussed in our previous article, Hyperledger Besu: How to Create an Ethereum Genesis File, can be called from the command line. The Hyperledger Besu documentation has all the options and subcommands that you can apply when using Hyperledger Besu. In this article, we are going to explain options and subcommands, and introduce the concept that certain combinations of options and subcommands allow us to create a specific configuration of our Ethereum client.
What is an option? What is a subcommand?
When using the CLI, we call commands. These commands are programs (they may also sometimes be classified as scripts) that tell the computer to do a specific set of actions. When Hyperledger Besu is installed on your computer, it creates a global command besu - which tells your computer to run the Besu client with the default options and subcommands we showed above. Let’s walk through some of those in more detail.
Options: --network
Options are variables that work with the base command of besu. One example option is
--network=<NETWORK>
When we run the besu command, the default network is mainnet, so running
besu
or
besu --network=mainnet
accomplishes the same outcome - Hyperledger Besu starts the process of connecting to mainnet.
But, we can tell Hyperledger Besu to connect to different networks, including a local testnet on our computer. If we wanted Hyperledger Besu to connect to the testnet Rinkeby, we would use the option:
besu --network=rinkeby
If we want Besu to start locally on our computer as a private PoW network, the network option becomes
besu --network=dev
You are now starting to see how an option modifies the command besu.
Subcommands: blocks
Subcommands are programs that tell the computer to run an additional operation. An example of a subcommand is
besu blocks export [--start-block=<LONG>] [--end-block=<LONG>] --to=<block-file>
This highlighted subcommand tells Hyperledger Besu to export a block or a range of blocks from storage to a file in a recursive length prefix (RLP) format.
In practice this would be called like:
besu blocks export --start-block=100 --end-block=300 --to=/home/exportblock.bin
We have told Hyperledger Besu to export blocks 100 to 300 from mainnet to the location on our computer ~/home/exportblock.bin
The subcommand differs from an option because it is a subcommand telling the computer to run another program, whereas an option is telling the computer to modify the parameters of the original command. Subcommands are short lived and give the user functionality related blocks, keys, or a configuration, do a specific quick task, and then exit. They do not keep the command running or connect to a network.
A subcommand and option are different in the ways they interact with the program. As we saw earlier, an option modifies a program by providing it with certain parameters. The subcommand, on the other hand, is actually telling the program to run another operation entirely.
Examples
In our first example, we are going to create a local development blockchain that uses PoW consensus, we want the maximum amount of verbosity (or information) the logs provide, and the output of the command line be color coded. This looks like
besu --network=dev --logging=ALL --color-enabled=true
--network=dev is the option to create a local development blockchain with PoW consensus
--logging=ALL is the option to provide maximum verbosity of the logs
--color-enabled=true is the option to color code the command line outputs
In our second example, we are doing to be using options and subcommands to create an address for a Node in a permissioned network created using Clique PoA. As part of the set up for the network, we need to export an address for the Node that will start the network. This looks like:
besu --data-path=data public-key export-address --to=data/nodeAddress1
--data-path= data is an option indicating the location of database on disk. In this case, it is within the folder data
public-key export-address to=data/nodeAddress1 is a subcommand outputting the node address to the file nodeAddress1, which will be inside the folder data
We have just touched the surface of what can be accomplished using options and subcommands. We encourage you to further explore the options and subcommands, and then come join us in the Consensys Discord to discuss how you are using Hyperledger Besu.