sys/netinet/libalias/libalias.3

   1 .\"-
   2 .\" Copyright (c) 2001 Charles Mott <cm@linktel.net>
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd July 4, 2011
  29 .Dt LIBALIAS 3
  30 .Os
  31 .Sh NAME
  32 .Nm libalias
  33 .Nd packet aliasing library for masquerading and network address translation
  34 .Sh SYNOPSIS
  35 .In sys/types.h
  36 .In netinet/in.h
  37 .In alias.h
  38 .Pp
  39 Function prototypes are given in the main body of the text.
  40 .Sh DESCRIPTION
  41 The
  42 .Nm
  43 library is a collection of functions for aliasing and de-aliasing of IP
  44 packets, intended for masquerading and network address translation (NAT).
  45 .Sh INTRODUCTION
  46 This library is a moderately portable set of functions designed to assist
  47 in the process of IP masquerading and network address translation.
  48 Outgoing packets from a local network with unregistered IP addresses can
  49 be aliased to appear as if they came from an accessible IP address.
  50 Incoming packets are then de-aliased so that they are sent to the correct
  51 machine on the local network.
  52 .Pp
  53 A certain amount of flexibility is built into the packet aliasing engine.
  54 In the simplest mode of operation, a many-to-one address mapping takes
  55 place between the local network and the packet aliasing host.
  56 This is known as IP masquerading.
  57 In addition, one-to-one mappings between local and public addresses can
  58 also be implemented, which is known as static NAT.
  59 In between these extremes, different groups of private addresses can be
  60 linked to different public addresses, comprising several distinct
  61 many-to-one mappings.
  62 Also, a given public address and port can be statically redirected to a
  63 private address/port.
  64 .Sh INITIALIZATION AND CONTROL
  65 One special function,
  66 .Fn LibAliasInit ,
  67 must always be called before any packet handling may be performed, and
  68 the returned instance pointer must be passed to all the other functions.
  69 Normally, the
  70 .Fn LibAliasSetAddress
  71 function is called afterwards, to set the default aliasing address.
  72 In addition, the operating mode of the packet aliasing engine can be
  73 customized by calling
  74 .Fn LibAliasSetMode .
  75 .Pp
  76 .Ft "struct libalias *"
  77 .Fn LibAliasInit "struct libalias *"
  78 .Bd -ragged -offset indent
  79 This function is used to initialize
  80 internal data structures.
  81 When called the first time, a
  82 .Dv NULL
  83 pointer should be passed as an argument.
  84 The following mode bits are always set after calling
  85 .Fn LibAliasInit .
  86 See the description of
  87 .Fn LibAliasSetMode
  88 below for the meaning of these mode bits.
  89 .Pp
  90 .Bl -item -offset indent -compact
  91 .It
  92 .Dv PKT_ALIAS_SAME_PORTS
  93 .It
  94 .Dv PKT_ALIAS_USE_SOCKETS
  95 .It
  96 .Dv PKT_ALIAS_RESET_ON_ADDR_CHANGE
  97 .El
  98 .Pp
  99 This function will always return the packet aliasing engine to the same
 100 initial state.
 101 The
 102 .Fn LibAliasSetAddress
 103 function is normally called afterwards, and any desired changes from the
 104 default mode bits listed above require a call to
 105 .Fn LibAliasSetMode .
 106 .Pp
 107 It is mandatory that this function be called at the beginning of a program
 108 prior to any packet handling.
 109 .Ed
 110 .Pp
 111 .Ft void
 112 .Fn LibAliasUninit "struct libalias *"
 113 .Bd -ragged -offset indent
 114 This function has no return value and is used to clear any
 115 resources attached to internal data structures.
 116 .Pp
 117 This function should be called when a program stops using the aliasing
 118 engine; amongst other things, it clears out any firewall holes.
 119 To provide backwards compatibility and extra security, it is added to
 120 the
 121 .Xr atexit 3
 122 chain by
 123 .Fn LibAliasInit .
 124 .Ed
 125 .Pp
 126 .Ft void
 127 .Fn LibAliasSetAddress "struct libalias *" "struct in_addr addr"
 128 .Bd -ragged -offset indent
 129 This function sets the source address to which outgoing packets from the
 130 local area network are aliased.
 131 All outgoing packets are re-mapped to this address unless overridden by a
 132 static address mapping established by
 133 .Fn LibAliasRedirectAddr .
 134 If this function has not been called, and no static rules match, an outgoing
 135 packet retains its source address.
 136 .Pp
 137 If the
 138 .Dv PKT_ALIAS_RESET_ON_ADDR_CHANGE
 139 mode bit is set (the default mode of operation), then the internal aliasing
 140 link tables will be reset any time the aliasing address changes.
 141 This is useful for interfaces such as
 142 .Xr ppp 8 ,
 143 where the IP
 144 address may or may not change on successive dial-up attempts.
 145 .Pp
 146 If the
 147 .Dv PKT_ALIAS_RESET_ON_ADDR_CHANGE
 148 mode bit is set to zero, this function can also be used to dynamically change
 149 the aliasing address on a packet-to-packet basis (it is a low overhead call).
 150 .Pp
 151 It is mandatory that this function be called prior to any packet handling.
 152 .Ed
 153 .Pp
 154 .Ft unsigned int
 155 .Fn LibAliasSetMode "struct libalias *" "unsigned int flags" "unsigned int mask"
 156 .Bd -ragged -offset indent
 157 This function sets or clears mode bits
 158 according to the value of
 159 .Fa flags .
 160 Only bits marked in
 161 .Fa mask
 162 are affected.
 163 The following mode bits are defined in
 164 .In alias.h :
 165 .Bl -tag -width indent
 166 .It Dv PKT_ALIAS_LOG
 167 Enables logging into
 168 .Pa /var/log/alias.log .
 169 Each time an aliasing link is created or deleted, the log file is appended to
 170 with the current number of ICMP, TCP and UDP links.
 171 Mainly useful for debugging when the log file is viewed continuously with
 172 .Xr tail 1 .
 173 .It Dv PKT_ALIAS_DENY_INCOMING
 174 If this mode bit is set, all incoming packets associated with new TCP
 175 connections or new UDP transactions will be marked for being ignored
 176 .Fn ( LibAliasIn
 177 returns
 178 .Dv PKT_ALIAS_IGNORED
 179 code)
 180 by the calling program.
 181 Response packets to connections or transactions initiated from the packet
 182 aliasing host or local network will be unaffected.
 183 This mode bit is useful for implementing a one-way firewall.
 184 .It Dv PKT_ALIAS_SAME_PORTS
 185 If this mode bit is set, the packet-aliasing engine will attempt to leave
 186 the alias port numbers unchanged from the actual local port numbers.
 187 This can be done as long as the quintuple (proto, alias addr, alias port,
 188 remote addr, remote port) is unique.
 189 If a conflict exists, a new aliasing port number is chosen even if this
 190 mode bit is set.
 191 .It Dv PKT_ALIAS_USE_SOCKETS
 192 This bit should be set when the packet aliasing host originates network
 193 traffic as well as forwards it.
 194 When the packet aliasing host is waiting for a connection from an unknown
 195 host address or unknown port number (e.g.\& an FTP data connection), this
 196 mode bit specifies that a socket be allocated as a place holder to prevent
 197 port conflicts.
 198 Once a connection is established, usually within a minute or so, the socket
 199 is closed.
 200 .It Dv PKT_ALIAS_UNREGISTERED_ONLY
 201 If this mode bit is set, traffic on the local network which does not
 202 originate from unregistered address spaces will be ignored.
 203 Standard Class A, B and C unregistered addresses are:
 204 .Bd -literal -offset indent
 205 10.0.0.0     ->  10.255.255.255   (Class A subnet)
 206 172.16.0.0   ->  172.31.255.255   (Class B subnets)
 207 192.168.0.0  ->  192.168.255.255  (Class C subnets)
 208 .Ed
 209 .Pp
 210 This option is useful in the case that the packet aliasing host has both
 211 registered and unregistered subnets on different interfaces.
 212 The registered subnet is fully accessible to the outside world, so traffic
 213 from it does not need to be passed through the packet aliasing engine.
 214 .It Dv PKT_ALIAS_RESET_ON_ADDR_CHANGE
 215 When this mode bit is set and
 216 .Fn LibAliasSetAddress
 217 is called to change the aliasing address, the internal link table of the
 218 packet aliasing engine will be cleared.
 219 This operating mode is useful for
 220 .Xr ppp 8
 221 links where the interface address can sometimes change or remain the same
 222 between dial-up attempts.
 223 If this mode bit is not set, the link table will never be reset in the event
 224 of an address change.
 225 .It Dv PKT_ALIAS_PUNCH_FW
 226 This option makes
 227 .Nm
 228 .Dq punch holes
 229 in an
 230 .Xr ipfirewall 4 -
 231 based firewall for FTP/IRC DCC connections.
 232 The holes punched are bound by from/to IP address and port; it will not be
 233 possible to use a hole for another connection.
 234 A hole is removed when the connection that uses it dies.
 235 To cater to unexpected death of a program using
 236 .Nm
 237 (e.g.\& kill -9),
 238 changing the state of the flag will clear the entire firewall range
 239 allocated for holes.
 240 This clearing will also happen on the initial call to
 241 .Fn LibAliasSetFWBase ,
 242 which must happen prior to setting this flag.
 243 .It Dv PKT_ALIAS_REVERSE
 244 This option makes
 245 .Nm
 246 reverse the way it handles incoming and outgoing packets, allowing it
 247 to be fed with data that passes through the internal interface rather
 248 than the external one.
 249 .It Dv PKT_ALIAS_PROXY_ONLY
 250 This option tells
 251 .Nm
 252 to obey transparent proxy rules only.
 253 Normal packet aliasing is not performed.
 254 See
 255 .Fn LibAliasProxyRule
 256 below for details.
 257 .It Dv PKT_ALIAS_SKIP_GLOBAL
 258 This option is used by
 259 .Pa ipfw_nat
 260 only.
 261 Specifying it as a flag to
 262 .Fn LibAliasSetMode
 263 has no effect.
 264 See section
 265 .Sx NETWORK ADDRESS TRANSLATION
 266 in
 267 .Xr ipfw 8
 268 for more details.
 269 .El
 270 .Ed
 271 .Pp
 272 .Ft void
 273 .Fn LibAliasSetFWBase "struct libalias *" "unsigned int base" "unsigned int num"
 274 .Bd -ragged -offset indent
 275 Set the firewall range allocated for punching firewall holes (with the
 276 .Dv PKT_ALIAS_PUNCH_FW
 277 flag).
 278 The range is cleared for all rules on initialization.
 279 .Ed
 280 .Pp
 281 .Ft void
 282 .Fn LibAliasSkinnyPort "struct libalias *" "unsigned int port"
 283 .Bd -ragged -offset indent
 284 Set the TCP port used by the Skinny Station protocol.
 285 Skinny is used by Cisco IP phones to communicate with
 286 Cisco Call Managers to set up voice over IP calls.
 287 If this is not set, Skinny aliasing will not be done.
 288 The typical port used by Skinny is 2000.
 289 .Ed
 290 .Sh PACKET HANDLING
 291 The packet handling functions are used to modify incoming (remote to local)
 292 and outgoing (local to remote) packets.
 293 The calling program is responsible for receiving and sending packets via
 294 network interfaces.
 295 .Pp
 296 Along with
 297 .Fn LibAliasInit
 298 and
 299 .Fn LibAliasSetAddress ,
 300 the two packet handling functions,
 301 .Fn LibAliasIn
 302 and
 303 .Fn LibAliasOut ,
 304 comprise the minimal set of functions needed for a basic IP masquerading
 305 implementation.
 306 .Pp
 307 .Ft int
 308 .Fn LibAliasIn "struct libalias *" "char *buffer" "int maxpacketsize"
 309 .Bd -ragged -offset indent
 310 An incoming packet coming from a remote machine to the local network is
 311 de-aliased by this function.
 312 The IP packet is pointed to by
 313 .Fa buffer ,
 314 and
 315 .Fa maxpacketsize
 316 indicates the size of the data structure containing the packet and should
 317 be at least as large as the actual packet size.
 318 .Pp
 319 Return codes:
 320 .Bl -tag -width indent
 321 .It Dv PKT_ALIAS_OK
 322 The packet aliasing process was successful.
 323 .It Dv PKT_ALIAS_IGNORED
 324 The packet was ignored and not de-aliased.
 325 This can happen if the protocol is unrecognized, as for an ICMP message
 326 type that is not handled, or if incoming packets for new connections are being
 327 ignored (if the
 328 .Dv PKT_ALIAS_DENY_INCOMING
 329 mode bit was set using
 330 .Fn LibAliasSetMode ) .
 331 .It Dv PKT_ALIAS_UNRESOLVED_FRAGMENT
 332 This is returned when a fragment cannot be resolved because the header
 333 fragment has not been sent yet.
 334 In this situation, fragments must be saved with
 335 .Fn LibAliasSaveFragment
 336 until a header fragment is found.
 337 .It Dv PKT_ALIAS_FOUND_HEADER_FRAGMENT
 338 The packet aliasing process was successful, and a header fragment was found.
 339 This is a signal to retrieve any unresolved fragments with
 340 .Fn LibAliasGetFragment
 341 and de-alias them with
 342 .Fn LibAliasFragmentIn .
 343 .It Dv PKT_ALIAS_ERROR
 344 An internal error within the packet aliasing engine occurred.
 345 .El
 346 .Ed
 347 .Pp
 348 .Ft int
 349 .Fn LibAliasOut "struct libalias *" "char *buffer" "int maxpacketsize"
 350 .Bd -ragged -offset indent
 351 An outgoing packet coming from the local network to a remote machine is
 352 aliased by this function.
 353 The IP packet is pointed to by
 354 .Fa buffer ,
 355 and
 356 .Fa maxpacketsize
 357 indicates the maximum packet size permissible should the packet length be
 358 changed.
 359 IP encoding protocols place address and port information in the encapsulated
 360 data stream which has to be modified and can account for changes in packet
 361 length.
 362 Well known examples of such protocols are FTP and IRC DCC.
 363 .Pp
 364 Return codes:
 365 .Bl -tag -width indent
 366 .It Dv PKT_ALIAS_OK
 367 The packet aliasing process was successful.
 368 .It Dv PKT_ALIAS_IGNORED
 369 The packet was ignored and not aliased.
 370 This can happen if the protocol is unrecognized, or possibly an ICMP message
 371 type is not handled.
 372 .It Dv PKT_ALIAS_ERROR
 373 An internal error within the packet aliasing engine occurred.
 374 .El
 375 .Ed
 376 .Sh PORT AND ADDRESS REDIRECTION
 377 The functions described in this section allow machines on the local network
 378 to be accessible in some degree to new incoming connections from the external
 379 network.
 380 Individual ports can be re-mapped or static network address translations can
 381 be designated.
 382 .Pp
 383 .Ft struct alias_link *
 384 .Fo LibAliasRedirectPort
 385 .Fa "struct libalias *"
 386 .Fa "struct in_addr local_addr"
 387 .Fa "u_short local_port"
 388 .Fa "struct in_addr remote_addr"
 389 .Fa "u_short remote_port"
 390 .Fa "struct in_addr alias_addr"
 391 .Fa "u_short alias_port"
 392 .Fa "u_char proto"
 393 .Fc
 394 .Bd -ragged -offset indent
 395 This function specifies that traffic from a given remote address/port to
 396 an alias address/port be redirected to a specified local address/port.
 397 The parameter
 398 .Fa proto
 399 can be either
 400 .Dv IPPROTO_TCP
 401 or
 402 .Dv IPPROTO_UDP ,
 403 as defined in
 404 .In netinet/in.h .
 405 .Pp
 406 If
 407 .Fa local_addr
 408 or
 409 .Fa alias_addr
 410 is zero, this indicates that the packet aliasing address as established
 411 by
 412 .Fn LibAliasSetAddress
 413 is to be used.
 414 Even if
 415 .Fn LibAliasSetAddress
 416 is called to change the address after
 417 .Fn LibAliasRedirectPort
 418 is called, a zero reference will track this change.
 419 .Pp
 420 If the link is further set up to operate with load sharing, then
 421 .Fa local_addr
 422 and
 423 .Fa local_port
 424 are ignored, and are selected dynamically from the server pool, as described in
 425 .Fn LibAliasAddServer
 426 below.
 427 .Pp
 428 If
 429 .Fa remote_addr
 430 is zero, this indicates to redirect packets from any remote address.
 431 Likewise, if
 432 .Fa remote_port
 433 is zero, this indicates to redirect packets originating from any remote
 434 port number.
 435 The remote port specification will almost always be zero, but non-zero
 436 remote addresses can sometimes be useful for firewalling.
 437 If two calls to
 438 .Fn LibAliasRedirectPort
 439 overlap in their address/port specifications, then the most recent call
 440 will have precedence.
 441 .Pp
 442 This function returns a pointer which can subsequently be used by
 443 .Fn LibAliasRedirectDelete .
 444 If
 445 .Dv NULL
 446 is returned, then the function call did not complete successfully.
 447 .Pp
 448 All port numbers should be in network address byte order, so it is necessary
 449 to use
 450 .Xr htons 3
 451 to convert these parameters from internally readable numbers to network byte
 452 order.
 453 Addresses are also in network byte order, which is implicit in the use of the
 454 .Fa struct in_addr
 455 data type.
 456 .Ed
 457 .Pp
 458 .Ft struct alias_link *
 459 .Fo LibAliasRedirectAddr
 460 .Fa "struct libalias *"
 461 .Fa "struct in_addr local_addr"
 462 .Fa "struct in_addr alias_addr"
 463 .Fc
 464 .Bd -ragged -offset indent
 465 This function designates that all incoming traffic to
 466 .Fa alias_addr
 467 be redirected to
 468 .Fa local_addr .
 469 Similarly, all outgoing traffic from
 470 .Fa local_addr
 471 is aliased to
 472 .Fa alias_addr .
 473 .Pp
 474 If
 475 .Fa local_addr
 476 or
 477 .Fa alias_addr
 478 is zero, this indicates that the packet aliasing address as established by
 479 .Fn LibAliasSetAddress
 480 is to be used.
 481 Even if
 482 .Fn LibAliasSetAddress
 483 is called to change the address after
 484 .Fn LibAliasRedirectAddr
 485 is called, a zero reference will track this change.
 486 .Pp
 487 If the link is further set up to operate with load sharing, then the
 488 .Fa local_addr
 489 argument is ignored, and is selected dynamically from the server pool,
 490 as described in
 491 .Fn LibAliasAddServer
 492 below.
 493 .Pp
 494 If subsequent calls to
 495 .Fn LibAliasRedirectAddr
 496 use the same aliasing address, all new incoming traffic to this aliasing
 497 address will be redirected to the local address made in the last function
 498 call.
 499 New traffic generated by any of the local machines, designated in the
 500 several function calls, will be aliased to the same address.
 501 Consider the following example:
 502 .Bd -literal -offset indent
 503 LibAliasRedirectAddr(la, inet_aton("192.168.0.2"),
 504                         inet_aton("141.221.254.101"));
 505 LibAliasRedirectAddr(la, inet_aton("192.168.0.3"),
 506                         inet_aton("141.221.254.101"));
 507 LibAliasRedirectAddr(la, inet_aton("192.168.0.4"),
 508                         inet_aton("141.221.254.101"));
 509 .Ed
 510 .Pp
 511 Any outgoing connections such as
 512 .Xr telnet 1
 513 or
 514 .Xr ftp 1
 515 from 192.168.0.2, 192.168.0.3 and 192.168.0.4 will appear to come from
 516 141.221.254.101.
 517 Any incoming connections to 141.221.254.101 will be directed to 192.168.0.4.
 518 .Pp
 519 Any calls to
 520 .Fn LibAliasRedirectPort
 521 will have precedence over address mappings designated by
 522 .Fn LibAliasRedirectAddr .
 523 .Pp
 524 This function returns a pointer which can subsequently be used by
 525 .Fn LibAliasRedirectDelete .
 526 If
 527 .Dv NULL
 528 is returned, then the function call did not complete successfully.
 529 .Ed
 530 .Pp
 531 .Ft int
 532 .Fo LibAliasAddServer
 533 .Fa "struct libalias *"
 534 .Fa "struct alias_link *link"
 535 .Fa "struct in_addr addr"
 536 .Fa "u_short port"
 537 .Fc
 538 .Bd -ragged -offset indent
 539 This function sets the
 540 .Fa link
 541 up for Load Sharing using IP Network Address Translation (RFC 2391, LSNAT).
 542 LSNAT operates as follows.
 543 A client attempts to access a server by using the server virtual address.
 544 The LSNAT router transparently redirects the request to one of the hosts
 545 in the server pool, using a real-time load sharing algorithm.
 546 Multiple sessions may be initiated from the same client, and each session
 547 could be directed to a different host based on the load balance across server
 548 pool hosts when the sessions are initiated.
 549 If load sharing is desired for just a few specific services, the configuration
 550 on LSNAT could be defined to restrict load sharing to just the services
 551 desired.
 552 .Pp
 553 Currently, only the simplest selection algorithm is implemented, where a
 554 host is selected on a round-robin basis only, without regard to load on
 555 the host.
 556 .Pp
 557 First, the
 558 .Fa link
 559 is created by either
 560 .Fn LibAliasRedirectPort
 561 or
 562 .Fn LibAliasRedirectAddr .
 563 Then,
 564 .Fn LibAliasAddServer
 565 is called multiple times to add entries to the
 566 .Fa link Ns 's
 567 server pool.
 568 .Pp
 569 For links created with
 570 .Fn LibAliasRedirectAddr ,
 571 the
 572 .Fa port
 573 argument is ignored and could have any value, e.g.\& htons(~0).
 574 .Pp
 575 This function returns 0 on success, \-1 otherwise.
 576 .Ed
 577 .Pp
 578 .Ft int
 579 .Fn LibAliasRedirectDynamic "struct libalias *" "struct alias_link *link"
 580 .Bd -ragged -offset indent
 581 This function marks the specified static redirect rule entered by
 582 .Fn LibAliasRedirectPort
 583 as dynamic.
 584 This can be used to e.g.\& dynamically redirect a single TCP connection,
 585 after which the rule is removed.
 586 Only fully specified links can be made dynamic.
 587 (See the
 588 .Sx STATIC AND DYNAMIC LINKS
 589 and
 590 .Sx PARTIALLY SPECIFIED ALIASING LINKS
 591 sections below for a definition of static vs.\& dynamic,
 592 and partially vs.\& fully specified links.)
 593 .Pp
 594 This function returns 0 on success, \-1 otherwise.
 595 .Ed
 596 .Pp
 597 .Ft void
 598 .Fn LibAliasRedirectDelete "struct libalias *" "struct alias_link *link"
 599 .Bd -ragged -offset indent
 600 This function will delete a specific static redirect rule entered by
 601 .Fn LibAliasRedirectPort
 602 or
 603 .Fn LibAliasRedirectAddr .
 604 The parameter
 605 .Fa link
 606 is the pointer returned by either of the redirection functions.
 607 If an invalid pointer is passed to
 608 .Fn LibAliasRedirectDelete ,
 609 then a program crash or unpredictable operation could result, so
 610 care is needed when using this function.
 611 .Ed
 612 .Pp
 613 .Ft int
 614 .Fn LibAliasProxyRule "struct libalias *" "const char *cmd"
 615 .Bd -ragged -offset indent
 616 The passed
 617 .Fa cmd
 618 string consists of one or more pairs of words.
 619 The first word in each pair is a token and the second is the value that
 620 should be applied for that token.
 621 Tokens and their argument types are as follows:
 622 .Bl -tag -width indent
 623 .It Cm type encode_ip_hdr | encode_tcp_stream | no_encode
 624 In order to support transparent proxying, it is necessary to somehow
 625 pass the original address and port information into the new destination
 626 server.
 627 If
 628 .Cm encode_ip_hdr
 629 is specified, the original destination address and port are passed
 630 as an extra IP option.
 631 If
 632 .Cm encode_tcp_stream
 633 is specified, the original destination address and port are passed
 634 as the first piece of data in the TCP stream in the format
 635 .Dq Li DEST Ar IP port .
 636 .It Cm port Ar portnum
 637 Only packets with the destination port
 638 .Ar portnum
 639 are proxied.
 640 .It Cm server Ar host Ns Op : Ns Ar portnum
 641 This specifies the
 642 .Ar host
 643 and
 644 .Ar portnum
 645 that the data is to be redirected to.
 646 .Ar host
 647 must be an IP address rather than a DNS host name.
 648 If
 649 .Ar portnum
 650 is not specified, the destination port number is not changed.
 651 .Pp
 652 The
 653 .Ar server
 654 specification is mandatory unless the
 655 .Cm delete
 656 command is being used.
 657 .It Cm rule Ar index
 658 Normally, each call to
 659 .Fn LibAliasProxyRule
 660 inserts the next rule at the start of a linear list of rules.
 661 If an
 662 .Ar index
 663 is specified, the new rule will be checked after all rules with lower
 664 indices.
 665 Calls to
 666 .Fn LibAliasProxyRule
 667 that do not specify a rule are assigned rule 0.
 668 .It Cm delete Ar index
 669 This token and its argument MUST NOT be used with any other tokens.
 670 When used, all existing rules with the given
 671 .Ar index
 672 are deleted.
 673 .It Cm proto tcp | udp
 674 If specified, only packets of the given protocol type are matched.
 675 .It Cm src Ar IP Ns Op / Ns Ar bits
 676 If specified, only packets with a source address matching the given
 677 .Ar IP
 678 are matched.
 679 If
 680 .Ar bits
 681 is also specified, then the first
 682 .Ar bits
 683 bits of
 684 .Ar IP
 685 are taken as a network specification, and all IP addresses from that
 686 network will be matched.
 687 .It Cm dst Ar IP Ns Op / Ns Ar bits
 688 If specified, only packets with a destination address matching the given
 689 .Ar IP
 690 are matched.
 691 If
 692 .Ar bits
 693 is also specified, then the first
 694 .Ar bits
 695 bits of
 696 .Ar IP
 697 are taken as a network specification, and all IP addresses from that
 698 network will be matched.
 699 .El
 700 .Pp
 701 This function is usually used to redirect outgoing connections for
 702 internal machines that are not permitted certain types of internet
 703 access, or to restrict access to certain external machines.
 704 .Ed
 705 .Pp
 706 .Ft struct alias_link *
 707 .Fo LibAliasRedirectProto
 708 .Fa "struct libalias *"
 709 .Fa "struct in_addr local_addr"
 710 .Fa "struct in_addr remote_addr"
 711 .Fa "struct in_addr alias_addr"
 712 .Fa "u_char proto"
 713 .Fc
 714 .Bd -ragged -offset indent
 715 This function specifies that any IP packet with protocol number of
 716 .Fa proto
 717 from a given remote address to an alias address will be
 718 redirected to a specified local address.
 719 .Pp
 720 If
 721 .Fa local_addr
 722 or
 723 .Fa alias_addr
 724 is zero, this indicates that the packet aliasing address as established
 725 by
 726 .Fn LibAliasSetAddress
 727 is to be used.
 728 Even if
 729 .Fn LibAliasSetAddress
 730 is called to change the address after
 731 .Fn LibAliasRedirectProto
 732 is called, a zero reference will track this change.
 733 .Pp
 734 If
 735 .Fa remote_addr
 736 is zero, this indicates to redirect packets from any remote address.
 737 Non-zero remote addresses can sometimes be useful for firewalling.
 738 .Pp
 739 If two calls to
 740 .Fn LibAliasRedirectProto
 741 overlap in their address specifications, then the most recent call
 742 will have precedence.
 743 .Pp
 744 This function returns a pointer which can subsequently be used by
 745 .Fn LibAliasRedirectDelete .
 746 If
 747 .Dv NULL
 748 is returned, then the function call did not complete successfully.
 749 .Ed
 750 .Sh FRAGMENT HANDLING
 751 The functions in this section are used to deal with incoming fragments.
 752 .Pp
 753 Outgoing fragments are handled within
 754 .Fn LibAliasOut
 755 by changing the address according to any applicable mapping set by
 756 .Fn LibAliasRedirectAddr ,
 757 or the default aliasing address set by
 758 .Fn LibAliasSetAddress .
 759 .Pp
 760 Incoming fragments are handled in one of two ways.
 761 If the header of a fragmented IP packet has already been seen, then all
 762 subsequent fragments will be re-mapped in the same manner the header
 763 fragment was.
 764 Fragments which arrive before the header are saved and then retrieved
 765 once the header fragment has been resolved.
 766 .Pp
 767 .Ft int
 768 .Fn LibAliasSaveFragment "struct libalias *" "char *ptr"
 769 .Bd -ragged -offset indent
 770 When
 771 .Fn LibAliasIn
 772 returns
 773 .Dv PKT_ALIAS_UNRESOLVED_FRAGMENT ,
 774 this function can be used to save the pointer to the unresolved fragment.
 775 .Pp
 776 It is implicitly assumed that
 777 .Fa ptr
 778 points to a block of memory allocated by
 779 .Xr malloc 3 .
 780 If the fragment is never resolved, the packet aliasing engine will
 781 automatically free the memory after a timeout period.
 782 [Eventually this function should be modified so that a callback function
 783 for freeing memory is passed as an argument.]
 784 .Pp
 785 This function returns
 786 .Dv PKT_ALIAS_OK
 787 if it was successful and
 788 .Dv PKT_ALIAS_ERROR
 789 if there was an error.
 790 .Ed
 791 .Pp
 792 .Ft char *
 793 .Fn LibAliasGetFragment "struct libalias *" "char *buffer"
 794 .Bd -ragged -offset indent
 795 This function can be used to retrieve fragment pointers saved by
 796 .Fn LibAliasSaveFragment .
 797 The IP header fragment pointed to by
 798 .Fa buffer
 799 is the header fragment indicated when
 800 .Fn LibAliasIn
 801 returns
 802 .Dv PKT_ALIAS_FOUND_HEADER_FRAGMENT .
 803 Once a fragment pointer is retrieved, it becomes the calling program's
 804 responsibility to free the dynamically allocated memory for the fragment.
 805 .Pp
 806 The
 807 .Fn LibAliasGetFragment
 808 function can be called sequentially until there are no more fragments
 809 available, at which time it returns
 810 .Dv NULL .
 811 .Ed
 812 .Pp
 813 .Ft void
 814 .Fn LibAliasFragmentIn "struct libalias *" "char *header" "char *fragment"
 815 .Bd -ragged -offset indent
 816 When a fragment is retrieved with
 817 .Fn LibAliasGetFragment ,
 818 it can then be de-aliased with a call to
 819 .Fn LibAliasFragmentIn .
 820 The
 821 .Fa header
 822 argument is the pointer to a header fragment used as a template, and
 823 .Fa fragment
 824 is the pointer to the packet to be de-aliased.
 825 .Ed
 826 .Sh MISCELLANEOUS FUNCTIONS
 827 .Ft struct alias_link *
 828 .Fn AddLink "struct libalias *" "struct in_addr src_addr" "struct in_addr dst_addr" \
 829 "struct in_addr alias_addr" "u_short src_port" "u_short dst_port" \
 830 "int alias_param" "int link_type"
 831 .Bd -ragged -offset indent
 832 This function adds new state to the instance hash table.
 833 The dst_address and/or dst_port may be given as zero, which
 834 introduces some dynamic character into the link, since
 835 LibAliasSetAddress can change the address that is used.
 836 However, in the current implementation, such links can only be used
 837 for inbound (ext -> int) traffic.
 838 .Ed
 839 .Pp
 840 .Ft void
 841 .Fn LibAliasSetTarget "struct libalias *" "struct in_addr addr"
 842 .Bd -ragged -offset indent
 843 When an incoming packet not associated with any pre-existing aliasing link
 844 arrives at the host machine, it will be sent to the address indicated by a
 845 call to
 846 .Fn LibAliasSetTarget .
 847 .Pp
 848 If this function is called with an
 849 .Dv INADDR_NONE
 850 address argument, then all new incoming packets go to the address set by
 851 .Fn LibAliasSetAddress .
 852 .Pp
 853 If this function is not called, or is called with an
 854 .Dv INADDR_ANY
 855 address argument, then all new incoming packets go to the address specified
 856 in the packet.
 857 This allows external machines to talk directly to internal machines if they
 858 can route packets to the machine in question.
 859 .Ed
 860 .Pp
 861 .Ft int
 862 .Fn LibAliasCheckNewLink "struct libalias *"
 863 .Bd -ragged -offset indent
 864 This function returns a non-zero value when a new aliasing link is created.
 865 In circumstances where incoming traffic is being sequentially sent to
 866 different local servers, this function can be used to trigger when
 867 .Fn LibAliasSetTarget
 868 is called to change the default target address.
 869 .Ed
 870 .Pp
 871 .Ft u_short
 872 .Fn LibAliasInternetChecksum "struct libalias *" "u_short *buffer" "int nbytes"
 873 .Bd -ragged -offset indent
 874 This is a utility function that does not seem to be available elsewhere and
 875 is included as a convenience.
 876 It computes the internet checksum, which is used in both IP and
 877 protocol-specific headers (TCP, UDP, ICMP).
 878 .Pp
 879 The
 880 .Fa buffer
 881 argument points to the data block to be checksummed, and
 882 .Fa nbytes
 883 is the number of bytes.
 884 The 16-bit checksum field should be zeroed before computing the checksum.
 885 .Pp
 886 Checksums can also be verified by operating on a block of data including
 887 its checksum.
 888 If the checksum is valid,
 889 .Fn LibAliasInternetChecksum
 890 will return zero.
 891 .Ed
 892 .Pp
 893 .Ft int
 894 .Fn LibAliasUnaliasOut "struct libalias *" "char *buffer" "int maxpacketsize"
 895 .Bd -ragged -offset indent
 896 An outgoing packet, which has already been aliased,
 897 has its private address/port information restored by this function.
 898 The IP packet is pointed to by
 899 .Fa buffer ,
 900 and
 901 .Fa maxpacketsize
 902 is provided for error checking purposes.
 903 This function can be used if an already-aliased packet needs to have its
 904 original IP header restored for further processing (e.g.\& logging).
 905 .Ed
 906 .Sh AUTHORS
 907 .An Charles Mott Aq cm@linktel.net ,
 908 versions 1.0 - 1.8, 2.0 - 2.4.
 909 .An Eivind Eklund Aq eivind@FreeBSD.org ,
 910 versions 1.8b, 1.9 and 2.5.
 911 Added IRC DCC support as well as contributing a number of architectural
 912 improvements; added the firewall bypass for FTP/IRC DCC.
 913 .An Erik Salander Aq erik@whistle.com
 914 added support for PPTP and RTSP.
 915 .An Junichi Satoh Aq junichi@junichi.org
 916 added support for RTSP/PNA.
 917 .An Ruslan Ermilov Aq ru@FreeBSD.org
 918 added support for PPTP and LSNAT as well as general hacking.
 919 .An Paolo Pisati Aq piso@FreeBSD.org
 920 made the library modular, moving support for all
 921 protocols (except for IP, TCP and UDP) to external modules.
 922 .Sh ACKNOWLEDGEMENTS
 923 Listed below, in approximate chronological order, are individuals who
 924 have provided valuable comments and/or debugging assistance.
 925 .Bd -ragged -offset indent
 926 .An -split
 927 .An Gary Roberts
 928 .An Tom Torrance
 929 .An Reto Burkhalter
 930 .An Martin Renters
 931 .An Brian Somers
 932 .An Paul Traina
 933 .An Ari Suutari
 934 .An Dave Remien
 935 .An J. Fortes
 936 .An Andrzej Bialecki
 937 .An Gordon Burditt
 938 .Ed
 939 .Sh CONCEPTUAL BACKGROUND
 940 This section is intended for those who are planning to modify the source
 941 code or want to create somewhat esoteric applications using the packet
 942 aliasing functions.
 943 .Pp
 944 The conceptual framework under which the packet aliasing engine operates
 945 is described here.
 946 Central to the discussion is the idea of an
 947 .Em aliasing link
 948 which describes the relationship for a given packet transaction between
 949 the local machine, aliased identity and remote machine.
 950 It is discussed how such links come into existence and are destroyed.
 951 .Ss ALIASING LINKS
 952 There is a notion of an
 953 .Em aliasing link ,
 954 which is a 7-tuple describing a specific translation:
 955 .Bd -literal -offset indent
 956 (local addr, local port, alias addr, alias port,
 957  remote addr, remote port, protocol)
 958 .Ed
 959 .Pp
 960 Outgoing packets have the local address and port number replaced with the
 961 alias address and port number.
 962 Incoming packets undergo the reverse process.
 963 The packet aliasing engine attempts to match packets against an internal
 964 table of aliasing links to determine how to modify a given IP packet.
 965 Both the IP header and protocol dependent headers are modified as necessary.
 966 Aliasing links are created and deleted as necessary according to network
 967 traffic.
 968 .Pp
 969 Protocols can be TCP, UDP or even ICMP in certain circumstances.
 970 (Some types of ICMP packets can be aliased according to sequence or ID
 971 number which acts as an equivalent port number for identifying how
 972 individual packets should be handled.)
 973 .Pp
 974 Each aliasing link must have a unique combination of the following five
 975 quantities: alias address/port, remote address/port and protocol.
 976 This ensures that several machines on a local network can share the
 977 same aliasing IP address.
 978 In cases where conflicts might arise, the aliasing port is chosen so that
 979 uniqueness is maintained.
 980 .Ss STATIC AND DYNAMIC LINKS
 981 Aliasing links can either be static or dynamic.
 982 Static links persist indefinitely and represent fixed rules for translating
 983 IP packets.
 984 Dynamic links come into existence for a specific TCP connection or UDP
 985 transaction or ICMP ECHO sequence.
 986 For the case of TCP, the connection can be monitored to see when the
 987 associated aliasing link should be deleted.
 988 Aliasing links for UDP transactions (and ICMP ECHO and TIMESTAMP requests)
 989 work on a simple timeout rule.
 990 When no activity is observed on a dynamic link for a certain amount of time
 991 it is automatically deleted.
 992 Timeout rules also apply to TCP connections which do not open or close
 993 properly.
 994 .Ss PARTIALLY SPECIFIED ALIASING LINKS
 995 Aliasing links can be partially specified, meaning that the remote address
 996 and/or remote port are unknown.
 997 In this case, when a packet matching the incomplete specification is found,
 998 a fully specified dynamic link is created.
 999 If the original partially specified link is dynamic, it will be deleted
