lib/libalias/libalias.3

   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.