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