{"id":17399282,"url":"https://github.com/feross/raft","last_synced_at":"2025-06-25T13:34:15.880Z","repository":{"id":65990044,"uuid":"178147619","full_name":"feross/raft","owner":"feross","description":"An understandable consensus algorithm ","archived":false,"fork":false,"pushed_at":"2019-03-28T07:16:32.000Z","size":251,"stargazers_count":25,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-03T02:53:06.610Z","etag":null,"topics":["cpp","raft","raft-consensus-algorithm"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/feross.png","metadata":{"files":{"readme":"README.md","changelog":"changes","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"feross"}},"created_at":"2019-03-28T07:15:47.000Z","updated_at":"2024-03-20T07:40:56.000Z","dependencies_parsed_at":null,"dependency_job_id":"9dc8291f-8cf9-4203-8397-693a04f19b8b","html_url":"https://github.com/feross/raft","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/feross%2Fraft","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/feross%2Fraft/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/feross%2Fraft/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/feross%2Fraft/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/feross","download_url":"https://codeload.github.com/feross/raft/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":232886000,"owners_count":18591917,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cpp","raft","raft-consensus-algorithm"],"created_at":"2024-10-16T15:14:58.945Z","updated_at":"2025-01-07T13:39:10.905Z","avatar_url":"https://github.com/feross.png","language":"C++","readme":"\u003ch1 align=\"center\"\u003e\n  \u003cbr\u003e\n  \u003cimg src=\"https://raft.github.io/logo/annie-solo.png\" alt=\"Raft logo\" width=\"200\"\u003e\n  \u003cbr\u003e\n  Raft - An understandable consensus algorithm\n  \u003cbr\u003e\n  \u003cbr\u003e\n\u003c/h1\u003e\n\n## What is Raft?\n\nRaft is a consensus algorithm that is designed to be easy to understand. It's\nequivalent to Paxos in fault-tolerance and performance. The difference is that\nit's decomposed into relatively independent subproblems, and it cleanly\naddresses all major pieces needed for practical systems. We hope Raft will make\nconsensus available to a wider audience, and that this wider audience will be\nable to develop a variety of higher quality consensus-based systems than are\navailable today.\n\n## Quick Start\n\n```bash\n$ make install-deps # Quick install system dependencies (macOS only)\n$ make\n$ ./raft --help\n```\n\n🥳 Congrats, you just got the Raft binary running! Now, let's start a basic Raft server.\n\n### Starting the Raft server\n\nThe basic command line format is as follows:\n\n```bash\nmake\n./raft --id \u003cserver_id\u003e\n```\n\nThe first option `--id \u003cserver_id\u003e` gives the server the specified name or\n\"server id\". This is a friendly name that the server uses to identify itself to\nother servers in the cluster, as well as to name thee persistent storage file.\n\nThis command looks for a config file at `./config` and reads in information\nabout the Raft cluster from there. Here's what a simple config file for a single\nserver cluster looks like:\n\n```\n127.0.0.1 4000\n```\n\nThis defines a server that listens for client requests on `127.0.0.1` and port\n`4000`.\n\nNow start the server like this:\n\n```bash\n./raft --id 0 --reset\n./raft --id 0\n```\n\nThe `--reset` option must be included the first time a server is run to\nestablish the persistent storage and log files on disk. Read more about\n`--reset` and the other command line options below.\n\n🌟 That's it. Now that you know how to start a single Raft server, you're ready\nto start an entire Raft cluster. We'll do that in the next section.\n\n### Start a three server Raft cluster\n\nTo start a real Raft cluster, you need to run three copies of the program in\nparallel and ensure that each command is given a unique server id.\n\nHere is a sample config file for a three server cluster:\n\n```\n127.0.0.1 4000 4001 4002\n127.0.0.1 5000 5001 5002\n127.0.0.1 6000 6001 6002\n```\n\nEach line represents a separate server. Since there are three servers in the\ncluster, each server needs to open two additional ports to receive connections\nfrom the other servers in the cluster.\n\nHere are some commands you can copy-paste into three separate terminals to start\nup the cluster:\n\n```bash\n./raft --id 0 --reset\n./raft --id 0\n```\n\n```bash\n./raft --id 1 --reset\n./raft --id 1\n```\n\n```bash\n./raft --id 2 --reset\n./raft --id 2\n```\n\n✨ And just like that, you're running a Raft cluster!\n\n### Sending commands to the cluster\n\nThe purpose of Raft is to make a bunch of servers work together to reliably\nupdate a state machine. So, we'll now discuss how to actually update the state\nin the state machine.\n\n**Note:** In this implementation of Raft, we include a sample state machine that\ntakes terminal commands and runs them in `bash`, returning the output as a\nstring. The bash state machine conforms to the `StateMachine` interface defined\nin `state-machine.h` and you can use it as an example when writing your own\nstate machine implementation, if you so desire.\n\nFirst, start the `./client` program which creates a REPL that sends commands to\nthe Raft cluster. The client automatically handles finding the leader server,\nretrying the request with a different server if the leader becomes unavailable,\nand displaying the output from running each command.\n\nHere's what a sample run of the client looks like:\n\n```bash\n$ ./client\n\u003e echo hello\nhello\n\u003e touch myfile.txt\n\u003e ls\nmyfile.txt\n\u003e quit\n```\n\n### A few odds and ends...\n\n#### Reset persistent storage\n\nTo reset the persistent storage of a server, use the `--reset` boolean argument.\nThis option is required the first time you start the server.\n\n```bash\n./raft --id \u003cserver_id\u003e --reset\n```\n\n**Note:** Do not use `--reset` when a server is rejoining the cluster after a\ncrash or shutdown as this will wipe away the persistent state and log which will\ncause consistency issues. Adding/removing servers from the cluster as described\nin the Raft paper is currently not supported in this implementation.\n\n#### Use a custom configuration file location\n\n```bash\n./raft --id \u003cserver_id\u003e --config ./my_cool_config_file\n```\n\nTo use a custom configuration file location, use the `--config` string argument.\n\n#### Show debug logs\n\nTo show extremely verbose debug logs, use the `--debug` boolean argument.\n\n```bash\n./raft --id \u003cserver_id\u003e --debug\n```\n\n#### Quiet mode\n\nTo show only warnings and errors and hide almost every other log message, use\nthe `--quiet` boolean argument.\n\n```bash\n./raft --id \u003cserver_id\u003e --quiet\n```\n\n### Command Line Help\n\nGet help from the command line by using the `--help` boolean argument:\n\n```\n$ ./raft --help\nRaft - An understandable consensus algorithm\n\nUsage:\n    ./raft [options] [peers ...]\n\nMinimal Example:\n    Start a server that connects to one other server.\n\n        ./raft --id \u003cserver_id\u003e --reset\n\nCluster Example:\n    Start a three server Raft cluster.\n\n    Use the config file:\n        127.0.0.1 4000 4001 4002\n        127.0.0.1 5000 5001 5002\n        127.0.0.1 6000 6001 6002\n\n    Run:\n    ./raft --id 0 --reset\n    ./raft --id 1 --reset\n    ./raft --id 2 --reset\n\nUsage:\n    --config  Path to configuration file (default = ./config) [string]\n    --debug   Show all logs                                   [bool]\n    --help    Print help message                              [bool]\n    --id      Server identifier                               [int]\n    --quiet   Show only errors                                [bool]\n    --reset   Delete server storage                           [bool]\n```\n\n## Install Dependencies\n\n### Quick Install (macOS only)\n\nmacOS users with the [Homebrew](https://brew.sh/) package manager installed can\ninstall all system dependencies in one step.\n\n```bash\nmake install-deps\n```\n\n### Protocol Buffers\n\nProtocol buffers are a language-neutral, platform-neutral, extensible way of\nserializing structured data for use in communications protocols and data storage.\n\nSee the official\n[Protocol Buffers](https://developers.google.com/protocol-buffers/) website to\nlearn more.\n\n### pkg-config\n\n`pkg-config` is a helper tool used when compiling applications and libraries. It\nhelps you insert the correct compiler options on the command line.\n\nSee the official\n[`pkg-config`](https://www.freedesktop.org/wiki/Software/pkg-config/) website\nto learn more.\n\n## Additional Raft Resources\n\n- [In Search of an Understandable Consensus Algorithm](https://raft.github.io/raft.pdf)\n- [Raft Visualization](https://raft.github.io/)\n\n# License\n\nCopyright (c) Feross Aboukhadijeh and Jake McKinnon\n","funding_links":["https://github.com/sponsors/feross"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffeross%2Fraft","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffeross%2Fraft","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffeross%2Fraft/lists"}