chiark / gitweb /
Merge branch 'mdw/backoff'
[tripe] / svc / tripe-ifup.8.in
1 .\" -*-nroff-*-
2 .\".
3 .\" Manual for the watch service
4 .\"
5 .\" (c) 2008 Straylight/Edgeware
6 .\"
7 .
8 .\"----- Licensing notice ---------------------------------------------------
9 .\"
10 .\" This file is part of Trivial IP Encryption (TrIPE).
11 .\"
12 .\" TrIPE is free software; you can redistribute it and/or modify
13 .\" it under the terms of the GNU General Public License as published by
14 .\" the Free Software Foundation; either version 2 of the License, or
15 .\" (at your option) any later version.
16 .\"
17 .\" TrIPE is distributed in the hope that it will be useful,
18 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
19 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
20 .\" GNU General Public License for more details.
21 .\"
22 .\" You should have received a copy of the GNU General Public License
23 .\" along with TrIPE; if not, write to the Free Software Foundation,
24 .\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
25 .
26 .\"--------------------------------------------------------------------------
27 .so ../defs.man.in \"@@@PRE@@@
28 .
29 .\"--------------------------------------------------------------------------
30 .TH tripe-ifup 8 "20 December 2008" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
31 .
32 .\"--------------------------------------------------------------------------
33 .SH "NAME"
34 .
35 tripe-ifup \- configure VPN network interfaces and routes
36 .
37 .\"--------------------------------------------------------------------------
38 .SH "SYNOPSIS"
39 .
40 .B tripe-ifup
41 .I peer
42 .I ifname
43 .I address-family
44 .IR addr ...
45 .
46 .\"--------------------------------------------------------------------------
47 .SH "DESCRIPTION"
48 .
49 The
50 .B tripe-ifup
51 program configures network interfaces and routes for
52 .BR tripe (8).
53 It expects a number of values to be passed as environment variables.  It
54 is usually invoked by the
55 .BR watch (8)
56 service, which provides values for these environment variables by
57 consulting the peer database
58 .BR peers.cdb (5).
59 These parameters are therefore described in terms of their keys in the
60 peer's database record; the corresponding environment variable name is
61 formed by converting letters to uppercase and prefixing with
62 .RB ` P_ '.
63 .PP
64 The command-line arguments are as follows.
65 .TP
66 .I peer
67 The name of the peer, as known to the
68 .BR tripe (8)
69 server and various services.  This is used to notify the server of
70 changes, and to announce final success.
71 .TP
72 .I ifname
73 The current name of the interface, as known to the kernel.
74 .TP
75 .IR address-family " and " addr
76 The address, in the format described in
77 .BR tripe-admin (5).
78 Currently only the
79 .B INET
80 address family is supported.
81 .SS Procedure
82 In the following, a name in
83 .I italics
84 is used to represent the value of the correspondingly named key in the
85 peer's record.  For example,then
86 .I nets
87 denotes the value assigned to the
88 .B nets
89 key, as passed in the
90 .B T_NETS
91 environment variable.
92 .PP
93 The network interface is configured as follows.
94 .hP 1.
95 The network interface name is set.  If
96 .I ifname
97 is set, then the network interface is renamed to
98 .IR ifname ;
99 a
100 .B SETIFNAME
101 command is issued to keep the server informed.  Further configuration is
102 performed using the new interface name.
103 .hP 2.
104 Configure the interface addresses.  If
105 .I laddr
106 is set, it should be a space-separated list of IPv4 and IPv6 addresses:
107 there may be any number of either.
108 If
109 .I raddr
110 is set, it should be an IPv4 and/or an IPv6 address, separated by space:
111 these are the addresses to configure as the remote end point of the
112 point-to-point link.  (Further remote addresses can be configured as
113 host routes: see below.)  IPv4 addresses are expected to be in
114 dotted-quad form; IPv6 addresses should be in RFC4291 hex-and-colons
115 form.
116 .hP 3.
117 Establish routes.  If addresses were configured, and
118 .I nets
119 is set, then
120 .I nets
121 is split into space-separated networks.  For each network, of the form
122 .IB address / mask \fR,
123 a route is configured to the given network, via the remote address of
124 the link, over the tunnel interface.  The
125 .IR address es
126 may be IPv4 or IPv6 addresses.  If the interface has only an IPv4
127 address then IPv6 routes will be ignored, and
128 .IR "vice versa" .
129 .hP 4.
130 Configure the interface MTU and bring it up.  The
131 interface MTU is configured based on the path MTU to the peer's external
132 address and the cryptographic algorithms in use by the
133 .BR tripe (8)
134 server; this can be overridden by setting the
135 .I mtu
136 key.
137 .hP 5.
138 Invoke user hook.  If
139 .I ifupextra
140 is set, it is interpreted as a Bourne shell command and evaluated.
141 .hP 6.
142 Notify services.  A notification
143 .RS
144 .IP
145 .B USER tripe-ifup configured
146 .I peer
147 .PP
148 is issued.
149 .RE
150 .
151 .\"--------------------------------------------------------------------------
152 .SH "SEE ALSO"
153 .
154 .BR peers.in (5),
155 .BR watch (8),
156 .BR tripe (8).
157 .
158 .\"--------------------------------------------------------------------------
159 .SH "AUTHOR"
160 .
161 Mark Wooding, <mdw@distorted.org.uk>
162 .
163 .\"----- That's all, folks --------------------------------------------------