diff --git a/README.md b/README.md index f220f5ecc8..aaae18ff9f 100644 --- a/README.md +++ b/README.md @@ -38,15 +38,17 @@ when a backwards incompatible change is made. ## Install and Build (Ubuntu Linux 18.04) -Concord-BFT supports two kinds of builds: native and docker. +Concord-BFT supports two kinds of builds are, +* Docker +* Native -The docker build is **strongly recommended**. +The docker build is **strongly recommended** ### Docker -* Install the latest docker. +* [Install the latest docker] (https://docs.docker.com/engine/install/ubuntu/). * Optional: [configure docker as non-root user](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user). -* Build: +* Build concord-bft ```sh cd concord-bft make @@ -55,9 +57,11 @@ make test Run `make help` to see more commands. Note: +* If you face any format related issues than run `make format` before running `make` command to build concord-bft. * The output binaries are stored in the host's `concord-bft/build`. -* `Makefile` is configurable. -For example, if you want to use another compiler you may pass it to the `make`: +* Default compiler is clang and clang++. +* `Makefile` is configurable. If you want to use another compiler you may pass it to the `make`. +For example, ``` make CONCORD_BFT_CONTAINER_CXX=g++ \ CONCORD_BFT_CONTAINER_CC=gcc \ @@ -66,17 +70,12 @@ make CONCORD_BFT_CONTAINER_CXX=g++ \ Other build options, including passthrough options for CMake, are defined in the Makefile and prefixed with `CONCORD_BFT_`. Variables that are capable of being overridden on the commandline are set with the Make conditional operator `?=` and are at the beginning of [Makefile](Makefile). Please check that file for options. -#### Select comm module -One option that is worth calling out explicitly is the communication (transport) library. Transport defaults to TLS and can be configured explicitly by setting the `CONCORD_BFT_CMAKE_TRANSPORT` flag. The flag defaults to **TLS**, but also supports **UDP** and **TCP**. These can be useful because the use of pinned certificates for TLS requires an out of band setup. - -See [create_tls_certs.sh](scripts/linux/create_tls_certs.sh) for an example. This script is used in apollo tests. For production usage, an out of band deployment for each replica must be used to avoid revealing private keys to each replica. - ### Native ```sh git clone https://github.com/vmware/concord-bft cd concord-bft -sudo ./install_deps.sh # Installs all dependencies and 3rd parties +sudo ./install_deps.sh # Install all dependencies and 3rd parties mkdir build cd build cmake .. @@ -88,21 +87,17 @@ In order to turn on or off various options, you need to change your cmake config done by passing arguments to cmake with a `-D` prefix: e.g. `cmake -DBUILD_TESTING=OFF`. Note that make must be run afterwards to build according to the configuration. Please see [CMakeLists.txt](CMakeLists.txt) for configurable options. -#### Select comm module -One option that is worth calling out explicitly is the communication (transport) library. -We support both UDP and TCP communication. UDP is the default. In order to -enable TCP communication, build with `-DBUILD_COMM_TCP_PLAIN=TRUE` in the cmake -instructions shown above. If set, the test client will run using TCP. If you -wish to use TCP in your application, you need to build the TCP module as -mentioned above and then create the communication object using CommFactory and -passing PlainTcpConfig object to it. - -We also support TCP over TLS communication. To enable it, change the -`BUILD_COMM_TCP_TLS` flag to `TRUE` in the main CMakeLists.txt file. When -running simpleTest using the testReplicasAndClient.sh - there is no need to create TLS certificates manually. The script will use the `create_tls_certs.sh` (located under the scripts/linux folder) to create certificates. The latter can be used to create TLS files for any number of replicas, e.g. when extending existing tests. +### Select comm module +One option that is worth calling out explicitly is the communication (transport) library. Transport defaults to TLS and can be configured explicitly by setting the `CONCORD_BFT_CMAKE_TRANSPORT` flag. The flag defaults to **TLS**, but also supports **UDP** and **TCP**. +In order to enable TCP or UDP communication, build with below flags, +``` +make build CONCORD_BFT_CMAKE_TRANSPORT=TCP # To enable TCP communication +make build CONCORD_BFT_CMAKE_TRANSPORT=UDP # To enable UDP communication +``` +These can be useful because the use of pinned certificates for TLS requires an out of band setup. -As we used pinned certificates for TLS, the user will have to manually provide these. THey can use the [create_tls_certs.sh](scripts/linux/create_tls_certs.sh) script as an example. +See [create_tls_certs.sh](scripts/linux/create_tls_certs.sh) for an example. This script is used in apollo tests. For production usage, an out of band deployment for each replica must be used to avoid revealing private keys to each replica. ### C++ Linter @@ -178,34 +173,42 @@ Please find more details about the Apollo framework [here](tests/apollo/README.m ## Run examples -### Simple test application (4 replicas and 1 client on a single machine) - -Tests are compiled into in the build directory and can be run from anywhere as -long as they aren't moved. - -Run the following from the top level concord-bft directory: - - ./build/tests/simpleTest/scripts/testReplicasAndClient.sh - -### Using simple test application via Python script - -You can use the simpleTest.py script to run various configurations via a simple -command line interface. -Please find more information [here](./tests/simpleTest/README.md) +### Simple Test application +Simple Test application is used to demonstrate how to use concord and enables you to perform READ and WRITE requests +from client to replicas on a single-register state machine and then the consensus algorithm is run using this setup. +Simple Test is compiled into the build directory and can be run from anywhere as long as it isn't moved. +Simple Test can be run using 2 methods: +#### 1) Shell script +./build/tests/simpleTest/scripts/testReplicasAndClient.sh +You can use this shell script to run Simple Test using default configuration i.e. 4 replicas and 1 client. +#### 2) Python script +./build/tests/simpleTest/scripts/simpleTest.py +You can use the simpleTest.py script to run various configurations via a simple command line interface. +Please find more information on Simple Test [here](./tests/simpleTest/README.md) ## Directory Structure -- [bftengine](./bftengine): concord-bft codebase - - [include](./bftengine/include): external interfaces of concord-bft (to be used by client applications) - - [src](./bftengine/src): internal implementation of concord-bft - - [tests](./bftengine/tests): tests and usage examples -- [threshsign](./threshsign): crypto library that supports digital threshold signatures - - [include](./threshsign/include): external interfaces of threshsign (to be used by client applications) - - [src](./threshsign/src): internal implementation of threshsign - - [tests](./threshsign/tests): tests and usage examples -- [scripts](./scripts): build scripts -- [tests](./tests): BFT engine system tests +- [bftengine](./bftengine): Library containing State transfer, SBFT consensus, and Pre execution. +- [ccron](./ccron): Distributed Job Scheduler. Find more information [here](./ccron/README.md) +- [client](./client): Contains the implementation of BFT Client and Thin Replica Client. +- [communication](./communication): Contains the abstractions which is used by all the Replicas to send and receive messages. +- [diagnostics](./diagnostics): This library is used for building interactive diagnostics for applications built on top of concord-bft. +- [docs](./docs): Contains documentation of design decisions for various components of concord. This is a place where we will opensource our design and provide tutorials to onboard new developers from the community. +- [kvbc](./kvbc): This contains the code for Key-Value Blockchain (Merkle tree-based). Find more information [here](./docs/kvbc) +- [logging](./logging): Log4cpp abstraction for concord open source. +- [messages](./messages): Concord Message format library which does code generation for serialization and deserialization of messages. Find more information [here](./messages/README.md) +- [performance](./performance): Components provided for making better performance measurements and bottleneck analysis. +- [reconfiguration](./reconfiguration): This is the reconfiguration handler library. But major code of reconfiguration is in closed source. +- [scripts](./scripts): Some miscellaneous scripts. +- [secretsmanager](./secretsmanager): Abstraction for encryption and decryption. +- [storage](./storage): Library abstracting the storage layer. It provides functions to access RocksDB and MemoryDB. +- [tests](./tests): Contains a Tester Replica, Test client, and Apollo Testing Framework. +- [thin-replicap-server](./thin-replica-server): Implementation of Thin Replica Server. +- [thirdparty](./thirdparty): Some third party cmake files for external dependencies. +- [threshsign](./threshsign): crypto library that supports digital threshold signatures. +- [tools](./tools): This is a tools folder for any tools that we create, like tools for generating all the keys required by the replicas in a Concord cluster. +- [util](./util): This contains the utility libraries, like thread pools, metrics, asserting, crypto utilities, etc. ## Contributing @@ -215,9 +218,6 @@ signed our contributor license agreement (CLA), our bot will update the issue wh questions about the CLA process, please refer to our [FAQ](https://cla.vmware.com/faq). For more detailed information, refer to [CONTRIBUTING.md](CONTRIBUTING.md). -## Notes -The library calls `std::terminate()` when it cannot continue in a safe manner. -In that way, users can install a handler that does something different than just calling `std::abort()`. ## Community diff --git a/tests/simpleTest/README.md b/tests/simpleTest/README.md index fefbb51486..86ca7540ab 100644 --- a/tests/simpleTest/README.md +++ b/tests/simpleTest/README.md @@ -53,7 +53,7 @@ make login Then, you can run the test using the following command: ``` -./build/bftengine/tests/simpleTest/scripts/testReplicasAndClient.sh +./build/tests/simpleTest/scripts/testReplicasAndClient.sh ``` You should see output like the following: @@ -218,14 +218,14 @@ Once you have built Concord and are in the top-level directory, you can run the test with the following command: ``` -./build/bftengine/tests/simpleTest/scripts/simpleTest.py -bft n=4,r=4,f=1,c=0,cl=1 +./build/tests/simpleTest/scripts/simpleTest.py -bft n=4,r=4,f=1,c=0,cl=1 ``` The command above is EQUAL to running the test via the shell script, as desribed above. Note: if you run the command as described above and experience Python related issues, please run it using - python3 build/bftengine/tests/simpleTest/scripts/simpleTest.py -bft n=4,r=4,f=1,c=0,cl=1 + python3 build/tests/simpleTest/scripts/simpleTest.py -bft n=4,r=4,f=1,c=0,cl=1 ### BFT Metadata with the simple test BFT metadata allows replica to recover from crash if the metadata has been written to the disk when replica is running.