ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/gvpe/doc/vped.conf.5.pod
Revision: 1.9
Committed: Mon May 10 18:57:07 2004 UTC (20 years ago) by pcg
Branch: MAIN
CVS Tags: VPE-1_6_1, VPE_1_6
Changes since 1.8: +11 -3 lines
Log Message:
*** empty log message ***

File Contents

# User Rev Content
1 pcg 1.1 =head1 NAME
2    
3     vped.conf - vpe daemon configuration file
4    
5     =head1 SYNOPSIS
6    
7 pcg 1.9 enable-udp = yes
8 pcg 1.1 udp-port = 407
9     mtu = 1492
10     ifname = vpn0
11 pcg 1.2
12 pcg 1.1 node = branch1
13     hostname = 1.2.3.4
14    
15     node = branch2
16     hostname = www.example.net
17     udp-port = 500 # this host uses a different udp-port
18    
19     node = branch3
20     connect = ondemand
21    
22     =head1 DESCRIPTION
23    
24     The vpe config file consists of a series of lines that contain C<variable
25     = value> pairs. Empty lines are ignored. Comments start with a C<#> and
26     extend to the end of the line. They can be used on their own lines, or
27     after any directives. Spaces are allowed before or after the C<=> sign or
28     after values, but not within the variable names or values themselves.
29    
30     The only exception to the above is the "on" directive that can prefix any
31     C<name = value> setting and will only "execute" it on the named node, or
32     (if the nodename starts with "!") on all nodes except the named one.
33    
34     name = value
35     on branch1 loglevel = noise
36     on !branch2 connect = ondemand
37    
38     All settings are executed "in order", that is, later settings of the same
39     variable overwrite earlier ones.
40    
41     =head1 ANATOMY OF A CONFIG FILE
42    
43     Usually, a config file starts with global settings (like the udp port to
44     listen on), followed by node-specific sections that begin with a C<node =
45     nickname> line.
46    
47     Every node that is part of the network must have a section that starts
48     with C<node = nickname>. The number and order of the nodes is important
49     and must be the same on all hosts. It is not uncommon for node sections to
50     be completely empty - if the default values are right.
51    
52     Node-specific settings can be used at any time. If used before the first
53     node section they will set the default values for all following nodes.
54    
55     =head1 CONFIG VARIABLES
56    
57     =head2 GLOBAL SETTINGS
58    
59     Global settings will affect the behaviour of the running vped daemon, that
60     is, they are in some sense node-specific (config files can set different
61     values on different nodes using C<on>), but will affect the behaviour of
62     the vped daemon and all connections it creates.
63    
64     =over 4
65    
66     =item loglevel = noise|trace|debug|info|notice|warn|error|critical
67    
68     Set the logging level. Connection established messages are logged at level
69     C<info>, notable errors are logged with C<error>. Default is C<info>.
70    
71     =item node = nickname
72    
73     Not really a config setting but introduces a node section. The nickname is
74     used to select the right configuration section and must be passed as an
75     argument to the vped daemon.
76    
77     =item private-key = relative-path-to-key
78    
79     Sets the path (relative to the config directory) to the private key
80     (default: C<hostkey>). This is a printf format string so every C<%> must
81     be doubled. A single C<%s> is replaced by the hostname, so you could
82     use paths like C<hostkeys/%s> to fetch the files at the location where
83     C<vpectrl> puts them.
84    
85     Since only the private key file of the current node is used and the
86     private key file should be kept secret per-host to avoid spoofings, it is
87     not recommended to use this feature.
88    
89     =item ifpersist = yes|true|on | no|false|off
90    
91     Should the tun/tap device be made persistent, that is, should the device
92     stay up even when vped exits? Some versions of the tunnel device have
93     problems sending packets when vped is restarted in persistent mode, so
94     if the connections can be established but you cannot send packets from
95     the local node, try to set this to C<off> and do an ifconfig down on the
96     device.
97    
98     =item ifname = devname
99    
100     Sets the tun interface name to the given name. The default is OS-specific
101     and most probably something like C<tun0>.
102    
103     =item rekey = seconds
104    
105     Sets the rekeying interval in seconds (default: C<3600>). Connections are
106     reestablished every C<rekey> seconds.
107    
108     =item keepalive = seconds
109    
110     Sets the keepalive probe interval in seconds (default: C<60>). After this
111     many seconds of inactivity the daemon will start to send keepalive probe
112     every 5 seconds until it receives a reply from the other end. If no reply
113     is received within 30 seconds, the peer is considered unreachable and the
114     connection is closed.
115    
116     =item mtu = bytes
117    
118     Sets the maximum MTU that should be used on outgoing packets (basically
119     the MTU of the outgoing interface) The daemon will automatically calculate
120     maximum overhead (e.g. udp header size, encryption blocksize...) and pass
121     this information to the C<if-up> script.
122    
123     Recommended values are 1500 (ethernet), 1492 (pppoe), 1472 (pptp).
124    
125     This value must be the minimum of the mtu values of all hosts.
126    
127     =item ip-proto = numerical-ip-protocol
128    
129     Sets the protocol number to be used for the rawip protocol. This is a
130     global option because all hosts must use the same protocol, and since
131     there are no port numbers, you cannot easily run more than one vped
132     instance using the same protocol, nor can you share the protocol with
133     other programs.
134    
135     The default is 47 (GRE), which has a good chance of tunneling through
136     firewalls (but note that the rawip protocol is not GRE compatible). Other
137     common choices are 50 (IPSEC, ESP), 51 (IPSEC, AH), 4 (IPIP tunnels) or 98
138     (ENCAP, rfc1241)
139    
140     =item if-up = relative-or-absolute-path
141    
142     Sets the path of a script that should be called immediately after the
143     network interface is initialized (but not neccessarily up). The following
144     environment variables are passed to it (the values are just examples):
145    
146     =over 4
147    
148     =item CONFBASE=/etc/vpe
149    
150     The configuration base directory.
151    
152     =item IFNAME=vpn0
153    
154     The interface to initialize.
155    
156     =item MTU=1436
157    
158     The MTU to set the interface to. You can use lower values (if done
159     consistently on all hosts), but this is usually ineffective.
160    
161     =item MAC=fe:fd:80:00:00:01
162    
163     The MAC address to set the interface to. The script *must* set the
164 pcg 1.6 interface MAC to this value. You will most likely use one of these:
165 pcg 1.1
166 pcg 1.6 ip link set $IFNAME address $MAC mtu $MTU up # GNU/Linux
167     ifconfig $IFNAME ether $MAC mtu $MTU up # FreeBSD
168    
169 pcg 1.8 Please see the C<vpe.osdep(5)> manpage for platform-specific information.
170    
171     =item IFTYPE=native # or tincd
172 pcg 1.6
173     =item IFSUBTYPE=linux # or freebsd, darwin etc..
174    
175     The interface type (C<native> or C<tincd>) and the subtype (usually the os
176     name in lowercase) that this vpe was configured for. Can be used to select
177     the correct syntax to use for network-related commands.
178 pcg 1.1
179     =item NODENAME=branch1
180    
181     The nickname of the current node, as passed to the vped daemon.
182    
183     =item NODEID=1
184    
185     The numerical node id of the current node. The first node mentioned in the
186     config file gets ID 1, the second ID 2 and so on.
187    
188     =back
189    
190     Here is a simple if-up script:
191    
192     #!/bin/sh
193     ip link set $IFNAME address $MAC mtu $MTU up
194     [ $NODENAME = branch1 ] && ip addr add 10.0.0.1 dev $IFNAME
195     [ $NODENAME = branch2 ] && ip addr add 10.1.0.1 dev $IFNAME
196     ip route add 10.0.0.0/8 dev $IFNAME
197    
198     More complicated examples (using routing to reduce arp traffic) can be
199     found in the etc/ subdirectory of the distribution.
200    
201     =item node-up = relative-or-absolute-path
202    
203     Sets a command (default: no script) that should be called whenever a
204     connection is established (even on rekeying operations). In addition
205     to the variables passed to C<if-up> scripts, the following environment
206     variables will be set:
207    
208     =over 4
209    
210     =item DESTNODE=branch2
211    
212     The name of the remote node.
213    
214     =item DESTID=2
215    
216     The node id of the remote node.
217    
218     =item DESTIP=188.13.66.8
219    
220     The numerical IP address of the remote host (vped accepts connections from
221     everywhere, as long as the other host can authenticate itself).
222    
223 pcg 1.7 =item DESTPORT=655 # deprecated
224 pcg 1.1
225     The UDP port used by the other side.
226    
227     =item STATE=UP
228    
229     Node-up scripts get called with STATE=UP, node-down scripts get called
230     with STATE=DOWN.
231    
232     =back
233    
234     Here is a nontrivial example that uses nsupdate to update the name => ip
235     mapping in some dns zone:
236    
237     #!/bin/sh
238     {
239     echo update delete $DESTNODE.lowttl.example.net. a
240     echo update add $DESTNODE.lowttl.example.net. 1 in a $DESTIP
241     echo
242     } | nsupdate -d -k $CONFBASE:key.example.net.
243    
244     =item node-down = relative-or-absolute-path
245    
246     Same as C<node-up>, but gets called whenever a connection is lost.
247    
248 pcg 1.4 =item http-proxy-host = hostname/ip
249    
250 pcg 1.5 The C<http-proxy-*> family of options are only available if vpe was
251 pcg 1.4 compiled with the C<--enable-http-proxy> option and enable tunneling of
252     tcp connections through a http proxy server.
253    
254     C<http-proxy-host> and C<http-proxy-port> should specify the hostname and
255     port number of the proxy server. See C<http-proxy-loginpw> if your proxy
256     requires authentication.
257    
258     Please note that vpe will still try to resolve all hostnames in the
259     configuration file, so if you are behind a proxy without access to a dns
260     server better use numerical IP addresses.
261    
262     To make best use of this option disable all protocols except tcp in your
263     config file and make sure your routers (or all other hosts) are listening
264     on a port that the proxy allows (443, https, is a common choice).
265    
266     If you have a router, connecting to it will suffice. Otherwise tcp must be
267     enabled on all hosts.
268    
269     Example:
270    
271     http-proxy-host = proxy.example.com
272     http-proxy-port = 3128 # 8080 is another common choice
273     http-proxy-auth = schmorp:grumbeere
274    
275     =item http-proxy-port = proxy-tcp-port
276    
277     The port where your proxy server listens.
278    
279     =item http-proxy-auth = login:password
280    
281     The optional login and password used to authenticate to the proxy server,
282     seperated by a literal colon (C<:>). Only basic authentication is
283     currently supported.
284    
285 pcg 1.9 =item pid-file = path
286    
287     The path to the pid file to check and create (Default:
288    
289 pcg 1.1 =back
290    
291     =head2 NODE SPECIFIC SETTINGS
292    
293     The following settings are node-specific, that is, every node can have
294     different settings, even within the same vped instance. Settings that are
295     executed before the first node section set the defaults, settings that are
296     executed within a node section only apply to the given node.
297    
298     =over 4
299    
300     =item udp-port = port-number
301    
302 pcg 1.7 Sets the port number used by the UDP protocol (default: C<655>, not
303 pcg 1.1 officially assigned by IANA!).
304 pcg 1.3
305     =item tcp-port = port-number
306    
307 pcg 1.7 Similar to C<udp-port> (default: C<655>), but sets the TCP port number.
308 pcg 1.3
309     =item enable-rawip = yes|true|on | no|false|off
310    
311     Enable the RAW IPv4 transport using the C<ip-proto> protocol
312     (default: C<no>). This is the best choice, since the overhead per packet
313     is only 38 bytes, as opposed to UDP's 58 (or TCP's 60+).
314    
315     =item enable-udp = yes|true|on | no|false|off
316    
317 pcg 1.9 Enable the UDPv4 transport using the C<udp-port> port (default: C<yes>,
318     but this will change!). This is a good general choice since UDP tunnels
319     well through many firewalls.
320    
321     NOTE: Please specify C<enable-udp = yes> even though it is the default, as
322     some future version will have all protocols disabled by default.
323 pcg 1.3
324     =item enable-tcp = yes|true|on | no|false|off
325    
326     Enable the TCPv4 transport using the C<tcp-port> port
327     (default: C<no>). Support for this horribly unsuitable protocol is only
328     available when vpe was compiled using the C<--enable-tcp> option. Never
329     use this transport unless you really must, it is horribly ineffiecent and
330     resource-intensive compared to the other transports.
331 pcg 1.1
332     =item router-priority = positive-number
333    
334     Sets the router priority of the given host (default: C<0>, disabled). If
335     some host tries to connect to another host without a hostname, it asks
336     the router host for it's IP address. The router host is the one with the
337     highest priority that is currently reachable. Make sure all clients always
338     connect to the router hosts, otherwise conencting to them is impossible.
339    
340     =item connect = ondemand|never|always|disabled
341    
342     Sets the connect mode (default: C<always>). It can be C<always> (always
343     try to establish and keep a conenction to the given host), C<never>
344     (nevr initiate a connection to the given host, but accept connections),
345     C<ondemand> (try to establish a connection on the first packet sent, and
346     take it down after the keepalive interval) or C<disabled> (node is bad,
347     don't talk to it).
348    
349     =item inherit-tos = yes|true|on | no|false|off
350    
351     Wether to inherit the TOS settings of packets sent to the tunnel when
352     sending packets to this node (default: C<yes>). If set to C<yes> then
353     outgoing tunnel packets will have the same TOS setting as the packets sent
354     to the tunnel device, which is usually what you want.
355    
356     =item compress = yes|true|on | no|false|off
357    
358     Wether to compress data packets sent to this host (default: C<yes>).
359     Compression is really cheap even on slow computers and has no size
360     overhead at all, so enabling this is a good idea.
361    
362     =back
363    
364     =head1 CONFIG DIRECTORY LAYOUT
365    
366     The default (or recommended) directory layout for the config directory is:
367    
368     =over 4
369    
370     =item vped.conf
371    
372     The config file.
373    
374     =item if-up
375    
376     The if-up script
377    
378     =item node-up, node-down
379    
380     If used the node up or node-down scripts.
381    
382     =item hostkey
383    
384     The private key (taken from C<hostkeys/nodename>) of the current host.
385    
386     =item pubkey/nodename
387    
388     The public keys of the other nodes, one file per node.
389    
390     =back
391    
392     =head1 SEE ALSO
393    
394     vpe(5), vped(8), vpectrl(8).
395    
396     =head1 AUTHOR
397    
398     Marc Lehmann <vpe@plan9.de>
399