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.

12 files changed, 646 insertions, 29 deletions

diff --git a/README b/README
index bbeb5750..dbc5ebc9 100644
--- a/README
+++ b/README
@@ -1,3 +1,2 @@
-This is the repository holding the Ouroboros prototype. Ouroboros is
-an implementation of the Recursive InterNetwork Architecture. For more
+This is the repository holding the Ouroboros IPC subsystem. For more
 information please refer to the doc/ folder.
\ No newline at end of file
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 <dimitri.staessens@ugent.be>
 .\" Sander Vrijders <sander.vrijders@ugent.be>
 
-.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 <dimitri.staessens@ugent.be>
 .\" Sander Vrijders <sander.vrijders@ugent.be>
 
-.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 <dimitri.staessens@ugent.be>
 .\" Sander Vrijders <sander.vrijders@ugent.be>
 
-.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 <dimitri.staessens@ugent.be>
 .\" Sander Vrijders <sander.vrijders@ugent.be>
 
-.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 <dimitri.staessens@ugent.be>
 .\" Sander Vrijders <sander.vrijders@ugent.be>
 
-.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 <dimitri.staessens@ugent.be>
+.\" Sander Vrijders <sander.vrijders@ugent.be>
+
+.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 <dimitri.staessens@ugent.be>
+.\" Sander Vrijders <sander.vrijders@ugent.be>
+
+.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 <dimitri.staessens@ugent.be>
+.\" Sander Vrijders <sander.vrijders@ugent.be>
+
+.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] <command> <args>
+
+.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