doc/tripe-service.5: New manpage describing service providers.

General command-line and documentation conventions, that sort of thing.

diff --git a/Makefile.am b/Makefile.am
index a36afeb8f7370451aaa343e9888fc8a31b804caf..d4af1ef4b879c25d09ba3498fc5464c35fbd754c 100644 (file)
--- a/Makefile.am
+++ b/Makefile.am
@@ -50,6 +50,11 @@ if HAVE_WIRESHARK
 SUBDIRS                        += wireshark
 endif
 
+## Services.
+if HAVE_PYTHON
+SUBDIRS                        += svc
+endif
+
 ## Key-management.
 if HAVE_PYCATACOMB
 SUBDIRS                        += keys

diff --git a/configure.ac b/configure.ac
index a8723c2560ff8fe1f286f41cbabfe5785b8ea7e5..2d70b948b3e266d5ef6872c43abb0273de2d86cc 100644 (file)
--- a/configure.ac
+++ b/configure.ac
@@ -321,6 +321,7 @@ AC_CONFIG_FILES(
   [wireshark/Makefile]
   [init/Makefile]
   [keys/Makefile]
+  [svc/Makefile]
   [mon/Makefile]
   [t/Makefile t/atlocal])
 AC_OUTPUT

diff --git a/debian/tripe.install b/debian/tripe.install
index 7df892387a5104c25b9d890efd816c462a5f16d0..54165e82ba87ae261fdc26139b36635b91ac2cb1 100644 (file)
--- a/debian/tripe.install
+++ b/debian/tripe.install
@@ -2,6 +2,7 @@ debian/tmp/usr/bin/tripectl
 debian/tmp/usr/sbin/tripe
 debian/tmp/usr/share/man/man1/tripectl.1
 debian/tmp/usr/share/man/man5/tripe-admin.5
+debian/tmp/usr/share/man/man7/tripe-service.7
 debian/tmp/usr/share/man/man8/tripe.8
 debian/tmp/usr/lib/tripe/tripe-privhelper
 debian/tmp/usr/share/man/man8/tripe-privhelper.8

diff --git a/svc/Makefile.am b/svc/Makefile.am
new file mode 100644 (file)
index 0000000..f37ecb1
--- /dev/null
+++ b/svc/Makefile.am
@@ -0,0 +1,38 @@
+### -*-makefile-*-
+###
+### Makefile for TrIPE services
+###
+### (c) 2001 Straylight/Edgeware
+###
+
+###----- Licensing notice ---------------------------------------------------
+###
+### This file is part of Trivial IP Encryption (TrIPE).
+###
+### TrIPE is free software; you can redistribute it and/or modify
+### it under the terms of the GNU General Public License as published by
+### the Free Software Foundation; either version 2 of the License, or
+### (at your option) any later version.
+###
+### TrIPE is distributed in the hope that it will be useful,
+### but WITHOUT ANY WARRANTY; without even the implied warranty of
+### MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+### GNU General Public License for more details.
+###
+### You should have received a copy of the GNU General Public License
+### along with TrIPE; if not, write to the Free Software Foundation,
+### Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+
+include $(top_srcdir)/vars.am
+
+man_MANS                =
+
+###--------------------------------------------------------------------------
+### Services.
+
+## Services manual page.
+man_MANS               += tripe-service.7
+CLEANFILES             += tripe-service.7
+EXTRA_DIST             += tripe-service.7.in
+
+###----- That's all, folks --------------------------------------------------

