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