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