1000 after the fully specified link is created, otherwise it will persist.
1001 .Pp
1002 For instance, a partially specified link might be
1003 .Bd -literal -offset indent
1004 (192.168.0.4, 23, 204.228.203.215, 8066, 0, 0, tcp)
1005 .Ed
1006 .Pp
1007 The zeros denote unspecified components for the remote address and port.
1008 If this link were static it would have the effect of redirecting all
1009 incoming traffic from port 8066 of 204.228.203.215 to port 23 (telnet)
1010 of machine 192.168.0.4 on the local network.
1011 Each individual telnet connection would initiate the creation of a distinct
1012 dynamic link.
1013 .Ss DYNAMIC LINK CREATION
1014 In addition to aliasing links, there are also address mappings that can be
1015 stored within the internal data table of the packet aliasing mechanism.
1016 .Bd -literal -offset indent
1017 (local addr, alias addr)
1018 .Ed
1019 .Pp
1020 Address mappings are searched when creating new dynamic links.
1021 .Pp
1022 All outgoing packets from the local network automatically create a dynamic
1023 link if they do not match an already existing fully specified link.
1024 If an address mapping exists for the outgoing packet, this determines
1025 the alias address to be used.
1026 If no mapping exists, then a default address, usually the address of the
1027 packet aliasing host, is used.
1028 If necessary, this default address can be changed as often as each individual
1029 packet arrives.
1030 .Pp
1031 The aliasing port number is determined such that the new dynamic link does
1032 not conflict with any existing links.
1033 In the default operating mode, the packet aliasing engine attempts to set
1034 the aliasing port equal to the local port number.
1035 If this results in a conflict, then port numbers are randomly chosen until
1036 a unique aliasing link can be established.
1037 In an alternate operating mode, the first choice of an aliasing port is also
1038 random and unrelated to the local port number.
1039 .Sh MODULAR ARCHITECTURE (AND Xr ipfw 4 Sh SUPPORT)
1040 One of the latest improvements to
1041 .Nm
1042 was to make its support
1043 for new protocols independent from the rest of the library, giving it
1044 the ability to load/unload support for new protocols at run-time.
1045 To achieve this feature, all the code for protocol handling was moved
1046 to a series of modules outside of the main library.
1047 These modules are compiled from the same sources but work in
1048 different ways, depending on whether they are compiled to work inside a kernel
1049 or as part of the userland library.
1050 .Ss LIBALIAS MODULES IN KERNEL LAND
1051 When compiled for the kernel,
1052 .Nm
1053 modules are plain KLDs recognizable with the
1054 .Pa alias_
1055 prefix.
1056 .Pp
1057 To add support for a new protocol, load the corresponding module.
1058 For example:
1059 .Pp
1060 .Dl "kldload alias_ftp"
1061 .Pp
1062 When support for a protocol is no longer needed, its module can be unloaded:
1063 .Pp
1064 .Dl "kldunload alias_ftp"
1065 .Ss LIBALIAS MODULES IN USERLAND
1066 Due to the differences between kernel and userland (no KLD mechanism,
1067 many different address spaces, etc.), we had to change a bit how to
1068 handle module loading/tracking/unloading in userland.
1069 .Pp
1070 While compiled for a userland
1071 .Nm ,
1072 all the modules are plain libraries, residing in
1073 .Pa /usr/lib ,
1074 and recognizable with the
1075 .Pa libalias_
1076 prefix.
1077 .Pp
1078 There is a configuration file,
1079 .Pa /etc/libalias.conf ,
1080 with the following contents (by default):
1081 .Bd -literal -offset indent
1082 /usr/lib/libalias_cuseeme.so
1083 /usr/lib/libalias_ftp.so
1084 /usr/lib/libalias_irc.so
1085 /usr/lib/libalias_nbt.so
1086 /usr/lib/libalias_pptp.so
1087 /usr/lib/libalias_skinny.so
1088 /usr/lib/libalias_smedia.so
1089 .Ed
1090 .Pp
1091 This file contains the paths to the modules that
1092 .Nm
1093 will load.
1094 To load/unload a new module, just add its path to
1095 .Pa libalias.conf
1096 and call
1097 .Fn LibAliasRefreshModules
1098 from the program.
1099 In case the application provides a
1100 .Dv SIGHUP
1101 signal handler, add a call to
1102 .Fn LibAliasRefreshModules
1103 inside the handler, and everytime you want to refresh the loaded modules,
1104 send it the
1105 .Dv SIGHUP
1106 signal:
1107 .Pp
1108 .Dl "kill -HUP <process_pid>"
1109 .Ss MODULAR ARCHITECURE: HOW IT WORKS
1110 The modular architecture of
1111 .Nm
1112 works similar whether it is running inside the
1113 kernel or in userland.
1114 From
1115 .Pa alias_mod.c :
1116 .Bd -literal
1117 /* Protocol and userland module handlers chains. */
1118 LIST_HEAD(handler_chain, proto_handler) handler_chain ...
1119 \&...
1120 SLIST_HEAD(dll_chain, dll) dll_chain ...
1121 .Ed
1122 .Pp
1123 .Va handler_chain
1124 keeps track of all the protocol handlers loaded, while
1125 .Va ddl_chain
1126 tracks which userland modules are loaded.
1127 .Pp
1128 .Va handler_chain
1129 is composed of
1130 .Vt "struct proto_handler"
1131 entries:
1132 .Bd -literal
1133 struct proto_handler {
1134         u_int pri;
1135         int16_t dir;
1136         uint8_t proto;
1137         int (*fingerprint)(struct libalias *la,
1138                  struct ip *pip, struct alias_data *ah);
1139         int (*protohandler)(struct libalias *la,
1140                  struct ip *pip, struct alias_data *ah);
1141         LIST_ENTRY(proto_handler) entries;
1142 };
1143 .Ed
1144 .Pp
1145 where:
1146 .Bl -inset
1147 .It Va pri
1148 is the priority assigned to a protocol handler; lower priority
1149 is better.
1150 .It Va dir
1151 is the direction of packets: ingoing or outgoing.
1152 .It Va proto
1153 indicates to which protocol this packet belongs: IP, TCP or UDP.
1154 .It Va fingerprint
1155 points to the fingerprint function while protohandler points
1156 to the protocol handler function.
1157 .El
1158 .Pp
1159 The
1160 .Va fingerprint
1161 function has the dual role of checking if the
1162 incoming packet is found, and if it belongs to any categories that this
1163 module can handle.
1164 .Pp
1165 The
1166 .Va protohandler
1167 function actually manipulates
1168 the packet to make
1169 .Nm
1170 correctly NAT it.
1171 .Pp
1172 When a packet enters
1173 .Nm ,
1174 if it meets a module hook,
1175 .Va handler_chain
1176 is searched to see if there is an handler that matches
1177 this type of a packet (it checks protocol and direction of packet).
1178 Then, if more than one handler is found, it starts with the module with
1179 the lowest priority number: it calls the
1180 .Va fingerprint
1181 function and interprets the result.
1182 .Pp
1183 If the result value is equal to 0 then it calls the protocol handler
1184 of this handler and returns.
1185 Otherwise, it proceeds to the next eligible module until the
1186 .Va handler_chain
1187 is exhausted.
1188 .Pp
1189 Inside
1190 .Nm ,
1191 the module hook looks like this:
1192 .Bd -literal -offset indent
1193 struct alias_data ad = {
1194         lnk,
1195         &original_address,
1196         &alias_address,
1197         &alias_port,
1198         &ud->uh_sport,          /* original source port */
1199         &ud->uh_dport,          /* original dest port */
1200         256                     /* maxpacketsize */
1201 };
1202
1203 \&...
1204
1205 /* walk out chain */
1206 err = find_handler(IN, UDP, la, pip, &ad);
1207 .Ed
1208 .Pp
1209 All data useful to a module are gathered together in an
1210 .Vt alias_data
1211 structure, then
1212 .Fn find_handler
1213 is called.
1214 The
1215 .Fn find_handler
1216 function is responsible for walking the handler
1217 chain; it receives as input parameters:
1218 .Bl -tag -width indent
1219 .It Fa IN
1220 direction
1221 .It Fa UDP
1222 working protocol
1223 .It Fa la
1224 pointer to this instance of libalias
1225 .It Fa pip
1226 pointer to a
1227 .Vt "struct ip"
1228 .It Fa ad
1229 pointer to
1230 .Vt "struct alias_data"
1231 (see above)
1232 .El
1233 .Pp
1234 In this case,
1235 .Fn find_handler
1236 will search only for modules registered for
1237 supporting INcoming UDP packets.
1238 .Pp
1239 As was mentioned earlier,
1240 .Nm
1241 in userland is a bit different, as
1242 care must be taken in module handling as well (avoiding duplicate load of
1243 modules, avoiding modules with same name, etc.) so
1244 .Va dll_chain
1245 was introduced.
1246 .Pp
1247 .Va dll_chain
1248 contains a list of all userland
1249 .Nm
1250 modules loaded.
1251 .Pp
1252 When an application calls
1253 .Fn LibAliasRefreshModules ,
1254 .Nm
1255 first unloads all the loaded modules, then reloads all the modules listed in
1256 .Pa /etc/libalias.conf :
1257 for every module loaded, a new entry is added to
1258 .Va dll_chain .
1259 .Pp
1260 .Va dll_chain
1261 is composed of
1262 .Vt "struct dll"
1263 entries:
1264 .Bd -literal
1265 struct dll {
1266         /* name of module */
1267         char            name[DLL_LEN];
1268         /*
1269          * ptr to shared obj obtained through
1270          * dlopen() - use this ptr to get access
1271          * to any symbols from a loaded module
1272          * via dlsym()
1273          */
1274         void            *handle;
1275         struct dll      *next;
1276 };
1277 .Ed
1278 .Bl -inset
1279 .It Va name
1280 is the name of the module.
1281 .It Va handle
1282 is a pointer to the module obtained through
1283 .Xr dlopen 3 .
1284 .El
1285 Whenever a module is loaded in userland, an entry is added to
1286 .Va dll_chain ,
1287 then every protocol handler present in that module
1288 is resolved and registered in
1289 .Va handler_chain .
1290 .Ss HOW TO WRITE A MODULE FOR LIBALIAS
1291 There is a module (called
1292 .Pa alias_dummy.[ch] )
1293 in
1294 .Nm
1295 that can be used as a skeleton for future work.
1296 Here we analyse some parts of that module.
1297 From
1298 .Pa alias_dummy.c :
1299 .Bd -literal
1300 struct proto_handler handlers [] = {{666, IN|OUT, UDP|TCP,
1301                                     &fingerprint, &protohandler}};
1302 .Ed
1303 .Pp
1304 The variable
1305 .Va handlers
1306 is the
1307 .Dq "most important thing"
1308 in a module
1309 since it describes the handlers present and lets the outside world use
1310 it in an opaque way.
1311 .Pp
1312 It must ALWAYS be present in every module, and it MUST retain
1313 the name
1314 .Va handlers ,
1315 otherwise attempting to load a module in userland will fail and
1316 complain about missing symbols: for more information about module
1317 load/unload, please refer to
1318 .Fn LibAliasRefreshModules ,
1319 .Fn LibAliasLoadModule
1320 and
1321 .Fn LibAliasUnloadModule
1322 in
1323 .Pa alias.c .
1324 .Pp
1325 .Va handlers
1326 contains all the
1327 .Vt proto_handler
1328 structures present in a module.
1329 .Bd -literal
1330 static int
1331 mod_handler(module_t mod, int type, void *data)
1332 {
1333         int error;
1334
1335         switch (type) {
1336         case MOD_LOAD:
1337                 error = 0;
1338                 attach_handlers(handlers);
1339                 break;
1340         case MOD_UNLOAD:
1341                 error = 0;
1342                 detach_handlers(handlers;
1343                 break;
1344         default:
1345                 error = EINVAL;
1346         }
1347         return (error);
1348 }
1349 .Ed
1350 When running as KLD,
1351 .Fn mod_handler
1352 registers/deregisters the module using
1353 .Fn attach_handlers
1354 and
1355 .Fn detach_handlers ,
1356 respectively.
1357 .Pp
1358 Every module must contain at least 2 functions: one fingerprint
1359 function and a protocol handler function.
1360 .Bd -literal
1361 #ifdef _KERNEL
1362 static
1363 #endif
1364 int
1365 fingerprint(struct libalias *la, struct ip *pip, struct alias_data *ah)
1366 {
1367
1368 \&...
1369 }
1370
1371 #ifdef _KERNEL
1372 static
1373 #endif
1374 int
1375 protohandler(struct libalias *la, struct ip *pip,
1376              struct alias_data *ah)
1377 {
1378
1379 \&...
1380 }
1381 .Ed
1382 and they must accept exactly these input parameters.
1383 .Ss PATCHING AN APPLICATION FOR USERLAND LIBALIAS MODULES
1384 To add module support into an application that uses
1385 .Nm ,
1386 the following simple steps can be followed.
1387 .Bl -enum
1388 .It
1389 Find the main file of an application
1390 (let us call it
1391 .Pa main.c ) .
1392 .It
1393 Add this to the header section of
1394 .Pa main.c ,
1395 if not already present:
1396 .Pp
1397 .Dl "#include <signal.h>"
1398 .Pp
1399 and this just after the header section:
1400 .Pp
1401 .Dl "static void signal_handler(int);"
1402 .It
1403 Add the following line to the init function of an application or,
1404 if it does not have any init function, put it in
1405 .Fn main :
1406 .Pp
1407 .Dl "signal(SIGHUP, signal_handler);"
1408 .Pp
1409 and place the
1410 .Fn signal_handler
1411 function somewhere in
1412 .Pa main.c :
1413 .Bd -literal -offset indent
1414 static void
1415 signal_handler(int sig)
1416 {
1417
1418         LibAliasRefreshModules();
1419 }
1420 .Ed
1421 .Pp
1422 Otherwise, if an application already traps the
1423 .Dv SIGHUP
1424 signal, just add a call to
1425 .Fn LibAliasRefreshModules
1426 in the signal handler function.
1427 .El
1428 For example, to patch
1429 .Xr natd 8
1430 to use
1431 .Nm
1432 modules, just add the following line to
1433 .Fn RefreshAddr "int sig __unused" :
1434 .Pp
1435 .Dl "LibAliasRefreshModules()"
1436 .Pp
1437 recompile and you are done.
1438 .Ss LOGGING SUPPORT IN KERNEL LAND
1439 When working as KLD,
1440 .Nm
1441 now has log support that
1442 happens on a buffer allocated inside
1443 .Vt "struct libalias"
1444 (from
1445 .Pa alias_local.h ) :
1446 .Bd -literal
1447 struct libalias {
1448        ...
1449
1450         /* log descriptor        */
1451 #ifdef  KERNEL_LOG
1452         char           *logDesc;        /*
1453                                          * ptr to an auto-malloced
1454                                          * memory buffer when libalias
1455                                          * works as kld
1456                                          */
1457 #else
1458         FILE           *logDesc;        /*
1459                                          * ptr to /var/log/alias.log
1460                                          * when libalias runs as a
1461                                          * userland lib
1462                                          */
1463 #endif
1464
1465         ...
1466 }
1467 .Ed
1468 so all applications using
1469 .Nm
1470 will be able to handle their
1471 own logs, if they want, accessing
1472 .Va logDesc .
1473 Moreover, every change to a log buffer is automatically added to
1474 .Xr syslog 3
1475 with the
1476 .Dv LOG_SECURITY
1477 facility and the
1478 .Dv LOG_INFO
1479 level.