--- /dev/null
+.\" -*-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, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
~mdw / tripe / blobdiff