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