# Command-line tools
Drand's main functionality is provided by the
drand program, which allows you to run a drand server and control its operation. You can also
drand as a client to fetch randomness from a drand network.
See the Supplemental Tools for some other helpful tools for scaling drand, as well as a standalone client for consuming randomness.
# Installing drand
# Binary releases
The simplest way to get
drand is to download a pre-built binary release (opens new window) for your platform.
You can verify the checksum of a
drand binary release by checking the
checksums.txt listed in the GitHub assets for the release, which
contains the SHA-256 checsum for each release archive. To check your local download, you can use the
shasum -a 256 <path-to-drand.tar.gz>
# Source code
You can compile
drand from source code by cloning the drand GitHub repository (opens new window) and building the project.
With those requirements met, install drand via:
git clone https://github.com/drand/drand cd drand make install
This will install
$GOPATH/bin, which should be on your
$PATH if you followed the standard Go install instructions.
If you'd prefer not to install
drand globally, or if you want to put the
drand binary in a different location, you can run
make build instead
make install. This will create the
drand binary in the current directory.
This section gives a basic overview of the main
drand CLI interface to give an idea of the options available.
If you're setting up a drand network deployment, please see the Deployment Guide, which walks through
drand to run a live network.
drand command has several subcommands. Among the most important is
drand help, which will introduce you to
the rest of the subcommands:
$ drand help NAME: drand - distributed randomness service USAGE: drand [global options] command [command options] [arguments...] VERSION: 0.0.0 COMMANDS: start Start the drand daemon. stop Stop the drand daemon. share Launch a sharing protocol. load Launch a sharing protocol from filesystem follow follow and store a randomness chain generate-keypair Generate the longterm keypair (drand.private, drand.public) for this node, and load it on the drand daemon if it is up and running. get get allows for public information retrieval from a remote drand node. util Multiple commands of utility functions, such as reseting a state, checking the connection of a peer... show local information retrieval about the node's cryptographic material. Show prints the information about the collective public key (drand.cokey), the group details (group.toml), the long-term private key (drand.private), the long-term public key (drand.public), or the private key share (drand.share), respectively. help, h Shows a list of commands or help for one command GLOBAL OPTIONS: --verbose If set, verbosity is at the debug level (default: false) --folder value Folder to keep all drand cryptographic information, with absolute path. (default: "/Users/<username>/.drand") --help, -h show help (default: false) --version, -v print the version (default: false)
help command can be used for subcommands as well, for example
drand help generate-keypair. If you prefer, you can
also show help with the
--help flag after the subcommand name, e.g.:
drand generate-keypair --help.
generate-keypair command creates a long-term public/private keypair for a drand network. You must provide the
address that your drand node will listen on, including the publicly reachable port number. This may be different
from the port specified when starting the daemon, for example if you've set up
drand to run behind a reverse
proxy as described in the Deployment Guide. These new keys will be loaded on drand daemon if the daemon
is up and running.
$ drand help generate-keypair NAME: drand generate-keypair - Generate the longterm keypair (drand.private, drand.public) for this node, and load it on the drand daemon if it is up and running. USAGE: drand generate-keypair [command options] <address> is the address other nodes will be able to contact this node on (specified as 'private-listen' to the daemon) OPTIONS: --control value Set the port you want to listen to for control port commands. If not specified, we will use the default port 8888. --folder value Folder to keep all drand cryptographic information, with absolute path. (default: "/Users/<username>/.drand") --tls-disable Disable TLS for all communications (not recommended). (default: false) --id value Indicates the id for the randomness generation process which will be started
The generated key and all other drand state will be stored in
$HOME/.drand by default, but this
can be overridden with the
--tls-disable flag should only be used if you intend to run an insecure test deployment without TLS protection.
drand itself or a reverse proxy is providing TLS protection, the keypair must be generated with TLS
set to the default of
--id flag should be used when generating long-term public/private keypair for networks with beacon id different from
default. If you don't provide a value, the default beacon id will be used. For example, a network with beacon id
beacon_name_x, you must set the flag
If you use a non-standard control port, you will also need to use the
when running this command.
start command starts the drand daemon. Note that
drand does not automatically go into the background when launched, and
long-running deployments should be run inside of a
tmux session, or otherwise "daemonized" using the tools available
for your operating system.
If this node has already joined a network by performing a Distributed Key Generation phase, it will attempt to catch up with the drand beacon chain by contacting other nodes and will participate in the randomness generation protocol once it has caught up.
If the DKG has not yet been performed, the daemon will wait for an operator to begin the DKG phase using the
drand share command.
$ drand help start NAME: drand start - Start the drand daemon. USAGE: drand start [command options] [arguments...] OPTIONS: --folder value Folder to keep all drand cryptographic information, with absolute path. (default: "/Users/<username>/.drand") --tls-cert value Set the TLS certificate chain (in PEM format) for this drand node. The certificates have to be specified as a list of whitespace-separated file paths. This parameter is required by default and can only be omitted if the --tls-disable flag is used. --tls-key value Set the TLS private key (in PEM format) for this drand node. The key has to be specified as a file path. This parameter is required by default and can only be omitted if the --tls-disable flag is used. --tls-disable Disable TLS for all communications (not recommended). (default: false) --control value Set the port you want to listen to for control port commands. If not specified, we will use the default port 8888. --private-listen value Set the listening (binding) address of the private API. Useful if you have some kind of proxy. --public-listen value Set the listening (binding) address of the public API. Useful if you have some kind of proxy. --metrics value Launch a metrics server at the specified (host:)port. --certs-dir value directory containing trusted certificates (PEM format). Useful for testing and self signed certificates --push Push mode forces the daemon to start making beacon requests to the other node, instead of waiting the other nodes contact it to catch-up on the round (default: false) --verbose If set, verbosity is at the debug level (default: false) --private-rand Enables the private randomness feature on the daemon. By default, this feature is disabled. (default: false) --from value Old group.toml path to specify when a new node wishes to participate in a resharing protocol. This flag is optional in case a node is already included in the current DKG. --skipValidation skips bls verification of beacon rounds for faster catchup. (default: false) --json Set the output as json format (default: false)
# Endpoint configuration
drand exposes up to four endpoints, depending on the flags passed in.
The private drand API endpoint is used to communicate with other nodes using gRPC. The private API is always enabled.
As drand can now support multiple beacons, it will always need the private address to be set, in order to know where to listen.
You can pass the
--private-listen flag and specify the
host:port to bind to. Note that the addresss associated with
the keypair must be publicly accessible and mapped to the
--private-listen address, for example using a reverse proxy.
While the private API is primarily intended for inter-node communication, it may be exposed to the internet to allow clients
to fetch randomness over gRPC using the
drand get command and/or
This will not allow access to any secret information, but we generally recommend restricting gRPC access using firewall
rules to limit the potential for denial of service attacks.
The control API endpoint is used by the
drand command to control a running drand daemon using commands like
The control interface is always enabled and bound to the
localhost interface. The default port is
8888, but this can be
overridden with the
--control flag. If you use a non-standard control port, you will also need to use the
when running other commands such as
The control API exposes private information, therefore, the control port must not be exposed to the internet and should
be used only from the local machine where the
drand daemon is running.
The remaining endpoints are optional, and will only be enabled if the flags are given.
The public HTTP endpoint provides an API that clients can fetch randomness from. To enable it, pass in the
--public-listen flag and specify the
host:port that you want to listen on. This endpoint exposes no sensitive
information and is safe to expose to the internet. Alternatively, you may keep this endpoint behind a firewall and
expose randomness to the public with the help of a relay server such as
Finally, the metrics endpoint provides an API for observing runtime metrics about the drand node. It can be enabled
--metrics <metrics-port> flag. See drand Metrics for more details on accessing the metrics.
The metrics API may expose sensitive information about the running
drand daemon, and should not be exposed to the public internet.
# TLS configuration
--tls-key commands give the path to TLS certificates and keys needed for
drand to provide TLS protection
to its connections with other
drand nodes. If you are using a reverse proxy as described in the Deployment Guide,
you should pass the
--tls-disable flag, as the proxy will handle TLS instead of
--tls-disable flag may also be used to run without TLS entirely, but we do not recommend disabling TLS except for local
drand development. If you do run without TLS, you must also provide the
--tls-disable flag when
generating your key.
For more on TLS setup, see the Deployment Guide.
stop command tells the
drand daemon to shut down. If no beacon id is set, it will stop the entire daemon.
However, if you provide the
--id flag and a value, it will only stop that specific network.
$ drand help stop NAME: drand stop - Stop the drand daemon. USAGE: drand stop [command options] [arguments...] OPTIONS: --control value Set the port you want to listen to for control port commands. If not specified, we will use the default port 8888. --id value Indicates the id for the randomness generation process which will be started
If the daemon was started with a non-standard control port, you must use the
--control flag to specify the control port
reload command tells the
drand daemon to load a network which has been previously stopped. You
--id flag to choose the correct network to load again.
$ drand help load NAME: drand load - Launch a sharing protocol from filesystem USAGE: drand load [command options] [arguments...] OPTIONS: --control value Set the port you want to listen to for control port commands. If not specified, we will use the default port 8888. --id value Indicates the id for the randomness generation process which will be started
If the daemon was started with a non-standard control port, you must use the
--control flag to specify the control port
share command tells the
drand daemon to begin the Distributed Key Generation (DKG) protocol on a new network to create private
key shares with the other drand nodes.
share command must be used when setting up a new drand network before randomness generation can begin. It may also be
used after the network is running to "re-share" the key material, which allows us to change the members of the drand network
without interrupting the generation of randomness.
For details about to running the initial DKG, see the Deployment Guide.
$ drand help share NAME: drand share - Launch a sharing protocol. USAGE: drand share [command options] [arguments...] OPTIONS: --tls-disable Disable TLS for all communications (not recommended). (default: false) --control value Set the port you want to listen to for control port commands. If not specified, we will use the default port 8888. --from value Old group.toml path to specify when a new node wishes to participate in a resharing protocol. This flag is optional in case a node is already included in the current DKG. --timeout value Timeout to use during the DKG, in string format. Default is 10s --source value Source flag allows to provide an executable which output will be used as additional entropy during resharing step. --user-source-only user-source-only flag used with the source flag allows to only use the user's entropy to pick the dkg secret (won't be mixed with crypto/rand). Should be used for reproducibility and debbuging purposes. (default: false) --secret-file value Specify the secret to use when doing the share so the leader knows you are an eligible potential participant. must be at least 32 characters. --period value period to set when doing a setup --nodes value number of nodes expected (default: 0) --threshold value threshold to use for the DKG (default: 0) --connect value Address of the coordinator that will assemble the public keys and start the DKG --out value save the group file into a separate file instead of stdout --leader Specify if this node should act as the leader for setting up the group (default: false) --beacon-delay value Leader uses this flag to specify the genesis time or transition time as a delay from when group is ready to run the share protocol (default: 0) --transition When set, this flag indicates the share operation is a resharing. The node will use the currently stored group as the basis for the resharing (default: false) --force When set, this flag forces the daemon to start a new reshare operation.By default, it does not allow to restart one (default: false) --catchup-period value Minimum period while in catchup. Set only by the leader of share / reshares (default: "0s") --scheme value Indicates a set of values drand will use to configure the randomness generation process (default: "pedersen-bls-chained") --id value Indicates the id for the randomness generation process which will be started
The node that begins the sharing procedure should run with the
--leader flag. The other nodes use the
--connect <leader-addr> flag, passing
in the address of the leader.
All nodes must specify the following values:
--secret- a secret value, shared out-of-band with the other node operators. When re-sharing, this may be distinct from the secrets used for any prior DKG rounds.
--id- the unique identifier of the new network we will start. This value cannot be change on re-sharing. This identifier must be equal to the one used when generating long-term keypair. If you don't set this value, the default identifier will be used.
Only the leader must specify the following values:
--period- sets the interval between rounds of the drand beacon chain. This must be a string that's parse-able by Golang's time.ParseDuration function (opens new window), for example "30s" or "1m".
--nodes- the number of nodes expected to take part in the DKG. Note that the DKG will succeed even if fewer nodes participate, so long as there are enough to meet the threshold.
--threshold- the number of nodes required to generate randomness. The DKG will fail if fewer than
thresholdnodes participate in the DKG before the timeout.
When re-sharing to nodes that are not members of the existing drand group, the new nodes must obtain a copy of the group configuration file
from an existing member, and use the
--from <group-file-path> flag to specify the path to the
group.toml file. In this case,
is not required, as the unique identifier will be taken from the file. Members of the existing group may omit the
--from flag, as they already
posse the current group configuration.
You can mix an external source of entropy into the key sharing protocol by using the
--source flag. The argument should be the path
to an executable that must output random binary data when run. By default, external entropy sources are mixed with Golang's
crypto/rand secure RNG. The
--user-source-only flag overrides this default, which is useful during testing and debugging to allow a reproducible "random" value,
but should not be used in production.
get command allows you to fetch public information from a running drand node, including random values and the public
distributed key. Note that you do not need to be a node operator or a member of the drand group in order to use
but you will need a copy of the group configuration file. You will also need access to the gRPC API endpoint, which may be
protected by firewall rules.
$ drand get --help NAME: drand get - get allows for public information retrieval from a remote drand node. USAGE: drand get command [command options] [arguments...] COMMANDS: private Get private randomness from the drand beacon as specified in group.toml. Only one node is contacted by default. Requests are ECIES-encrypted towards the public key of the contacted node. This command attempts to connect to the drand beacon via TLS and falls back to plaintext communication if the contacted node has not activated TLS in which case it prints a warning. public Get the latest public randomness from the drand beacon and verify it against the collective public key as specified in group.toml. Only one node is contacted by default. This command attempts to connect to the drand beacon via TLS and falls back to plaintext communication if the contacted node has not activated TLS in which case it prints a warning. chain-info Get the binding chain information that this node participates to help, h Shows a list of commands or help for one command OPTIONS: --help, -h show help (default: false) --version, -v print the version (default: false)
There are three main subcommands for
drand get public <path-to-group.toml>returns the latest public random value from the group described in
group.toml. You may fetch a specific round instead of the latest by supplying the
drand get private <path-to-group.toml>sends an encrypted request for private randomness to one of the nodes in
drand get chain-info --chain-hash <value>returns the binding chain information that this node participates to. In order to choose a network among the running ones on a node, you must provide the chain hash of it.
show command returns private information from a local
drand node, including its private cryptographic material.
There are several subcommands for
drand show shareprints the private distributed key share for the local node.
drand show groupprints the group configuration file. If a DKG has been performed, this will include the distributed public key.
drand show chain-infoprints the information for the randomness chain the local node is participating in.
drand show privateprints the long-term private key of the local node.
drand show publicprints the long-term public key of the local node.
For full usage information, run
drand show --help.
You must use
--id flag to choose between all running networks on the node.
util command provides several subcommands that are useful for debugging and managing local node state:
drand util check <address>attempts to contact the node at the given address to see if it's online and responding to requests. This can be used to check that a running network on your local node is reachable at its public address, or to make sure that a remote node can be reached before running
drand util list-schemeslists all scheme the node supports and can be used on share command.
drand util remote-statusasks for the statuses of remote networks' nodes indicated by
ADDRESS1 ADDRESS2 ADDRESS3..., including the network visibility over the rest of the addresses given.
drand util statusgets the status of many modules of a running network on the local node.
drand util migrateruns the migration required the multi-beacon folder structure on the local node.
drand util pingsends a ping to the local
dranddaemon and prints its status.
drand util backupbacks up the primary drand database of a running network to a secondary location.
drand util self-signsigns the public identity of a running network. Needed for backward compatibility with previous versions.
drand util resetdeletes all distributed information (group file, key share, random beacon state, etc) from a network on the local node. It does NOT delete the long-term keypair.
drand util del-beacon <round-number>deletes all beacon chain rounds from
<round-number>until the current head of the beacon chain from a running network's database. You MUST restart the running network after issuing this command.
For full usage information, run
drand util --help.
# Supplemental tools
In addition to the main
drand cli app, there are several supplemental tools that can be used to consume randomness from
a drand network or help securely scale a drand deployment.
The following tools do not yet have binary releases and must be installed from source. The basic procedure is the same
as installing drand from source, but instead of
make install or
make build, you'll run one of:
drand-client command is a standalone drand client that's optimized to fetch randomness from a drand network and provide it over a CDN.
The client is configured with the URL for a drand HTTP endpoint, and may optionally be configured with the addresses of one or more libp2p relay nodes. If libp2p relays are configured, the HTTP endpoint will be used as a fallback if the libp2p relays fail to deliver randomness at the expected interval.
To see full usage information, run
drand-relay-http command provides a gRPC to HTTP relay server that can be used to relay requests from the public internet to a drand
daemon. This is an alternative to the public HTTP endpoint that runs in the main
drand process when starting
drand with the
--public-listen flag is convenient, running a seperate relay process allows the HTTP communications to be isolated from the
drand process, which limits the attack surface of the
To see full usage information, run
drand-relay-gossip command provides a relay server that connects to a drand node over gRPC and provides randomness to consumers over
a libp2p PubSub (opens new window) topic. Randomness provided by a gossip relay may be consumed directly
over PubSub by libp2p-capable programs, and/or via a CDN which has been configured to listen to a PubSub topic using