.\"
.\" 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 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.
+.\" 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.
+.\" along with TrIPE. If not, see <https://www.gnu.org/licenses/>.
.
.\"--------------------------------------------------------------------------
.so ../common/defs.man \"@@@PRE@@@
.
.\"--------------------------------------------------------------------------
-.TH connect 8 "8 January 2007" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
+.TH conntrack 8tripe "8 January 2007" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
.
.\"--------------------------------------------------------------------------
.SH "NAME"
The
.B conntrack
service watches D-Bus network management services like
-.BR NetworkManager (8)
+.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
.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
+should be selected if the host's current IP address is within one of the
+networks indicated by
.IB network / mask \fR.
-Here,
+Here, a
.I network
-is an IP address in dotted-quad form, and
+is an IPv4 or IPv6 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.
+is a netmask, either in dotted-quad form (for IPv4), or as a prefix
+length (i.e., the number of initial 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
+an IP packet sent to a particular remote address; note that this is
+entirely hypothetical, and no actual packets are transmitted. The
+default remote addresses are 1.2.3.4 (for IPv4, which is unlikely ever
+to be assigned), and 2001::1 (for IPv6); 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 one or more lines
.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.)
+The peer definitions in each group are checked in the order given, and
+searching stops as soon as a match is found. (In older versions of
+.BR conntrack ,
+definitions were processed according to a most-specific-first order, but
+that doesn't provide an ordering between IPv4 and IPv6 networks, which
+is important; so this has been changed.)
.PP
Peers are connected using the
.BR connect (8)
.TP
.BI state= label
The service's internal state machine is confused.
+.RE
.SP
-.BI "USER conntrack " up \fR| down " " reason\fR...
+.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. The
+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
-.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.
+.BI "connman initially-" state
+ConnMan was detected on startup, and is in the given
+.I state
+\(en see below.
.TP
-.B "nm connected"
-NetworkManager has acquired an active network connection.
+.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
-.B "nm disconnected"
-NetworkManager has lost its active network connection.
+.BI "icd connected " iap
+Maemo ICd has acquired an active network connection, identified by
+.IR iap .
.TP
-.B "nm default-connection-change"
-NetworkManager has changed its default route.
+.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
.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
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
.
.\"--------------------------------------------------------------------------
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"
~mdw / tripe / blobdiff