Add DHCPv6 functionality.
[l2tpns.git] / Docs / startup-config.5.pod
1 =pod
2
3 =head1 NAME
4
5 startup-config - configuration file for l2tpns
6
7 =head1 SYNOPSIS
8
9 /etc/l2tpns/startup-config
10
11 =head1 DESCRIPTION
12
13 B<startup-config> is the configuration file for B<l2tpns>
14
15 The format is plain text, in the same format as accepted by
16 the configuration mode of l2tpns's telnet administrative 
17 interface. Comments are indicated by either the character # or !.
18
19 =head2 SETTINGS
20
21 Settings are specified with
22
23 =over
24
25 =item B<set> F<variable> F<value>
26
27 =back
28
29 A list of the possible configuration directives follows. Each of these should be set by a line like:
30
31 =over
32
33 =item B<set> I<configstring> I<"value">
34
35 =item B<set> I<ipaddress> I<192.168.1.1>
36
37 =item B<set> I<boolean> I<true>
38
39 =back
40
41 The following F<variables> may be set:
42
43 =over
44
45 =item B<accounting_dir> (string)
46
47 If set to a directory, then every 5 minutes the current usage for every connected use will be dumped to a file in this directory. Each file dumped begins with a header, where each line is prefixed by #. Following the header is a single line for every connected user, fields separated by a space.
48
49 The fields are username, ip, qos, uptxoctets, downrxoctets, origin (optional). The qos field is 1 if a standard user, and 2 if the user is throttled. The origin field is dump if B<account_all_origin> is set to true (origin value: L=LAC data, R=Remote LNS data, P=PPPOE data).
50
51 =item B<account_all_origin> (boolean)
52
53 If set to true, all origin of the usage is dumped to the accounting file (LAC+Remote LNS+PPPOE)(default false).
54
55 =item B<allow_duplicate_users> (boolean)
56
57 Allow multiple logins with the same username. If false (the default), any prior session with the same username will be dropped when a new session is established.
58
59 =item B<auth_tunnel_change_addr_src> (boolean)
60
61 This parameter authorize to change the source IP of the tunnels l2tp. This parameter can be used when the remotes BAS/LAC are l2tpns server configured in cluster mode, but that the interface to remote LNS are not clustered (the tunnel can be coming from different source IP) (default: no).
62
63 =item B<bind_address> (ip address)
64
65 It's the listen address of the l2tp udp protocol sent and received to LAC. This address is also assigned to the tun interface if no iftun_address is specified. Packets containing user traffic should be routed via this address if given, otherwise the primary address of the machine.
66
67 =item B<bind_multi_address> (ip address)
68
69 This parameter permit to listen several addresss of the l2tp udp protocol (and set several address to the tun interface).
70
71 WHEN this parameter is set, It OVERWRITE the parameters "bind_address" and "iftun_address".
72
73 these can be interesting when you want do load-balancing in cluster mode of the uploaded from the LAC. For example you can set a bgp.prepend(MY_AS) for Address1 on LNS1 and a bgp.prepend(MY_AS) for Address2 on LNS2 (see BGP AS-path prepending).
74
75 example of use with 2 address:
76
77 B<set> I<bind_multi_address> "64.14.13.41, 64.14.13.42"
78
79 =item B<cluster_address> (ip address)
80
81 Multicast cluster address (default: 239.192.13.13). See the section on Clustering for more information.
82
83 =item B<cluster_interface> (string)
84
85 Interface for cluster packets (default: eth0).
86
87 =item B<cluster_mcast_ttl> (int)
88
89 TTL for multicast packets (default: 1).
90
91 =item B<cluster_hb_interval> (int)
92
93 Interval in tenths of a second between cluster heartbeat/pings.
94
95 =item B<cluster_hb_timeout> (int)
96
97 Cluster heartbeat timeout in tenths of a second. A new master will be elected when this interval has been passed without seeing a heartbeat from the master.
98
99 =item B<cluster_master_min_adv> (int)
100
101 Determines the minumum number of up to date slaves required before the master will drop routes (default: 1).
102
103 =item B<debug> (int)
104
105 Set the level of debugging messages written to the log file. The value should
106 be between 0 and 5, with 0 being no debugging, and 5 being the highest.
107 A rough description of the levels is:
108
109 =over
110
111 =item 0. Critical Errors - Things are probably broken
112
113 =item 1. Errors - Things might have gone wrong, but probably will recover
114
115 =item 2. Warnings - Just in case you care what is not quite perfect
116
117 =item 3. Information - Parameters of control packets
118
119 =item 4. Calls - For tracing the execution of the code
120
121 =item 5. Packets - Everything, including a hex dump of all packets processed... probably twice
122
123 =back
124
125 Note that the higher you set the debugging level, the slower the program will run. Also, at level 5 a LOT of information will be logged. This should only ever be used for working out why it doesn't work at all.
126
127 =item B<dump_speed> (boolean)
128
129 If set to true, then the current bandwidth utilization will be logged every second. Even if this is disabled, you can see this information by running the uptime command on the CLI.
130
131 =item B<disable_sending_hello> (boolean)
132
133 Disable l2tp sending HELLO message for Apple compatibility. Some OS X implementation of l2tp no manage the L2TP "HELLO message". (default: no).
134
135 =item B<echo_timeout> (int)
136
137 Time between last packet sent and LCP ECHO generation (default: 10 (seconds)).
138
139 =item B<guest_account>
140
141 Allow multiple logins matching this specific username.
142
143 =item B<icmp_rate> (int)
144
145 Maximum number of host unreachable ICMP packets to send per second.
146
147 =item B<idle_echo_timeout> (int)
148
149 Drop sessions who have not responded within idle_echo_timeout seconds (default: 240 (seconds))
150
151 =item B<iftun_address> (ip address)
152
153 This parameter is used when you want a tun interface address different from the address of "bind_address" (For use in cases of specific configuration). If no address is given to iftun_address and bind_address, 1.1.1.1 is used.
154
155 =item B<l2tp_mtu> (int)
156
157 MTU of interface for L2TP traffic (default: 1500). Used to set link MRU and adjust TCP MSS.
158
159 =item B<l2tp_secret> (string)
160
161 The secret used by l2tpns for authenticating tunnel request. Must be the same as the LAC, or authentication will fail. Only actually be used if the LAC requests authentication.
162
163 =item B<lock_pages> (boolean)
164
165 Keep all pages mapped by the l2tpns process in memory.
166
167 =item B<log_file> (string)
168
169 This will be where all logging and debugging information is written to.This may be either a filename, such as /var/log/l2tpns, or the string syslog:facility, where facility is any one of the syslog logging facilities, such as local5.
170
171 =item B<multi_read_count> (int)
172
173 Number of packets to read off each of the UDP and TUN fds when returned as readable by select (default: 10). Avoids incurring the unnecessary system call overhead of select on busy servers.
174
175 =item B<packet_limit> (int>
176
177 Maximum number of packets of downstream traffic to be handled each tenth of a second per session. If zero, no limit is applied (default: 0). Intended as a DoS prevention mechanism and not a general throttling control (packets are dropped, not queued).
178
179 =item B<peer_address> (ip address)
180
181 Address to send to clients as the default gateway.
182
183 =item B<pid_file> (string)
184
185 If set, the process id will be written to the specified file. The value must be an absolute path.
186
187 =item B<ppp_restart_time> (int)
188
189 =item B<ppp_max_configure> (int)
190
191 =item B<ppp_max_failure> (int)
192
193 PPP counter and timer values, as described in Section 4.1 of RFC1661.
194
195 I<ppp_restart_time>, Restart timer for PPP protocol negotiation in seconds (default: 3).
196
197 I<ppp_max_configure>, Number of configure requests to send before giving up (default: 10).
198
199 I<ppp_max_failure>, Number of Configure-Nak requests to send before sending a Configure-Reject (default: 5).
200
201 =item B<primary_dns> (ip address), B<secondary_dns> (ip address)
202
203 Whenever a PPP connection is established, DNS servers will be sent to the user, both a primary and a secondary. If either is set to 0.0.0.0, then that one will not be sent.
204
205 =item B<primary_radius> (ip address), B<secondary_radius> (ip address)
206
207 Sets the RADIUS servers used for both authentication and accounting. If the primary server does not respond, then the secondary RADIUS server will be tried.
208
209 Note: in addition to the source IP address and identifier, the RADIUS server must include the source port when detecting duplicates to supress (in order to cope with a large number of sessions comming on-line simultaneously l2tpns uses a set of udp sockets, each with a seperate identifier).
210
211 =item B<primary_radius_port> (short), B<secondary_radius_port> (short)
212
213 Sets the authentication ports for the primary and secondary RADIUS servers. The accounting port is one more than the authentication port. If no RADIUS ports are given, the authentication port defaults to 1645, and the accounting port to 1646.
214
215 =item B<radius_accounting> (boolean)
216
217 If set to true, then RADIUS accounting packets will be sent. This means that a B<Start> record will be sent when the session is successfully authenticated, and a B<Stop> record will be sent when the session is closed.
218
219 =item B<radius_interim> (int)
220
221 If radius_accounting is on, defines the interval between sending of RADIUS interim accounting records (in seconds).
222
223 =item B<radius_secret> (string)
224
225 This secret will be used in all RADIUS queries. If this is not set then RADIUS queries will fail.
226
227 =item B<radius_authtypes> (string)
228
229 A comma separated list of supported RADIUS authentication methods ("pap" or "chap"), in order of preference (default "pap").
230
231 =item B<radius_dae_port> (short)
232
233 Port for DAE RADIUS (Packet of Death/Disconnect, Change of Authorization) requests (default: 3799).
234
235 =item B<radius_bind_min>, B<radius_bind_max> (int)
236
237 Define a port range in which to bind sockets used to send and receive RADIUS packets. Must be at least RADIUS_FDS (64) wide. Simplifies firewalling of RADIUS ports (default: dynamically assigned).
238
239 =item B<random_device> (string)
240
241 Path to random data source (default /dev/urandom). Use "" to use the rand() library function.
242
243 =item B<scheduler_fifo> (boolean)
244
245 Sets the scheduling policy for the l2tpns process to SCHED_FIFO. This causes the kernel to immediately preempt any currently running SCHED_OTHER (normal) process in favour of l2tpns when it becomes runnable. Ignored on uniprocessor systems.
246
247 =item B<send_garp> (boolean)
248
249 Determines whether or not to send a gratuitous ARP for the bind_address when the server is ready to handle traffic (default: true). This value is ignored if BGP is configured.
250
251 =item B<tundevicename> (string)
252
253 Name of the tun interface (default: "tun0").
254
255 =item B<throttle_speed> (int)
256
257 Sets the default speed (in kbits/s) which sessions will be limited to. If this is set to 0, then throttling will not be used at all. Note: You can set this by the CLI, but changes will not affect currently connected users.
258
259 =item B<throttle_buckets> (int)
260
261 Number of token buckets to allocate for throttling. Each throttled session requires two buckets (in and out).
262
263 =back
264
265 =head2 DHCPv6 And IPv6 SETTINGS
266
267 =over
268
269 =item B<dhcp6_preferred_lifetime> (int)
270
271 The preferred lifetime for the IPv6 address and the IPv6 prefix address, expressed in units of seconds (see rfc3315).
272
273 =item B<dhcp6_valid_lifetime> (int)
274
275 The valid lifetime for the IPv6 address and the IPv6 prefix address, expressed in units of seconds (see rfc3315).
276
277 =item B<dhcp6_server_duid> (int)
278
279 DUID Based on Link-layer Address (DUID-LL) (see rfc3315).
280
281 =item B<primary_ipv6_dns>, B<secondary_ipv6_dns> (Ipv6 address)
282
283 IPv6 DNS servers will be sent to the user (see rfc3646). 
284
285 =item B<default_ipv6_domain_list> (string)
286
287 The Domain Search List (ex: "fdn.fr") (see rfc3646).
288
289 =item B<ipv6_prefix> (Ipv6 address)
290
291 Enable negotiation of IPv6. This forms the the first 64 bits of the client allocated address. The remaining 64 come from the allocated IPv4 address and 4 bytes of 0.
292
293 =back
294
295 =head2 LAC SETTINGS
296
297 =over
298
299 =item B<bind_address_remotelns> (ip address)
300
301 Address of the interface to listen the remote LNS tunnels. If no address is given, all interfaces are listened (Any Address).
302
303 =item B<bind_portremotelns> (short)
304
305 Port to bind for the Remote LNS (default: 65432).
306
307 =back
308
309 A static REMOTES LNS configuration can be entered by the command:
310
311 =over
312
313 =item B<setforward> I<MASK> I<IP> I<PORT> I<SECRET>
314
315 where MASK specifies the mask of users who have forwarded to remote LNS (ex: "/friendISP@company.com").
316
317 where IP specifies the IP of the remote LNS (ex: "66.66.66.55").
318
319 where PORT specifies the L2TP Port of the remote LNS (Normally should be 1701) (ex: 1701).
320
321 where SECRET specifies the secret password the remote LNS (ex: mysecret).
322
323 =back 
324
325 The static REMOTE LNS configuration can be used when the friend ISP not have a proxied Radius.
326
327 If a proxied Radius is used, It will return the RADIUS attributes:
328
329 =over
330
331 =item Tunnel-Type:1 = L2TP
332
333 =item Tunnel-Medium-Type:1 = IPv4
334
335 =item Tunnel-Password:1 = "LESECRETL2TP"
336
337 =item Tunnel-Server-Endpoint:1 = "88.xx.xx.x1"
338
339 =item Tunnel-Assignment-Id:1 = "friendisp_lns1"
340
341 =item Tunnel-Type:2 += L2TP
342
343 =item Tunnel-Medium-Type:2 += IPv4
344
345 =item Tunnel-Password:2 += "LESECRETL2TP"
346
347 =item Tunnel-Server-Endpoint:2 += "88.xx.xx.x2"
348
349 =item Tunnel-Assignment-Id:2 += "friendisp_lns2"
350
351 =back
352
353 =head2 PPPOE SETTINGS
354
355 =over
356
357 =item B<pppoe_if_to_bind> (string)
358
359 PPPOE server interface to bind (ex: "eth0.12"), If not specified the server PPPOE is not enabled. For the pppoe clustering, all the interfaces PPPOE of the clusters must use the same HW address (MAC address).
360
361 =item B<pppoe_service_name> (string)
362
363 PPPOE service name (default: NULL).
364
365 =item B<pppoe_ac_name> (string)
366
367 PPPOE access concentrator name (default: "l2tpns-pppoe").
368
369 =item B<pppoe_only_equal_svc_name> (boolean)
370
371 If set to yes, the PPPOE server only accepts clients with a "service-name" different from NULL and a "service-name" equal to server "service-name" (default: no).
372
373 =back
374
375 =head2 BGP ROUTING
376
377 The routing configuration section is entered by the command
378
379 B<router> B<bgp> I<as>
380
381 where I<as> specifies the local AS number.
382
383 Subsequent lines prefixed with B<neighbour> I<peer> define the attributes of BGP neighhbours. Valid commands are:
384
385 B<neighbour> I<peer> B<remote-as> I<as>
386
387 B<neighbour> I<peer> B<timers> I<keepalive> I<hold>
388
389 Where I<peer> specifies the BGP neighbour as either a hostname or IP address, I<as> is the remote AS number and I<keepalive>, I<hold> are the timer values in seconds.
390
391 =head2 NAMED ACCESS LISTS
392
393 Named access lists may be defined with either of
394
395 =over
396
397 =item
398
399 B<ip> B<access-list> B<standard> I<name>
400
401 =item
402
403 B<ip> B<access-list> B<extended> I<name>
404
405 =back
406
407 Subsequent lines starting with permit or deny define the body of the access-list.
408
409 =head3 Standard Access Lists
410
411 Standard access lists are defined with:
412
413 =over
414
415 =item
416
417 {B<permit>|B<deny>} I<source> [I<dest>]
418
419 =back
420
421 Where I<source> and I<dest> specify IP matches using one of:
422
423 =over
424
425 =item
426
427 I<address> I<wildard>
428
429 =item
430
431 B<host> I<address>
432
433 =item
434
435 B<any>
436
437 =back
438
439 I<address> and I<wildard> are in dotted-quad notation, bits in the I<wildard> indicate which address bits in I<address> are relevant to the match (0 = exact match; 1 = don't care).
440
441 The shorthand 'host address' is equivalent to 'I<address> B<0.0.0.0>'; 'B<any>' to 'B<0.0.0.0> B<255.255.255.255>'.
442
443 =head3 Extended Access Lists
444
445 Extended access lists are defined with:
446
447 =over
448
449 =item
450
451 {B<permit>|B<deny>} I<proto> I<source> [I<ports>] I<dest> [I<ports>] [I<flags>]
452
453 =back
454
455 Where I<proto> is one of B<ip>, B<tcp> or B<udp>, and I<source> and I<dest> are as described above for standard lists.
456
457 For TCP and UDP matches, source and destination may be optionally followed by a ports specification:
458
459 =over
460
461 =item
462
463 {B<eq|neq|gt|lt>} I<port>
464
465 =item
466
467 B<range> I<from> I<to>
468
469 =back
470
471 I<flags> may be one of:
472
473 =over
474
475 =item {B<match-any|match-all>} {B<+|->}{B<fin|syn|rst|psh|ack|urg>} ...
476
477 Match packets with any or all of the tcp flags set (+) or clear (-).
478
479 =item B<established>
480
481 Match "established" TCP connections: packets with RST or ACK set, and SYN clear.
482
483 =item B<fragments>
484
485 Match IP fragments. May not be specified on rules with layer 4 matches.
486
487 =back
488
489 =head1 SEE ALSO
490
491 L<l2tpns(8)>
492
493 =cut