svc/conntrack{,.8}.in: Better diagnostics.

[tripe] / svc / tripe-ifup.8.in

.\" -*-nroff-*-
.\".
.\" Manual for the watch service
.\"
.\" (c) 2008 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 ../defs.man.in \"@@@PRE@@@
.
.\"--------------------------------------------------------------------------
.TH tripe-ifup 8 "20 December 2008" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
.
.\"--------------------------------------------------------------------------
.SH "NAME"
.
tripe-ifup \- configure VPN network interfaces and routes
.
.\"--------------------------------------------------------------------------
.SH "SYNOPSIS"
.
.B tripe-ifup
.I peer
.I ifname
.I address-family
.IR addr ...
.
.\"--------------------------------------------------------------------------
.SH "DESCRIPTION"
.
The
.B tripe-ifup
program configures network interfaces and routes for
.BR tripe (8).
It expects a number of values to be passed as environment variables.  It
is usually invoked by the
.BR watch (8)
service, which provides values for these environment variables by
consulting the peer database
.BR peers.cdb (5).
These parameters are therefore described in terms of their keys in the
peer's database record; the corresponding environment variable name is
formed by converting letters to uppercase and prefixing with
.RB ` P_ '.
.PP
The command-line arguments are as follows.
.TP
.I peer
The name of the peer, as known to the
.BR tripe (8)
server and various services.  This is used to notify the server of
changes, and to announce final success.
.TP
.I ifname
The current name of the interface, as known to the kernel.
.TP
.IR address-family " and " addr
The address, in the format described in
.BR tripe-admin (5).
Currently only the
.B INET
address family is supported.
.SS Procedure
In the following, a name in
.I italics
is used to represent the value of the correspondingly named key in the
peer's record.  For example,then
.I nets
denotes the value assigned to the
.B nets
key, as passed in the
.B T_NETS
environment variable.
.PP
The network interface is configured as follows.
.hP 1.
The network interface name is set.  If
.I ifname
is set, then the network interface is renamed to
.IR ifname ;
a
.B SETIFNAME
command is issued to keep the server informed.  Further configuration is
performed using the new interface name.
.hP 2.
Configure the interface addresses.  If
.I laddr
is set, it should be a space-separated list of IPv4 and IPv6 addresses:
there may be any number of either.
If
.I raddr
is set, it should be an IPv4 and/or an IPv6 address, separated by space:
these are the addresses to configure as the remote end point of the
point-to-point link.  (Further remote addresses can be configured as
host routes: see below.)  IPv4 addresses are expected to be in
dotted-quad form; IPv6 addresses should be in RFC4291 hex-and-colons
form.
.hP 3.
Establish routes.  If addresses were configured, and
.I nets
is set, then
.I nets
is split into space-separated networks.  For each network, of the form
.IB address / mask \fR,
a route is configured to the given network, via the remote address of
the link, over the tunnel interface.  The
.IR address es
may be IPv4 or IPv6 addresses.  If the interface has only an IPv4
address then IPv6 routes will be ignored, and
.IR "vice versa" .
.hP 4.
Configure the interface MTU and bring it up.  The
interface MTU is configured based on the path MTU to the peer's external
address and the cryptographic algorithms in use by the
.BR tripe (8)
server; this can be overridden by setting the
.I mtu
key.
.hP 5.
Invoke user hook.  If
.I ifupextra
is set, it is interpreted as a Bourne shell command and evaluated.
.hP 6.
Notify services.  A notification
.RS
.IP
.B USER tripe-ifup configured
.I peer
.PP
is issued.
.RE
.
.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
.
.BR peers.in (5),
.BR watch (8),
.BR tripe (8).
.
.\"--------------------------------------------------------------------------
.SH "AUTHOR"
.
Mark Wooding, <mdw@distorted.org.uk>
.
.\"----- That's all, folks --------------------------------------------------