Ouroboros Tutorials

Collection of tutorials, follow the main article link for the actual tutorial. Also see the man pages for API reference.

Running the tutorials in a container

The tutorials run the IRMd and the IPC processes as root, change files under /etc/ouroboros, and Tutorial 08 adds packet loss to the loopback device. To keep all of that off your machine, you can follow them in a Docker container. Save the text below as Dockerfile in an empty directory:

# Ouroboros tutorials: a debug build with default options.
FROM archlinux:base-devel

RUN pacman -Syu --noconfirm cmake fuse2 git iperf3 iproute2 libgcrypt \
        openssl protobuf-c tcpdump \
 && pacman -Scc --noconfirm

RUN git clone https://github.com/cktan/tomlc17 /tmp/tomlc17 \
 && make -C /tmp/tomlc17 install \
 && rm -rf /tmp/tomlc17

ARG BRANCH=master
ARG CMAKE_ARGS=""
RUN git clone --branch ${BRANCH} https://codeberg.org/o7s/ouroboros \
        /src/ouroboros \
 && cmake -S /src/ouroboros -B /src/build -DCMAKE_BUILD_TYPE=Debug \
        -DCMAKE_INSTALL_PREFIX=/usr ${CMAKE_ARGS} \
 && make -C /src/build -j"$(nproc)" install

RUN echo user_allow_other >> /etc/fuse.conf \
 && useradd -m user \
 && echo 'user ALL=(ALL) NOPASSWD: ALL' > /etc/sudoers.d/user

USER user
WORKDIR /home/user
CMD ["/bin/bash"]

It builds a debug build with default build options, the build the tutorials use, from the be branch. To build another branch, add --build-arg BRANCH=<branch>. Tutorials 07 and 10 need extra build options; pass them with --build-arg CMAKE_ARGS="-DOPTION=VALUE ...". Build the image and start a container:

$ docker build -t o7s-tutorials .
$ docker run -it --init --privileged --shm-size=1g --name o7s o7s-tutorials

For every extra terminal that a tutorial asks for, open a shell in the same container:

$ docker exec -it o7s bash

A few things to know about this setup:

• The shells run as user, a regular user who can use sudo without a password. The tutorials need a regular user, so that the oping client and server end up in different packet pools.
• --privileged lets the container mount FUSE filesystems for the RIB, open raw sockets for the Ethernet PoAs and change the queueing discipline of lo. The lo device is the container's own, so the tutorials do not touch the loopback device of your machine.
• --init runs a small init process as the first process of the container. It reaps the processes that exit, such as the servers the IRMd starts, and passes on signals such as Ctrl-C.
• --shm-size=1g gives the packet pools room in /dev/shm. The default of 64 MB is too small, and the IRMd crashes with a bus error when its pools do not fit.
• The container has no system log. In Tutorial 03, start the IRMd with --stdout to see its output.
• Tutorial 08 and Tutorial 10 need the sch_netem kernel module on the host, and Tutorial 10 also the bridge and veth modules.

Tutorial 01: Local IPC

Main article: Ouroboros Tutorial 01

We will start an ouroboros ping (oping) server application and connect a oping client over local IPC. This tutorial explains how to bind service names to an application and the concept and process of flow allocation and flow deallocation.

Tutorial 02: Local IPC, 2-Layer network

Main article: Ouroboros Tutorial 02

We create a 2-node unicast Layer: we bootstrap a first IPCP, enroll a second IPCP with it, connect the two, and ping over the Layer. It also demonstrates the use of anycast names.

Tutorial 03: Configuration file

Main article: Ouroboros Tutorial 03.

This tutorial sets up the same configuration as Tutorial 02, but instead of using the CLI to configure O7s, we use a configuration file. It demonstrates auto-instantiation of programs, and uses the system log for logging.

Tutorial 04: Ouroboros over Ethernet

Main article: Ouroboros Tutorial 04.

The previous tutorials used the Local Layer (ipcpd-local) to demonstrate basic configuration and operation. In this tutorial we connect two machines over an Ethernet and dip a toe into encrypted flows.

Tutorial 05: Ouroboros over UDP/IP

Main article: Ouroboros Tutorial 05.

Shows how to configure O7s over a UDP/IP network. Also demonstrates load-balancing between multiple program instances on the server.

Tutorial 06: Authenticated flows

Main article: Ouroboros Tutorial 06.

Shows how to authenticate flows with certificates: the server, the client, and the IPCPs that join a Layer.

Tutorial 07: OAP Protocol deep dive and re-keying

Main article: Ouroboros Tutorial 07.

Shows protocol details about authenticated flows and encryption.

Tutorial 08: Loss and retransmission

Main article: Ouroboros Tutorial 08.

Adds packet loss and delay to the loopback Layer of Tutorial 04 with netem, and shows how FRCT repairs a reliable flow: the FRCT header and retransmissions on the wire, the per-flow statistics in the RIB, and when the retransmission timer, SACK and RACK each come into play.

Tutorial 09: Congestion avoidance

Main article: Ouroboros Tutorial 09.

Shapes the loopback Layer of Tutorial 04 to 10 Mbit/s and loads it with ocbr, to show how congestion avoidance in the unicast IPCP shares a link: one controller per path, the multi-bit ECN byte on the wire and the flow updates that report it back, a raw flow that cannot opt out, and flows arriving and leaving without a single drop. With the namespace testbed of the integration suite, it then runs two sources, with one and five flows, on two controllers that split a bottleneck evenly.

Tutorial 10: Loss and congestion

Main article: Ouroboros Tutorial 10.

Sends 1 GiB with oftp over a 100 Mbit/s link with 10 ms of delay and 1% loss, built from veth pairs and a bridge, and shows the two loops at work at once: FRCT repairs the holes while the IPCP keeps the link full, and neither reads the other's signal. The same link with TCP shows what welding the two together costs.