Add cluster_port parameter for Multiple clusters
[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<Bcluster_port> (int)
84
85 UDP cluster port (default: 32792). See the section on Clustering for more information.
86
87 =item B<cluster_interface> (string)
88
89 Interface for cluster packets (default: eth0).
90
91 =item B<cluster_mcast_ttl> (int)
92
93 TTL for multicast packets (default: 1).
94
95 =item B<cluster_hb_interval> (int)
96
97 Interval in tenths of a second between cluster heartbeat/pings.
98
99 =item B<cluster_hb_timeout> (int)
100
101 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.
102
103 =item B<cluster_master_min_adv> (int)
104
105 Determines the minumum number of up to date slaves required before the master will drop routes (default: 1).
106
107 =item B<debug> (int)
108
109 Set the level of debugging messages written to the log file. The value should
110 be between 0 and 5, with 0 being no debugging, and 5 being the highest.
111 A rough description of the levels is:
112
113 =over
114
115 =item 0. Critical Errors - Things are probably broken
116
117 =item 1. Errors - Things might have gone wrong, but probably will recover
118
119 =item 2. Warnings - Just in case you care what is not quite perfect
120
121 =item 3. Information - Parameters of control packets
122
123 =item 4. Calls - For tracing the execution of the code
124
125 =item 5. Packets - Everything, including a hex dump of all packets processed... probably twice
126
127 =back
128
129 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.
130
131 =item B<dump_speed> (boolean)
132
133 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.
134
135 =item B<disable_sending_hello> (boolean)
136
137 Disable l2tp sending HELLO message for Apple compatibility. Some OS X implementation of l2tp no manage the L2TP "HELLO message". (default: no).
138
139 =item B<echo_timeout> (int)
140
141 Time between last packet sent and LCP ECHO generation (default: 10 (seconds)).
142
143 =item B<guest_account>
144
145 Allow multiple logins matching this specific username.
146
147 =item B<icmp_rate> (int)
148
149 Maximum number of host unreachable ICMP packets to send per second.
150
151 =item B<idle_echo_timeout> (int)
152
153 Drop sessions who have not responded within idle_echo_timeout seconds (default: 240 (seconds))
154
155 =item B<iftun_address> (ip address)
156
157 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.
158
159 =item B<l2tp_mtu> (int)
160
161 MTU of interface for L2TP traffic (default: 1500). Used to set link MRU and adjust TCP MSS.
162
163 =item B<l2tp_secret> (string)
164
165 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.
166
167 =item B<lock_pages> (boolean)
168
169 Keep all pages mapped by the l2tpns process in memory.
170
171 =item B<log_file> (string)
172
173 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.
174
175 =item B<multi_read_count> (int)
176
177 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.
178
179 =item B<packet_limit> (int>
180
181 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).
182
183 =item B<peer_address> (ip address)
184
185 Address to send to clients as the default gateway.
186
187 =item B<pid_file> (string)
188
189 If set, the process id will be written to the specified file. The value must be an absolute path.
190
191 =item B<ppp_keepalive> (boolean)
192
193 Change this value to no to force generation of LCP ECHO every echo_timeout seconds, even there are activity on the link (default: yes)
194
195 =item B<ppp_restart_time> (int)
196
197 =item B<ppp_max_configure> (int)
198
199 =item B<ppp_max_failure> (int)
200
201 PPP counter and timer values, as described in Section 4.1 of RFC1661.
202
203 I<ppp_restart_time>, Restart timer for PPP protocol negotiation in seconds (default: 3).
204
205 I<ppp_max_configure>, Number of configure requests to send before giving up (default: 10).
206
207 I<ppp_max_failure>, Number of Configure-Nak requests to send before sending a Configure-Reject (default: 5).
208
209 =item B<primary_dns> (ip address), B<secondary_dns> (ip address)
210
211 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.
212
213 =item B<primary_radius> (ip address), B<secondary_radius> (ip address)
214
215 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.
216
217 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).
218
219 =item B<primary_radius_port> (short), B<secondary_radius_port> (short)
220
221 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.
222
223 =item B<radius_accounting> (boolean)
224
225 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.
226
227 =item B<radius_interim> (int)
228
229 If radius_accounting is on, defines the interval between sending of RADIUS interim accounting records (in seconds).
230
231 =item B<radius_secret> (string)
232
233 This secret will be used in all RADIUS queries. If this is not set then RADIUS queries will fail.
234
235 =item B<radius_authtypes> (string)
236
237 A comma separated list of supported RADIUS authentication methods ("pap" or "chap"), in order of preference (default "pap").
238
239 =item B<radius_dae_port> (short)
240
241 Port for DAE RADIUS (Packet of Death/Disconnect, Change of Authorization) requests (default: 3799).
242
243 =item B<radius_bind_min>, B<radius_bind_max> (int)
244
245 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).
246
247 =item B<random_device> (string)
248
249 Path to random data source (default /dev/urandom). Use "" to use the rand() library function.
250
251 =item B<scheduler_fifo> (boolean)
252
253 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.
254
255 =item B<send_garp> (boolean)
256
257 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.
258
259 =item B<tundevicename> (string)
260
261 Name of the tun interface (default: "tun0").
262
263 =item B<throttle_speed> (int)
264
265 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.
266
267 =item B<throttle_buckets> (int)
268
269 Number of token buckets to allocate for throttling. Each throttled session requires two buckets (in and out).
270
271 =back
272
273 =head2 DHCPv6 And IPv6 SETTINGS
274
275 =over
276
277 =item B<dhcp6_preferred_lifetime> (int)
278
279 The preferred lifetime for the IPv6 address and the IPv6 prefix address, expressed in units of seconds (see rfc3315).
280
281 =item B<dhcp6_valid_lifetime> (int)
282
283 The valid lifetime for the IPv6 address and the IPv6 prefix address, expressed in units of seconds (see rfc3315).
284
285 =item B<dhcp6_server_duid> (int)
286
287 DUID Based on Link-layer Address (DUID-LL) (see rfc3315).
288
289 =item B<primary_ipv6_dns>, B<secondary_ipv6_dns> (Ipv6 address)
290
291 IPv6 DNS servers will be sent to the user (see rfc3646). 
292
293 =item B<default_ipv6_domain_list> (string)
294
295 The Domain Search List (ex: "fdn.fr") (see rfc3646).
296
297 =item B<ipv6_prefix> (Ipv6 address)
298
299 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.
300
301 =back
302
303 =head2 LAC SETTINGS
304
305 =over
306
307 =item B<bind_address_remotelns> (ip address)
308
309 Address of the interface to listen the remote LNS tunnels. If no address is given, all interfaces are listened (Any Address).
310
311 =item B<bind_portremotelns> (short)
312
313 Port to bind for the Remote LNS (default: 65432).
314
315 =back
316
317 A static REMOTES LNS configuration can be entered by the command:
318
319 =over
320
321 =item B<setforward> I<MASK> I<IP> I<PORT> I<SECRET>
322
323 where MASK specifies the mask of users who have forwarded to remote LNS (ex: "/friendISP@company.com").
324
325 where IP specifies the IP of the remote LNS (ex: "66.66.66.55").
326
327 where PORT specifies the L2TP Port of the remote LNS (Normally should be 1701) (ex: 1701).
328
329 where SECRET specifies the secret password the remote LNS (ex: mysecret).
330
331 =back 
332
333 The static REMOTE LNS configuration can be used when the friend ISP not have a proxied Radius.
334
335 If a proxied Radius is used, It will return the RADIUS attributes:
336
337 =over
338
339 =item Tunnel-Type:1 = L2TP
340
341 =item Tunnel-Medium-Type:1 = IPv4
342
343 =item Tunnel-Password:1 = "LESECRETL2TP"
344
345 =item Tunnel-Server-Endpoint:1 = "88.xx.xx.x1"
346
347 =item Tunnel-Assignment-Id:1 = "friendisp_lns1"
348
349 =item Tunnel-Type:2 += L2TP
350
351 =item Tunnel-Medium-Type:2 += IPv4
352
353 =item Tunnel-Password:2 += "LESECRETL2TP"
354
355 =item Tunnel-Server-Endpoint:2 += "88.xx.xx.x2"
356
357 =item Tunnel-Assignment-Id:2 += "friendisp_lns2"
358
359 =back
360
361 =head2 PPPOE SETTINGS
362
363 =over
364
365 =item B<pppoe_if_to_bind> (string)
366
367 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).
368
369 =item B<pppoe_service_name> (string)
370
371 PPPOE service name (default: NULL).
372
373 =item B<pppoe_ac_name> (string)
374
375 PPPOE access concentrator name (default: "l2tpns-pppoe").
376
377 =item B<pppoe_only_equal_svc_name> (boolean)
378
379 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).
380
381 =back
382
383 =head2 BGP ROUTING
384
385 The routing configuration section is entered by the command
386
387 B<router> B<bgp> I<as>
388
389 where I<as> specifies the local AS number.
390
391 Subsequent lines prefixed with B<neighbour> I<peer> define the attributes of BGP neighhbours. Valid commands are:
392
393 B<neighbour> I<peer> B<remote-as> I<as>
394
395 B<neighbour> I<peer> B<timers> I<keepalive> I<hold>
396
397 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.
398
399 =head2 NAMED ACCESS LISTS
400
401 Named access lists may be defined with either of
402
403 =over
404
405 =item
406
407 B<ip> B<access-list> B<standard> I<name>
408
409 =item
410
411 B<ip> B<access-list> B<extended> I<name>
412
413 =back
414
415 Subsequent lines starting with permit or deny define the body of the access-list.
416
417 =head3 Standard Access Lists
418
419 Standard access lists are defined with:
420
421 =over
422
423 =item
424
425 {B<permit>|B<deny>} I<source> [I<dest>]
426
427 =back
428
429 Where I<source> and I<dest> specify IP matches using one of:
430
431 =over
432
433 =item
434
435 I<address> I<wildard>
436
437 =item
438
439 B<host> I<address>
440
441 =item
442
443 B<any>
444
445 =back
446
447 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).
448
449 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>'.
450
451 =head3 Extended Access Lists
452
453 Extended access lists are defined with:
454
455 =over
456
457 =item
458
459 {B<permit>|B<deny>} I<proto> I<source> [I<ports>] I<dest> [I<ports>] [I<flags>]
460
461 =back
462
463 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.
464
465 For TCP and UDP matches, source and destination may be optionally followed by a ports specification:
466
467 =over
468
469 =item
470
471 {B<eq|neq|gt|lt>} I<port>
472
473 =item
474
475 B<range> I<from> I<to>
476
477 =back
478
479 I<flags> may be one of:
480
481 =over
482
483 =item {B<match-any|match-all>} {B<+|->}{B<fin|syn|rst|psh|ack|urg>} ...
484
485 Match packets with any or all of the tcp flags set (+) or clear (-).
486
487 =item B<established>
488
489 Match "established" TCP connections: packets with RST or ACK set, and SYN clear.
490
491 =item B<fragments>
492
493 Match IP fragments. May not be specified on rules with layer 4 matches.
494
495 =back
496
497 =head1 SEE ALSO
498
499 L<l2tpns(8)>
500
501 =cut