| 1 | .\"- |
| 2 | .\" Copyright (c) 2001 Charles Mott <cm@linktel.net> |
| 3 | .\" All rights reserved. |
| 4 | .\" |
| 5 | .\" Redistribution and use in source and binary forms, with or without |
| 6 | .\" modification, are permitted provided that the following conditions |
| 7 | .\" are met: |
| 8 | .\" 1. Redistributions of source code must retain the above copyright |
| 9 | .\" notice, this list of conditions and the following disclaimer. |
| 10 | .\" 2. Redistributions in binary form must reproduce the above copyright |
| 11 | .\" notice, this list of conditions and the following disclaimer in the |
| 12 | .\" documentation and/or other materials provided with the distribution. |
| 13 | .\" |
| 14 | .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND |
| 15 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| 16 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| 17 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE |
| 18 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
| 19 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
| 20 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
| 21 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
| 22 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
| 23 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
| 24 | .\" SUCH DAMAGE. |
| 25 | .\" |
| 26 | .\" $FreeBSD: src/lib/libalias/libalias.3,v 1.23.2.11 2001/12/17 10:08:22 ru Exp $ |
| 27 | .\" $DragonFly: src/lib/libalias/libalias.3,v 1.4 2006/05/26 19:39:36 swildner Exp $ |
| 28 | .\" |
| 29 | .Dd April 13, 2000 |
| 30 | .Dt LIBALIAS 3 |
| 31 | .Os |
| 32 | .Sh NAME |
| 33 | .Nm libalias |
| 34 | .Nd packet aliasing library for masquerading and network address translation |
| 35 | .Sh SYNOPSIS |
| 36 | .In sys/types.h |
| 37 | .In netinet/in.h |
| 38 | .In alias.h |
| 39 | .Pp |
| 40 | Function prototypes are given in the main body of the text. |
| 41 | .Sh DESCRIPTION |
| 42 | The |
| 43 | .Nm |
| 44 | library is a collection of functions for aliasing and de-aliasing of IP |
| 45 | packets, intended for masquerading and network address translation (NAT). |
| 46 | .Sh INTRODUCTION |
| 47 | This library is a moderately portable set of functions designed to assist |
| 48 | in the process of IP masquerading and network address translation. |
| 49 | Outgoing packets from a local network with unregistered IP addresses can |
| 50 | be aliased to appear as if they came from an accessible IP address. |
| 51 | Incoming packets are then de-aliased so that they are sent to the correct |
| 52 | machine on the local network. |
| 53 | .Pp |
| 54 | A certain amount of flexibility is built into the packet aliasing engine. |
| 55 | In the simplest mode of operation, a many-to-one address mapping takes |
| 56 | place between local network and the packet aliasing host. |
| 57 | This is known as IP masquerading. |
| 58 | In addition, one-to-one mappings between local and public addresses can |
| 59 | also be implemented, which is known as static NAT. |
| 60 | In between these extremes, different groups of private addresses can be |
| 61 | linked to different public addresses, comprising several distinct |
| 62 | many-to-one mappings. |
| 63 | Also, a given public address and port can be statically redirected to a |
| 64 | private address/port. |
| 65 | .Pp |
| 66 | The packet aliasing engine was designed to operate in user space outside |
| 67 | of the kernel, without any access to private kernel data structure, but |
| 68 | the source code can also be ported to a kernel environment. |
| 69 | .Sh INITIALIZATION AND CONTROL |
| 70 | Two special functions, |
| 71 | .Fn PacketAliasInit |
| 72 | and |
| 73 | .Fn PacketAliasSetAddress , |
| 74 | must always be called before any packet handling may be performed. |
| 75 | In addition, the operating mode of the packet aliasing engine can be |
| 76 | customized by calling |
| 77 | .Fn PacketAliasSetMode . |
| 78 | .Pp |
| 79 | .Ft void |
| 80 | .Fn PacketAliasInit void |
| 81 | .Bd -ragged -offset indent |
| 82 | This function has no arguments or return value and is used to initialize |
| 83 | internal data structures. |
| 84 | The following mode bits are always set after calling |
| 85 | .Fn PacketAliasInit . |
| 86 | See the description of |
| 87 | .Fn PacketAliasSetMode |
| 88 | below for the meaning of these mode bits. |
| 89 | .Pp |
| 90 | .Bl -item -offset indent -compact |
| 91 | .It |
| 92 | .Dv PKT_ALIAS_SAME_PORTS |
| 93 | .It |
| 94 | .Dv PKT_ALIAS_USE_SOCKETS |
| 95 | .It |
| 96 | .Dv PKT_ALIAS_RESET_ON_ADDR_CHANGE |
| 97 | .El |
| 98 | .Pp |
| 99 | This function will always return the packet aliasing engine to the same |
| 100 | initial state. |
| 101 | .Fn PacketAliasSetAddress |
| 102 | must be called afterwards, and any desired changes from the default mode |
| 103 | bits listed above require a call to |
| 104 | .Fn PacketAliasSetMode . |
| 105 | .Pp |
| 106 | It is mandatory that this function be called at the beginning of a program |
| 107 | prior to any packet handling. |
| 108 | .Ed |
| 109 | .Pp |
| 110 | .Ft void |
| 111 | .Fn PacketAliasUninit void |
| 112 | .Bd -ragged -offset indent |
| 113 | This function has no arguments or return value and is used to clear any |
| 114 | resources attached to internal data structures. |
| 115 | .Pp |
| 116 | This functions should be called when a program stops using the aliasing |
| 117 | engine; it does, amongst other things, clear out any firewall holes. |
| 118 | To provide backwards compatibility and extra security, it is added to |
| 119 | the |
| 120 | .Xr atexit 3 |
| 121 | chain by |
| 122 | .Fn PacketAliasInit . |
| 123 | Calling it multiple times is harmless. |
| 124 | .Ed |
| 125 | .Pp |
| 126 | .Ft void |
| 127 | .Fn PacketAliasSetAddress "struct in_addr addr" |
| 128 | .Bd -ragged -offset indent |
| 129 | This function sets the source address to which outgoing packets from the |
| 130 | local area network are aliased. |
| 131 | All outgoing packets are re-mapped to this address unless overridden by a |
| 132 | static address mapping established by |
| 133 | .Fn PacketAliasRedirectAddr . |
| 134 | .Pp |
| 135 | If the |
| 136 | .Dv PKT_ALIAS_RESET_ON_ADDR_CHANGE |
| 137 | mode bit is set (the default mode of operation), then the internal aliasing |
| 138 | link tables will be reset any time the aliasing address changes. |
| 139 | This is useful for interfaces such as |
| 140 | .Xr ppp 8 , |
| 141 | where the IP |
| 142 | address may or may not change on successive dial-up attempts. |
| 143 | .Pp |
| 144 | If the |
| 145 | .Dv PKT_ALIAS_RESET_ON_ADDR_CHANGE |
| 146 | mode bit is set to zero, this function can also be used to dynamically change |
| 147 | the aliasing address on a packet to packet basis (it is a low overhead call). |
| 148 | .Pp |
| 149 | It is mandatory that this function be called prior to any packet handling. |
| 150 | .Ed |
| 151 | .Pp |
| 152 | .Ft unsigned int |
| 153 | .Fn PacketAliasSetMode "unsigned int flags" "unsigned int mask" |
| 154 | .Bd -ragged -offset indent |
| 155 | This function sets or clears mode bits |
| 156 | according to the value of |
| 157 | .Fa flags . |
| 158 | Only bits marked in |
| 159 | .Fa mask |
| 160 | are affected. |
| 161 | The following mode bits are defined in |
| 162 | .In alias.h : |
| 163 | .Bl -tag -width indent |
| 164 | .It Dv PKT_ALIAS_LOG |
| 165 | Enables logging into |
| 166 | .Pa /var/log/alias.log . |
| 167 | Each time an aliasing link is created or deleted, the log file is appended |
| 168 | with the current number of ICMP, TCP and UDP links. |
| 169 | Mainly useful for debugging when the log file is viewed continuously with |
| 170 | .Xr tail 1 . |
| 171 | .It Dv PKT_ALIAS_DENY_INCOMING |
| 172 | If this mode bit is set, all incoming packets associated with new TCP |
| 173 | connections or new UDP transactions will be marked for being ignored |
| 174 | .Fn ( PacketAliasIn |
| 175 | returns |
| 176 | .Dv PKT_ALIAS_IGNORED |
| 177 | code) |
| 178 | by the calling program. |
| 179 | Response packets to connections or transactions initiated from the packet |
| 180 | aliasing host or local network will be unaffected. |
| 181 | This mode bit is useful for implementing a one-way firewall. |
| 182 | .It Dv PKT_ALIAS_SAME_PORTS |
| 183 | If this mode bit is set, the packet aliasing engine will attempt to leave |
| 184 | the alias port numbers unchanged from the actual local port numbers. |
| 185 | This can be done as long as the quintuple (proto, alias addr, alias port, |
| 186 | remote addr, remote port) is unique. |
| 187 | If a conflict exists, a new aliasing port number is chosen even if this |
| 188 | mode bit is set. |
| 189 | .It Dv PKT_ALIAS_USE_SOCKETS |
| 190 | This bit should be set when the packet aliasing host originates network |
| 191 | traffic as well as forwards it. |
| 192 | When the packet aliasing host is waiting for a connection from an unknown |
| 193 | host address or unknown port number (e.g. an FTP data connection), this |
| 194 | mode bit specifies that a socket be allocated as a place holder to prevent |
| 195 | port conflicts. |
| 196 | Once a connection is established, usually within a minute or so, the socket |
| 197 | is closed. |
| 198 | .It Dv PKT_ALIAS_UNREGISTERED_ONLY |
| 199 | If this mode bit is set, traffic on the local network which does not |
| 200 | originate from unregistered address spaces will be ignored. |
| 201 | Standard Class A, B and C unregistered addresses are: |
| 202 | .Bd -literal -offset indent |
| 203 | 10.0.0.0 -> 10.255.255.255 (Class A subnet) |
| 204 | 172.16.0.0 -> 172.31.255.255 (Class B subnets) |
| 205 | 192.168.0.0 -> 192.168.255.255 (Class C subnets) |
| 206 | .Ed |
| 207 | .Pp |
| 208 | This option is useful in the case that packet aliasing host has both |
| 209 | registered and unregistered subnets on different interfaces. |
| 210 | The registered subnet is fully accessible to the outside world, so traffic |
| 211 | from it does not need to be passed through the packet aliasing engine. |
| 212 | .It Dv PKT_ALIAS_RESET_ON_ADDR_CHANGE |
| 213 | When this mode bit is set and |
| 214 | .Fn PacketAliasSetAddress |
| 215 | is called to change the aliasing address, the internal link table of the |
| 216 | packet aliasing engine will be cleared. |
| 217 | This operating mode is useful for |
| 218 | .Xr ppp 8 |
| 219 | links where the interface address can sometimes change or remain the same |
| 220 | between dial-up attempts. |
| 221 | If this mode bit is not set, the link table will never be reset in the event |
| 222 | of an address change. |
| 223 | .It Dv PKT_ALIAS_PUNCH_FW |
| 224 | This option makes |
| 225 | .Nm |
| 226 | `punch holes' in an |
| 227 | .Xr ipfirewall 4 |
| 228 | based firewall for FTP/IRC DCC connections. |
| 229 | The holes punched are bound by from/to IP address and port; it will not be |
| 230 | possible to use a hole for another connection. |
| 231 | A hole is removed when the connection that uses it dies. |
| 232 | To cater to unexpected death of a program using |
| 233 | .Nm |
| 234 | (e.g. kill -9), |
| 235 | changing the state of the flag will clear the entire firewall range |
| 236 | allocated for holes. |
| 237 | This will also happen on the initial call to |
| 238 | .Fn PacketAliasSetFWBase . |
| 239 | This call must happen prior to setting this flag. |
| 240 | .It Dv PKT_ALIAS_REVERSE |
| 241 | This option makes |
| 242 | .Nm |
| 243 | reverse the way it handles incoming and outgoing packets, allowing it |
| 244 | to be fed with data that passes through the internal interface rather |
| 245 | than the external one. |
| 246 | .It Dv PKT_ALIAS_PROXY_ONLY |
| 247 | This option tells |
| 248 | .Nm |
| 249 | to obey transparent proxy rules only. |
| 250 | Normal packet aliasing is not performed. |
| 251 | See |
| 252 | .Fn PacketAliasProxyRule |
| 253 | below for details. |
| 254 | .El |
| 255 | .Ed |
| 256 | .Pp |
| 257 | .Ft void |
| 258 | .Fn PacketAliasSetFWBase "unsigned int base" "unsigned int num" |
| 259 | .Bd -ragged -offset indent |
| 260 | Set firewall range allocated for punching firewall holes (with the |
| 261 | .Dv PKT_ALIAS_PUNCH_FW |
| 262 | flag). |
| 263 | The range will be cleared for all rules on initialization. |
| 264 | .Ed |
| 265 | .Sh PACKET HANDLING |
| 266 | The packet handling functions are used to modify incoming (remote to local) |
| 267 | and outgoing (local to remote) packets. |
| 268 | The calling program is responsible for receiving and sending packets via |
| 269 | network interfaces. |
| 270 | .Pp |
| 271 | Along with |
| 272 | .Fn PacketAliasInit |
| 273 | and |
| 274 | .Fn PacketAliasSetAddress , |
| 275 | the two packet handling functions, |
| 276 | .Fn PacketAliasIn |
| 277 | and |
| 278 | .Fn PacketAliasOut , |
| 279 | comprise minimal set of functions needed for a basic IP masquerading |
| 280 | implementation. |
| 281 | .Pp |
| 282 | .Ft int |
| 283 | .Fn PacketAliasIn "char *buffer" "int maxpacketsize" |
| 284 | .Bd -ragged -offset indent |
| 285 | An incoming packet coming from a remote machine to the local network is |
| 286 | de-aliased by this function. |
| 287 | The IP packet is pointed to by |
| 288 | .Fa buffer , |
| 289 | and |
| 290 | .Fa maxpacketsize |
| 291 | indicates the size of the data structure containing the packet and should |
| 292 | be at least as large as the actual packet size. |
| 293 | .Pp |
| 294 | Return codes: |
| 295 | .Bl -tag -width indent |
| 296 | .It Dv PKT_ALIAS_OK |
| 297 | The packet aliasing process was successful. |
| 298 | .It Dv PKT_ALIAS_IGNORED |
| 299 | The packet was ignored and not de-aliased. |
| 300 | This can happen if the protocol is unrecognized, possibly an ICMP message |
| 301 | type is not handled or if incoming packets for new connections are being |
| 302 | ignored (if |
| 303 | .Dv PKT_ALIAS_DENY_INCOMING |
| 304 | mode bit was set by |
| 305 | .Fn PacketAliasSetMode ) . |
| 306 | .It Dv PKT_ALIAS_UNRESOLVED_FRAGMENT |
| 307 | This is returned when a fragment cannot be resolved because the header |
| 308 | fragment has not been sent yet. |
| 309 | In this situation, fragments must be saved with |
| 310 | .Fn PacketAliasSaveFragment |
| 311 | until a header fragment is found. |
| 312 | .It Dv PKT_ALIAS_FOUND_HEADER_FRAGMENT |
| 313 | The packet aliasing process was successful, and a header fragment was found. |
| 314 | This is a signal to retrieve any unresolved fragments with |
| 315 | .Fn PacketAliasGetFragment |
| 316 | and de-alias them with |
| 317 | .Fn PacketAliasFragmentIn . |
| 318 | .It Dv PKT_ALIAS_ERROR |
| 319 | An internal error within the packet aliasing engine occurred. |
| 320 | .El |
| 321 | .Ed |
| 322 | .Pp |
| 323 | .Ft int |
| 324 | .Fn PacketAliasOut "char *buffer" "int maxpacketsize" |
| 325 | .Bd -ragged -offset indent |
| 326 | An outgoing packet coming from the local network to a remote machine is |
| 327 | aliased by this function. |
| 328 | The IP packet is pointed to by |
| 329 | .Fa buffer , |
| 330 | and |
| 331 | .Fa maxpacketsize |
| 332 | indicates the maximum packet size permissible should the packet length be |
| 333 | changed. |
| 334 | IP encoding protocols place address and port information in the encapsulated |
| 335 | data stream which has to be modified and can account for changes in packet |
| 336 | length. |
| 337 | Well known examples of such protocols are FTP and IRC DCC. |
| 338 | .Pp |
| 339 | Return codes: |
| 340 | .Bl -tag -width indent |
| 341 | .It Dv PKT_ALIAS_OK |
| 342 | The packet aliasing process was successful. |
| 343 | .It Dv PKT_ALIAS_IGNORED |
| 344 | The packet was ignored and not aliased. |
| 345 | This can happen if the protocol is unrecognized, or possibly an ICMP message |
| 346 | type is not handled. |
| 347 | .It Dv PKT_ALIAS_ERROR |
| 348 | An internal error within the packet aliasing engine occurred. |
| 349 | .El |
| 350 | .Ed |
| 351 | .Sh PORT AND ADDRESS REDIRECTION |
| 352 | The functions described in this section allow machines on the local network |
| 353 | to be accessible in some degree to new incoming connections from the external |
| 354 | network. |
| 355 | Individual ports can be re-mapped or static network address translations can |
| 356 | be designated. |
| 357 | .Pp |
| 358 | .Ft struct alias_link * |
| 359 | .Fo PacketAliasRedirectPort |
| 360 | .Fa "struct in_addr local_addr" |
| 361 | .Fa "u_short local_port" |
| 362 | .Fa "struct in_addr remote_addr" |
| 363 | .Fa "u_short remote_port" |
| 364 | .Fa "struct in_addr alias_addr" |
| 365 | .Fa "u_short alias_port" |
| 366 | .Fa "u_char proto" |
| 367 | .Fc |
| 368 | .Bd -ragged -offset indent |
| 369 | This function specifies that traffic from a given remote address/port to |
| 370 | an alias address/port be redirected to a specified local address/port. |
| 371 | The parameter |
| 372 | .Fa proto |
| 373 | can be either |
| 374 | .Dv IPPROTO_TCP |
| 375 | or |
| 376 | .Dv IPPROTO_UDP , |
| 377 | as defined in |
| 378 | .In netinet/in.h . |
| 379 | .Pp |
| 380 | If |
| 381 | .Fa local_addr |
| 382 | or |
| 383 | .Fa alias_addr |
| 384 | is zero, this indicates that the packet aliasing address as established |
| 385 | by |
| 386 | .Fn PacketAliasSetAddress |
| 387 | is to be used. |
| 388 | Even if |
| 389 | .Fn PacketAliasSetAddress |
| 390 | is called to change the address after |
| 391 | .Fn PacketAliasRedirectPort |
| 392 | is called, a zero reference will track this change. |
| 393 | .Pp |
| 394 | If the link is further set up to operate for a load sharing, then |
| 395 | .Fa local_addr |
| 396 | and |
| 397 | .Fa local_port |
| 398 | are ignored, and are selected dynamically from the server pool, as described in |
| 399 | .Fn PacketAliasAddServer |
| 400 | below. |
| 401 | .Pp |
| 402 | If |
| 403 | .Fa remote_addr |
| 404 | is zero, this indicates to redirect packets from any remote address. |
| 405 | Likewise, if |
| 406 | .Fa remote_port |
| 407 | is zero, this indicates to redirect packets originating from any remote |
| 408 | port number. |
| 409 | Almost always, the remote port specification will be zero, but non-zero |
| 410 | remote addresses can sometimes be useful for firewalling. |
| 411 | If two calls to |
| 412 | .Fn PacketAliasRedirectPort |
| 413 | overlap in their address/port specifications, then the most recent call |
| 414 | will have precedence. |
| 415 | .Pp |
| 416 | This function returns a pointer which can subsequently be used by |
| 417 | .Fn PacketAliasRedirectDelete . |
| 418 | If |
| 419 | .Dv NULL |
| 420 | is returned, then the function call did not complete successfully. |
| 421 | .Pp |
| 422 | All port numbers should be in network address byte order, so it is necessary |
| 423 | to use |
| 424 | .Xr htons 3 |
| 425 | to convert these parameters from internally readable numbers to network byte |
| 426 | order. |
| 427 | Addresses are also in network byte order, which is implicit in the use of the |
| 428 | .Fa struct in_addr |
| 429 | data type. |
| 430 | .Ed |
| 431 | .Pp |
| 432 | .Ft struct alias_link * |
| 433 | .Fo PacketAliasRedirectAddr |
| 434 | .Fa "struct in_addr local_addr" |
| 435 | .Fa "struct in_addr alias_addr" |
| 436 | .Fc |
| 437 | .Bd -ragged -offset indent |
| 438 | This function designates that all incoming traffic to |
| 439 | .Fa alias_addr |
| 440 | be redirected to |
| 441 | .Fa local_addr . |
| 442 | Similarly, all outgoing traffic from |
| 443 | .Fa local_addr |
| 444 | is aliased to |
| 445 | .Fa alias_addr . |
| 446 | .Pp |
| 447 | If |
| 448 | .Fa local_addr |
| 449 | or |
| 450 | .Fa alias_addr |
| 451 | is zero, this indicates that the packet aliasing address as established by |
| 452 | .Fn PacketAliasSetAddress |
| 453 | is to be used. |
| 454 | Even if |
| 455 | .Fn PacketAliasSetAddress |
| 456 | is called to change the address after |
| 457 | .Fn PacketAliasRedirectAddr |
| 458 | is called, a zero reference will track this change. |
| 459 | .Pp |
| 460 | If the link is further set up to operate for a load sharing, then |
| 461 | .Fa local_addr |
| 462 | is ignored, and is selected dynamically from the server pool, as described in |
| 463 | .Fn PacketAliasAddServer |
| 464 | below. |
| 465 | .Pp |
| 466 | If subsequent calls to |
| 467 | .Fn PacketAliasRedirectAddr |
| 468 | use the same aliasing address, all new incoming traffic to this aliasing |
| 469 | address will be redirected to the local address made in the last function |
| 470 | call. |
| 471 | New traffic generated by any of the local machines, designated in the |
| 472 | several function calls, will be aliased to the same address. |
| 473 | Consider the following example: |
| 474 | .Bd -literal -offset indent |
| 475 | PacketAliasRedirectAddr(inet_aton("192.168.0.2"), |
| 476 | inet_aton("141.221.254.101")); |
| 477 | PacketAliasRedirectAddr(inet_aton("192.168.0.3"), |
| 478 | inet_aton("141.221.254.101")); |
| 479 | PacketAliasRedirectAddr(inet_aton("192.168.0.4"), |
| 480 | inet_aton("141.221.254.101")); |
| 481 | .Ed |
| 482 | .Pp |
| 483 | Any outgoing connections such as |
| 484 | .Xr telnet 1 |
| 485 | or |
| 486 | .Xr ftp 1 |
| 487 | from 192.168.0.2, 192.168.0.3 and 192.168.0.4 will appear to come from |
| 488 | 141.221.254.101. |
| 489 | Any incoming connections to 141.221.254.101 will be directed to 192.168.0.4. |
| 490 | .Pp |
| 491 | Any calls to |
| 492 | .Fn PacketAliasRedirectPort |
| 493 | will have precedence over address mappings designated by |
| 494 | .Fn PacketAliasRedirectAddr . |
| 495 | .Pp |
| 496 | This function returns a pointer which can subsequently be used by |
| 497 | .Fn PacketAliasRedirectDelete . |
| 498 | If |
| 499 | .Dv NULL |
| 500 | is returned, then the function call did not complete successfully. |
| 501 | .Ed |
| 502 | .Pp |
| 503 | .Ft int |
| 504 | .Fo PacketAliasAddServer |
| 505 | .Fa "struct alias_link *link" |
| 506 | .Fa "struct in_addr addr" |
| 507 | .Fa "u_short port" |
| 508 | .Fc |
| 509 | .Bd -ragged -offset indent |
| 510 | This function sets the |
| 511 | .Fa link |
| 512 | up for Load Sharing using IP Network Address Translation (RFC 2391, LSNAT). |
| 513 | LSNAT operates as follows. |
| 514 | A client attempts to access a server by using the server virtual address. |
| 515 | The LSNAT router transparently redirects the request to one of the hosts |
| 516 | in server pool, selected using a real-time load sharing algorithm. |
| 517 | Multiple sessions may be initiated from the same client, and each session |
| 518 | could be directed to a different host based on load balance across server |
| 519 | pool hosts at the time. |
| 520 | If load share is desired for just a few specific services, the configuration |
| 521 | on LSNAT could be defined to restrict load share for just the services |
| 522 | desired. |
| 523 | .Pp |
| 524 | Currently, only the simplest selection algorithm is implemented, where a |
| 525 | host is selected on a round-robin basis only, without regard to load on |
| 526 | the host. |
| 527 | .Pp |
| 528 | First, the |
| 529 | .Fa link |
| 530 | is created by either |
| 531 | .Fn PacketAliasRedirectPort |
| 532 | or |
| 533 | .Fn PacketAliasRedirectAddr . |
| 534 | Then, |
| 535 | .Fn PacketAliasAddServer |
| 536 | is called multiple times to add entries to the |
| 537 | .Fa link Ns 's |
| 538 | server pool. |
| 539 | .Pp |
| 540 | For links created with |
| 541 | .Fn PacketAliasRedirectAddr , |
| 542 | the |
| 543 | .Fa port |
| 544 | argument is ignored and could have any value, e.g. htons(~0). |
| 545 | .Pp |
| 546 | This function returns 0 on success, -1 otherwise. |
| 547 | .Ed |
| 548 | .Pp |
| 549 | .Ft void |
| 550 | .Fn PacketAliasRedirectDelete "struct alias_link *link" |
| 551 | .Bd -ragged -offset indent |
| 552 | This function will delete a specific static redirect rule entered by |
| 553 | .Fn PacketAliasRedirectPort |
| 554 | or |
| 555 | .Fn PacketAliasRedirectAddr . |
| 556 | The parameter |
| 557 | .Fa link |
| 558 | is the pointer returned by either of the redirection functions. |
| 559 | If an invalid pointer is passed to |
| 560 | .Fn PacketAliasRedirectDelete , |
| 561 | then a program crash or unpredictable operation could result, so it is |
| 562 | necessary to be careful using this function. |
| 563 | .Ed |
| 564 | .Pp |
| 565 | .Ft int |
| 566 | .Fn PacketAliasProxyRule "const char *cmd" |
| 567 | .Bd -ragged -offset indent |
| 568 | The passed |
| 569 | .Fa cmd |
| 570 | string consists of one or more pairs of words. |
| 571 | The first word in each pair is a token and the second is the value that |
| 572 | should be applied for that token. |
| 573 | Tokens and their argument types are as follows: |
| 574 | .Bl -tag -width indent |
| 575 | .It Cm type encode_ip_hdr | encode_tcp_stream | no_encode |
| 576 | In order to support transparent proxying, it is necessary to somehow |
| 577 | pass the original address and port information into the new destination |
| 578 | server. |
| 579 | If |
| 580 | .Cm encode_ip_hdr |
| 581 | is specified, the original address and port is passed as an extra IP |
| 582 | option. |
| 583 | If |
| 584 | .Cm encode_tcp_stream |
| 585 | is specified, the original address and port is passed as the first |
| 586 | piece of data in the TCP stream in the format |
| 587 | .Dq DEST Ar IP port . |
| 588 | .It Cm port Ar portnum |
| 589 | Only packets with the destination port |
| 590 | .Ar portnum |
| 591 | are proxied. |
| 592 | .It Cm server Ar host Ns Xo |
| 593 | .Op : Ns Ar portnum |
| 594 | .Xc |
| 595 | This specifies the |
| 596 | .Ar host |
| 597 | and |
| 598 | .Ar portnum |
| 599 | that the data is to be redirected to. |
| 600 | .Ar host |
| 601 | must be an IP address rather than a DNS host name. |
| 602 | If |
| 603 | .Ar portnum |
| 604 | is not specified, the destination port number is not changed. |
| 605 | .Pp |
| 606 | The |
| 607 | .Ar server |
| 608 | specification is mandatory unless the |
| 609 | .Cm delete |
| 610 | command is being used. |
| 611 | .It Cm rule Ar index |
| 612 | Normally, each call to |
| 613 | .Fn PacketAliasProxyRule |
| 614 | inserts the next rule at the start of a linear list of rules. |
| 615 | If an |
| 616 | .Ar index |
| 617 | is specified, the new rule will be checked after all rules with lower |
| 618 | indices. |
| 619 | Calls to |
| 620 | .Fn PacketAliasProxyRule |
| 621 | that do not specify a rule are assigned rule 0. |
| 622 | .It Cm delete Ar index |
| 623 | This token and its argument MUST NOT be used with any other tokens. |
| 624 | When used, all existing rules with the given |
| 625 | .Ar index |
| 626 | are deleted. |
| 627 | .It Cm proto tcp | udp |
| 628 | If specified, only packets of the given protocol type are matched. |
| 629 | .It Cm src Ar IP Ns Xo |
| 630 | .Op / Ns Ar bits |
| 631 | .Xc |
| 632 | If specified, only packets with a source address matching the given |
| 633 | .Ar IP |
| 634 | are matched. |
| 635 | If |
| 636 | .Ar bits |
| 637 | is also specified, then the first |
| 638 | .Ar bits |
| 639 | bits of |
| 640 | .Ar IP |
| 641 | are taken as a network specification, and all IP addresses from that |
| 642 | network will be matched. |
| 643 | .It Cm dst Ar IP Ns Xo |
| 644 | .Op / Ns Ar bits |
| 645 | .Xc |
| 646 | If specified, only packets with a destination address matching the given |
| 647 | .Ar IP |
| 648 | are matched. |
| 649 | If |
| 650 | .Ar bits |
| 651 | is also specified, then the first |
| 652 | .Ar bits |
| 653 | bits of |
| 654 | .Ar IP |
| 655 | are taken as a network specification, and all IP addresses from that |
| 656 | network will be matched. |
| 657 | .El |
| 658 | .Pp |
| 659 | This function is usually used to redirect outgoing connections for |
| 660 | internal machines that are not permitted certain types of internet |
| 661 | access, or to restrict access to certain external machines. |
| 662 | .Ed |
| 663 | .Pp |
| 664 | .Ft struct alias_link * |
| 665 | .Fo PacketAliasRedirectProto |
| 666 | .Fa "struct in_addr local_addr" |
| 667 | .Fa "struct in_addr remote_addr" |
| 668 | .Fa "struct in_addr alias_addr" |
| 669 | .Fa "u_char proto" |
| 670 | .Fc |
| 671 | .Bd -ragged -offset indent |
| 672 | This function specifies that any IP packet with protocol number of |
| 673 | .Fa proto |
| 674 | from a given remote address to an alias address be |
| 675 | redirected to a specified local address. |
| 676 | .Pp |
| 677 | If |
| 678 | .Fa local_addr |
| 679 | or |
| 680 | .Fa alias_addr |
| 681 | is zero, this indicates that the packet aliasing address as established |
| 682 | by |
| 683 | .Fn PacketAliasSetAddress |
| 684 | is to be used. |
| 685 | Even if |
| 686 | .Fn PacketAliasSetAddress |
| 687 | is called to change the address after |
| 688 | .Fn PacketAliasRedirectProto |
| 689 | is called, a zero reference will track this change. |
| 690 | .Pp |
| 691 | If |
| 692 | .Fa remote_addr |
| 693 | is zero, this indicates to redirect packets from any remote address. |
| 694 | Non-zero remote addresses can sometimes be useful for firewalling. |
| 695 | .Pp |
| 696 | If two calls to |
| 697 | .Fn PacketAliasRedirectProto |
| 698 | overlap in their address specifications, then the most recent call |
| 699 | will have precedence. |
| 700 | .Pp |
| 701 | This function returns a pointer which can subsequently be used by |
| 702 | .Fn PacketAliasRedirectDelete . |
| 703 | If |
| 704 | .Dv NULL |
| 705 | is returned, then the function call did not complete successfully. |
| 706 | .Ed |
| 707 | .Sh FRAGMENT HANDLING |
| 708 | The functions in this section are used to deal with incoming fragments. |
| 709 | .Pp |
| 710 | Outgoing fragments are handled within |
| 711 | .Fn PacketAliasOut |
| 712 | by changing the address according to any applicable mapping set by |
| 713 | .Fn PacketAliasRedirectAddr , |
| 714 | or the default aliasing address set by |
| 715 | .Fn PacketAliasSetAddress . |
| 716 | .Pp |
| 717 | Incoming fragments are handled in one of two ways. |
| 718 | If the header of a fragmented IP packet has already been seen, then all |
| 719 | subsequent fragments will be re-mapped in the same manner the header |
| 720 | fragment was. |
| 721 | Fragments which arrive before the header are saved and then retrieved |
| 722 | once the header fragment has been resolved. |
| 723 | .Pp |
| 724 | .Ft int |
| 725 | .Fn PacketAliasSaveFragment "char *ptr" |
| 726 | .Bd -ragged -offset indent |
| 727 | When |
| 728 | .Fn PacketAliasIn |
| 729 | returns |
| 730 | .Dv PKT_ALIAS_UNRESOLVED_FRAGMENT , |
| 731 | this function can be used to save the pointer to the unresolved fragment. |
| 732 | .Pp |
| 733 | It is implicitly assumed that |
| 734 | .Fa ptr |
| 735 | points to a block of memory allocated by |
| 736 | .Xr malloc 3 . |
| 737 | If the fragment is never resolved, the packet aliasing engine will |
| 738 | automatically free the memory after a timeout period. |
| 739 | [Eventually this function should be modified so that a callback function |
| 740 | for freeing memory is passed as an argument.] |
| 741 | .Pp |
| 742 | This function returns |
| 743 | .Dv PKT_ALIAS_OK |
| 744 | if it was successful and |
| 745 | .Dv PKT_ALIAS_ERROR |
| 746 | if there was an error. |
| 747 | .Ed |
| 748 | .Pp |
| 749 | .Ft char * |
| 750 | .Fn PacketAliasGetFragment "char *buffer" |
| 751 | .Bd -ragged -offset indent |
| 752 | This function can be used to retrieve fragment pointers saved by |
| 753 | .Fn PacketAliasSaveFragment . |
| 754 | The IP header fragment pointed to by |
| 755 | .Fa buffer |
| 756 | is the header fragment indicated when |
| 757 | .Fn PacketAliasIn |
| 758 | returns |
| 759 | .Dv PKT_ALIAS_FOUND_HEADER_FRAGMENT . |
| 760 | Once a fragment pointer is retrieved, it becomes the calling program's |
| 761 | responsibility to free the dynamically allocated memory for the fragment. |
| 762 | .Pp |
| 763 | .Fn PacketAliasGetFragment |
| 764 | can be called sequentially until there are no more fragments available, |
| 765 | at which time it returns |
| 766 | .Dv NULL . |
| 767 | .Ed |
| 768 | .Pp |
| 769 | .Ft void |
| 770 | .Fn PacketAliasFragmentIn "char *header" "char *fragment" |
| 771 | .Bd -ragged -offset indent |
| 772 | When a fragment is retrieved with |
| 773 | .Fn PacketAliasGetFragment , |
| 774 | it can then be de-aliased with a call to |
| 775 | .Fn PacketAliasFragmentIn . |
| 776 | The |
| 777 | .Fa header |
| 778 | argument is the pointer to a header fragment used as a template, and |
| 779 | .Fa fragment |
| 780 | is the pointer to the packet to be de-aliased. |
| 781 | .Ed |
| 782 | .Sh MISCELLANEOUS FUNCTIONS |
| 783 | .Ft void |
| 784 | .Fn PacketAliasSetTarget "struct in_addr addr" |
| 785 | .Bd -ragged -offset indent |
| 786 | When an incoming packet not associated with any pre-existing aliasing link |
| 787 | arrives at the host machine, it will be sent to the address indicated by a |
| 788 | call to |
| 789 | .Fn PacketAliasSetTarget . |
| 790 | .Pp |
| 791 | If this function is called with an |
| 792 | .Dv INADDR_NONE |
| 793 | address argument, then all new incoming packets go to the address set by |
| 794 | .Fn PacketAliasSetAddress . |
| 795 | .Pp |
| 796 | If this function is not called, or is called with an |
| 797 | .Dv INADDR_ANY |
| 798 | address argument, then all new incoming packets go to the address specified |
| 799 | in the packet. |
| 800 | This allows external machines to talk directly to internal machines if they |
| 801 | can route packets to the machine in question. |
| 802 | .Ed |
| 803 | .Pp |
| 804 | .Ft int |
| 805 | .Fn PacketAliasCheckNewLink void |
| 806 | .Bd -ragged -offset indent |
| 807 | This function returns a non-zero value when a new aliasing link is created. |
| 808 | In circumstances where incoming traffic is being sequentially sent to |
| 809 | different local servers, this function can be used to trigger when |
| 810 | .Fn PacketAliasSetTarget |
| 811 | is called to change the default target address. |
| 812 | .Ed |
| 813 | .Pp |
| 814 | .Ft u_short |
| 815 | .Fn PacketAliasInternetChecksum "u_short *buffer" "int nbytes" |
| 816 | .Bd -ragged -offset indent |
| 817 | This is a utility function that does not seem to be available elsewhere and |
| 818 | is included as a convenience. |
| 819 | It computes the internet checksum, which is used in both IP and |
| 820 | protocol-specific headers (TCP, UDP, ICMP). |
| 821 | .Pp |
| 822 | The |
| 823 | .Fa buffer |
| 824 | argument points to the data block to be checksummed, and |
| 825 | .Fa nbytes |
| 826 | is the number of bytes. |
| 827 | The 16-bit checksum field should be zeroed before computing the checksum. |
| 828 | .Pp |
| 829 | Checksums can also be verified by operating on a block of data including |
| 830 | its checksum. |
| 831 | If the checksum is valid, |
| 832 | .Fn PacketAliasInternetChecksum |
| 833 | will return zero. |
| 834 | .Ed |
| 835 | .Pp |
| 836 | .Ft int |
| 837 | .Fn PacketUnaliasOut "char *buffer" "int maxpacketsize" |
| 838 | .Bd -ragged -offset indent |
| 839 | An outgoing packet, which has already been aliased, |
| 840 | has its private address/port information restored by this function. |
| 841 | The IP packet is pointed to by |
| 842 | .Fa buffer , |
| 843 | and |
| 844 | .Fa maxpacketsize |
| 845 | is provided for error checking purposes. |
| 846 | This function can be used if an already-aliased packet needs to have its |
| 847 | original IP header restored for further processing (eg. logging). |
| 848 | .Ed |
| 849 | .Sh AUTHORS |
| 850 | .An Charles Mott Aq cm@linktel.net , |
| 851 | versions 1.0 - 1.8, 2.0 - 2.4. |
| 852 | .An Eivind Eklund Aq eivind@FreeBSD.org , |
| 853 | versions 1.8b, 1.9 and 2.5. |
| 854 | Added IRC DCC support as well as contributing a number of architectural |
| 855 | improvements; added the firewall bypass for FTP/IRC DCC. |
| 856 | .An Erik Salander Aq erik@whistle.com |
| 857 | added support for PPTP and RTSP. |
| 858 | .An Junichi Satoh Aq junichi@junichi.org |
| 859 | added support for RTSP/PNA. |
| 860 | .Sh ACKNOWLEDGMENTS |
| 861 | Listed below, in approximate chronological order, are individuals who |
| 862 | have provided valuable comments and/or debugging assistance. |
| 863 | .Pp |
| 864 | .Bd -ragged -offset indent |
| 865 | .An -split |
| 866 | .An Gary Roberts |
| 867 | .An Tom Torrance |
| 868 | .An Reto Burkhalter |
| 869 | .An Martin Renters |
| 870 | .An Brian Somers |
| 871 | .An Paul Traina |
| 872 | .An Ari Suutari |
| 873 | .An Dave Remien |
| 874 | .An J. Fortes |
| 875 | .An Andrzej Bialecki |
| 876 | .An Gordon Burditt |
| 877 | .Ed |
| 878 | .Sh CONCEPTUAL BACKGROUND |
| 879 | This section is intended for those who are planning to modify the source |
| 880 | code or want to create somewhat esoteric applications using the packet |
| 881 | aliasing functions. |
| 882 | .Pp |
| 883 | The conceptual framework under which the packet aliasing engine operates |
| 884 | is described here. |
| 885 | Central to the discussion is the idea of an |
| 886 | .Em aliasing link |
| 887 | which describes the relationship for a given packet transaction between |
| 888 | the local machine, aliased identity and remote machine. |
| 889 | It is discussed how such links come into existence and are destroyed. |
| 890 | .Ss ALIASING LINKS |
| 891 | There is a notion of an |
| 892 | .Em aliasing link , |
| 893 | which is a 7-tuple describing a specific translation: |
| 894 | .Bd -literal -offset indent |
| 895 | (local addr, local port, alias addr, alias port, |
| 896 | remote addr, remote port, protocol) |
| 897 | .Ed |
| 898 | .Pp |
| 899 | Outgoing packets have the local address and port number replaced with the |
| 900 | alias address and port number. |
| 901 | Incoming packets undergo the reverse process. |
| 902 | The packet aliasing engine attempts to match packets against an internal |
| 903 | table of aliasing links to determine how to modify a given IP packet. |
| 904 | Both the IP header and protocol dependent headers are modified as necessary. |
| 905 | Aliasing links are created and deleted as necessary according to network |
| 906 | traffic. |
| 907 | .Pp |
| 908 | Protocols can be TCP, UDP or even ICMP in certain circumstances. |
| 909 | (Some types of ICMP packets can be aliased according to sequence or ID |
| 910 | number which acts as an equivalent port number for identifying how |
| 911 | individual packets should be handled.) |
| 912 | .Pp |
| 913 | Each aliasing link must have a unique combination of the following five |
| 914 | quantities: alias address/port, remote address/port and protocol. |
| 915 | This ensures that several machines on a local network can share the |
| 916 | same aliasing IP address. |
| 917 | In cases where conflicts might arise, the aliasing port is chosen so that |
| 918 | uniqueness is maintained. |
| 919 | .Ss STATIC AND DYNAMIC LINKS |
| 920 | Aliasing links can either be static or dynamic. |
| 921 | Static links persist indefinitely and represent fixed rules for translating |
| 922 | IP packets. |
| 923 | Dynamic links come into existence for a specific TCP connection or UDP |
| 924 | transaction or ICMP ECHO sequence. |
| 925 | For the case of TCP, the connection can be monitored to see when the |
| 926 | associated aliasing link should be deleted. |
| 927 | Aliasing links for UDP transactions (and ICMP ECHO and TIMESTAMP requests) |
| 928 | work on a simple timeout rule. |
| 929 | When no activity is observed on a dynamic link for a certain amount of time |
| 930 | it is automatically deleted. |
| 931 | Timeout rules also apply to TCP connections which do not open or close |
| 932 | properly. |
| 933 | .Ss PARTIALLY SPECIFIED ALIASING LINKS |
| 934 | Aliasing links can be partially specified, meaning that the remote address |
| 935 | and/or remote port are unknown. |
| 936 | In this case, when a packet matching the incomplete specification is found, |
| 937 | a fully specified dynamic link is created. |
| 938 | If the original partially specified link is dynamic, it will be deleted |
| 939 | after the fully specified link is created, otherwise it will persist. |
| 940 | .Pp |
| 941 | For instance, a partially specified link might be |
| 942 | .Bd -literal -offset indent |
| 943 | (192.168.0.4, 23, 204.228.203.215, 8066, 0, 0, tcp) |
| 944 | .Ed |
| 945 | .Pp |
| 946 | The zeros denote unspecified components for the remote address and port. |
| 947 | If this link were static it would have the effect of redirecting all |
| 948 | incoming traffic from port 8066 of 204.228.203.215 to port 23 (telnet) |
| 949 | of machine 192.168.0.4 on the local network. |
| 950 | Each individual telnet connection would initiate the creation of a distinct |
| 951 | dynamic link. |
| 952 | .Ss DYNAMIC LINK CREATION |
| 953 | In addition to aliasing links, there are also address mappings that can be |
| 954 | stored within the internal data table of the packet aliasing mechanism. |
| 955 | .Bd -literal -offset indent |
| 956 | (local addr, alias addr) |
| 957 | .Ed |
| 958 | .Pp |
| 959 | Address mappings are searched when creating new dynamic links. |
| 960 | .Pp |
| 961 | All outgoing packets from the local network automatically create a dynamic |
| 962 | link if they do not match an already existing fully specified link. |
| 963 | If an address mapping exists for the outgoing packet, this determines |
| 964 | the alias address to be used. |
| 965 | If no mapping exists, then a default address, usually the address of the |
| 966 | packet aliasing host, is used. |
| 967 | If necessary, this default address can be changed as often as each individual |
| 968 | packet arrives. |
| 969 | .Pp |
| 970 | The aliasing port number is determined such that the new dynamic link does |
| 971 | not conflict with any existing links. |
| 972 | In the default operating mode, the packet aliasing engine attempts to set |
| 973 | the aliasing port equal to the local port number. |
| 974 | If this results in a conflict, then port numbers are randomly chosen until |
| 975 | a unique aliasing link can be established. |
| 976 | In an alternate operating mode, the first choice of an aliasing port is also |
| 977 | random and unrelated to the local port number. |
| 978 | .Sh BUGS |
| 979 | PPTP aliasing does not work when more than one internal client |
| 980 | connects to the same external server at the same time, because |
| 981 | PPTP requires a single TCP control connection to be established |
| 982 | between any two IP addresses. |