Index: stable/4/share/man/man4/divert.4 =================================================================== --- stable/4/share/man/man4/divert.4 (revision 67508) +++ stable/4/share/man/man4/divert.4 (revision 67509) @@ -1,170 +1,170 @@ .\" $FreeBSD$ .\" .Dd June 18, 1996 .Dt DIVERT 4 .Os FreeBSD .Sh NAME .Nm divert .Nd kernel packet diversion mechanism .Sh SYNOPSIS .Fd #include .Fd #include .Fd #include .Ft int .Fn socket PF_INET SOCK_RAW IPPROTO_DIVERT .Sh DESCRIPTION .Pp Divert sockets are similar to raw IP sockets, except that they can be bound to a specific .Nm port via the .Xr bind 2 system call. The IP address in the bind is ignored; only the port number is significant. A divert socket bound to a divert port will receive all packets diverted to that port by some (here unspecified) kernel mechanism(s). Packets may also be written to a divert port, in which case they re-enter kernel IP packet processing. .Pp Divert sockets are normally used in conjunction with FreeBSD's packet filtering implementation and the .Xr ipfw 8 program. By reading from and writing to a divert socket, matching packets can be passed through an arbitrary ``filter'' as they travel through the host machine, special routing tricks can be done, etc. .Sh READING PACKETS Packets are diverted either as they are ``incoming'' or ``outgoing.'' Incoming packets are diverted after reception on an IP interface, whereas outgoing packets are diverted before next hop forwarding. .Pp Diverted packets may be read unaltered via .Xr read 2 , .Xr recv 2 , or .Xr recvfrom 2 . In the latter case, the address returned will have its port set to the some tag supplied by the packet diverter, (usually the ipfw rule number) and the IP address set to the (first) address of the interface on which the packet was received (if the packet was incoming) or .Dv INADDR_ANY (if the packet was outgoing). In the case of an incoming packet the interface name will also be placed in the 8 bytes following the address, (assuming it fits). .Sh WRITING PACKETS Writing to a divert socket is similar to writing to a raw IP socket; the packet is injected ``as is'' into the normal kernel IP packet processing and minimal error checking is done. Packets are written as either incoming or outgoing: if .Xr write 2 or .Xr send 2 is used to deliver the packet, or if .Xr sendto 2 is used with a destination IP address of .Dv INADDR_ANY , then the packet is treated as if it were outgoing, i.e., destined for a non-local address. Otherwise, the packet is assumed to be incoming and full packet routing is done. .Pp In the latter case, the IP address specified must match the address of some local interface, or an interface name must be found after the IP address. If an interface name is found, that interface will be used and the value of the IP address will be ignored (other than the fact that it is not .Dv INADDR_ANY ). This is to indicate on which interface the packet ``arrived.'' .Pp Normally, packets read as incoming should be written as incoming; similarly for outgoing packets. When reading and then writing back packets, passing the same socket address supplied by .Xr recvfrom 2 unmodified to .Xr sendto 2 simplifies things (see below). .Pp The port part of the socket address passed to the .Xr sendto 2 contains a tag that should be meaningful to the diversion module. In the case of .Xr Ipfw 8 the tag is interpretted as the rule number .Em after which rule processing should restart. .Sh LOOP AVOIDANCE Packets written into a divert socket .Po using .Xr sendto 2 .Pc re-enter the packet filter at the rule number following the tag given in the port part of the socket address, which is usually already set at the rule number that caused the diversion (not the next rule if there are several at the same number). If the 'tag' is altered to indicate an alternative re-entry point, care should be taken to avoid loops, where the same packet is diverted more than once at the same rule. .Sh DETAILS To enable divert sockets, your kernel must be compiled with the option .Dv IPDIVERT . .Pp If a packet is diverted but no socket is bound to the port, or if .Dv IPDIVERT is not enabled in the kernel, the packet is dropped. .Pp Incoming packet fragments which get diverted are fully reassembled before delivery; the diversion of any one fragment causes the entire packet to get diverted. If different fragments divert to different ports, then which port ultimately gets chosen is unpredictable. .Pp Packets are received and sent unchanged, except that packets written as outgoing have their IP header checksums overwritten with the correct value. Packets written as incoming and having incorrect checksums will be dropped. Otherwise, all header fields are unchanged (and therefore in network order). .Pp Binding to port numbers less than 1024 requires super-user access, as does creating a socket of type SOCK_RAW. .Sh ERRORS Writing to a divert socket can return these errors, along with the usual errors possible when writing raw packets: .Bl -tag -width Er .It Bq Er EINVAL The packet had an invalid header, or the IP options in the packet and the socket options set were incompatible. .It Bq Er EADDRNOTAVAIL The destination address contained an IP address not equal to .Dv INADDR_ANY that was not associated with any interface. .El .Sh SEE ALSO .Xr bind 2 , .Xr recvfrom 2 , .Xr sendto 2 , .Xr socket 2 , .Xr ipfw 8 .Sh BUGS This is an attempt to provide a clean way for user mode processes to implement various IP tricks like address translation, but it could be cleaner, and it's too dependent on .Xr ipfw 8 . .Pp It's questionable whether incoming fragments should be reassembled before being diverted. For example, if only some fragments of a packet destined for another machine don't get routed through the local machine, the packet is lost. This should probably be a settable socket option in any case. .Sh AUTHORS -.An Archie Cobbs Aq archie@whistle.com , +.An Archie Cobbs Aq archie@freebsd.org , Whistle Communications Corp. Index: stable/4/share/man/man4/ipfirewall.4 =================================================================== --- stable/4/share/man/man4/ipfirewall.4 (revision 67508) +++ stable/4/share/man/man4/ipfirewall.4 (revision 67509) @@ -1,270 +1,270 @@ .\" .\" $FreeBSD$ .\" .Dd June 22, 1997 .Dt IPFIREWALL 4 .Os .Sh NAME .Nm ipfirewall .Nd IP packet filter and traffic accounting .Sh SYNOPSIS .Fd #include .Fd #include .Fd #include .Fd #include .Ft int .Fn setsockopt raw_socket IPPROTO_IP "ipfw option" "struct ipfw" size .Sh DESCRIPTION Ipfirewall (alias ipfw) is a system facility which allows filtering, redirecting, and other operations on IP packets travelling through system interfaces. Packets are matched by applying an ordered list of pattern rules against each packet until a match is found, at which point the corresponding action is taken. Rules are numbered from 1 to 65534; multiple rules may share the same number. .Pp There is one rule that always exists, rule number 65535. This rule normally causes all packets to be dropped. Hence, any packet which does not match a lower numbered rule will be dropped. However, a kernel compile time option .Dq IPFIREWALL_DEFAULT_TO_ACCEPT allows the administrator to change this fixed rule to permit everything. .Pp The value passed to .Fn setsockopt is a struct ip_fw describing the rule (see below). In some cases (such as .Dv IP_FW_DEL ) , only the rule number is significant. .Ss Commands The following socket options are used to manage the rule list: .Bl -tag -width "IP_FW_FLUSH" .It Dv IP_FW_ADD inserts the rule into the rule list .It Dv IP_FW_DEL deletes all rules having the matching rule number .It Dv IP_FW_GET returns the (first) rule having the matching rule number .It Dv IP_FW_ZERO zeros the statistics associated with all rules having the matching rule number. If the rule number is zero, all rules are zeroed. .It Dv IP_FW_FLUSH removes all rules (except 65535). .El .Pp When the kernel security level is greater than 2, only .Dv IP_FW_GET is allowed. .Ss Rule Structure Rules are described by the following structure: .Bd -literal /* Specify an interface */ union ip_fw_if { struct in_addr fu_via_ip; /* Specified by IP address */ struct { /* Specified by interface name */ #define FW_IFNLEN 6 /* To keep structure on 2^x boundary */ char name[FW_IFNLEN]; short unit; /* -1 means match any unit */ } fu_via_if; }; /* One ipfw rule */ struct ip_fw { u_long fw_pcnt,fw_bcnt; /* Packet and byte counters */ struct in_addr fw_src, fw_dst; /* Source and destination IP addr */ struct in_addr fw_smsk, fw_dmsk;/* Mask for src and dest IP addr */ u_short fw_number; /* Rule number */ u_short fw_flg; /* Flags word */ #define IP_FW_MAX_PORTS 10 /* A reasonable maximum */ u_short fw_pts[IP_FW_MAX_PORTS];/* Array of port numbers to match */ u_char fw_ipopt,fw_ipnopt; /* IP options set/unset */ u_char fw_tcpf,fw_tcpnf; /* TCP flags set/unset */ #define IP_FW_ICMPTYPES_DIM (256 / (sizeof(unsigned) * 8)) unsigned fw_icmptypes[IP_FW_ICMPTYPES_DIM]; /* ICMP types bitmap */ long timestamp; /* timestamp (tv_sec) of last match */ union ip_fw_if fw_in_if, fw_out_if;/* Incoming / outgoing interfaces */ union { u_short fu_divert_port; /* Divert/tee port */ u_short fu_skipto_rule; /* SKIPTO command rule number */ u_short fu_reject_code; /* REJECT response code */ } fw_un; u_char fw_prot; /* IP protocol */ u_char fw_nports; /* N'of src ports and # of dst ports */ /* in ports array (dst ports follow */ /* src ports; max of 10 ports in all */ /* count of 0 means match all ports) */ }; /* Encoding of number of source/dest ports from "fw_nports" */ #define IP_FW_GETNSRCP(rule) ((rule)->fw_nports & 0x0f) #define IP_FW_SETNSRCP(rule, n) do { \\ (rule)->fw_nports &= ~0x0f; \\ (rule)->fw_nports |= (n); \\ } while (0) #define IP_FW_GETNDSTP(rule) ((rule)->fw_nports >> 4) #define IP_FW_SETNDSTP(rule, n) do { \\ (rule)->fw_nports &= ~0xf0; \\ (rule)->fw_nports |= (n) << 4;\\ } while (0) /* Flags values for "flags" field */ #define IP_FW_F_IN 0x0001 /* Check inbound packets */ #define IP_FW_F_OUT 0x0002 /* Check outbound packets */ #define IP_FW_F_IIFACE 0x0004 /* Apply inbound interface test */ #define IP_FW_F_OIFACE 0x0008 /* Apply outbound interface test */ #define IP_FW_F_COMMAND 0x0070 /* Mask for type of chain entry: */ #define IP_FW_F_DENY 0x0000 /* This is a deny rule */ #define IP_FW_F_REJECT 0x0010 /* Deny and send a response packet */ #define IP_FW_F_ACCEPT 0x0020 /* This is an accept rule */ #define IP_FW_F_COUNT 0x0030 /* This is a count rule */ #define IP_FW_F_DIVERT 0x0040 /* This is a divert rule */ #define IP_FW_F_TEE 0x0050 /* This is a tee rule */ #define IP_FW_F_SKIPTO 0x0060 /* This is a skipto rule */ #define IP_FW_F_PRN 0x0080 /* Print if this rule matches */ #define IP_FW_F_SRNG 0x0100 /* The first two src ports are a min * * and max range (stored in host byte * * order). */ #define IP_FW_F_DRNG 0x0200 /* The first two dst ports are a min * * and max range (stored in host byte * * order). */ #define IP_FW_F_IIFNAME 0x0400 /* In interface by name/unit (not IP) */ #define IP_FW_F_OIFNAME 0x0800 /* Out interface by name/unit (not IP) */ #define IP_FW_F_INVSRC 0x1000 /* Invert sense of src check */ #define IP_FW_F_INVDST 0x2000 /* Invert sense of dst check */ #define IP_FW_F_FRAG 0x4000 /* Fragment */ #define IP_FW_F_ICMPBIT 0x8000 /* ICMP type bitmap is valid */ #define IP_FW_F_MASK 0xFFFF /* All possible flag bits mask */ .Ed .Ss Rule Actions Each rule has an action described by the IP_FW_F_COMMAND bits in the flags word: .Bl -tag -width "IP_FW_F_DIVERT" .It Dv IP_FW_F_DENY drop packet .It Dv IP_FW_F_REJECT drop packet; send rejection via ICMP or TCP .It Dv IP_FW_F_ACCEPT accept packet .It Dv IP_FW_F_COUNT increment counters; continue matching .It Dv IP_FW_F_DIVERT divert packet to a .Xr divert 4 socket .It Dv IP_FW_F_TEE copy packet to a .Xr divert 4 socket; continue .It Dv IP_FW_F_SKIPTO skip to rule number .Va fu_skipto_rule .El .Pp In the case of .Dv IP_FW_F_REJECT , if the .Va fu_reject_code is a number from 0 to 255, then an ICMP unreachable packet is sent back to the original packet's source IP address, with the corresponding code. Otherwise, the value must be 256 and the protocol .Dv IPPROTO_TCP , in which case a TCP reset packet is sent instead. .Pp With .Dv IP_FW_F_SKIPTO , all succeeding rules having rule number less than .Va fu_skipto_rule are skipped. .Ss Kernel Options Options in the kernel configuration file: .Bl -tag -width "optionsXIPFIREWALL_VERBOSE_LIMIT" .It Cd options IPFIREWALL enable .Nm .It Cd options IPFIREWALL_VERBOSE enable firewall output .It Cd options IPFIREWALL_VERBOSE_LIMIT limit firewall output .It Cd options IPDIVERT enable .Xr divert 4 sockets .El .Pp When packets match a rule with the .Dv IP_FW_F_PRN bit set, a message is logged to the console if .Dv IPFIREWALL_VERBOSE has been enabled; Dq IPFIREWALL_VERBOSE_LIMIT limits the maximum number of times each rule can cause a log message. These variables are also available via the .Xr sysctl 3 interface. .Sh RETURN VALUES The .Fn setsockopt function returns 0 on success. Otherwise, -1 is returned and the global variable .Va errno is set to indicate the error. .Sh ERRORS The .Fn setsockopt function will fail if: .Bl -tag -width Er .It Bq Er EINVAL The IP option field was improperly formed; an option field was shorter than the minimum value or longer than the option buffer provided. .It Bq Er EINVAL A structural error in ip_fw structure occurred (n_src_p+n_dst_p too big, ports set for ALL/ICMP protocols etc.). .It Bq Er EINVAL An invalid rule number was used. .El .Sh SEE ALSO .Xr setsockopt 2 , .Xr divert 4 , .Xr ip 4 , .Xr ipfw 8 , .Xr sysctl 8 . .Sh BUGS The ``tee'' rule is not yet implemented (currently it has no effect). .Pp This man page still needs work. .Sh HISTORY The ipfw facility was initially written as package to BSDI by .An Daniel Boulet .Aq danny@BouletFermat.ab.ca . It has been heavily modified and ported to .Fx by .Ar Ugen J.S.Antsilevich .Aq ugen@NetVision.net.il . .Pp Several enhancements added by .An Archie Cobbs -.Aq archie@whistle.com . +.Aq archie@freebsd.org . Index: stable/4/share/man/man4/ng_ether.4 =================================================================== --- stable/4/share/man/man4/ng_ether.4 (revision 67508) +++ stable/4/share/man/man4/ng_ether.4 (revision 67509) @@ -1,209 +1,209 @@ .\" Copyright (c) 2000 Whistle Communications, Inc. .\" All rights reserved. .\" .\" Subject to the following obligations and disclaimer of warranty, use and .\" redistribution of this software, in source or object code forms, with or .\" without modifications are expressly permitted by Whistle Communications; .\" provided, however, that: .\" 1. Any and all reproductions of the source or object code must include the .\" copyright notice above and the following disclaimer of warranties; and .\" 2. No rights are granted, in any manner or form, to use Whistle .\" Communications, Inc. trademarks, including the mark "WHISTLE .\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as .\" such appears in the above copyright notice or in the software. .\" .\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, .\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. .\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY .\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS .\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. .\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES .\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING .\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, .\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY .\" OF SUCH DAMAGE. .\" -.\" Author: Archie Cobbs +.\" Author: Archie Cobbs .\" .\" $FreeBSD$ .\" .Dd June 26, 2000 .Dt NG_ETHER 4 .Os FreeBSD .Sh NAME .Nm ng_ether .Nd Ethernet netgraph node type .Sh SYNOPSIS .Fd #include .Sh DESCRIPTION The .Nm ng_ether netgraph node type allows Ethernet interfaces to interact with the .Xr netgraph 4 networking subsystem. Once the .Nm module is loaded in the kernel, a node is automatically created for each Ethernet interface in the system. Each node will attempt to name itself with the same name as the associated interface. All .Nm nodes are persistent for as long as the interface itself exists. .Pp Three hooks are supported: .Dv lower , .Dv upper , and .Dv orphans . The hook name .Dv divert may be used as an alias for .Dv lower , and is provided for backward compatibility. In reality the two names represent the same hook. .Pp The .Dv lower hook is a connection to the raw Ethernet device. When connected, all incoming packets are diverted out this hook. Writing to this hook results in a raw Ethernet frame being transmitted by the device. Normal outgoing packets are not affected by .Dv lower being connected. .Pp The .Dv upper hook is a connection to the upper protocol layers. When connected, all outgoing packets are diverted out this hook. Writing to this hook results in a raw Ethernet frame being received by the kernel just as if it had come in over the wire. Normal incoming packets are not affected by .Dv upper being connected. .Pp The .Dv orphans hook is equivalent to .Dv lower , except that only unrecognized packets (that would otherwise be discarded) are written to the hook, and normal incoming traffic is unaffected. At most one of .Dv orphans and .Dv lower may be connected at any time. .Pp In all cases, frames are raw Ethernet frames with the standard 14 byte Ethernet header (but no checksum). .Pp When no hooks are connected, .Dv upper and .Dv lower are in effect connected together, so that packets flow normally upwards and downwards. .Sh HOOKS This node type supports the following hooks: .Pp .Bl -tag -width orphans .It Dv lower Connection to the lower device link layer. .It Dv upper Connection to the upper protocol layers. .It Dv orphans Like .Dv lower , but only receives unrecognized packets. .El .Sh CONTROL MESSAGES This node type supports the generic control messages, plus the following: .Bl -tag -width foo .It Dv NGM_ETHER_GET_IFNAME Returns the name of the associated interface as a NUL-terminated ASCII string. Normally this is the same as the name of the node. .It Dv NGM_ETHER_GET_IFINDEX Returns the global index of the associated interface as a 32 bit integer. .It Dv NGM_ETHER_GET_ENADDR Returns the device's unique six byte Ethernet address. .It Dv NGM_ETHER_SET_ENADDR Sets the device's unique six byte Ethernet address. This control message is equivalent to using the .Dv SIOCSIFLLADDR .Xr ioctl 2 system call. .It Dv NGM_ETHER_SET_PROMISC Enable or disable promiscuous mode. This message includes a single 32 bit integer flag that enables or disables promiscuous mode on the interface. .It Dv NGM_ETHER_GET_PROMISC Get the current value of the node's promiscuous flag. The returned value is always either one or zero. Note that this flag reflects the node's own promiscuous setting and does not necessarily reflect the promiscuous state of the actual interface, which can be affected by other means (e.g., .Xr bpf 4 ) . .It Dv NGM_ETHER_SET_AUTOSRC Sets the automatic source address override flag. This message includes a single 32 bit integer flag that causes all outgoing packets to have their source Ethernet address field overwritten with the device's unique Ethernet address. If this flag is set to zero, the source address in outgoing packets is not modified. The default setting for this flag is enabled. .It Dv NGM_ETHER_GET_AUTOSRC Get the current value of the node's source address override flag. The returned value is always either one or zero. .El .Sh SHUTDOWN This node is persistent for as long as the interface exists. Upon receipt of a .Dv NGM_SHUTDOWN control message, all hooks are disconnected, promiscuous mode is disabled, and the source address override flag is reenabled, but the node is not removed. If the interface itself is detached (e.g., because of PCCARD removal), the node disappears as well. .Sh EXAMPLE This command dumps all unrecognized packets received by the .Dv fxp0 interface to standard output decoded in hex and ASCII: .Bd -literal -offset indent nghook -a fxp0: orphans .Ed .Pp This command sends the contents of .Dv foo.pkt out the interface .Dv ed0 : .Bd -literal -offset indent cat foo.pkt | nghook fxp0: orphans .Ed .Pp These commands insert an .Xr ng_tee 4 node between the lower and upper protocol layers, which can be used for tracing packet flow, statistics, etc.: .Bd -literal -offset indent ngctl mkpeer fxp0: tee lower right ngctl connect fxp0: lower upper left .Ed .Sh SEE ALSO .Xr arp 4 , .Xr netgraph 4 , .Xr netintro 4 , .Xr ifconfig 8 , .Xr nghook 8 , .Xr ngctl 8 .Sh AUTHORS .An Julian Elischer Aq julian@FreeBSD.org .An Archie Cobbs Aq archie@FreeBSD.org