Merge branch 'mdw/svc-merge'

[tripe] / svc / tripe-service.7.in

.\" -*-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 --------------------------------------------------