chiark / gitweb /
mon/tripemon.in: Support the new-style bindings for Gtk and friends.
[tripe] / svc / tripe-service.7.in
CommitLineData
2aff5dbb
MW
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.
35tripe-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.
56The
57.BR tripe (8)
58server allows external programs to provide useful services through its
59administration interface, as described in
60.BR tripe-admin (5).
61This manual page describes standard conventions for such service
62providers.
63.PP
64Service providers are programs; they are usually invoked automatically
65by
66.BR tripe 's
67startup script.
68.SS "Command line"
69Service providers may accept non-option command-line arguments, but it
70should always be possible to start the provider without any.
71.PP
72All service providers recognize the following options.
73.TP
74.B "\-h, \-\-help"
75Print a help message describing the service provider's command line
76usage and suchlike to standard output, and exit with status 0.
77.TP
78.B "\-\-version"
79Print the service provider's version number to standard output, and exit
80with status 0.
81.TP
82.BI "\-a, \-\-admin-socket=" socket
83Connect to the named administration
84.IR socket .
85The default socket is given by the environment variable
86.BR TRIPESOCK ;
87if that's not defined either, a default default of
88.B $socketdir/tripesock
89is used.
90.TP
91.BI "\-d, \-\-directory=" dir
92Make
93.I dir
94the current directory, before doing anything else. Note that all the
95other filenames (e.g., the log output file) are relative to this
96directory. The default directory, if this option is not specified, is
97taken from the environment variable
98.BR TRIPEDIR ;
99if that's not defined either, a default default of
100.B $configdir
101is used.
102.TP
103.B "\-\-daemon"
104Run the service provider in the background, as a daemon, after starting
105up.
106.TP
107.B "\-\-startup"
108Inform the service provider that it is being run as part of
109.BR tripe 's
110startup process, and that it should therefore do any special things
111which are appropriate.
112.PP
113The values of
114.B $socketdir
115and
116.B $configdir
117can be obtained from
118.BR pkg-config (1),
119e.g.,
120.VS
121pkg-config --variable=socketdir tripe
122.VE
123.SS "Documentation"
124Manual pages for
125.B tripe
126services are in section 7 of the manual, for want of somewhere better to
127put them. The manual pages are divided into sections, as usual:
128.TP
129.B NAME
130The name of the service provider, and any services it provides, with a
131one-line description.
132.TP
133.B SYNOPSIS
134A very brief summary of the command-line syntax of the service provider,
135a blank line, and one-line summaries of the commands provided by each
136service.
137.TP
138.B DESCRIPTION
139A general description of the service(s) provided, and any unusual
140command-line options recognized by the service provider, followed by a
141description of the commands provided by each service.
142.SS "Commands"
143All services must provide the following simple commands (available by
144sending
145.IP
146.B SVCSUBMIT
147.I service
148.I command
149.IR args ...
150.PP
151to the server).
152.TP
153.B HELP
154Write an
155.B INFO
156line for each command recognized by the service, in the format used by
157the
158.B tripe
159.B HELP
160command.
161.TP
162.B QUIT
163Send 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
174command) 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.
185Mark Wooding, <mdw@distorted.org.uk>
186.
187.\"----- That's all, folks --------------------------------------------------