Ouroboros Prototype

 This page is under construction  

The Ouroboros prototype is a user-space decentralized packet network implementation based on an overhauled networking model. It is being developed in C for POSIX operating systems.

This prototype is very much a work in progress.

On this page are instructions for installing the prototype. Once done, head to the tutorials section. The old documentation website is still available for reference, but only this wiki is maintained.

Install the Prototype

The prototype consists of the library, which provides the core Application Programming Interfaces (Unicast API and Broadcast API), the functions of the application end-to-end layer and various functions used by the other components in the prototype; the IPC Resource Management daemon IRMd, which is the core component for administering Ouroboros; the IPCPs that actually forward packets and make up the (peer-to-peer) packet network; and a collection of tools, of which the most important is the IPC Resource Management (IRM) Command Line Interface (CLI) for management and some basic tools for demo purposes. In addition, there is an orchestration framework for setting up experiments and an InfluxDB exporter for observability. The prototype is written in C, but we provide some APIs for other popular languages, currently Python and Rust.

Requirements

Ouroboros builds on most POSIX compliant systems. Below you will find instructions for GNU/Linux, FreeBSD and OS X. On Windows 10, you can build Ouroboros using the Linux Subsystem for Windows.

Get Ouroboros

You can clone Ouroboros using the command line from its website or, if you prefer you can clone and/or fork from our Github or BitBucket mirrors.

$ git clone https://ouroboros.rocks/git/ouroboros
$ git clone git://ouroboros.rocks/ouroboros
$ git clone https://github.com/dstaesse/ouroboros

Another option is downloading a snapshot tarball and extracting it. Optional repositories are pyOuroboros, a Python wrapper to write Ouroboros programs in Python, and ouroboros-metrics that contains an InfluxDB exporter.

Dependencies

To build Ouroboros, you need cmake, google protocol buffers installed in addition to a C compiler (gcc or clang) and make.

On GNU/Linux you will need either libgcrypt (≥ 1.7.0) or libssl if your glibc is older than version 2.25.

On OS X, you will need homebrew. Disable System Integrity Protection during the installation and/or removal of Ouroboros.

Optionally, you can also install libgcrypt, libssl (to enable encryption), fuse (to enable exporting internal metrics), and dnsutils (to enable use of a DynDNS server to be used as a naming directory for a UDP layer). Setting up a DNS server (e.g. bind) is out of scope of this installation guide.

Debian/Ubuntu Linux

$ apt-get install git protobuf-c-compiler cmake
$ apt-get install libgcrypt20-dev libssl-dev libfuse-dev dnsutils cmake-curses-gui

If during the build process cmake complains that the Protobuf C compiler is required but not found, and you installed the protobuf-c-compiler package, you will also need this:

$ apt-get install libprotobuf-c-dev

Arch Linux

$ pacman -S git protobuf-c cmake
$ pacman -S libgcrypt openssl fuse dnsutils

FreeBSD 11/12/13/14

$ pkg install git protobuf-c cmake
$ pkg install libgcrypt openssl fusefs-libs bind-tools

Mac OS X 10/11/12/13/14

$ brew install git protobuf-c cmake
$ brew install libgcrypt openssl

On mac OS X, you may also need to add /usr/local/include/ to your build path (e.g. when compiling with libtomlc99):

$ export C_INCLUDE_PATH=/usr/local/include

There is a known issue with homebrew and protobuf-c 1.5.0.4:

https://github.com/Homebrew/homebrew-core/issues/168501
https://github.com/protobuf-c/protobuf-c/pull/711

A confirmed workaround is to replace "protoc-c" with "protoc" in the build.cmake scripts for the following components before running make:

libouroboros-common
libouroboros-irm
ipcpd-unicast

Configuration file support

It is highly recommended you install libtomlc99 before building O7s to enable configuration file support.

GNU/Linux and mac OS X

git clone https://github.com/cktan/tomlc99
cd tomlc99
make && sudo make install

FreeBSD

The tomlc99 makefiles contain directives specific to GNU make. You will need to install and use gmake instead of make:

pkg install gmake

git clone https://github.com/cktan/tomlc99
cd tomlc99
gmake && sudo gmake install

Installation instructions

Arch Linux

Ouroboros is available as an AUR package, which will install all dependencies (except configfile support) and a Release build from the master branch. To enable configfile support, install tomlc99 before building this AUR package.

From source

When installing from source, go to the cloned git repository or extract the tarball and enter the main directory. We recommend creating a build directory inside this directory. Run cmake providing the path to where you cloned the Ouroboros repository. Assuming you created the build directory inside the repository directory, the following commands build and install O7s:

$ cd <path/to/ouroboros/repo>
$ mkdir build && cd build
$ cmake ..    # optional: configure build parameters
$ make && sudo make install

Running the unit tests

To compile and run the unit tests, do

$ make check

Note that "make test" will only try to run the tests, not compile the necessary sources and may result in errors.

Build configuration parameters

At compile time, there are a number of parameters that can be tweaked, for instance to enable debug logging, enable various sanitizers, to increase performance or decrease memory consumption. You can find a full list on the Ouroboros Build Parameters page.

Remove Ouroboros

To uninstall Ouroboros, simply execute the following command from your build directory:

$ sudo make uninstall