libalias.3 revision 46395
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 make 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 263.El 264 265.Ss 2.5 PacketAliasSetFWBase() 266 267.Ft void 268.Fn PacketAliasSetFWBase "unsigned int base" "unsigned int num" 269 270Set IPFW range allocated for punching firewall holes (with the 271PKT_ALIAS_PUNCH_FW flag). The range will be cleared for all rules on 272initialization. 273 274.Sh 3. Packet Handling 275The packet handling functions are used to 276modify incoming (remote->local) and outgoing 277(local->remote) packets. The calling program 278is responsible for receiving and sending 279packets via network interfaces. 280 281Along with PacketAliasInit() and PacketAliasSetAddress(), 282the two packet handling functions, PacketAliasIn() 283and PacketAliasOut(), comprise minimal set of functions 284needed for a basic IP masquerading implementation. 285.Ss 3.1 PacketAliasIn() 286 287.Ft int 288.Fn PacketAliasIn "char *buffer" "int maxpacketsize" 289 290An incoming packet coming from a remote machine to 291the local network is de-aliased by this function. 292The IP packet is pointed to by 293.Em buffer , 294and 295.Em maxpacketsize 296indicates the size of the data structure containing 297the packet and should be at least as large as the 298actual packet size. 299 300Return codes: 301.Bl -hang -offset left 302.It PKT_ALIAS_ERROR. 303An internal error within the packet aliasing 304engine occurred. 305.It PKT_ALIAS_OK. 306The packet aliasing process was successful. 307.It PKT_ALIAS_IGNORED. 308The packet was ignored and not de-aliased. 309This can happen if the protocal is unrecognized, 310possibly an ICMP message type is not handled or 311if incoming packets for new connections are being 312ignored (see PKT_ALIAS_DENY_INCOMING in section 3132.2). 314.It PKT_ALIAS_UNRESOLVED_FRAGMENT. 315This is returned when a fragment cannot be 316resolved because the header fragment has not 317been sent yet. In this situation, fragments 318must be saved with PacketAliasSaveFragment() 319until a header fragment is found. 320.It PKT_ALIAS_FOUND_HEADER_FRAGMENT. 321The packet aliasing process was successful, 322and a header fragment was found. This is a 323signal to retrieve any unresolved fragments 324with PacketAliasGetFragment() and de-alias 325them with PacketAliasFragmentIn(). 326.El 327.Ss 3.2 PacketAliasOut() 328 329.Ft int 330.Fn PacketAliasOut "char *buffer" "int maxpacketsize" 331 332An outgoing packet coming from the local network 333to a remote machine is aliased by this function. 334The IP packet is pointed to by 335.Em buffer r, 336and 337.Em maxpacketsize 338indicates the maximum packet size permissible 339should the packet length be changed. IP encoding 340protocols place address and port information in 341the encapsulated data stream which have to be 342modified and can account for changes in packet 343length. Well known examples of such protocols 344are FTP and IRC DCC. 345 346Return codes: 347.Bl -hang -offset left 348.It PKT_ALIAS_ERROR. 349An internal error within the packet aliasing 350engine occurred. 351.It PKT_ALIAS_OK. 352The packet aliasing process was successful. 353.It PKT_ALIAS_IGNORED. 354The packet was ignored and not de-aliased. 355This can happen if the protocal is unrecognized, 356or possibly an ICMP message type is not handled. 357.El 358 359.Sh 4. Port and Address Redirection 360The functions described in this section allow machines 361on the local network to be accessible in some degree 362to new incoming connections from the external network. 363Individual ports can be re-mapped or static network 364address translations can be designated. 365.Ss 4.1 PacketAliasRedirectPort() 366 367.Ft struct alias_link * 368.Fo PacketAliasRedirectPort 369.Fa "struct in_addr local_addr" 370.Fa "u_short local_port" 371.Fa "struct in_addr remote_addr" 372.Fa "u_short remote_port" 373.Fa "struct in_addr alias_addr" 374.Fa "u_short alias_port" 375.Fa "u_char proto" 376.Fc 377 378This function specifies that traffic from a 379given remote address/port to an alias address/port 380be redirected to a specified local address/port. 381The parameter 382.Em proto 383can be either IPPROTO_TCP or IPPROTO_UDP, as 384defined in <netinet/in.h>. 385 386If 387.Em local_addr 388or 389.Em alias_addr 390is zero, this indicates that the packet aliasing 391address as established by PacketAliasSetAddress() 392is to be used. Even if PacketAliasAddress() is 393called to change the address after PacketAliasRedirectPort() 394is called, a zero reference will track this change. 395 396If 397.Em remote_addr 398is zero, this indicates to redirect packets from 399any remote address. Likewise, if 400.Em remote_port 401is zero, this indicates to redirect packets originating 402from any remote port number. Almost always, the remote 403port specification will be zero, but non-zero remote 404addresses can be sometimes be useful for firewalling. 405If two calls to PacketAliasRedirectPort() overlap in 406their address/port specifications, then the most recent 407call will have precedence. 408 409This function returns a pointer which can subsequently 410be used by PacketAliasRedirectDelete(). If NULL is 411returned, then the function call did not complete 412successfully. 413 414All port numbers are in network address byte order, 415so it is necessary to use htons() to convert these 416parameters from internally readable numbers to 417network byte order. Addresses are also in network 418byte order, which is implicit in the use of the 419.Em struct in_addr 420data type. 421.Ss 4.2 PacketAliasRedirectAddr() 422 423.Ft struct alias_link * 424.Fo PacketAliasRedirectAddr 425.Fa "struct in_addr local_addr" 426.Fa "struct in_addr alias_addr" 427.Fc 428 429This function desgnates that all incoming 430traffic to 431.Em alias_addr 432be redirected to 433.Em local_addr. 434Similarly, all outgoing traffic from 435.Em local_addr 436is aliased to 437.Em alias_addr . 438 439If 440.Em local_addr 441or 442.Em alias_addr 443is zero, this indicates that the packet aliasing 444address as established by PacketAliasSetAddress() 445is to be used. Even if PacketAliasAddress() is 446called to change the address after PacketAliasRedirectAddr() 447is called, a zero reference will track this change. 448 449If subsequent calls to PacketAliasRedirectAddr() 450use the same aliasing address, all new incoming 451traffic to this aliasing address will be redirected 452to the local address made in the last function call, 453but new traffic all of the local machines designated 454in the several function calls will be aliased to 455the same address. Consider the following example: 456.Bd -literal -offset left 457 PacketAliasRedirectAddr(inet_aton("192.168.0.2"), 458 inet_aton("141.221.254.101")); 459 PacketAliasRedirectAddr(inet_aton("192.168.0.3"), 460 inet_aton("141.221.254.101")); 461 PacketAliasRedirectAddr(inet_aton("192.168.0.4"), 462 inet_aton("141.221.254.101")); 463.Ed 464 465Any outgoing connections such as telnet or ftp 466from 192.168.0.2, 102.168.0.3, 192.168.0.4 will 467appear to come from 141.221.254.101. Any incoming 468connections to 141.221.254.101 will be directed 469to 192.168.0.4. 470 471Any calls to PacketAliasRedirectPort() will 472have precedence over address mappings designated 473by PacketAliasRedirectAddr(). 474 475This function returns a pointer which can subsequently 476be used by PacketAliasRedirectDelete(). If NULL is 477returned, then the function call did not complete 478successfully. 479.Ss 4.3 PacketAliasRedirectDelete() 480 481.Ft void 482.Fn PacketAliasRedirectDelete "struct alias_link *ptr" 483 484This function will delete a specific static redirect 485rule entered by PacketAliasRedirectPort() or 486PacketAliasRedirectAddr(). The parameter 487.Em ptr 488is the pointer returned by either of the redirection 489functions. If an invalid pointer is passed to 490PacketAliasRedirectDelete(), then a program crash 491or unpredictable operation could result, so it is 492necessary to be careful using this function. 493 494.Sh 5. Fragment Handling 495The functions in this section are used to deal with 496incoming fragments. 497 498Outgoing fragments are handled within PacketAliasOut() 499by changing the address according to any 500applicable mapping set by PacketAliasRedirectAddress(), 501or the default aliasing address set by 502PacketAliasSetAddress(). 503 504Incoming fragments are handled in one of two ways. 505If the header of a fragmented IP packet has already 506been seen, then all subsequent fragments will be 507re-mapped in the same manner the header fragment 508was. Fragments which arrive before the header 509are saved and then retrieved once the header fragment 510has been resolved. 511 512.Ss 4.4 PacketAliasProxyRule() 513 514.Ft int 515.Fn PacketAliasProxyRule "const char *cmd" 516 517The passed 518.Ar cmd 519string consists of one or more pairs of words. The first word in each 520pair is a token and the second is the value that should be applied for 521that token. Tokens and their argument types are as follows: 522 523.Bl -tag -offset XXX -width XXX 524.It type encode_ip_hdr|encode_tcp_stream|no_encode 525In order to support transparent proxying, it is necessary to somehow 526pass the original address and port information into the new destination 527server. If 528.Dq encode_ip_hdr 529is specified, the original address and port is passed as an extra IP 530option. If 531.Dq encode_tcp_stream 532is specified, the original address and port is passed as the first 533piece of data in the tcp stream in the format 534.Dq DEST Ar IP port . 535.It port Ar portnum 536Only packets with the destination port 537.Ar portnum 538are proxied. 539.It server Ar host[:portnum] 540This specifies the 541.Ar host 542and 543.Ar portnum 544that the data is to be redirected to. 545.Ar host 546must be an IP address rather than a DNS host name. If 547.Ar portnum 548is not specified, the destination port number is not changed. 549.Pp 550The 551.Ar server 552specification is mandatory unless the 553.Dq delete 554command is being used. 555.It rule Ar index 556Normally, each call to 557.Fn PacketAliasProxyRule 558inserts the next rule at the start of a linear list of rules. If an 559.Ar index 560is specified, the new rule will be checked after all rules with lower 561indices. Calls to 562.Fn PacketAliasProxyRule 563that do not specify a rule are assigned rule 0. 564.It delete Ar index 565This token and its argument must not be used with any other tokens. When 566used, all existing rules with the given 567.Ar index 568are deleted. 569.It proto tcp|udp 570If specified, only packets of the given protocol type are matched. 571.It src Ar IP[/bits] 572If specified, only packets with a source address matching the given 573.Ar IP 574are matched. If 575.Ar bits 576is also specified, then the first 577.Ar bits 578bits of 579.Ar IP 580are taken as a network specification, and all IP addresses from that 581network will be matched. 582.It dest Ar IP[/bits] 583If specified, only packets with a destination address matching the given 584.Ar IP 585are matched. If 586.Ar bits 587is also specified, then the first 588.Ar bits 589bits of 590.Ar IP 591are taken as a network specification, and all IP addresses from that 592network will be matched. 593.El 594 595This function is usually used to redirect outgoing connections for 596internal machines that are not permitted certain types of internet 597access, or to restrict access to certain external machines. 598 599.Ss 4.5 PacketAliasPptp() 600 601.Ft extern int 602.Fn PacketAliasPptp "struct in_addr addr" 603 604This function causes any 605.Em G Ns No eneral 606.Em R Ns No outing 607.Em E Ns No encapsulated 608.Pq Dv IPPROTO_GRE 609packets to be aliased using 610.Ar addr 611rather than the address set via 612.Fn PacketAliasSetAddress . 613This allows the uses of the 614.Em P Ns No oint 615to 616.Em P Ns No oint 617.Em T Ns No unneling 618.Em P Ns No rotocol 619on a machine on the internal network. 620.Pp 621If the passed address is 622.Dv INADDR_NONE 623.Pq 255.255.255.255 , 624.Dv PPTP 625aliasing is disabled. 626 627.Ss 5.1 PacketAliasSaveFragment() 628 629.Ft int 630.Fn PacketAliasSaveFragment "char *ptr" 631 632When PacketAliasIn() returns 633PKT_ALIAS_UNRESOLVED_FRAGMENT, this 634function can be used to save the pointer to 635the unresolved fragment. 636 637It is implicitly assumed that 638.Em ptr 639points to a block of memory allocated by 640malloc(). If the fragment is never 641resolved, the packet aliasing engine will 642automatically free the memory after a 643timeout period. [Eventually this function 644should be modified so that a callback 645function for freeing memory is passed as 646an argument.] 647 648This function returns PKT_ALIAS_OK if it 649was successful and PKT_ALIAS_ERROR if there 650was an error. 651 652.Ss 5.2 PacketAliasGetFragment() 653 654.Ft char * 655.Fn PacketAliasGetFragment "char *buffer" 656 657This function can be used to retrieve fragment 658pointers saved by PacketAliasSaveFragment(). 659The IP header fragment pointed to by 660.Em buffer 661is the header fragment indicated when 662PacketAliasIn() returns PKT_ALIAS_FOUND_HEADER_FRAGMENT. 663Once a a fragment pointer is retrieved, it 664becomes the calling program's responsibility 665to free the dynamically allocated memory for 666the fragment. 667 668PacketAliasGetFragment() can be called 669sequentially until there are no more fragments 670available, at which time it returns NULL. 671.Ss 5.3 PacketAliasFragmentIn() 672 673.Ft void 674.Fn PacketAliasFragmentIn "char *header" "char *fragment" 675 676When a fragment is retrieved with 677PacketAliasGetFragment(), it can then be 678de-aliased with a call to PacketAliasFragmentIn(). 679.Em header 680is the pointer to a header fragment used as a 681template, and 682.Em fragment 683is the pointer to the packet to be de-aliased. 684 685.Sh 6. Miscellaneous Functions 686 687.Ss 6.1 PacketAliasSetTarget() 688 689.Ft void 690.Fn PacketAliasSetTarget "struct in_addr addr" 691 692When an incoming packet not associated with 693any pre-existing aliasing link arrives at the 694host machine, it will be sent to the address 695indicated by a call to PacketAliasSetTarget(). 696 697If this function is not called, or is called 698with a zero address argument, then all new 699incoming packets go to the address set by 700PacketAliasSetAddress. 701.Ss 6.2 PacketAliasCheckNewLink() 702 703.Ft int 704.Fn PacketAliasCheckNewLink "void" 705 706This function returns a non-zero value when 707a new aliasing link is created. In circumstances 708where incoming traffic is being sequentially 709sent to different local servers, this function 710can be used to trigger when PacketAliasSetTarget() 711is called to change the default target address. 712.Ss 6.3 PacketAliasInternetChecksum() 713 714.Ft u_short 715.Fn PacketAliasInternetChecksum "u_short *buffer" "int nbytes" 716 717This is a utility function that does not seem 718to be available elswhere and is included as a 719convenience. It computes the internet checksum, 720which is used in both IP and protocol-specific 721headers (TCP, UDP, ICMP). 722 723.Em buffer 724points to the data block to be checksummed, and 725.Em nbytes 726is the number of bytes. The 16-bit checksum 727field should be zeroed before computing the checksum. 728 729Checksums can also be verified by operating on a block 730of data including its checksum. If the checksum is 731valid, PacketAliasInternetChecksum() will return zero. 732 733.Sh 7. Authors 734Charles Mott (cmott@srv.net), versions 1.0 - 1.8, 2.0 - 2.4. 735 736Eivind Eklund (eivind@freebsd.org), versions 1.8b, 1.9 and 7372.5. Added IRC DCC support as well as contributing a number of 738architectural improvements; added the firewall bypass 739for FTP/IRC DCC. 740 741.Sh 8. Acknowledgments 742 743Listed below, in approximate chronological 744order, are individuals who have provided 745valuable comments and/or debugging assistance. 746 747.Bl -inset -compact -offset left 748.It Gary Roberts 749.It Tom Torrance 750.It Reto Burkhalter 751.It Martin Renters 752.It Brian Somers 753.It Paul Traina 754.It Ari Suutari 755.It Dave Remien 756.It J. Fortes 757.It Andrzej Bialeki 758.It Gordon Burditt 759.El 760 761.Sh Appendix: Conceptual Background 762This appendix is intended for those who 763are planning to modify the source code or want 764to create somewhat esoteric applications using 765the packet aliasing functions. 766 767The conceptual framework under which the 768packet aliasing engine operates is described here. 769Central to the discussion is the idea of an 770"aliasing link" which describes the relationship 771for a given packet transaction between the local 772machine, aliased identity and remote machine. It 773is discussed how such links come into existence 774and are destroyed. 775.Ss A.1 Aliasing Links 776There is a notion of an "aliasing link", 777which is 7-tuple describing a specific 778translation: 779.Bd -literal -offset indent 780(local addr, local port, alias addr, alias port, 781 remote addr, remote port, protocol) 782.Ed 783 784Outgoing packets have the local address and 785port number replaced with the alias address 786and port number. Incoming packets undergo the 787reverse process. The packet aliasing engine 788attempts to match packets against an internal 789table of aliasing links to determine how to 790modify a given IP packet. Both the IP 791header and protocol dependent headers are 792modified as necessary. Aliasing links are 793created and deleted as necessary according 794to network traffic. 795 796Protocols can be TCP, UDP or even ICMP in 797certain circumstances. (Some types of ICMP 798packets can be aliased according to sequence 799or id number which acts as an equivalent port 800number for identifying how individual packets 801should be handled.) 802 803Each aliasing link must have a unique 804combination of the following five quantities: 805alias address/port, remote address/port 806and protocol. This ensures that several 807machines on a local network can share the 808same aliased IP address. In cases where 809conflicts might arise, the aliasing port 810is chosen so that uniqueness is maintained. 811.Ss A.2 Static and Dynamic Links 812Aliasing links can either be static or dynamic. 813Static links persist indefinitely and represent 814fixed rules for translating IP packets. Dynamic 815links come into existence for a specific TCP 816connection or UDP transaction or ICMP echo 817sequence. For the case of TCP, the connection 818can be monitored to see when the associated 819aliasing link should be deleted. Aliasing links 820for UDP transactions (and ICMP echo and timestamp 821requests) work on a simple timeout rule. When 822no activity is observed on a dynamic link for 823a certain amount of time it is automatically 824deleted. Timeout rules also apply to TCP 825connections which do not open or close 826properly. 827.Ss A.3 Partially Specified Aliasing Links 828Aliasing links can be partially specified, 829meaning that the remote address and/or remote 830ports are unknown. In this case, when a packet 831matching the incomplete specification is found, 832a fully specified dynamic link is created. If 833the original partially specified link is dynamic, 834it will be deleted after the fully specified link 835is created, otherwise it will persist. 836 837For instance, a partially specified link might 838be 839.Bd -literal -offset indent 840(192.168.0.4, 23, 204.228.203.215, 8066, 0, 0, tcp) 841.Ed 842 843The zeros denote unspecified components for 844the remote address and port. If this link were 845static it would have the effect of redirecting 846all incoming traffic from port 8066 of 847204.228.203.215 to port 23 (telnet) of machine 848192.168.0.4 on the local network. Each 849individual telnet connection would initiate 850the creation of a distinct dynamic link. 851.Ss A.4 Dynamic Link Creation 852In addition to aliasing links, there are 853also address mappings that can be stored 854within the internal data table of the packet 855aliasing mechanism. 856.Bd -literal -offset indent 857(local addr, alias addr) 858.Ed 859 860Address mappings are searched when creating 861new dynamic links. 862 863All outgoing packets from the local network 864automatically create a dynamic link if 865they do not match an already existing fully 866specified link. If an address mapping exists 867for the the outgoing packet, this determines 868the alias address to be used. If no mapping 869exists, then a default address, usually the 870address of the packet aliasing host, is used. 871If necessary, this default address can be 872changed as often as each individual packet 873arrives. 874 875The aliasing port number is determined 876such that the new dynamic link does not 877conflict with any existing links. In the 878default operating mode, the packet aliasing 879engine attempts to set the aliasing port 880equal to the local port number. If this 881results in a conflict, then port numbers 882are randomly chosen until a unique aliasing 883link can be established. In an alternate 884operating mode, the first choice of an 885aliasing port is also random and unrelated 886to the local port number. 887 888