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 | .\"-------------------------------------------------------------------------- | |
27 | .so ../defs.man.in \" @@@PRE@@@ | |
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 | |
47 | .RB [ \-Dl ] | |
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 | |
fc916a09 | 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 | |
fc916a09 | 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 | |
203 | Set gid to that of | |
204 | .I group | |
205 | (either a group name or integer gid) after initialization. If a new | |
206 | .BR tripe (8) | |
207 | server is going to be spawned then it is also passed a corresponding | |
208 | .B \-G | |
209 | option. | |
210 | .TP | |
87154d69 | 211 | .B "\-l, \-\-syslog" |
212 | Send warnings and trace messages to the | |
213 | .BR syslog (8) | |
214 | service. Messages are logged using the | |
215 | .B daemon | |
216 | facility. Warnings are logged with severity | |
217 | .BR warning ; | |
218 | trace messages are logged with severity | |
219 | .BR debug . | |
220 | .TP | |
221 | .BI "\-f, \-\-logfile=" file | |
222 | Write warnings and trace messages to | |
223 | .IR file . | |
224 | On receipt of a | |
225 | .B SIGHUP | |
226 | signal, | |
227 | .B tripectl | |
228 | will close its log file and reopen a new one with the same name. This | |
229 | is useful when you rotate logs. | |
230 | .TP | |
231 | .B "\-w, \-\-warnings" | |
232 | Write warnings to standard error even when running noninteractively. | |
233 | .SS "Interactive use" | |
234 | With no arguments, | |
235 | .B tripectl | |
236 | will connect to a running server and await commands from its standard | |
237 | input. The commands are submitted to the server unchanged, and the | |
238 | results written to standard output. It will quit when it receives a | |
239 | fatal signal or an end-of-file indication from the server. | |
240 | .SS "Use from scripts" | |
241 | If arguments are given to | |
242 | .BR tripectl , | |
0ed0735f MW |
243 | they are quoted if necessary to protect spaces and other special |
244 | characters, concatenated with spaces between, and submitted to the | |
245 | server after connection. Any | |
87154d69 | 246 | .B INFO |
247 | responses returned by the server are written to standard output (without | |
248 | the | |
249 | .B INFO | |
250 | on the front). A | |
251 | .B FAIL | |
252 | response causes the error message to be written to standard error, and | |
253 | the client to exit with a nonzero return code. An | |
254 | .B OK | |
255 | response causes the client to exit with a zero return code. Unless the | |
256 | .B \-w | |
257 | command-line option was given, any | |
258 | .B WARN | |
259 | responses are discarded; if | |
260 | .B \-w | |
261 | .I was | |
262 | given, | |
263 | .B WARN | |
264 | responses are written to standard error. In all cases, | |
265 | .B TRACE | |
266 | responses are ignored. | |
267 | .SS "Starting the tripe server" | |
268 | If any of the options | |
269 | .BR \-s , | |
e04c2d50 | 270 | .B \-p |
87154d69 | 271 | or |
272 | .B \-S | |
273 | are given, | |
274 | .B tripectl | |
275 | will start a new | |
276 | .B tripe | |
46dde080 MW |
277 | server, rather than connecting to an existing one. |
278 | .PP | |
279 | The command line for the new server is | |
280 | .IP | |
281 | .I path | |
282 | .B \-F | |
283 | .B \-d.\& | |
284 | .B \-a | |
285 | .I socket | |
286 | .I dash-S-options | |
287 | .PP | |
288 | where | |
289 | .I dash-S-options | |
290 | is the concatenation of the arguments of | |
291 | .B \-S | |
292 | options, split at commas. | |
293 | .PP | |
294 | Starting a | |
295 | .B tripe | |
296 | server through | |
297 | .B tripectl | |
298 | is most useful if you want to collect logging information from the | |
299 | server, and want to avoid losing any. For example, the command | |
87154d69 | 300 | .VS |
301 | tripectl -Ds -f tripe.log | |
302 | .VE | |
303 | starts up a new server in the default directory, and captures all of its | |
304 | logging output (i.e., | |
305 | .B WARN | |
306 | and | |
307 | .B TRACE | |
308 | messages) in the file | |
309 | .BR tripe.log . | |
310 | It stores its process-id in | |
311 | .BR tripectl.pid . | |
312 | .PP | |
313 | It's possible to communicate interactively with a newly-started server, | |
314 | or to give it a command and quit, but this is seldom useful. | |
fc916a09 MW |
315 | . |
316 | .\"-------------------------------------------------------------------------- | |
87154d69 | 317 | .SH "SEE ALSO" |
fc916a09 | 318 | . |
87154d69 | 319 | .BR tripe\-admin (5), |
320 | .BR tripe (8). | |
321 | .PP | |
322 | .IR "The Trivial IP Encryption Protocol" , | |
323 | .IR "The Wrestlers Protocol" . | |
fc916a09 MW |
324 | . |
325 | .\"-------------------------------------------------------------------------- | |
87154d69 | 326 | .SH "AUTHOR" |
fc916a09 | 327 | . |
98fdb08d | 328 | Mark Wooding, <mdw@distorted.org.uk> |
fc916a09 MW |
329 | . |
330 | .\"----- That's all, folks -------------------------------------------------- |