From d6b7840709288cd1fdd1d275986c4133856c5e2d Mon Sep 17 00:00:00 2001 From: dimitri staessens Date: Sun, 15 Oct 2017 21:56:26 +0200 Subject: doc: Add general documentation This adds user documentation for the Ouroboros User Manual in man sections 7 and 8. It consists of a general man page, a tutorial and a glossary. It also fixes and updates other manpages in the Ouroboros Programmer's Manual. --- doc/man/CMakeLists.txt | 5 + doc/man/fccntl.3 | 38 ++++-- doc/man/flow_alloc.3 | 10 +- doc/man/flow_read.3 | 13 +- doc/man/fqueue.3 | 11 +- doc/man/fset.3 | 10 +- doc/man/irm.8 | 1 + doc/man/irmd.8 | 1 + doc/man/ouroboros-glossary.7 | 122 +++++++++++++++++ doc/man/ouroboros-tutorial.7 | 146 ++++++++++++++++++++ doc/man/ouroboros.8 | 315 +++++++++++++++++++++++++++++++++++++++++++ 11 files changed, 645 insertions(+), 27 deletions(-) create mode 100644 doc/man/irm.8 create mode 100644 doc/man/irmd.8 create mode 100644 doc/man/ouroboros-glossary.7 create mode 100644 doc/man/ouroboros-tutorial.7 create mode 100644 doc/man/ouroboros.8 (limited to 'doc') diff --git a/doc/man/CMakeLists.txt b/doc/man/CMakeLists.txt index ba72b14b..e1d5c04a 100644 --- a/doc/man/CMakeLists.txt +++ b/doc/man/CMakeLists.txt @@ -18,6 +18,11 @@ set(MAN_NAMES fset_add.3 fset_del.3 fset_has.3 + ouroboros-glossary.7 + ouroboros-tutorial.7 + ouroboros.8 + irmd.8 + irm.8 ) macro(INSTALL_MAN __mans) diff --git a/doc/man/fccntl.3 b/doc/man/fccntl.3 index eaa6a02e..ac28aef5 100644 --- a/doc/man/fccntl.3 +++ b/doc/man/fccntl.3 @@ -2,7 +2,7 @@ .\" Dimitri Staessens .\" Sander Vrijders -.TH FCCNTL 3 2017-08-30 GNU "Ouroboros Programmer's Manual" +.TH FCCNTL 3 2017-08-30 Ouroboros "Ouroboros Programmer's Manual" .SH NAME @@ -43,17 +43,20 @@ flow. Takes a \fBqosspec_t * \fIqs\fR as third argument. \fBFLOWSFLAGS\fR - set flow flags. Takes flow flags as third argument. Supported flags are: - \fIFLOWFRDONLY\fR - set flow to read-only. +.RS 8 +\fIFLOWFRDONLY\fR - set flow to read-only. - \fIFLOWFWRONLY\fR - set flow_to write-only. +\fIFLOWFWRONLY\fR - set flow_to write-only. - \fIFLOWFRDWR\fR - set flow to read-write. +\fIFLOWFRDWR\fR - set flow to read-write. - \fIFLOWFDOWN\fR - mark flow as down. +\fIFLOWFDOWN\fR - mark flow as down. - \fIFLOWFNONBLOCK\fR - set I/O to non-blocking. +\fIFLOWFNONBLOCK\fR - set I/O to non-blocking. - \fIFLOWFDEFAULT\fR - set flow defaults (blocking, read-write). +\fIFLOWFDEFAULT\fR - set flow defaults (blocking, read-write). + +.RE \fBFLOWGFLAGS\fR - get the current flow flags. Takes an \fBuint32_t \fIflags\fR as third argument. @@ -61,15 +64,18 @@ argument. Supported flags are: \fBFRCTSFLAGS\fR - set FRCT flags. Takes FRCT flags as third argument. Supported flags are: - \fIFRCTFRESCNTRL\fR - enable resource control. +.RS 8 +\fIFRCTFRESCNTRL\fR - enable resource control. + +\fIFRCTFRTX\fR - enable retransmission. - \fIFRCTFRTX\fR - enable retransmission. +\fIFRCTFERRCHCK\fR - enable checksum (CRC32). - \fIFRCTFERRCHCK\fR - enable checksum (CRC32). +\fIFRCTFORDERING\fR - enable packet in-order delivery. - \fIFRCTFORDERING\fR - enable packet in-order delivery. +\fIFRCTFPARTIAL\fR - enable partial delivery. - \fIFRCTFPARTIAL\fR - enable partial delivery. +.RE \fBFRCTGFLAGS\fR - get the current flow flags. Takes an \fBuint16_t \fIflags\fR as third argument. @@ -112,10 +118,14 @@ _ \fBfccntl\fR() & Thread safety & MT-Safe .TE +.SH TERMINOLOGY +Please see \fBouroboros-glossary\fR(7). + .SH SEE ALSO -.BR flow_alloc "(3), " flow_accept "(3), " flow_dealloc "(3), " fqueue (3) +.BR flow_alloc "(3), " flow_read "(3), " fqueue "(3), " fset "(3), " \ +ouroboros (8) .SH COLOPHON This page is part of the Ouroboros project, found at -https://bitbucket.org/ouroboros-rina/ouroboros +http://ouroboros.ilabt.imec.be diff --git a/doc/man/flow_alloc.3 b/doc/man/flow_alloc.3 index cab8153e..cc505df6 100644 --- a/doc/man/flow_alloc.3 +++ b/doc/man/flow_alloc.3 @@ -2,7 +2,7 @@ .\" Dimitri Staessens .\" Sander Vrijders -.TH FLOW_ALLOC 3 2017-04-10 GNU "Ouroboros Programmer's Manual" +.TH FLOW_ALLOC 3 2017-04-10 Ouroboros "Ouroboros Programmer's Manual" .SH NAME @@ -107,10 +107,14 @@ _ \fBflow_dealloc\fR() & Thread safety & MT-Safe .TE +.SH TERMINOLOGY +Please see \fBouroboros-glossary\fR(7). + .SH SEE ALSO -.BR flow_read "(3), " flow_write (3) +.BR fccntl "(3), " flow_read "(3), " fqueue "(3), " fset "(3), " \ +ouroboros (8) .SH COLOPHON This page is part of the Ouroboros project, found at -https://bitbucket.org/ouroboros-rina/ouroboros +http://ouroboros.ilabt.imec.be diff --git a/doc/man/flow_read.3 b/doc/man/flow_read.3 index 9e7842e5..db42301d 100644 --- a/doc/man/flow_read.3 +++ b/doc/man/flow_read.3 @@ -2,7 +2,7 @@ .\" Dimitri Staessens .\" Sander Vrijders -.TH FLOW_READ 3 2017-04-10 GNU "Ouroboros Programmer's Manual" +.TH FLOW_READ 3 2017-04-10 Ouroboros "Ouroboros Programmer's Manual" .SH NAME @@ -53,6 +53,9 @@ The flow was not allocated. .B -EFLOWDOWN The flow has been reported down. +.B -EMSGSIZE +The buffer was too large to be written. + .SH ATTRIBUTES For an explanation of the terms used in this section, see \fBattributes\fR(7). @@ -68,10 +71,14 @@ _ \fBflow_write\fR() & Thread safety & MT-Safe .TE +.SH TERMINOLOGY +Please see \fBouroboros-glossary\fR(7). + .SH SEE ALSO -.BR flow_alloc "(3), " flow_dealloc (3) +.BR fccntl "(3), " flow_alloc "(3), " fqueue "(3), " fset "(3), " \ +ouroboros (8) .SH COLOPHON This page is part of the Ouroboros project, found at -https://bitbucket.org/ouroboros-rina/ouroboros +http://ouroboros.ilabt.imec.be diff --git a/doc/man/fqueue.3 b/doc/man/fqueue.3 index f932633d..eeda6425 100644 --- a/doc/man/fqueue.3 +++ b/doc/man/fqueue.3 @@ -2,7 +2,7 @@ .\" Dimitri Staessens .\" Sander Vrijders -.TH FQUEUE 3 2017-08-29 GNU "Ouroboros Programmer's Manual" +.TH FQUEUE 3 2017-08-29 Ouroboros "Ouroboros Programmer's Manual" .SH NAME @@ -92,11 +92,14 @@ _ \fBfevent\fR() & Thread safety & MT-Safe .TE +.SH TERMINOLOGY +Please see \fBouroboros-glossary\fR(7). + .SH SEE ALSO -.BR fset_create "(3), " fset_destroy "(3), " \ -fset_add "(3), " fset_del "(3), " fset_has "(3), " fset_zero (3) +.BR fccntl "(3), " flow_alloc "(3), " flow_read "(3), " fqueue "(3), " \ +fset "(3), " ouroboros (8) .SH COLOPHON This page is part of the Ouroboros project, found at -https://bitbucket.org/ouroboros-rina/ouroboros +http://ouroboros.ilabt.imec.be diff --git a/doc/man/fset.3 b/doc/man/fset.3 index 3b367e17..f5a2b4cc 100644 --- a/doc/man/fset.3 +++ b/doc/man/fset.3 @@ -2,7 +2,7 @@ .\" Dimitri Staessens .\" Sander Vrijders -.TH FSET 3 2017-04-10 GNU "Ouroboros Programmer's Manual" +.TH FSET 3 2017-04-10 Ouroboros "Ouroboros Programmer's Manual" .SH NAME @@ -98,10 +98,14 @@ _ \fBfset_has\fR() & Thread safety & MT-Safe .TE +.SH TERMINOLOGY +Please see \fBouroboros-glossary\fR(7). + .SH SEE ALSO -.BR fqueue "(3), " fevent (3) +.BR fccntl "(3), " flow_alloc "(3), " flow_read "(3), " fccntl "(3), " \ +fqueue "(3), " ouroboros (8) .SH COLOPHON This page is part of the Ouroboros project, found at -https://bitbucket.org/ouroboros-rina/ouroboros +http://ouroboros.ilabt.imec.be diff --git a/doc/man/irm.8 b/doc/man/irm.8 new file mode 100644 index 00000000..6ac4974b --- /dev/null +++ b/doc/man/irm.8 @@ -0,0 +1 @@ +.so ouroboros.8 diff --git a/doc/man/irmd.8 b/doc/man/irmd.8 new file mode 100644 index 00000000..6ac4974b --- /dev/null +++ b/doc/man/irmd.8 @@ -0,0 +1 @@ +.so ouroboros.8 diff --git a/doc/man/ouroboros-glossary.7 b/doc/man/ouroboros-glossary.7 new file mode 100644 index 00000000..cb397c76 --- /dev/null +++ b/doc/man/ouroboros-glossary.7 @@ -0,0 +1,122 @@ +.\" Ouroboros man pages (C) 2017 +.\" Dimitri Staessens +.\" Sander Vrijders + +.TH OUROBOROS-GLOSSARY 7 2017-10-15 Ouroboros "Ouroboros User Manual" + +.SH NAME + +ouroboros-glossary - The Ouroboros Glossary + +.SH SYNOPSIS + * + +.SH USER MANUAL GLOSSARY +.PP +address +.RS 4 +an element of a partially ordered set (POSET) consisting of data +transfer component namespaces within an IPC process +.RE + +.PP +bind a name +.RS 4 +to associate a name with a program or process. This mapping is stored +in the IRMd. +.RE + +.PP +bootstrap +.RS 4 +to configure an IPCP and start it as the first member of a DIF. +.RE + +.PP +congestion control +.RS 4 +the mechanism by which a server DIF controls its resources and +prevents its client processes from sending more information than it +can currently handle. This is orthogonal to flow control. +.RE + +.PP +directory +.RS 4 +the database that keeps a mapping between an address and a registered +hash. In Ouroboros, the default implementation is a Distributed Hash +Table. +.RE + +.PP +distributed IPC facility (DIF) +.RS 4 +deprecate? +.RE + +.PP +enrolment +.RS 4 +the action of connecting to a member of an existing DIF, retrieving +the bootstrap information and starting the IPCP as a new member of +that DIF. +.RE + +.PP +flow +.RS 4 +the system and network resources over which two application processes +can send information. A flow is an abstraction of the actual +underlying IPC mechanism and has a quality of service (QoS) associated +with it, which reflects externally measurable quantities such as +delay, jitter, bandwidth, loss and bit error rate. +.RE + +.PP +flow allocator +.RS 4 +the component of an IPCP that reserves the resources for a flow +towards a given registered hash. +.RE + +.PP +flow control +.RS 4 +the mechanism with which the destination endpoint of a connection +controls the source to prevent the source from sending more +information than the destination can currently handle. This is +orthogonal to congestion control. +.RE + +.PP +flow descriptor +.RS 4 +an integer used as a handle to a flow (a port ID) within an +application. +.RE + +.PP +inter process communication (IPC) +.RS 4 +the mechanisms that allow processes to share information. +.RE + +.PP +IPC process +.RS 4 +a process that allocates and manages the necessary resources within a +layer to allow IPC between processes that are clients of that layer. +.RE + +.PP +IPC resource manager (IRM) +.RS 4 +the process that manages local IPC and IPCPs (providing remote IPC). +.RE + +.SH SEE ALSO +\fBouroboros-tutorial\fR(7)\fB, ouroboros\fR(8) + +.SH COLOPHON +This page is part of the Ouroboros project, found at +http://ouroboros.ilabt.imec.be diff --git a/doc/man/ouroboros-tutorial.7 b/doc/man/ouroboros-tutorial.7 new file mode 100644 index 00000000..200d7589 --- /dev/null +++ b/doc/man/ouroboros-tutorial.7 @@ -0,0 +1,146 @@ +.\" Ouroboros man pages (C) 2017 +.\" Dimitri Staessens +.\" Sander Vrijders + +.TH OUROBOROS-TUTORIAL 7 2017-10-15 Ouroboros "Ouroboros User Manual" + +.SH NAME + +ouroboros-tutorial - A tutorial introduction to managing Ouroboros + +.SH SYNOPSIS + +irm * + +.SH DESCRIPTION +This tutorial explains how to start and configure the Ouroboros +Inter-Process Communication subsystem. + +.SH STARTING AND STOPPING THE IPC RESOURCE MANAGER DAEMON + +For the tutorials, it is recommended to start the IRMd (you will need +root privileges) as a user process, writing output to stdout (If your +system has an IRMd running as a systemd service, you will need to stop +it). + +.RS 4 +$ irmd --stdout +.RE + +Terminating the irmd can be done by pressing Ctrl+C if it is running +in the foreground or by sending it a kill command for its process ID: + +.RS 4 +$ kill 25959 +.RE + +The output should be + +.RS 4 +==25959== irmd(II): Ouroboros IPC Resource Manager daemon started... +.br +==25959== irmd(II): IRMd shutting down... +.br +==25959== irmd(II): Bye. +.RE + +.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 a shim-eth-llc shim 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)). + +.RS 4 +$ irm ipcp bootstrap type shim-eth-llc name shim dif llc if lo +.RE + +.RS 4 +==23918== irmd(II): Created IPCP 23932. +.br +==23932== ipcpd/shim-eth-llc(II): Using raw socket device. +.br +==23918== irmd(II): Bootstrapped IPCP 23932 in DIF llc. +.RE + +Now that we have a shim IPCP bootstrapped, it can act as a local +network 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 +shim DIF. + +.RS 4 +$ irm reg name my.oping.server dif llc +.RE + +The IRMd should respond with + +.RS 4 +==23918== irmd(II): Registered my.oping.server in llc as 716016b1. +.RE + +Now start a server of oping in the background (or in a different +terminal) and bind the process to the name "my.oping.server" (replace +the correct process id for your system). + +.RS 4 +$ oping -l & +.br +[1] 24063 +.br +$ irm bind api 24063 name my.oping.server +.RE + +With the server up and running, let's connect a client and send 3 +pings: + +.RS 4 +$ oping -n my.oping.server -c 3 +.br +Pinging my.oping.server with 64 bytes of data: + +64 bytes from my.oping.server: seq=0 time=0.475 ms +.br +64 bytes from my.oping.server: seq=1 time=0.304 ms +.br +64 bytes from my.oping.server: seq=2 time=0.398 ms + +--- my.oping.server ping statistics --- +.br +3 SDUs transmitted, 3 received, 0% packet loss, time: 3001.011 ms +.br +rtt min/avg/max/mdev = 0.304/0.392/0.475/0.086 ms +.RE + +That's all there is to it! The IRMd should log the flow +allocation. There are two endpoints of the flow (port_id's 0 and 1), +one for the server (1) and one for the client (0). After the flow +request, a new port_id is created at the server side (port_id 1) and +then a previously pending flow (on port_id 0) is allocated following +the response from the server. + +When the communication is done, the flow is deallocated and the +resources (port_id's 0 and 1) are released. + +.RS 4 +==23918== irmd(II): Flow request arrived for my.oping.server. +.br +==23918== irmd(II): Flow on port_id 1 allocated. +.br +==23918== irmd(II): Flow on port_id 0 allocated. +.br +==23918== irmd(II): Completed deallocation of port_id 0 by AP-I 23932. +.br +==23918== irmd(II): Completed deallocation of port_id 1 by AP-I 23932. +.RE + +.SH TERMINOLOGY +Please see \fBouroboros-glossary\fR(7). + +.SH SEE ALSO +\fBouroboros\fR(8)\fB, ouroboros-tutorial\fR(7)\fB.\fR + +.SH COLOPHON +This page is part of the Ouroboros project, found at +http://ouroboros.ilabt.imec.be diff --git a/doc/man/ouroboros.8 b/doc/man/ouroboros.8 new file mode 100644 index 00000000..c7e8aaab --- /dev/null +++ b/doc/man/ouroboros.8 @@ -0,0 +1,315 @@ +.\" Ouroboros man pages (C) 2017 +.\" Dimitri Staessens +.\" Sander Vrijders + +.TH OUROBOROS 8 2017-10-15 Ouroboros "Ouroboros User Manual" + +.SH NAME + +Ouroboros - the free IPC subsystem + +.SH SYNOPSIS + +\fIirmd\fR [--stdout] [--version] + +\fIirm\fR [ipcp] + +.SH 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 \fBouroboros-tutorial\fR(7) to get started. + +This page provides an overview of the command options for the +\fBirmd\fR and associated \fBirm\fR toolset. You can learn more about +individual commands with "irm [command] help". + +.SH IRM DAEMON +The \fBIPC Resource Manager (IRM)\fR is the core component of the +Ouroboros subsystem. It manages \fIIPC processes\fR 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: +.PP +\-\-stdout +.RS 4 +The \fIIRM\fR daemon and \fIIPCPs\fR will print output to stdout +instead of the system logs. +.RE + +.PP +\-\-version +.RS 4 +The \fIIRM\fR daemon will print the Ouroboros version to stdout and exit. +.RE + +.SH IRM TOOL +The \fBirm\fR tool is used to command the Ouroboros subsystem or +individual IPCPs. + +.SH WORKFLOW +To setup a \fIflow\fR between processes, Ouroboros has a number of +steps that must be taken. These steps can be taken in (almost) any +order. + +.RS 4 + +\fBBinding a name to a program or process\fR tells the IRMd that a +certain \fIprogram\fR or \fIprocess\fR will respond to \fIflow +allocation\fR 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. + +\fBCreating an IPC Process\fR will instantiate a new IPCP in the +system. This IPCP will be empty, with only a name and type specified, +and ready for either \fIbootstrapping\fR into a new DIF (or a new or +existing shim DIF) or \fIenrolling\fR in an existing DIF. + +\fBBootstrapping an IPC Process\fR gives it the necessary information +from the command line to start operating as a \fIDIF\fR. Each IPCP +type has its own set of configuration options. + +\fBEnrolling an IPC Process\fR in a DIF configures it by contacting +another IPCP that is already a member of that DIF (bootstrapped or +enrolled). After \fIenrollment\fR, the IPCP is configured, and may or +may not have connections to the DIF. + +\fBRegistering a name in a DIF\fR inserts the name in that \fIDIF\fR's +\fIdirectory\fR. Once a name is \fIregistered\fR in a DIF, the name +can be used as a destination handle for \fIflow allocation\fR. + +Ouroboros normal IPCPs are just like any other process, and will need +to be bound and registered in a lower-rank DIF before they can be +accessed by other processes. + +In order to enroll an IPC process in a DIF, some other member will +have to be reachable over a lower DIF. Shim IPCPs are all bootstrapped +and thus need not enroll as they work directly over a physical +connection. Ouroboros currently supports shim IPCPs over shared memory +(local), L2 (shim-eth-llc), L1 (raptor, experimental) and L3 +(shim-udp). The normal DIF requires connections to be established +between IPCP components for its operation. + +.RS 4 +\fBConnecting the management components\fR using \fImanagement +flows\fR 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. + +\fBConnecting the data transfer components\fR using \fIdata transfer +flows\fR 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 \fIdirectory\fR and the +\fIflow allocator\fR. + +.RE + +.SH IRM IPCP COMMANDS +.PP +\fBirm ipcp create\fR type \fItype\fR name \fIname\fR +.RS 4 +creates an IPCP process of type \fItype\fR in the system with name +\fIname\fR. Allowable values for \fItype\fR are: +.PP +\fBlocal\fR - create a loopback IPCP. +.PP +\fBshim-eth-llc\fR - create an IPCP that attaches to an Ethernet adapter. +.PP +\fBshim-udp\fR - create an IPCP that attaches to a UDP socket. +.PP +\fBnormal\fR - create a normal IPCP that uses lower level DIFs. +.RE + +.PP +\fBirm ipcp destroy\fR name \fIname\fR +.RS 4 +destroys the IPCP process with name \fIname\fR. +.RE +.PP +\fBirm ipcp bootstrap\fR type \fItype\fR name \fIname\fR dif \fIdif\fR \ +[\fIparams\fR] +.RS 4 +bootstraps an IPCP process of type \fItype\fR and name \fIname\fR in a +DIF \fIdif\fR. If an IPCP with that name does not exist yet, the IPCP +will be created. +.PP +Values for [\fIparam\fR] are dependent on \fItype\fR: +.PP +\fBlocal\fR +.RS 4 +does not take additional parameters. +.RE + +.PP +\fBshim-eth-llc\fR +.RS 4 +if_name \fIinterface\fR specifies the interface to bind the shim to. +.RE + +.PP +\fBshim-udp\fR +.RS 4 +ip \fIip\fR specifies the local IP address to bind to + +[dns \fdns\fR] specifies an optional DDNS server that will be used for +the directory. +.RE + +.PP +\fBnormal\fR +.RS 4 +[addr \fIaddress_size\fR] specifies the size of an address in bytes. +.br +default: 4 bytes. +.PP +[fd \fIfd_size\fR] specifies the size of the flow descriptor field +(for identifying internal components using the DT component) in bytes. +.br +default: 2 bytes. +.PP +[ttl] specifies the presence of a time-to-live field. +TODO: set a default TTL here? +.PP +[addr_auth \fIpolicy\fR] specifies the address authority policy. +.br +\fIpolicy\fR: flat. +.br +default: flat. +.PP +[routing \fIpolicy\fR] specifies the routing policy. +.br +\fIpolicy\fR: link_state, lfa. +.br +default: link_state. +.PP +[pff \fIpolicy\fR] specifies the pdu forwarding function policy. +.br +\fIpolicy\fR: simple, alternate. +.br +default: simple. +.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 +.RE + +.PP +\fBirm ipcp enroll\fR name \fIname\fR dif \fIdif\fR +.RS 4 +enrolls a normal IPCP \fIname\fR to a dif for which the IPCPs accept flows for +\fIname\fR. +.RE + +\fBirm ipcp connect\fR name \fIname\fR component \fIcomponent\fR dst +\fIdestination\fR +.RS 4 +connects a \fIcomponent\fR (\fBdt\fR or \fBmgmt\fR) of a normal IPCP +with name \fIname\FR to that component of the destination IPCP within the +same DIF. +.RE + +\fBirm ipcp disconnect\fR name \fIname\fR component \fIcomponent\fR dst +\fIdestination\fR +.RS 4 +disconnects \fIcomponent\fR (\fBdt\fR or \fBmgmt\fR) of a normal IPCP +with name \fIname\FR from that component of the destination IPCP within the +same DIF. +.RE +.RE + +.SH IRM COMMANDS +.PP +\fBirm bind\fR ap \fiprogram\fR name \fIname\fR [[\fIauto\fR] -- \ +[\fIparam\fR] [\fIparam\fR] ... [\fIparam\fR]] +.RS 4 +bind a program \fIprogram\fR, 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 \fBPATH\fR +variable. If \fIname\fR is registered in a DIF, all instances of +\fIprogram\fR will accept flows for \fIname\fR. If the \fIauto\fR +keyword is specified, the IRMd will start instances if there are no +readily available instances when a new flow is requested and any +arguments \fIparam\fR that are passed after -- are passed to the +application when it is started. +.RE + +.PP +\fBirm bind\fR api \fIpid\fR name \fInamefR +.RS 4 +bind a process \fIpid\fR to a certain name. If \fIname\fR is registered +in a DIF, the process \fIpid\fR will accept flows for that name. +.RE + +.PP +\fBirm bind\fR ipcp \fIipcp\fR name \fIname\fR +.RS 4 +bind an IPCP \fIipcp\fR to a \fIname\fR. If \fIname\fR is registered +in a DIF, \fIipcp\fR will accept flows for \fIname\fR. This is a +shorthand for binding the pid of \fipcp\fR. +.RE + +.PP +\fBirm unbind\fR ap \fIprogram\fR name \fIname\fR +.RS 4 +remove the binding between \fIprogram\fR and \fIname\fR. Instances of +\fIprogram\fR will not accept future flow allocation requests for +\fIname\fR. +.RE + +.PP +\fBirm unbind\fR api \fIpid\fR name \fIname\fR +.RS 4 +remove the binding between \fIpid\fR and \fIname\fR. The process +\fIpid\fR will not accept future flow allocation requests for +\fIname\fR. +.RE + +.PP +\fBirm unbind\fR ipcp \fIipcp\fR name \fIname\fR +.RS 4 +remove the binding between \fIipcp\fR and \fIname\fR. This IPCP will +not accept future flow allocation requests for \fIname\fR. +.RE + +.PP +\fBirm reg\fR name \fIname\fR dif \fIdif\fR [dif \fIdif\fR ...] +.RS 4 +Register name \fIname\fR in difs \fIdif\fR. +.RE + +.PP +\fBirm unreg\fR name \fIname\fR dif \fIdif\fR [dif \fIdif\fR ...] +.RS 4 +Unregister name \fIname\fR in difs \fIdif\fR. +.RE + +.SH TERMINOLOGY +Please see \fBouroboros-glossary\fR(7). + +.SH AUTHORS +Ouroboros was started and is currently maintained by Dimitri Staessens +and Sander Vrijders. + +.SH REPORTING BUGS +Report bugs on the bugzilla tracker at https://ouroboros.ilabt.imec.be/bugzilla. + +.SH SEE ALSO +\fBouroboros-tutorial\fR(7)\fB, ouroboros-glossary\fR(7)\fB.\fR + +.SH COLOPHON +This page is part of the Ouroboros project, found at +http://ouroboros.ilabt.imec.be -- cgit v1.2.3