--- /dev/null
+.\" -*-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 7tripe "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 --------------------------------------------------
~mdw / tripe / blobdiff