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