Created documentation for in.ivyd

Made documentation for ivyd and ivyecho more detailed.

3 files changed, 202 insertions, 26 deletions

diff --git a/doc/in.ivyd.8 b/doc/in.ivyd.8
new file mode 100644
index 0000000..e0dae52
--- /dev/null
+++ b/doc/in.ivyd.8
@@ -0,0 +1,77 @@
+.\"
+.\"	IvyDaemon, an Ivy gateway for short-lived agents
+.\"
+.\"	Copyright (C) 1999
+.\"	Centre d'Études de la Navigation Aérienne
+.\"
+.\"	man page for in.ivyd
+.\"
+.\"	Author(s): Stephane Chatty <chatty@cena.dgac.fr>
+.\"
+.\"	$Id $
+.\"
+.\"	Please refer to file version.h for the
+.\"	copyright notice regarding this software
+
+
+.TH IVYD 1 "11 Nov 1999"
+.ds )H CENA, France.
+.ds ]W V1.0
+.UC 4
+.SH NAME
+in.ivyd - super-daemon that works as a port server for the Ivy daemon
+
+.SH SYNOPSIS
+.B "/usr/sbin/in.ivyd [-boot]"
+
+.SH DESCRIPTION
+.B in.ivyd
+is normally not launched by users. It is the port server used by the Ivy daemon
+.B ivyd
+and its clients to know which port they should use to communicate. 
+
+.B in.ivyd
+is either launched by
+.B inetd,
+or at boot time (or manually). The latter option is 
+used in the Linux distributions of the Ivy daemon.
+
+.SH LAUNCHING FROM INETD
+If you want
+.B in.ivyd
+to be launched by
+.B inetd,
+you should add the appropriate lines to
+.I /etc/services
+and
+.I /etc/inetd.conf.
+
+.LP
+In
+.I /etc/services,
+you should add the following line:
+.IP
+in.ivyd      3006/udp                        # ivyd port server
+
+.LP
+and in
+.I /etc/inetd.conf,
+the following line:
+.IP
+in.ivyd   dgram   udp     wait    root    /usr/sbin/in.ivyd  in.ivyd
+
+.SH LAUNCHING MANUALLY OR AT BOOT TIME
+
+To launch
+.B in.ivyd
+manually or at boot time, you must launch it with the flag
+.I \-boot.
+
+Launch at boot time is the default option in the Linux packages, which come with 
+the appropriate command file to add to the boot sequence.
+
+.SH SEE ALSO
+.PP
+ivyd(1),
+ivyecho(1),
+Ivy(1)
diff --git a/doc/ivyd.1 b/doc/ivyd.1
index 6808c53..cf611d9 100644
--- a/doc/ivyd.1
+++ b/doc/ivyd.1
@@ -6,7 +6,7 @@
 .\"
 .\"	man page for ivyd
 .\"
-.\"	Author(s): Stephane Chatty <chatty@cenatoulouse.dgac.fr>
+.\"	Author(s): Stephane Chatty <chatty@cena.dgac.fr>
 .\"
 .\"	$Id$
 .\"
@@ -15,40 +15,97 @@
 
 
 
-.TH IVYD 1 "17 Feb 1999"
+.TH IVYD 1 "11 Nov 1999"
 .ds )H CENA, France.
 .ds ]W V1.0
 .UC 4
 .SH NAME
-ivyd - daemon to relay messages to an Ivy bus.
+ivyd - the Ivy daemon that relays messages to an Ivy bus.
 .SH SYNOPSIS
-.B "ivyd [-d] [-b [network[,network]][:port]]"
+.B "ivyd [-d] [-b bus]"
 .SH DESCRIPTION
 .B ivyd
-is an Ivy agent which binds to a port and awaits requests from
+is an Ivy agent which binds to a socket and awaits requests from
 clients.  Upon receiving a request, it reemits its contents as a message
-on the Ivy bus. The port is chosen dynamically, and registered by sending an UDP 
-message to the
-.B in.ivyd
-daemon.
-
+on the Ivy bus it belongs to. 
 .B ivyd
 is especially useful for short-lived applications that wish to send
-messages on an Ivy bus but cannot stay connected to a bus long enough.
+messages on an Ivy bus but cannot stay connected to a bus long enough,
+such as a shell script. Many other applications will want to connect directly
+to a bus rather than using
+.B ivyd,
+however.
+
 .SH OPTIONS
 .RS
 .TP 6
 .B -d
-Prints debug messages, and do not fork from the calling shell.
+Print debug messages, and do not fork from the calling shell.
 .TP
