chiark - git - mdw - tripe/blob - svc/tripe-service.7.in

   1 .\" -*-nroff-*-
   2 .\".
   3 .\" Manual for TrIPE services
   4 .\"
   5 .\" (c) 2008 Straylight/Edgeware
   6 .\"
   7 .
   8 .\"----- Licensing notice ---------------------------------------------------
   9 .\"
  10 .\" This file is part of Trivial IP Encryption (TrIPE).
  11 .\"
  12 .\" TrIPE is free software; you can redistribute it and/or modify
  13 .\" it under the terms of the GNU General Public License as published by
  14 .\" the Free Software Foundation; either version 2 of the License, or
  15 .\" (at your option) any later version.
  16 .\"
  17 .\" TrIPE is distributed in the hope that it will be useful,
  18 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  19 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20 .\" GNU General Public License for more details.
  21 .\"
  22 .\" You should have received a copy of the GNU General Public License
  23 .\" along with TrIPE; if not, write to the Free Software Foundation,
  24 .\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  25 .
  26 .\"--------------------------------------------------------------------------
  27 .so ../defs.man.in \"@@@PRE@@@
  28 .
  29 .\"--------------------------------------------------------------------------
  30 .TH tripe-service 7 "8 January 2007" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
  31 .
  32 .\"--------------------------------------------------------------------------
  33 .SH "NAME"
  34 .
  35 tripe-service \- common information about tripe service providers
  36 .
  37 .\"--------------------------------------------------------------------------
  38 .SH "SYNOPSIS"
  39 .
  40 .I program
  41 .RB [ \-a
  42 .IR socket ]
  43 .RB [ \-d
  44 .IR dir ]
  45 .RB [ \-\-daemon ]
  46 .RB [ \-\-startup ]
  47 .PP
  48 .nf
  49 .B HELP
  50 .B QUIT
  51 .fi
  52 .
  53 .\"--------------------------------------------------------------------------
  54 .SH "DESCRIPTION"
  55 .
  56 The
  57 .BR tripe (8)
  58 server allows external programs to provide useful services through its
  59 administration interface, as described in
  60 .BR tripe-admin (5).
  61 This manual page describes standard conventions for such service
  62 providers.
  63 .PP
  64 Service providers are programs; they are usually invoked automatically
  65 by
  66 .BR tripe 's
  67 startup script.
  68 .SS "Command line"
  69 Service providers may accept non-option command-line arguments, but it
  70 should always be possible to start the provider without any.
  71 .PP
  72 All service providers recognize the following options.
  73 .TP
  74 .B "\-h, \-\-help"
  75 Print a help message describing the service provider's command line
  76 usage and suchlike to standard output, and exit with status 0.
  77 .TP
  78 .B "\-\-version"
  79 Print the service provider's version number to standard output, and exit
  80 with status 0.
  81 .TP
  82 .BI "\-a, \-\-admin-socket=" socket
  83 Connect to the named administration
  84 .IR socket .
  85 The default socket is given by the environment variable
  86 .BR TRIPESOCK ;
  87 if that's not defined either, a default default of
  88 .B $socketdir/tripesock
  89 is used.
  90 .TP
  91 .BI "\-d, \-\-directory=" dir
  92 Make
  93 .I dir
  94 the current directory, before doing anything else.  Note that all the
  95 other filenames (e.g., the log output file) are relative to this
  96 directory.  The default directory, if this option is not specified, is
  97 taken from the environment variable
  98 .BR TRIPEDIR ;
  99 if that's not defined either, a default default of
 100 .B $configdir
 101 is used.
 102 .TP
 103 .B "\-\-daemon"
 104 Run the service provider in the background, as a daemon, after starting
 105 up.
 106 .TP
 107 .B "\-\-startup"
 108 Inform the service provider that it is being run as part of
 109 .BR tripe 's
 110 startup process, and that it should therefore do any special things
 111 which are appropriate.
 112 .PP
 113 The values of
 114 .B $socketdir
 115 and
 116 .B $configdir
 117 can be obtained from
 118 .BR pkg-config (1),
 119 e.g.,
 120 .VS
 121 pkg-config --variable=socketdir tripe
 122 .VE
 123 .SS "Documentation"
 124 Manual pages for
 125 .B tripe
 126 services are in section 7 of the manual, for want of somewhere better to
 127 put them.  The manual pages are divided into sections, as usual:
 128 .TP
 129 .B NAME
 130 The name of the service provider, and any services it provides, with a
 131 one-line description.
 132 .TP
 133 .B SYNOPSIS
 134 A very brief summary of the command-line syntax of the service provider,
 135 a blank line, and one-line summaries of the commands provided by each
 136 service.
 137 .TP
 138 .B DESCRIPTION
 139 A general description of the service(s) provided, and any unusual
 140 command-line options recognized by the service provider, followed by a
 141 description of the commands provided by each service.
 142 .SS "Commands"
 143 All services must provide the following simple commands (available by
 144 sending
 145 .IP
 146 .B SVCSUBMIT
 147 .I service
 148 .I command
 149 .IR args ...
 150 .PP
 151 to the server).
 152 .TP
 153 .B HELP
 154 Write an
 155 .B INFO
 156 line for each command recognized by the service, in the format used by
 157 the
 158 .B tripe
 159 .B HELP
 160 command.
 161 .TP
 162 .B QUIT
 163 Send a warning of the form
 164 .RS
 165 .IP
 166 .B WARN
 167 .B USER
 168 .I service
 169 .B svc-quit
 170 .B user-request
 171 .PP
 172 (using the
 173 .B WARN
 174 command) and terminate the service-provider program.
 175 .
 176 .\"--------------------------------------------------------------------------
 177 .SH "SEE ALSO"
 178 .
 179 .BR tripe (8),
 180 .BR tripe\-admin (5).
 181 .
 182 .\"--------------------------------------------------------------------------
 183 .SH "AUTHOR"
 184 .
 185 Mark Wooding, <mdw@distorted.org.uk>
 186 .
 187 .\"----- That's all, folks --------------------------------------------------