Raft is a consensus algorithm that is designed to be easy to understand. It's equivalent to Paxos in fault-tolerance and performance. The difference is that it's decomposed into relatively independent subproblems, and it cleanly addresses all major pieces needed for practical systems. We hope Raft will make consensus available to a wider audience, and that this wider audience will be able to develop a variety of higher quality consensus-based systems than are available today.
$ make install-deps # Quick install system dependencies (macOS only)
$ make
$ ./raft --help🥳 Congrats, you just got the Raft binary running! Now, let's start a basic Raft server.
The basic command line format is as follows:
make
./raft --id <server_id>The first option --id <server_id> gives the server the specified name or
"server id". This is a friendly name that the server uses to identify itself to
other servers in the cluster, as well as to name thee persistent storage file.
This command looks for a config file at ./config and reads in information
about the Raft cluster from there. Here's what a simple config file for a single
server cluster looks like:
127.0.0.1 4000
This defines a server that listens for client requests on 127.0.0.1 and port
4000.
Now start the server like this:
./raft --id 0 --reset
./raft --id 0The --reset option must be included the first time a server is run to
establish the persistent storage and log files on disk. Read more about
--reset and the other command line options below.
🌟 That's it. Now that you know how to start a single Raft server, you're ready to start an entire Raft cluster. We'll do that in the next section.
To start a real Raft cluster, you need to run three copies of the program in parallel and ensure that each command is given a unique server id.
Here is a sample config file for a three server cluster:
127.0.0.1 4000 4001 4002
127.0.0.1 5000 5001 5002
127.0.0.1 6000 6001 6002
Each line represents a separate server. Since there are three servers in the cluster, each server needs to open two additional ports to receive connections from the other servers in the cluster.
Here are some commands you can copy-paste into three separate terminals to start up the cluster:
./raft --id 0 --reset
./raft --id 0./raft --id 1 --reset
./raft --id 1./raft --id 2 --reset
./raft --id 2✨ And just like that, you're running a Raft cluster!
The purpose of Raft is to make a bunch of servers work together to reliably update a state machine. So, we'll now discuss how to actually update the state in the state machine.
Note: In this implementation of Raft, we include a sample state machine that
takes terminal commands and runs them in bash, returning the output as a
string. The bash state machine conforms to the StateMachine interface defined
in state-machine.h and you can use it as an example when writing your own
state machine implementation, if you so desire.
First, start the ./client program which creates a REPL that sends commands to
the Raft cluster. The client automatically handles finding the leader server,
retrying the request with a different server if the leader becomes unavailable,
and displaying the output from running each command.
Here's what a sample run of the client looks like:
$ ./client
> echo hello
hello
> touch myfile.txt
> ls
myfile.txt
> quitTo reset the persistent storage of a server, use the --reset boolean argument.
This option is required the first time you start the server.
./raft --id <server_id> --resetNote: Do not use --reset when a server is rejoining the cluster after a
crash or shutdown as this will wipe away the persistent state and log which will
cause consistency issues. Adding/removing servers from the cluster as described
in the Raft paper is currently not supported in this implementation.
./raft --id <server_id> --config ./my_cool_config_fileTo use a custom configuration file location, use the --config string argument.
To show extremely verbose debug logs, use the --debug boolean argument.
./raft --id <server_id> --debugTo show only warnings and errors and hide almost every other log message, use
the --quiet boolean argument.
./raft --id <server_id> --quietGet help from the command line by using the --help boolean argument:
$ ./raft --help
Raft - An understandable consensus algorithm
Usage:
./raft [options] [peers ...]
Minimal Example:
Start a server that connects to one other server.
./raft --id <server_id> --reset
Cluster Example:
Start a three server Raft cluster.
Use the config file:
127.0.0.1 4000 4001 4002
127.0.0.1 5000 5001 5002
127.0.0.1 6000 6001 6002
Run:
./raft --id 0 --reset
./raft --id 1 --reset
./raft --id 2 --reset
Usage:
--config Path to configuration file (default = ./config) [string]
--debug Show all logs [bool]
--help Print help message [bool]
--id Server identifier [int]
--quiet Show only errors [bool]
--reset Delete server storage [bool]
macOS users with the Homebrew package manager installed can install all system dependencies in one step.
make install-depsProtocol buffers are a language-neutral, platform-neutral, extensible way of serializing structured data for use in communications protocols and data storage.
See the official Protocol Buffers website to learn more.
pkg-config is a helper tool used when compiling applications and libraries. It
helps you insert the correct compiler options on the command line.
See the official
pkg-config website
to learn more.
Copyright (c) Feross Aboukhadijeh and Jake McKinnon