-.B -b [network[,network]][:port]
-Connects to and reemits messages on the Ivy bus defined by the broadcast address
+.B -b bus
+Connect to and reemit messages on the Ivy bus defined by the address
+.I bus.
+The syntax of bus addresses is
+.I [network[,network]][:port],
+where
 .I port
-and/or the set of networks
-.I network[,network].
-The default port is 2010, and the default network is 127, ie loopback.
+is the UDP port used to broadcast information on the Ivy bus, and
+.I network[,network]
+is a set of network addresses on which information is
+broadcast. Examples of bus adresses are 192.75:2000, :2001 or 192.75,192.76.
+The default port is
+.I 2010,
+and the default network is
+.I 127,
+ie. loopback on the
+local host.
+
+.SH EXAMPLE
+.LP
+This example launches an ivyd relay to the bus :2010 (port 2010 on local host)
+then relays two messages to the bus.
+.IP
+.B ivyd \-b
+.I :2010
+
+.B ivyecho \-b
+.I :2010
+.I This is message 1
+
+.B ivyecho \-b
+.I :2010
+.I And this is message 2
+
+.SH CLIENT-SERVER ISSUES
+The communication port with clients is chosen dynamically, and registered by
+sending an UDP message to the
+.B in.ivyd
+super-daemon. Clients such as
+.B ivyecho
+obtain the address by sending a request to the super-daemon.
+.B in.ivyd
+is often launched at boot time, this is the default behaviour with
+Linux packages of ivyd.
+
+
+.SH LIMITATIONS
+The mapping between clients and multiple
+.B ivyd
+servers is ensured through the port number in the bus address: in the example
+above, the
+.B ivyecho
+client is directed by
+.B in.ivyd
+to the server that was launched just before because it refers to the bus port
+.I 2010.
+This means that only one Ivy daemon can run on a given bus.
+
+Another limitation: no server is automatically launched if a client tries to get
+a message relayed to a bus for which there is no relay server. You must launch
+your servers beforehand.
+
 .SH SEE ALSO
 .PP
-in.ivyd(1),
+in.ivyd(8),
 ivyecho(1),
 Ivy(1)
diff --git a/doc/ivyecho.1 b/doc/ivyecho.1
index 32a55bc..1956cb2 100644
--- a/doc/ivyecho.1
+++ b/doc/ivyecho.1
@@ -15,33 +15,75 @@
 
 
 
-.TH IVYECHO 1 "17 Feb 1999"
+.TH IVYECHO 1 "11 Nov 1999"
 .ds )H CENA, France.
 .ds ]W V1.0
 .UC 4
 .SH NAME
-ivyecho - client of ivyd, Ivy equivalent of 'echo'
+ivyecho - client of the Ivy daemon: the Ivy equivalent of 'echo'
 .SH SYNOPSIS
-.B "ivyecho [-s serverhost] text"
+.B "ivyecho [-b bus] [-d] [-s serverhost] text"
 .SH DESCRIPTION
 .B ivyecho
 emits
 .I text
-on an Ivy bus. It first sends a request to the
+on an Ivy bus.
+
+This works as follows:
+.B ivyecho
+first sends a request to the
 .B in.ivyd
-daemon to determine on which port to contact
-.B ivyd.
+daemon to determine on which port to contact the appropriate
+.B ivyd
+relay server.
 It then sends a request to
 .B ivyd,
 that relays
 .I text
-to the Ivy bus.
+to the Ivy bus. This only works if the appropriate
+.B ivyd
+server is running.
+
 .SH OPTIONS
 .RS
+
 .TP 6
+.B -b bus
+Get message relayed to the Ivy bus defined by the address
+.I bus.
+The syntax of bus addresses is
+.I [network[,network]][:port],
+where
+.I port
+is the UDP port used to broadcast information on the Ivy bus, and
+.I network[,network]
+is a set of network addresses on which information is
+broadcast. Examples of bus adresses are 192.75:2000, :2001 or 192.75,192.76.
+The default port is
+.I 2010,
+and the default network is
+.I 127,
+ie. loopback on the
+local host.
+.I port
+is used to determine which
+.B ivyd
+server to use.
+
+.TP
+.B -d
+print debug information.
+
+
 .TP
 .B -s serverhost
-Determines the host on which to contact in.ivyd and ivyd.
+Use
+.I serverhost
+as the host on which to contact
+.B in.ivyd
+and
+.B ivyd.
+
 .SH SEE ALSO
 .PP
 in.ivyd(1),