OUROBOROS

NAME

Ouroboros - the free IPC subsystem

SYNOPSIS

irmd [--config <path>] [--stdout] [--version]

irm [ipcp] <command> <args>

DESCRIPTION

See ouroboros-tutorial(7) to get started.

This page provides an overview of the command options for the irmd and associated irm toolset. You can learn more about individual commands with "irm [command] help".

IRM DAEMON

$ irmd

or, if your system uses systemd, Ouroboros can be started as a service:

$ systemctl start ouroboros

When started from the command line, the IRM has the following options:

--config path

The IRM daemon will read its configuration from the file at path. Only available when Ouroboros is built with configuration file support.

--stdout

The IRM daemon and IPCPs will print output to stdout instead of the system logs.

--version

The IRM daemon will print the Ouroboros version to stdout and exit.

IRM TOOL

WORKFLOW

Binding a name to a program or process tells the IRMd that a certain program or process will respond to flow allocation requests for the bound name. Multiple programs and processes can be bound to the same name, and a program or process can be bound to multiple names. This only works for programs that use the Ouroboros API.

Creating an IPC Process will instantiate a new IPCP in the system. This IPCP will be empty, with only a name and type specified, and ready for either bootstrapping into a new layer or enrolling in an existing layer.

Bootstrapping an IPC Process gives it the necessary information from the command line to start operating as a layer. Each IPCP type has its own set of configuration options.

Enrolling an IPC Process in a layer configures it by contacting another IPCP that is already a member of that layer (bootstrapped or enrolled). After enrollment, the IPCP is configured, and may or may not have connections to the layer.

Registering a name in a layer inserts the name in that layer's directory. Once a name is registered in a layer, the name can be used as a destination handle for flow allocation.

