X-Git-Url: https://git.distorted.org.uk/~mdw/tripe/blobdiff_plain/a02240ba1ed0d7f8ca6b4ab45e9c9e3532a9f7ea..2ec904370c028570277cb1d88405e7ab68e71f50:/svc/conntrack.8.in diff --git a/svc/conntrack.8.in b/svc/conntrack.8.in new file mode 100644 index 00000000..9c0fe1be --- /dev/null +++ b/svc/conntrack.8.in @@ -0,0 +1,273 @@ +.\" -*-nroff-*- +.\". +.\" Manual for the conntrack service +.\" +.\" (c) 2010 Straylight/Edgeware +.\" +. +.\"----- Licensing notice --------------------------------------------------- +.\" +.\" This file is part of Trivial IP Encryption (TrIPE). +.\" +.\" TrIPE is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" TrIPE is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with TrIPE; if not, write to the Free Software Foundation, +.\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +. +.\"-------------------------------------------------------------------------- +.so ../common/defs.man \"@@@PRE@@@ +. +.\"-------------------------------------------------------------------------- +.TH connect 8 "8 January 2007" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption" +. +.\"-------------------------------------------------------------------------- +.SH "NAME" +. +conntrack \- tripe service to start/stop peers depending on external connectivity +. +.\"-------------------------------------------------------------------------- +.SH "SYNOPSIS" +. +.B conntrack +.RB [ \-a +.IR socket ] +.RB [ \-d +.IR dir ] +.RB [ \-f +.IR file ] +.br +\& \c +.RB [ \-\-daemon ] +.RB [ \-\-debug ] +.RB [ \-\-startup ] +. +.\"-------------------------------------------------------------------------- +.SH "DESCRIPTION" +. +The +.B conntrack +service watches D-Bus network management services like +.BR NetworkManager (8) +and Nokia's +.BR ICd , +bringing peers up and down automatically. It's designed to be useful on +a mobile device, such as a laptop; I expect servers to stay where +they're put and be configured statically. +.SS "Configuration" +The +.B conntrack +service reads a configuration file, by default +.BR conntrack.conf , +explaining which peers to bring up under which circumstances. The +configuration file is automatically re-read if it's changed. +.PP +The +configuration is split into sections, each describing a +.IR "peer group" . +A section begins with the peer group name in square brackets: +.IP +.BI [ group ] +.PP +The group name is entirely arbitrary, and affects nothing else. This is +followed by peer definitions, each of which looks like this: +.IP +.I tag +.B = +.RI [ remote-addr ] +.IB network / mask +.PP +This means that the peer +.I tag +should be selected if the host's current IP address is within the +network indicated by +.IB network / mask \fR. +Here, +.I network +is an IP address in dotted-quad form, and +.I mask +is a netmask, either in dotted-quad form, or as a number of 1-bits. +Only one peer in each group may be connected at any given time; if a +change is needed, any existing peer in the group is killed before +connecting the new one. If no match is found in a particular group, +then no peers in the group are connected. Strange and unhelpful things +will happen if you put the same peer in several different groups. +.PP +The notion of `current IP address' is somewhat vague. The +.B conntrack +service calculates it as the source address that the host would put on +an IP packet sent to an arbitrarily chosen remote address. The default +remote address is 1.2.3.4 (which is unlikely ever to be assigned); this +should determine an IP address on the network interface closest to the +default gateway. You can influence this process in two ways. Firstly, +you can change the default remote address used by adding a line +.IP +.B "test-addr =" +.I remote-addr +.PP +before the first peer group section. Secondly, you can specify a +particular +.I remote-addr +to use when checking whether a particular peer is applicable. +.PP +The peer definitions can be in any order. They are checked +most-specific first, and searching stops as soon as a match is found. +Therefore a default definition can be added as +.IP +.I tag +.B = +.B 0/0 +.PP +without fear of overriding any more specific definitions. For avoidance +of doubt, one peer definition is +.I more specific +than another if either the former has a specified +.I remote-addr +and the latter has not, or the former is wholly contained within the +latter. (Overlapping definitions are not recommended, and will be +processed in an arbitrary order.) +.PP +Peers are connected using the +.BR connect (8) +service: +.IP +.B SVCSUBMIT connect active +.I peer +.SS "Command line" +In addition to the standard options described in +.BR tripe-service (7), +the following command-line options are recognized. +.TP +.BI "\-f, \-\-config=" file +Use +.I file +as the configuration file. In the absence of this option, the +file named +.B conntrack.conf +in the current working directory is used instead. +. +.\"-------------------------------------------------------------------------- +.SH "SERVICE COMMAND REFERENCE" +. +.\"* 10 Service commands +The commands provided by the service are as follows. +.SP +.BI "up " reason\fR... +Informs the service that the network connection has been established: +peer groups should be connected. The +.I reason +is quoted in the status notification. +.SP +.BI "down " reason\fR... +Informs the service that the network connection has been lost: +peer groups should be disconnected. The +.I reason +is quoted in the status notification. +. +.\"-------------------------------------------------------------------------- +.SH "NOTIFICATIONS" +. +.\"* 30 Notification broadcasts (NOTE codes) +All notifications issued by +.B conntrack +begin with the tokens +.BR "USER conntrack" . +.SP +.BI "USER conntrack " up \fR| down " " reason\fR... +The network connection has apparently gone up or down, and +.B conntrack +is about to kill and/or connect peers accordingly. The +.I reason +is one of the following. +.RS +.TP +.B "nm initially-connected" +NetworkManager was detected on startup, and has an active network +connection. +.TP +.B "nm initially-disconnected" +NetworkManager was detected on startup, and has no active network +connection. +.TP +.B "nm connected" +NetworkManager has acquired an active network connection. +.TP +.B "nm disconnected" +NetworkManager has lost its active network connection. +.TP +.B "nm default-connection-change" +NetworkManager has changed its default route. +.TP +.BI "icd initially-connected " iap +Maemo ICd was detected on startup, and has an active network connection +identified by +.IR iap . +.TP +.B "icd initially-disconnected" +Maemo ICd was detected on startup, and has no active network connection. +.TP +.BI "icd connected " iap +Maemo ICd has acquired an active network connection, identified by +.IR iap . +.TP +.B "icd idle" +Maemo ICd has lost its active network connection. +.TP +.B interval-timer +A change was detected during +.BR conntrack 's +periodic status check. This usually means that the network connection +was reconfigured manually without informing +.BR conntrack . +.TP +.BI "manual " reason\fR... +The connection status was changed manually, using the +.B up +or +.B down +service command. +.RE +. +.\"-------------------------------------------------------------------------- +.SH "WARNINGS" +. +.\"* 40 Warning broadcasts (WARN codes) +All warnings issued by +.B conntrack +begin with the tokens +.BR "USER conntrack" . +.SP +.BI "USER conntrack config-file-error " exception " " error-text +The configuration file is invalid. The +.I exception +token names a Python exception; the +.I error-text +describes the problem encountered, though it may not be very useful. +. +.\"-------------------------------------------------------------------------- +.SH "SUMMARY" +. +.\"= summary +. +.\"-------------------------------------------------------------------------- +.SH "SEE ALSO" +. +.BR tripe-service (7), +.BR peers.in (5), +.BR watch (8), +.BR tripe (8). +. +.\"-------------------------------------------------------------------------- +.SH "AUTHOR" +. +Mark Wooding, +. +.\"----- That's all, folks --------------------------------------------------