Commit | Line | Data |
---|---|---|
a62f8e8a MW |
1 | .\" -*-nroff-*- |
2 | .\". | |
3 | .\" Manual for the connect service | |
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. | |
a62f8e8a | 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. | |
a62f8e8a 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/>. |
a62f8e8a MW |
24 | . |
25 | .\"-------------------------------------------------------------------------- | |
cd450424 | 26 | .so ../common/defs.man \"@@@PRE@@@ |
a62f8e8a MW |
27 | . |
28 | .\"-------------------------------------------------------------------------- | |
0647ba7c | 29 | .TH connect 8tripe "11 December 2007" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption" |
a62f8e8a MW |
30 | . |
31 | .\"-------------------------------------------------------------------------- | |
32 | .SH "NAME" | |
33 | . | |
d64ce4ae | 34 | connect \- tripe service to handle addition and removal of peers |
a62f8e8a MW |
35 | . |
36 | .\"-------------------------------------------------------------------------- | |
37 | .SH "SYNOPSIS" | |
38 | . | |
39 | .B connect | |
40 | .RB [ \-a | |
41 | .IR socket ] | |
42 | .RB [ \-d | |
43 | .IR dir ] | |
44 | .RB [ \-p | |
45 | .IR file ] | |
46 | .br | |
47 | \& \c | |
48 | .RB [ \-\-daemon ] | |
49 | .RB [ \-\-debug ] | |
50 | .RB [ \-\-startup ] | |
51 | . | |
52 | .\"-------------------------------------------------------------------------- | |
53 | .SH "DESCRIPTION" | |
54 | . | |
55 | The | |
56 | .B connect | |
d64ce4ae MW |
57 | service tracks associations with peers and performs various actions at |
58 | appropriate stages in the assocations' lifecycles. It also registers | |
59 | new peers with the | |
a62f8e8a | 60 | .BR tripe (8) |
d64ce4ae MW |
61 | server on demand. |
62 | .PP | |
63 | For example: | |
64 | .hP \*o | |
65 | When a peer is added, it arranges to configure the corresponding network | |
66 | interface correctly, and (if necessary) to initiate a dynamic | |
67 | connection. | |
68 | .hP \*o | |
69 | When a peer is removed, it arranges to bring down the network interface. | |
70 | .hP \*o | |
71 | While the peer is known, it | |
72 | .BR PING s | |
73 | it at regular intervals. If the peer fails to respond, it can be | |
74 | removed or reconnected. | |
a62f8e8a MW |
75 | .PP |
76 | A peer may participate | |
77 | .I actively | |
78 | or | |
79 | .I passively | |
80 | in a connection. A peer participating actively (an | |
81 | .IR "active peer" ) | |
82 | must already know its peer's connection details \(en its server's IP | |
83 | address and port. Active connection is suitable when the peer is a | |
84 | well-known server with stable details. | |
85 | .PP | |
86 | A server participating passively (a | |
87 | .IR "passive peer" ) | |
88 | waits to be contacted by its peer, and discovers the peer's IP address | |
89 | and port as a result of a simple protocol described below. Passive | |
90 | connection is suitable when the peer's IP address or port can vary over | |
91 | time \(en e.g., if its IP address is assigned dynamically by DHCP or | |
92 | PPP, or if it is hidden behind a NAT firewall. | |
93 | .PP | |
94 | If both peers are active, we say that they establish an | |
95 | .IR "static connection" ; | |
96 | if one is passive, we say that they establish a | |
97 | .IR "dynamic connection" . | |
98 | At least one of the peers must be active; it is not possible to | |
99 | establish a connection if both peers are passive. | |
100 | .SS "Command line" | |
101 | In addition to the standard options described in | |
102 | .BR tripe-service (7), | |
103 | the following command-line options are recognized. | |
104 | .TP | |
105 | .BI "\-p, \-\-peerdb=" file | |
106 | Use | |
107 | .I file | |
108 | as the (CDB format) peer database. In the absence of this option, the | |
109 | file named by the | |
110 | .B TRIPEPEERDB | |
111 | environment variable is used; if that's not set either, then the default | |
112 | default of | |
113 | .B peers.cdb | |
114 | in the current working directory is used instead. | |
d64ce4ae MW |
115 | . |
116 | .\"-------------------------------------------------------------------------- | |
117 | .SH "BEHAVIOUR" | |
118 | . | |
119 | .SS "Adoption" | |
120 | The | |
121 | .B connect | |
122 | service maintains a list of peers which it has adopted. A peer is | |
123 | .I eligible for adoption | |
124 | if it has a record in the peer database | |
125 | .BR peers.cdb (5) | |
126 | in which the | |
127 | .B watch | |
128 | key is assigned the value | |
129 | .BR t , | |
130 | .BR true , | |
131 | .BR y , | |
132 | .BR yes , | |
133 | or | |
134 | .BR on . | |
135 | .PP | |
136 | The service pings adopted peers periodically in order to ensure that | |
137 | they are alive, and takes appropriate action if no replies are received. | |
a62f8e8a | 138 | .PP |
d64ce4ae MW |
139 | A peer is said to be |
140 | .I adopted | |
141 | when it is added to this list, and | |
142 | .I disowned | |
143 | when it removed. | |
144 | . | |
145 | .SS "Configuring interfaces" | |
146 | The | |
147 | .B connect | |
148 | service configures network interfaces by invoking an | |
149 | .B ifup | |
150 | script. The script is invoked as | |
151 | .IP | |
152 | .I script | |
153 | .IR args ... | |
154 | .I peer | |
155 | .I ifname | |
156 | .IR addr ... | |
157 | .PP | |
158 | where the elements are as described below. | |
159 | .TP | |
160 | .IR script " and " args | |
161 | The peer's database record is retrieved; the value assigned to the | |
162 | .B ifup | |
163 | key is split into words (quoting is allowed; see | |
164 | .BR tripe-admin (5) | |
165 | for details). The first word is the | |
166 | .IR script ; | |
167 | subsequent words are gathered to form the | |
168 | .IR args . | |
169 | .TP | |
170 | .I peer | |
171 | The name of the peer. | |
172 | .TP | |
173 | .I ifname | |
174 | The name of the network interface associated with the peer, as returned | |
175 | by the | |
176 | .B IFNAME | |
177 | administration command (see | |
178 | .BR tripe-admin (5)). | |
179 | .TP | |
180 | .I addr | |
181 | The network address of the peer's TrIPE server, in the form output by | |
182 | the | |
183 | .B ADDR | |
184 | administration command (see | |
185 | .BR tripe-admin (5)). | |
186 | The first word of | |
187 | .I addr | |
188 | is therefore a network address family, e.g., | |
189 | .BR INET . | |
190 | .PP | |
191 | The | |
192 | .B connect | |
193 | service deconfigures interfaces by invoking an | |
194 | .B ifdown | |
195 | script, in a similar manner. The script is invoked as | |
196 | .IP | |
197 | .I script | |
198 | .IR args ... | |
199 | .I peer | |
200 | .PP | |
201 | where the elements are as above, except that | |
202 | .I script | |
203 | and | |
204 | .I args | |
205 | are formed by splitting the value associated with the peer record's | |
206 | .B ifdown | |
207 | key. | |
208 | .PP | |
209 | In both of the above cases, if the relevant key (either | |
210 | .B ifup | |
211 | or | |
212 | .BR ifdown ) | |
213 | is absent, no action is taken. | |
214 | .PP | |
215 | The key/value pairs in the peer's database record and the server's | |
216 | response to the | |
217 | .B ALGS | |
218 | administration command (see | |
219 | .BR tripe-admin (5)) | |
220 | are passed to the | |
221 | .B ifup | |
222 | and | |
223 | .B ifdown | |
224 | scripts as environment variables. The environment variable name | |
225 | corresponding to a key is determined as follows: | |
226 | .hP \*o | |
227 | Convert all letters to upper-case. | |
228 | .hP \*o Convert all sequences of one or more non-alphanumeric characters | |
229 | to an underscore | |
230 | .RB ` _ '. | |
231 | .hP \*o Prefix the resulting name by | |
232 | .RB ` P_ ' | |
233 | or | |
234 | .RB ` A_ ' | |
235 | depending on whether it came from the peer's database record or the | |
236 | .B ALGS | |
237 | output respectively. | |
238 | .PP | |
239 | For example, | |
240 | .B ifname | |
241 | becomes | |
242 | .BR P_IFNAME ; | |
243 | and | |
244 | .B cipher-blksz | |
245 | becomes | |
246 | .BR A_CIPHER_BLKSZ . | |
247 | . | |
248 | .SS "Dynamic connection" | |
8362ac1c MW |
249 | The |
250 | .B connect | |
251 | service supports two kinds of dynamic connection. | |
252 | .PP | |
253 | The new kind of dynamic association uses the built-in | |
254 | .B knock | |
255 | protocol. If the peer's database record assigns a value to the | |
256 | .B knock | |
257 | key, then the new connection protocol is used: this value is sent to the | |
258 | peer during key-exchange, which should (if the peer is properly | |
259 | configured) automatically establish the other end of the connection. | |
260 | The string should have the form | |
261 | .RI [ prefix\fB. ] tag , | |
262 | where the whole string names this host as it is known by the remote | |
263 | host, and the | |
264 | .I tag | |
265 | names this host's public key. The passive server receives this string, | |
266 | verifies that the sender has access to the claimed private key, and | |
267 | emits a | |
268 | .B KNOCK | |
269 | notification which | |
270 | .B connect | |
271 | notices, causing it to establish the passive peer. While the internals | |
272 | are somewhat complex, configuration is pretty easy. | |
273 | .PP | |
274 | The older kind of dynamic association is rather more complicated to set | |
275 | up, and involves running shell commands, and probably configuring SSH. | |
d64ce4ae MW |
276 | If a peer's database record assigns a value to the |
277 | .B connect | |
278 | key, then the | |
279 | .B connect | |
280 | service will attempt to establish a connection dynamically with the | |
281 | peer. The value of the | |
282 | .B connect | |
283 | key is invoked as a Bourne shell command, i.e., | |
284 | .IP | |
285 | .B /bin/sh \-c | |
286 | .I connect | |
287 | .PP | |
288 | is executed. The command is expected to contact the remote server and | |
289 | report, on standard output, a challenge string, typically by issuing | |
290 | a | |
291 | .B passive | |
292 | command to the instance of the | |
293 | .B connect | |
294 | service running on the peer. The | |
295 | .B connect | |
296 | service reads this challenge, and submits the command | |
297 | .IP | |
298 | .B GREET | |
299 | .I peer | |
300 | .I challenge | |
301 | .PP | |
302 | Typically, the | |
303 | .B connect | |
304 | command will issue a command such as | |
305 | .IP | |
306 | .B SVCSUBMIT connect passive | |
307 | .I our-name | |
308 | .PP | |
309 | where | |
310 | .I our-name | |
311 | is the remote peer's name for this host. | |
312 | .PP | |
313 | Similarly, if the database record has a | |
314 | .B disconnect | |
315 | entry, then | |
316 | .B connect | |
317 | will use this to give the peer explicit notification that its services | |
318 | are no longer needed. The value of the | |
319 | .B disconnect | |
320 | key is invoked as a Bourne shell command. This ought to result in a | |
321 | .B KILL | |
322 | command being issued to the peer's server. | |
323 | .PP | |
8362ac1c MW |
324 | In detail, the protocol for old-style dynamic connection works as |
325 | follows. | |
a62f8e8a MW |
326 | .hP 1. |
327 | The active peer | |
328 | .BR ADD s | |
329 | its partner, typically using the | |
330 | .B \-cork | |
331 | option to suppress the key-exchange message which the server usually | |
332 | sends immediately, since otherwise the passive peer will warn about it. | |
333 | .hP 2. | |
d64ce4ae | 334 | The active peer issues the command |
a62f8e8a MW |
335 | .RS |
336 | .IP | |
337 | .B SVCSUBMIT connect passive | |
338 | .I user | |
339 | .PP | |
340 | to the passive peer's server. (Here, | |
341 | .I user | |
d64ce4ae MW |
342 | is a name identifying the active peer; see below.) Doing this is the |
343 | responsibility of the | |
344 | .B connect | |
345 | command. | |
a62f8e8a MW |
346 | .RE |
347 | .hP 3. | |
348 | The | |
349 | .B connect | |
350 | service on the passive peer responds with a | |
351 | .I challenge | |
352 | \(en a short Base64-encoded string. Somehow this challenge is sent back | |
353 | to the passive peer without being intercepted. | |
354 | .hP 4. | |
355 | The active peer sends a | |
356 | .BR GREET ing | |
357 | containing the challenge to its passive partner. The passive server | |
358 | announces the arrival of this message, and the originating address and | |
359 | port. | |
360 | .hP 5. | |
361 | The | |
362 | .B connect | |
363 | service running on the passive host receives the notification, matches | |
364 | it up with the | |
365 | .I user | |
366 | from the initial connection request, and | |
367 | .BR ADD s | |
368 | the appropriate peer, with the address from the | |
369 | .BR GREET ing. | |
d64ce4ae MW |
370 | . |
371 | .SS "Operation" | |
372 | On startup, | |
373 | .B connect | |
374 | requests a list of current peers from the | |
375 | .BR tripe (8) | |
376 | server, and adopts any eligible peers. If the | |
377 | .B \-\-startup | |
378 | flag was passed on the command line, the newly adopted peers have their | |
379 | interfaces configured and connection attempts are made. | |
a62f8e8a | 380 | .PP |
d64ce4ae MW |
381 | Adopted peers are pinged at regular intervals (using the |
382 | .B PING | |
383 | administrative command; see | |
384 | .BR tripe-admin (5)). | |
385 | This process can be configured by assigning values to keys in the peer's | |
386 | database record. Some of these parameters are time intervals, | |
387 | expressed as a nonnegative integer followed optionally by | |
388 | .BR d , | |
389 | .BR h , | |
390 | .BR m , | |
391 | or | |
392 | .B s | |
393 | for days, hours, minutes, or seconds, respectively; if no suffix is | |
394 | given, seconds are assumed. | |
395 | .PP | |
396 | The parameters are as follows. | |
397 | .TP | |
398 | .B every | |
399 | A time interval: how often to ping the peer to ensure that it's still | |
02c99524 MW |
400 | alive. The default is 30 seconds for active dynamic peers, and 5 |
401 | minutes for passive peers. | |
402 | .IP | |
403 | The period for dynamic peers should be no longer than | |
404 | .I timeout | |
405 | \(mu | |
406 | .RI ( retries | |
407 | \- 1). Consider an idle mobile peer which has its IP address changed | |
408 | just before its passive peer begins pinging. The static peer's pings | |
409 | will go to the old address until it receives a ping back from the mobile | |
410 | peer. Therefore, the static peer has to keep pinging until it would | |
411 | definitely have received an unsolicited ping from the mobile peer, and | |
412 | therefore be informed of the change of address. And it's no use | |
413 | learning about the change of address just after sending the last ping to | |
414 | the old address, so the last retry doesn't count for the purposes of | |
415 | this calculation. | |
416 | .IP | |
417 | Besides, the consequences of failed pinging differ between dynamic and | |
418 | passive peers. In the former case, a failure provokes a reconnection | |
419 | attempt, after which (hopefully) things will work again: it's probably a | |
420 | good thing to check frequently and fail fast. In the latter case, the | |
421 | dynamic peer will certainly have to notice that it's been abandoned and | |
422 | arrange to retry, causing a communication failure where maybe there | |
423 | wasn't really one before. | |
d64ce4ae MW |
424 | .TP |
425 | .B timeout | |
426 | A time interval: how long to wait for a reply before retrying or giving | |
427 | up. The default is 10 seconds. | |
428 | .TP | |
429 | .B retries | |
430 | An integer: how many failed attempts to make before deciding that the | |
431 | peer is unreachable and taking action. The default is 5 attempts. | |
432 | .PP | |
433 | The algorithm is as follows. Send up to | |
434 | .I retries | |
435 | pings; if a reply is received before the | |
436 | .I timeout | |
437 | then the peer is alive; wait | |
438 | .I every | |
439 | and check again. If no reply is received within the | |
440 | .IR timeout , | |
441 | then try again up to | |
442 | .I retries | |
443 | times. If no attempt succeeds, the peer is declared unreachable. If | |
444 | the peer has a | |
445 | .B connect | |
446 | command (i.e., it connects dynamically) then another connection attempt | |
447 | is made. Otherwise the peer is killed. | |
a62f8e8a MW |
448 | . |
449 | .\"-------------------------------------------------------------------------- | |
450 | .SH "SERVICE COMMAND REFERENCE" | |
451 | . | |
452 | .\"* 10 Service commands | |
453 | The commands provided by the service are as follows. | |
454 | .SP | |
455 | .BI "active " peer | |
456 | Make an active connection to the named | |
457 | .IR peer . | |
458 | The service will submit the command | |
459 | .RS | |
460 | .IP | |
461 | .B ADD | |
462 | .RB [ \-cork ] | |
463 | .RB [ \-keepalive | |
464 | .IR time ] | |
48b84569 MW |
465 | .RB [ \-key |
466 | .IR tag ] | |
d64ce4ae MW |
467 | .RB [ \-priv |
468 | .IR tag ] | |
6411163d | 469 | .RB [ \-mobile ] |
067aa5f0 | 470 | .RB [ \-ephemeral ] |
a62f8e8a MW |
471 | .RB [ \-tunnel |
472 | .IR driver ] | |
473 | .I address | |
474 | .PP | |
475 | Specifically: | |
476 | .hP \*o | |
477 | The option | |
478 | .B \-cork | |
479 | is provided if the peer's database record assigns the | |
480 | .B cork | |
481 | key one of the values | |
482 | .BR t , | |
483 | .BR true , | |
484 | .BR y , | |
485 | .BR yes, | |
486 | or | |
487 | .BR on . | |
488 | .hP \*o | |
489 | The option | |
490 | .B \-keepalive | |
491 | .I time | |
492 | is provided if the database record assigns a value | |
493 | .I time | |
494 | to the | |
495 | .B keepalive | |
496 | key. | |
497 | .hP \*o | |
498 | The option | |
48b84569 MW |
499 | .B \-key |
500 | .I tag | |
501 | is provided if the database record assigns a value | |
502 | .I tag | |
503 | to the | |
504 | .B key | |
505 | key. | |
506 | .hP \*o | |
507 | The option | |
d64ce4ae MW |
508 | .B \-priv |
509 | .I tag | |
510 | is provided if the database record assigns a value | |
511 | .I tag | |
512 | to the | |
513 | .B priv | |
514 | key. | |
515 | .hP \*o | |
516 | The option | |
6411163d MW |
517 | .B \-mobile |
518 | is provided if the peer's database record assigns the | |
519 | .B mobile | |
520 | key one of the values | |
521 | .BR t , | |
522 | .BR true , | |
523 | .BR y , | |
524 | .BR yes, | |
525 | or | |
526 | .BR on . | |
527 | .hP \*o | |
528 | The option | |
a62f8e8a MW |
529 | .B \-tunnel |
530 | .I driver | |
531 | is provided if the database record assigns a value | |
532 | .I driver | |
533 | to the | |
534 | .B tunnel | |
535 | key. | |
536 | .hP \*o | |
067aa5f0 MW |
537 | The option |
538 | .B \-ephemeral | |
539 | is provided if the peer's database record assigns the | |
540 | .B ephemeral | |
541 | key one of the values | |
542 | .BR t , | |
543 | .BR true , | |
544 | .BR y , | |
545 | .BR yes, | |
546 | or | |
547 | .BR on ; | |
548 | or if it is absent. | |
549 | .hP \*o | |
a62f8e8a MW |
550 | The |
551 | .I address | |
552 | is the value assigned to the | |
553 | .B peer | |
554 | key in the database record. | |
555 | .RE | |
556 | .SP | |
d64ce4ae MW |
557 | .B adopted |
558 | For each peer being tracked by the | |
559 | .B connect | |
560 | service, write a line | |
561 | .B INFO | |
562 | .IR name . | |
563 | (Compatibility note: it's possible that further information will be | |
564 | provided about each peer, in the form of subsequent tokens. Clients | |
565 | should be prepared to ignore such tokens.) | |
566 | .SP | |
a62f8e8a | 567 | .BI "info " peer |
b9dedfa6 | 568 | Lists the database record and additional information about the named |
a62f8e8a MW |
569 | .IR peer . |
570 | For each key/value pair, a line | |
571 | .RS | |
572 | .IP | |
573 | .B INFO | |
574 | .IB key = value | |
575 | .PP | |
576 | is output. The key/value pairs are output in an arbitrary order. | |
b9dedfa6 MW |
577 | .PP |
578 | In addition to the fields of the peer's database record, the following | |
579 | additional keys are defined. | |
580 | .TP | |
581 | .B failures | |
582 | The number of failed pings in the current or most recent batch, in | |
583 | decimal. | |
584 | .TP | |
585 | .B last-ping | |
586 | The round-trip time of the most recent ping in milliseconds, in the form | |
587 | .IB nn.n ms\fR, | |
588 | or | |
589 | .B timeout | |
590 | if the most recent ping timed out, | |
591 | or | |
592 | .B \- | |
593 | if no pings have yet completed. | |
594 | .TP | |
595 | .B max-ping | |
596 | The maximum successful ping time so far in milliseconds, in the form | |
597 | .IB nn.n ms\fR, | |
598 | or | |
599 | .B \- | |
600 | if no pings have yet succeeded. | |
601 | .TP | |
602 | .B mean-ping | |
603 | The average successful ping time so far in milliseconds, in the form | |
604 | .IB nn.n ms\fR, | |
605 | or | |
606 | .B \- | |
607 | if no pings have yet succeeded. | |
608 | .TP | |
609 | .B min-ping | |
610 | The minimum successful ping time so far in milliseconds, in the form | |
611 | .IB nn.n ms\fR, | |
612 | or | |
613 | .B \- | |
614 | if no pings have yet succeeded. | |
615 | .TP | |
616 | .B n-lost | |
617 | The number of pings which have been declared timed out so far, in | |
618 | decimal. | |
619 | .TP | |
620 | .B n-ping | |
621 | The number of successful pings so far, in decimal. | |
622 | .TP | |
623 | .B sd-ping | |
624 | The standard deviation of ping times so far in milliseconds, in the form | |
625 | .IB nn.n ms\fR, | |
626 | or | |
627 | .B \- | |
628 | if no pings have yet succeeded. | |
629 | .TP | |
630 | .B state | |
631 | One of the strings: | |
632 | .B idle | |
633 | if the peer has responded to a ping recently, and we are waiting for the | |
634 | .B every | |
635 | delay before we try again; or | |
636 | .B check | |
637 | if we are currently waiting for a ping to return. | |
a62f8e8a | 638 | .RE |
d64ce4ae MW |
639 | .SP |
640 | .BI "kick " peer | |
641 | If | |
642 | .I peer | |
643 | is currently added, and its record in the peer database contains a | |
644 | .B connect | |
645 | key (see | |
646 | .BR peers.in ) | |
647 | then force a reconnection attempt. See | |
648 | .BR "Dynamic connection" . | |
649 | .SP | |
650 | .B "list-active" | |
a62f8e8a MW |
651 | Output a list of peers in the database. For each peer name |
652 | .IR peer , | |
653 | a line | |
654 | .RS | |
655 | .IP | |
656 | .B INFO | |
657 | .I peer | |
658 | .PP | |
659 | is output. | |
660 | .RE | |
661 | .SP | |
662 | .BI "passive \fR[" options "\fR]\fP " user | |
663 | If the database contains a user record mapping | |
664 | .I user | |
665 | to some | |
666 | .I peer | |
667 | then an | |
668 | .B INFO | |
669 | line is written containing a freshly chosen challenge string. If the | |
670 | server receives a | |
671 | .BR GREET ing | |
672 | message quoting this challenge within 30 seconds, the | |
673 | .B connect | |
674 | service will issue an | |
675 | .B ADD | |
676 | request for the peer, as for the | |
677 | .B active | |
678 | command, except that the origin of the | |
679 | .BR GREET ing | |
680 | packet is used as the peer's address. | |
681 | .RS | |
682 | .\"+opts | |
683 | .PP | |
684 | The following option is recognized. | |
685 | .TP | |
686 | .BI "\-timeout " time | |
687 | Wait for | |
688 | .I time | |
689 | instead of 30 seconds. The | |
690 | .I time | |
691 | is expressed as a non-negative integer followed by | |
692 | .BR d , | |
693 | .BR h , | |
694 | .BR m , | |
695 | or | |
696 | .B s | |
697 | for days, hours, minutes or seconds respectively; if no suffix is given, | |
698 | seconds are assumed. | |
699 | .\"-opts | |
700 | .RE | |
d3731285 | 701 | .SP |
965eb987 MW |
702 | .BI "sabotage " peer |
703 | Sabotage the | |
704 | .I peer | |
705 | so that | |
706 | .B connect | |
707 | thinks that it can't respond to pings. This will usually provoke a | |
708 | reconnection attempt. Use | |
709 | .B kick | |
710 | instead unless you're trying to test | |
711 | .BR connect . | |
712 | .SP | |
d3731285 MW |
713 | .BI "userpeer " user |
714 | Output a single | |
715 | .B INFO | |
716 | line identifying the peer corresponding to the | |
717 | .I user | |
718 | name. | |
a62f8e8a MW |
719 | . |
720 | .\"-------------------------------------------------------------------------- | |
d64ce4ae | 721 | .SH "NOTIFICATIONS" |
a62f8e8a | 722 | . |
d64ce4ae MW |
723 | .\"* 30 Notification broadcasts (NOTE codes) |
724 | All notifications issued by | |
725 | .B connect | |
726 | begin with the tokens | |
727 | .BR "USER connect" . | |
a62f8e8a | 728 | .SP |
d64ce4ae MW |
729 | .B "USER connect peerdb-update" |
730 | The peer database has changed. Other interested clients should reopen | |
731 | the database. | |
a62f8e8a | 732 | .SP |
d64ce4ae MW |
733 | .BI "USER connect ping-failed " peer " " error\fR... |
734 | An attempt to | |
735 | .B PING | |
736 | the named | |
a62f8e8a | 737 | .I peer |
d64ce4ae MW |
738 | failed; the server replied |
739 | .B FAIL | |
740 | .IR error ... | |
a62f8e8a | 741 | .SP |
d64ce4ae | 742 | .BI "USER connect " process\fR... " stdout " line |
a62f8e8a | 743 | The |
d64ce4ae MW |
744 | .I process |
745 | spawned by the | |
746 | .B connect | |
747 | service unexpectedly wrote | |
748 | .I line | |
749 | to its standard output. | |
a62f8e8a MW |
750 | . |
751 | .\"-------------------------------------------------------------------------- | |
752 | .SH "WARNINGS" | |
753 | . | |
754 | .\"* 40 Warning broadcasts (WARN codes) | |
755 | All warnings issued by | |
756 | .B connect | |
757 | begin with the tokens | |
758 | .BR "USER connect" . | |
759 | .SP | |
760 | .BI "USER connect auto-add-failed " name " " error\fR... | |
761 | The attempt to add the peer | |
762 | .I name | |
763 | automatically failed: the | |
764 | .B ADD | |
765 | command reported | |
766 | .B FAIL | |
767 | .IR error ... | |
d64ce4ae | 768 | .SP |
8362ac1c MW |
769 | .BI "USER connect knock-active-peer " name |
770 | The server reported a valid | |
771 | .B knock | |
772 | message from a peer calling itself | |
773 | .I name | |
774 | but this is not a passive peer. | |
775 | .SP | |
776 | .BI "USER connect knock-unknown-peer " name | |
777 | The server reported a valid | |
778 | .B knock | |
779 | message from a peer calling itself | |
780 | .I name | |
781 | but no such peer is defined in the database. | |
782 | .SP | |
783 | .BI "USER connect knock-tag-mismatch peer " name " public-key-tag " tag | |
784 | The server reported a valid | |
785 | .B knock | |
786 | message from a peer calling itself | |
787 | .I name | |
788 | but this name doesn't match that peer's recorded public-key tag, which | |
789 | is | |
790 | .IR tag . | |
791 | .SP | |
d64ce4ae MW |
792 | .BI "USER connect ping-ok " peer |
793 | A reply was received to a | |
794 | .B PING | |
795 | sent to the | |
796 | .IR peer , | |
797 | though earlier attempts had failed. | |
798 | .SP | |
799 | .BI "USER connect ping-timeout " peer " attempt " i " of " n | |
800 | No reply was received to a | |
801 | .B PING | |
802 | sent to the | |
803 | .IR peer . | |
804 | So far, | |
805 | .I i | |
806 | .BR PING s | |
807 | have been sent; if a total of | |
808 | .I n | |
809 | consecutive attempts time out, the | |
810 | .B connect | |
811 | service will take further action. | |
812 | .SP | |
813 | .B "USER connect reconnecting " peer | |
814 | The dynamically connected | |
815 | .I peer | |
816 | seems to be unresponsive. The | |
817 | .B connect | |
818 | service will attempt to reconnect. | |
819 | .SP | |
820 | .BI "USER connect " process\fR... " stderr " line | |
821 | The | |
822 | .I process | |
823 | spawned by the | |
824 | .B connect | |
825 | service wrote | |
826 | .I line | |
827 | to its standard error. | |
828 | .SP | |
829 | .BI "USER connect " process\fR... " exit-nonzero " code | |
830 | The | |
831 | .I process | |
832 | spawned by the | |
833 | .B connect | |
834 | service exited with the nonzero status | |
835 | .IR code . | |
836 | .SP | |
837 | .BI "USER connect " process\fR... " exit-signal S" code | |
838 | The | |
839 | .I process | |
840 | spawned by the | |
841 | .B connect | |
842 | service was killed by signal | |
843 | .IR code . | |
844 | Here, | |
845 | .I code | |
846 | is the numeric value of the fatal signal. | |
847 | .SP | |
848 | .BI "USER connect " process\fR... " exit-unknown " status | |
849 | The | |
850 | .I process | |
851 | spawned by the | |
852 | .B connect | |
853 | service exited with an unknown | |
854 | .IR status . | |
855 | Here, | |
856 | .I status | |
857 | is the raw exit status, as returned by | |
858 | .BR waitpid (2), | |
859 | in hexadecimal. | |
860 | . | |
861 | .\"-------------------------------------------------------------------------- | |
862 | .SH "CHILD PROCESS IDENTIFIERS" | |
863 | . | |
864 | .\"* 50 Child process identifiers | |
865 | Some of the warnings and notifications refer to processes spawned by | |
866 | .B connect | |
867 | under various circumstances. The process identifiers are as follows. | |
868 | .SP | |
869 | .BI "connect " peer | |
870 | A child spawned in order to establish a dynamic connection with | |
871 | .IR peer . | |
872 | .SP | |
873 | .BI "disconnect " peer | |
874 | A child spawned in order to shut down a dynamic connection with | |
875 | .IR peer . | |
876 | .SP | |
877 | .BI "ifdown " peer | |
878 | A child spawned to deconfigure the network interface for | |
879 | .IR peer . | |
880 | .SP | |
881 | .BI "ifup " peer | |
882 | A child spawned to configure the network interface for | |
883 | .IR peer . | |
a62f8e8a MW |
884 | . |
885 | .\"-------------------------------------------------------------------------- | |
886 | .SH "SUMMARY" | |
887 | . | |
888 | .\"= summary | |
889 | . | |
890 | .\"-------------------------------------------------------------------------- | |
891 | .SH "SEE ALSO" | |
892 | . | |
893 | .BR tripe-service (7), | |
894 | .BR peers.in (5), | |
a62f8e8a MW |
895 | .BR tripe (8). |
896 | . | |
897 | .\"-------------------------------------------------------------------------- | |
898 | .SH "AUTHOR" | |
899 | . | |
900 | Mark Wooding, <mdw@distorted.org.uk> | |
901 | . | |
902 | .\"----- That's all, folks -------------------------------------------------- |