Attachment 116654 Details for Bug 158623 – file.diff

[patch] file.diff

file.diff (text/plain), 12.99 KB, created by Ben Kaduk on 2011-07-03 22:20:11 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Ben Kaduk

Created: 2011-07-03 22:20:11 UTC

Size: 12.99 KB

patch

obsolete

>--- libalias.3.orig	2011-07-01 18:58:15.000000000 -0400
>+++ libalias.3	2011-07-03 17:08:48.000000000 -0400
>@@ -25,7 +25,7 @@
> .\"
> .\" $FreeBSD: src/sys/netinet/libalias/libalias.3,v 1.61 2011/06/22 20:00:27 ae Exp $
> .\"
>-.Dd June 22, 2011
>+.Dd July 03, 2011
> .Dt LIBALIAS 3
> .Os
> .Sh NAME
>@@ -52,7 +52,7 @@
> .Pp
> A certain amount of flexibility is built into the packet aliasing engine.
> In the simplest mode of operation, a many-to-one address mapping takes
>-place between local network and the packet aliasing host.
>+place between the local network and the packet aliasing host.
> This is known as IP masquerading.
> In addition, one-to-one mappings between local and public addresses can
> also be implemented, which is known as static NAT.
>@@ -63,13 +63,13 @@
> private address/port.
> .Pp
> The packet aliasing engine was designed to operate in user space outside
>-of the kernel, without any access to private kernel data structure, but
>+of the kernel, without any access to private kernel data structures, but
> the source code can also be ported to a kernel environment.
> .Sh INITIALIZATION AND CONTROL
> One special function,
> .Fn LibAliasInit ,
>-must always be called before any packet handling may be performed and
>-the returned instance pointer passed to all the other functions.
>+must always be called before any packet handling may be performed, and
>+the returned instance pointer must be passed to all the other functions.
> Normally, the
> .Fn LibAliasSetAddress
> function is called afterwards, to set the default aliasing address.
>@@ -118,8 +118,8 @@
> This function has no return value and is used to clear any
> resources attached to internal data structures.
> .Pp
>-This functions should be called when a program stops using the aliasing
>-engine; it does, amongst other things, clear out any firewall holes.
>+This function should be called when a program stops using the aliasing
>+engine; amongst other things, it clears out any firewall holes.
> To provide backwards compatibility and extra security, it is added to
> the
> .Xr atexit 3
>@@ -135,7 +135,7 @@
> All outgoing packets are re-mapped to this address unless overridden by a
> static address mapping established by
> .Fn LibAliasRedirectAddr .
>-If this function is not called, and no static rules match, an outgoing
>+If this function has not been called, and no static rules match, an outgoing
> packet retains its source address.
> .Pp
> If the
>@@ -150,7 +150,7 @@
> If the
> .Dv PKT_ALIAS_RESET_ON_ADDR_CHANGE
> mode bit is set to zero, this function can also be used to dynamically change
>-the aliasing address on a packet to packet basis (it is a low overhead call).
>+the aliasing address on a packet-to-packet basis (it is a low overhead call).
> .Pp
> It is mandatory that this function be called prior to any packet handling.
> .Ed
>@@ -170,7 +170,7 @@
> .It Dv PKT_ALIAS_LOG
> Enables logging into
> .Pa /var/log/alias.log .
>-Each time an aliasing link is created or deleted, the log file is appended
>+Each time an aliasing link is created or deleted, the log file is appended to
> with the current number of ICMP, TCP and UDP links.
> Mainly useful for debugging when the log file is viewed continuously with
> .Xr tail 1 .
>@@ -186,7 +186,7 @@
> aliasing host or local network will be unaffected.
> This mode bit is useful for implementing a one-way firewall.
> .It Dv PKT_ALIAS_SAME_PORTS
>-If this mode bit is set, the packet aliasing engine will attempt to leave
>+If this mode bit is set, the packet-aliasing engine will attempt to leave
> the alias port numbers unchanged from the actual local port numbers.
> This can be done as long as the quintuple (proto, alias addr, alias port,
> remote addr, remote port) is unique.
>@@ -211,7 +211,7 @@
> 192.168.0.0  ->  192.168.255.255  (Class C subnets)
> .Ed
> .Pp
>-This option is useful in the case that packet aliasing host has both
>+This option is useful in the case that the packet aliasing host has both
> registered and unregistered subnets on different interfaces.
> The registered subnet is fully accessible to the outside world, so traffic
> from it does not need to be passed through the packet aliasing engine.
>@@ -229,8 +229,9 @@
> .It Dv PKT_ALIAS_PUNCH_FW
> This option makes
> .Nm
>-`punch holes' in an
>-.Xr ipfirewall 4
>+.Dq punch holes
>+in an
>+.Xr ipfirewall 4 -
> based firewall for FTP/IRC DCC connections.
> The holes punched are bound by from/to IP address and port; it will not be
> possible to use a hole for another connection.
>@@ -240,9 +241,9 @@
> (e.g.\& kill -9),
> changing the state of the flag will clear the entire firewall range
> allocated for holes.
>-This will also happen on the initial call to
>-.Fn LibAliasSetFWBase .
>-This call must happen prior to setting this flag.
>+This clearing will also happen on the initial call to
>+.Fn LibAliasSetFWBase ,
>+which must happen prior to setting this flag.
> .It Dv PKT_ALIAS_REVERSE
> This option makes
> .Nm
>@@ -260,9 +261,11 @@
> .It Dv PKT_ALIAS_SKIP_GLOBAL
> This option is used by
> .Pa ipfw_nat
>-only. Specifying it as a flag to
>+only.
>+Specifying it as a flag to
> .Fn LibAliasSetMode
>-has no effect. See section
>+has no effect.
>+See section
> .Sx NETWORK ADDRESS TRANSLATION
> in
> .Xr ipfw 8
>@@ -273,10 +276,10 @@
> .Ft void
> .Fn LibAliasSetFWBase "struct libalias *" "unsigned int base" "unsigned int num"
> .Bd -ragged -offset indent
>-Set firewall range allocated for punching firewall holes (with the
>+Set the firewall range allocated for punching firewall holes (with the
> .Dv PKT_ALIAS_PUNCH_FW
> flag).
>-The range will be cleared for all rules on initialization.
>+The range is cleared for all rules on initialization.
> .Ed
> .Pp
> .Ft void
>@@ -302,7 +305,7 @@
> .Fn LibAliasIn
> and
> .Fn LibAliasOut ,
>-comprise minimal set of functions needed for a basic IP masquerading
>+comprise the minimal set of functions needed for a basic IP masquerading
> implementation.
> .Pp
> .Ft int
>@@ -323,11 +326,11 @@
> The packet aliasing process was successful.
> .It Dv PKT_ALIAS_IGNORED
> The packet was ignored and not de-aliased.
>-This can happen if the protocol is unrecognized, possibly an ICMP message
>-type is not handled or if incoming packets for new connections are being
>-ignored (if
>+This can happen if the protocol is unrecognized, as for an ICMP message
>+type that is not handled, or if incoming packets for new connections are being
>+ignored (if the
> .Dv PKT_ALIAS_DENY_INCOMING
>-mode bit was set by
>+mode bit was set using
> .Fn LibAliasSetMode ) .
> .It Dv PKT_ALIAS_UNRESOLVED_FRAGMENT
> This is returned when a fragment cannot be resolved because the header
>@@ -418,7 +421,7 @@
> .Fn LibAliasRedirectPort
> is called, a zero reference will track this change.
> .Pp
>-If the link is further set up to operate for a load sharing, then
>+If the link is further set up to operate with load sharing, then
> .Fa local_addr
> and
> .Fa local_port
>@@ -433,7 +436,7 @@
> .Fa remote_port
> is zero, this indicates to redirect packets originating from any remote
> port number.
>-Almost always, the remote port specification will be zero, but non-zero
>+The remote port specification will almost always be zero, but non-zero
> remote addresses can sometimes be useful for firewalling.
> If two calls to
> .Fn LibAliasRedirectPort
>@@ -485,8 +488,9 @@
> .Fn LibAliasRedirectAddr
> is called, a zero reference will track this change.
> .Pp
>-If the link is further set up to operate for a load sharing, then
>+If the link is further set up to operate with load sharing, then the
> .Fa local_addr
>+argument
> is ignored, and is selected dynamically from the server pool, as described in
> .Fn LibAliasAddServer
> below.
>@@ -542,12 +546,12 @@
> LSNAT operates as follows.
> A client attempts to access a server by using the server virtual address.
> The LSNAT router transparently redirects the request to one of the hosts
>-in server pool, selected using a real-time load sharing algorithm.
>+in the server pool, using a real-time load sharing algorithm.
> Multiple sessions may be initiated from the same client, and each session
>-could be directed to a different host based on load balance across server
>-pool hosts at the time.
>-If load share is desired for just a few specific services, the configuration
>-on LSNAT could be defined to restrict load share for just the services
>+could be directed to a different host based on the load balance across server
>+pool hosts when the sessions are initiated.
>+If load sharing is desired for just a few specific services, the configuration
>+on LSNAT could be defined to restrict load sharing to just the services
> desired.
> .Pp
> Currently, only the simplest selection algorithm is implemented, where a
>@@ -606,8 +610,8 @@
> is the pointer returned by either of the redirection functions.
> If an invalid pointer is passed to
> .Fn LibAliasRedirectDelete ,
>-then a program crash or unpredictable operation could result, so it is
>-necessary to be careful using this function.
>+then a program crash or unpredictable operation could result, so
>+care is needed when using this function.
> .Ed
> .Pp
> .Ft int
>@@ -714,7 +718,7 @@
> .Bd -ragged -offset indent
> This function specifies that any IP packet with protocol number of
> .Fa proto
>-from a given remote address to an alias address be
>+from a given remote address to an alias address will be
> redirected to a specified local address.
> .Pp
> If
>@@ -829,10 +833,12 @@
> "struct in_addr alias_addr" "u_short src_port" "u_short dst_port" \
> "int alias_param" "int link_type"
> .Bd -ragged -offset indent
>-This function adds new state to instance hash table.
>-Zero can be specified instead of dst_address and/or dst port.
>-This makes link partially specified dynamic.
>-However due to hashing method such links can be resolved on inbound (ext -> int) only.
>+This function adds new state to the instance hash table.
>+The dst_address and/or dst_port may be given as zero, which
>+introduces some dynamic character into the link, since
>+LibAliasSetAddress can change the address that is used.
>+However, in the current implementation, such links can only be used
>+for inbound (ext -> int) traffic.
> .Ed
> .Pp
> .Ft void
>@@ -1119,9 +1125,9 @@
> .Ed
> .Pp
> .Va handler_chain
>-keep tracks of all the protocol handlers loaded, while
>+keeps track of all the protocol handlers loaded, while
> .Va ddl_chain
>-takes care of userland modules loaded.
>+tracks which userland modules are loaded.
> .Pp
> .Va handler_chain
> is composed of
>@@ -1143,12 +1149,12 @@
> where:
> .Bl -inset
> .It Va pri
>-is the priority assigned to a protocol handler, lower
>+is the priority assigned to a protocol handler; lower priority
> is better.
> .It Va dir
> is the direction of packets: ingoing or outgoing.
> .It Va proto
>-says at which protocol this packet belongs: IP, TCP or UDP.
>+indicates to which protocol this packet belongs: IP, TCP or UDP.
> .It Va fingerprint
> points to the fingerprint function while protohandler points
> to the protocol handler function.
>@@ -1156,8 +1162,8 @@
> .Pp
> The
> .Va fingerprint
>-function has the double of scope of checking if the
>-incoming packet is found and if it belongs to any categories that this
>+function has the dual role of checking if the
>+incoming packet is found, and if it belongs to any categories that this
> module can handle.
> .Pp
> The
>@@ -1172,7 +1178,8 @@
> if it meets a module hook,
> .Va handler_chain
> is searched to see if there is an handler that matches
>-this type of a packet (it checks protocol and direction of packet), then if
>+this type of a packet (it checks protocol and direction of packet).
>+Then, if
> more than one handler is found, it starts with the module with
> the lowest priority number: it calls the
> .Va fingerprint
>@@ -1211,8 +1218,8 @@
> is called.
> The
> .Fn find_handler
>-function is responsible for walking out the handler
>-chain, it receives as input parameters:
>+function is responsible for walking the handler
>+chain; it receives as input parameters:
> .Bl -tag -width indent
> .It Fa IN
> direction
>@@ -1236,9 +1243,9 @@
> .Pp
> As was mentioned earlier,
> .Nm
>-in userland is a bit different, cause
>-care has to be taken of module handling too (avoiding duplicate load of
>-module, avoiding module with same name, etc.) so
>+in userland is a bit different, as
>+care must be taken in module handling as well (avoiding duplicate load of
>+modules, avoiding modules with same name, etc.) so
> .Va dll_chain
> was introduced.
> .Pp
>@@ -1252,9 +1259,8 @@
> .Nm
> first unloads all the loaded modules, then reloads all the modules listed in
> .Pa /etc/libalias.conf :
>-for every module loaded, a new entry to
>-.Va dll_chain
>-is added.
>+for every module loaded, a new entry is added to
>+.Va dll_chain .
> .Pp
> .Va dll_chain
> is composed of
>@@ -1291,7 +1297,8 @@
> .Pa alias_dummy.[ch] )
> in
> .Nm
>-that can be used as a skeleton for future work, here we analyse some parts of that
>+that can be used as a skeleton for future work.
>+Here we analyse some parts of that
> module.
> From
> .Pa alias_dummy.c :
>@@ -1305,7 +1312,7 @@
> is the
> .Dq "most important thing"
> in a module
>-cause it describes the handlers present and lets the outside world use
>+since it describes the handlers present and lets the outside world use
> it in an opaque way.
> .Pp
> It must ALWAYS be present in every module, and it MUST retain
>@@ -1348,7 +1355,7 @@
> .Ed
> When running as KLD,
> .Fn mod_handler
>-register/deregister the module using
>+registers/deregisters the module using
> .Fn attach_handlers
> and
> .Fn detach_handlers ,

Actions: View | Diff

Attachments on bug 158623: 116654