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