View source for Ouroboros Tutorials

Collection of tutorials, follow the main article link for the actual tutorial. Also see the [https://ouroboros.rocks/man/man8/ouroboros.8.html 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:

<syntaxhighlight lang=docker>
# 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"]
</syntaxhighlight>

It builds a [[Ouroboros Build Parameters|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:

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

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

<syntaxhighlight>
$ docker exec -it o7s bash
</syntaxhighlight>

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 [[Ouroboros Tutorial 03|Tutorial 03]], start the IRMd with ''--stdout'' to see its output.
* [[Ouroboros Tutorial 08|Tutorial 08]] and [[Ouroboros Tutorial 10|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.