Commit | Line | Data |
---|---|---|
d6623498 | 1 | .\" -*-nroff-*- |
fc916a09 MW |
2 | .\". |
3 | .\" Manual for the administration client | |
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 | .\"-------------------------------------------------------------------------- | |
e99aedcf | 27 | .so ../common/defs.man \" @@@PRE@@@ |
fc916a09 MW |
28 | . |
29 | .\"-------------------------------------------------------------------------- | |
d6623498 | 30 | .TH tripectl 1 "19 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption" |
fc916a09 MW |
31 | . |
32 | .\"-------------------------------------------------------------------------- | |
33 | .SH "NAME" | |
34 | . | |
d6623498 | 35 | tripectl \- simple client for TrIPE |
fc916a09 MW |
36 | . |
37 | .\"-------------------------------------------------------------------------- | |
38 | .SH "SYNOPSIS" | |
39 | . | |
d6623498 | 40 | .B tripectl |
41 | .RB [ \-w ] | |
42 | .RB [ \-\fIoptions ] | |
43 | .RI [ command | |
44 | .RI [ args ]...] | |
45 | .br | |
46 | .B tripectl | |
ae8928d2 | 47 | .RB [ \-Dlt ] |
d6623498 | 48 | .RB [ \-f |
49 | .IR file ] | |
50 | .RB [ \-\fIoptions ] | |
51 | .PP | |
52 | Options: | |
53 | .br | |
54 | \& | |
55 | .RB [ \-s ] | |
56 | .RB [ \-d | |
87154d69 | 57 | .IR dir ] |
d6623498 | 58 | .RB [ \-a |
59 | .IR socket ] | |
87154d69 | 60 | .RB [ \-P |
61 | .IR pidfile ] | |
d6623498 | 62 | .br |
63 | \& | |
64 | .RB [ \-p | |
46dde080 | 65 | .IR path ] |
ab46a787 MW |
66 | .RB [ \-U |
67 | .IR user ] | |
68 | .RB [ \-G | |
69 | .IR group ] | |
d6623498 | 70 | .RB [ \-S |
71 | .IB arg , arg ,\fR...] | |
fc916a09 MW |
72 | . |
73 | .\"-------------------------------------------------------------------------- | |
74 | .SH "DESCRIPTION" | |
75 | . | |
87154d69 | 76 | The |
77 | .B tripectl | |
1a19f865 | 78 | program is a simple client which can be used, either interactively or |
79 | from a script, to send commands to and read status information from a | |
80 | running | |
87154d69 | 81 | .BR tripe (8) |
82 | server. It can also be used to start | |
83 | .BR tripe (8), | |
84 | passing appropriate arguments and capturing logging information. | |
85 | .SS "Command-line options" | |
86 | .TP | |
87 | .B "\-h, \-\-help" | |
88 | Writes a brief description of the command-line options available to | |
89 | standard output and exits with status 0. | |
90 | .TP | |
91 | .B "\-v, \-\-version" | |
92 | Writes tripe's version number to standard output and exits with status | |
93 | 0. | |
94 | .TP | |
95 | .B "\-u, \-\-usage" | |
96 | Writes a brief usage summary to standard output and exits with status 0. | |
97 | .TP | |
98 | .B "\-D, \-\-daemon" | |
99 | Makes | |
100 | .B tripectl | |
101 | disassociate from the terminal and become a background process after | |
102 | connecting to the server. | |
103 | .TP | |
104 | .BI "\-d, \-\-directory=" dir | |
105 | Make | |
106 | .I dir | |
107 | the current directory, before doing anything else. Note that all the | |
108 | other filenames (e.g., the log output file) are relative to this | |
109 | directory. The default directory, if this option is not specified, is | |
110 | taken from the environment variable | |
111 | .BR TRIPEDIR ; | |
112 | if that's not defined either, a default default of | |
f7b5d108 | 113 | .B "\*(/c" |
87154d69 | 114 | is used. |
115 | .TP | |
797cf76b | 116 | .BI "\-a, \-\-admin-socket=" socket |
87154d69 | 117 | If connecting to a running server, connect to the socket named |
7cf0f3cc | 118 | .IR socket ; |
119 | if running a new server, instruct it to listen for admin | |
87154d69 | 120 | connections on |
121 | .IR socket . | |
797cf76b MW |
122 | The default socket, if this option is not specified, is taken from the |
123 | environment variable | |
124 | .BR TRIPESOCK ; | |
125 | if that's not defined either, a default default of | |
f7b5d108 | 126 | .B "\*(/s/tripesock" |
797cf76b | 127 | is used. |
87154d69 | 128 | .TP |
129 | .BI "\-P, \-\-pidfile=" pidfile | |
130 | Write | |
131 | .BR tripectl 's | |
132 | process-id to | |
133 | .I pidfile | |
134 | (relative to | |
135 | .IR dir ). | |
136 | If the | |
137 | .B \-D | |
138 | and | |
139 | .B \-f | |
140 | options are given, a default of | |
141 | .IB dir /tripectl.pid | |
142 | is used if you don't give a | |
143 | .B \-P | |
144 | option. | |
145 | .TP | |
146 | .B "\-s, \-\-spawn" | |
147 | Start a new server: don't connect to an existing one. Starting a | |
148 | .BR tripe (8) | |
149 | server in this manner is a good way to ensure that no log messages are | |
150 | lost. The | |
151 | .BR \-l , | |
152 | .B \-f | |
153 | and | |
154 | .B \-D | |
155 | options are particularly useful in conjunction with | |
156 | .BR \-s . | |
157 | .TP | |
158 | .BI "\-p, \-\-spawn\-path=" path | |
159 | Implies | |
160 | .BR \-s ; | |
161 | runs the program named by | |
162 | .I path | |
163 | rather than the default | |
164 | .BR tripe . | |
165 | If | |
166 | .I path | |
167 | is actually an unqualified filename, the program to run is found using | |
168 | the | |
169 | .B PATH | |
170 | environment variable in the usual way. | |
171 | .TP | |
172 | .BI "\-S, \-\-spawn\-args=" arg , arg ,\fR... | |
173 | Implies | |
174 | .BR \-s ; | |
175 | passes the comma-separated | |
176 | .IR arg s | |
177 | to the | |
178 | .B tripe | |
179 | server on its command line. Arguments added using this option are added | |
180 | .I after | |
181 | any passed automatically by | |
182 | .B tripectl | |
e04c2d50 | 183 | (e.g., |
87154d69 | 184 | .BR \-a ). |
185 | .TP | |
ab46a787 MW |
186 | .BI "\-U, \-\-setuid=" user |
187 | Set uid to that of | |
188 | .I user | |
189 | (either a user name or integer uid) after initialization. Also set gid | |
190 | to | |
191 | .IR user 's | |
192 | primary group, unless overridden by a | |
193 | .B \-G | |
194 | option. If a new | |
195 | .BR tripe (8) | |
196 | server is going to be spawned then it is also passed corresponding | |
197 | .B \-U | |
198 | and | |
199 | .B \-G | |
200 | options. | |
201 | .TP | |
202 | .BI "\-G, \-\-setgid=" group | |
ec9b8aed MW |
203 | If the current effective uid is zero (i.e., the daemon was invoked as |
204 | .BR root ) | |
205 | then set gid to that of | |
ab46a787 MW |
206 | .I group |
207 | (either a group name or integer gid) after initialization. If a new | |
208 | .BR tripe (8) | |
209 | server is going to be spawned then it is also passed a corresponding | |
210 | .B \-G | |
211 | option. | |
212 | .TP | |
87154d69 | 213 | .B "\-l, \-\-syslog" |
214 | Send warnings and trace messages to the | |
215 | .BR syslog (8) | |
216 | service. Messages are logged using the | |
217 | .B daemon | |
218 | facility. Warnings are logged with severity | |
219 | .BR warning ; | |
220 | trace messages are logged with severity | |
221 | .BR debug . | |
222 | .TP | |
223 | .BI "\-f, \-\-logfile=" file | |
224 | Write warnings and trace messages to | |
225 | .IR file . | |
ae8928d2 MW |
226 | The |
227 | .I file | |
228 | may be | |
229 | .RB ` \- ' | |
230 | to request output to stdout, or | |
231 | .RB ` ! ' | |
232 | to request output to stderr. If a proper filename is given (rather than | |
233 | one of these special tokens), then on receipt of a | |
87154d69 | 234 | .B SIGHUP |
235 | signal, | |
236 | .B tripectl | |
ae8928d2 MW |
237 | will close its log file and reopen a new one with the same name; this is |
238 | useful when you rotate logs. | |
239 | .TP | |
240 | .B "\-t, \-\-no-timestamp" | |
241 | When logging to a file (with | |
242 | .BR \-f ), | |
243 | don't prefix log items with a timestamp. This is useful when the log | |
244 | output is being captured by some process which will add its own | |
245 | timestamps anyway. | |
87154d69 | 246 | .TP |
247 | .B "\-w, \-\-warnings" | |
248 | Write warnings to standard error even when running noninteractively. | |
249 | .SS "Interactive use" | |
250 | With no arguments, | |
251 | .B tripectl | |
252 | will connect to a running server and await commands from its standard | |
253 | input. The commands are submitted to the server unchanged, and the | |
254 | results written to standard output. It will quit when it receives a | |
255 | fatal signal or an end-of-file indication from the server. | |
256 | .SS "Use from scripts" | |
257 | If arguments are given to | |
258 | .BR tripectl , | |
0ed0735f MW |
259 | they are quoted if necessary to protect spaces and other special |
260 | characters, concatenated with spaces between, and submitted to the | |
261 | server after connection. Any | |
87154d69 | 262 | .B INFO |
263 | responses returned by the server are written to standard output (without | |
264 | the | |
265 | .B INFO | |
266 | on the front). A | |
267 | .B FAIL | |
268 | response causes the error message to be written to standard error, and | |
269 | the client to exit with a nonzero return code. An | |
270 | .B OK | |
271 | response causes the client to exit with a zero return code. Unless the | |
272 | .B \-w | |
273 | command-line option was given, any | |
274 | .B WARN | |
275 | responses are discarded; if | |
276 | .B \-w | |
277 | .I was | |
278 | given, | |
279 | .B WARN | |
280 | responses are written to standard error. In all cases, | |
281 | .B TRACE | |
282 | responses are ignored. | |
283 | .SS "Starting the tripe server" | |
284 | If any of the options | |
285 | .BR \-s , | |
e04c2d50 | 286 | .B \-p |
87154d69 | 287 | or |
288 | .B \-S | |
289 | are given, | |
290 | .B tripectl | |
291 | will start a new | |
292 | .B tripe | |
46dde080 MW |
293 | server, rather than connecting to an existing one. |
294 | .PP | |
295 | The command line for the new server is | |
296 | .IP | |
297 | .I path | |
298 | .B \-F | |
299 | .B \-d.\& | |
300 | .B \-a | |
301 | .I socket | |
302 | .I dash-S-options | |
303 | .PP | |
304 | where | |
305 | .I dash-S-options | |
306 | is the concatenation of the arguments of | |
307 | .B \-S | |
308 | options, split at commas. | |
309 | .PP | |
310 | Starting a | |
311 | .B tripe | |
312 | server through | |
313 | .B tripectl | |
314 | is most useful if you want to collect logging information from the | |
315 | server, and want to avoid losing any. For example, the command | |
87154d69 | 316 | .VS |
317 | tripectl -Ds -f tripe.log | |
318 | .VE | |
319 | starts up a new server in the default directory, and captures all of its | |
320 | logging output (i.e., | |
321 | .B WARN | |
322 | and | |
323 | .B TRACE | |
324 | messages) in the file | |
325 | .BR tripe.log . | |
326 | It stores its process-id in | |
327 | .BR tripectl.pid . | |
328 | .PP | |
329 | It's possible to communicate interactively with a newly-started server, | |
330 | or to give it a command and quit, but this is seldom useful. | |
fc916a09 MW |
331 | . |
332 | .\"-------------------------------------------------------------------------- | |
87154d69 | 333 | .SH "SEE ALSO" |
fc916a09 | 334 | . |
87154d69 | 335 | .BR tripe\-admin (5), |
336 | .BR tripe (8). | |
337 | .PP | |
338 | .IR "The Trivial IP Encryption Protocol" , | |
339 | .IR "The Wrestlers Protocol" . | |
fc916a09 MW |
340 | . |
341 | .\"-------------------------------------------------------------------------- | |
87154d69 | 342 | .SH "AUTHOR" |
fc916a09 | 343 | . |
98fdb08d | 344 | Mark Wooding, <mdw@distorted.org.uk> |
fc916a09 MW |
345 | . |
346 | .\"----- That's all, folks -------------------------------------------------- |