Ouroboros Tutorials: Difference between revisions

From Ouroboros
Jump to navigation Jump to search
No edit summary
No edit summary
 
(31 intermediate revisions by the same user not shown)
Line 1: Line 1:
Collection of tutorials
{{Under construction}}


== Tutorial 1 ==
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.


This is a very simple scenario that starts an application
==  Tutorial 01: Local IPC ==


We will start the IRMd, create a local IPCP, start an ouroboros ping (oping) server application and connect a oping client. This will involve binding (1) that server application to a name and registering (2) that name into the local layer. After that, the client will be able to allocate a flow (3) to that name for which the server will respond.
Main article: [[Ouroboros Tutorial 01]]


We recommend to open 3 terminal windows for this tutorial. In the first window, start the IRMd (as a superuser) in stdout mode. The output shows the process id (pid) of the IRMd, which will be different on your machine.
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''.


<syntaxhighlight lang="bash">
== Tutorial 02: Local IPC, 2-Layer network ==
$ sudo irmd --stdout
Main article: [[Ouroboros Tutorial 02]]
==02301== irmd(II): Ouroboros IPC Resource Manager daemon started\...
</syntaxhighlight>


The type of IPCP we will create is a “local” IPCP. The local IPCP is a kind of loopback interface that is native to Ouroboros. It implements all the functions that the Ouroboros API provides, but only for a local scope. The IPCP create function will instantiate a new local IPC process, which in our case has pid 2324. The “ipcp create” command merely creates the IPCP. At this point it is not a part of a layer. We will also need to bootstrap this IPCP in a layer, we will name it “local_layer”. As a shortcut, the bootstrap command will automatically create an IPCP if no IPCP by than name exists, so in this case, the IPCP create command is optional. In the second terminal, enter the commands:
In this tutorial we will add a unicast layer on top of the local layer. It also demonstrates the use of ''anycast'' names.


<syntaxhighlight lang="bash">
== Tutorial 03: Configuration file ==
$ irm ipcp create type local name local_ipcp
$ irm ipcp bootstrap type local name local_ipcp layer local_layer
</syntaxhighlight>


The IRMd and ipcpd output in the first terminal reads:
Main article: [[Ouroboros Tutorial 03]].


<syntaxhighlight lang="bash">
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.
==02301== irmd(II): Created IPCP 2324.
==02324== ipcpd-local(II): Bootstrapped local IPCP with pid 2324.
==02301== irmd(II): Bootstrapped IPCP 2324 in layer local_layer.
</syntaxhighlight>


From the third terminal window, let’s start our oping application in server mode (“oping –help” shows oping command line parameters):
== Tutorial 04: Ouroboros over Ethernet ==


<syntaxhighlight lang="bash">
Main article: [[Ouroboros Tutorial 04]].
$ oping --listen
Ouroboros ping server started.
</syntaxhighlight>


The IRMd will notice that an oping server with pid 10539 has started:
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.


<syntaxhighlight lang="bash">
== Tutorial 05: Ouroboros over UDP/IP ==
==02301== irmd(DB): New instance (10539) of oping added.
==02301== irmd(DB): This process accepts flows for:
</syntaxhighlight>


The server application is not yet reachable by clients. Next we will bind the server to a name and register that name in the “local_layer”. The name for the server can be chosen at will, let’s take “oping_server”. In the second terminal window, execute:
Main article: [[Ouroboros Tutorial 05]].


<syntaxhighlight lang="bash">
Shows how to configure O7s over a UDP/IP network. Also demonstrates load-balancing between multiple program instances on the server.
$ irm bind proc 2337 name oping_server
$ irm name register oping_server layer local_layer
</syntaxhighlight>
 
The IRMd and IPCPd in terminal one will now acknowledge that the name is bound and registered:
 
<syntaxhighlight lang="bash">
==02301== irmd(II): Bound process 2337 to name oping_server.
==02324== ipcpd-local(II): Registered 4721372d.
==02301== irmd(II): Registered oping_server in local_layer as
4721372d.
</syntaxhighlight>
 
Ouroboros registers name not in plaintext but using a (configurable) hashing algorithm. The default hash is a 256 bit SHA3 hash. The output in the logs is truncated to the first 4 bytes in a HEX notation.
 
Now that we have bound and registered our server, we can connect from the client. In the second terminal window, start an oping client with destination oping_server and it will begin pinging:
 
<syntaxhighlight lang="bash">
$ oping -n oping_server -c 5
Pinging oping_server with 64 bytes of data:
 
64 bytes from oping_server: seq=0 time=0.694 ms
64 bytes from oping_server: seq=1 time=0.364 ms
64 bytes from oping_server: seq=2 time=0.190 ms
64 bytes from oping_server: seq=3 time=0.269 ms
64 bytes from oping_server: seq=4 time=0.351 ms
 
--- oping_server ping statistics ---
5 SDUs transmitted, 5 received, 0% packet loss, time: 5001.744 ms
rtt min/avg/max/mdev = 0.190/0.374/0.694/0.192 ms
</syntaxhighlight>
 
The server will acknowledge that it has a new flow connected on flow descriptor 64, which will time out a few seconds after the oping client stops sending:
 
<syntaxhighlight lang="bash">
New flow 64.
Flow 64 timed out.
</syntaxhighlight>
 
The IRMd and IPCP logs provide some additional output detailing the flow allocation process:
 
<syntaxhighlight lang="bash">
==02324== ipcpd-local(DB): Allocating flow to 4721372d on fd 64.
==02301== irmd(DB): Flow req arrived from IPCP 2324 for 4721372d.
==02301== irmd(II): Flow request arrived for oping_server.
==02324== ipcpd-local(II): Pending local allocation request on fd 64.
==02301== irmd(II): Flow on port_id 0 allocated.
==02324== ipcpd-local(II): Flow allocation completed, fds (64, 65).
==02301== irmd(II): Flow on port_id 1 allocated.
==02301== irmd(DB): New instance (2337) of oping added.
==02301== irmd(DB): This process accepts flows for:
==02301== irmd(DB): oping_server
</syntaxhighlight>
 
First, the IPCPd shows that it will allocate a flow towards a destination hash “4721372d” (truncated). The IRMd logs that IPCPd 2324 (our local IPCPd) requests a flow towards any process that is listening for “4721372d”, and resolves it to “oping_server”, as that is a process that is bound to that name. At this point, the local IPCPd has a pending flow on the client side. Since this is the first port_id in the system, it has port_id 0. The server will accept the flow and the other end of the flow gets port_id 1. The local IPCPd sees that the flow allocation is completed. Internally it sees the endpoints as flow descriptors 64 and 65 which map to port_id 0 and port_id 1. The IPCP cannot directly access port_ids, they are assigned and managed by the IRMd. After it has accepted the flow, the oping server enters flow_accept() again. The IRMd notices the instance and reports that it accepts flows for “oping_server”.
 
This concludes this first short tutorial. All running processes can be terminated by issuing a Ctrl-C command in their respective terminals or you can continue with the next tutorial.
 
 
== Tutorial 2 ==

Latest revision as of 12:03, 25 November 2023

Under contruction This page is under construction  

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

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

In this tutorial we will add a unicast layer on top of the local 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.

Retrieved from "https://ouroboros.rocks/mediawiki/index.php?title=Ouroboros_Tutorials&oldid=1373"