diff --git a/svc/tripe-service.7.in b/svc/tripe-service.7.in
new file mode 100644 (file)
index 0000000..56d9670
--- /dev/null
+++ b/svc/tripe-service.7.in
@@ -0,0 +1,187 @@
+.\" -*-nroff-*-
+.\".
+.\" Manual for TrIPE services
+.\"
+.\" (c) 2008 Straylight/Edgeware
+.\"
+.
+.\"----- Licensing notice ---------------------------------------------------
+.\"
+.\" This file is part of Trivial IP Encryption (TrIPE).
+.\"
+.\" TrIPE is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 2 of the License, or
+.\" (at your option) any later version.
+.\"
+.\" TrIPE is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with TrIPE; if not, write to the Free Software Foundation,
+.\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+.
+.\"--------------------------------------------------------------------------
+.so ../defs.man.in \"@@@PRE@@@
+.
+.\"--------------------------------------------------------------------------
+.TH tripe-service 7 "8 January 2007" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
+.
+.\"--------------------------------------------------------------------------
+.SH "NAME"
+.
+tripe-service \- common information about tripe service providers
+.
+.\"--------------------------------------------------------------------------
+.SH "SYNOPSIS"
+.
+.I program
+.RB [ \-a
+.IR socket ]
+.RB [ \-d
+.IR dir ]
+.RB [ \-\-daemon ]
+.RB [ \-\-startup ]
+.PP
+.nf
+.B HELP
+.B QUIT
+.fi
+.
+.\"--------------------------------------------------------------------------
+.SH "DESCRIPTION"
+.
+The
+.BR tripe (8)
+server allows external programs to provide useful services through its
+administration interface, as described in
+.BR tripe-admin (5).
+This manual page describes standard conventions for such service
+providers.
+.PP
+Service providers are programs; they are usually invoked automatically
+by
+.BR tripe 's
+startup script.
+.SS "Command line"
+Service providers may accept non-option command-line arguments, but it
+should always be possible to start the provider without any.
+.PP
+All service providers recognize the following options.
+.TP
+.B "\-h, \-\-help"
+Print a help message describing the service provider's command line
+usage and suchlike to standard output, and exit with status 0.
+.TP
+.B "\-\-version"
+Print the service provider's version number to standard output, and exit
+with status 0.
+.TP
+.BI "\-a, \-\-admin-socket=" socket
+Connect to the named administration
+.IR socket .
+The default socket is given by the environment variable
+.BR TRIPESOCK ;
+if that's not defined either, a default default of
+.B $socketdir/tripesock
+is used.
+.TP
+.BI "\-d, \-\-directory=" dir
+Make
+.I dir
+the current directory, before doing anything else.  Note that all the
+other filenames (e.g., the log output file) are relative to this
+directory.  The default directory, if this option is not specified, is
+taken from the environment variable
+.BR TRIPEDIR ;
+if that's not defined either, a default default of
+.B $configdir
+is used.
+.TP
+.B "\-\-daemon"
+Run the service provider in the background, as a daemon, after starting
+up.
+.TP
+.B "\-\-startup"
+Inform the service provider that it is being run as part of
+.BR tripe 's
+startup process, and that it should therefore do any special things
+which are appropriate.
+.PP
+The values of
+.B $socketdir
+and
+.B $configdir
+can be obtained from
+.BR pkg-config (1),
+e.g.,
+.VS
+pkg-config --variable=socketdir tripe
+.VE
+.SS "Documentation"
+Manual pages for
+.B tripe
+services are in section 7 of the manual, for want of somewhere better to
+put them.  The manual pages are divided into sections, as usual:
+.TP
+.B NAME
+The name of the service provider, and any services it provides, with a
+one-line description.
+.TP
+.B SYNOPSIS
+A very brief summary of the command-line syntax of the service provider,
+a blank line, and one-line summaries of the commands provided by each
+service.
+.TP
+.B DESCRIPTION
+A general description of the service(s) provided, and any unusual
+command-line options recognized by the service provider, followed by a
+description of the commands provided by each service.
+.SS "Commands"
+All services must provide the following simple commands (available by
+sending
+.IP
+.B SVCSUBMIT
+.I service
+.I command
+.IR args ...
+.PP
+to the server).
+.TP
+.B HELP
+Write an
+.B INFO
+line for each command recognized by the service, in the format used by
+the
+.B tripe
+.B HELP
+command.
+.TP
+.B QUIT
+Send a warning of the form
+.RS
+.IP
+.B WARN
+.B USER
+.I service
+.B svc-quit
+.B user-request
+.PP
+(using the
+.B WARN
+command) and terminate the service-provider program.
+.
+.\"--------------------------------------------------------------------------
+.SH "SEE ALSO"
+.
+.BR tripe (8),
+.BR tripe\-admin (5).
+.
+.\"--------------------------------------------------------------------------
+.SH "AUTHOR"
+.
+Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------