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