Getting Started

How to get up and running with the Ouroboros prototype.

Get Ouroboros

Packages:

For ArchLinux users, the easiest way to try Ouroboros is via the Arch User Repository, which will also install all dependencies.

Source:

You can clone the repository over https or git:

$ git clone https://ouroboros.rocks/git/ouroboros
$ git clone git://ouroboros.rocks/ouroboros

Or download a snapshot tarball and extract it.

System 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 .

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

Optionally, you can also install libgcrypt, libssl, fuse, and dnsutils.

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.

Install the dependencies

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:

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

Mac OS X Sierra / High Sierra:

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

Install Ouroboros

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:

$ mkdir build && cd build

Run cmake providing the path to where you cloned the Ouroboros repository. Assuming you created the build directory inside the repository directory, do:

$ cmake ..

Build and install Ouroboros:

$ sudo make install

Advanced options

Ouroboros can be configured by providing parameters to the cmake command:

$ cmake -D<option>=<value> ..

Alternatively, after running cmake and before installation, run ccmake to configure Ouroboros:

$ ccmake .

A list of all build options can be found here.

Remove Ouroboros

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

$ sudo make uninstall

To check if everything is installed correctly, you can now jump into the Tutorials section, or you can try to ping this webhost over ouroboros using the name ouroboros.rocks.oping

Our webserver is of course on an IP network, and ouroboros does not control IP, but it can run over UDP/IP.

To be able to contact our server over ouroboros, you will need to do some small DNS configuration: to tell the ouroboros UDP system that the process “ouroboros.rocks.oping” is running on our webserver by add the line

51.38.114.133      1bf2cb4fb361f67a59907ef7d2dc5290

to your /etc/hosts file12.

Here are the steps to ping our server over ouroboros:

Run the IRMd:

$ sudo irmd &

Then you will need find your (private) IP address and start an ouroboros UDP daemon (ipcpd-udp) on that interface:

$ irm ipcp bootstrap type udp name udp layer udp ip <your local ip address>

Now you can ping our server:

$ oping -n ouroboros.rocks.oping

The output from the IRM daemon should look something like this (in DEBUG mode):

[dstaesse@heteropoda build]$ sudo irmd --stdout
==01749== irmd(II): Ouroboros IPC Resource Manager daemon started...
==01749== irmd(II): Created IPCP 1781.
==01781== ipcpd/udp(DB): Bootstrapped IPCP over UDP with pid 1781.
==01781== ipcpd/udp(DB): Bound to IP address 192.168.66.233.
==01781== ipcpd/udp(DB): Using port 3435.
==01781== ipcpd/udp(DB): DNS server address is not set.
==01781== ipcpd/ipcp(DB): Locked thread 140321690191424 to CPU 7/8.
==01749== irmd(II): Bootstrapped IPCP 1781 in layer udp.
==01781== ipcpd/ipcp(DB): Locked thread 140321681798720 to CPU 6/8.
==01781== ipcpd/ipcp(DB): Locked thread 140321673406016 to CPU 1/8.
==01781== ipcpd/udp(DB): Allocating flow to 1bf2cb4f.
==01781== ipcpd/udp(DB): Destination UDP ipcp resolved at 51.38.114.133.
==01781== ipcpd/udp(DB): Flow to 51.38.114.133 pending on fd 64.
==01749== irmd(II): Flow on flow_id 0 allocated.
==01781== ipcpd/udp(DB): Flow allocation completed on eids (64, 64).
==01749== irmd(DB): Partial deallocation of flow_id 0 by process 1800.
==01749== irmd(II): Completed deallocation of flow_id 0 by process 1781.
==01781== ipcpd/udp(DB): Flow with fd 64 deallocated.
==01749== irmd(DB): Dead process removed: 1800.

If connecting to ouroboros.rocks.oping failed, you are probably behind a NAT firewall that is actively blocking outbound UDP port 3435.


  1. This is the IP address of our server and the MD5 hash of the string ouroboros.rocks.oping. To check if this is configured correctly, you should be able to ping the server with ping 1bf2cb4fb361f67a59907ef7d2dc5290 from the command line.

    [return]
  2. The ipcpd-udp allows setting up a (private) DDNS server and using the Ouroboros irm name API to populate it, instead of requiring each node to manually edit the /etc/hosts file. While we technically could also set up such a DNS on our server for demo purposes, it is just too likely that it would be abused. The Internet is a nasty place.

    [return]

Last modified January 1, 0001