Ouroboros unicast IPCPs are just like any other process, and will need to be bound and registered in a lower-rank layer before they can be 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. A unicast or broadcast IPCP attaches to a transmission technology itself, as a point of attachment (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.

Connecting the management components using management flows allows management information to be sent between IPCPs so that resources for flows can be allocated. Currently the only component that requires management flows is the routing component.

Connecting the data transfer components using data transfer flows allows the routing system to forward packets between IPCPs. This establishes adjacencies in a network of IPCPs. Components that rely on data transfer flows are the directory and the flow allocator.

IRM IPCP COMMANDS

irm ipcp create type type name name [transit on|off]

creates an IPCP process of type type in the system with name name. Allowable values for type are:

local - create a loopback IPCP.

unicast - create a unicast IPCP that uses lower level layers.

broadcast - create a broadcast IPCP that uses lower level layers.

A unicast or broadcast IPCP can be created with transit off to disable forwarding traffic.

irm ipcp destroy name name

destroys the IPCP process with name name.

irm ipcp bootstrap type type name name layer layer [params] [transit on|off] [autobind]

bootstraps an IPCP process of type type and name name in a layer layer, creating the IPCP first if none with that name exists. [transit on|off] sets the transit setting of the IPCP before it is bootstrapped.

Values for [param] are dependent on type:

local

[hash policy] specifies the hash function used for the directory,
policy: SHA3_224, SHA3_256, SHA3_384, SHA3_512.
default: SHA3_256.

unicast

[addr address_size] specifies the size of an address in bytes.
default: 4 bytes.

[eid eid_size] specifies the size of the endpoint identifier field in bytes.
default: 8 bytes, the only supported value.

[ttl] specifies the maximum value for the time-to-live field.

[addr_auth policy] specifies the address authority policy.
policy: flat.
default: flat.

[routing policy] specifies the routing policy.
policy:

link_state: default shortest-path link-state routing.
lfa: loop-free alternate resilient routing.
ecmp: equal-cost multipath routing.

default: link_state.

[congestion policy] specifies the congestion avoidance policy.
policy:

none: no congestion avoidance.
mb-ecn: Multi-bit explicit congestion notification and avoidance.

default: mb-ecn.

[hash policy] specifies the hash function used for the directory.
policy: SHA3_224, SHA3_256, SHA3_384, SHA3_512.
default: SHA3_256.

[autobind] will automatically bind a unicast or broadcast IPCP to its name and the layer name.

broadcast

[hash policy] specifies the hash function used for the layer name.
policy: SHA3_224, SHA3_256, SHA3_384, SHA3_512.
default: SHA3_256.

irm ipcp poa attach name name poa

attaches the IPCP with name name to a point of attachment. Repeat to attach more than one. Exactly one poa is given:

udp ip[:port] attaches to a local IPv4 or IPv6 address. IPv6 addresses need brackets when a port is given: [ip]:port.
default port: 3435.

eth dev device [ethertype ethertype] attaches to an Ethernet device.
default: 0xA000.

irm ipcp poa detach name name poa

releases a point of attachment that the IPCP with name name is attached to. Flows over it are brought down first. poa takes the same values as for attach.

irm ipcp poa list name name

lists the points of attachment that the IPCP with name name is attached to.

irm ipcp enroll name name [type type] [dst dst] [layer layer] [transit on|off] [autobind]

enrolls a unicast or broadcast IPCP name with a dst IPCP into a layer. Either dst or layer need to be specified.

[type type] specifies the IPCP type (unicast or broadcast).

[dst dst] specifies the destination name to enroll with

[layer layer] specifies the name of the layer. Only specifying the layer name is a shorthand for the destination name being the same as the layer name.

[transit on|off] sets the transit setting of the IPCP before it is enrolled.

[autobind] will automatically bind this IPCP to its name and the layer name.

[udp ip[:port]] enrols over a point of attachment this IPCP is attached to, at a peer reachable at this IPv4 or IPv6 address or host name.

[eth [dev device] [ethertype ethertype]] enrols over a point of attachment this IPCP is attached to, resolving the peer by a name query over Ethernet. [dev device] restricts the query to one attached device.

irm ipcp connect name name component component dst destination

connects a component (dt or mgmt) of a unicast or broadcast IPCP with name name to that component of the destination IPCP within the same layer.

[qos qos] specifies the QoS cube for a dt flow: raw, safe, rt, rt-safe or msg.

[udp ip[:port]] connects over a point of attachment this IPCP is attached to, to a peer reachable at this IPv4 or IPv6 address or host name.

[eth [dev device] [ethertype ethertype]] connects over a point of attachment this IPCP is attached to, resolving the peer by a name query over Ethernet. [dev device] restricts the query to one attached device.

irm ipcp disconnect name name component component dst destination

disconnects component (dt or mgmt) of a unicast or broadcast IPCP with name name from that component of the destination IPCP within the same layer.

irm ipcp list type type name name layer layer

lists IPCPs in the system, with the transit setting of each. You can filter by type, by name or by layer.

irm ipcp set name name transit on|off

changes the transit setting of a running IPCP.

IRM BIND COMMANDS

irm bind program program name name [[auto] -- [param] [param] ... [param]]

bind a program program, referenced by its binary, to a certain name. The binary can be specified by an absolute or relative path, and will be searched for in all directories specified in the PATH variable. If name is registered in a layer, all instances of program will accept flows for name. If the auto keyword is specified, the IRMd will start instances if there are no readily available instances when a new flow is requested and any arguments param that are passed after -- are passed to the application when it is started.

irm bind process pid name name

bind a process pid to a certain name. If name is registered in a layer, the process pid will accept flows for that name.

irm bind ipcp ipcp name name

bind an IPCP ipcp to a name. If name is registered in a layer, ipcp will accept flows for name. This is a shorthand for binding the pid of ipcp.

irm unbind program program name name

remove the binding between program and name. Instances of program will not accept future flow allocation requests for name.

irm unbind process pid name name

remove the binding between pid and name. The process pid will not accept future flow allocation requests for name.

irm unbind ipcp ipcp name name

remove the binding between ipcp and name. This IPCP will not accept future flow allocation requests for name.

IRM NAME COMMANDS

irm name create name lb policy [ssecpath /path/to/server/sec.conf] [scrtpath /path/to/server/crt.pem] [skeypath /path/to/server/key.pem]

[csecpath /path/to/client/sec.conf] [ccrtpath /path/to/client/crt.pem] [ckeypath /path/to/client/key.pem]

Create a name name with a load-balancing policy and security credentials
policy: round-robin, spillover
/path/to/sec.conf: The path to the server and client security configuration. /path/to/pem: The path to the server and client certificates and private keys, in pem format.

irm name destroy name

Destroy name name. This does not unregister or unbind it.

irm name register name ipcp ipcp [ipcp ...] layer [layer layer ...]

Register name name in ipcps ipcp ipcp and layers layer.

irm name unregister name ipcp ipcp [ipcp ...] layer [layer layer ...]

Unregister name name in ipcps ipcp ipcp and layers layer.

irm name list name

List names in the system. name can be used as a prefix to filter the names.

TERMINOLOGY

AUTHORS

REPORTING BUGS

SEE ALSO

COLOPHON

These man pages are licensed under the Creative Commons Attribution 4.0 International License. To view a copy of this license, visit http://creativecommons.org/licenses/by/4.0/

Index

NAME

SYNOPSIS

DESCRIPTION

IRM DAEMON

IRM TOOL

WORKFLOW

IRM IPCP COMMANDS

IRM BIND COMMANDS

IRM NAME COMMANDS

TERMINOLOGY

AUTHORS

REPORTING BUGS

SEE ALSO

COLOPHON