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" | |
249 | If a peer's database record assigns a value to the | |
250 | .B connect | |
251 | key, then the | |
252 | .B connect | |
253 | service will attempt to establish a connection dynamically with the | |
254 | peer. The value of the | |
255 | .B connect | |
256 | key is invoked as a Bourne shell command, i.e., | |
257 | .IP | |
258 | .B /bin/sh \-c | |
259 | .I connect | |
260 | .PP | |
261 | is executed. The command is expected to contact the remote server and | |
262 | report, on standard output, a challenge string, typically by issuing | |
263 | a | |
264 | .B passive | |
265 | command to the instance of the | |
266 | .B connect | |
267 | service running on the peer. The | |
268 | .B connect | |
269 | service reads this challenge, and submits the command | |
270 | .IP | |
271 | .B GREET | |
272 | .I peer | |
273 | .I challenge | |
274 | .PP | |
275 | Typically, the | |
276 | .B connect | |
277 | command will issue a command such as | |
278 | .IP | |
279 | .B SVCSUBMIT connect passive | |
280 | .I our-name | |
281 | .PP | |
282 | where | |
283 | .I our-name | |
284 | is the remote peer's name for this host. | |
285 | .PP | |
286 | Similarly, if the database record has a | |
287 | .B disconnect | |
288 | entry, then | |
289 | .B connect | |
290 | will use this to give the peer explicit notification that its services | |
291 | are no longer needed. The value of the | |
292 | .B disconnect | |
293 | key is invoked as a Bourne shell command. This ought to result in a | |
294 | .B KILL | |
295 | command being issued to the peer's server. | |
296 | .PP | |
297 | In detail, the protocol for passive connection works as follows. | |
a62f8e8a MW |
298 | .hP 1. |
299 | The active peer | |
300 | .BR ADD s | |
301 | its partner, typically using the | |
302 | .B \-cork | |
303 | option to suppress the key-exchange message which the server usually | |
304 | sends immediately, since otherwise the passive peer will warn about it. | |
305 | .hP 2. | |
d64ce4ae | 306 | The active peer issues the command |
a62f8e8a MW |
307 | .RS |
308 | .IP | |
309 | .B SVCSUBMIT connect passive | |
310 | .I user | |
311 | .PP | |
312 | to the passive peer's server. (Here, | |
313 | .I user | |
d64ce4ae MW |
314 | is a name identifying the active peer; see below.) Doing this is the |
315 | responsibility of the | |
316 | .B connect | |
317 | command. | |
a62f8e8a MW |
318 | .RE |
319 | .hP 3. | |
320 | The | |
321 | .B connect | |
322 | service on the passive peer responds with a | |
323 | .I challenge | |
324 | \(en a short Base64-encoded string. Somehow this challenge is sent back | |
325 | to the passive peer without being intercepted. | |
326 | .hP 4. | |
327 | The active peer sends a | |
328 | .BR GREET ing | |
329 | containing the challenge to its passive partner. The passive server | |
330 | announces the arrival of this message, and the originating address and | |
331 | port. | |
332 | .hP 5. | |
333 | The | |
334 | .B connect | |
335 | service running on the passive host receives the notification, matches | |
336 | it up with the | |
337 | .I user | |
338 | from the initial connection request, and | |
339 | .BR ADD s | |
340 | the appropriate peer, with the address from the | |
341 | .BR GREET ing. | |
d64ce4ae MW |
342 | . |
343 | .SS "Operation" | |
344 | On startup, | |
345 | .B connect | |
346 | requests a list of current peers from the | |
347 | .BR tripe (8) | |
348 | server, and adopts any eligible peers. If the | |
349 | .B \-\-startup | |
350 | flag was passed on the command line, the newly adopted peers have their | |
351 | interfaces configured and connection attempts are made. | |
a62f8e8a | 352 | .PP |
d64ce4ae MW |
353 | Adopted peers are pinged at regular intervals (using the |
354 | .B PING | |
355 | administrative command; see | |
356 | .BR tripe-admin (5)). | |
357 | This process can be configured by assigning values to keys in the peer's | |
358 | database record. Some of these parameters are time intervals, | |
359 | expressed as a nonnegative integer followed optionally by | |
360 | .BR d , | |
361 | .BR h , | |
362 | .BR m , | |
363 | or | |
364 | .B s | |
365 | for days, hours, minutes, or seconds, respectively; if no suffix is | |
366 | given, seconds are assumed. | |
367 | .PP | |
368 | The parameters are as follows. | |
369 | .TP | |
370 | .B every | |
371 | A time interval: how often to ping the peer to ensure that it's still | |
02c99524 MW |
372 | alive. The default is 30 seconds for active dynamic peers, and 5 |
373 | minutes for passive peers. | |
374 | .IP | |
375 | The period for dynamic peers should be no longer than | |
376 | .I timeout | |
377 | \(mu | |
378 | .RI ( retries | |
379 | \- 1). Consider an idle mobile peer which has its IP address changed | |
380 | just before its passive peer begins pinging. The static peer's pings | |
381 | will go to the old address until it receives a ping back from the mobile | |
382 | peer. Therefore, the static peer has to keep pinging until it would | |
383 | definitely have received an unsolicited ping from the mobile peer, and | |
384 | therefore be informed of the change of address. And it's no use | |
385 | learning about the change of address just after sending the last ping to | |
386 | the old address, so the last retry doesn't count for the purposes of | |
387 | this calculation. | |
388 | .IP | |
389 | Besides, the consequences of failed pinging differ between dynamic and | |
390 | passive peers. In the former case, a failure provokes a reconnection | |
391 | attempt, after which (hopefully) things will work again: it's probably a | |
392 | good thing to check frequently and fail fast. In the latter case, the | |
393 | dynamic peer will certainly have to notice that it's been abandoned and | |
394 | arrange to retry, causing a communication failure where maybe there | |
395 | wasn't really one before. | |
d64ce4ae MW |
396 | .TP |
397 | .B timeout | |
398 | A time interval: how long to wait for a reply before retrying or giving | |
399 | up. The default is 10 seconds. | |
400 | .TP | |
401 | .B retries | |
402 | An integer: how many failed attempts to make before deciding that the | |
403 | peer is unreachable and taking action. The default is 5 attempts. | |
404 | .PP | |
405 | The algorithm is as follows. Send up to | |
406 | .I retries | |
407 | pings; if a reply is received before the | |
408 | .I timeout | |
409 | then the peer is alive; wait | |
410 | .I every | |
411 | and check again. If no reply is received within the | |
412 | .IR timeout , | |
413 | then try again up to | |
414 | .I retries | |
415 | times. If no attempt succeeds, the peer is declared unreachable. If | |
416 | the peer has a | |
417 | .B connect | |
418 | command (i.e., it connects dynamically) then another connection attempt | |
419 | is made. Otherwise the peer is killed. | |
a62f8e8a MW |
420 | . |
421 | .\"-------------------------------------------------------------------------- | |
422 | .SH "SERVICE COMMAND REFERENCE" | |
423 | . | |
424 | .\"* 10 Service commands | |
425 | The commands provided by the service are as follows. | |
426 | .SP | |
427 | .BI "active " peer | |
428 | Make an active connection to the named | |
429 | .IR peer . | |
430 | The service will submit the command | |
431 | .RS | |
432 | .IP | |
433 | .B ADD | |
434 | .RB [ \-cork ] | |
435 | .RB [ \-keepalive | |
436 | .IR time ] | |
48b84569 MW |
437 | .RB [ \-key |
438 | .IR tag ] | |
d64ce4ae MW |
439 | .RB [ \-priv |
440 | .IR tag ] | |
6411163d | 441 | .RB [ \-mobile ] |
a62f8e8a MW |
442 | .RB [ \-tunnel |
443 | .IR driver ] | |
444 | .I address | |
445 | .PP | |
446 | Specifically: | |
447 | .hP \*o | |
448 | The option | |
449 | .B \-cork | |
450 | is provided if the peer's database record assigns the | |
451 | .B cork | |
452 | key one of the values | |
453 | .BR t , | |
454 | .BR true , | |
455 | .BR y , | |
456 | .BR yes, | |
457 | or | |
458 | .BR on . | |
459 | .hP \*o | |
460 | The option | |
461 | .B \-keepalive | |
462 | .I time | |
463 | is provided if the database record assigns a value | |
464 | .I time | |
465 | to the | |
466 | .B keepalive | |
467 | key. | |
468 | .hP \*o | |
469 | The option | |
48b84569 MW |
470 | .B \-key |
471 | .I tag | |
472 | is provided if the database record assigns a value | |
473 | .I tag | |
474 | to the | |
475 | .B key | |
476 | key. | |
477 | .hP \*o | |
478 | The option | |
d64ce4ae MW |
479 | .B \-priv |
480 | .I tag | |
481 | is provided if the database record assigns a value | |
482 | .I tag | |
483 | to the | |
484 | .B priv | |
485 | key. | |
486 | .hP \*o | |
487 | The option | |
6411163d MW |
488 | .B \-mobile |
489 | is provided if the peer's database record assigns the | |
490 | .B mobile | |
491 | key one of the values | |
492 | .BR t , | |
493 | .BR true , | |
494 | .BR y , | |
495 | .BR yes, | |
496 | or | |
497 | .BR on . | |
498 | .hP \*o | |
499 | The option | |
a62f8e8a MW |
500 | .B \-tunnel |
501 | .I driver | |
502 | is provided if the database record assigns a value | |
503 | .I driver | |
504 | to the | |
505 | .B tunnel | |
506 | key. | |
507 | .hP \*o | |
508 | The | |
509 | .I address | |
510 | is the value assigned to the | |
511 | .B peer | |
512 | key in the database record. | |
513 | .RE | |
514 | .SP | |
d64ce4ae MW |
515 | .B adopted |
516 | For each peer being tracked by the | |
517 | .B connect | |
518 | service, write a line | |
519 | .B INFO | |
520 | .IR name . | |
521 | (Compatibility note: it's possible that further information will be | |
522 | provided about each peer, in the form of subsequent tokens. Clients | |
523 | should be prepared to ignore such tokens.) | |
524 | .SP | |
a62f8e8a | 525 | .BI "info " peer |
b9dedfa6 | 526 | Lists the database record and additional information about the named |
a62f8e8a MW |
527 | .IR peer . |
528 | For each key/value pair, a line | |
529 | .RS | |
530 | .IP | |
531 | .B INFO | |
532 | .IB key = value | |
533 | .PP | |
534 | is output. The key/value pairs are output in an arbitrary order. | |
b9dedfa6 MW |
535 | .PP |
536 | In addition to the fields of the peer's database record, the following | |
537 | additional keys are defined. | |
538 | .TP | |
539 | .B failures | |
540 | The number of failed pings in the current or most recent batch, in | |
541 | decimal. | |
542 | .TP | |
543 | .B last-ping | |
544 | The round-trip time of the most recent ping in milliseconds, in the form | |
545 | .IB nn.n ms\fR, | |
546 | or | |
547 | .B timeout | |
548 | if the most recent ping timed out, | |
549 | or | |
550 | .B \- | |
551 | if no pings have yet completed. | |
552 | .TP | |
553 | .B max-ping | |
554 | The maximum successful ping time so far in milliseconds, in the form | |
555 | .IB nn.n ms\fR, | |
556 | or | |
557 | .B \- | |
558 | if no pings have yet succeeded. | |
559 | .TP | |
560 | .B mean-ping | |
561 | The average successful ping time so far in milliseconds, in the form | |
562 | .IB nn.n ms\fR, | |
563 | or | |
564 | .B \- | |
565 | if no pings have yet succeeded. | |
566 | .TP | |
567 | .B min-ping | |
568 | The minimum successful ping time so far in milliseconds, in the form | |
569 | .IB nn.n ms\fR, | |
570 | or | |
571 | .B \- | |
572 | if no pings have yet succeeded. | |
573 | .TP | |
574 | .B n-lost | |
575 | The number of pings which have been declared timed out so far, in | |
576 | decimal. | |
577 | .TP | |
578 | .B n-ping | |
579 | The number of successful pings so far, in decimal. | |
580 | .TP | |
581 | .B sd-ping | |
582 | The standard deviation of ping times so far in milliseconds, in the form | |
583 | .IB nn.n ms\fR, | |
584 | or | |
585 | .B \- | |
586 | if no pings have yet succeeded. | |
587 | .TP | |
588 | .B state | |
589 | One of the strings: | |
590 | .B idle | |
591 | if the peer has responded to a ping recently, and we are waiting for the | |
592 | .B every | |
593 | delay before we try again; or | |
594 | .B check | |
595 | if we are currently waiting for a ping to return. | |
a62f8e8a | 596 | .RE |
d64ce4ae MW |
597 | .SP |
598 | .BI "kick " peer | |
599 | If | |
600 | .I peer | |
601 | is currently added, and its record in the peer database contains a | |
602 | .B connect | |
603 | key (see | |
604 | .BR peers.in ) | |
605 | then force a reconnection attempt. See | |
606 | .BR "Dynamic connection" . | |
607 | .SP | |
608 | .B "list-active" | |
a62f8e8a MW |
609 | Output a list of peers in the database. For each peer name |
610 | .IR peer , | |
611 | a line | |
612 | .RS | |
613 | .IP | |
614 | .B INFO | |
615 | .I peer | |
616 | .PP | |
617 | is output. | |
618 | .RE | |
619 | .SP | |
620 | .BI "passive \fR[" options "\fR]\fP " user | |
621 | If the database contains a user record mapping | |
622 | .I user | |
623 | to some | |
624 | .I peer | |
625 | then an | |
626 | .B INFO | |
627 | line is written containing a freshly chosen challenge string. If the | |
628 | server receives a | |
629 | .BR GREET ing | |
630 | message quoting this challenge within 30 seconds, the | |
631 | .B connect | |
632 | service will issue an | |
633 | .B ADD | |
634 | request for the peer, as for the | |
635 | .B active | |
636 | command, except that the origin of the | |
637 | .BR GREET ing | |
638 | packet is used as the peer's address. | |
639 | .RS | |
640 | .\"+opts | |
641 | .PP | |
642 | The following option is recognized. | |
643 | .TP | |
644 | .BI "\-timeout " time | |
645 | Wait for | |
646 | .I time | |
647 | instead of 30 seconds. The | |
648 | .I time | |
649 | is expressed as a non-negative integer followed by | |
650 | .BR d , | |
651 | .BR h , | |
652 | .BR m , | |
653 | or | |
654 | .B s | |
655 | for days, hours, minutes or seconds respectively; if no suffix is given, | |
656 | seconds are assumed. | |
657 | .\"-opts | |
658 | .RE | |
d3731285 | 659 | .SP |
965eb987 MW |
660 | .BI "sabotage " peer |
661 | Sabotage the | |
662 | .I peer | |
663 | so that | |
664 | .B connect | |
665 | thinks that it can't respond to pings. This will usually provoke a | |
666 | reconnection attempt. Use | |
667 | .B kick | |
668 | instead unless you're trying to test | |
669 | .BR connect . | |
670 | .SP | |
d3731285 MW |
671 | .BI "userpeer " user |
672 | Output a single | |
673 | .B INFO | |
674 | line identifying the peer corresponding to the | |
675 | .I user | |
676 | name. | |
a62f8e8a MW |
677 | . |
678 | .\"-------------------------------------------------------------------------- | |
d64ce4ae | 679 | .SH "NOTIFICATIONS" |
a62f8e8a | 680 | . |
d64ce4ae MW |
681 | .\"* 30 Notification broadcasts (NOTE codes) |
682 | All notifications issued by | |
683 | .B connect | |
684 | begin with the tokens | |
685 | .BR "USER connect" . | |
a62f8e8a | 686 | .SP |
d64ce4ae MW |
687 | .B "USER connect peerdb-update" |
688 | The peer database has changed. Other interested clients should reopen | |
689 | the database. | |
a62f8e8a | 690 | .SP |
d64ce4ae MW |
691 | .BI "USER connect ping-failed " peer " " error\fR... |
692 | An attempt to | |
693 | .B PING | |
694 | the named | |
a62f8e8a | 695 | .I peer |
d64ce4ae MW |
696 | failed; the server replied |
697 | .B FAIL | |
698 | .IR error ... | |
a62f8e8a | 699 | .SP |
d64ce4ae | 700 | .BI "USER connect " process\fR... " stdout " line |
a62f8e8a | 701 | The |
d64ce4ae MW |
702 | .I process |
703 | spawned by the | |
704 | .B connect | |
705 | service unexpectedly wrote | |
706 | .I line | |
707 | to its standard output. | |
a62f8e8a MW |
708 | . |
709 | .\"-------------------------------------------------------------------------- | |
710 | .SH "WARNINGS" | |
711 | . | |
712 | .\"* 40 Warning broadcasts (WARN codes) | |
713 | All warnings issued by | |
714 | .B connect | |
715 | begin with the tokens | |
716 | .BR "USER connect" . | |
717 | .SP | |
718 | .BI "USER connect auto-add-failed " name " " error\fR... | |
719 | The attempt to add the peer | |
720 | .I name | |
721 | automatically failed: the | |
722 | .B ADD | |
723 | command reported | |
724 | .B FAIL | |
725 | .IR error ... | |
d64ce4ae MW |
726 | .SP |
727 | .BI "USER connect ping-ok " peer | |
728 | A reply was received to a | |
729 | .B PING | |
730 | sent to the | |
731 | .IR peer , | |
732 | though earlier attempts had failed. | |
733 | .SP | |
734 | .BI "USER connect ping-timeout " peer " attempt " i " of " n | |
735 | No reply was received to a | |
736 | .B PING | |
737 | sent to the | |
738 | .IR peer . | |
739 | So far, | |
740 | .I i | |
741 | .BR PING s | |
742 | have been sent; if a total of | |
743 | .I n | |
744 | consecutive attempts time out, the | |
745 | .B connect | |
746 | service will take further action. | |
747 | .SP | |
748 | .B "USER connect reconnecting " peer | |
749 | The dynamically connected | |
750 | .I peer | |
751 | seems to be unresponsive. The | |
752 | .B connect | |
753 | service will attempt to reconnect. | |
754 | .SP | |
755 | .BI "USER connect " process\fR... " stderr " line | |
756 | The | |
757 | .I process | |
758 | spawned by the | |
759 | .B connect | |
760 | service wrote | |
761 | .I line | |
762 | to its standard error. | |
763 | .SP | |
764 | .BI "USER connect " process\fR... " exit-nonzero " code | |
765 | The | |
766 | .I process | |
767 | spawned by the | |
768 | .B connect | |
769 | service exited with the nonzero status | |
770 | .IR code . | |
771 | .SP | |
772 | .BI "USER connect " process\fR... " exit-signal S" code | |
773 | The | |
774 | .I process | |
775 | spawned by the | |
776 | .B connect | |
777 | service was killed by signal | |
778 | .IR code . | |
779 | Here, | |
780 | .I code | |
781 | is the numeric value of the fatal signal. | |
782 | .SP | |
783 | .BI "USER connect " process\fR... " exit-unknown " status | |
784 | The | |
785 | .I process | |
786 | spawned by the | |
787 | .B connect | |
788 | service exited with an unknown | |
789 | .IR status . | |
790 | Here, | |
791 | .I status | |
792 | is the raw exit status, as returned by | |
793 | .BR waitpid (2), | |
794 | in hexadecimal. | |
795 | . | |
796 | .\"-------------------------------------------------------------------------- | |
797 | .SH "CHILD PROCESS IDENTIFIERS" | |
798 | . | |
799 | .\"* 50 Child process identifiers | |
800 | Some of the warnings and notifications refer to processes spawned by | |
801 | .B connect | |
802 | under various circumstances. The process identifiers are as follows. | |
803 | .SP | |
804 | .BI "connect " peer | |
805 | A child spawned in order to establish a dynamic connection with | |
806 | .IR peer . | |
807 | .SP | |
808 | .BI "disconnect " peer | |
809 | A child spawned in order to shut down a dynamic connection with | |
810 | .IR peer . | |
811 | .SP | |
812 | .BI "ifdown " peer | |
813 | A child spawned to deconfigure the network interface for | |
814 | .IR peer . | |
815 | .SP | |
816 | .BI "ifup " peer | |
817 | A child spawned to configure the network interface for | |
818 | .IR peer . | |
a62f8e8a MW |
819 | . |
820 | .\"-------------------------------------------------------------------------- | |
821 | .SH "SUMMARY" | |
822 | . | |
823 | .\"= summary | |
824 | . | |
825 | .\"-------------------------------------------------------------------------- | |
826 | .SH "SEE ALSO" | |
827 | . | |
828 | .BR tripe-service (7), | |
829 | .BR peers.in (5), | |
a62f8e8a MW |
830 | .BR tripe (8). |
831 | . | |
832 | .\"-------------------------------------------------------------------------- | |
833 | .SH "AUTHOR" | |
834 | . | |
835 | Mark Wooding, <mdw@distorted.org.uk> | |
836 | . | |
837 | .\"----- That's all, folks -------------------------------------------------- |