2023-12-10T19:21:37Z

Thijs:

Ouroboros is far from complete. Plenty of things need to be researched and implemented. We don’t really keep a list, but this [https://tree.taiga.io/project/dstaesse-ouroboros/kanban kanban board] can give you some ideas of what is still on our mind and where you may be able to contribute.
Our coding guidelines can be found in the [[Source Code Guide]].

= Contact =

There are 2 ways that are used to communicate.

For daily chat we use a [https://matrix.to/#/#ODecentralize:matrix.org matrix space] bridged to a [https://join.slack.com/t/odecentralize/shared_invite/enQtOTU2NjI5OTk3NDYzLTM2ZjkwZjAxMTcyZjI5N2Y1NGZlNWJjODA0MDU2Y2MzN2Q3MjA5ZTAwYjIyMDMzNGNhZTc1NWQwNWYyMjBhMWU public slack channel]. Use the tool you prefer and whatever login name you desire. Just hop on and ask away.

The [https://www.freelists.org/list/ouroboros mailing list] is mostly used for sending software patches, but can be used to contact us about almost anything. Participation requires you to register for this list.

= Bug reports =

Bugs are reported through our [https://ouroboros.rocks/bugzilla/ Bugzilla issue tracker], or alternatively via [https://github.com/dstaesse/ouroboros/issues GitHub].

When reporting bugs, check if the bug is still present in the 'be' branch, and try to include the following:

* Provide a description of the bug
* Provide system logs of the IRMd and IPCPs
* Provide a minimal code example to reproduce the bug
* Sync with the HEAD of the most stable branch where the bug is present
* Provide a bug fix if you can, send a patch to the mailing list

= Feature requests =

New features can be always be requested through the mailing list or alternatively
[https://github.com/dstaesse/ouroboros/issues GitHub]. They will be taken into account when a next version of the prototype is discussed.

= Contributions =

== Patches ==

Git patches can be sent to the [https://www.freelists.org/list/ouroboros mailing list]. You will need to use an email address that is registered to the mailing list.
Sending commits by mail can be done with [https://git-scm.com/docs/git-send-email git send-email], which might need to be installed separately.

To set this up, open your git config
<syntaxhighlight lang="bash">
git config --global --edit
</syntaxhighlight>

and add your email settings, e.g. for a gmail account (don't forget to '''edit your email address''' in this snippet):

<syntaxhighlight lang="bash">
[sendemail]
smtpserver = smtp.googlemail.com
smtpencryption = tls
smtpserverport = 587
smtpuser = youremail@ymail.com
confirm=auto
</syntaxhighlight>

For other email providers it is similar.

When this is set up, the last commit on the current branch is sent as a patch from the command line using [https://git-scm.com/docs/git-send-email git send-email]:

<syntaxhighlight lang="bash">
git send-email -1 --to=ouroboros@freelists.org
</syntaxhighlight>

== Commit messages ==

A commit message should follow these 10 simple rules, based on [http://chris.beams.io/posts/git-commit/ Chris Beams]' excellent guide.

* Separate subject from body with a blank line
* Limit the subject line to 50 characters
* Capitalize the subject line
* Do not end the subject line with a period
* Use the imperative mood in the subject line
* Precede the subject line by indicating the component where changes were made
* Wrap the body at 72 characters
* Use the body to explain what and why vs. how
* If the commit addresses a bug, reference it in the body
* Sign off your commits using the signoff feature in git

Here is an example of a change in the lib/ folder:

<syntaxhighlight>
lib: Add support for Linux RTT estimator

This adds the option to use the Round-Trip-Time (RTT) estimation
algorithm as it is implemented in the TCP implementation in Linux. It
looks like it outperforms the TCP default algorithm, so I enabled this
one by default. Also adds the option to change the RTO timeout
calculation to include more (or less) than 4 times the mdev (specified
as a power of 2. Left the default value to 2 (so, 4 mdevs), but 3 (8
mdevs) gives better results in my tests.

Signed-off-by: Dimitri Staessens <dimitri@ouroboros.rocks>
</syntaxhighlight>

== Versioning ==

Git is used as a version tooling for the code. Releases are identified through a git tag by a number MAJOR.MICRO.PATCHLEVEL.
* Incrementing MAJOR is done to indicate a big step ahead in terms of features; it is discussed when new features are planned.
* Incrementing MICRO is done when APIs/ABIs are not necessarily compatible.
* The PATCHLEVEL is incremented when an urgent bugfix is incorporated.

Version 1.0.0 would be the first minimum viable prototype version.

== Repository structure==

The main git repository can be found at: https://ouroboros.rocks/cgit/ouroboros

It contains the following branches:

* master: Contains the most stable versions of Ouroboros.
* testing: Contains tested code but may still contain bugs.
* be: Contains untested but compiling code.

All new contributions are integrated into ‘be’ through patches sent to the mailing list. Once a version of ‘be’ is tested enough, it is merged into ‘testing’. When a ‘testing’ version is considered stable enough, it is merged into ‘master’. Most users should probably use master.

New development is always done against the ‘be’ branch of the main git repository. Contributions are always made using your real name and real e-mail address.

Source Code Guide

2023-12-10T16:02:15Z

Thijs:

MediaWiki:Sidebar

2023-12-10T15:55:44Z

Thijs: Reverted edits by Thijs (talk) to last revision by Dimitri

2023-12-04T10:55:56Z

Thijs: Restructure sidebar (WIP)

* navigation
** mainpage|mainpage-description
** Ouroboros Prototype#Try_the_Prototype|Getting Started
** Ouroboros Model|Network Model
** Ouroboros Protocols|Core Protocols
** Glossary | Glossary
** Ouroboros Frequently Asked Questions|Frequently Asked Questions

* Network admin perspective
** Ouroboros Tutorials | Tutorials
** Ouroboros Metrics | Metrics / Observability
** Rumba|Orchestration

* Application dev perspective

* Prototype contribution perspective
** Source Code Guide | Source Code Guide
** Prototype Version History | Version history

* Community
** Ouroboros Contributions | Contact

* Wiki links
** recentchanges-url|recentchanges
** randompage-url|randompage
** helppage|help-mediawiki

* SEARCH
* TOOLBOX
* LANGUAGES

MediaWiki:Sidebar

2023-12-02T10:15:51Z

Thijs: Split of dynamic links specific provided by mediawiki

Ouroboros

2023-12-01T12:21:27Z

Thijs: Small extension to link to all relevant sides of O7s, see discussion

[[File: Scalingtime.png|border|right|thumb|frame|Example Multi-Layer Ouroboros network (visualized using [[Rumba]])]]

Rebuilding packet networks from the ground up.

= Summary =

Ouroboros (abbreviated as O7s) is a prototype packet-switching technology that can function as an alternative to TCP/IP. It is aimed at substantially simplifying configuration and operation of packet-switched networks. It is based on a [[Ouroboros Functional Layering|redesign of the Internet model]] – from the programming API almost to the wire. If we had to describe Ouroboros in a single sentence, it could be ''micro-services architecture applied to the network itself''.

From an end-user application perspective, an Ouroboros network is a black box with a simple application programming interface to request communication services. Ouroboros can provision unicast flows - (bidirectional) channels that deliver message streams or byte streams with some requested operational (QoS) parameters such as maximum delay and bandwidth, protection against packet loss and authentication of peers and encryption of in-flight data; or it can provide broadcast flows to sets of processes.

From an administrative perspective, an Ouroboros network is a collection of daemons that can be thought of as software routers (unicast) or software hubs (broadcast) that can be connected to each other; again through a simple management API. [[Ouroboros Tutorials|The tutorials]] highlight the administrative perspective of Ouroboros.

The prototype is developed for POSIX operating systems (Linux, *BSD, OS X). It is not directly compatible with TCP/IP (it uses different protocols) nor with POSIX sockets (it has a different API), but it has interfaces and tools to run over Ethernet or UDP, or to create IP/Ethernet tunnels over Ouroboros by exposing tap or tun devices for injecting packets.

= Motivation and Objectives =

Setting up a service over TCP/IP usually involves many different technologies. By the time the service is up and running, it will likely have involved configuring (switchport-based and trunk) VLANs, enabling some Spanning Tree Protocol variant in parts of the network, setting up link aggregation between ports on stacked switches, defining IP subnetworks, configuring a DHCP server to assign addresses to the subnets, setting up gateways, DNS servers, possibly configuring OSPF, IS-IS or iBGP/eBGP, selecting TCP and UDP ports for the applications, configuring reverse proxies, setting firewall and Network Address Translation (NAT) rules, adding some servers to a demilitarized zone, configuring a Virtual Private Network server, establishing a few SSH tunnels here and there... the list is almost endless.

A lot of this configuration is mostly static and done manually, once the service is in place, everything needs to be painstakingly documented because the configuration can be very brittle: introducing small changes can inadvertently bring the service down, and tracking down bugs, configuration errors or faults can take hours or even days. News stories about some DNS or [https://blog.cloudflare.com/october-2021-facebook-outage/ BGP misconfiguration] taking down a global service pop up regularly in the media.

The configuration is also spread out as IP address and port configurations need to be applied consistently between different devices (application servers, DHCP and DNS servers, NAT firewalls, application client hardware) and software packages (server software, reverse proxies, client software), whose configuration files often have different formats. Storing, maintaining and automating network and service configuration has become so elaborate and daunting that it now has its own buzzword: ''infrastructure as code''.

The service configuration is not very scalable or portable. The IP network topology is defined by manual subnet assignments, and IP addresses often double as server identifiers in the minds of network admins. If an IP subnet has been over- or under-dimensioned, changing it can cause the need for redesigning many parts of the network. More than often, design compromises are made leaving as much of the network as-is because changing it would take weeks and involve downtime for many critical services. Moving infrastructure within or between datacenters or reintegrating it in a different parts can cause many headaches, some can be mitigated using virtualization, but the configuration of virtual machines and containers is still much more complicated than necessary.

Core Internet technology itself has become ''ossified''; the core protocols haven't changed much in 30 years because making changes that are easy in theory, such as adding a new L3 protocol (IPv6) has become a decades-long slog. There are many ''layer violations'' creating unnecessary and unwanted ties between different layers in the model: L2 (Ethertype), L3 (protocol field), L4 (well-known ports) and L5 (struct sockaddr_in/_in6). A change in one of the layers permeates all the way through the network stack. To make things worse, standardization and research bodies have been established along the (blurry) demarcation lines of the 5-Layer Internet model. [https://en.wikipedia.org/wiki/Conway%27s_law Conway's Law] prevents any significant architectural or structural innovations from taking root.

The Internet is not a friendly place. Deploying a service over the Internet is more akin to venturing out into a lawless warzone than taking a nice stroll in the friendly neighborhood park. The first thing on any dotcom entrepreneur's mind is cybersecurity (quickly followed by how much it's going to cost him or her when the inevitable security breach comes). We would argue that the reason that the Internet has become ossified is also the reason for many network-level exploits: its bloated protocols rolled out the red carpet for cybercrime, cyberterrorism and cyberwarfare. TCP/IP has enabled an Internet that is robust to physical attacks on its infrastructure but left vulnerable to cyberattacks on its services. Unless we revise its architecture and core protocols, mitigating cyberthreats will remain a perpetual arms race between service providers and malicious hackers<ref>[https://blog.cloudflare.com/the-ddos-that-knocked-spamhaus-offline-and-ho/ The DDoS That Knocked Spamhaus Offline (And How We Mitigated It)]</ref>.

The Internet model is also rife with internal contradictions and inconsistencies. Examples abound of protocols that are jammed into the model without fitting - if IP is L3, how is ICMP also L3 as it runs on top of IP? Such contradictions hint at an incomplete understanding of packet networks.

In a nutshell, our objectives are to simplify and reduce network and service configuration and prevent ossification, and to do this by cleaning up and polishing the architecture and its protocols.

= Ouroboros characteristics =

O7s has '''no well-known ports''', ephemeral endpoint identifiers (EIDs) are defined at the model's [[Ouroboros Functional Layering|network end-to-end layer]] and are (randomly) assigned at runtime - the sole exception is the flow allocator at EID 0. This implies:
* no direct tie between the network protocols and certain application, and thus no need to 'standardize' certain values for certain identifiers (Ethertype/protocol/port).
* no need to define, track and/or de-conflict port values when setting up networked applications
* no hacks such as port-scanning a server for (vulnerable) applications

The flow allocator is a '''single point of contact''':
* endpoint identifiers assigned when a flow is allocated
* sets and stores peer information (remote address and endpoint identifier) at the start of communication, so
** no need for source address and source endpoint in every packet
** even if an attacker would find a valid address/endpoint, fabricated packets sent there will not result in any knowledge gained by the attacker as return traffic is sent to the stored peer, not the attacker.
** no smurf/amplification attacks leveraging faked source addresses
* backpressure may be an option to quench DDoS attempts
* authentication/encryption before first application byte

The application library and IRMd work together to create a '''single point of configuration''':
* Instead of having network configuration per application, single network configuration file per system
* All O7s applications in the system inherit the network capabilities of the installed O7s version.

All traffic is congestion controlled, the congestion avoidance algorithm sits in the network end-to-end layer.

= The project =

Ouroboros leverages about 4 decades of hindsight and 2 decades worth of research experience in [[History of Ouroboros | academic projects]] on future networks, more specifically in EU-funded (FP6, FP7 and Horizon 2020) projects on IP/WDM, Carrier Ethernet, Software Defined Networks (SDNs) and the Recursive InterNetwork Architecture (RINA). After gaining development experience on the [https://github.com/IRATI/stack IRATI] kernel RINA prototype for OS/Linux, in early 2016 the decision was made to restart from scratch and try to avoid some issues we identified with the RINA model as it stood at that time. We aimed at POSIX user-space to make the prototype more accessible as compiling a kernel or kernel modules is a steep barrier to entry. Development was done in parallel with ongoing funded research to keep things as independent as possible from outside interference, but we used Ouroboros as one of the prototypes for the development of the [[Rumba]] orchestration framework for recursive networks. After leaving university we decided to keep taking the prototype forward in our spare time. It's a lot of work, but we still have a pretty clear view of the path forward, and there's only one way to eat an elephant: one bite at a time.

= What to expect from this right now =

In its current state, the prototype can demonstrate the validity of many aspects of the model and the potential of a full implementation of this model. It is far from a production piece of software, but rather a proof-of-concept that you can toy around with. See our [[Ouroboros Tutorials| tutorials]] section to get an overview of what the prototype can currently do. Our [[Ouroboros Implementation Overview|implementation overview]] tries to paint a picture of the implementation status of various components and functions. We are aware that parts of the implementation are quite buggy and are working on getting this fixed.

Initially, a lot of the information on this website may sound a bit awkward, especially if configuring VLANs, defining IP subnets and configuring BGP routers are your daily bread and butter. We are the first to admit some of the terminology could use an overhaul. It will require a bit of effort to plow through the concepts of ''flow allocation'' and ''binding / registering names'' but once the penny drops, understanding O7s should prove rewarding.

If you find this interesting, just ask around on our [https://matrix.to/#/#ODecentralize:matrix.org matrix channel].

= References =

Talk:Ouroboros

2023-12-01T12:16:03Z

Thijs: Structuring the O7s wiki, proposal

I think it might be beneficial to clearly structure the different ways O7s can be viewed AND link directly to relevant documentation.
Maybe also clearly structuring the sidebar might help, because in my opinion it is a bit chaos right now.
I subdived this myself, I'm convinced category 2,3 & 4 need to be clearly distinguished.
I ''think'' category 1 is then the overarching story, with 5 also being important to view separately.
Also would be beneficial to split off links like 'Recent changes' and 'Random page' in the sidebar.

1. '''The overall architecture? Architectural documents?'''<br/>
'The story', I'd say.
Maybe also [[Ouroboros Prototype | Getting Started]] aka installation of the O7s prototype fits here? It is needed for 2,3 and 4 at least...
[[Ouroboros Model|Network Model]], [[Ouroboros Protocols|Core Protocols]], [[Glossary]] and [[Ouroboros Frequently Asked Questions| FAQ]] fit also in this category.

2. '''Using O7 as a network admin.'''<br/>
The [[Ouroboros Tutorials|tutorials]] are focusing on this aspect, I think
Also [[Ouroboros Metrics|Metrics/Observability]] and [[Rumba|Orchestration]] fall under this viewpoint?!

3. '''Using O7s as an end-user application.'''<br/>
Here, the [https://{{SERVERNAME}}/docs/examples/ examples] & [https://{{SERVERNAME}}/docs/api/ APIs] need to be ported from the old website and extended.

4. '''Contributing to O7s itself.'''<br/>
Maybe includes a roadmap/link to Kanban.
Link to [[Source Code Guide]], [[Prototype Version History]].

5. '''Community''' :)<br/>
Includes [[Ouroboros Contributions|contact]] page

Ouroboros Tutorial 05

2023-11-30T13:08:49Z

Thijs: Use long form command line options in documentation & scripts.

[[File: O7s_tutorial05-01.png|border|right|thumb|frame|Ouroboros Tutorial 05]]

In this tutorial, we show how to run oping between two machines connected to the same IPv4 network (LAN or Internet). As usual we use a debug build to show some extra log output. In addition to showing how to configure O7s over UDP/IPv4, we also show how to configure load-balancing of flow allocation requests between processes at the server side.

This tutorial uses a desktop and a raspberry pi. To run this tutorial on a single machine, configure the UDP 0-Layer to to use the loopback adapter (set 127.0.0.1 for the SERVER IP ADDRESS).

Configuration for the raspberry pi, which will run 2 oping server processes, which will be available under different service names: oping-server, and oping-server2. Flows to oping-server will be load-balanced in a round-robin way (alternating between the processes), flows to oping-server2 will (usually) go to the same process.

Configuration file for the server machine. Fill out the correct IP address for the interface you want to use, without subnet (e.g. "192.168.0.2"):

$ cat /etc/ouroboros/tut05.conf
[name."oping-server"]
prog=["/usr/bin/oping"]
args=["--listen"]
lb="round-robin"

[name."oping-server2"]
prog=["/usr/bin/oping"]
args=["--listen"]

[udp.wifi1]
bootstrap="wifi-network"
ip="<SERVER IP ADDRESS>"
reg=["oping-server", "oping-server2"]

Configuration file for the machine running the clients (if a different machine):

$ cat /etc/ouroboros/tut05.conf
[udp.wifi1]
bootstrap="wifi-network"
ip="<CLIENT IP ADDRESS>"

Save the configurations as a file (we named it /etc/ouroboros/tut05.conf on both machines).
We are using UDP/IP and the ipcpd-udp will try to resolve the MD5 hash of the application name to an IP address via DNS: ''gethostbyname()''.
For this tutorial we add the DNS entries to /etc/hosts (on the client machine):

$ cat /etc/hosts | grep oping-server
<SERVER IP ADDRESS> 6ae220aa6aae06c43878513c64db34b6 #oping-server
<SERVER IP ADDRESS> f87b9400fa8f3d568b1481da7a99d122 #oping-server2

Once this is set up, start the IRMd on your machine(s) with the configurations above. The IRMd will show some details for the ipcpd-udp:

==16716== irmd/configuration(DB): Found IPCP wifi1 in configuration file.
==16716== irmd(II): Created IPCP 16728.
==16728== ipcpd/ipcp(II): Bootstrapping...
==16728== ipcpd/udp(DB): Bootstrapped IPCP over UDP with pid 16728.
==16728== ipcpd/udp(DB): Bound to IP address 192.168.0.2.
==16728== ipcpd/udp(DB): Using port 3435.
==16728== ipcpd/udp(DB): DNS server not in use.
==16728== ipcpd/ipcp(II): Finished bootstrapping: 0.
==16716== irmd(II): Bootstrapped IPCP 16728 in layer wifi-network.

The default UDP port for O7s ipcpd-udp is 3435 (both server and client side, to simplify traversing NATs), which can be changed with the port="<port>" option. All ipcpd-udps in a UDP Layer need to have the same UDP port set. The UDP Layer supports using a private DDNS server (such as ''bind''), which can be specified with a dns="<DNS IP ADDRESS>" option (see the example config file).

With the irmds started, just spin up a few servers: open 2 terminals, and in each start an oping server with "oping -l". You will see that they service requests for both names:

==16716== irmd(DB): Process 16792 inherits name oping-server2 from program oping.
==16716== irmd(DB): Process 16792 inherits name oping-server from program oping.
==16716== irmd(DB): New instance (16792) of oping added.
==16716== irmd(DB): This process accepts flows for:
==16716== irmd(DB): oping-server
==16716== irmd(DB): oping-server2
==16716== irmd(DB): Process 16809 inherits name oping-server2 from program oping.
==16716== irmd(DB): Process 16809 inherits name oping-server from program oping.
==16716== irmd(DB): New instance (16809) of oping added.
==16716== irmd(DB): This process accepts flows for:
==16716== irmd(DB): oping-server
==16716== irmd(DB): oping-server2

Then on the client machine, if we run the client a few times, you should see that the requests to oping-server (''oping -n oping-server -c 1 -Q'') get serviced by both oping servers in an alternating way. However, requests to oping-server2 (''oping -n oping-server2 -c 1 -Q'') all go to the same oping instance.

Note that there is no guarantee that oping-server2 will always go to the same instance (to see that, run clients mixing the service names). To guarantee going to a specific process, bind a specific (single) process (in our example, for instance, PID 16809) to a name using the ''irm name bind process <pid> name <name>'' CLI command. Multiple UDP Layers can be configured in parallel, but then it's best to use DDNS, and a separate DDNS server for each Layer; the hosts file is valid for all ipcpd-udp processes and will potentially mess things up.

Ouroboros Tutorial 04

2023-11-30T13:05:23Z

Thijs: Use long form command line options in documentation & scripts.

[[File: O7s_tutorial04-01.png|border|right|thumb|frame|Ouroboros Tutorial 04]]

In this tutorial, we show how to run oping between two machines connected to the same Ethernet LAN. It requires OpenSSL to be installed before building O7s to enable encrypted flows, and as usual we use a debug build to show some extra log output.

For the second machine we use a Raspberry Pi Model 4B+ (ARM64, 32-bit Raspbian 11) connected to the same WiFi LAN as my desktop (Intel 13900KF, ArchLinux).

We chose the Ethernet DIX option, because our LLC packets sometimes get dropped on wireless LANs (protocol ossification at work). To use the LLC Ethernet 0-Layer, all that is needed is to change eth-dix to eth-llc in (both) the configuration files in this tutorial (left to the reader).

We run the server on the raspberry pi. The O7s config file for the Raspberry Pi connects to the ''wlan0'' device and registers the "oping-server" application with the Ethernet 0-Layer. You will have to replace wlan0 with the correct ethernet device! The name ''wifi1'' and ''wifi-network'' don't really matter, so you can change them to your liking.

[name."oping-server"]
prog=["/usr/bin/oping"]
args=["--listen"]

[eth-dix.wifi1]
bootstrap="wifi-network"
dev="''wlan0''"
reg=["oping-server"]

The configuration for the desktop machine (O7s client) is quite simple:

[eth-dix.wifi1]
bootstrap="wifi-network"
dev="''wlan0''"

If you do not have two machines, you can run this on a single machine using the loopback adapter. In that case, set the following in your configuration file:

[name."oping-server"]
prog=["/usr/bin/oping"]
args=["--listen"]

[eth-dix.lo]
bootstrap="loopback-network"
dev="lo"
reg=["oping-server"]

The description assumes you are running on 2 machines, on a single machine. Save these configuration as a file on each machine - we chose to save them at /etc/ouroboros/tut04.conf - and start an IRMd on each machine with that config file.
The IRMd will log the use of the configuration file, on the raspberry pi it will create the service name for oping-server:

dstaesse@raspberrypi:~ $ sudo irmd --stdout --config /etc/ouroboros/tut04.conf
==28267== irmd(II): Ouroboros IPC Resource Manager daemon started...
==28267== irmd/configuration(II): Reading configuration from file /etc/ouroboros/tut04.conf
==28267== irmd/configuration(DB): Found service name oping-server in configuration file.
==28267== irmd(II): Created new name: oping-server.
==28267== irmd(II): Bound program /usr/bin/oping to name oping-server.

The IRMd then bootstraps the IPCP (this happens on both machines):

==28267== irmd/configuration(DB): Found IPCP wifi1 in configuration file.
==28267== irmd(II): Created IPCP 28279.
==28267== irmd/configuration(DB): No hash specified, using default.
==28279== ipcpd/ipcp(II): Bootstrapping...
==28279== ipcpd/eth-dix(DB): Device MTU is 1500.
==28279== ipcpd/eth-dix(DB): Layer MTU is 1500.
==28279== ipcpd/eth-dix(II): Using raw socket device.
==28279== ipcpd/eth-dix(DB): Bootstrapped IPCP over DIX Ethernet with pid 28279 and Ethertype 0xA000.
==28279== ipcpd/ipcp(II): Finished bootstrapping: 0.
==28267== irmd(II): Bootstrapped IPCP 28279 in layer wifi-network.

The ipcpd-eth-* detects the device MTU (which is usually 1500 bytes, but can be lower on virtual machine guests, or higher, for instance the loopback interface). The ipcpd-eth-* Layer MTU will be set to the device MTU, or to [[Ouroboros Build Parameters|IPCP_ETH_LO_MTU]] when using the loopback adapter. We will probably make the Layer MTU a runtime configuration parameter in the future, so it can be configured in the configuration file. The Raspberry Pi is using Linux, which defaults to a raw socket device for interfacing with Ethernet devices. Other options for interfacing with Ethernet are Berkeley Packet Filter (BPF) (for *BSD and OS X) or netmap (if installed). Our IPCP will process all packets on a specified Ethertype. The default value is 0xA000.

The IRMd on the raspberry Pi will make the oping service available on the Ethernet 0-Layer:

==28267== irmd/configuration(DB): Registering oping-server in 28279
==28267== irmd(WW): Name oping-server already exists.
==28279== ipcpd/ipcp(II): Registering f6c93ff2...
==28279== ipcpd/ipcp(II): Finished registering f6c93ff2 : 0.
==28267== irmd(II): Registered oping-server with IPCP 28279 as f6c93ff2.

With the IRMd started on both machines, we can start the oping server. We use the --quiet (-Q) option to reduce output in the example (oping -l -Q).

In addition to demonstrating the use of the ipcpd-eth-dix, we will also show the use of ''encrypted flows''. To make this more visible, we dump the traffic on the Raspberry Pi's wlan0 device for ethertype 0xA000 using ''tcpdump'' (change wlan0 to the correct ethernet device).
dstaesse@raspberrypi:~ $ sudo tcpdump -i wlan0 ether proto 0xa000
tcpdump: verbose output suppressed, use -v[v]... for full protocol decode
listening on wlan0, link-type EN10MB (Ethernet), snapshot length 262144 bytes

Our desktop machine has MAC address c8:cb:9e:d0:04:08, the Raspberry Pi has MAC address d8:3a:dd:39:0a:b5.

Our ipcpd-eth-dix has the following packet header, note that the dst and src hardware (MAC) addresses and the ethertype are shown on the first line of the tcpdump output. The hex output starts at ''eid''.

uint8_t dst_hwaddr[6];
uint8_t src_hwaddr[6];
uint16_t ethertype;

uint16_t eid;
uint16_t length;

The endpoint identifier (EID, ''eid'' field in the header above) is used for multiplexing flows, in the ipcpd-eth-* it is 16 bits wide and set to the flow descriptor used by the application (in the ipcpd-unicast the EID is 64 bits and assigned in a random way). The ''length'' field is needed to deal with Ethernet frames that would be shorter than 64 bytes, which are padded with zero bytes, and we need to know if those zeroes are padding or payload. These are known as ''runt'' frames.

For readers also trying the ipcpd-eth-llc, the header format is a little bit different: no ''eid'' instead we use LLC SAPs as endpoint identifiers and no ''length'' (Ethernet LLC has its own length field instead of the Ethertype to deal with runt frames). The control field ''cf'' is fixed and set to [https://en.wikipedia.org/wiki/IEEE_802.2 LLC type 1] (0x03).

When we ping (one ping only) from the desktop (''oping -n oping-server -c 1''), we see the traffic exchange on the wlan. Let's break it down:

The client initiates the communications using the ''flow_alloc()'' function call. This will send a ''Flow Allocation Request'' message to the server. We have not requested anything special, so this will be a request for a vanilla best-effort ''raw flow'':

09:57:08.998005 c8:cb:9e:d0:04:08 (oui Unknown) > d8:3a:dd:39:0a:b5 (oui Unknown), ethertype Unknown (0xa000), length 88:
0x0000: 0000 '''0046''' 0040 '''0000''' 0000 0001 '''0000 0000''' ...F.@..........
0x0010: '''0000 0000''' 0000 0001 '''ffff ffff''' ffff ffff ................
0x0020: '''0001 d4c0''' 0000 '''00'''00 '''00'''00 '''f6c9 3ff2 3bd9''' ............?.;.
0x0030: '''1094 3a77 8e7b 3faf 7bff ec03 796d b676''' ..:w.{?.{...ym.v
0x0040: '''1bfa 5f70 758f 9ee2 e6fa''' .._pu.....

The packet is a flow allocation message (fixed packet format for the flow allocator). The full description of what's in this packet is:

uint16_t eid: 0000 = 0 (This message is for the flow allocator)
uint16_t length: 0046 = 70 (Length of the payload)

uint16_t src eid: 0040 = 64 (EID assigned to the oping client)
uint16_t dst eid: 0000 = 0 (not used in allocation request)
uint32_t loss: 0000 0001 = 1 (disables ARQ)
uint64_t bandwidth: 0000 0000 0000 0000 = 0 (no reservation)
uint32_t ber: 0000 0001 = 1 (disables CRC)
uint32_t max_gap: ffff ffff = MAX_INT (any inter-packet gap is fine)
uint32_t delay: ffff ffff = MAX_INT (any delay is fine)
uint32_t timeout: 0001 d4c0 = 120000 (2 minutes)
uint16_t cypher_s: 0000 = 0 (no encryption)
uint8_t in_order: 00 = 0 (no in-order delivery)
uint8_t code: 00 = 0 (flow allocation request)
uint8_t availability: 00 = 0 (9's, any availability will do)
int8_t response 00 = 0 (not used in flow allocation request)

The final 32 bytes of the message (f6c9 3f.. ..e2 e6fa) is the SHA3-256 hash of ''oping-server''. When the flow is accepted at the server side (on the Raspberry Pi), the ipcpd-eth-dix responds with a flow allocation response.

The format is the same as above, without the destination has, and the QoS is set to 0 (QoS negotiation is not yet implemented).

09:57:09.000685 d8:3a:dd:39:0a:b5 (oui Unknown) > c8:cb:9e:d0:04:08 (oui Unknown), ethertype Unknown (0xa000), length 56:
0x0000: 0000 '''0026''' 0040 '''0040''' 0000 0000 0000 0000 ...&.@.@........
0x0010: 0000 0000 0000 0000 0000 0000 0000 0000 ................
0x0020: 0000 0000 0000 00'''01''' 00'''00''' ..........

The full explanation of the response is:
uint16_t eid: 0000 = 0 (This message is for the flow allocator)
uint16_t length: 0026 = 38 (Length of the payload)

uint16_t src eid: 0040 = 64 (EID assigned to the oping server at the server IPCP)
uint16_t dst eid: 0040 = 64 (EID assigned to the oping client at the client IPCP)
/* QoS ''all zero'' unused in response */
uint8_t in_order: 00 = 0 (part of QoS, zero)
uint8_t code: 01 = 1 (flow allocation response)
uint8_t availability: 00 = 0 (part of QoS, zero)
int8_t response 00 = 0 (flow allocation request was successful)

The next message is the actual oping message. Note the first two fields are 0040, the first is the destination EID (64), the second is not the source EID, but the payload length (both are also 64).

09:57:10.020082 c8:cb:9e:d0:04:08 (oui Unknown) > d8:3a:dd:39:0a:b5 (oui Unknown), ethertype Unknown (0xa000), length 82:
0x0000: 0040 '''0040''' 0000 0000 '''0000 0000''' e307 0000 .@.@............
0x0010: 0000 0000''' aa02 f70d 0000 0000''' 0000 0000 ................
0x0020: 0000 0000 0000 0000 0000 0000 0000 0000 ................
0x0030: 0000 0000 0000 0000 0000 0000 0000 0000 ................
0x0040: 0000 0000 ....

The format of an oping message is:

uint32_t type: 0000 0000 = 0 (oping request)
uint32_t id: 0000 0000 = 0 (sequence number, first message)
uint64_t tv_sec: e307 0000 0000 0000 = - (monotonic clock timestamp)
uint64_t tv_nsec: aa02 f70d 0000 0000 = - (monotonic clock timestamp)

The remainder are 40 bytes worth of zeroes to get the payload length to 64 bytes (ping default). Note that the timestamp is not converted to network byte order as it is only set and read at the client to calculate the round-trip time.

The oping response has the message type set to 0000 0001 (1 = oping response) below:

09:57:10.020890 d8:3a:dd:39:0a:b5 (oui Unknown) > c8:cb:9e:d0:04:08 (oui Unknown), ethertype Unknown (0xa000), length 82:
0x0000: 0040 0040 '''0000 0001''' 0000 0000 e307 0000 .@.@............
0x0010: 0000 0000 aa02 f70d 0000 0000 0000 0000 ................
0x0020: 0000 0000 0000 0000 0000 0000 0000 0000 ................
0x0030: 0000 0000 0000 0000 0000 0000 0000 0000 ................
0x0040: 0000 0000

Now, let's request an encrypted flow. To do that, start the oping client again, but now give it a raw_crypt option (''oping -n oping-server -c 1 -q raw_crypt'').

The first message is again a flow allocation request. The formatting is the same as above, so let's highlight the differences.

09:57:20.057379 c8:cb:9e:d0:04:08 (oui Unknown) > d8:3a:dd:39:0a:b5 (oui Unknown), ethertype Unknown (0xa000), length 179:
0x0000: 0000 00a1 0040 0000 0000 0001 0000 0000 .....@..........
0x0010: 0000 0000 0000 0001 ffff ffff ffff ffff ................
0x0020: 0001 d4c0 '''0100''' 0000 0000 f6c9 3ff2 3bd9 ............?.;.
0x0030: 1094 3a77 8e7b 3faf 7bff ec03 796d b676 ..:w.{?.{...ym.v
0x0040: 1bfa 5f70 758f 9ee2 e6fa '''3059 3013 0607''' .._pu.....0Y0...
0x0050: '''2a86 48ce 3d02 0106 082a 8648 ce3d 0301''' *.H.=....*.H.=..
0x0060: '''0703 4200 0476 5de7 77ed 2802 2ad0 d02a''' ..B..v].w.(.*..*
0x0070: '''2d63 98df 7ad2 454f dea9 043f 7a50 4a5e''' -c..z.EO...?zPJ^
0x0080: '''1e33 1bf8 6fe9 8f06 f5b7 89b1 1b8b d1d9''' .3..o...........
0x0090: '''0084 c0e4 df5e 5833 19ab ab0f db54 8882''' .....^X3.....T..
0x00a0: '''1b7a 7cb8 ee''' .z|..

The QoS now specified the cypher strength as 0100 (256). The value doesn't matter at the moment, when it's non-zero it enables encryption. We will revise this option entirely. For now, it's enough for demoing the concept of encrypted flows.

With encryption enabled, not only the destination hash is sent, but also a source (ephemeral) public key (3059 30.. 7cb8 ee) is attached to the flow allocation request to perform a Diffie-Hellman exchange. The destination uses the source public key (and its own private key) to generate a shared secret and then hashes this secret (SHA3-256) to derive a unique 256-bit symmetric encryption key (AES-256).

The oping server then sends the response, with its own (ephemeral) public key (3059 30.. 45e9 ad):

09:57:20.060233 d8:3a:dd:39:0a:b5 (oui Unknown) > c8:cb:9e:d0:04:08 (oui Unknown), ethertype Unknown (0xa000), length 147:
0x0000: 0000 0081 0041 0040 0000 0000 0000 0000 .....A.@........
0x0010: 0000 0000 0000 0000 0000 0000 0000 0000 ................
0x0020: 0000 0000 0000 0001 0000 '''3059 3013 0607''' ..........0Y0...
0x0030: '''2a86 48ce 3d02 0106 082a 8648 ce3d 0301''' *.H.=....*.H.=..
0x0040: '''0703 4200 045b b39c 9f17 ce44 005a e2cb''' ..B..[.....D.Z..
0x0050: '''d2c9 5207 8cad 2aa5 37fc 727b 71de 77e6''' ..R...*.7.r{q.w.
0x0060: '''e0e3 2164 b619 a8a3 94c3 d6de ce4b dda8''' ..!d.........K..
0x0070: '''d31e b218 5a59 24c9 685f 0943 55f5 128a''' ....ZY$.h_.CU...
0x0080: '''0eba 46e9 ad''' ..F..

The client can now use the server's public key and its own private key to derive the same shared secret.

The source ping is then sent encrypted over the Ethernet network. The destination EID is 0041 (= 65). I was quick and the previous flow on the server had not timed out yet. It will be more common to have the same EID as before (0040, 64) if you follow this tutorial for the first time. Everything after the EID is encrypted. The packet length is now 114 bytes instead of 82 for the non-encrypted case (payload length is 0060 = 96 bytes). This is because we add a 128-bit (32 byte) random Initialization Vector (IV) to each packet to prevent the same data plaintext to always result in the same cypher text.

09:57:21.075534 c8:cb:9e:d0:04:08 (oui Unknown) > d8:3a:dd:39:0a:b5 (oui Unknown), ethertype Unknown (0xa000), length 114:
0x0000: 0041 0060 c180 1f26 71d1 3911 3e7c 0d29 .A.`...&q.9.>|.)
0x0010: 7287 17c8 708a cc5b bc77 9b8e af55 7594 r...p..[.w...Uu.
0x0020: 5efb 00a8 aa8d 1749 440f 6c68 6d27 cd33 ^......ID.lhm'.3
0x0030: 630a c34b a500 ea78 7d4e 1fd2 47d1 f5ab c..K...x}N..G...
0x0040: 2e17 5dc0 581a bee8 efbf dea4 fe41 2c12 ..].X........A,.
0x0050: 37f1 9704 d2da a94c 0e8a 0a00 2844 4ea2 7......L....(DN.
0x0060: b177 58b1 .wX.

09:57:21.076497 d8:3a:dd:39:0a:b5 (oui Unknown) > c8:cb:9e:d0:04:08 (oui Unknown), ethertype Unknown (0xa000), length 114:
0x0000: 0040 0060 8708 787f cf81 c7aa a006 4195 .@.`..x.......A.
0x0010: 64d8 d977 24bc bc38 cb16 138f 181e 78cd d..w$..8......x.
0x0020: 3877 c8de fed1 f0a1 902f aee6 245b a291 8w......./..$[..
0x0030: 5c7f 5e35 0f85 858b 0fb0 c55c 60e5 c38a \.^5.......\`...
0x0040: 06ac 2c11 e582 7de2 5371 32fc b58a 6c83 ..,...}.Sq2...l.
0x0050: 129d dc90 c4c8 ab5a a3e7 efd2 e8de 6ffb .......Z......o.
0x0060: 7932 7439

This was a brief tutorial demoing encrypted flows. The implementation is still rudimentary at this point, and support for other encryption methods (galois counter mode for reliable encrypted flows) and authenticated flows are on the roadmap.

Ouroboros Tutorial 03

2023-11-30T12:59:23Z

Thijs:

[[File: O7s_tutorial03-01.png|border|right|thumb|frame|Ouroboros Tutorial 03]]

Ouroboros can be configured using a config file in TOML format (requires [https://github.com/cktan/tomlc99 libtomlc99] to be installed when building the prototype).

Copy/paste the text below and store it as a file, we named it ''tut03.conf'' and saved it in /etc/ouroboros/, which is the default used for O7s configurations.

<syntaxhighlight lang=toml>
### Ouroboros configuration file Tutorial 03
[name.oping-server]
prog=["/usr/bin/oping"]
args=["--listen"]

[local.local-ipcp]
bootstrap="local-layer"
reg=["uni-1", "uni-2", "unicast-layer"]

[unicast.uni-1]
bootstrap="unicast-layer"
autobind=true
reg=["oping-server"]

[unicast.uni-2]
enrol="unicast-layer"
conn=["uni-1"]
</syntaxhighlight>

The configuration file is in TOML format (we may add support for other formats in the future). This demo will create a local Layer and then a 2-node unicast Layer on top, just like in [[Ouroboros Tutorial 02 | Tutorial 02]] to support the ''oping'' application.

It has 4 stanza:
# ''name.oping-server'': This creates a service name, in this case the name is ''oping-server''. Note that if we wanted to name the service ''oping.server'' it would need quotes like this ''[name."oping.server"]''. That name will be served by all instances of the ''oping'' binary (located at /usr/bin/oping). We specify the ''args'' option to start oping automatically (see below).
# ''local.local-ipcp'': The IRMd will start a local IPCP called ''local-ipcp''. We also specify a bootstrap option to start a new Layer called ''local-layer''. We will be running 2 unicast IPCPs on top, named uni-1 and uni-2. Both of these will also listen to the ''anycast'' name ''unicast-layer''.
# ''unicast.uni-1'': The IRMd will start a unicast IPCP called ''uni-1''. We also specify it will bootstrap a new network Layer called ''unicast-layer''. The autobind option will bind it to both the IPCP name ("uni-1") as the anycast layer name ("unicast-layer"). We register the oping server application on this node.
# ''unicast.uni-2'': The IRMd will start a unicast IPCP called ''uni-1''. This IPCP will not bootstrap, but enroll in the ''unicast-layer'' and then connect (creating both management and data transfer flow) to create a forwarding adjacency with "uni-1".

Instead of logging to standard output, we will use the system log, which is Ouroboros' default. Use your preferred way to view the system log. We use journalctl

$ sudo journalctl --identifier=irmd --follow #short form: sudo journalctl -t irmd -f

In a different window, start the irmd using the config file and without the ''--stdout'' option:

$ sudo irmd --config /etc/ouroboros/tut03.conf

This will load the configuration and will set up the same network that we created in [[Ouroboros Tutorial 02 | the second tutorial]].

Now, we will ping an oping server from the client over that unicast-layer. In the previous two tutorials, we first started the server, but O7s can start a server automatically. This is the ''auto'' feature of the ''irm bind program'' CLI tool. In the configuration file, this feature is enabled by specifying an ''args'' line for a service name. In our configuration example, we defined that the service name ''oping-server'' is bound to program ''/usr/bin/oping'' and can be automatically started if needed with the argument ''--listen'' (the short form is -l).

Just start a client towards oping-server:

$ oping -n oping-server -c 10
Pinging oping-server with 64 bytes of data (10 packets):

64 bytes from oping-server: seq=0 time=1.223 ms
64 bytes from oping-server: seq=1 time=0.885 ms
64 bytes from oping-server: seq=2 time=0.988 ms
<snip>
64 bytes from oping-server: seq=9 time=0.819 ms

--- oping-server ping statistics ---
10 packets transmitted, 10 received, 0 out-of-order, 0% packet loss, time: 10003.173 ms
rtt min/avg/max/mdev = 0.705/0.877/1.223/0.144 ms

The window where we started the IRMd will log the server output:

Ouroboros ping server started.
New flow 64.
Received 64 bytes on fd 64.
Received 64 bytes on fd 64.
<snip>
Received 64 bytes on fd 64.
Flow 64 timed out.

When the IRMd auto-instantiates a program, it will log this event as:

Nov 05 17:58:38 phonetria irmd[3820]: Flow request arrived for oping-server.
Nov 05 17:58:38 phonetria irmd[3820]: Instantiated /usr/bin/oping as process 3961.
Nov 05 17:58:38 phonetria irmd[3820]: Process 3961 inherits name oping-server from program oping.