From 5c239c128c04883dbed6d66f574edf8b48d11e11 Mon Sep 17 00:00:00 2001 From: Dimitri Staessens Date: Sun, 16 Aug 2026 18:55:15 +0000 Subject: lib: Replace shim IPCPs with points of attachment Removes the UDP and Ethernet shim IPCPs. The unicast and broadcast IPCPs can now directly attach to a "legacy" socket. We adopt Saltzer's Point-of-Attachment terminology, also advocated in Day's "Patterns in Network Architecture". The "poa" component manages these PoA's with one management thread, one link monitoring thread and one thread per attached point. For Ethernet PoA's the irm connect and enroll can resolve the destination IPCP or Layer name with a broadcast name query over the attached PoAs (first reply wins). UDP PoA's require a destination IP address or FQDN. attach to a local endpoint (required both server and client side): irm ipcp poa attach name a udp 10.0.0.1 irm ipcp poa attach name a udp 10.0.0.1:3435 irm ipcp poa attach name a udp [::1]:3435 irm ipcp poa attach name a eth dev eth0 irm ipcp poa attach name a eth dev eth0 ethertype 0xA000 release a PoA (refused while it carries a flow): irm ipcp poa detach name a udp 10.0.0.1:3435 irm ipcp poa detach name a eth eth0 list an IPCP's PoAs: irm ipcp poa list name a connect to a peer, by name or at an address: irm ipcp connect name b dst a irm ipcp connect name b dst a eth irm ipcp connect name b dst a eth dev eth0 irm ipcp connect name b dst a udp 10.0.0.1:3435 irm ipcp connect name b dst a udp peer.example.com:3435 disconnect by peer name, no address: irm ipcp disconnect name b dst a irm ipcp disconnect name b dst a component mgmt enroll has the same shape as connect: irm ipcp enroll name b layer lr autobind irm ipcp enroll name b layer lr autobind eth dev eth0 irm ipcp enroll name b layer lr autobind udp 10.0.0.1:3435 the IRMd config file attaches PoAs and names peers the same way: udp = [ "10.0.0.1", "10.0.0.1:3436" ] eth = [ "eth0", {dev="eth1", ethertype=0xA007} ] enrol={dst="LAN", eth={dev="eth0"}} conn=[{dst="lan3", eth={}}, {dst="lan4", udp="10.0.0.1:3435"}] Signed-off-by: Dimitri Staessens Signed-off-by: Sander Vrijders --- doc/man/ouroboros-tutorial.7 | 43 ++++++++++---- doc/man/ouroboros.8 | 132 ++++++++++++++++++++----------------------- 2 files changed, 91 insertions(+), 84 deletions(-) (limited to 'doc') diff --git a/doc/man/ouroboros-tutorial.7 b/doc/man/ouroboros-tutorial.7 index 1fc02a02..54abba5b 100644 --- a/doc/man/ouroboros-tutorial.7 +++ b/doc/man/ouroboros-tutorial.7 @@ -47,37 +47,56 @@ The output should be .SH PINGING A SERVER APPLICATION OVER THE LOOPBACK ADAPTER With a running irmd, let's create an IPC process. For this tutorial, -we will create and bootstrap an eth-llc IPCP over the loopback -interface. To observe what's going on, open another terminal -window. Note that "ipcp bootstrap" will create an IPCP if an IPCP by -that name does not yet exist (See \fBouroboros\fR(8)). +we will create a unicast IPCP, attach it to the loopback interface and +bootstrap it. To observe what's going on, open another terminal +window. .RS 4 -$ irm ipcp bootstrap type eth-llc name llc layer llc if lo +$ irm ipcp create name lan type unicast .RE .RS 4 ==23918== irmd(II): Created IPCP 23932. -.br -==23932== ipcpd/eth-llc(II): Using raw socket device. -.br -==23918== irmd(II): Bootstrapped IPCP 23932 in layer llc. +.RE + +An IPCP needs a \fIpoint of attachment\fR: the transmission technology +it sends and receives on. Attach it to the loopback interface (See +\fBouroboros\fR(8)). + +.RS 4 +$ irm ipcp poa attach name lan eth dev lo +.RE + +.RS 4 +==23918== irmd(II): Attached IPCP 23932. +.RE + +.RS 4 +$ irm ipcp bootstrap name lan layer lan +.RE + +.RS 4 +==23918== irmd(II): Bootstrapped IPCP 23932. .RE Now that we have the IPCP bootstrapped, it can act as a local network layer that can provide full connectivity between all processes in the system. Let's test it using the oping application. First, let's choose -a name for the server ("my.oping.server") and register in the llc +a name for the server ("my.oping.server") and register it in the lan layer. .RS 4 -$ irm reg name my.oping.server layer llc +$ irm name create my.oping.server +.br +$ irm name register my.oping.server layer lan .RE The IRMd should respond with .RS 4 -==23918== irmd(II): Registered my.oping.server in llc as 716016b1. +==23918== irmd(II): Created new name: my.oping.server. +.br +==23918== irmd(II): Registered my.oping.server with IPCP 23932 as 716016b1. .RE Now start a server of oping in the background (or in a different diff --git a/doc/man/ouroboros.8 b/doc/man/ouroboros.8 index 759b1433..4c83e5a9 100644 --- a/doc/man/ouroboros.8 +++ b/doc/man/ouroboros.8 @@ -98,10 +98,13 @@ accessed by other processes. In order to enroll an IPC process in a layer, some other member will have to be reachable over a lower layer. IPCPs that wrap a legacy transmission technology are all bootstrapped and thus need not enroll -as they work directly over a physical connection. Ouroboros currently -supports IPCPs over shared memory (local), L2 (eth-llc and eth-dix) -and L3 (udp). The unicast and broadcast layers require connections to -be established between IPCP components for its operation. +as they work directly over a physical connection. A unicast or +broadcast IPCP attaches to a transmission technology itself, as a +\fIpoint of attachment\fR (PoA); Ouroboros currently supports PoAs on +L2 (Ethernet) and L3 (UDP/IPv4 and UDP/IPv6), next to IPCPs over +shared memory (local). The unicast and broadcast layers require +connections to be established between IPCP components for its +operation. \fBConnecting the management components\fR using \fImanagement flows\fR allows management information to be sent between IPCPs so @@ -123,14 +126,6 @@ creates an IPCP process of type \fItype\fR in the system with name .PP \fBlocal\fR - create a loopback IPCP. .PP -\fBeth-llc\fR - create an IPCP that attaches to Ethernet using LLC frames. -.PP -\fBeth-dix\fR - create an IPCP that attaches to Ethernet using DIX frames. -.PP -\fBudp4\fR - create an IPCP that attaches to a UDP/IPv4 socket. -.PP -\fBudp6\fR - create an IPCP that attaches to a UDP/IPv6 socket. -.PP \fBunicast\fR - create a unicast IPCP that uses lower level layers. .PP \fBbroadcast\fR - create a broadcast IPCP that uses lower level layers. @@ -161,69 +156,9 @@ Values for [\fIparam\fR] are dependent on \fItype\fR: default: SHA3_256. .RE -.PP -\fBeth-llc\fR -.RS 4 -.PP -dev \fIinterface\fR specifies the interface to bind the IPCP to. -.PP -[hash \fIpolicy\fR] specifies the hash function used for the directory, -.br -\fIpolicy\fR: SHA3_224, SHA3_256, SHA3_384, SHA3_512. -.br -default: SHA3_256. -.RE -.PP -\fBeth-dix\fR -.RS 4 -.PP -dev \fIinterface\fR specifies the interface to bind the IPCP to. -.PP -[ethertype \fIethertype\fR] specifies the ethertype used for the layer. -.br -default: 0xA000. -.PP -[hash \fIpolicy\fR] specifies the hash function used for the directory, -.br -\fIpolicy\fR: SHA3_224, SHA3_256, SHA3_384, SHA3_512. -.br -default: SHA3_256. -.RE -.PP -\fBudp4\fR -.RS 4 -.PP -ip \fIip\fR specifies the local IPv4 address to bind to -.PP -[dns \fIdns\fR] specifies an optional DDNS server that will be used for -the directory. -.PP -[port \fIport\fR] specifies a UDP port that is used for sending and -receiving ouroboros traffic. This must be the same for the entire UDP4 -layer. Parallel UDP4 layers should use different ports. This UDP port -needs to be forwarded if the server is behind a NAT and wants to -receive incoming requests. -.br -default: 3435 -.RE -.PP -\fBudp6\fR -.RS 4 -.PP -ip \fIip\fR specifies the local IPv6 address to bind to -.PP -[dns \fIdns\fR] specifies an optional DDNS server that will be used for -the directory. -.PP -[port \fIport\fR] specifies a UDP port that is used for sending and -receiving ouroboros traffic. This must be the same for the entire UDP6 -layer. Parallel UDP6 layers should use different ports. -.br -default: 3435 -.RE .PP \fBunicast\fR @@ -292,6 +227,38 @@ default: SHA3_256. .RE .RE +.PP +\fBirm ipcp poa attach\fR name \fIname\fR \fIpoa\fR +.RS 4 +attaches the IPCP with name \fIname\fR to a point of attachment. +Repeat to attach more than one. Exactly one \fIpoa\fR is given: +.PP +udp \fIip\fR[:\fIport\fR] attaches to a local IPv4 or IPv6 address. +IPv6 addresses need brackets when a port is given: [\fIip\fR]:\fIport\fR. +.br +default port: 3435. +.PP +eth dev \fIdevice\fR [ethertype \fIethertype\fR] attaches to an Ethernet +device. +.br +default: 0xA000. +.RE + +.PP +\fBirm ipcp poa detach\fR name \fIname\fR \fIpoa\fR +.RS 4 +releases a point of attachment that the IPCP with name \fIname\fR is +attached to. Flows over it are brought down first. \fIpoa\fR takes the +same values as for \fBattach\fR. +.RE + +.PP +\fBirm ipcp poa list\fR name \fIname\fR +.RS 4 +lists the points of attachment that the IPCP with name \fIname\fR is +attached to. +.RE + .PP \fBirm ipcp enroll\fR name \fIname\fR [type \fItype\fR] [dst \fIdst\fR] \ [layer \fIlayer\fR] [\fIautobind\fR] @@ -308,6 +275,15 @@ the layer name is a shorthand for the destination name being the same as the layer name. .PP [autobind] will automatically bind this IPCP to its name and the layer name. +.PP +[udp \fIip\fR[:\fIport\fR]] enrols over a point of attachment this +IPCP is attached to, at a peer reachable at this IPv4 or IPv6 address +or host name. +.PP +[eth [dev \fIdevice\fR] [ethertype \fIethertype\fR]] enrols over a +point of attachment this IPCP is attached to, resolving the peer by a +name query over Ethernet. [dev \fIdevice\fR] restricts the query to +one attached device. .RE \fBirm ipcp connect\fR name \fIname\fR component \fIcomponent\fR dst @@ -316,6 +292,18 @@ as the layer name. connects a \fIcomponent\fR (\fBdt\fR or \fBmgmt\fR) of a unicast or broadcast IPCP with name \fIname\fR to that component of the destination IPCP within the same layer. +.PP +[qos \fIqos\fR] specifies the QoS cube for a \fBdt\fR flow: raw, safe, +rt, rt-safe or msg. +.PP +[udp \fIip\fR[:\fIport\fR]] connects over a point of attachment +this IPCP is attached to, to a peer reachable at this IPv4 or IPv6 +address or host name. +.PP +[eth [dev \fIdevice\fR] [ethertype \fIethertype\fR]] connects over a +point of attachment this IPCP is attached to, resolving the peer by a +name query over Ethernet. [dev \fIdevice\fR] restricts the query to +one attached device. .RE \fBirm ipcp disconnect\fR name \fIname\fR component \fIcomponent\fR dst -- cgit v1.2.3