OUROBOROS(8)

NAME
Ouroboros - the free IPC subsystem

SYNOPSIS
irmd [--stdout] [--version] irm [ipcp] <command> <args>

DESCRIPTION
Ouroboros is an Inter-Process Communication (IPC) subsystem consisting of an IPC Resource Manager (IRM), a number of IPC Processes (IPCPs) and a library. It provides an API to establish communication between processes, regardless of whether they are running locally or remote. 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
The IPC Resource Manager (IRM) is the core component of the Ouroboros subsystem. It manages IPC processes and the datastructures used for communication over Ouroboros. Before using Ouroboros, an IRM daemon must be running on your system. The IRM daemon can be started as a process at the command line (as a superuser): $ irmd or, if your system uses systemd, the IRM can be started as a service: $ systemctl start irmd 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
The irm tool is used to command the Ouroboros subsystem or individual IPCPs.

WORKFLOW
To setup a flow between processes, Ouroboros has a number of steps that must be taken. These steps can be taken in (almost) any order.
    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. 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 normal 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), L1 (raptor, experimental), L2 (eth-llc) and L3 (udp). The normal layer requires 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.

    raptor - create an IPCP that attaches to a raptor NetFPGA device.

    eth-llc - create an IPCP that attaches to an Ethernet adapter.

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

    normal - create a normal 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.
    raptor

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

    eth-llc
        if_name 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.

    udp
        ip ip specifies the local IP address to bind to [dns ns] specifies an optional DDNS server that will be used for the directory.

    normal
        [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, lfa.
        default: link_state.

        [pff policy] specifies the pdu forwarding function policy.
        policy: simple, alternate.
        default: simple.

        [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 normal IPCP to its name and the layer name.

irm ipcp enroll name name layer layer [autobind]
    enrolls a normal IPCP name to a layer for which the IPCPs accept flows for 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 normal 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 normal IPCP with name name from that component of the destination IPCP within the same layer.

IRM 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 reg name name layer layer [layer layer ...]
    Register name name in layers layer.

irm unreg name name layer layer [layer layer ...]
    Unregister name name in layers layer.

TERMINOLOGY
Please see ouroboros-glossary(7).

AUTHORS
Ouroboros was started and is currently maintained by Dimitri Staessens and Sander Vrijders.

REPORTING BUGS
Report bugs on the bugzilla tracker at https://ouroboros.ilabt.imec.be/bugzilla

SEE ALSO
flow_alloc(3), ouroboros-tutorial(7), ouroboros-glossary(7)

COLOPHON
This page is part of the Ouroboros project, found at http://ouroboros.ilabt.imec.be 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/