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.