svc/conntrack.in: Process peer patterns in order.

[tripe] / svc / conntrack.8.in

.\" -*-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 3 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, see <https://www.gnu.org/licenses/>.
.
.\"--------------------------------------------------------------------------
.so ../common/defs.man \"@@@PRE@@@
.
.\"--------------------------------------------------------------------------
.TH conntrack 8tripe "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),
.BR ConnMan
.RB ( connmand (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 tags
.B down
and
.BI down/ anything
are special and mean that no peer from the group should be active.  This
is useful for detecting a `home' network, where a VPN is unnecessary
(or, worse, break routing completely).
.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 in each group are checked in the order given, and
searching stops as soon as a match is found.
.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 dbus-connection " status
The service's connection to D-Bus has changed state.  The
.I status
is one of the following.
.RS
.TP
.B startup
Initially trying to connect.
.TP
.B connected
Successfully established a connection to the bus.
.TP
.B lost
A connection has been lost.
.TP
.BI state= label
The service's internal state machine is confused.
.RE
.SP
.BI "USER conntrack " up \fR| down " " group = peer\fR... " " reason\fR...
The network connection has apparently gone up or down, and
.B conntrack
is about to kill and/or connect peers accordingly: for each group, the
selected peer is listed; if a group is not listed, then either the group
is to be brought down, or no matching peer was found.  The
.I reason
is one of the following.
.RS
.TP
.BI "connman initially-" state
ConnMan was detected on startup, and is in the given
.I state
\(en see below.
.TP
.BI "connman " state
ConnMan has transitioned to
.IR state .
The possible states are:
.B offline
(the network is turned off by user request);
.B idle
(no network interfaces are active);
.B ready
(an interface is up but not fully configured); and
.B online
(an interface is up and configured).
.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
.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
.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.
.TP
.B "nm connected"
NetworkManager has acquired an active network connection.
.TP
.B "nm default-connection-change"
NetworkManager has changed its default route.
.TP
.B "nm disconnected"
NetworkManager has lost its active network connection.
.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.
.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.
.SP
.BI "USER conntrack connect-failed " peer " " tokens\fR...
An attempt to connect the named
.I peer
failed; the error message is given by the
.IR tokens .
.
.\"--------------------------------------------------------------------------
.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 --------------------------------------------------