From 2aff5dbb7d9458dc30136e264b921a0c8c520c41 Mon Sep 17 00:00:00 2001 Message-Id: <2aff5dbb7d9458dc30136e264b921a0c8c520c41.1714053369.git.mdw@distorted.org.uk> From: Mark Wooding Date: Mon, 19 Apr 2010 21:11:04 +0100 Subject: [PATCH] doc/tripe-service.5: New manpage describing service providers. Organization: Straylight/Edgeware From: Mark Wooding General command-line and documentation conventions, that sort of thing. --- Makefile.am | 5 ++ configure.ac | 1 + debian/tripe.install | 1 + svc/Makefile.am | 38 +++++++++ svc/tripe-service.7.in | 187 +++++++++++++++++++++++++++++++++++++++++ 5 files changed, 232 insertions(+) create mode 100644 svc/Makefile.am create mode 100644 svc/tripe-service.7.in diff --git a/Makefile.am b/Makefile.am index a36afeb8..d4af1ef4 100644 --- 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 a8723c25..2d70b948 100644 --- 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 7df89238..54165e82 100644 --- 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 index 00000000..f37ecb17 --- /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 index 00000000..56d9670d --- /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, +. +.\"----- That's all, folks -------------------------------------------------- -- [mdw]