OUROBOROS

NAME

Ouroboros - the free IPC subsystem

SYNOPSIS

irmd [--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:

--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. 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.

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

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

local - create a loopback IPCP.

eth-llc - create an IPCP that attaches to Ethernet using LLC frames.

eth-dix - create an IPCP that attaches to Ethernet using DIX frames.

udp - create an IPCP that attaches to a UDP socket.

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

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

irm ipcp destroy name name

destroys the IPCP process with name name.

irm ipcp bootstrap type type name name layer layer [params] [autobind]

bootstraps an IPCP process of type type and name name in a layer layer. If an IPCP with that name does not exist yet, the IPCP will be created.

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.

eth-llc

dev interface specifies the interface to bind the IPCP to.

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

eth-dix

dev interface specifies the interface to bind the IPCP to.

[ethertype ethertype] specifies the ethertype used for the layer.
default: 0xA000.

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

udp

ip ip specifies the local IP address to bind to

[dns dns] specifies an optional DDNS server that will be used for the directory.

[port port] specifies a UDP port that is used for sending and receiving ouroboros traffic. This must be the same for the entire UDP layer. Parallel UDP 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.
default: 3435

unicast

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

[fd fd_size] specifies the size of the flow descriptor field (for identifying internal components using the DT component) in bytes.
default: 2 bytes.

[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 enroll name name [type type] [dst dst] [layer layer] [autobind]

enrolls a unicast ot 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.

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

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.

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. You can filter by type, by name or by layer.

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 pcp.

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

Create a name name with a load-balancing policy
policy: round-robin, spillover

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