chiark - git - mdw - tripe/blob - 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 8tripe "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 with optional prefix lengths; there may be any number of either.  If
 108 .I raddr
 109 is set, it should be a list IPv4 and/or an IPv6 addresses, with optional
 110 prefix lengths, separated by space: these are the addresses to
 111 configure as the remote end point of the point-to-point link.  (Further
 112 remote addresses can be configured as host routes: see below.)  IPv4
 113 addresses are expected to be in dotted-quad form; IPv6 addresses should
 114 be in RFC4291 hex-and-colons form.
 115 .hP 3.
 116 Establish routes.  If addresses were configured, and
 117 .I nets
 118 is set, then
 119 .I nets
 120 is split into space-separated networks.  For each network, of the form
 121 .IB address / mask \fR,
 122 a route is configured to the given network, via the remote address of
 123 the link, over the tunnel interface.  The
 124 .IR address es
 125 may be IPv4 or IPv6 addresses.  If the interface has only an IPv4
 126 address then IPv6 routes will be ignored, and
 127 .IR "vice versa" .
 128 .RS
 129 .PP
 130 If any configuration commands fail, a warning
 131 .IP
 132 .B USER tripe-ifup command-failed
 133 .BI rc= rc
 134 .I command
 135 .PP
 136 is issued.
 137 .RE
 138 .hP 4.
 139 Configure the interface MTU and bring it up.  The
 140 interface MTU is configured based on the path MTU to the peer's external
 141 address and the cryptographic algorithms in use by the
 142 .BR tripe (8)
 143 server; this can be overridden by setting the
 144 .I mtu
 145 key.
 146 .hP 5.
 147 Invoke user hook.  If
 148 .I ifupextra
 149 is set, it is interpreted as a Bourne shell command and evaluated.
 150 .hP 6.
 151 Notify services.  A notification
 152 .RS
 153 .IP
 154 .B USER tripe-ifup configured
 155 .I peer
 156 .RB [ failed ]
 157 .PP
 158 is issued: the
 159 .B failed
 160 token is included if any of the configuration commands failed.
 161 .RE
 162 .
 163 .\"--------------------------------------------------------------------------
 164 .SH "SEE ALSO"
 165 .
 166 .BR peers.in (5),
 167 .BR watch (8),
 168 .BR tripe (8).
 169 .
 170 .\"--------------------------------------------------------------------------
 171 .SH "AUTHOR"
 172 .
 173 Mark Wooding, <mdw@distorted.org.uk>
 174 .
 175 .\"----- That's all, folks --------------------------------------------------