| 1 |
<h1 id="overview">Overview</h1> |
| 2 |
<p><code>l2tpns</code> is half of a complete L2TP implementation. It |
| 3 |
supports only the LNS side of the connection.</p> |
| 4 |
<p>L2TP (Layer 2 Tunneling Protocol) is designed to allow any layer 2 |
| 5 |
protocol (e.g. Ethernet, PPP) to be tunneled over an IP connection. |
| 6 |
<code>l2tpns</code> implements PPP over L2TP only.</p> |
| 7 |
<p>There are a couple of other L2TP implementations, of which <a |
| 8 |
href="http://sourceforge.net/projects/l2tpd">l2tpd</a> is probably the |
| 9 |
most popular. l2tpd also will handle being either end of a tunnel, and |
| 10 |
is a lot more configurable than <code>l2tpns</code>. However, due to the |
| 11 |
way it works, it is nowhere near as scalable.</p> |
| 12 |
<p><code>l2tpns</code> uses the TUN/TAP interface provided by the Linux |
| 13 |
kernel to receive and send packets. Using some packet manipulation it |
| 14 |
doesn't require a single interface per connection, as l2tpd does.</p> |
| 15 |
<p>This allows it to scale extremely well to very high loads and very |
| 16 |
high numbers of connections.</p> |
| 17 |
<p>It also has a plugin architecture which allows custom code to be run |
| 18 |
during processing. An example of this is in the walled garden module |
| 19 |
included.</p> |
| 20 |
<h1 id="installation">Installation</h1> |
| 21 |
<h2 id="installation-requirements">Requirements</h2> |
| 22 |
<ul> |
| 23 |
<li><p>Linux kernel version 2.4 or above, with the Tun/Tap interface |
| 24 |
either compiled in, or as a module.</p></li> |
| 25 |
<li><p>libcli 1.8.5 or greater. You can get this from <a |
| 26 |
href="http://sourceforge.net/projects/libcli">SourceForge</a></p></li> |
| 27 |
</ul> |
| 28 |
<h2 id="installation-compile">Compiling</h2> |
| 29 |
<p>You can generally get away with just running <code>make</code> from |
| 30 |
the source directory. This will compile the daemon, associated tools and |
| 31 |
any modules shipped with the distribution.</p> |
| 32 |
<h2 id="installation-install">Installing</h2> |
| 33 |
<p>After you have successfully compiled everything, run |
| 34 |
<code>make install</code> to install it. By default, the binaries are |
| 35 |
installed into <code>/usr/sbin</code>, the configuration into |
| 36 |
<code>/etc/l2tpns</code>, and the modules into |
| 37 |
<code>/usr/lib/l2tpns</code>.</p> |
| 38 |
<p>You will definately need to edit the configuration files before you |
| 39 |
start. See <a href="#configuration">Configuration</a> for more |
| 40 |
information.</p> |
| 41 |
<h2 id="installation-run">Running</h2> |
| 42 |
<p>You only need to run <code>/usr/sbin/l2tpns</code> as root to start |
| 43 |
it. It does not normally detach to a daemon process (see the |
| 44 |
<code>-d</code> option), so you should perhaps run it from |
| 45 |
<code>init</code>.</p> |
| 46 |
<p>By default there is no log destination set, so all log messages will |
| 47 |
go to stdout.</p> |
| 48 |
<h1 id="configuration">Configuration</h1> |
| 49 |
<p>All configuration of the software is done from the files installed |
| 50 |
into <code>/etc/l2tpns</code>.</p> |
| 51 |
<h2 id="config-startup"><code>startup-config</code></h2> |
| 52 |
<p>This is the main configuration file for <code>l2tpns</code>. The |
| 53 |
format of the file is a list of commands that can be run through the |
| 54 |
command-line interface. This file can also be written directly by the |
| 55 |
<code>l2tpns</code> process if a user runs the <code>write memory</code> |
| 56 |
command, so any comments will be lost. However if your policy is not to |
| 57 |
write the config by the program, then feel free to comment the file with |
| 58 |
a <code>#</code> or <code>!</code> at the beginning of the line.</p> |
| 59 |
<p>A list of the possible configuration directives follows. Each of |
| 60 |
these should be set by a line like: set configstring "value" set |
| 61 |
ipaddress 192.168.1.1 set boolean true</p> |
| 62 |
<dl> |
| 63 |
<dt><code>debug</code> (int)</dt> |
| 64 |
<dd> |
| 65 |
<p>Sets the level of messages that will be written to the log file. The |
| 66 |
value should be between 0 and 5, with 0 being no debugging, and 5 being |
| 67 |
the highest. A rough description of the levels is:</p> |
| 68 |
<dl> |
| 69 |
<dt><code>0</code>: Critical Errors</dt> |
| 70 |
<dd> |
| 71 |
<p>Things are probably broken</p> |
| 72 |
</dd> |
| 73 |
<dt><code>1</code>: Errors</dt> |
| 74 |
<dd> |
| 75 |
<p>Things might have gone wrong, but probably will recover</p> |
| 76 |
</dd> |
| 77 |
<dt><code>2</code>: Warnings</dt> |
| 78 |
<dd> |
| 79 |
<p>Just in case you care what is not quite perfect</p> |
| 80 |
</dd> |
| 81 |
<dt><code>3</code>: Information</dt> |
| 82 |
<dd> |
| 83 |
<p>Parameters of control packets</p> |
| 84 |
</dd> |
| 85 |
<dt><code>4</code>: Calls</dt> |
| 86 |
<dd> |
| 87 |
<p>For tracing the execution of the code</p> |
| 88 |
</dd> |
| 89 |
<dt><code>5</code>: Packets</dt> |
| 90 |
<dd> |
| 91 |
<p>Everything, including a hex dump of all packets processed... probably |
| 92 |
twice</p> |
| 93 |
</dd> |
| 94 |
</dl> |
| 95 |
<p>Note that the higher you set the debugging level, the slower the |
| 96 |
program will run. Also, at level 5 a <em>lot</em> of information will be |
| 97 |
logged. This should only ever be used for working out why it doesn't |
| 98 |
work at all.</p> |
| 99 |
</dd> |
| 100 |
<dt><code>log_file</code> (string)</dt> |
| 101 |
<dd> |
| 102 |
<p>This will be where all logging and debugging information is written |
| 103 |
to. This may be either a filename, such as <code>/var/log/l2tpns</code>, |
| 104 |
or the special magic string <code>syslog:</code>facility, where facility |
| 105 |
is any one of the syslog logging facilities, such as |
| 106 |
<code>local5</code>.</p> |
| 107 |
</dd> |
| 108 |
<dt><code>pid_file</code> (string)</dt> |
| 109 |
<dd> |
| 110 |
<p>If set, the process id will be written to the specified file. The |
| 111 |
value must be an absolute path.</p> |
| 112 |
</dd> |
| 113 |
<dt><code>random_device</code> (string)</dt> |
| 114 |
<dd> |
| 115 |
<p>Path to random data source (default <code>/dev/urandom</code>). Use |
| 116 |
"" to use the rand() library function.</p> |
| 117 |
</dd> |
| 118 |
<dt><code>l2tp_secret</code> (string)</dt> |
| 119 |
<dd> |
| 120 |
<p>The secret used by <code>l2tpns</code> for authenticating tunnel |
| 121 |
request. Must be the same as the LAC, or authentication will fail. Only |
| 122 |
actually be used if the LAC requests authentication.</p> |
| 123 |
</dd> |
| 124 |
<dt><code>l2tp_mtu</code> (int)</dt> |
| 125 |
<dd> |
| 126 |
<p>MTU of interface for L2TP traffic (default: <code>1500</code>). Used |
| 127 |
to set link MRU and adjust TCP MSS.</p> |
| 128 |
</dd> |
| 129 |
<dt><code>mp_mrru</code> (int)</dt> |
| 130 |
<dd> |
| 131 |
<p>MRRU for MP traffic (default: <code>1614</code>). Can be set to 0 to |
| 132 |
disable MP negociation.</p> |
| 133 |
</dd> |
| 134 |
<dt><code>ppp_restart_time</code> (int); <code>ppp_max_configure</code> |
| 135 |
(int); <code>ppp_max_failure</code> (int)</dt> |
| 136 |
<dd> |
| 137 |
<p>PPP counter and timer values, as described in §4.1 of <a |
| 138 |
href="ftp://ftp.rfc-editor.org/in-notes/rfc1661.txt">RFC1661</a>.</p> |
| 139 |
</dd> |
| 140 |
<dt><code>lcp_renegotiation</code> (string)</dt> |
| 141 |
<dd> |
| 142 |
<p>By default (<code>always</code>), we renegotiate LCP even if the LAC |
| 143 |
already did with the client.</p> |
| 144 |
<p>We can avoid the LCP renegotiation (proxy LCP negotiation), unless |
| 145 |
what was already negotiated is not fine for us |
| 146 |
(<code>on-mismatch</code>). To be noted: we will accept not using our |
| 147 |
preferred RADIUS authentication method. This is notably useful when the |
| 148 |
LAC cannot pass LCP configuration through, and thus we have to try to |
| 149 |
accept what was already negotiated by the LAC with the client.</p> |
| 150 |
</dd> |
| 151 |
<dt><code>primary_dns</code> (ip address); <code>econdary_dns</code> (ip |
| 152 |
address)</dt> |
| 153 |
<dd> |
| 154 |
<p>Whenever a PPP connection is established, DNS servers will be sent to |
| 155 |
the user, both a primary and a secondary. If either is set to 0.0.0.0, |
| 156 |
then that one will not be sent.</p> |
| 157 |
</dd> |
| 158 |
<dt><code>primary_radius</code> (ip address); |
| 159 |
<code>secondary_radius</code> (ip address)</dt> |
| 160 |
<dd> |
| 161 |
<p>Sets the RADIUS servers used for both authentication and accounting. |
| 162 |
If the primary server does not respond, then the secondary RADIUS server |
| 163 |
will be tried.</p> |
| 164 |
<div class="note"> |
| 165 |
<p>In addition to the source IP address and identifier, the RADIUS |
| 166 |
server <em>must</em> include the source port when detecting duplicates |
| 167 |
to suppress (in order to cope with a large number of sessions coming |
| 168 |
on-line simultaneously <code>l2tpns</code> uses a set of udp sockets, |
| 169 |
each with a separate identifier).</p> |
| 170 |
</div> |
| 171 |
</dd> |
| 172 |
<dt><code>primary_radius_port</code> (short); |
| 173 |
<code>secondary_radius_port</code> (short)</dt> |
| 174 |
<dd> |
| 175 |
<p>Sets the authentication ports for the primary and secondary RADIUS |
| 176 |
servers. The accounting port is one more than the authentication port. |
| 177 |
If no RADIUS ports are given, the authentication port defaults to 1812, |
| 178 |
and the accounting port to 1813.</p> |
| 179 |
</dd> |
| 180 |
<dt><code>radius_accounting</code> (boolean)</dt> |
| 181 |
<dd> |
| 182 |
<p>If set to true, then RADIUS accounting packets will be sent. This |
| 183 |
means that a Start record will be sent when the session is successfully |
| 184 |
authenticated, and a Stop record will be sent when the session is |
| 185 |
closed.</p> |
| 186 |
</dd> |
| 187 |
<dt><code>radius_interim</code> (int)</dt> |
| 188 |
<dd> |
| 189 |
<p>If <code>radius_accounting</code> is on, defines the interval between |
| 190 |
sending of RADIUS interim accounting records (in seconds).</p> |
| 191 |
</dd> |
| 192 |
<dt><code>radius_secret</code> (string)</dt> |
| 193 |
<dd> |
| 194 |
<p>This secret will be used in all RADIUS queries. If this is not set |
| 195 |
then RADIUS queries will fail.</p> |
| 196 |
</dd> |
| 197 |
<dt><code>radius_require_message_authenticator</code> (string)</dt> |
| 198 |
<dd> |
| 199 |
<p>If set to true, RADIUS answers to AccessRequests will have to contain |
| 200 |
a valid MessageAuthenticator. If set to auto (default), if the first |
| 201 |
RADIUS answer to AccessRequests contains a valid MessageAuthenticator, |
| 202 |
subsequent answers will have to contain one. If set to no (not |
| 203 |
recommended), RADIUS answers to AccessRequests do not have to contain a |
| 204 |
valid MessageAuthenticator. It is advised to set this to true after |
| 205 |
checking that your RADIUS server does send MessageAuthenticator.</p> |
| 206 |
</dd> |
| 207 |
<dt><code>radius_authtypes</code> (string)</dt> |
| 208 |
<dd> |
| 209 |
<p>A comma separated list of supported RADIUS authentication methods |
| 210 |
(<code>pap</code> or <code>chap</code>), in order of preference (default |
| 211 |
<code>pap</code>).</p> |
| 212 |
</dd> |
| 213 |
<dt><code>radius_bind_min</code> (short); <code>radius_bind_max</code> |
| 214 |
(short)</dt> |
| 215 |
<dd> |
| 216 |
<p>Define a port range in which to bind sockets used to send and receive |
| 217 |
RADIUS packets. Must be at least RADIUS_FDS (64) wide. Simplifies |
| 218 |
firewalling of RADIUS ports (default: dynamically assigned).</p> |
| 219 |
</dd> |
| 220 |
<dt><code>radius_dae_port</code> (short)</dt> |
| 221 |
<dd> |
| 222 |
<p>Port for DAE RADIUS (Packet of Death/Disconnect, Change of |
| 223 |
Authorization) requests (default: <code>3799</code>).</p> |
| 224 |
</dd> |
| 225 |
<dt><code>allow_duplicate_users</code> (boolean)</dt> |
| 226 |
<dd> |
| 227 |
<p>Allow multiple logins with the same username. If false (the default), |
| 228 |
any prior session with the same username will be dropped when a new |
| 229 |
session is established.</p> |
| 230 |
</dd> |
| 231 |
<dt><code>guest_account</code> (string)</dt> |
| 232 |
<dd> |
| 233 |
<p>Allow multiple logins matching this specific username.</p> |
| 234 |
</dd> |
| 235 |
<dt><code>bind_address</code> (ip address)</dt> |
| 236 |
<dd> |
| 237 |
<p>When the tun interface is created, it is assigned the address |
| 238 |
specified here. If no address is given, 1.1.1.1 is used. Packets |
| 239 |
containing user traffic should be routed via this address if given, |
| 240 |
otherwise the primary address of the machine.</p> |
| 241 |
</dd> |
| 242 |
<dt><code>peer_address</code> (ip address)</dt> |
| 243 |
<dd> |
| 244 |
<p>Address to send to clients as the default gateway.</p> |
| 245 |
</dd> |
| 246 |
<dt><code>route_protocol</code> (short)</dt> |
| 247 |
<dd> |
| 248 |
<p>Protocol number to record when adding a route (see |
| 249 |
<code>/usr/share/iproute2/rt_protos</code>). This allows to separate |
| 250 |
routes added by several l2tpns instances. The default is 42.</p> |
| 251 |
</dd> |
| 252 |
<dt><code>route_metric</code> (int)</dt> |
| 253 |
<dd> |
| 254 |
<p>Metric of the route. Routes with lower values are preferred. This |
| 255 |
should not be changed during execution, since l2tpns would then not |
| 256 |
recognize the routes it added itself. The default is 1.</p> |
| 257 |
</dd> |
| 258 |
<dt><code>ipv6_prefix</code> (ipv6 address)</dt> |
| 259 |
<dd> |
| 260 |
<p>Enable negotiation of IPv6. This forms the the first 64 bits of the |
| 261 |
client allocated address. The remaining 64 come from the allocated IPv4 |
| 262 |
address and 4 bytes of 0s.</p> |
| 263 |
</dd> |
| 264 |
<dt><code>send_garp</code> (boolean)</dt> |
| 265 |
<dd> |
| 266 |
<p>Determines whether or not to send a gratuitous ARP for the |
| 267 |
bind_address when the server is ready to handle traffic (default: |
| 268 |
<code>true</code>). This value is ignored if BGP is configured.</p> |
| 269 |
</dd> |
| 270 |
<dt><code>throttle_speed</code> (int)</dt> |
| 271 |
<dd> |
| 272 |
<p>Sets the default speed (in kbits/s) which sessions will be limited |
| 273 |
to. If this is set to 0, then throttling will not be used at all. Note: |
| 274 |
You can set this by the CLI, but changes will not affect currently |
| 275 |
connected users.</p> |
| 276 |
</dd> |
| 277 |
<dt><code>throttle_buckets</code> (int)</dt> |
| 278 |
<dd> |
| 279 |
<p>Number of token buckets to allocate for throttling. Each throttled |
| 280 |
session requires two buckets (in and out).</p> |
| 281 |
</dd> |
| 282 |
<dt><code>accounting_dir</code> (string)</dt> |
| 283 |
<dd> |
| 284 |
<p>If set to a directory, then every 5 minutes the current usage for |
| 285 |
every connected use will be dumped to a file in this directory. Each |
| 286 |
file dumped begins with a header, where each line is prefixed by |
| 287 |
<code>#</code>. Following the header is a single line for every |
| 288 |
connected user, fields separated by a space.</p> |
| 289 |
<p>The fields are username, ip, qos, uptxoctets, downrxoctets. The qos |
| 290 |
field is 1 if a standard user, and 2 if the user is throttled.</p> |
| 291 |
</dd> |
| 292 |
<dt><code>dump_speed</code> (boolean)</dt> |
| 293 |
<dd> |
| 294 |
<p>If set to true, then the current bandwidth utilization will be logged |
| 295 |
every second. Even if this is disabled, you can see this information by |
| 296 |
running the <code>uptime</code> command on the CLI.</p> |
| 297 |
</dd> |
| 298 |
<dt><code>multi_read_count</code> (int)</dt> |
| 299 |
<dd> |
| 300 |
<p>Number of packets to read off each of the UDP and TUN fds when |
| 301 |
returned as readable by select (default: 10). Avoids incurring the |
| 302 |
unnecessary system call overhead of select on busy servers.</p> |
| 303 |
</dd> |
| 304 |
<dt><code>scheduler_fifo</code> (boolean)</dt> |
| 305 |
<dd> |
| 306 |
<p>Sets the scheduling policy for the <code>l2tpns</code> process to |
| 307 |
<code>SCHED_FIFO</code>. This causes the kernel to immediately preempt |
| 308 |
any currently running <code>SCHED_OTHER</code> (normal) process in |
| 309 |
favour of <code>l2tpns</code> when it becomes runnable. Ignored on |
| 310 |
uniprocessor systems.</p> |
| 311 |
</dd> |
| 312 |
<dt><code>lock_pages</code> (boolean)</dt> |
| 313 |
<dd> |
| 314 |
<p>Keep all pages mapped by the <code>l2tpns</code> process in |
| 315 |
memory.</p> |
| 316 |
</dd> |
| 317 |
<dt><code>icmp_rate</code> (int)</dt> |
| 318 |
<dd> |
| 319 |
<p>Maximum number of host unreachable ICMP packets to send per |
| 320 |
second.</p> |
| 321 |
</dd> |
| 322 |
<dt><code>packet_limit</code> (int)</dt> |
| 323 |
<dd> |
| 324 |
<p>Maximum number of packets of downstream traffic to be handled each |
| 325 |
tenth of a second per session. If zero, no limit is applied (default: |
| 326 |
0). Intended as a DoS prevention mechanism and not a general throttling |
| 327 |
control (packets are dropped, not queued).</p> |
| 328 |
</dd> |
| 329 |
<dt><code>cluster_address</code> (ip address)</dt> |
| 330 |
<dd> |
| 331 |
<p>Multicast cluster address (default: 239.192.13.13). See <a |
| 332 |
href="#clustering">Clustering</a> for more information.</p> |
| 333 |
</dd> |
| 334 |
<dt><code>cluster_port</code> (udp port)</dt> |
| 335 |
<dd> |
| 336 |
<p>UDP cluster port (default: 32792). See <a |
| 337 |
href="#clustering">Clustering</a> for more information.</p> |
| 338 |
</dd> |
| 339 |
<dt><code>cluster_interface</code> (string)</dt> |
| 340 |
<dd> |
| 341 |
<p>Interface for cluster packets (default: none). An IPv4 address can |
| 342 |
also be specified, e.g. to run several l2tpns on the same host (but |
| 343 |
beware of enabling kernel acceleration only on one instance, to set a |
| 344 |
different <code>bind_portremotelns</code>, and to set a different |
| 345 |
<code>route_metric</code>. It is also useful to set a different |
| 346 |
<code>route_protocol</code> number)</p> |
| 347 |
</dd> |
| 348 |
<dt><code>cluster_mcast_ttl</code> (int)</dt> |
| 349 |
<dd> |
| 350 |
<p>TTL for multicast packets (default: 1).</p> |
| 351 |
</dd> |
| 352 |
<dt><code>cluster_hb_interval</code> (int)</dt> |
| 353 |
<dd> |
| 354 |
<p>Interval in tenths of a second between cluster heartbeat/pings.</p> |
| 355 |
</dd> |
| 356 |
<dt><code>cluster_hb_timeout</code> (int)</dt> |
| 357 |
<dd> |
| 358 |
<p>Cluster heartbeat timeout in tenths of a second. A new master will be |
| 359 |
elected when this interval has been passed without seeing a heartbeat |
| 360 |
from the master.</p> |
| 361 |
</dd> |
| 362 |
<dt><code>cluster_master_min_adv</code> (int)</dt> |
| 363 |
<dd> |
| 364 |
<p>Determines the minimum number of up to date slaves required before |
| 365 |
the master will drop routes (default: 1).</p> |
| 366 |
</dd> |
| 367 |
</dl> |
| 368 |
<h3 id="config-startup-bgp">BGP</h3> |
| 369 |
<p>BGP routing configuration is entered by the command: router bgp as |
| 370 |
where as specifies the local AS number.</p> |
| 371 |
<p>Subsequent lines prefixed with neighbour peer define the attributes |
| 372 |
of BGP neighhbours. Valid commands are: neighbour peer remote-as as |
| 373 |
neighbour peer timers keepalive hold</p> |
| 374 |
<p>Where peer specifies the BGP neighbour as either a hostname or IP |
| 375 |
address, as is the remote AS number and keepalive, hold are the timer |
| 376 |
values in seconds.</p> |
| 377 |
<h3 id="config-startup-acl">Access Lists</h3> |
| 378 |
<p>Named access-lists are configured using one of the commands: ip |
| 379 |
access-list standard name ip access-list extended name</p> |
| 380 |
<p>Subsequent lines prefixed with <code>permit</code> or |
| 381 |
<code>deny</code> define the body of the access-list. Standard |
| 382 |
access-list syntax:</p> |
| 383 |
<p>{<code>permit</code>|<code>deny</code>} {host|source |
| 384 |
source-wildcard|<code>any</code>} [{host|destination |
| 385 |
destination-wildcard|<code>any</code>}]</p> |
| 386 |
<p>Extended access-lists:</p> |
| 387 |
<p>{<code>permit</code>|<code>deny</code>} <code>ip</code> {host|source |
| 388 |
source-wildcard|<code>any</code>} {host|destination |
| 389 |
destination-wildcard|<code>any</code>} [<code>fragments</code>]</p> |
| 390 |
<p>{<code>permit</code>|<code>deny</code>} <code>udp</code> {host|source |
| 391 |
source-wildcard|<code>any</code>} |
| 392 |
[{<code>eq</code>|<code>neq</code>|<code>gt</code>|<code>lt</code>} |
| 393 |
port|<code>range</code> from to] {host|destination |
| 394 |
destination-wildcard|<code>any</code>} |
| 395 |
[{<code>eq</code>|<code>neq</code>|<code>gt</code>|<code>lt</code>} |
| 396 |
port|<code>range</code> from to] [<code>fragments</code>]</p> |
| 397 |
<p>{<code>permit</code>|<code>deny</code>} <code>tcp</code> {host|source |
| 398 |
source-wildcard|<code>any</code>} |
| 399 |
[{<code>eq</code>|<code>neq</code>|<code>gt</code>|<code>lt</code>} |
| 400 |
port|<code>range</code> from to] {host|destination |
| 401 |
destination-wildcard|<code>any</code>} |
| 402 |
[{<code>eq</code>|<code>neq</code>|<code>gt</code>|<code>lt</code>} |
| 403 |
port|<code>range</code> from to] |
| 404 |
[{<code>established</code>|{<code>match-any</code>|<code>match-all</code>} |
| 405 |
{<code>+</code>|<code>-</code>}{<code>fin</code>|<code>syn</code>|<code>rst</code>|<code>psh</code>|<code>ack</code>|<code>urg</code>} |
| 406 |
...|<code>fragments</code>]</p> |
| 407 |
<h2 id="config-users"><code>users</code></h2> |
| 408 |
<p>Usernames and passwords for the command-line interface are stored in |
| 409 |
this file. The format is username:password where password may either by |
| 410 |
plain text, an MD5 digest (prefixed by |
| 411 |
<code>$1</code>salt<code>$</code>) or a DES password, distinguished from |
| 412 |
plain text by the prefix <code>{crypt}</code>.</p> |
| 413 |
<p>The username <code>enable</code> has a special meaning and is used to |
| 414 |
set the enable password.</p> |
| 415 |
<div class="important"> |
| 416 |
<p>If this file doesn't exist, then anyone who can get to port 23 will |
| 417 |
be allowed access without a username or password.</p> |
| 418 |
</div> |
| 419 |
<h2 id="config-ip-pool"><code>ip_pool</code></h2> |
| 420 |
<p>This file is used to configure the IP address pool which user |
| 421 |
addresses are assigned from. This file should contain either an IP |
| 422 |
address or a CIDR network per line. e.g.:</p> |
| 423 |
<pre><code>192.168.1.1 |
| 424 |
192.168.1.2 |
| 425 |
192.168.1.3 |
| 426 |
192.168.4.0/24 |
| 427 |
172.16.0.0/16 |
| 428 |
10.0.0.0/8</code></pre> |
| 429 |
<p>Keep in mind that <code>l2tpns</code> can only handle 65535 |
| 430 |
connections per process, so don't put more than 65535 IP addresses in |
| 431 |
the configuration file. They will be wasted.</p> |
| 432 |
<h2 id="config-build-garden"><code>build-garden</code></h2> |
| 433 |
<p>The garden plugin on startup creates a NAT table called "garden" then |
| 434 |
sources the <code>build-garden</code> script to populate that table. All |
| 435 |
packets from gardened users will be sent through this table. |
| 436 |
Example:</p> |
| 437 |
<pre><code>iptables -t nat -A garden -p tcp -m tcp --dport 25 -j DNAT --to 192.168.1.1 |
| 438 |
iptables -t nat -A garden -p udp -m udp --dport 53 -j DNAT --to 192.168.1.1 |
| 439 |
iptables -t nat -A garden -p tcp -m tcp --dport 53 -j DNAT --to 192.168.1.1 |
| 440 |
iptables -t nat -A garden -p tcp -m tcp --dport 80 -j DNAT --to 192.168.1.1 |
| 441 |
iptables -t nat -A garden -p tcp -m tcp --dport 110 -j DNAT --to 192.168.1.1 |
| 442 |
iptables -t nat -A garden -p tcp -m tcp --dport 443 -j DNAT --to 192.168.1.1 |
| 443 |
iptables -t nat -A garden -p icmp -m icmp --icmp-type echo-request -j DNAT --to 192.168.1.1 |
| 444 |
iptables -t nat -A garden -p icmp -j ACCEPT |
| 445 |
iptables -t nat -A garden -j DROP</code></pre> |
| 446 |
<h1 id="operation">Operation</h1> |
| 447 |
<p>A running l2tpns process can be controlled in a number of ways. The |
| 448 |
primary method of control is by the Command-Line Interface (CLI).</p> |
| 449 |
<p>You can also remotely send commands to modules via the |
| 450 |
<code>nsctl</code> client provided.</p> |
| 451 |
<p>There are also a number of signals that l2tpns understands and takes |
| 452 |
action when it receives them.</p> |
| 453 |
<h2 id="operation-cli">Command-Line Interface</h2> |
| 454 |
<p>You can access the command line interface by telneting to port 23. |
| 455 |
There is no IP address restriction, so it's a good idea to firewall this |
| 456 |
port off from anyone who doesn't need access to it. See <a |
| 457 |
href="#config-users"></a> for information on restricting access based on |
| 458 |
a username and password.</p> |
| 459 |
<p>The CLI gives you real-time control over almost everything in the |
| 460 |
process. The interface is designed to look like a Cisco device, and |
| 461 |
supports things like command history, line editing and context sensitive |
| 462 |
help. This is provided by linking with the <a |
| 463 |
href="http://sourceforge.net/projects/libcli">libcli</a> library. Some |
| 464 |
general documentation of the interface is <a |
| 465 |
href="http://sourceforge.net/docman/display_doc.php?docid=20501&group_id=79019">here</a>.</p> |
| 466 |
<p>After you have connected to the telnet port (and perhaps logged in), |
| 467 |
you will be presented with a <code>hostname></code> prompt.</p> |
| 468 |
<p>Enter <code>help</code> to get a list of possible commands, or press |
| 469 |
<code>?</code> for context-specific help.</p> |
| 470 |
<p>A brief overview of the more important commands follows:</p> |
| 471 |
<p><code>show session [ID]</code></p> |
| 472 |
<p>: Detailed information for a specific session is presented if you |
| 473 |
specify a session ID argument.</p> |
| 474 |
<pre><code>If no ID is given, a summary of all connected sessions is produced. |
| 475 |
Note that this summary list can be around 185 columns wide, so you |
| 476 |
should probably use a wide terminal. |
| 477 |
|
| 478 |
The columns listed in the summary are: |
| 479 |
|
| 480 |
-------------- -------------------------------------------------------------------------------------------------------------- ------------------------------------------------------------------------------------------------------------------------------------ |
| 481 |
`SID` Session ID |
| 482 |
`TID` Tunnel ID See also the [show tunnel](#operation-cli-show-tunnel) CLI command. |
| 483 |
`Username` The username given in the PPP authentication. If this is \*, then LCP authentication has not completed. |
| 484 |
`IP` The IP address given to the session. If this is 0.0.0.0, IPCP negotiation has not completed |
| 485 |
`I` Intercept Y or N: indicates whether the session is being snooped. See also the [snoop](#operation-cli-snoop) CLI command. |
| 486 |
`T` Throttled Y or N: indicates whether the session is currently throttled. See also the [throttle](#operation-cli-throttle) CLI command. |
| 487 |
`G` Walled Garden Y or N: indicates whether the user is trapped in the walled garden. This field is present even if the garden module is not loaded. |
| 488 |
`6` IPv6 Y or N: indicates whether the session has IPv6 active (IPV6CP open) |
| 489 |
`opened` The number of seconds since the session started |
| 490 |
`downloaded` Number of bytes downloaded by the user |
| 491 |
`uploaded` Number of bytes uploaded by the user |
| 492 |
`idle` The number of seconds since traffic was detected on the session |
| 493 |
`LAC` The IP address of the LAC the session is connected to. |
| 494 |
`CLI` The Calling-Line-Identification field provided during the session setup. This field is generated by the LAC. |
| 495 |
-------------- -------------------------------------------------------------------------------------------------------------- ------------------------------------------------------------------------------------------------------------------------------------</code></pre> |
| 496 |
<p><code>show users</code>; <code>show user username</code></p> |
| 497 |
<p>: With no arguments, display a list of currently connected users. If |
| 498 |
an argument is given, the session details for the given username are |
| 499 |
displayed.</p> |
| 500 |
<dl> |
| 501 |
<dt><code>show tunnel [ID]</code></dt> |
| 502 |
<dd> |
| 503 |
<p>Produce a summary list of all open tunnels, or detail on a specific |
| 504 |
tunnel ID.</p> |
| 505 |
<p>The columns listed in the summary are:</p> |
| 506 |
<table> |
| 507 |
<tbody> |
| 508 |
<tr class="odd"> |
| 509 |
<td style="text-align: left;">TID</td> |
| 510 |
<td style="text-align: left;">Tunnel ID</td> |
| 511 |
</tr> |
| 512 |
<tr class="even"> |
| 513 |
<td style="text-align: left;">Hostname</td> |
| 514 |
<td style="text-align: left;">The hostname for the tunnel as provided by |
| 515 |
the LAC. This has no relation to DNS, it is just a text field.</td> |
| 516 |
</tr> |
| 517 |
<tr class="odd"> |
| 518 |
<td style="text-align: left;">IP</td> |
| 519 |
<td style="text-align: left;">The IP address of the LAC</td> |
| 520 |
</tr> |
| 521 |
<tr class="even"> |
| 522 |
<td style="text-align: left;">State</td> |
| 523 |
<td style="text-align: left;">Tunnel state: Free, Open, Dieing, |
| 524 |
Opening</td> |
| 525 |
</tr> |
| 526 |
<tr class="odd"> |
| 527 |
<td style="text-align: left;">Sessions</td> |
| 528 |
<td style="text-align: left;">The number of open sessions on the |
| 529 |
tunnel</td> |
| 530 |
</tr> |
| 531 |
</tbody> |
| 532 |
</table> |
| 533 |
</dd> |
| 534 |
<dt><code>show pool</code></dt> |
| 535 |
<dd> |
| 536 |
<p>Displays the current IP address pool allocation. This will only |
| 537 |
display addresses that are in use, or are reserved for re-allocation to |
| 538 |
a disconnected user.</p> |
| 539 |
<p>If an address is not currently in use, but has been used, then in the |
| 540 |
User column the username will be shown in square brackets, followed by |
| 541 |
the time since the address was used:</p> |
| 542 |
<pre><code>IP Address Used Session User |
| 543 |
192.168.100.6 N [joe.user] 1548s</code></pre> |
| 544 |
</dd> |
| 545 |
<dt><code>show radius</code></dt> |
| 546 |
<dd> |
| 547 |
<p>Show a summary of the in-use RADIUS sessions. This list should not be |
| 548 |
very long, as RADIUS sessions should be cleaned up as soon as they are |
| 549 |
used. The columns listed are:</p> |
| 550 |
<table> |
| 551 |
<tbody> |
| 552 |
<tr class="odd"> |
| 553 |
<td style="text-align: left;">Radius</td> |
| 554 |
<td style="text-align: left;">The ID of the RADIUS request. This is sent |
| 555 |
in the packet to the RADIUS server for identification</td> |
| 556 |
</tr> |
| 557 |
<tr class="even"> |
| 558 |
<td style="text-align: left;">State</td> |
| 559 |
<td style="text-align: left;">The state of the request: WAIT, CHAP, |
| 560 |
AUTH, IPCP, START, STOP or NULL</td> |
| 561 |
</tr> |
| 562 |
<tr class="odd"> |
| 563 |
<td style="text-align: left;">Session</td> |
| 564 |
<td style="text-align: left;">The session ID that this RADIUS request is |
| 565 |
associated with</td> |
| 566 |
</tr> |
| 567 |
<tr class="even"> |
| 568 |
<td style="text-align: left;">Retry</td> |
| 569 |
<td style="text-align: left;">If a response does not appear to the |
| 570 |
request, it will retry at this time. This is a Unix timestamp</td> |
| 571 |
</tr> |
| 572 |
<tr class="odd"> |
| 573 |
<td style="text-align: left;">Try</td> |
| 574 |
<td style="text-align: left;">Retry count. The RADIUS request is |
| 575 |
discarded after 3 retries</td> |
| 576 |
</tr> |
| 577 |
</tbody> |
| 578 |
</table> |
| 579 |
</dd> |
| 580 |
<dt><code>show running-config</code></dt> |
| 581 |
<dd> |
| 582 |
<p>This will list the current running configuration. This is in a format |
| 583 |
that can either be pasted into the configuration file, or run directly |
| 584 |
at the command line.</p> |
| 585 |
</dd> |
| 586 |
<dt><code>show counters</code></dt> |
| 587 |
<dd> |
| 588 |
<p>Internally, counters are kept of key values, such as bytes and |
| 589 |
packets transferred, as well as function call counters. This function |
| 590 |
displays all these counters, and is probably only useful for |
| 591 |
debugging.</p> |
| 592 |
<p>You can reset these counters by running |
| 593 |
<code>clear counters</code>.</p> |
| 594 |
</dd> |
| 595 |
<dt><code>show cluster</code></dt> |
| 596 |
<dd> |
| 597 |
<p>Show cluster status. Shows the cluster state for this server |
| 598 |
(Master/Slave), information about known peers and (for slaves) the |
| 599 |
master IP address, last packet seen and up-to-date status. See <a |
| 600 |
href="#clustering">Clustering</a> for more information.</p> |
| 601 |
</dd> |
| 602 |
<dt><code>write memory</code></dt> |
| 603 |
<dd> |
| 604 |
<p>This will write the current running configuration to the config file |
| 605 |
<code>startup-config</code>, which will be run on a restart.</p> |
| 606 |
</dd> |
| 607 |
</dl> |
| 608 |
<p><code>snoop user IP port</code></p> |
| 609 |
<p>: You must specify a username, IP address and port. All packets for |
| 610 |
the current session for that username will be forwarded to the given |
| 611 |
host/port. Specify <code>no snoop username</code> to disable |
| 612 |
interception for the session.</p> |
| 613 |
<pre><code>If you want interception to be permanent, you will have to modify |
| 614 |
the RADIUS response for the user. See [Interception](#interception).</code></pre> |
| 615 |
<p><code>throttle user [in|out] rate</code></p> |
| 616 |
<p>: You must specify a username, which will be throttled for the |
| 617 |
current session to rate Kbps. Prefix rate with <code>in</code> or |
| 618 |
<code>out</code> to set different upstream and downstream rates.</p> |
| 619 |
<pre><code>Specify `no throttle |
| 620 |
username` to disable throttling for the current session. |
| 621 |
|
| 622 |
If you want throttling to be permanent, you will have to modify the |
| 623 |
RADIUS response for the user. See [Throttling](#throttling).</code></pre> |
| 624 |
<dl> |
| 625 |
<dt><code>drop session</code></dt> |
| 626 |
<dd> |
| 627 |
<p>This will cleanly disconnect the session specified by session ID.</p> |
| 628 |
</dd> |
| 629 |
<dt><code>drop tunnel</code></dt> |
| 630 |
<dd> |
| 631 |
<p>This will cleanly disconnect the tunnel specified by tunnel ID, as |
| 632 |
well as all sessions on that tunnel.</p> |
| 633 |
</dd> |
| 634 |
<dt><code>uptime</code></dt> |
| 635 |
<dd> |
| 636 |
<p>This will show how long the <code>l2tpns</code> process has been |
| 637 |
running, and the current bandwidth utilization:</p> |
| 638 |
<pre><code>17:10:35 up 8 days, 2212 users, load average: 0.21, 0.17, 0.16 |
| 639 |
Bandwidth: UDP-ETH:6/6 ETH-UDP:13/13 TOTAL:37.6 IN:3033 OUT:2569</code></pre> |
| 640 |
<p>The bandwidth line contains 4 sets of values:</p> |
| 641 |
<table> |
| 642 |
<tbody> |
| 643 |
<tr class="odd"> |
| 644 |
<td style="text-align: left;">UDP-ETH</td> |
| 645 |
<td style="text-align: left;">The current bandwidth going from the LAC |
| 646 |
to the ethernet (user uploads), in mbits/sec.</td> |
| 647 |
</tr> |
| 648 |
<tr class="even"> |
| 649 |
<td style="text-align: left;">ETH-UDP</td> |
| 650 |
<td style="text-align: left;">The current bandwidth going from ethernet |
| 651 |
to the LAC (user downloads).</td> |
| 652 |
</tr> |
| 653 |
<tr class="odd"> |
| 654 |
<td style="text-align: left;">TOTAL</td> |
| 655 |
<td style="text-align: left;">The total aggregate bandwidth in |
| 656 |
mbits/s.</td> |
| 657 |
</tr> |
| 658 |
<tr class="even"> |
| 659 |
<td style="text-align: left;">IN and OUT</td> |
| 660 |
<td style="text-align: left;">Packets/per-second going between UDP-ETH |
| 661 |
and ETH-UDP.</td> |
| 662 |
</tr> |
| 663 |
</tbody> |
| 664 |
</table> |
| 665 |
<p>These counters are updated every second.</p> |
| 666 |
</dd> |
| 667 |
<dt><code>configure terminal</code></dt> |
| 668 |
<dd> |
| 669 |
<p>Enter configuration mode. Use <code>exit</code> or <code>^Z</code> to |
| 670 |
exit this mode.</p> |
| 671 |
<p>The following commands are valid in this mode:</p> |
| 672 |
<p><code>load plugin name</code></p> |
| 673 |
<p>: Load a plugin. You must specify the plugin name, and it will search |
| 674 |
in <code>/usr/lib/l2tpns</code> for <code>name.so</code>. You can unload |
| 675 |
a loaded plugin with |
| 676 |
<code>remove plugin name</code>.</p> |
| 677 |
<dl> |
| 678 |
<dt><code>set</code> ...</dt> |
| 679 |
<dd> |
| 680 |
<p>Set a configuration variable. You must specify the variable name, and |
| 681 |
the value. If the value contains any spaces, you should quote the value |
| 682 |
with double (") or single (') quotes.</p> |
| 683 |
<p>You can set any configuration value in this way, although some may |
| 684 |
require a restart to take effect. See <a |
| 685 |
href="#config-startup"></a>.</p> |
| 686 |
</dd> |
| 687 |
<dt><code>router bgp</code> ...</dt> |
| 688 |
<dd> |
| 689 |
<p>Configure BGP. See <a href="#config-startup-bgp">BGP</a>.</p> |
| 690 |
</dd> |
| 691 |
<dt><code>ip access-list</code> ...</dt> |
| 692 |
<dd> |
| 693 |
<p>Configure a named access list. See <a |
| 694 |
href="#config-startup-acl">Access Lists</a>.</p> |
| 695 |
</dd> |
| 696 |
</dl> |
| 697 |
</dd> |
| 698 |
</dl> |
| 699 |
<h2 id="operation-nsctl">nsctl</h2> |
| 700 |
<p><code>nsctl</code> sends messages to a running <code>l2tpns</code> |
| 701 |
instance to be control plugins.</p> |
| 702 |
<p>Arguments are <code>command</code> and optional args. See |
| 703 |
<code>nsctl(8)</code>.</p> |
| 704 |
<p>Built-in command are <code>load_plugin</code>, |
| 705 |
<code>unload_plugin</code> and <code>help</code>. Any other commands are |
| 706 |
passed to plugins for processing by the <code>plugin_control</code> |
| 707 |
function.</p> |
| 708 |
<h2 id="operation-signals">Signals</h2> |
| 709 |
<p>While the process is running, you can send it a few different |
| 710 |
signals, using the <code>kill</code> command.</p> |
| 711 |
<pre><code>killall -HUP l2tpns</code></pre> |
| 712 |
<p>The signals understood are:</p> |
| 713 |
<dl> |
| 714 |
<dt>SIGHUP</dt> |
| 715 |
<dd> |
| 716 |
<p>Reload the config from disk and re-open log file.</p> |
| 717 |
</dd> |
| 718 |
<dt>SIGTERM; SIGINT</dt> |
| 719 |
<dd> |
| 720 |
<p>Stop process. Tunnels and sessions are not terminated. This signal |
| 721 |
should be used to stop <code>l2tpns</code> on a cluster node where there |
| 722 |
are other machines to continue handling traffic. See <a |
| 723 |
href="#clustering">Clustering</a></p> |
| 724 |
</dd> |
| 725 |
<dt>SIGQUIT</dt> |
| 726 |
<dd> |
| 727 |
<p>Shut down tunnels and sessions, exit process when complete.</p> |
| 728 |
</dd> |
| 729 |
</dl> |
| 730 |
<h1 id="throttling">Throttling</h1> |
| 731 |
<p><code>l2tpns</code> contains support for slowing down user sessions |
| 732 |
to whatever speed you desire. The global setting |
| 733 |
<code>throttle_speed</code> defines the default throttle rate.</p> |
| 734 |
<p>To throttle a sesion permanently, add a <code>Cisco-AVPair</code> |
| 735 |
RADIUS attribute. The <code>autothrotle</code> module interprets the |
| 736 |
following attributes:</p> |
| 737 |
<table> |
| 738 |
<tbody> |
| 739 |
<tr class="odd"> |
| 740 |
<td style="text-align: left;"><code>throttle=yes</code></td> |
| 741 |
<td style="text-align: left;">Throttle upstream/downstream traffic to |
| 742 |
the configured <code>throttle_speed</code>.</td> |
| 743 |
</tr> |
| 744 |
<tr class="even"> |
| 745 |
<td style="text-align: left;"><code>throttle=rate</code></td> |
| 746 |
<td style="text-align: left;">Throttle upstream/downstream traffic to |
| 747 |
the specified rate Kbps.</td> |
| 748 |
</tr> |
| 749 |
<tr class="odd"> |
| 750 |
<td style="text-align: left;">`lcp:interface-config#1=service-policy |
| 751 |
input</td> |
| 752 |
<td style="text-align: left;">Alternate (Cisco) format: throttle |
| 753 |
upstream/downstream to specified rate Kbps.</td> |
| 754 |
</tr> |
| 755 |
<tr class="even"> |
| 756 |
<td style="text-align: left;">rate`</td> |
| 757 |
<td style="text-align: left;"></td> |
| 758 |
</tr> |
| 759 |
<tr class="odd"> |
| 760 |
<td style="text-align: left;">`lcp:interface-config#2=service-policy |
| 761 |
output</td> |
| 762 |
<td style="text-align: left;"></td> |
| 763 |
</tr> |
| 764 |
<tr class="even"> |
| 765 |
<td style="text-align: left;">rate`</td> |
| 766 |
<td style="text-align: left;"></td> |
| 767 |
</tr> |
| 768 |
</tbody> |
| 769 |
</table> |
| 770 |
<p>You can also enable and disable throttling an active session using |
| 771 |
the <a href="#operation-cli-throttle">throttle</a> CLI command.</p> |
| 772 |
<h1 id="interception">Interception</h1> |
| 773 |
<p>You may have to deal with legal requirements to be able to intercept |
| 774 |
a user's traffic at any time. <code>l2tpns</code> allows you to begin |
| 775 |
and end interception on the fly, as well as at authentication time.</p> |
| 776 |
<p>When a user is being intercepted, a copy of every packet they send |
| 777 |
and receive will be sent wrapped in a UDP packet to a specified |
| 778 |
host.</p> |
| 779 |
<p>The UDP packet contains just the raw IP frame, with no extra headers. |
| 780 |
The script <code>scripts/l2tpns-capture</code> may be used as the |
| 781 |
end-point for such intercepts, writing the data in PCAP format (suitable |
| 782 |
for inspection with <code>tcpdump</code>).</p> |
| 783 |
<p>To enable or disable interception of a connected user, use the <a |
| 784 |
href="#operation-cli-snoop">snoop</a> and <code>no snoop</code> |
| 785 |
CLI commands. These will enable interception immediately.</p> |
| 786 |
<p>If you wish the user to be intercepted whenever they reconnect, you |
| 787 |
will need to modify the RADIUS response to include the Vendor-Specific |
| 788 |
value <code>Cisco-AVPair="intercept=ip:port"</code>. For this feature to |
| 789 |
be enabled, you need to have the <code>autosnoop</code> module |
| 790 |
loaded.</p> |
| 791 |
<h1 id="plugins">Plugins</h1> |
| 792 |
<p>So as to make <code>l2tpns</code> as flexible as possible, a plugin |
| 793 |
API is include which you can use to hook into certain events.</p> |
| 794 |
<p>There are a some standard modules included which may be used as |
| 795 |
examples: <code>autosnoop</code>, <code>autothrottle</code>, |
| 796 |
<code>garden</code>, <code>sessionctl</code>, <code>setrxspeed</code>, |
| 797 |
<code>snoopctl</code>, <code>stripdomain</code> and |
| 798 |
<code>throttlectl</code>.</p> |
| 799 |
<p>When an event occurs that has a hook, <code>l2tpns</code> looks for a |
| 800 |
predefined function name in every loaded module, and runs them in the |
| 801 |
order the modules were loaded.</p> |
| 802 |
<p>The function should return <code>PLUGIN_RET_OK</code> if it is all |
| 803 |
OK. If it returns <code>PLUGIN_RET_STOP</code>, then it is assumed to |
| 804 |
have worked, but that no further modules should be run for this |
| 805 |
event.</p> |
| 806 |
<p>A return of <code>PLUGIN_RET_ERROR</code> means that this module |
| 807 |
failed, and no further processing should be done for this event.</p> |
| 808 |
<div class="note"> |
| 809 |
<p>Use this with care.</p> |
| 810 |
</div> |
| 811 |
<p>Most event functions take a specific structure named |
| 812 |
<code>param_event</code>, which varies in content with each event. The |
| 813 |
function name for each event will be <code>plugin_event</code>, so for |
| 814 |
the event timer, the function declaration should look like:</p> |
| 815 |
<pre><code>int plugin_timer(struct param_timer *data);</code></pre> |
| 816 |
<p>A list of the available events follows, with a list of all the fields |
| 817 |
in the supplied structure:</p> |
| 818 |
<table style="width:97%;"> |
| 819 |
<colgroup> |
| 820 |
<col style="width: 29%" /> |
| 821 |
<col style="width: 29%" /> |
| 822 |
<col style="width: 29%" /> |
| 823 |
<col style="width: 8%" /> |
| 824 |
</colgroup> |
| 825 |
<tbody> |
| 826 |
<tr class="odd"> |
| 827 |
<td rowspan="2"><h1 id="event">Event</h1> |
| 828 |
<p><code>plugin_init</code></p></td> |
| 829 |
<td rowspan="2"><h1 id="description">Description</h1> |
| 830 |
<p>Called when the plugin is loaded. A pointer to a struct containing |
| 831 |
function pointers is passed as the only argument, allowing the plugin to |
| 832 |
call back into the main code.</p> |
| 833 |
<p>Prior to loading the plugin, <code>l2tpns</code> checks the API |
| 834 |
version the plugin was compiled against. All plugins should contain:</p> |
| 835 |
<pre><code> int</code></pre> |
| 836 |
<p>plugin_api_version = PLUGIN_API_VERSION;</p></td> |
| 837 |
<td rowspan="2"><h1 id="arguments">Arguments</h1> |
| 838 |
<p><code>s truct pluginfuncs *</code></p></td> |
| 839 |
<td></td> |
| 840 |
</tr> |
| 841 |
<tr class="even"> |
| 842 |
<td></td> |
| 843 |
</tr> |
| 844 |
<tr class="odd"> |
| 845 |
<td>See <code>pluginfuncs</code> structure in <code>plugin.h</code> for |
| 846 |
available functions.</td> |
| 847 |
<td></td> |
| 848 |
<td></td> |
| 849 |
<td></td> |
| 850 |
</tr> |
| 851 |
<tr class="even"> |
| 852 |
<td><code>plugin_done</code></td> |
| 853 |
<td>Called when the plugin is unloaded or <code>l2tpns</code> is |
| 854 |
shutdown.</td> |
| 855 |
<td><code>void</code></td> |
| 856 |
<td></td> |
| 857 |
</tr> |
| 858 |
<tr class="odd"> |
| 859 |
<td>No arguments.</td> |
| 860 |
<td></td> |
| 861 |
<td></td> |
| 862 |
<td></td> |
| 863 |
</tr> |
| 864 |
<tr class="even"> |
| 865 |
<td><code>plugin_pre_auth</code></td> |
| 866 |
<td>Called after a RADIUS response has been received, but before it has |
| 867 |
been processed by the code. This will allow you to modify the response |
| 868 |
in some way.</td> |
| 869 |
<td><code>struct plug in param_pre_auth *</code></td> |
| 870 |
<td></td> |
| 871 |
</tr> |
| 872 |
<tr class="odd"> |
| 873 |
<td><code>tunnelt *t</code></td> |
| 874 |
<td>Tunnel.</td> |
| 875 |
<td></td> |
| 876 |
<td></td> |
| 877 |
</tr> |
| 878 |
<tr class="even"> |
| 879 |
<td><code>sessiont *s</code></td> |
| 880 |
<td>Session.</td> |
| 881 |
<td></td> |
| 882 |
<td></td> |
| 883 |
</tr> |
| 884 |
<tr class="odd"> |
| 885 |
<td><code>char *username</code></td> |
| 886 |
<td>User name.</td> |
| 887 |
<td></td> |
| 888 |
<td></td> |
| 889 |
</tr> |
| 890 |
<tr class="even"> |
| 891 |
<td><code>char *password</code></td> |
| 892 |
<td>Password.</td> |
| 893 |
<td></td> |
| 894 |
<td></td> |
| 895 |
</tr> |
| 896 |
<tr class="odd"> |
| 897 |
<td><code>int protocol</code></td> |
| 898 |
<td>Authentication protocol: <code>0xC023</code> for PAP, |
| 899 |
<code>0xC223</code> for CHAP.</td> |
| 900 |
<td></td> |
| 901 |
<td></td> |
| 902 |
</tr> |
| 903 |
<tr class="even"> |
| 904 |
<td><code>int continue_auth</code></td> |
| 905 |
<td>Set to 0 to stop processing authentication modules.</td> |
| 906 |
<td></td> |
| 907 |
<td></td> |
| 908 |
</tr> |
| 909 |
<tr class="odd"> |
| 910 |
<td><code>plugin_post_auth</code></td> |
| 911 |
<td>Called after a RADIUS response has been received, and the basic |
| 912 |
checks have been performed. This is what the <code>garden</code> module |
| 913 |
uses to force authentication to be accepted.</td> |
| 914 |
<td><code>struct plugi n param_post_auth *</code></td> |
| 915 |
<td></td> |
| 916 |
</tr> |
| 917 |
<tr class="even"> |
| 918 |
<td><code>tunnelt *t</code></td> |
| 919 |
<td>Tunnel.</td> |
| 920 |
<td></td> |
| 921 |
<td></td> |
| 922 |
</tr> |
| 923 |
<tr class="odd"> |
| 924 |
<td><code>sessiont *s</code></td> |
| 925 |
<td>Session.</td> |
| 926 |
<td></td> |
| 927 |
<td></td> |
| 928 |
</tr> |
| 929 |
<tr class="even"> |
| 930 |
<td><code>char *username</code></td> |
| 931 |
<td>User name.</td> |
| 932 |
<td></td> |
| 933 |
<td></td> |
| 934 |
</tr> |
| 935 |
<tr class="odd"> |
| 936 |
<td><code>short auth_allowed</code></td> |
| 937 |
<td>Initially true or false depending on whether authentication has been |
| 938 |
allowed so far. You can set this to 1 or 0 to force authentication to be |
| 939 |
accepted or rejected.</td> |
| 940 |
<td></td> |
| 941 |
<td></td> |
| 942 |
</tr> |
| 943 |
<tr class="even"> |
| 944 |
<td><code>int protocol</code></td> |
| 945 |
<td>Authentication protocol: <code>0xC023</code> for PAP, |
| 946 |
<code>0xC223</code> for CHAP.</td> |
| 947 |
<td></td> |
| 948 |
<td></td> |
| 949 |
</tr> |
| 950 |
<tr class="odd"> |
| 951 |
<td><code>plugin_timer</code></td> |
| 952 |
<td>Run once per second.</td> |
| 953 |
<td><code>struct p lugin param_timer *</code></td> |
| 954 |
<td></td> |
| 955 |
</tr> |
| 956 |
<tr class="even"> |
| 957 |
<td><code>time_t time_now</code></td> |
| 958 |
<td>The current unix timestamp.</td> |
| 959 |
<td></td> |
| 960 |
<td></td> |
| 961 |
</tr> |
| 962 |
<tr class="odd"> |
| 963 |
<td><code>plugin_new_session</code></td> |
| 964 |
<td>Called after a session is fully set up. The session is now ready to |
| 965 |
handle traffic.</td> |
| 966 |
<td><code>struct plugin param_new_session *</code></td> |
| 967 |
<td></td> |
| 968 |
</tr> |
| 969 |
<tr class="even"> |
| 970 |
<td><code>tunnelt *t</code></td> |
| 971 |
<td>Tunnel.</td> |
| 972 |
<td></td> |
| 973 |
<td></td> |
| 974 |
</tr> |
| 975 |
<tr class="odd"> |
| 976 |
<td><code>sessiont *s</code></td> |
| 977 |
<td>Session.</td> |
| 978 |
<td></td> |
| 979 |
<td></td> |
| 980 |
</tr> |
| 981 |
<tr class="even"> |
| 982 |
<td><code>plugin_kill_session</code></td> |
| 983 |
<td>Called when a session is about to be shut down. This may be called |
| 984 |
multiple times for the same session.</td> |
| 985 |
<td><code>struct plugin p aram_kill_session *</code></td> |
| 986 |
<td></td> |
| 987 |
</tr> |
| 988 |
<tr class="odd"> |
| 989 |
<td><code>tunnelt *t</code></td> |
| 990 |
<td>Tunnel.</td> |
| 991 |
<td></td> |
| 992 |
<td></td> |
| 993 |
</tr> |
| 994 |
<tr class="even"> |
| 995 |
<td><code>sessiont *s</code></td> |
| 996 |
<td>Session.</td> |
| 997 |
<td></td> |
| 998 |
<td></td> |
| 999 |
</tr> |
| 1000 |
<tr class="odd"> |
| 1001 |
<td><code>plugin_control</code></td> |
| 1002 |
<td><p>Called in whenever a <code>nsctl</code> packet is received. This |
| 1003 |
should handle the packet and form a response if required.</p> |
| 1004 |
<p>Plugin-specific help strings may be included in the output of |
| 1005 |
<code>nsctl help</code> by defining a <code>NULL</code> terminated list |
| 1006 |
of strings as follows:</p> |
| 1007 |
<pre><code>char</code></pre> |
| 1008 |
<p>*plugin_control_hel p[] = { …, NULL };</p></td> |
| 1009 |
<td><code>struct plu gin param_control *</code></td> |
| 1010 |
<td></td> |
| 1011 |
</tr> |
| 1012 |
<tr class="even"> |
| 1013 |
<td><code>int iam_master</code></td> |
| 1014 |
<td>If true, this node is the cluster master.</td> |
| 1015 |
<td></td> |
| 1016 |
<td></td> |
| 1017 |
</tr> |
| 1018 |
<tr class="odd"> |
| 1019 |
<td><code>int argc</code></td> |
| 1020 |
<td><code>nsctl</code> arguments.</td> |
| 1021 |
<td></td> |
| 1022 |
<td></td> |
| 1023 |
</tr> |
| 1024 |
<tr class="even"> |
| 1025 |
<td><code>char **argc</code></td> |
| 1026 |
<td></td> |
| 1027 |
<td></td> |
| 1028 |
<td></td> |
| 1029 |
</tr> |
| 1030 |
<tr class="odd"> |
| 1031 |
<td><code>int response</code></td> |
| 1032 |
<td>Response from control message (if handled): should be either |
| 1033 |
<code>NSCTL_RES_OK</code> or <code>NSCTL_RES_ERR</code>.</td> |
| 1034 |
<td></td> |
| 1035 |
<td></td> |
| 1036 |
</tr> |
| 1037 |
<tr class="even"> |
| 1038 |
<td><code>char *additional</code></td> |
| 1039 |
<td>Additional information, output by <code>nsctl</code> on receiving |
| 1040 |
the response.</td> |
| 1041 |
<td></td> |
| 1042 |
<td></td> |
| 1043 |
</tr> |
| 1044 |
<tr class="odd"> |
| 1045 |
<td colspan="4"><code>plugin_radius_response</code> | Called whenever a |
| 1046 |
| |
| 1047 |
<code>struct plugin para | | RADIUS response | m_radius_response *</code> |
| 1048 |
| | includes a | | | <code>Cisco-AVPair</code> | | | value. The value is |
| 1049 |
| | | split into | | | key<code>=</code>value pairs. | | | Will be |
| 1050 |
called once | | | for each pair in the | | | response. | |</td> |
| 1051 |
</tr> |
| 1052 |
<tr class="even"> |
| 1053 |
<td><code>tunnelt *t</code></td> |
| 1054 |
<td>Tunnel.</td> |
| 1055 |
<td></td> |
| 1056 |
<td></td> |
| 1057 |
</tr> |
| 1058 |
<tr class="odd"> |
| 1059 |
<td><code>sessiont *s</code></td> |
| 1060 |
<td>Session.</td> |
| 1061 |
<td></td> |
| 1062 |
<td></td> |
| 1063 |
</tr> |
| 1064 |
<tr class="even"> |
| 1065 |
<td><code>char *key</code></td> |
| 1066 |
<td>Key and value.</td> |
| 1067 |
<td></td> |
| 1068 |
<td></td> |
| 1069 |
</tr> |
| 1070 |
<tr class="odd"> |
| 1071 |
<td><code>char *value</code></td> |
| 1072 |
<td></td> |
| 1073 |
<td></td> |
| 1074 |
<td></td> |
| 1075 |
</tr> |
| 1076 |
<tr class="even"> |
| 1077 |
<td colspan="4"><code>plugin_radius_reset</code> | Called whenever a | |
| 1078 |
<code>struct p | | RADIUS CoA request | aram_radius_reset *</code> |
| 1079 |
| | is received to reset | | | any options to | | | default values | | | |
| 1080 |
before the new | | | values are applied. | |</td> |
| 1081 |
</tr> |
| 1082 |
<tr class="odd"> |
| 1083 |
<td><code>tunnelt *t</code></td> |
| 1084 |
<td>Tunnel.</td> |
| 1085 |
<td></td> |
| 1086 |
<td></td> |
| 1087 |
</tr> |
| 1088 |
<tr class="even"> |
| 1089 |
<td><code>sessiont *s</code></td> |
| 1090 |
<td>Session.</td> |
| 1091 |
<td></td> |
| 1092 |
<td></td> |
| 1093 |
</tr> |
| 1094 |
<tr class="odd"> |
| 1095 |
<td colspan="4"><code>plugin_radius_account</code> | Called when | |
| 1096 |
<code>struct par | | preparing a RADIUS | am_radius_account *</code> |
| 1097 |
| | accounting record to | | | allow additional | | | data to be added |
| 1098 |
to | | | the packet. | |</td> |
| 1099 |
</tr> |
| 1100 |
<tr class="even"> |
| 1101 |
<td><code>tunnelt *t</code></td> |
| 1102 |
<td>Tunnel.</td> |
| 1103 |
<td></td> |
| 1104 |
<td></td> |
| 1105 |
</tr> |
| 1106 |
<tr class="odd"> |
| 1107 |
<td><code>sessiont *s</code></td> |
| 1108 |
<td>Session.</td> |
| 1109 |
<td></td> |
| 1110 |
<td></td> |
| 1111 |
</tr> |
| 1112 |
<tr class="even"> |
| 1113 |
<td><code>uint8_t **packet</code></td> |
| 1114 |
<td>Pointer to the end of the currently assembled packet buffer. The |
| 1115 |
value should be incremented by the length of any data added.</td> |
| 1116 |
<td></td> |
| 1117 |
<td></td> |
| 1118 |
</tr> |
| 1119 |
<tr class="odd"> |
| 1120 |
<td colspan="4"><code>plugin_become_master</code> | Called when a node | |
| 1121 |
<code>void</code> | | elects itself | | | cluster master. | |</td> |
| 1122 |
</tr> |
| 1123 |
<tr class="even"> |
| 1124 |
<td>No arguments.</td> |
| 1125 |
<td></td> |
| 1126 |
<td></td> |
| 1127 |
<td></td> |
| 1128 |
</tr> |
| 1129 |
<tr class="odd"> |
| 1130 |
<td colspan="4"><code>plugin_new_session_master</code> | Called once for |
| 1131 |
each | <code>sessiont *</code> | open session on | | | becoming cluster |
| 1132 |
| | | master. | |</td> |
| 1133 |
</tr> |
| 1134 |
<tr class="even"> |
| 1135 |
<td>Session.</td> |
| 1136 |
<td></td> |
| 1137 |
<td></td> |
| 1138 |
<td></td> |
| 1139 |
</tr> |
| 1140 |
</tbody> |
| 1141 |
</table> |
| 1142 |
<h1 id="walled-garden">Walled Garden</h1> |
| 1143 |
<p>A "Walled Garden" is implemented so that you can provide perhaps |
| 1144 |
limited service to sessions that incorrectly authenticate.</p> |
| 1145 |
<p>Whenever a session provides incorrect authentication, and the RADIUS |
| 1146 |
server responds with Auth-Reject, the walled garden module (if loaded) |
| 1147 |
will force authentication to succeed, but set the |
| 1148 |
<code>walled_garden</code> flag in the session structure, and adds an |
| 1149 |
<code>iptables</code> rule to the <code>garden_users</code> chain to |
| 1150 |
cause all packets for the session to traverse the <code>garden</code> |
| 1151 |
chain.</p> |
| 1152 |
<p>This doesn't <em>just work</em>. To set this all up, you will to |
| 1153 |
setup the <code>garden</code> nat table with the <a |
| 1154 |
href="#config-build-garden">build-garden</a> script with rules to limit |
| 1155 |
user's traffic.</p> |
| 1156 |
<p>For example, to force all traffic except DNS to be forwarded to |
| 1157 |
192.168.1.1, add these entries to your <code>build-garden</code> |
| 1158 |
script:</p> |
| 1159 |
<pre><code>iptables -t nat -A garden -p tcp --dport ! 53 -j DNAT --to 192.168.1.1 |
| 1160 |
iptables -t nat -A garden -p udp --dport ! 53 -j DNAT --to 192.168.1.1</code></pre> |
| 1161 |
<p><code>l2tpns</code> will add entries to the <code>garden_users</code> |
| 1162 |
chain as appropriate.</p> |
| 1163 |
<p>You can check the amount of traffic being captured using the |
| 1164 |
following command:</p> |
| 1165 |
<pre><code>iptables -t nat -L garden -nvx</code></pre> |
| 1166 |
<h1 id="filtering">Filtering</h1> |
| 1167 |
<p>Sessions may be filtered by specifying <code>Filter-Id</code> |
| 1168 |
attributes in the RADIUS reply. filter.<code>in</code> specifies that |
| 1169 |
the named access-list filter should be applied to traffic from the |
| 1170 |
customer, filter.<code>out</code> specifies a list for traffic to the |
| 1171 |
customer.</p> |
| 1172 |
<h1 id="clustering">Clustering</h1> |
| 1173 |
<p>An <code>l2tpns</code> cluster consists of one* or more servers |
| 1174 |
configured with the same configuration, notably the multicast |
| 1175 |
<code>cluster_address</code> and the <code>cluster_port</code></p> |
| 1176 |
<p>*A stand-alone server is simply a degraded cluster.</p> |
| 1177 |
<p>Initially servers come up as cluster slaves, and periodically (every |
| 1178 |
<code>cluster_hb_interval</code>/10 seconds) send out ping packets |
| 1179 |
containing the start time of the process to the multicast |
| 1180 |
<code>cluster_address</code> on <code>cluster_port</code>.</p> |
| 1181 |
<p>A cluster master sends heartbeat rather than ping packets, which |
| 1182 |
contain those session and tunnel changes since the last heartbeat.</p> |
| 1183 |
<p>When a slave has not seen a heartbeat within |
| 1184 |
<code>cluster_hb_timeout</code>/10 seconds it "elects" a new master by |
| 1185 |
examining the list of peers it has seen pings from and determines which |
| 1186 |
of these and itself is the "best" candidate to be master. "Best" in this |
| 1187 |
context means the server with the highest uptime (the highest IP address |
| 1188 |
is used as a tie-breaker in the case of equal uptimes).</p> |
| 1189 |
<p>After discovering a master, and determining that it is up-to-date |
| 1190 |
(has seen an update for all in-use sessions and tunnels from heartbeat |
| 1191 |
packets) will raise a route (see <a href="#routing">Routing</a>) for the |
| 1192 |
<code>bind_address</code> and for all addresses/networks in |
| 1193 |
<code>ip_pool</code>.</p> |
| 1194 |
<p>Any packets received by the slave which would alter the session |
| 1195 |
state, as well as packets for throttled or gardened sessions are |
| 1196 |
forwarded to the master for handling. In addition, byte counters for |
| 1197 |
session traffic are periodically forwarded.</p> |
| 1198 |
<p>The heartbeat exchange use timing, so the master and slaves need to |
| 1199 |
have their time synchronized, e.g. with ntp.</p> |
| 1200 |
<p>Since all the masters and slaves should be able to receive all |
| 1201 |
packets, <code>bind_address</code> needs to be used to make all of them |
| 1202 |
agree on the IP to be used. If <code>l2tpns</code> is to behave as LAC, |
| 1203 |
<code>bind_address_remotelns</code> also needs to be set.</p> |
| 1204 |
<p>To balance the load, <code>bind_multi_address</code> can be used to |
| 1205 |
make them support several IPs, and one can then prioritize one or the |
| 1206 |
other on each server, and make e.g. radius pick up one of them randomly |
| 1207 |
for <code>Tunnel-Server-Endpoint</code>. There is currently no support |
| 1208 |
for such load balancing for LAC support.</p> |
| 1209 |
<p>*Configurable with <code>cluster_master_min_adv</code></p> |
| 1210 |
<p>Multiple clusters can be run on the same network by just using |
| 1211 |
different multicast <code>cluster_address</code>. However, for a given |
| 1212 |
host to be part of multiple clusters without mixing the clusters, |
| 1213 |
<code>cluster_port</code> must be different for each cluster.</p> |
| 1214 |
<h1 id="routing">Routing</h1> |
| 1215 |
<p>If you are running a single instance, you may simply statically route |
| 1216 |
the IP pools to the <code>bind_address</code> (<code>l2tpns</code> will |
| 1217 |
send a gratuitous arp).</p> |
| 1218 |
<p>For a cluster, configure the members as BGP neighbours on your router |
| 1219 |
and configure multi-path load-balancing. Cisco uses |
| 1220 |
<code>maximum-paths ibgp</code> for IBGP. If this is not supported by |
| 1221 |
your IOS revision, you can use <code>maximum-paths</code> (which works |
| 1222 |
for EBGP) and set <code>as_number</code> to a private value such as |
| 1223 |
64512.</p> |