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
| 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 zero address argument, then all new
705incoming packets go to the address set by
706PacketAliasSetAddress.
707.Ss 6.2 PacketAliasCheckNewLink()
708
709.Ft int
710.Fn PacketAliasCheckNewLink "void"
711
712This function returns a non-zero value when
713a new aliasing link is created. In circumstances
714where incoming traffic is being sequentially
715sent to different local servers, this function
716can be used to trigger when PacketAliasSetTarget()
717is called to change the default target address.
718.Ss 6.3 PacketAliasInternetChecksum()
719
720.Ft u_short
721.Fn PacketAliasInternetChecksum "u_short *buffer" "int nbytes"
722
723This is a utility function that does not seem
724to be available elswhere and is included as a
725convenience. It computes the internet checksum,
726which is used in both IP and protocol-specific
727headers (TCP, UDP, ICMP).
728
729.Em buffer
730points to the data block to be checksummed, and
731.Em nbytes
732is the number of bytes. The 16-bit checksum
733field should be zeroed before computing the checksum.
734
735Checksums can also be verified by operating on a block
736of data including its checksum. If the checksum is
737valid, PacketAliasInternetChecksum() will return zero.
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.Sh 8. Acknowledgments
746
747Listed below, in approximate chronological
748order, are individuals who have provided
749valuable comments and/or debugging assistance.
750
751.Bl -inset -compact -offset left
752.It Gary Roberts
753.It Tom Torrance
754.It Reto Burkhalter
755.It Martin Renters
756.It Brian Somers
757.It Paul Traina
758.It Ari Suutari
759.It Dave Remien
760.It J. Fortes
761.It Andrzej Bialeki
762.It Gordon Burditt
763.El
764.Sh Appendix: Conceptual Background
765This appendix is intended for those who
766are planning to modify the source code or want
767to create somewhat esoteric applications using
768the packet aliasing functions.
769
770The conceptual framework under which the
771packet aliasing engine operates is described here.
772Central to the discussion is the idea of an
773"aliasing link" which describes the relationship
774for a given packet transaction between the local
775machine, aliased identity and remote machine. It
776is discussed how such links come into existence
777and are destroyed.
778.Ss A.1 Aliasing Links
779There is a notion of an "aliasing link",
780which is 7-tuple describing a specific
781translation:
782.Bd -literal -offset indent
783(local addr, local port, alias addr, alias port,
784 remote addr, remote port, protocol)
785.Ed
786
787Outgoing packets have the local address and
788port number replaced with the alias address
789and port number. Incoming packets undergo the
790reverse process. The packet aliasing engine
791attempts to match packets against an internal
792table of aliasing links to determine how to
793modify a given IP packet. Both the IP
794header and protocol dependent headers are
795modified as necessary. Aliasing links are
796created and deleted as necessary according
797to network traffic.
798
799Protocols can be TCP, UDP or even ICMP in
800certain circumstances. (Some types of ICMP
801packets can be aliased according to sequence
802or id number which acts as an equivalent port
803number for identifying how individual packets
804should be handled.)
805
806Each aliasing link must have a unique
807combination of the following five quantities:
808alias address/port, remote address/port
809and protocol. This ensures that several
810machines on a local network can share the
811same aliased IP address. In cases where
812conflicts might arise, the aliasing port
813is chosen so that uniqueness is maintained.
814.Ss A.2 Static and Dynamic Links
815Aliasing links can either be static or dynamic.
816Static links persist indefinitely and represent
817fixed rules for translating IP packets. Dynamic
818links come into existence for a specific TCP
819connection or UDP transaction or ICMP echo
820sequence. For the case of TCP, the connection
821can be monitored to see when the associated
822aliasing link should be deleted. Aliasing links
823for UDP transactions (and ICMP echo and timestamp
824requests) work on a simple timeout rule. When
825no activity is observed on a dynamic link for
826a certain amount of time it is automatically
827deleted. Timeout rules also apply to TCP
828connections which do not open or close
829properly.
830.Ss A.3 Partially Specified Aliasing Links
831Aliasing links can be partially specified,
832meaning that the remote address and/or remote
833ports are unknown. In this case, when a packet
834matching the incomplete specification is found,
835a fully specified dynamic link is created. If
836the original partially specified link is dynamic,
837it will be deleted after the fully specified link
838is created, otherwise it will persist.
839
840For instance, a partially specified link might
841be
842.Bd -literal -offset indent
843(192.168.0.4, 23, 204.228.203.215, 8066, 0, 0, tcp)
844.Ed
845
846The zeros denote unspecified components for
847the remote address and port. If this link were
848static it would have the effect of redirecting
849all incoming traffic from port 8066 of
850204.228.203.215 to port 23 (telnet) of machine
851192.168.0.4 on the local network. Each
852individual telnet connection would initiate
853the creation of a distinct dynamic link.
854.Ss A.4 Dynamic Link Creation
855In addition to aliasing links, there are
856also address mappings that can be stored
857within the internal data table of the packet
858aliasing mechanism.
859.Bd -literal -offset indent
860(local addr, alias addr)
861.Ed
862
863Address mappings are searched when creating
864new dynamic links.
865
866All outgoing packets from the local network
867automatically create a dynamic link if
868they do not match an already existing fully
869specified link. If an address mapping exists
870for the outgoing packet, this determines
871the alias address to be used. If no mapping
872exists, then a default address, usually the
873address of the packet aliasing host, is used.
874If necessary, this default address can be
875changed as often as each individual packet
876arrives.
877
878The aliasing port number is determined
879such that the new dynamic link does not
880conflict with any existing links. In the
881default operating mode, the packet aliasing
882engine attempts to set the aliasing port
883equal to the local port number. If this
884results in a conflict, then port numbers
885are randomly chosen until a unique aliasing
886link can be established. In an alternate
887operating mode, the first choice of an
888aliasing port is also random and unrelated
889to the local port number.
890
|