Index: head/share/man/man4/aout.4 =================================================================== --- head/share/man/man4/aout.4 (revision 275989) +++ head/share/man/man4/aout.4 (revision 275990) @@ -1,146 +1,146 @@ .\" Copyright (c) 2012 Konstantin Belousov .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 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 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd August 14, 2012 .Dt AOUT 4 .Os .Sh NAME .Nm aout .Nd kernel support for executing binary files in legacy a.out format .Sh SYNOPSIS .Bd -literal -offset indent kldload a.out .Ed .Sh DESCRIPTION The .Xr a.out 5 executable format was used before the release of .Fx 3.0 . Since i386 was the only supported architecture at that time, .Xr a.out 5 executables can only be activated on platforms that support execution of i386 code, such as i386 and amd64. .Pp To add kernel support for old syscalls and old syscall invocation methods, place the following options in the kernel configuration file: .Bd -ragged -offset indent .Cd "options COMPAT_43" .br .Cd "options COMPAT_FREEBSD32" .Ed .Pp The .Va COMPAT_FREEBSD32 option is only required on 64-bit CPU architectures. .Pp The .Va aout.ko module needs to be loaded with the .Xr kldload 8 utility in order to support the .Xr a.out 5 image activator: .Bd -ragged -offset indent .Ic kldload aout .Ed .Pp Alternatively, to load the module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent aout_load="YES" .Ed .Pp The .Xr a.out 5 format was mainstream quite a long time ago. Reasonable default settings and security requirements of modern operating systems today contradict the default environment of that time and require adjustments of the system to mimic natural environment for old binaries. .Pp The following .Xr sysctl 8 tunables are useful for this: .Bl -tag -offset indent -width "XXXXXXXXXXXXXXXXXXXXXXXXX" .It Xo Va security.bsd.map_at_zero .Xc Set to 1 to allow mapping of process pages at address 0. Some very old .Va ZMAGIC executable images require text mapping at address 0. .It Xo Va kern.pid_max .Xc Old versions of .Fx used signed 16-bit type for .Vt pid_t . Current kernels use 32-bit type for .Vt pid_t , and allow process id's up to 99999. Such values cannot be represented by old .Vt pid_t , mostly causing issues for processes using .Xr wait 2 syscalls, for example shells. Set the sysctl to 30000 to work around the problem. .It Xo Va kern.elf32.read_exec .Xc Set to 1 to force any accessible memory mapping performed by 32-bit process to allow execution, see .Xr mmap 2 . Old i386 CPUs did not have a bit in PTE which disallowed execution from the page, so many old programs did not specify .Va PROT_EXEC even for mapping of executable code. The sysctl forces .Va PROT_EXEC if mapping has any access allowed at all. The setting is only needed if the host architecture allows non-executable mappings. .El .Sh SEE ALSO .Xr execve 2 , .Xr a.out 5 , .Xr elf 5 , -.Xr sysctl 8 . +.Xr sysctl 8 .Sh HISTORY The .Xr a.out 5 executable format was used on ancient .At and served as the main executable format for .Fx from the beginning up to .Fx 2.2.9 . In .Fx 3.0 it was superseded by .Xr elf 5 . .Sh AUTHORS The .Nm manual page was written by .An Konstantin Belousov Aq Mt kib@FreeBSD.org . .Sh BUGS On 64bit architectures, not all wrappers for older syscalls are implemented. Index: head/share/man/man4/ath_ahb.4 =================================================================== --- head/share/man/man4/ath_ahb.4 (revision 275989) +++ head/share/man/man4/ath_ahb.4 (revision 275990) @@ -1,60 +1,60 @@ .\"- .\" Copyright (c) 2011 Adrian Chadd, Xenion Pty Ltd .\" All rights reserved. .\"" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer, .\" without modification. .\" 2. Redistributions in binary form must reproduce at minimum a disclaimer .\" similar to the "NO WARRANTY" disclaimer below ("Disclaimer") and any .\" redistribution must be conditioned upon including a substantially .\" similar Disclaimer requirement for further binary redistribution. .\" .\" NO WARRANTY .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT .\" LIMITED TO, THE IMPLIED WARRANTIES OF NONINFRINGEMENT, MERCHANTIBILITY .\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL .\" THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, .\" OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS .\" INTERRUPTION) HOWEVER CAUSED AND ON 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 ADVISED OF .\" THE POSSIBILITY OF SUCH DAMAGES. .\" .\" $FreeBSD$ .\"/ .Dd May 30, 2011 .Dt ATH_AHB 4 .Os .Sh NAME .Nm ath_ahb .Nd "Atheros AHB device glue" .Sh SYNOPSIS .Cd "device ath_ahb" .Sh DESCRIPTION This module provides the AHB bus glue needed for the devices supported by the .Xr ath 4 and .Xr ath_hal 4 drivers. .Pp This is only relevant for embedded System-on-Chip (SoC) devices such as the Atheros AR913x series, which include an Atheros wireless MAC on-die. .Sh SEE ALSO -.Xr ath 4 +.Xr ath 4 , .Xr ath_hal 4 .Sh HISTORY The .Nm module first appeared in .Fx 9.0 . .Sh BUGS See .Xr ath 4 for known bugs. Index: head/share/man/man4/ath_pci.4 =================================================================== --- head/share/man/man4/ath_pci.4 (revision 275989) +++ head/share/man/man4/ath_pci.4 (revision 275990) @@ -1,57 +1,57 @@ .\"- .\" Copyright (c) 2011 Adrian Chadd, Xenion Pty Ltd .\" All rights reserved. .\"" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer, .\" without modification. .\" 2. Redistributions in binary form must reproduce at minimum a disclaimer .\" similar to the "NO WARRANTY" disclaimer below ("Disclaimer") and any .\" redistribution must be conditioned upon including a substantially .\" similar Disclaimer requirement for further binary redistribution. .\" .\" NO WARRANTY .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT .\" LIMITED TO, THE IMPLIED WARRANTIES OF NONINFRINGEMENT, MERCHANTIBILITY .\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL .\" THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, .\" OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS .\" INTERRUPTION) HOWEVER CAUSED AND ON 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 ADVISED OF .\" THE POSSIBILITY OF SUCH DAMAGES. .\" .\" $FreeBSD$ .\"/ .Dd May 30, 2011 .Dt ATH_PCI 4 .Os .Sh NAME .Nm ath_pci .Nd "Atheros PCI device glue" .Sh SYNOPSIS .Cd "device ath_pci" .Sh DESCRIPTION This module provides the PCI/PCIe bus glue needed for the devices supported by the .Xr ath 4 and .Xr ath_hal 4 drivers. .Sh SEE ALSO -.Xr ath 4 +.Xr ath 4 , .Xr ath_hal 4 .Sh HISTORY The .Nm module first appeared in .Fx 9.0 . .Sh BUGS See .Xr ath 4 for known bugs. Index: head/share/man/man4/carp.4 =================================================================== --- head/share/man/man4/carp.4 (revision 275989) +++ head/share/man/man4/carp.4 (revision 275990) @@ -1,323 +1,323 @@ .\" $OpenBSD: carp.4,v 1.16 2004/12/07 23:41:35 jmc Exp $ .\" .\" Copyright (c) 2003, Ryan McBride. All rights reserved. .\" Copyright (c) 2011, Gleb Smirnoff .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON 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 ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd February 21, 2013 .Dt CARP 4 .Os .Sh NAME .Nm carp .Nd Common Address Redundancy Protocol .Sh SYNOPSIS .Cd "device carp" .Sh DESCRIPTION The CARP allows multiple hosts on the same local network to share a set of IPv4 and/or IPv6 addresses. Its primary purpose is to ensure that these addresses are always available. .Pp To use .Nm , the administrator needs to configure at a minimum a common virtual host ID (vhid), and attach at least one IP address to this vhid on each machine which is to take part in the virtual group. Additional parameters can also be set on a per-vhid basis: .Cm advbase and .Cm advskew , which are used to control how frequently the host sends advertisements when it is the master for a virtual host, and .Cm pass which is used to authenticate .Nm advertisements. The .Cm advbase parameter stands for .Dq "advertisement base" . It is measured in seconds and specifies the base of the advertisement interval. The .Cm advskew parameter stands for .Dq "advertisement skew" . It is measured in 1/256 of seconds. It is added to the base advertisement interval to make one host advertise a bit slower that the other does. Both .Cm advbase and .Cm advskew are put inside CARP advertisements. These values can be configured using .Xr ifconfig 8 , or through the .Dv SIOCSVH .Xr ioctl 2 . .Pp CARP virtual hosts can be configured on multicast-capable interfaces: Ethernet, layer 2 VLAN, FDDI and Token Ring. An arbitrary number of virtual host IDs can be configured on an interface. An arbitrary number of IPv4 or IPv6 addresses can be attached to a particular vhid. It is important that all hosts participating in a vhid have the same list of prefixes configured on the vhid, since all prefixes are included in the cryptographic checksum supplied in each advertisement. Multiple vhids running on one interface participate in master/backup elections independently. .Pp Additionally, there are a number of global parameters which can be set using .Xr sysctl 8 : .Bl -tag -width ".Va net.inet.carp.ifdown_demotion_factor" .It Va net.inet.carp.allow Accept incoming .Nm packets. Enabled by default. .It Va net.inet.carp.preempt Allow virtual hosts to preempt each other. When enabled, a vhid in a backup state would preempt a master that is announcing itself with a lower advskew. Disabled by default. .It Va net.inet.carp.log Determines what events relating to .Nm vhids are logged. A value of 0 disables any logging. A value of 1 enables logging state changes of .Nm vhids. Values above 1 enable logging of bad .Nm packets. The default value is 1. .It Va net.inet.carp.demotion This value shows current level of CARP demotion. The value is added to the actual advskew sent in announcements for all vhids. At normal system operation the demotion factor is zero. However, problematic conditions raise its level: when .Nm experiences problem with sending announcements, when an interface running a vhid goes down, or while the .Xr pfsync 4 interface is not synchronized. The demotion factor can be adjusted writing to the sysctl oid. The signed value supplied to the .Xr sysctl 8 command is added to current demotion factor. This allows to control .Nm behaviour depending on some external conditions, for example on the status of some daemon utility. .It Va net.inet.carp.ifdown_demotion_factor This value is added to .Va net.inet.carp.demotion when an interface running a vhid goes down. The default value is 240 (the maximum advskew value). .It Va net.inet.carp.senderr_demotion_factor This value is added to .Va net.inet.carp.demotion when .Nm experiences errors sending its announcements. The default value is 240 (the maximum advskew value). .El .\".Sh ARP level load balancing .\"A .\".Nm .\"interface has limited abilities for load balancing incoming connections .\"between hosts in an Ethernet network. .\"For load-balancing operation, one needs several CARP interfaces that .\"are configured to the same IP address, but to a different vhids. .\"Once an ARP request is received, the CARP protocol will use a hashing .\"function against the source IP address in the ARP request to determine .\"which vhid the request will be assigned to. .\"If the corresponding CARP interface is the current .\"master interface, a reply will .\"be sent to the ARP request; .\"otherwise it will be ignored. .\"See the .\".Sx EXAMPLES .\"section for a practical example of load balancing. .\".Pp .\"The ARP load balancing implemented in .\".Nm .\"has some limitations. .\"First, ARP balancing only works on the local network segment. .\"It cannot balance traffic that crosses a router, because the .\"router itself will always be balanced to the same virtual host. .\"Second, ARP load balancing can lead to asymmetric routing .\"of incoming and outgoing traffic, and thus combining it with .\".Xr pfsync 4 .\"is dangerous, because this creates a race condition between .\"balanced routers and a host they are serving. .\"Imagine an incoming packet creating state on the first router, being .\"forwarded to its destination, and the destination replying faster .\"than the state information is packed and synced with the second router. .\"If the reply would be load balanced to second router, it will be .\"dropped since the second router has not yet received information about .\"the connection state. .Sh STATE CHANGE NOTIFICATIONS Sometimes it is useful to get notified about .Nm status change events. This can be accomplished by using .Xr devd 8 hooks. Master/slave events are signalled under system .Dv CARP . The subsystem specifies the vhid and name of the interface where the master/slave event occurred. The type of the message displays the new state of the vhid. Please see .Xr devd.conf 5 and the .Sx EXAMPLES section for more information. .Sh EXAMPLES For firewalls and routers with multiple interfaces, it is desirable to failover all of the addresses running .Nm together, when one of the physical interfaces goes down. This is achieved by the use of the preempt option. Enable it on both hosts A and B: .Pp .Dl sysctl net.inet.carp.preempt=1 .Pp Assume that host A is the preferred master and we are running the 192.168.1.0/24 prefix on em0 and 192.168.2.0/24 on em1. This is the setup for host A (advskew is above 0 so it could be overwritten in the emergency situation from the other host): .Bd -literal -offset indent ifconfig em0 vhid 1 advskew 100 pass mekmitasdigoat 192.168.1.1/24 ifconfig em1 vhid 2 advskew 100 pass mekmitasdigoat 192.168.2.1/24 .Ed .Pp The setup for host B is identical, but it has a higher .Cm advskew : .Bd -literal -offset indent ifconfig em0 vhid 1 advskew 200 pass mekmitasdigoat 192.168.1.1/24 ifconfig em1 vhid 2 advskew 200 pass mekmitasdigoat 192.168.2.1/24 .Ed .Pp When one of the physical interfaces of host A fails, .Cm advskew is demoted to a configured value on all its .Nm vhids. Due to the preempt option, host B would start announcing itself, and thus preempt host A on both interfaces instead of just the failed one. .\".Pp .\"In order to set up an ARP balanced virtual host, it is necessary to configure .\"one virtual host for each physical host which would respond to ARP requests .\"and thus handle the traffic. .\"In the following example, two virtual hosts are configured on two hosts to .\"provide balancing and failover for the IP address 192.168.1.10. .\".Pp .\"First the .\".Nm .\"interfaces on host A are configured. .\"The .\".Cm advskew .\"of 100 on the second virtual host means that its advertisements will be sent .\"out slightly less frequently. .\".Bd -literal -offset indent .\"ifconfig carp0 create .\"ifconfig carp0 vhid 1 advskew 100 pass mekmitasdigoat 192.168.1.10/24 .\"ifconfig carp1 create .\"ifconfig carp1 vhid 2 advskew 200 pass mekmitasdigoat 192.168.1.10/24 .\".Ed .\".Pp .\"The configuration for host B is identical, except the .\".Cm advskew .\"is on virtual host 1 rather than virtual host 2. .\".Bd -literal -offset indent .\"ifconfig carp0 create .\"ifconfig carp0 vhid 1 advskew 200 pass mekmitasdigoat 192.168.1.10/24 .\"ifconfig carp1 create .\"ifconfig carp1 vhid 2 advskew 100 pass mekmitasdigoat 192.168.1.10/24 .\".Ed .\".Pp .\"Finally, the ARP balancing feature must be enabled on both hosts: .\".Pp .\".Dl sysctl net.inet.carp.arpbalance=1 .\".Pp .\"When the hosts receive an ARP request for 192.168.1.10, the source IP address .\"of the request is used to compute which virtual host should answer the request. .\"The host which is master of the selected virtual host will reply to the .\"request, the other(s) will ignore it. .\".Pp .\"This way, locally connected systems will receive different ARP replies and .\"subsequent IP traffic will be balanced among the hosts. .\"If one of the hosts fails, the other will take over the virtual MAC address, .\"and begin answering ARP requests on its behalf. .Pp Processing of .Nm status change events can be set up by using the following devd.conf rule: .Bd -literal -offset indent notify 0 { match "system" "CARP"; match "subsystem" "[0-9]+@[0-9a-z]+"; match "type" "(MASTER|BACKUP)"; action "/root/carpcontrol.sh $subsystem $type"; }; .Ed .Pp To see .Nm packets decoded in .Xr tcpdump 8 output, one needs to specify .Fl T Ar carp option, otherwise .Xr tcpdump 8 tries to interpret them as VRRP packets: .Bd -literal -offset indent tcpdump -npi vlan0 -T carp .Ed .Sh SEE ALSO .Xr inet 4 , .Xr pfsync 4 , .Xr rc.conf 5 , .Xr devd.conf 5 , .Xr ifconfig 8 , -.Xr sysctl 8 +.Xr sysctl 8 , .Xr tcpdump 8 .Sh HISTORY The .Nm device first appeared in .Ox 3.5 . The .Nm device was imported into .Fx 5.4 . In .Fx 10.0 , .Nm was significantly rewritten, and is no longer a pseudo-interface. Index: head/share/man/man4/crypto.4 =================================================================== --- head/share/man/man4/crypto.4 (revision 275989) +++ head/share/man/man4/crypto.4 (revision 275990) @@ -1,434 +1,433 @@ .\" $NetBSD: crypto.4,v 1.24 2014/01/27 21:23:59 pgoyette Exp $ .\" .\" Copyright (c) 2008 The NetBSD Foundation, Inc. .\" Copyright (c) 2014 The FreeBSD Foundation .\" All rights reserved. .\" .\" Portions of this documentation were written by John-Mark Gurney .\" under sponsorship of the FreeBSD Foundation and .\" Rubicon Communications, LLC (Netgate). .\" .\" This code is derived from software contributed to The NetBSD Foundation .\" by Coyote Point Systems, Inc. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS .\" INTERRUPTION) HOWEVER CAUSED AND ON 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 ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" .\" .\" .\" Copyright (c) 2004 .\" Jonathan Stone . All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY Jonathan Stone AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL Jonathan Stone OR THE VOICES IN HIS HEAD .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS .\" INTERRUPTION) HOWEVER CAUSED AND ON 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 ADVISED OF .\" THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd December 12, 2014 .Dt CRYPTO 4 .Os .Sh NAME .Nm crypto , .Nm cryptodev .Nd user-mode access to hardware-accelerated cryptography .Sh SYNOPSIS .Cd device crypto .Cd device cryptodev .Pp .In sys/ioctl.h .In sys/time.h .In crypto/cryptodev.h .Sh DESCRIPTION The .Nm driver gives user-mode applications access to hardware-accelerated cryptographic transforms, as implemented by the .Xr opencrypto 9 in-kernel interface. .Pp The .Pa /dev/crypto special device provides an .Xr ioctl 2 based interface. User-mode applications should open the special device, then issue .Xr ioctl 2 calls on the descriptor. User-mode access to .Pa /dev/crypto is controlled by three .Xr sysctl 8 variables, .Ic kern.userasymcrypto and .Ic kern.cryptodevallowsoft . See .Xr sysctl 7 for additional details. .Pp The .Nm device provides two distinct modes of operation: one mode for symmetric-keyed cryptographic requests, and a second mode for both asymmetric-key (public-key/private-key) requests, and for modular arithmetic (for Diffie-Hellman key exchange and other cryptographic protocols). The two modes are described separately below. .Sh THEORY OF OPERATION Regardless of whether symmetric-key or asymmetric-key operations are to be performed, use of the device requires a basic series of steps: -.Pp .Bl -enum .It Open a file descriptor for the device. See .Xr open 2 . .It If any symmetric operation will be performed, create one session, with .Dv CIOCGSESSION . Most applications will require at least one symmetric session. Since cipher and MAC keys are tied to sessions, many applications will require more. Asymmetric operations do not use sessions. .It Submit requests, synchronously with .Dv CIOCCRYPT (symmetric) or .Dv CIOCKEY (asymmetric). .It Destroy one session with .Dv CIOCFSESSION . .It Close the device with .Xr close 2 . .El .Sh SYMMETRIC-KEY OPERATION The symmetric-key operation mode provides a context-based API to traditional symmetric-key encryption (or privacy) algorithms, or to keyed and unkeyed one-way hash (HMAC and MAC) algorithms. The symmetric-key mode also permits fused operation, where the hardware performs both a privacy algorithm and an integrity-check algorithm in a single pass over the data: either a fused encrypt/HMAC-generate operation, or a fused HMAC-verify/decrypt operation. .Pp To use symmetric mode, you must first create a session specifying the algorithm(s) and key(s) to use; then issue encrypt or decrypt requests against the session. .Ss Algorithms For a list of supported algorithms, see .Xr crypto 7 and .Xr crypto 9 . .Ss IOCTL Request Descriptions .\" .Bl -tag -width CIOCGSESSION .\" .It Dv CRIOGET Fa int *fd Clone the fd argument to .Xr ioctl 2 , yielding a new file descriptor for the creation of sessions. .\" .It Dv CIOCFINDDEV Fa struct crypt_find_op *fop .Bd -literal struct crypt_find_op { int crid; /* driver id + flags */ char name[32]; /* device/driver name */ }; .Ed If .Fa crid is -1, then find the driver named .Fa name and return the id in .Fa crid . If .Fa crid is not -1, return the name of the driver with .Fa crid in .Fa name . In either case, if the driver is not found, .Dv ENOENT is returned. .It Dv CIOCGSESSION Fa struct session_op *sessp .Bd -literal struct session_op { u_int32_t cipher; /* e.g. CRYPTO_DES_CBC */ u_int32_t mac; /* e.g. CRYPTO_MD5_HMAC */ u_int32_t keylen; /* cipher key */ void * key; int mackeylen; /* mac key */ void * mackey; u_int32_t ses; /* returns: ses # */ }; .Ed Create a new cryptographic session on a file descriptor for the device; that is, a persistent object specific to the chosen privacy algorithm, integrity algorithm, and keys specified in .Fa sessp . The special value 0 for either privacy or integrity is reserved to indicate that the indicated operation (privacy or integrity) is not desired for this session. .Pp Multiple sessions may be bound to a single file descriptor. The session ID returned in .Fa sessp-\*[Gt]ses is supplied as a required field in the symmetric-operation structure .Fa crypt_op for future encryption or hashing requests. .\" .Pp .\" This implementation will never return a session ID of 0 for a successful .\" creation of a session, which is a .\" .Nx .\" extension. .Pp For non-zero symmetric-key privacy algorithms, the privacy algorithm must be specified in .Fa sessp-\*[Gt]cipher , the key length in .Fa sessp-\*[Gt]keylen , and the key value in the octets addressed by .Fa sessp-\*[Gt]key . .Pp For keyed one-way hash algorithms, the one-way hash must be specified in .Fa sessp-\*[Gt]mac , the key length in .Fa sessp-\*[Gt]mackey , and the key value in the octets addressed by .Fa sessp-\*[Gt]mackeylen . .\" .Pp Support for a specific combination of fused privacy and integrity-check algorithms depends on whether the underlying hardware supports that combination. Not all combinations are supported by all hardware, even if the hardware supports each operation as a stand-alone non-fused operation. .It Dv CIOCCRYPT Fa struct crypt_op *cr_op .Bd -literal struct crypt_op { u_int32_t ses; u_int16_t op; /* e.g. COP_ENCRYPT */ u_int16_t flags; u_int len; caddr_t src, dst; caddr_t mac; /* must be large enough for result */ caddr_t iv; }; .Ed Request a symmetric-key (or hash) operation. The file descriptor argument to .Xr ioctl 2 must have been bound to a valid session. To encrypt, set .Fa cr_op-\*[Gt]op to .Dv COP_ENCRYPT . To decrypt, set .Fa cr_op-\*[Gt]op to .Dv COP_DECRYPT . The field .Fa cr_op-\*[Gt]len supplies the length of the input buffer; the fields .Fa cr_op-\*[Gt]src , .Fa cr_op-\*[Gt]dst , .Fa cr_op-\*[Gt]mac , .Fa cr_op-\*[Gt]iv supply the addresses of the input buffer, output buffer, one-way hash, and initialization vector, respectively. .It Dv CIOCCRYPTAEAD Fa struct crypt_aead *cr_aead .Bd -literal struct crypt_aead { u_int32_t ses; u_int16_t op; /* e.g. COP_ENCRYPT */ u_int16_t flags; u_int len; u_int aadlen; u_int ivlen; caddr_t src, dst; caddr_t aad; caddr_t tag; /* must be large enough for result */ caddr_t iv; }; .Ed The .Dv CIOCCRYPTAEAD is similar to the .Dv CIOCCRYPT but provides additional data in .Fa cr_aead-\*[Gt]aad to include in the authentication mode. .It Dv CIOCFSESSION Fa u_int32_t ses_id Destroys the /dev/crypto session associated with the file-descriptor argument. .It Dv CIOCNFSESSION Fa struct crypt_sfop *sfop ; .Bd -literal struct crypt_sfop { size_t count; u_int32_t *sesid; }; .Ed Destroys the .Fa sfop-\*[Gt]count sessions specified by the .Fa sfop array of session identifiers. .El .\" .Sh ASYMMETRIC-KEY OPERATION .Ss Asymmetric-key algorithms Contingent upon hardware support, the following asymmetric (public-key/private-key; or key-exchange subroutine) operations may also be available: .Pp .Bl -column "CRK_DH_COMPUTE_KEY" "Input parameter" "Output parameter" -offset indent -compact .It Em "Algorithm" Ta "Input parameter" Ta "Output parameter" .It Em " " Ta "Count" Ta "Count" .It Dv CRK_MOD_EXP Ta 3 Ta 1 .It Dv CRK_MOD_EXP_CRT Ta 6 Ta 1 .It Dv CRK_DSA_SIGN Ta 5 Ta 2 .It Dv CRK_DSA_VERIFY Ta 7 Ta 0 .It Dv CRK_DH_COMPUTE_KEY Ta 3 Ta 1 .El .Pp See below for discussion of the input and output parameter counts. .Ss Asymmetric-key commands .Bl -tag -width CIOCKEY .It Dv CIOCASYMFEAT Fa int *feature_mask Returns a bitmask of supported asymmetric-key operations. Each of the above-listed asymmetric operations is present if and only if the bit position numbered by the code for that operation is set. For example, .Dv CRK_MOD_EXP is available if and only if the bit .Pq 1 \*[Lt]\*[Lt] Dv CRK_MOD_EXP is set. .It Dv CIOCKEY Fa struct crypt_kop *kop .Bd -literal struct crypt_kop { u_int crk_op; /* e.g. CRK_MOD_EXP */ u_int crk_status; /* return status */ u_short crk_iparams; /* # of input params */ u_short crk_oparams; /* # of output params */ u_int crk_pad1; struct crparam crk_param[CRK_MAXPARAM]; }; /* Bignum parameter, in packed bytes. */ struct crparam { void * crp_p; u_int crp_nbits; }; .Ed Performs an asymmetric-key operation from the list above. The specific operation is supplied in .Fa kop-\*[Gt]crk_op ; final status for the operation is returned in .Fa kop-\*[Gt]crk_status . The number of input arguments and the number of output arguments is specified in .Fa kop-\*[Gt]crk_iparams and .Fa kop-\*[Gt]crk_iparams , respectively. The field .Fa crk_param[] must be filled in with exactly .Fa kop-\*[Gt]crk_iparams + kop-\*[Gt]crk_oparams arguments, each encoded as a .Fa struct crparam (address, bitlength) pair. .Pp The semantics of these arguments are currently undocumented. .El .Sh SEE ALSO .Xr aesni 4 , .Xr hifn 4 , .Xr ipsec 4 , .Xr padlock 4 , .Xr safe 4 , .Xr ubsec 4 , .Xr crypto 7 , .Xr geli 8 , .Xr crypto 9 .Sh HISTORY The .Nm driver first appeared in .Ox 3.0 . The .Nm driver was imported to .Fx 5.0 . .Sh BUGS Error checking and reporting is weak. .Pp The values specified for symmetric-key key sizes to .Dv CIOCGSESSION must exactly match the values expected by .Xr opencrypto 9 . The output buffer and MAC buffers supplied to .Dv CIOCCRYPT must follow whether privacy or integrity algorithms were specified for session: if you request a .No non- Ns Dv NULL algorithm, you must supply a suitably-sized buffer. .Pp The scheme for passing arguments for asymmetric requests is baroque. .Pp The naming inconsistency between .Dv CRIOGET and the various .Dv CIOC Ns \&* names is an unfortunate historical artifact. Index: head/share/man/man4/ip.4 =================================================================== --- head/share/man/man4/ip.4 (revision 275989) +++ head/share/man/man4/ip.4 (revision 275990) @@ -1,903 +1,903 @@ .\" Copyright (c) 1983, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON 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 ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)ip.4 8.2 (Berkeley) 11/30/93 .\" $FreeBSD$ .\" .Dd September 1, 2014 .Dt IP 4 .Os .Sh NAME .Nm ip .Nd Internet Protocol .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .In netinet/in.h .Ft int .Fn socket AF_INET SOCK_RAW proto .Sh DESCRIPTION .Tn IP is the transport layer protocol used by the Internet protocol family. Options may be set at the .Tn IP level when using higher-level protocols that are based on .Tn IP (such as .Tn TCP and .Tn UDP ) . It may also be accessed through a .Dq raw socket when developing new protocols, or special-purpose applications. .Pp There are several .Tn IP-level .Xr setsockopt 2 and .Xr getsockopt 2 options. .Dv IP_OPTIONS may be used to provide .Tn IP options to be transmitted in the .Tn IP header of each outgoing packet or to examine the header options on incoming packets. .Tn IP options may be used with any socket type in the Internet family. The format of .Tn IP options to be sent is that specified by the .Tn IP protocol specification (RFC-791), with one exception: the list of addresses for Source Route options must include the first-hop gateway at the beginning of the list of gateways. The first-hop gateway address will be extracted from the option list and the size adjusted accordingly before use. To disable previously specified options, use a zero-length buffer: .Bd -literal setsockopt(s, IPPROTO_IP, IP_OPTIONS, NULL, 0); .Ed .Pp .Dv IP_TOS and .Dv IP_TTL may be used to set the type-of-service and time-to-live fields in the .Tn IP header for .Dv SOCK_STREAM , SOCK_DGRAM , and certain types of .Dv SOCK_RAW sockets. For example, .Bd -literal int tos = IPTOS_LOWDELAY; /* see */ setsockopt(s, IPPROTO_IP, IP_TOS, &tos, sizeof(tos)); int ttl = 60; /* max = 255 */ setsockopt(s, IPPROTO_IP, IP_TTL, &ttl, sizeof(ttl)); .Ed .Pp .Dv IP_MINTTL may be used to set the minimum acceptable TTL a packet must have when received on a socket. All packets with a lower TTL are silently dropped. This option is only really useful when set to 255, preventing packets from outside the directly connected networks reaching local listeners on sockets. .Pp .Dv IP_DONTFRAG may be used to set the Don't Fragment flag on IP packets. Currently this option is respected only on .Xr udp 4 and raw .Xr ip 4 sockets, unless the .Dv IP_HDRINCL option has been set. On .Xr tcp 4 sockets, the Don't Fragment flag is controlled by the Path MTU Discovery option. Sending a packet larger than the MTU size of the egress interface, determined by the destination address, returns an .Er EMSGSIZE error. .Pp If the .Dv IP_RECVDSTADDR option is enabled on a .Dv SOCK_DGRAM socket, the .Xr recvmsg 2 call will return the destination .Tn IP address for a .Tn UDP datagram. The .Vt msg_control field in the .Vt msghdr structure points to a buffer that contains a .Vt cmsghdr structure followed by the .Tn IP address. The .Vt cmsghdr fields have the following values: .Bd -literal cmsg_len = CMSG_LEN(sizeof(struct in_addr)) cmsg_level = IPPROTO_IP cmsg_type = IP_RECVDSTADDR .Ed .Pp The source address to be used for outgoing .Tn UDP datagrams on a socket can be specified as ancillary data with a type code of .Dv IP_SENDSRCADDR . The msg_control field in the msghdr structure should point to a buffer that contains a .Vt cmsghdr structure followed by the .Tn IP address. The cmsghdr fields should have the following values: .Bd -literal cmsg_len = CMSG_LEN(sizeof(struct in_addr)) cmsg_level = IPPROTO_IP cmsg_type = IP_SENDSRCADDR .Ed .Pp The socket should be either bound to .Dv INADDR_ANY and a local port, and the address supplied with .Dv IP_SENDSRCADDR should't be .Dv INADDR_ANY , or the socket should be bound to a local address and the address supplied with .Dv IP_SENDSRCADDR should be .Dv INADDR_ANY . In the latter case bound address is overriden via generic source address selection logic, which would choose IP address of interface closest to destination. .Pp For convenience, .Dv IP_SENDSRCADDR is defined to have the same value as .Dv IP_RECVDSTADDR , so the .Dv IP_RECVDSTADDR control message from .Xr recvmsg 2 can be used directly as a control message for .Xr sendmsg 2 . .\" .Pp If the .Dv IP_ONESBCAST option is enabled on a .Dv SOCK_DGRAM or a .Dv SOCK_RAW socket, the destination address of outgoing broadcast datagrams on that socket will be forced to the undirected broadcast address, .Dv INADDR_BROADCAST , before transmission. This is in contrast to the default behavior of the system, which is to transmit undirected broadcasts via the first network interface with the .Dv IFF_BROADCAST flag set. .Pp This option allows applications to choose which interface is used to transmit an undirected broadcast datagram. For example, the following code would force an undirected broadcast to be transmitted via the interface configured with the broadcast address 192.168.2.255: .Bd -literal char msg[512]; struct sockaddr_in sin; int onesbcast = 1; /* 0 = disable (default), 1 = enable */ setsockopt(s, IPPROTO_IP, IP_ONESBCAST, &onesbcast, sizeof(onesbcast)); sin.sin_addr.s_addr = inet_addr("192.168.2.255"); sin.sin_port = htons(1234); sendto(s, msg, sizeof(msg), 0, &sin, sizeof(sin)); .Ed .Pp It is the application's responsibility to set the .Dv IP_TTL option to an appropriate value in order to prevent broadcast storms. The application must have sufficient credentials to set the .Dv SO_BROADCAST socket level option, otherwise the .Dv IP_ONESBCAST option has no effect. .Pp If the .Dv IP_BINDANY option is enabled on a .Dv SOCK_STREAM , .Dv SOCK_DGRAM or a .Dv SOCK_RAW socket, one can .Xr bind 2 to any address, even one not bound to any available network interface in the system. This functionality (in conjunction with special firewall rules) can be used for implementing a transparent proxy. The .Dv PRIV_NETINET_BINDANY privilege is needed to set this option. .Pp If the .Dv IP_RECVTTL option is enabled on a .Dv SOCK_DGRAM socket, the .Xr recvmsg 2 call will return the .Tn IP .Tn TTL (time to live) field for a .Tn UDP datagram. The msg_control field in the msghdr structure points to a buffer that contains a cmsghdr structure followed by the .Tn TTL . The cmsghdr fields have the following values: .Bd -literal cmsg_len = CMSG_LEN(sizeof(u_char)) cmsg_level = IPPROTO_IP cmsg_type = IP_RECVTTL .Ed .\" .Pp If the .Dv IP_RECVTOS option is enabled on a .Dv SOCK_DGRAM socket, the .Xr recvmsg 2 call will return the .Tn IP .Tn TOS (type of service) field for a .Tn UDP datagram. The msg_control field in the msghdr structure points to a buffer that contains a cmsghdr structure followed by the .Tn TOS . The cmsghdr fields have the following values: .Bd -literal cmsg_len = CMSG_LEN(sizeof(u_char)) cmsg_level = IPPROTO_IP cmsg_type = IP_RECVTOS .Ed .\" .Pp If the .Dv IP_RECVIF option is enabled on a .Dv SOCK_DGRAM socket, the .Xr recvmsg 2 call returns a .Vt "struct sockaddr_dl" corresponding to the interface on which the packet was received. The .Va msg_control field in the .Vt msghdr structure points to a buffer that contains a .Vt cmsghdr structure followed by the .Vt "struct sockaddr_dl" . The .Vt cmsghdr fields have the following values: .Bd -literal cmsg_len = CMSG_LEN(sizeof(struct sockaddr_dl)) cmsg_level = IPPROTO_IP cmsg_type = IP_RECVIF .Ed .Pp .Dv IP_PORTRANGE may be used to set the port range used for selecting a local port number on a socket with an unspecified (zero) port number. It has the following possible values: .Bl -tag -width IP_PORTRANGE_DEFAULT .It Dv IP_PORTRANGE_DEFAULT use the default range of values, normally .Dv IPPORT_HIFIRSTAUTO through .Dv IPPORT_HILASTAUTO . This is adjustable through the sysctl setting: .Va net.inet.ip.portrange.first and .Va net.inet.ip.portrange.last . .It Dv IP_PORTRANGE_HIGH use a high range of values, normally .Dv IPPORT_HIFIRSTAUTO and .Dv IPPORT_HILASTAUTO . This is adjustable through the sysctl setting: .Va net.inet.ip.portrange.hifirst and .Va net.inet.ip.portrange.hilast . .It Dv IP_PORTRANGE_LOW use a low range of ports, which are normally restricted to privileged processes on .Ux systems. The range is normally from .Dv IPPORT_RESERVED \- 1 down to .Li IPPORT_RESERVEDSTART in descending order. This is adjustable through the sysctl setting: .Va net.inet.ip.portrange.lowfirst and .Va net.inet.ip.portrange.lowlast . .El .Pp The range of privileged ports which only may be opened by root-owned processes may be modified by the .Va net.inet.ip.portrange.reservedlow and .Va net.inet.ip.portrange.reservedhigh sysctl settings. The values default to the traditional range, 0 through .Dv IPPORT_RESERVED \- 1 (0 through 1023), respectively. Note that these settings do not affect and are not accounted for in the use or calculation of the other .Va net.inet.ip.portrange values above. Changing these values departs from .Ux tradition and has security consequences that the administrator should carefully evaluate before modifying these settings. .Pp Ports are allocated at random within the specified port range in order to increase the difficulty of random spoofing attacks. In scenarios such as benchmarking, this behavior may be undesirable. In these cases, .Va net.inet.ip.portrange.randomized can be used to toggle randomization off. If more than .Va net.inet.ip.portrange.randomcps ports have been allocated in the last second, then return to sequential port allocation. Return to random allocation only once the current port allocation rate drops below .Va net.inet.ip.portrange.randomcps for at least .Va net.inet.ip.portrange.randomtime seconds. The default values for .Va net.inet.ip.portrange.randomcps and .Va net.inet.ip.portrange.randomtime are 10 port allocations per second and 45 seconds correspondingly. .Ss "Multicast Options" .Tn IP multicasting is supported only on .Dv AF_INET sockets of type .Dv SOCK_DGRAM and .Dv SOCK_RAW , and only on networks where the interface driver supports multicasting. .Pp The .Dv IP_MULTICAST_TTL option changes the time-to-live (TTL) for outgoing multicast datagrams in order to control the scope of the multicasts: .Bd -literal u_char ttl; /* range: 0 to 255, default = 1 */ setsockopt(s, IPPROTO_IP, IP_MULTICAST_TTL, &ttl, sizeof(ttl)); .Ed .Pp Datagrams with a TTL of 1 are not forwarded beyond the local network. Multicast datagrams with a TTL of 0 will not be transmitted on any network, but may be delivered locally if the sending host belongs to the destination group and if multicast loopback has not been disabled on the sending socket (see below). Multicast datagrams with TTL greater than 1 may be forwarded to other networks if a multicast router is attached to the local network. .Pp For hosts with multiple interfaces, where an interface has not been specified for a multicast group membership, each multicast transmission is sent from the primary network interface. The .Dv IP_MULTICAST_IF option overrides the default for subsequent transmissions from a given socket: .Bd -literal struct in_addr addr; setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, &addr, sizeof(addr)); .Ed .Pp where "addr" is the local .Tn IP address of the desired interface or .Dv INADDR_ANY to specify the default interface. .Pp To specify an interface by index, an instance of .Vt ip_mreqn may be passed instead. The .Vt imr_ifindex member should be set to the index of the desired interface, or 0 to specify the default interface. The kernel differentiates between these two structures by their size. .Pp The use of .Vt IP_MULTICAST_IF is .Em not recommended , as multicast memberships are scoped to each individual interface. It is supported for legacy use only by applications, such as routing daemons, which expect to be able to transmit link-local IPv4 multicast datagrams (224.0.0.0/24) on multiple interfaces, without requesting an individual membership for each interface. .Pp .\" An interface's local IP address and multicast capability can be obtained via the .Dv SIOCGIFCONF and .Dv SIOCGIFFLAGS ioctls. Normal applications should not need to use this option. .Pp If a multicast datagram is sent to a group to which the sending host itself belongs (on the outgoing interface), a copy of the datagram is, by default, looped back by the IP layer for local delivery. The .Dv IP_MULTICAST_LOOP option gives the sender explicit control over whether or not subsequent datagrams are looped back: .Bd -literal u_char loop; /* 0 = disable, 1 = enable (default) */ setsockopt(s, IPPROTO_IP, IP_MULTICAST_LOOP, &loop, sizeof(loop)); .Ed .Pp This option improves performance for applications that may have no more than one instance on a single host (such as a routing daemon), by eliminating the overhead of receiving their own transmissions. It should generally not be used by applications for which there may be more than one instance on a single host (such as a conferencing program) or for which the sender does not belong to the destination group (such as a time querying program). .Pp The sysctl setting .Va net.inet.ip.mcast.loop controls the default setting of the .Dv IP_MULTICAST_LOOP socket option for new sockets. .Pp A multicast datagram sent with an initial TTL greater than 1 may be delivered to the sending host on a different interface from that on which it was sent, if the host belongs to the destination group on that other interface. The loopback control option has no effect on such delivery. .Pp A host must become a member of a multicast group before it can receive datagrams sent to the group. To join a multicast group, use the .Dv IP_ADD_MEMBERSHIP option: .Bd -literal struct ip_mreq mreq; setsockopt(s, IPPROTO_IP, IP_ADD_MEMBERSHIP, &mreq, sizeof(mreq)); .Ed .Pp where .Fa mreq is the following structure: .Bd -literal struct ip_mreq { struct in_addr imr_multiaddr; /* IP multicast address of group */ struct in_addr imr_interface; /* local IP address of interface */ } .Ed .Pp .Va imr_interface should be set to the .Tn IP address of a particular multicast-capable interface if the host is multihomed. It may be set to .Dv INADDR_ANY to choose the default interface, although this is not recommended; this is considered to be the first interface corresponding to the default route. Otherwise, the first multicast-capable interface configured in the system will be used. .Pp Prior to .Fx 7.0 , if the .Va imr_interface member is within the network range .Li 0.0.0.0/8 , it is treated as an interface index in the system interface MIB, as per the RIP Version 2 MIB Extension (RFC-1724). In versions of .Fx since 7.0, this behavior is no longer supported. Developers should instead use the RFC 3678 multicast source filter APIs; in particular, .Dv MCAST_JOIN_GROUP . .Pp Up to .Dv IP_MAX_MEMBERSHIPS memberships may be added on a single socket. Membership is associated with a single interface; programs running on multihomed hosts may need to join the same group on more than one interface. .Pp To drop a membership, use: .Bd -literal struct ip_mreq mreq; setsockopt(s, IPPROTO_IP, IP_DROP_MEMBERSHIP, &mreq, sizeof(mreq)); .Ed .Pp where .Fa mreq contains the same values as used to add the membership. Memberships are dropped when the socket is closed or the process exits. .\" TODO: Update this piece when IPv4 source-address selection is implemented. .Pp The IGMP protocol uses the primary IP address of the interface as its identifier for group membership. This is the first IP address configured on the interface. If this address is removed or changed, the results are undefined, as the IGMP membership state will then be inconsistent. If multiple IP aliases are configured on the same interface, they will be ignored. .Pp This shortcoming was addressed in IPv6; MLDv2 requires that the unique link-local address for an interface is used to identify an MLDv2 listener. .Ss "Source-Specific Multicast Options" Since .Fx 8.0 , the use of Source-Specific Multicast (SSM) is supported. These extensions require an IGMPv3 multicast router in order to make best use of them. If a legacy multicast router is present on the link, .Fx will simply downgrade to the version of IGMP spoken by the router, and the benefits of source filtering on the upstream link will not be present, although the kernel will continue to squelch transmissions from blocked sources. .Pp Each group membership on a socket now has a filter mode: .Bl -tag -width MCAST_EXCLUDE .It Dv MCAST_EXCLUDE Datagrams sent to this group are accepted, unless the source is in a list of blocked source addresses. .It Dv MCAST_INCLUDE Datagrams sent to this group are accepted only if the source is in a list of accepted source addresses. .El .Pp Groups joined using the legacy .Dv IP_ADD_MEMBERSHIP option are placed in exclusive-mode, and are able to request that certain sources are blocked or allowed. This is known as the .Em delta-based API . .Pp To block a multicast source on an existing group membership: .Bd -literal struct ip_mreq_source mreqs; setsockopt(s, IPPROTO_IP, IP_BLOCK_SOURCE, &mreqs, sizeof(mreqs)); .Ed .Pp where .Fa mreqs is the following structure: .Bd -literal struct ip_mreq_source { struct in_addr imr_multiaddr; /* IP multicast address of group */ struct in_addr imr_sourceaddr; /* IP address of source */ struct in_addr imr_interface; /* local IP address of interface */ } .Ed .Va imr_sourceaddr should be set to the address of the source to be blocked. .Pp To unblock a multicast source on an existing group: .Bd -literal struct ip_mreq_source mreqs; setsockopt(s, IPPROTO_IP, IP_UNBLOCK_SOURCE, &mreqs, sizeof(mreqs)); .Ed .Pp The .Dv IP_BLOCK_SOURCE and .Dv IP_UNBLOCK_SOURCE options are .Em not permitted for inclusive-mode group memberships. .Pp To join a multicast group in .Dv MCAST_INCLUDE mode with a single source, or add another source to an existing inclusive-mode membership: .Bd -literal struct ip_mreq_source mreqs; setsockopt(s, IPPROTO_IP, IP_ADD_SOURCE_MEMBERSHIP, &mreqs, sizeof(mreqs)); .Ed .Pp To leave a single source from an existing group in inclusive mode: .Bd -literal struct ip_mreq_source mreqs; setsockopt(s, IPPROTO_IP, IP_DROP_SOURCE_MEMBERSHIP, &mreqs, sizeof(mreqs)); .Ed If this is the last accepted source for the group, the membership will be dropped. .Pp The .Dv IP_ADD_SOURCE_MEMBERSHIP and .Dv IP_DROP_SOURCE_MEMBERSHIP options are .Em not accepted for exclusive-mode group memberships. However, both exclusive and inclusive mode memberships support the use of the .Em full-state API documented in RFC 3678. For management of source filter lists using this API, please refer to .Xr sourcefilter 3 . .Pp The sysctl settings .Va net.inet.ip.mcast.maxsocksrc and .Va net.inet.ip.mcast.maxgrpsrc are used to specify an upper limit on the number of per-socket and per-group source filter entries which the kernel may allocate. .\"----------------------- .Ss "Raw IP Sockets" Raw .Tn IP sockets are connectionless, and are normally used with the .Xr sendto 2 and .Xr recvfrom 2 calls, though the .Xr connect 2 call may also be used to fix the destination for future packets (in which case the .Xr read 2 or .Xr recv 2 and .Xr write 2 or .Xr send 2 system calls may be used). .Pp If .Fa proto is 0, the default protocol .Dv IPPROTO_RAW is used for outgoing packets, and only incoming packets destined for that protocol are received. If .Fa proto is non-zero, that protocol number will be used on outgoing packets and to filter incoming packets. .Pp Outgoing packets automatically have an .Tn IP header prepended to them (based on the destination address and the protocol number the socket is created with), unless the .Dv IP_HDRINCL option has been set. Unlike in previous .Bx releases, incoming packets are received with .Tn IP header and options intact, leaving all fields in network byte order. .Pp .Dv IP_HDRINCL indicates the complete IP header is included with the data and may be used only with the .Dv SOCK_RAW type. .Bd -literal #include #include int hincl = 1; /* 1 = on, 0 = off */ setsockopt(s, IPPROTO_IP, IP_HDRINCL, &hincl, sizeof(hincl)); .Ed .Pp Unlike previous .Bx releases, the program must set all the fields of the IP header, including the following: .Bd -literal ip->ip_v = IPVERSION; ip->ip_hl = hlen >> 2; ip->ip_id = 0; /* 0 means kernel set appropriate value */ ip->ip_off = htons(offset); ip->ip_len = htons(len); .Ed .Pp The packet should be provided as is to be sent over wire. This implies all fields, including .Va ip_len and .Va ip_off to be in network byte order. See .Xr byteorder 3 for more information on network byte order. If the .Va ip_id field is set to 0 then the kernel will choose an appropriate value. If the header source address is set to .Dv INADDR_ANY , the kernel will choose an appropriate address. .Sh ERRORS A socket operation may fail with one of the following errors returned: .Bl -tag -width Er .It Bq Er EISCONN when trying to establish a connection on a socket which already has one, or when trying to send a datagram with the destination address specified and the socket is already connected; .It Bq Er ENOTCONN when trying to send a datagram, but no destination address is specified, and the socket has not been connected; .It Bq Er ENOBUFS when the system runs out of memory for an internal data structure; .It Bq Er EADDRNOTAVAIL when an attempt is made to create a socket with a network address for which no network interface exists. .It Bq Er EACCES when an attempt is made to create a raw IP socket by a non-privileged process. .El .Pp The following errors specific to .Tn IP may occur when setting or getting .Tn IP options: .Bl -tag -width Er .It Bq Er EINVAL An unknown socket option name was given. .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. .El .Pp The following errors may occur when attempting to send .Tn IP datagrams via a .Dq raw socket with the .Dv IP_HDRINCL option set: .Bl -tag -width Er .It Bq Er EINVAL The user-supplied .Va ip_len field was not equal to the length of the datagram written to the socket. .El .Sh SEE ALSO .Xr getsockopt 2 , .Xr recv 2 , .Xr send 2 , .Xr byteorder 3 , +.Xr sourcefilter 3 , .Xr icmp 4 , .Xr igmp 4 , .Xr inet 4 , .Xr intro 4 , -.Xr multicast 4 , -.Xr sourcefilter 3 +.Xr multicast 4 .Rs .%A D. Thaler .%A B. Fenner .%A B. Quinn .%T "Socket Interface Extensions for Multicast Source Filters" .%N RFC 3678 .%D Jan 2004 .Re .Sh HISTORY The .Nm protocol appeared in .Bx 4.2 . The .Vt ip_mreqn structure appeared in .Tn Linux 2.4 . .Sh BUGS Before .Fx 10.0 packets received on raw IP sockets had the .Va ip_hl subtracted from the .Va ip_len field. .Pp Before .Fx 11.0 packets received on raw IP sockets had the .Va ip_len and .Va ip_off fields converted to host byte order. Packets written to raw IP sockets were expected to have .Va ip_len and .Va ip_off in host byte order. Index: head/share/man/man4/ipheth.4 =================================================================== --- head/share/man/man4/ipheth.4 (revision 275989) +++ head/share/man/man4/ipheth.4 (revision 275990) @@ -1,105 +1,105 @@ .\" Copyright (c) 2014 Gavin Atkinson .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" .\" - Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" - Redistributions in binary form must reproduce the above .\" copyright notice, this list of conditions and the following .\" disclaimer in the documentation and/or other materials provided .\" with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS .\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER .\" CAUSED AND ON 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 ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd September 30, 2014 .Dt IPHETH 4 .Os .Sh NAME .Nm ipheth .Nd "USB Apple iPhone/iPad tethered Ethernet driver" .Sh SYNOPSIS To load the driver as a module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent if_ipheth_load="YES" .Ed .Pp Alternatively, to compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device uhci" .Cd "device ohci" .Cd "device usb" .Cd "device ipheth" .Ed .Sh DESCRIPTION The .Nm driver provides support for network access through Apple iPhone and iPad devices, often referred to as USB tethering. .Pp .Nm should work with any Apple iPhone or iPad device. In most cases this must be explicitly enabled on the device first. .Pp For more information on configuring this device, see .Xr ifconfig 8 . The device does not support different media types or options. .Sh HARDWARE The following devices are supported by the .Nm driver: .Pp .Bl -bullet -compact .It Apple iPhone tethering (all models) .It Apple iPad tethering (all models) .El .Sh SEE ALSO .Xr arp 4 , .Xr cdce 4 , .Xr intro 4 , .Xr netintro 4 , .Xr urndis 4 , .Xr usb 4 , -.Xr ifconfig 8 +.Xr ifconfig 8 , .Xr usbconfig 8 .Sh HISTORY The .Nm device driver first appeared in .Fx 8.2 . .Sh AUTHORS .An -nosplit The .Nm driver was written by .An Hans Petter Selasky Aq Mt hselasky@FreeBSD.org . .Sh BUGS Some devices may need to be manually configured to use an alternative configuration with the .Xr usbconfig 8 utility. A command similar to .Dl usbconfig -u 1 -a 2 set_config 3 may be required if the device is not recognised automatically by .Nm after it is connected. Index: head/share/man/man4/iscsi_initiator.4 =================================================================== --- head/share/man/man4/iscsi_initiator.4 (revision 275989) +++ head/share/man/man4/iscsi_initiator.4 (revision 275990) @@ -1,117 +1,118 @@ .\" Copyright (c) 2007-2010 Daniel Braniss .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON 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 ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd October 9, 2014 .Dt ISCSI_INITIATOR 4 .Os .Sh NAME .Nm iscsi_initiator .Nd kernel driver for the iSCSI protocol .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device iscsi_initiator" .Ed .Pp Alternatively, to load the driver as a module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent iscsi_initiator_load="YES" .Ed .Sh DESCRIPTION .Bf -symbolic This driver, along with its userspace counterpart .Xr iscontrol 8 , is obsolete. Users are advised to use .Xr iscsi 4 instead. .Ef .Pp The .Nm implements the kernel side of the Internet SCSI (iSCSI) network protocol standard, the user land companion is .Xr iscontrol 8 , and permits access to remote .Em virtual SCSI devices via .Xr cam 4 . .Sh SYSCTL VARIABLES .Bl -tag -width ".Va net.iscsi.n.targeaddress" .It Va debug.iscsi_initiator set the debug-level, 0 means no debugging, 9 for maximum. .It Va net.iscsi.isid the initiator part of the Session Identifier. .It Va "kern.cam.cam_srch_hi=1" allow search above LUN 7 for SCSI3 and greater devices. .It "the following are informative only:" .It Va net.iscsi.driver_version the current version of the driver. .It Va net.iscsi.sessions the number of current active sessions. .It Va net.iscsi.n.targetname is the targe name of session .Em n . .It Va net.iscsi.n.targeaddress is the IP address of the target of session .Em n . .It Va net.iscsi.n.stats are some statistics for session .Em n .It Va net.iscsi.n.pid is the .Em "process id" of the userland side of session .Em n , see .Xr iscontrol 8 . .El .Sh FILES The .Nm driver creates the following: .Pp .Bl -tag -width ".Pa /dev/iscsi%dxx" -compact .It Pa /dev/iscsi used to create new sessions. .It Pa /dev/iscsi%d for each new session. .El .Sh SEE ALSO .Xr cam 4 , .Xr camcontrol 8 , .Xr iscontrol 8 .Sh STANDARDS iSCSI RFC 3720 .\" .Sh HISTORY .Sh AUTHORS -This software was written by Daniel Braniss +This software was written by +.An Daniel Braniss Aq Mt danny@cs.huji.ac.il .Sh BUGS The lun discovery method is old-fashioned. Index: head/share/man/man4/isp.4 =================================================================== --- head/share/man/man4/isp.4 (revision 275989) +++ head/share/man/man4/isp.4 (revision 275990) @@ -1,242 +1,244 @@ .\" $NetBSD: isp.4,v 1.5 1999/12/18 18:33:05 mjacob Exp $ .\" .\" Copyright (c) 1998, 1999, 2001 .\" Matthew Jacob, for NASA/Ames Research Center .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 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 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" Additional Copyright (c) 2006 by Marcus Alves Grando .\" .\" $FreeBSD$ .\" .Dd December 1, 2014 .Dt ISP 4 .Os .Sh NAME .Nm isp .Nd Qlogic based SCSI and FibreChannel SCSI Host Adapters .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device scbus" .Cd "device isp" .Ed .Pp Alternatively, to load the driver as a module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent isp_load="YES" .Ed .Sh DESCRIPTION This driver provides access to .Tn SCSI or .Tn FibreChannel devices. .Pp SCSI features include support for Ultra SCSI and wide mode transactions for .Tn SCSI , Ultra2 LVD (for the ISP1080 and ISP1280), and Ultra3 LVD (for the ISP12160). .Pp Fibre Channel support uses FCP SCSI profile for .Tn FibreChannel , and utilizes Class 3 and Class 2 connections (Qlogic 2100 is Class 3 only, minor patches to the Qlogic 2200 to force Class 2 mode). Support is available for Public and Private loops, and for point-to-point connections (Qlogic 2200 only). The newer 2-Gigabit cards (2300, 2312, 2322) and 4-Gigabit (2422, 2432) are also supported. Command tagging is supported for all (in fact, .Tn FibreChannel requires tagging). Fabric support is enabled by default for other than 2100 cards. Fabric support for 2100 cards has been so problematic and these cards are so old now that it is just not worth your time to try it. .Sh FIRMWARE Firmware is available if the .Xr ispfw 4 module is loaded during bootstrap (q.v.). .Pp It is .Ar strongly recommended that you use the firmware available from .Xr ispfw 4 as it is the most likely to have been tested with this driver. .Sh HARDWARE Cards supported by the .Nm driver include: .Bl -tag -width xxxxxx -offset indent .It ISP1000 SBus Fast Wide, Ultra Fast Wide cards, Single Ended or Differential cards. .It ISP1020 Qlogic 1020 Fast Wide and Differential Fast Wide PCI cards. .It ISP1040 Qlogic 1040 Ultra Wide and Differential Ultra Wide PCI cards. Also known as the DEC KZPBA-CA (single ended) and KZPBA-CB (HVD differential). .It Qlogic 1240 Qlogic 1240 Dual Bus Ultra Wide and Differential Ultra Wide PCI cards. .It Qlogic 1020 Qlogic 1020 SCSI cards. .It Qlogic 1040 Qlogic 1040 Ultra SCSI cards. .It Qlogic 1080 Qlogic 1280 LVD Ultra2 Wide PCI cards. .It Qlogic 1280 Qlogic 1280 Dual Bus LVD Ultra2 Wide PCI cards. .It Qlogic 12160 Qlogic 12160 Dual Bus LVD Ultra3 Wide PCI cards. .It Qlogic 210X Qlogic 2100 and 2100A Copper and Optical Fibre Channel Arbitrated Loop (single, dual). .It Qlogic 220X Qlogic 2200 Copper and Optical Fibre Channel Arbitrated Loop PCI cards (single, dual, quad). .It Qlogic 2300 Qlogic 2300 Optical Fibre Channel PCI cards. .It Qlogic 2312 Qlogic 2312 Optical Fibre Channel PCI cards. .It Qlogic 234X Qlogic 234X Optical Fibre Channel PCI cards (2312 chipset, single and dual attach). .It Qlogic 2322 Qlogic 2322 Optical Fibre Channel PCIe cards. .It Qlogic 200 Dell Branded version of the QLogic 2312 Fibre Channel PCI cards. .It Qlogic 2422 Qlogic 2422 Optical Fibre Channel PCI cards (4 Gigabit) .It Qlogic 2432 Qlogic 2432 Optical Fibre Channel PCIe cards (4 Gigabit) .It Qlogic 2432 Qlogic 2532 Optical Fibre Channel PCIe cards (8 Gigabit) .El .Sh CONFIGURATION OPTIONS Target mode support may be enabled with the .Pp .Cd options ISP_TARGET_MODE .Pp option. .Sh BOOT OPTIONS The following options are switchable by setting values in .Pa /boot/device.hints . .Pp They are: .Bl -tag -width indent .It Va hint.isp.0.disable A hint value to disable driver in kernel. .It Va hint.isp.0.fwload_disable A hint value to disable loading of firmware .Xr ispfw 4 . .It Va hint.isp.0.prefer_memmap A hint value to use PCI memory space instead of I/O space access for. .It Va hint.isp.0.prefer_iomap A hint value to use PCI I/O space instead of Memory space access for. .It Va hint.isp.0.ignore_nvram A hint value to ignore board NVRAM settings for. Otherwise use NVRAM settings. .It Va hint.isp.0.fullduplex A hint value to set full duplex mode. .It Va hint.isp.0.topology A hint value to select topology of connection. Supported values are: .Pp .Bl -tag -width ".Li lport-only" -compact .It Li lport Prefer loopback and fallback to point to point. .It Li nport Prefer point to point and fallback to loopback. .It Li lport-only Loopback only. .It Li nport-only Point to point only. .El .It Va hint.isp.0.portwwn This should be the full 64 bit World Wide Port Name you would like to use, overriding the value in NVRAM for the card. .It Va hint.isp.0.nodewwn This should be the full 64 bit World Wide Node Name you would like to use, overriding the value in NVRAM for the card. .It Va hint.isp.0.iid A hint to override or set the Initiator ID or Loop ID. For Fibre Channel cards in Local Loop topologies it is .Ar strongly recommended that you set this value to non-zero. .It Va hint.isp.0.role A hint to define default role for isp instance (target, initiator, both). .It Va hint.isp.0.debug A hint value for a driver debug level (see the file .Pa /usr/src/sys/dev/isp/ispvar.h for the values. .It Va hint.isp.0.vports A hint to create specified number of additional virtual ports. .El .Sh SYSCTL OPTIONS .Bl -tag -width indent .It Va dev.isp.N.loop_down_limit This value says how long to wait in seconds after loop has gone down before giving up and expiring all of the devices that were visible. The default is 300 seconds (5 minutes). A separate (nonadjustable) timeout is used when booting to not stop booting on lack of FC connectivity. .It Va dev.isp.N.gone_device_time This value says how long to wait for devices to reappear if they (temporarily) disappear due to loop or fabric events. While this timeout is running, I/O to those devices will simply be held. .It Va dev.isp.N.wwnn This is the readonly World Wide Node Name value for this port. .It Va dev.isp.N.wwpn This is the readonly World Wide Port Name value for this port. .El .Sh SEE ALSO .Xr da 4 , .Xr intro 4 , .Xr ispfw 4 , .Xr sa 4 , .Xr scsi 4 , .Xr gmultipath 8 .Sh AUTHORS The .Nm -driver was written by Matthew Jacob originally for NetBSD at +driver was written by +.An Matthew Jacob +originally for NetBSD at NASA/Ames Research Center. .Sh BUGS The driver currently ignores some NVRAM settings. .Pp Target mode support is not completely reliable yet. It works reasonably well for Fibre Channel, somewhat well for Qlogic 1040 cards, but does not yet work for the other cards (due to last minute unannounced changes in firmware interfaces). Index: head/share/man/man4/ispfw.4 =================================================================== --- head/share/man/man4/ispfw.4 (revision 275989) +++ head/share/man/man4/ispfw.4 (revision 275990) @@ -1,59 +1,60 @@ .\" Copyright (c) 2000 .\" Matthew Jacob .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 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 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd July 20, 2000 .Dt ISPFW 4 .Os .Sh NAME .Nm ispfw .Nd "Firmware Module for Qlogic based SCSI and FibreChannel SCSI Host Adapters" .Sh SYNOPSIS To compile this driver into the kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "device ispfw" .Ed .Pp Alternatively, to load the driver as a module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent ispfw_load="YES" .Ed .Sh DESCRIPTION This trivial driver provides access to firmware sets for the Qlogic based SCSI and FibreChannel SCSI Host Adapters. It may either be statically linked into the kernel, or loaded as a module. In either case, the .Xr isp 4 driver will notice that firmware is available to be downloaded onto Qlogic cards (to replace the usually out of date firmware on the cards). This will kick the f/w into getting unstuck. .Sh SEE ALSO .Xr isp 4 .Sh AUTHORS -This driver was written by Matthew Jacob. +This driver was written by +.An Matthew Jacob . Index: head/share/man/man4/iwi.4 =================================================================== --- head/share/man/man4/iwi.4 (revision 275989) +++ head/share/man/man4/iwi.4 (revision 275990) @@ -1,160 +1,160 @@ .\" Copyright (c) 2004-2006 .\" Damien Bergamini . All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice unmodified, this list of conditions, and the following .\" disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON 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 ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd April 13, 2008 .Dt IWI 4 .Os .Sh NAME .Nm iwi .Nd "Intel PRO/Wireless 2200BG/2225BG/2915ABG IEEE 802.11 driver" .Sh SYNOPSIS To compile this driver into the kernel, include the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device iwi" .Cd "device iwifw" .Cd "device pci" .Cd "device wlan" .Cd "device firmware" .Ed .Pp Alternatively, to load the driver as a module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent if_iwi_load="YES" .Ed .Pp In both cases, place the following line in .Xr loader.conf 5 to acknowledge the firmware license (see below): .Bd -literal -offset indent legal.intel_iwi.license_ack=1 .Ed .Sh DESCRIPTION The .Nm driver provides support for .Tn Intel PRO/Wireless 2200BG/2915ABG MiniPCI and 2225BG PCI network adapters. .Nm supports .Cm station , .Cm adhoc , and .Cm monitor mode operation. Only one virtual interface may be configured at any time. For more information on configuring this device, see .Xr ifconfig 8 . .Pp This driver requires the firmware built with the .Nm iwifw module to work. For the loaded firmware to be enabled for use the license at .Pa /usr/share/doc/legal/intel_iwi/LICENSE must be agreed by adding the following line to .Xr loader.conf 5 : .Pp .Dl "legal.intel_iwi.license_ack=1" .Sh FILES .Bl -tag -width ".Pa /usr/share/doc/legal/intel_iwi/LICENSE" -compact .It Pa /usr/share/doc/legal/intel_iwi/LICENSE .Nm firmware license .El .Sh EXAMPLES Join an existing BSS network (i.e., connect to an access point): .Bd -literal -offset indent ifconfig wlan create wlandev iwi0 inet 192.168.0.20 \e netmask 0xffffff00 .Ed .Pp Join a specific BSS network with network name .Dq Li my_net : .Pp .Dl "ifconfig wlan create wlandev iwi0 ssid my_net up" .Pp Join a specific BSS network with 64-bit WEP encryption: .Bd -literal -offset indent ifconfig wlan create wlandev iwi0 ssid my_net \e wepmode on wepkey 0x1234567890 weptxkey 1 up .Ed .Pp Join a specific BSS network with 128-bit WEP encryption: .Bd -literal -offset indent ifconfig wlan create wlandev iwi0 wlanmode adhoc ssid my_net \e wepmode on wepkey 0x01020304050607080910111213 weptxkey 1 .Ed .Sh DIAGNOSTICS .Bl -diag .It "iwi%d: device timeout" The driver will reset the hardware. This should not happen. .It "iwi%d: firmware error" The onboard microcontroller crashed for some reason. The driver will reset the hardware. This should not happen. .It "iwi%d: timeout waiting for firmware initialization to complete" The onboard microcontroller failed to initialize in time. This should not happen. .It "iwi%d: could not load firmware image '%s'" The driver failed to load the firmware image using the .Xr firmware 9 subsystem. Verify the .Xr iwifw 4 firmware module is installed and the license agreement .Xr loader 8 tunable has been set. .It "iwi%d: could not load boot firmware" An attempt to upload the boot firmware image to the onboard microcontroller failed. This should not happen. .It "iwi%d: could not load microcode" An attempt to upload the microcode image to the onboard microcontroller failed. This should not happen. .It "iwi%d: could not load main firmware" An attempt to upload the main firmware image to the onboard microcontroller failed. This should not happen. .El .Sh SEE ALSO .Xr iwifw 4 , .Xr pci 4 , .Xr wlan 4 , .Xr wlan_ccmp 4 , .Xr wlan_tkip 4 , .Xr wlan_wep 4 , .Xr ifconfig 8 , -.Xr wpa_supplicant 8 . +.Xr wpa_supplicant 8 .Sh AUTHORS The original .Nm driver was written by .An Damien Bergamini Aq Mt damien.bergamini@free.fr . Index: head/share/man/man4/multicast.4 =================================================================== --- head/share/man/man4/multicast.4 (revision 275989) +++ head/share/man/man4/multicast.4 (revision 275990) @@ -1,1011 +1,1011 @@ .\" Copyright (c) 2001-2003 International Computer Science Institute .\" .\" Permission is hereby granted, free of charge, to any person obtaining a .\" copy of this software and associated documentation files (the "Software"), .\" to deal in the Software without restriction, including without limitation .\" the rights to use, copy, modify, merge, publish, distribute, sublicense, .\" and/or sell copies of the Software, and to permit persons to whom the .\" Software is furnished to do so, subject to the following conditions: .\" .\" The above copyright notice and this permission notice shall be included in .\" all copies or substantial portions of the Software. .\" .\" The names and trademarks of copyright holders may not be used in .\" advertising or publicity pertaining to the software without specific .\" prior permission. Title to copyright in this software and any associated .\" documentation will at all times remain with the copyright holders. .\" .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR .\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, .\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE .\" AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER .\" LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING .\" FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER .\" DEALINGS IN THE SOFTWARE. .\" .\" $FreeBSD$ .\" .Dd May 27, 2009 .Dt MULTICAST 4 .Os .\" .Sh NAME .Nm multicast .Nd Multicast Routing .\" .Sh SYNOPSIS .Cd "options MROUTING" .Pp .In sys/types.h .In sys/socket.h .In netinet/in.h .In netinet/ip_mroute.h .In netinet6/ip6_mroute.h .Ft int .Fn getsockopt "int s" IPPROTO_IP MRT_INIT "void *optval" "socklen_t *optlen" .Ft int .Fn setsockopt "int s" IPPROTO_IP MRT_INIT "const void *optval" "socklen_t optlen" .Ft int .Fn getsockopt "int s" IPPROTO_IPV6 MRT6_INIT "void *optval" "socklen_t *optlen" .Ft int .Fn setsockopt "int s" IPPROTO_IPV6 MRT6_INIT "const void *optval" "socklen_t optlen" .Sh DESCRIPTION .Tn "Multicast routing" is used to efficiently propagate data packets to a set of multicast listeners in multipoint networks. If unicast is used to replicate the data to all listeners, then some of the network links may carry multiple copies of the same data packets. With multicast routing, the overhead is reduced to one copy (at most) per network link. .Pp All multicast-capable routers must run a common multicast routing protocol. It is recommended that either Protocol Independent Multicast - Sparse Mode (PIM-SM), or Protocol Independent Multicast - Dense Mode (PIM-DM) are used, as these are now the generally accepted protocols in the Internet community. The .Sx HISTORY section discusses previous multicast routing protocols. .Pp To start multicast routing, the user must enable multicast forwarding in the kernel (see .Sx SYNOPSIS about the kernel configuration options), and must run a multicast routing capable user-level process. From developer's point of view, the programming guide described in the .Sx "Programming Guide" section should be used to control the multicast forwarding in the kernel. .\" .Ss Programming Guide This section provides information about the basic multicast routing API. The so-called .Dq advanced multicast API is described in the .Sx "Advanced Multicast API Programming Guide" section. .Pp First, a multicast routing socket must be open. That socket would be used to control the multicast forwarding in the kernel. Note that most operations below require certain privilege (i.e., root privilege): .Bd -literal /* IPv4 */ int mrouter_s4; mrouter_s4 = socket(AF_INET, SOCK_RAW, IPPROTO_IGMP); .Ed .Bd -literal int mrouter_s6; mrouter_s6 = socket(AF_INET6, SOCK_RAW, IPPROTO_ICMPV6); .Ed .Pp Note that if the router needs to open an IGMP or ICMPv6 socket (in case of IPv4 and IPv6 respectively) for sending or receiving of IGMP or MLD multicast group membership messages, then the same .Va mrouter_s4 or .Va mrouter_s6 sockets should be used for sending and receiving respectively IGMP or MLD messages. In case of .Bx Ns -derived kernel, it may be possible to open separate sockets for IGMP or MLD messages only. However, some other kernels (e.g., .Tn Linux ) require that the multicast routing socket must be used for sending and receiving of IGMP or MLD messages. Therefore, for portability reason the multicast routing socket should be reused for IGMP and MLD messages as well. .Pp After the multicast routing socket is open, it can be used to enable or disable multicast forwarding in the kernel: .Bd -literal /* IPv4 */ int v = 1; /* 1 to enable, or 0 to disable */ setsockopt(mrouter_s4, IPPROTO_IP, MRT_INIT, (void *)&v, sizeof(v)); .Ed .Bd -literal /* IPv6 */ int v = 1; /* 1 to enable, or 0 to disable */ setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_INIT, (void *)&v, sizeof(v)); \&... /* If necessary, filter all ICMPv6 messages */ struct icmp6_filter filter; ICMP6_FILTER_SETBLOCKALL(&filter); setsockopt(mrouter_s6, IPPROTO_ICMPV6, ICMP6_FILTER, (void *)&filter, sizeof(filter)); .Ed .Pp After multicast forwarding is enabled, the multicast routing socket can be used to enable PIM processing in the kernel if we are running PIM-SM or PIM-DM (see .Xr pim 4 ) . .Pp For each network interface (e.g., physical or a virtual tunnel) that would be used for multicast forwarding, a corresponding multicast interface must be added to the kernel: .Bd -literal /* IPv4 */ struct vifctl vc; memset(&vc, 0, sizeof(vc)); /* Assign all vifctl fields as appropriate */ vc.vifc_vifi = vif_index; vc.vifc_flags = vif_flags; vc.vifc_threshold = min_ttl_threshold; vc.vifc_rate_limit = 0; memcpy(&vc.vifc_lcl_addr, &vif_local_address, sizeof(vc.vifc_lcl_addr)); setsockopt(mrouter_s4, IPPROTO_IP, MRT_ADD_VIF, (void *)&vc, sizeof(vc)); .Ed .Pp The .Va vif_index must be unique per vif. The .Va vif_flags contains the .Dv VIFF_* flags as defined in .In netinet/ip_mroute.h . The .Dv VIFF_TUNNEL flag is no longer supported by .Fx . Users who wish to forward multicast datagrams over a tunnel should consider configuring a .Xr gif 4 or .Xr gre 4 tunnel and using it as a physical interface. .Pp The .Va min_ttl_threshold contains the minimum TTL a multicast data packet must have to be forwarded on that vif. Typically, it would have value of 1. .Pp The .Va max_rate_limit argument is no longer supported in .Fx and should be set to 0. Users who wish to rate-limit multicast datagrams should consider the use of .Xr dummynet 4 or .Xr altq 4 . .Pp The .Va vif_local_address contains the local IP address of the corresponding local interface. The .Va vif_remote_address contains the remote IP address in case of DVMRP multicast tunnels. .Bd -literal /* IPv6 */ struct mif6ctl mc; memset(&mc, 0, sizeof(mc)); /* Assign all mif6ctl fields as appropriate */ mc.mif6c_mifi = mif_index; mc.mif6c_flags = mif_flags; mc.mif6c_pifi = pif_index; setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_ADD_MIF, (void *)&mc, sizeof(mc)); .Ed .Pp The .Va mif_index must be unique per vif. The .Va mif_flags contains the .Dv MIFF_* flags as defined in .In netinet6/ip6_mroute.h . The .Va pif_index is the physical interface index of the corresponding local interface. .Pp A multicast interface is deleted by: .Bd -literal /* IPv4 */ vifi_t vifi = vif_index; setsockopt(mrouter_s4, IPPROTO_IP, MRT_DEL_VIF, (void *)&vifi, sizeof(vifi)); .Ed .Bd -literal /* IPv6 */ mifi_t mifi = mif_index; setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_DEL_MIF, (void *)&mifi, sizeof(mifi)); .Ed .Pp After the multicast forwarding is enabled, and the multicast virtual interfaces are added, the kernel may deliver upcall messages (also called signals later in this text) on the multicast routing socket that was open earlier with .Dv MRT_INIT or .Dv MRT6_INIT . The IPv4 upcalls have .Vt "struct igmpmsg" header (see .In netinet/ip_mroute.h ) with field .Va im_mbz set to zero. Note that this header follows the structure of .Vt "struct ip" with the protocol field .Va ip_p set to zero. The IPv6 upcalls have .Vt "struct mrt6msg" header (see .In netinet6/ip6_mroute.h ) with field .Va im6_mbz set to zero. Note that this header follows the structure of .Vt "struct ip6_hdr" with the next header field .Va ip6_nxt set to zero. .Pp The upcall header contains field .Va im_msgtype and .Va im6_msgtype with the type of the upcall .Dv IGMPMSG_* and .Dv MRT6MSG_* for IPv4 and IPv6 respectively. The values of the rest of the upcall header fields and the body of the upcall message depend on the particular upcall type. .Pp If the upcall message type is .Dv IGMPMSG_NOCACHE or .Dv MRT6MSG_NOCACHE , this is an indication that a multicast packet has reached the multicast router, but the router has no forwarding state for that packet. Typically, the upcall would be a signal for the multicast routing user-level process to install the appropriate Multicast Forwarding Cache (MFC) entry in the kernel. .Pp An MFC entry is added by: .Bd -literal /* IPv4 */ struct mfcctl mc; memset(&mc, 0, sizeof(mc)); memcpy(&mc.mfcc_origin, &source_addr, sizeof(mc.mfcc_origin)); memcpy(&mc.mfcc_mcastgrp, &group_addr, sizeof(mc.mfcc_mcastgrp)); mc.mfcc_parent = iif_index; for (i = 0; i < maxvifs; i++) mc.mfcc_ttls[i] = oifs_ttl[i]; setsockopt(mrouter_s4, IPPROTO_IP, MRT_ADD_MFC, (void *)&mc, sizeof(mc)); .Ed .Bd -literal /* IPv6 */ struct mf6cctl mc; memset(&mc, 0, sizeof(mc)); memcpy(&mc.mf6cc_origin, &source_addr, sizeof(mc.mf6cc_origin)); memcpy(&mc.mf6cc_mcastgrp, &group_addr, sizeof(mf6cc_mcastgrp)); mc.mf6cc_parent = iif_index; for (i = 0; i < maxvifs; i++) if (oifs_ttl[i] > 0) IF_SET(i, &mc.mf6cc_ifset); setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_ADD_MFC, (void *)&mc, sizeof(mc)); .Ed .Pp The .Va source_addr and .Va group_addr are the source and group address of the multicast packet (as set in the upcall message). The .Va iif_index is the virtual interface index of the multicast interface the multicast packets for this specific source and group address should be received on. The .Va oifs_ttl[] array contains the minimum TTL (per interface) a multicast packet should have to be forwarded on an outgoing interface. If the TTL value is zero, the corresponding interface is not included in the set of outgoing interfaces. Note that in case of IPv6 only the set of outgoing interfaces can be specified. .Pp An MFC entry is deleted by: .Bd -literal /* IPv4 */ struct mfcctl mc; memset(&mc, 0, sizeof(mc)); memcpy(&mc.mfcc_origin, &source_addr, sizeof(mc.mfcc_origin)); memcpy(&mc.mfcc_mcastgrp, &group_addr, sizeof(mc.mfcc_mcastgrp)); setsockopt(mrouter_s4, IPPROTO_IP, MRT_DEL_MFC, (void *)&mc, sizeof(mc)); .Ed .Bd -literal /* IPv6 */ struct mf6cctl mc; memset(&mc, 0, sizeof(mc)); memcpy(&mc.mf6cc_origin, &source_addr, sizeof(mc.mf6cc_origin)); memcpy(&mc.mf6cc_mcastgrp, &group_addr, sizeof(mf6cc_mcastgrp)); setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_DEL_MFC, (void *)&mc, sizeof(mc)); .Ed .Pp The following method can be used to get various statistics per installed MFC entry in the kernel (e.g., the number of forwarded packets per source and group address): .Bd -literal /* IPv4 */ struct sioc_sg_req sgreq; memset(&sgreq, 0, sizeof(sgreq)); memcpy(&sgreq.src, &source_addr, sizeof(sgreq.src)); memcpy(&sgreq.grp, &group_addr, sizeof(sgreq.grp)); ioctl(mrouter_s4, SIOCGETSGCNT, &sgreq); .Ed .Bd -literal /* IPv6 */ struct sioc_sg_req6 sgreq; memset(&sgreq, 0, sizeof(sgreq)); memcpy(&sgreq.src, &source_addr, sizeof(sgreq.src)); memcpy(&sgreq.grp, &group_addr, sizeof(sgreq.grp)); ioctl(mrouter_s6, SIOCGETSGCNT_IN6, &sgreq); .Ed .Pp The following method can be used to get various statistics per multicast virtual interface in the kernel (e.g., the number of forwarded packets per interface): .Bd -literal /* IPv4 */ struct sioc_vif_req vreq; memset(&vreq, 0, sizeof(vreq)); vreq.vifi = vif_index; ioctl(mrouter_s4, SIOCGETVIFCNT, &vreq); .Ed .Bd -literal /* IPv6 */ struct sioc_mif_req6 mreq; memset(&mreq, 0, sizeof(mreq)); mreq.mifi = vif_index; ioctl(mrouter_s6, SIOCGETMIFCNT_IN6, &mreq); .Ed .Ss Advanced Multicast API Programming Guide If we want to add new features in the kernel, it becomes difficult to preserve backward compatibility (binary and API), and at the same time to allow user-level processes to take advantage of the new features (if the kernel supports them). .Pp One of the mechanisms that allows us to preserve the backward compatibility is a sort of negotiation between the user-level process and the kernel: .Bl -enum .It The user-level process tries to enable in the kernel the set of new features (and the corresponding API) it would like to use. .It The kernel returns the (sub)set of features it knows about and is willing to be enabled. .It The user-level process uses only that set of features the kernel has agreed on. .El .\" .Pp To support backward compatibility, if the user-level process does not ask for any new features, the kernel defaults to the basic multicast API (see the .Sx "Programming Guide" section). .\" XXX: edit as appropriate after the advanced multicast API is .\" supported under IPv6 Currently, the advanced multicast API exists only for IPv4; in the future there will be IPv6 support as well. .Pp Below is a summary of the expandable API solution. Note that all new options and structures are defined in .In netinet/ip_mroute.h and .In netinet6/ip6_mroute.h , unless stated otherwise. .Pp The user-level process uses new .Fn getsockopt Ns / Ns Fn setsockopt options to perform the API features negotiation with the kernel. This negotiation must be performed right after the multicast routing socket is open. The set of desired/allowed features is stored in a bitset (currently, in .Vt uint32_t ; i.e., maximum of 32 new features). The new .Fn getsockopt Ns / Ns Fn setsockopt options are .Dv MRT_API_SUPPORT and .Dv MRT_API_CONFIG . Example: .Bd -literal uint32_t v; getsockopt(sock, IPPROTO_IP, MRT_API_SUPPORT, (void *)&v, sizeof(v)); .Ed .Pp would set in .Va v the pre-defined bits that the kernel API supports. The eight least significant bits in .Vt uint32_t are same as the eight possible flags .Dv MRT_MFC_FLAGS_* that can be used in .Va mfcc_flags as part of the new definition of .Vt "struct mfcctl" (see below about those flags), which leaves 24 flags for other new features. The value returned by .Fn getsockopt MRT_API_SUPPORT is read-only; in other words, .Fn setsockopt MRT_API_SUPPORT would fail. .Pp To modify the API, and to set some specific feature in the kernel, then: .Bd -literal uint32_t v = MRT_MFC_FLAGS_DISABLE_WRONGVIF; if (setsockopt(sock, IPPROTO_IP, MRT_API_CONFIG, (void *)&v, sizeof(v)) != 0) { return (ERROR); } if (v & MRT_MFC_FLAGS_DISABLE_WRONGVIF) return (OK); /* Success */ else return (ERROR); .Ed .Pp In other words, when .Fn setsockopt MRT_API_CONFIG is called, the argument to it specifies the desired set of features to be enabled in the API and the kernel. The return value in .Va v is the actual (sub)set of features that were enabled in the kernel. To obtain later the same set of features that were enabled, then: .Bd -literal getsockopt(sock, IPPROTO_IP, MRT_API_CONFIG, (void *)&v, sizeof(v)); .Ed .Pp The set of enabled features is global. In other words, .Fn setsockopt MRT_API_CONFIG should be called right after .Fn setsockopt MRT_INIT . .Pp Currently, the following set of new features is defined: .Bd -literal #define MRT_MFC_FLAGS_DISABLE_WRONGVIF (1 << 0) /* disable WRONGVIF signals */ #define MRT_MFC_FLAGS_BORDER_VIF (1 << 1) /* border vif */ #define MRT_MFC_RP (1 << 8) /* enable RP address */ #define MRT_MFC_BW_UPCALL (1 << 9) /* enable bw upcalls */ .Ed .\" .Pp .\" In the future there might be: .\" .Bd -literal .\" #define MRT_MFC_GROUP_SPECIFIC (1 << 10) /* allow (*,G) MFC entries */ .\" .Ed .\" .Pp .\" to allow (*,G) MFC entries (i.e., group-specific entries) in the kernel. .\" For now this is left-out until it is clear whether .\" (*,G) MFC support is the preferred solution instead of something more generic .\" solution for example. .\" .\" 2. The newly defined struct mfcctl2. .\" .Pp The advanced multicast API uses a newly defined .Vt "struct mfcctl2" instead of the traditional .Vt "struct mfcctl" . The original .Vt "struct mfcctl" is kept as is. The new .Vt "struct mfcctl2" is: .Bd -literal /* * The new argument structure for MRT_ADD_MFC and MRT_DEL_MFC overlays * and extends the old struct mfcctl. */ struct mfcctl2 { /* the mfcctl fields */ struct in_addr mfcc_origin; /* ip origin of mcasts */ struct in_addr mfcc_mcastgrp; /* multicast group associated*/ vifi_t mfcc_parent; /* incoming vif */ u_char mfcc_ttls[MAXVIFS];/* forwarding ttls on vifs */ /* extension fields */ uint8_t mfcc_flags[MAXVIFS];/* the MRT_MFC_FLAGS_* flags*/ struct in_addr mfcc_rp; /* the RP address */ }; .Ed .Pp The new fields are .Va mfcc_flags[MAXVIFS] and .Va mfcc_rp . Note that for compatibility reasons they are added at the end. .Pp The .Va mfcc_flags[MAXVIFS] field is used to set various flags per interface per (S,G) entry. Currently, the defined flags are: .Bd -literal #define MRT_MFC_FLAGS_DISABLE_WRONGVIF (1 << 0) /* disable WRONGVIF signals */ #define MRT_MFC_FLAGS_BORDER_VIF (1 << 1) /* border vif */ .Ed .Pp The .Dv MRT_MFC_FLAGS_DISABLE_WRONGVIF flag is used to explicitly disable the .Dv IGMPMSG_WRONGVIF kernel signal at the (S,G) granularity if a multicast data packet arrives on the wrong interface. Usually, this signal is used to complete the shortest-path switch in case of PIM-SM multicast routing, or to trigger a PIM assert message. However, it should not be delivered for interfaces that are not in the outgoing interface set, and that are not expecting to become an incoming interface. Hence, if the .Dv MRT_MFC_FLAGS_DISABLE_WRONGVIF flag is set for some of the interfaces, then a data packet that arrives on that interface for that MFC entry will NOT trigger a WRONGVIF signal. If that flag is not set, then a signal is triggered (the default action). .Pp The .Dv MRT_MFC_FLAGS_BORDER_VIF flag is used to specify whether the Border-bit in PIM Register messages should be set (in case when the Register encapsulation is performed inside the kernel). If it is set for the special PIM Register kernel virtual interface (see .Xr pim 4 ) , the Border-bit in the Register messages sent to the RP will be set. .Pp The remaining six bits are reserved for future usage. .Pp The .Va mfcc_rp field is used to specify the RP address (in case of PIM-SM multicast routing) for a multicast group G if we want to perform kernel-level PIM Register encapsulation. The .Va mfcc_rp field is used only if the .Dv MRT_MFC_RP advanced API flag/capability has been successfully set by .Fn setsockopt MRT_API_CONFIG . .Pp .\" .\" 3. Kernel-level PIM Register encapsulation .\" If the .Dv MRT_MFC_RP flag was successfully set by .Fn setsockopt MRT_API_CONFIG , then the kernel will attempt to perform the PIM Register encapsulation itself instead of sending the multicast data packets to user level (inside .Dv IGMPMSG_WHOLEPKT upcalls) for user-level encapsulation. The RP address would be taken from the .Va mfcc_rp field inside the new .Vt "struct mfcctl2" . However, even if the .Dv MRT_MFC_RP flag was successfully set, if the .Va mfcc_rp field was set to .Dv INADDR_ANY , then the kernel will still deliver an .Dv IGMPMSG_WHOLEPKT upcall with the multicast data packet to the user-level process. .Pp In addition, if the multicast data packet is too large to fit within a single IP packet after the PIM Register encapsulation (e.g., if its size was on the order of 65500 bytes), the data packet will be fragmented, and then each of the fragments will be encapsulated separately. Note that typically a multicast data packet can be that large only if it was originated locally from the same hosts that performs the encapsulation; otherwise the transmission of the multicast data packet over Ethernet for example would have fragmented it into much smaller pieces. .\" .\" Note that if this code is ported to IPv6, we may need the kernel to .\" perform MTU discovery to the RP, and keep those discoveries inside .\" the kernel so the encapsulating router may send back ICMP .\" Fragmentation Required if the size of the multicast data packet is .\" too large (see "Encapsulating data packets in the Register Tunnel" .\" in Section 4.4.1 in the PIM-SM spec .\" draft-ietf-pim-sm-v2-new-05.{txt,ps}). .\" For IPv4 we may be able to get away without it, but for IPv6 we need .\" that. .\" .\" 4. Mechanism for "multicast bandwidth monitoring and upcalls". .\" .Pp Typically, a multicast routing user-level process would need to know the forwarding bandwidth for some data flow. For example, the multicast routing process may want to timeout idle MFC entries, or in case of PIM-SM it can initiate (S,G) shortest-path switch if the bandwidth rate is above a threshold for example. .Pp The original solution for measuring the bandwidth of a dataflow was that a user-level process would periodically query the kernel about the number of forwarded packets/bytes per (S,G), and then based on those numbers it would estimate whether a source has been idle, or whether the source's transmission bandwidth is above a threshold. That solution is far from being scalable, hence the need for a new mechanism for bandwidth monitoring. .Pp Below is a description of the bandwidth monitoring mechanism. .Bl -bullet .It If the bandwidth of a data flow satisfies some pre-defined filter, the kernel delivers an upcall on the multicast routing socket to the multicast routing process that has installed that filter. .It The bandwidth-upcall filters are installed per (S,G). There can be more than one filter per (S,G). .It Instead of supporting all possible comparison operations (i.e., < <= == != > >= ), there is support only for the <= and >= operations, because this makes the kernel-level implementation simpler, and because practically we need only those two. Further, the missing operations can be simulated by secondary user-level filtering of those <= and >= filters. For example, to simulate !=, then we need to install filter .Dq bw <= 0xffffffff , and after an upcall is received, we need to check whether .Dq measured_bw != expected_bw . .It The bandwidth-upcall mechanism is enabled by .Fn setsockopt MRT_API_CONFIG for the .Dv MRT_MFC_BW_UPCALL flag. .It The bandwidth-upcall filters are added/deleted by the new .Fn setsockopt MRT_ADD_BW_UPCALL and .Fn setsockopt MRT_DEL_BW_UPCALL respectively (with the appropriate .Vt "struct bw_upcall" argument of course). .El .Pp From application point of view, a developer needs to know about the following: .Bd -literal /* * Structure for installing or delivering an upcall if the * measured bandwidth is above or below a threshold. * * User programs (e.g. daemons) may have a need to know when the * bandwidth used by some data flow is above or below some threshold. * This interface allows the userland to specify the threshold (in * bytes and/or packets) and the measurement interval. Flows are * all packet with the same source and destination IP address. * At the moment the code is only used for multicast destinations * but there is nothing that prevents its use for unicast. * * The measurement interval cannot be shorter than some Tmin (currently, 3s). * The threshold is set in packets and/or bytes per_interval. * * Measurement works as follows: * * For >= measurements: * The first packet marks the start of a measurement interval. * During an interval we count packets and bytes, and when we * pass the threshold we deliver an upcall and we are done. * The first packet after the end of the interval resets the * count and restarts the measurement. * * For <= measurement: * We start a timer to fire at the end of the interval, and * then for each incoming packet we count packets and bytes. * When the timer fires, we compare the value with the threshold, * schedule an upcall if we are below, and restart the measurement * (reschedule timer and zero counters). */ struct bw_data { struct timeval b_time; uint64_t b_packets; uint64_t b_bytes; }; struct bw_upcall { struct in_addr bu_src; /* source address */ struct in_addr bu_dst; /* destination address */ uint32_t bu_flags; /* misc flags (see below) */ #define BW_UPCALL_UNIT_PACKETS (1 << 0) /* threshold (in packets) */ #define BW_UPCALL_UNIT_BYTES (1 << 1) /* threshold (in bytes) */ #define BW_UPCALL_GEQ (1 << 2) /* upcall if bw >= threshold */ #define BW_UPCALL_LEQ (1 << 3) /* upcall if bw <= threshold */ #define BW_UPCALL_DELETE_ALL (1 << 4) /* delete all upcalls for s,d*/ struct bw_data bu_threshold; /* the bw threshold */ struct bw_data bu_measured; /* the measured bw */ }; /* max. number of upcalls to deliver together */ #define BW_UPCALLS_MAX 128 /* min. threshold time interval for bandwidth measurement */ #define BW_UPCALL_THRESHOLD_INTERVAL_MIN_SEC 3 #define BW_UPCALL_THRESHOLD_INTERVAL_MIN_USEC 0 .Ed .Pp The .Vt bw_upcall structure is used as an argument to .Fn setsockopt MRT_ADD_BW_UPCALL and .Fn setsockopt MRT_DEL_BW_UPCALL . Each .Fn setsockopt MRT_ADD_BW_UPCALL installs a filter in the kernel for the source and destination address in the .Vt bw_upcall argument, and that filter will trigger an upcall according to the following pseudo-algorithm: .Bd -literal if (bw_upcall_oper IS ">=") { if (((bw_upcall_unit & PACKETS == PACKETS) && (measured_packets >= threshold_packets)) || ((bw_upcall_unit & BYTES == BYTES) && (measured_bytes >= threshold_bytes))) SEND_UPCALL("measured bandwidth is >= threshold"); } if (bw_upcall_oper IS "<=" && measured_interval >= threshold_interval) { if (((bw_upcall_unit & PACKETS == PACKETS) && (measured_packets <= threshold_packets)) || ((bw_upcall_unit & BYTES == BYTES) && (measured_bytes <= threshold_bytes))) SEND_UPCALL("measured bandwidth is <= threshold"); } .Ed .Pp In the same .Vt bw_upcall the unit can be specified in both BYTES and PACKETS. However, the GEQ and LEQ flags are mutually exclusive. .Pp Basically, an upcall is delivered if the measured bandwidth is >= or <= the threshold bandwidth (within the specified measurement interval). For practical reasons, the smallest value for the measurement interval is 3 seconds. If smaller values are allowed, then the bandwidth estimation may be less accurate, or the potentially very high frequency of the generated upcalls may introduce too much overhead. For the >= operation, the answer may be known before the end of .Va threshold_interval , therefore the upcall may be delivered earlier. For the <= operation however, we must wait until the threshold interval has expired to know the answer. .Pp Example of usage: .Bd -literal struct bw_upcall bw_upcall; /* Assign all bw_upcall fields as appropriate */ memset(&bw_upcall, 0, sizeof(bw_upcall)); memcpy(&bw_upcall.bu_src, &source, sizeof(bw_upcall.bu_src)); memcpy(&bw_upcall.bu_dst, &group, sizeof(bw_upcall.bu_dst)); bw_upcall.bu_threshold.b_data = threshold_interval; bw_upcall.bu_threshold.b_packets = threshold_packets; bw_upcall.bu_threshold.b_bytes = threshold_bytes; if (is_threshold_in_packets) bw_upcall.bu_flags |= BW_UPCALL_UNIT_PACKETS; if (is_threshold_in_bytes) bw_upcall.bu_flags |= BW_UPCALL_UNIT_BYTES; do { if (is_geq_upcall) { bw_upcall.bu_flags |= BW_UPCALL_GEQ; break; } if (is_leq_upcall) { bw_upcall.bu_flags |= BW_UPCALL_LEQ; break; } return (ERROR); } while (0); setsockopt(mrouter_s4, IPPROTO_IP, MRT_ADD_BW_UPCALL, (void *)&bw_upcall, sizeof(bw_upcall)); .Ed .Pp To delete a single filter, then use .Dv MRT_DEL_BW_UPCALL , and the fields of bw_upcall must be set exactly same as when .Dv MRT_ADD_BW_UPCALL was called. .Pp To delete all bandwidth filters for a given (S,G), then only the .Va bu_src and .Va bu_dst fields in .Vt "struct bw_upcall" need to be set, and then just set only the .Dv BW_UPCALL_DELETE_ALL flag inside field .Va bw_upcall.bu_flags . .Pp The bandwidth upcalls are received by aggregating them in the new upcall message: .Bd -literal #define IGMPMSG_BW_UPCALL 4 /* BW monitoring upcall */ .Ed .Pp This message is an array of .Vt "struct bw_upcall" elements (up to .Dv BW_UPCALLS_MAX = 128). The upcalls are delivered when there are 128 pending upcalls, or when 1 second has expired since the previous upcall (whichever comes first). In an .Vt "struct upcall" element, the .Va bu_measured field is filled-in to indicate the particular measured values. However, because of the way the particular intervals are measured, the user should be careful how .Va bu_measured.b_time is used. For example, if the filter is installed to trigger an upcall if the number of packets is >= 1, then .Va bu_measured may have a value of zero in the upcalls after the first one, because the measured interval for >= filters is .Dq clocked by the forwarded packets. Hence, this upcall mechanism should not be used for measuring the exact value of the bandwidth of the forwarded data. To measure the exact bandwidth, the user would need to get the forwarded packets statistics with the .Fn ioctl SIOCGETSGCNT mechanism (see the .Sx Programming Guide section) . .Pp Note that the upcalls for a filter are delivered until the specific filter is deleted, but no more frequently than once per .Va bu_threshold.b_time . For example, if the filter is specified to deliver a signal if bw >= 1 packet, the first packet will trigger a signal, but the next upcall will be triggered no earlier than .Va bu_threshold.b_time after the previous upcall. .\" .Sh SEE ALSO -.Xr altq 4 , -.Xr dummynet 4 , .Xr getsockopt 2 , -.Xr gif 4 , -.Xr gre 4 , .Xr recvfrom 2 , .Xr recvmsg 2 , .Xr setsockopt 2 , .Xr socket 2 , .Xr sourcefilter 3 , +.Xr altq 4 , +.Xr dummynet 4 , +.Xr gif 4 , +.Xr gre 4 , .Xr icmp6 4 , .Xr igmp 4 , .Xr inet 4 , .Xr inet6 4 , .Xr intro 4 , .Xr ip 4 , .Xr ip6 4 , .Xr mld 4 , .Xr pim 4 .\" .Sh HISTORY The Distance Vector Multicast Routing Protocol (DVMRP) was the first developed multicast routing protocol. Later, other protocols such as Multicast Extensions to OSPF (MOSPF) and Core Based Trees (CBT), were developed as well. Routers at autonomous system boundaries may now exchange multicast routes with peers via the Border Gateway Protocol (BGP). Many other routing protocols are able to redistribute multicast routes for use with .Dv PIM-SM and .Dv PIM-DM . .Sh AUTHORS .An -nosplit The original multicast code was written by .An David Waitzman (BBN Labs), and later modified by the following individuals: .An Steve Deering (Stanford), .An Mark J. Steiglitz (Stanford), .An Van Jacobson (LBL), .An Ajit Thyagarajan (PARC), .An Bill Fenner (PARC). The IPv6 multicast support was implemented by the KAME project .Pq Pa http://www.kame.net , and was based on the IPv4 multicast code. The advanced multicast API and the multicast bandwidth monitoring were implemented by .An Pavlin Radoslavov (ICSI) in collaboration with .An Chris Brown (NextHop). The IGMPv3 and MLDv2 multicast support was implemented by .An Bruce Simpson . .Pp This manual page was written by .An Pavlin Radoslavov (ICSI). Index: head/share/man/man4/net80211.4 =================================================================== --- head/share/man/man4/net80211.4 (revision 275989) +++ head/share/man/man4/net80211.4 (revision 275990) @@ -1,1318 +1,1318 @@ .\"- .\" Copyright (c) 2009 Sam Leffler, Errno Consulting .\" All rights reserved. .\"" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer, .\" without modification. .\" 2. Redistributions in binary form must reproduce at minimum a disclaimer .\" similar to the "NO WARRANTY" disclaimer below ("Disclaimer") and any .\" redistribution must be conditioned upon including a substantially .\" similar Disclaimer requirement for further binary redistribution. .\" .\" NO WARRANTY .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT .\" LIMITED TO, THE IMPLIED WARRANTIES OF NONINFRINGEMENT, MERCHANTIBILITY .\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL .\" THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, .\" OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS .\" INTERRUPTION) HOWEVER CAUSED AND ON 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 ADVISED OF .\" THE POSSIBILITY OF SUCH DAMAGES. .\" .\" $FreeBSD$ .\" .Dd July 10, 2009 .Dt NET80211 4 .Os .Sh NAME .Nm net80211 .Nd standard interface to IEEE 802.11 devices .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .In net/if.h .In net/ethernet.h .In net80211/ieee80211_ioctl.h .Sh DESCRIPTION This section describes the standard programming interface to configure and retrieve status information for IEEE 802.11 devices that depend on the .Xr wlan 4 module for operation. The interface is via one of the following .Xr ioctl 2 calls on a socket: .Bl -tag -width ".Dv SIOCG80211" .It Dv SIOCG80211 Get configuration or status information. .It Dv SIOCS80211 Set configuration information. .El .Pp These requests are made via a modified .Vt ifreq structure. This structure is defined as follows: .Bd -literal struct ieee80211req { char i_name[IFNAMSIZ]; /* if_name, e.g. "wi0" */ uint16_t i_type; /* req type */ int16_t i_val; /* Index or simple value */ int16_t i_len; /* Index or simple value */ void *i_data; /* Extra data */ }; .Ed .Pp Requests that are not supported by the underlying device return -1 and set the global variable errno to .Er EOPNOTSUPP . .Dv SIOCG80211 requests that return data to an application place small values in .Va i_val or in a user-specified buffer pointed to by .Va i_data . When an indirect buffer is used .Va i_len specifies how large the indirect buffer is and on return it is set by the system to the actual amount of data returned. .Dv SIOCS80211 requests use a similar scheme with data passed to the system taken either from .Va i_val or an indirect buffer pointed to by .Va i_data . .Pp For .Dv SIOCG80211 the following values of .Va i_type are valid: .Bl -tag -width indent .It Dv IEEE80211_IOC_AMPDU Return whether or not AMPDU is enabled in .Va i_val . AMPDU is an aggregation scheme that is part of the 802.11n specification and is used only when operating on an HT channel. The value returned is one of: 0 (AMPDU disabled), 1 (AMPDU enabled for transmit), 2 (AMPDU enabled for receive), and 3 (AMPDU enabled for transmit and receive). The 802.11n specification says a compliant station must receive AMPDU but may not support transmitting AMPDU frames. Disabling AMPDU receive is mainly useful for testing and working around bugs. .It Dv IEEE80211_IOC_AMPDU_DENSITY Return the minimum density for bursting AMPDU frames in .Va i_val . The value returned is one of: 0 (no time restriction), 1 (1/4 usec), 2 (1/2 usec), 3 (1 usec), 4 (2 usec), 5 (4 usec), 6 (8 usec), and 7 (16 usec). .It Dv IEEE80211_IOC_AMPDU_LIMIT Return the limit on the size of AMPDU frames in .Va i_val . The value returned is one of: 0 (8 kilobytes), 1 (16 kilobytes), 2 (32 kilobytes), and 3 (64 kilobytes). .It Dv IEEE80211_IOC_AMSDU Return whether or not AMSDU is enabled in .Va i_val . AMSDU is an aggregation scheme that is part of the 802.11n specification and is used only when operating on an HT channel. The value returned is one of: 0 (AMSDU disabled), 1 (AMSDU enabled for transmit), 2 (AMSDU enabled for receive), and 3 (AMSDU enabled for transmit and receive). The 802.11n specification says a compliant station must receive AMSDU but may not support transmitting AMSDU frames. Disabling AMSDU receive is mainly useful for testing and working around bugs. .It Dv IEEE80211_IOC_AMSDU_LIMIT Return the limit on the size of AMSDU frames in .Va i_val . The value returned is one of: 3839 (bytes) and 7935 (bytes). Note these values are specified by 802.11n; arbitrary values are not allowed. .It Dv IEEE80211_IOC_APBRIDGE Return whether AP bridging is enabled in .Va i_val . Normally packets sent between stations associated to the same access point are delivered without going through system layers that do packet filtering; when AP bridging is disabled packets are passed up the system to be forwarded using some other mechanism. This value will be non-zero when AP bridging is enabled and otherwise zero. .It Dv IEEE80211_IOC_APPIE Return an application information element via .Va i_data . Application IE's are maintained for many 802.11 frames; the request must identify the frame to return an IE for in .Va i_val . For example, to retrieve the IE sent in each Beacon frame .Va i_val would be set to .Va IEEE80211_FC0_SUBTYPE_BEACON | IEEE80211_FC0_TYPE_MGT . If no information element is installed then .Er EINVAL is returned. If the data buffer for returning data is too small to hold the information element the value is truncated; this permits querying the presence of data by requesting zero bytes of data be returned. .It Dv IEEE80211_IOC_AUTHMODE Return the current authentication mode in .Va i_val . Valid values are .Dv IEEE80211_AUTH_NONE (no authentication), .Dv IEEE80211_AUTH_OPEN (open authentication), .Dv IEEE80211_AUTH_SHARED (shared key authentication), .Dv IEEE80211_AUTH_8021X (802.1x only authentication), and .Dv IEEE80211_AUTH_WPA (WPA/802.11i/802.1x authentication). .It Dv IEEE80211_IOC_BEACON_INTERVAL Return the time between Beacon frames (in TU) in .Va i_val . .It Dv IEEE80211_IOC_BGSCAN Return whether background scanning is enabled in .Va i_val . When this value is non-zero and operating in station mode the station will periodically leave the current channel and scan for neighboring stations. See also .Dv IEEE80211_IOC_BGSCAN_IDLE and .Dv IEEE80211_IOC_BGSCAN_INTERVAL . .It Dv IEEE80211_IOC_BGSCAN_IDLE Return in .Va i_val the minimum time (msecs) a station must be idle (i.e. not transmitting or receiving frames) before it will do a background scan. See also .Dv IEEE80211_IOC_BGSCAN_INTERVAL . .It Dv IEEE80211_IOC_BGSCAN_INTERVAL Return in .Va i_val the minimum time (seconds) between background scan operations. See also .Dv IEEE80211_IOC_BGSCAN_IDLE . .It Dv IEEE80211_IOC_BMISSTHRESHOLD Return in .Va i_val the number of consecutive missed Beacon frames before the system will attempt to roam to a different/better access point. .It Dv IEEE80211_IOC_BSSID Return the MAC address for the current BSS identifier via .Va i_data . When the interface is running, the bssid is either the value configured locally (e.g. for an IBSS network started by the local station) or the value adopted when joining an existing network. For WDS interfaces this value is the address of the remote station. When the interface is not running, the bssid returned is the desired bssid, if any, that has been configured. .It Dv IEEE80211_IOC_BURST Return whether or not packet bursting is enabled in .Va i_val . If this value is non-zero then the system will try to send packets closely spaced to improve throughput. .It Dv IEEE80211_IOC_CHANINFO Return the set of available channels via .Va i_data . Note this data should be used by user applications to map between channel specifications (frequency and attributes) and IEEE channel numbers as user applications may not have the necessary information to do this directly (e.g. for 900MHz radios, operation in the Public Safety Band). .It Dv IEEE80211_IOC_CHANLIST Return the current list of usable channels via .Va i_data . The channel list is returned as a bit vector with bit N set to 1 if IEEE channel number N is available for use. .It Dv IEEE80211_IOC_CHANNEL Return the IEEE channel number of the current channel in .Va i_val . Note this request is deprecated; use .Dv IEEE80211_IOC_CURCHAN instead. .It Dv IEEE80211_IOC_COUNTERMEASURES Return whether TKIP Countermeasures are enabled in .Va i_val . This value will be non-zero when Countermeasures are enabled and otherwise zero. .It Dv IEEE80211_IOC_CURCHAN Return information for the current channel via .Va i_data . This information includes the IEEE channel number, the frequency, and attributes that describe the operating constraints (e.g. Passive Scan, DFS, usage restrictions). .It Dv IEEE80211_IOC_DEVCAPS Return device capabilities in the data buffer pointed at by .Va i_data . The buffer must be large enough to return the number of available channels but otherwise may be made small to limit how much information is returned. .It Dv IEEE80211_IOC_DFS Return whether or not Dynamic Frequency Selection (DFS) is enabled in .Va i_val . DFS embodies several facilities including detection of overlapping radar signals, dynamic transmit power control, and channel selection according to a least-congested criteria. DFS support is mandatory for some 5GHz frequencies in certain locales (e.g. ETSI). By default DFS is enabled according to the regulatory definitions and the current country code, regdomain, and channel. .It Dv IEEE80211_IOC_DOTD Return whether or not 802.11d support is enabled in .Va i_val . When 802.11d is enabled in station mode, Beacon frames that advertise a country code different than the currently configured country code will cause an event to be dispatched to user applications. This event can be used by the station to adopt that country code and operate according to the associated regulatory constraints. When operating as an access point with 802.11d enabled the Beacon and ProbeResponse frames transmitted will advertise the current regulatory domain settings. .It Dv IEEE80211_IOC_DOTH Return whether 802.11h support is enabled in .Va i_val . When 802.11h is enabled Beacon and ProbeResponse frames will have the SpectrumMgt bit set in the capabilities field and country and power constraint information elements will be present. 802.11h support also includes handling Channel Switch Announcements (CSA) which are a mechanism to coordinate channel changes by an access point. By default 802.11h is enabled if the device is capable. .It Dv IEEE80211_IOC_DROPUNENCRYPTED Return, in .Va i_val , whether unencrypted packets transmit/received should be discarded. This value will be zero if unencrypted packets will be accepted and non-zero if they are to be discarded. .It Dv IEEE80211_IOC_DTIM_PERIOD Return the period (in beacon intervals) between DTIM events in .Va i_val . .It Dv IEEE80211_IOC_DWDS Return, in .Va i_val , whether or not Dynamic WDS support is enabled. Dynamic WDS is a facility by which packets may be tunneled over normal Infrastructure BSS associations using 4-address (WDS) frames. .It Dv IEEE80211_IOC_FF Return, in .Va i_val , whether Atheros fast-frames support is enabled. Fast-frames is a non-standard protocol extension that aggregates multiple frames to improve throughput. Note that enabling fast-frames support does not guarantee use; the client and access point must negotiate its use. .It Dv IEEE80211_IOC_FRAGTHRESHOLD Return, in .Va i_val , the threshold (in bytes) for enabling fragmentation frames. Packets larger than this value will automatically be split into multiple fragmented frames that are sent one after the other. .It Dv IEEE80211_IOC_GREENFIELD Return, in .Va i_val , whether or not Greenfield preamble use is enabled. This setting is meaningful only when operating with 802.11n on an HT channel. .It Dv IEEE80211_IOC_HIDESSID Return, in .Va i_val , whether SSID hiding/cloaking is enabled. SSID hiding is only meaningful when operating as an access point. When this is enabled Beacon frames do not include the SSID and ProbeRequest frames are not answered unless they include the AP's SSID. This value will be non-zero when SSID hiding is enabled and otherwise zero. .It Dv IEEE80211_IOC_HTCOMPAT Return, in .Va i_val , whether or not 802.11n compatibility support is enabled. The 802.11n protocol specification went through several incompatible iterations. Some vendors implemented 11n support to older specifications that will not interoperate with a purely 11n-compliant station. In particular the information elements included in management frames for old devices are different. When compatibility support is enabled both standard and compatible data will be provided and/or accepted. .It Dv IEEE80211_IOC_HTCONF Return the setting for automatic promotion of HT channels in .Va i_val . Promotion happens when the system must select a channel and may choose between legacy, HT20, and HT40 operation (e.g. when scanning). Valid values are: 0 (do not promote, use legacy), 1 (promote to HT20), and 2 (promote to HT40). .It Dv IEEE80211_IOC_HTPROTMODE Return, in .Va i_val , the technique used to protect HT frames in a mixed 802.11n network. Valid values are: .Dv IEEE80211_PROTMODE_OFF (no protection enabled) and .Dv IEEE80211_PROTMODE_RTSCTS (send RTS and wait for CTS). .It Dv IEEE80211_IOC_HWMP_MAXHOPS Return the maximum acceptable hop count in an HWMP path in .Va i_val . .It Dv IEEE80211_IOC_HWMP_ROOTMODE Return the setting for Mesh root mode operation in .Va i_val . Valid values are: .Dv IEEE80211_HWMP_ROOTMODE_DISABLED (root mode is disabled), .Dv IEEE80211_HWMP_ROOTMODE_NORMAL (send broadcast Path Request frames), .Dv IEEE80211_HWMP_ROOTMODE_PROACTIVE (send broadcast Path Request frames and force replies) and .Dv IEEE80211_HWMP_ROOTMODE_RANN (send broadcast Root Announcement (RANN) frames). .It Dv IEEE80211_IOC_INACTIVITY Return whether or not the system handles inactivity processing in .Va i_val . When inactivity processing is enabled the system will track stations that have not transmitted frames and periodically probe them to check if they are still present. Stations that are inactive and do not respond to probes are dropped. .It Dv IEEE80211_IOC_MACCMD Return information about the state of the MAC address access control list (ACL) system. There are two requests supported: .Dv IEEE80211_MACCMD_POLICY (to retrieve the current policy in .Va i_val ), and .Dv IEEE80211_MACCMD_LIST to retrieve the list installed/active ACL's via .Va i_data . The .Xr wlan_acl 4 module must be installed and enabled or .Er EINVAL will be returned. .It Dv IEEE80211_IOC_MESH_AP Return whether or not Mesh AP support is enabled in .Va i_val . .It Dv IEEE80211_IOC_MESH_ID Return the Mesh ID in the buffer pointed to by .Va i_data . .It Dv IEEE80211_IOC_MESH_FWRD Return whether or not packet forwarding support is enabled in .Va i_val . .It Dv IEEE80211_IOC_MESH_PP_METRIC Return the link metric protocol in the buffer pointed to by .Va i_data . .It Dv IEEE80211_IOC_MESH_PP_PATH Return the path selection protocol in the buffer pointed to by .Va i_data . .It Dv IEEE80211_IOC_MESH_RTCMD Return information about the state of the Mesh routing tables. One request is supported: .Dv IEEE80211_MESH_RTCMD_LIST to retrieve the contents of the routing table in the buffer pointed to by .Va i_data . .It Dv IEEE80211_IOC_MESH_TTL Return, in .Va i_val , the Mesh Time To Live (TTL) setting installed in packets transmitted by this mesh node. .It Dv IEEE80211_IOC_NUMSSIDS Return the number of SSIDs supported in .Va i_val . .It Dv IEEE80211_IOC_NUMWEPKEYS Return the number of WEP keys supported in .Va i_val . .It Dv IEEE80211_IOC_POWERSAVE Return the current powersaving mode in .Va i_val . Valid values are .Dv IEEE80211_POWERSAVE_OFF (power save operation is disabled) and .Dv IEEE80211_POWERSAVE_ON (power save operation is enabled). .It Dv IEEE80211_IOC_POWERSAVESLEEP Return the powersave sleep time in TU in .Va i_val . This value is also termed the listen interval and represents the maximum time a station will sleep before waking to retrieve packets buffered by an access point. .It Dv IEEE80211_IOC_PRIVACY Return the current MLME setting for PRIVACY in .Va i_val . When PRIVACY is enabled all data packets must be encrypted. This value will be zero if PRIVACY is disabled and non-zero when PRIVACY is enabled. .It Dv IEEE80211_IOC_PROTMODE Return the current 802.11g protection mode in .Va i_val . Protection is the mechanism used to safeguard 802.11b stations operating on an 802.11g network. Valid values are .Dv IEEE80211_PROTMODE_OFF (no protection enabled), .Dv IEEE80211_PROTMODE_CTS (send CTS to yourself), and .Dv IEEE80211_PROTMODE_RTSCTS (send RTS and wait for CTS). .It Dv IEEE80211_IOC_PUREG Return whether ``pure 11g'' mode is enabled in .Va i_val . This setting is meaningful only for access point operation; when non-zero, 802.11b stations will not be allowed to associate. .It Dv IEEE80211_IOC_PUREN Return whether ``pure 11n'' mode is enabled in .Va i_val . This setting is meaningful only for access point operation; when non-zero, legacy (non-11n capable) stations will not be allowed to associate. .It Dv IEEE80211_IOC_REGDOMAIN Return the regulatory state in the buffer pointed to by .Va i_data . .It Dv IEEE80211_IOC_RIFS Return whether or not Reduced InterFrame Spacing (RIFS) is enabled in .Va i_val . This setting is meaningful only when operating with 802.11n on an HT channel. .It Dv IEEE80211_IOC_ROAM Return station roaming parameters in the buffer pointed to by .Va i_data . .It Dv IEEE80211_IOC_ROAMING Return the current roaming mode in .Va i_val . Roaming mode specifies which entity controls operation of the MLME state machine when operating as a station in an Infrastructure BSS. Valid values are: .Dv IEEE80211_ROAMING_DEVICE (driver/firmware is in control), .Dv IEEE80211_ROAMING_AUTO (host 802.11 layer is in control), and .Dv IEEE80211_ROAMING_MANUAL (application is in control). .It Dv IEEE80211_IOC_RTSTHRESHOLD Return the threshold (in bytes) for enabling transmission of RTS frames in .Va i_val . Packets larger than this value will automatically have an RTS frame sent preceding it to reduce the likelihood of packet loss. .It Dv IEEE80211_IOC_SCAN_RESULTS Return the current contents of the scan cache in the data area pointed to by .Va i_data . .It Dv IEEE80211_IOC_SCANVALID Return in .Va i_val how long (in seconds) results from a scan operation will be considered valid. When scan results are no longer valid and they are needed (e.g. to roam) the system will initiate a scan operation to replenish the scan cache. .It Dv IEEE80211_IOC_SHORTGI Return whether or not Short Guard Interval (SGI) is enabled in .Va i_val . Note SGI is only used when operating with 802.11n on an HT channel. .It Dv IEEE80211_IOC_SMPS Return the Spatial Multiplexing Power Save (SMPS) setting in .Va i_val . This setting is meaningful only when operating with 802.11n on an HT channel. Valid values are: .Dv IEEE80211_HTCAP_SMPS_DYNAMIC (Dynamic SMPS is enabled), .Dv IEEE80211_HTCAP_SMPS_ENA (Static SMPS is enabled), and .Dv IEEE80211_HTCAP_SMPS_OFF (SMPS is disabled). .It Dv IEEE80211_IOC_SSID Return the requested SSID in the buffer pointed to by .Va i_data . If .Va i_val is \(>= 0 then the request refers to the configured value for that slot. Generally, 0 is the only valid value, but some interfaces support more SSIDs. .It Dv IEEE80211_IOC_STA_INFO Return information about the current state of the specified station(s) via .Va i_data . The MAC address of a single station may be passed in or, if the broadcast address is supplied, information about all stations will be returned. If a single station is requested and the MAC address is unknown then .Er ENOENT will be returned. .It Dv IEEE80211_IOC_STA_STATS Return collected statistics for the specified station via .Va i_data . The MAC address of the desired station is passed in; if it is unknown .Er ENOENT will be returned. .It Dv IEEE80211_IOC_STA_VLAN Return any VLAN tag assigned to a station via .Va i_data . .It Dv IEEE80211_IOC_TDMA_SLOT Return the slot number for the station in .Va i_val . Slot number zero is the master station in a TDMA network. .It Dv IEEE80211_IOC_TDMA_SLOTCNT Return the count of slots in the TDMA network in .Va i_val . .It Dv IEEE80211_IOC_TDMA_SLOTLEN Return the length (in usecs) of the TDMA slot assigned to each station in the network in .Va i_val . .It Dv IEEE80211_IOC_TDMA_BINTERVAL Return the number of superframes between Beacon frames in .Va i_val . A TDMA network with N slots and slot length T has a superframe of NxT. .It Dv IEEE80211_IOC_TSN Return whether or not Transitional Security Network (TSN) is enabled in .Va i_val . .It Dv IEEE80211_IOC_TURBOP Return whether Atheros Dynamic Turbo mode is enabled in .Va i_val . Dynamic Turbo mode is a non-standard protocol extension available only on Atheros devices where channel width is dynamically changed between 20MHz and 40MHz. Note that enabling Dynamic Turbo mode support does not guarantee use; both client and access point must use Atheros devices and support must be enabled on both sides. .It Dv IEEE80211_IOC_TXPARAMS Return transmit parameters in the buffer pointed to by .Va i_data . .It Dv IEEE80211_IOC_TXPOWER Return the transmit power limit in .5 dBm units in .Va i_val . This value represents the effective maximum and is calculated according to the maximum power allowed by local regulations, any user-specified power limit, and the maximum power the device is capable of. .It Dv IEEE80211_IOC_TXPOWMAX Return the user-specified maximum transmit power in .5 dBm units in .Va i_val . The maximum setting is applied after any regulatory cap. .It Dv IEEE80211_IOC_WEP Return the current WEP status in .Va i_val . Valid values are: .Dv IEEE80211_WEP_ON (enabled for all packets sent and received), .Dv IEEE80211_WEP_OFF (disabled), and .Dv IEEE80211_WEP_MIXED (enabled for transmit and receive but also willing to receive unencrypted frames). This request is deprecated; use .Dv IEEE80211_IOC_PRIVACY and .Dv IEEE80211_IOC_UNENCRYPTED instead. .It Dv IEEE80211_IOC_WEPKEY Return the requested WEP key via .Va i_data . The key number is specified in .Va i_val and may be 0-3. If the device does not support returning the WEP key or the user is not root then the key may be returned as all zeros. This request is deprecated in favor of .Dv IEEE80211_IOC_WPAKEY . .It Dv IEEE80211_IOC_WEPTXKEY Return the number of the WEP key used for transmission in .Va i_val . .It Dv IEEE80211_IOC_WME Return whether 802.11e/WME/WMM support is enabled in .Va i_val . This value will be non-zero when support is enabled and otherwise zero. .It Dv IEEE80211_IOC_WME_CWMIN Return the WME CWmin setting (log2) for the specified Access Class (AC) in .Va i_val . The AC is passed in through .Va i_len together with an optional IEEE80211_WMEPARAM_BSS flag to indicate if the parameter for the BSS or the channel is desired. If WME is not supported then .Er EINVAL will be returned. .It Dv IEEE80211_IOC_WME_CWMAX Return the WME CWmax setting (log2) for the specified Access Class (AC) in .Va i_val . See .Dv IEEE80211_IOC_WME_CWMIN above for more details. .It Dv IEEE80211_IOC_WME_AIFS Return the WME AIFS setting for the specified Access Class (AC) in .Va i_val . See .Dv IEEE80211_IOC_WME_CWMIN above for more details. .It Dv IEEE80211_IOC_WME_TXOPLIMIT Return the WME TxOpLimit (msec) for the specified Access Class (AC) in .Va i_val . See .Dv IEEE80211_IOC_WME_CWMIN above for more details. .It Dv IEEE80211_IOC_WME_ACM Return the WME Admission Control Mechanism (ACM) setting for the specified Access Class (AC) in .Va i_val . This value is meaningful only for the BSS (not channel). See .Dv IEEE80211_IOC_WME_CWMIN above for more details. .It Dv IEEE80211_IOC_WME_ACKPOLICY Return the WME ACK Policy setting for the specified Access Class (AC) in .Va i_val . When this value is zero frames will be transmitted without waiting for an Acknowledgement. This value is meaningful only for the channel (not BSS). See .Dv IEEE80211_IOC_WME_CWMIN above for more details. .It Dv IEEE80211_IOC_WPA Return the WPA configuration in .Va i_val . Valid values are 0 (WPA is not enabled), 1 (WPA1 is enabled), 2 (WPA2/802.11i is enabled), and 3 (WPA1 and WPA2/802.11i are both enabled). .It Dv IEEE80211_IOC_WPAIE Return any WPA information element for an associated station via .Va i_data . The request passed in through .Va i_data identifies the MAC address of the desired station. If an RSN (802.11i) element is present it is returned; otherwise any WPA element is returned. Note this request is deprecated; use .Dv IEEE80211_IOC_WPAIE2 instead. .It Dv IEEE80211_IOC_WPAIE2 Return any WPA information elements for an associated station via .Va i_data . The request passed in through .Va i_data identifies the MAC address of the desired station. One or both of RSN (802.11i) and WPA elements may be returned. .It Dv IEEE80211_IOC_WPAKEY Return the requested cryptographic key in the buffer pointed to by .Va i_data . The key number is specified in .Va i_val and may be 0-3. A key number of zero is used to retrieve a station's unicast cipher key when operating with WPA enabled. If the user is not root then the key data returned is all zeros. .It Dv IEEE80211_IOC_WPS Return whether or not Wi-FI Protected Setup (WPS) is enabled in .Va i_val . .El .Pp For .Dv SIOCS80211 the following values of .Va i_type are valid. Note that changing a value on an interface that is running may cause the interface to be .Sq reset . Resets may be handled without altering the state if the parameter does not affect the MLME state (e.g. RTS threshold), but in some cases the interface may need to scan for a new network or clear state (including any associated stations); in that case the interface is said to be .Sq restarted (it is equivalent to marking the interface down and back up). The information below identifies whether changing a value affects the state of a running interface. .Bl -tag -width indent .It Dv IEEE80211_IOC_ADDMAC Add an entry to the MAC address Access Control List (ACL) database using the value pointed to by .Va i_data . The .Xr wlan_acl 4 module must be installed and enabled or .Er EINVAL will be returned. .It Dv IEEE80211_IOC_AMPDU Set whether or not AMPDU is enabled for transmit and/or receive using the value in .Va i_val . This request causes a running interface operating on an HT channel to be reset. See .Dv IEEE80211_IOC_AMPDU above for details. .It Dv IEEE80211_IOC_AMPDU_DENSITY Set the minimum density for bursting AMPDU frames to the value in .Va i_val . This request causes a running interface to be reset. See .Dv IEEE80211_IOC_AMPDU_DENSITY above for details. .It Dv IEEE80211_IOC_AMPDU_LIMIT Set the limit on the size of AMPDU frames to the value in .Va i_val . This request causes a running interface to be reset. See .Dv IEEE80211_IOC_AMPDU_LIMIT above for details. .It Dv IEEE80211_IOC_AMSDU Set whether or not AMSDU is enabled for transmit and/or receive using the value in .Va i_val . This request causes a running interface operating on an HT channel to be reset. See .Dv IEEE80211_IOC_AMSDU above for details. .It Dv IEEE80211_IOC_AMSDU_LIMIT Set the limit on the size of AMSDU frames to the value in .Va i_val . This request causes a running interface to be reset. See .Dv IEEE80211_IOC_AMSDU_LIMIT above for details. .It Dv IEEE80211_IOC_APBRIDGE Set whether AP bridging is enabled using the value in .Va i_val . See .Dv IEEE80211_IOC_APBRIDGE above for details. .It Dv IEEE80211_IOC_APPIE Set an application information element using the data pointed to by .Va i_data . This request causes a running interface to be restarted if the WPA information element is changed. See .Dv IEEE80211_IOC_APPIE above for details. .It Dv IEEE80211_IOC_AUTHMODE Set the current authentication mode using the value in .Va i_val . This request causes a running interface to be restarted. See .Dv IEEE80211_IOC_AUTHMODE above for details. This request causes a running interface to be restarted. .It Dv IEEE80211_IOC_BEACON_INTERVAL Set the time between Beacon frames (in TU) to the value in .Va i_val . This request causes a running interface to be restarted. .It Dv IEEE80211_IOC_BGSCAN Set whether background scanning is enabled using the value in .Va i_val . .It Dv IEEE80211_IOC_BGSCAN_IDLE Set the minimum time (in msecs) a station must be idle before it will do a background scan to the value in .Va i_val . .It Dv IEEE80211_IOC_BGSCAN_INTERVAL Set the minimum time (seconds) between background scan operations to the value in .Va i_val . .It Dv IEEE80211_IOC_BMISSTHRESHOLD Set the number of consecutive missed Beacon frames before the system will attempt to roam to the value in .Va i_val . This request causes a running interface to be reset. .It Dv IEEE80211_IOC_BSSID Set the 802.11 MAC address for the desired BSS identifier according to .Va i_data . This request causes a running interface to be restarted. .It Dv IEEE80211_IOC_BURST Set whether or not packet bursting is enabled using the value in .Va i_val . This request causes a running interface to be reset. .It Dv IEEE80211_IOC_CHANNEL Set the desired/current channel to the value given by .Va i_val . This request causes a running interface to immediately change to the specified channel if possible; otherwise the interface will be restarted. Note this request is deprecated; use .Dv IEEE80211_IOC_CURCHAN instead. .It Dv IEEE80211_IOC_CHANLIST Set the list of available channels using the channel list pointed to by .Va i_data . The channel list is a bit vector with bit N set to 1 if IEEE channel number N is available for use. The specified channel list is checked against the set of supported channels and any channels not supported are silently ignored. If the intersection of the channel list and the supported channels is empty .Er EINVAL is returned. Note the current channel may be marked invalid after installing a new channel list. This request causes a running interface to be restarted. .It Dv IEEE80211_IOC_COUNTERMEASURES Set whether TKIP Countermeasures are enabled using the value in .Va i_val . This request can only be used when the authentication mode is set WPA; otherwise .Er EOPNOTSUPP will be returned. .It Dv IEEE80211_IOC_CURCHAN Set the current channel using the information referenced by .Va i_data . This request causes a running interface to immediately change to the specified channel if possible; otherwise the interface will be restarted. .It Dv IEEE80211_IOC_DELKEY Delete the key specified by the information referenced by .Va i_data . .It Dv IEEE80211_IOC_DELMAC Remove an entry in the MAC address Access Control List (ACL) database using the value pointed to by .Va i_data . The .Xr wlan_acl 4 module must be installed and enabled or .Er EINVAL will be returned. .It Dv IEEE80211_IOC_DFS Set whether or not Dynamic Frequency Selection (DFS) is enabled using the value in .Va i_val . This request will fail with .Er EINVAL if 802.11h support is not enabled. See .Dv IEEE80211_IOC_DFS above for details. .It Dv IEEE80211_IOC_DOTD Set whether or not 802.11d support is enabled using the value in .Va i_val . This request causes a running interface to be restarted. See .Dv IEEE80211_IOC_DOTD above for details. .It Dv IEEE80211_IOC_DOTH Return whether 802.11h support is enabled using the value in .Va i_val . See .Dv IEEE80211_IOC_DOTH above for details. .It Dv IEEE80211_IOC_DROPUNENCRYPTED Set whether unencrypted packets transmit/received should be discarded using the value in .Va i_val . .It Dv IEEE80211_IOC_DTIM_PERIOD Set the period (in beacon intervals) between DTIM events to the value in .Va i_val . This request causes a running interface to be restarted. .It Dv IEEE80211_IOC_DWDS Set whether or not Dynamic WDS support is enabled using the value in .Va i_val . See .Dv IEEE80211_IOC_DWDS above for details. .It Dv IEEE80211_IOC_FF Set whether Atheros fast-frames support is enabled using the value in .Va i_val . This request causes a running interface to be restarted. See .Dv IEEE80211_IOC_FF above for details. .It Dv IEEE80211_IOC_FRAGTHRESHOLD Set the threshold (in bytes) for enabling fragmentation frames using the value in .Va i_val . This request causes a running interface to be reset. See .Dv IEEE80211_IOC_FRAGTHRESHOLD above for details. .It Dv IEEE80211_IOC_GREENFIELD Set whether or not Greenfield preamble use is enabled using the value in .Va i_val . This request causes a running interface to be reset. See .Dv IEEE80211_IOC_GREENFIELD above for details. .It Dv IEEE80211_IOC_HIDESSID Set whether SSID hiding/cloaking is enabled using the value in .Va i_val . This request causes a running interface to be reset. See .Dv IEEE80211_IOC_HIDESSID above for details. .It Dv IEEE80211_IOC_HTCOMPAT Set whether or not 802.11n compatibility support is enabled using the value in .Va i_val . This request causes a running interface to be reset if operating on HT channel. See .Dv IEEE80211_IOC_HTCOMPAT above for details. .It Dv IEEE80211_IOC_HTCONF Set automatic promotion of HT channels using the value in .Va i_val . This request causes a running interface to be restarted. See .Dv IEEE80211_IOC_HTCONF above for details. .It Dv IEEE80211_IOC_HTPROTMODE Set the technique used to protect HT frames in a mixed 802.11n network using the value in .Va i_val . This request causes a running interface to be reset. See .Dv IEEE80211_IOC_HTPROTMODE above for details. .It Dv IEEE80211_IOC_HWMP_MAXHOPS Set the maximum acceptable hop count in an HWMP path according to .Va i_val . Values must be in the range [0-255]. .It Dv IEEE80211_IOC_HWMP_ROOTMODE Set the Mesh root mode operation according to .Va i_val . Valid values are .Dv IEEE80211_HWMP_ROOTMODE_DISABLED (root mode is disabled), .Dv IEEE80211_HWMP_ROOTMODE_NORMAL (send broadcast Path Request frames), .Dv IEEE80211_HWMP_ROOTMODE_PROACTIVE (send broadcast Path Request frames and force replies) and .Dv IEEE80211_HWMP_ROOTMODE_RANN (send broadcast Root Announcement (RANN) frames). .It Dv IEEE80211_IOC_INACTIVITY Set whether or not the system handles inactivity processing using the value in .Va i_val . When inactivity processing is enabled the system will track stations that have not transmitted frames and periodically probe them to check if they are still present. Stations that are inactive and do not respond to probes are dropped. .It Dv IEEE80211_IOC_MACCMD Change the state of the MAC address Access Control List (ACL) system. There are several requests supported: .Dv IEEE80211_MACCMD_POLICY_OPEN (set the current policy to disable ACL use), .Dv IEEE80211_MACCMD_POLICY_ALLOW (set the current policy to allow only addresses listed in the database), .Dv IEEE80211_MACCMD_POLICY_DENY (set the current policy to deny addresses listed in the database), .Dv IEEE80211_MACCMD_POLICY_RADUS (set the current policy to enable use of a RADIUS backend), .Dv IEEE80211_MACCMD_FLUSH (flush all addresses from the database), and .Dv IEEE80211_MACCMD_DETACH (detach the ACL subsystem, disabling it). The .Xr wlan_acl 4 module must be installed or .Er EINVAL will be returned. .It Dv IEEE80211_IOC_MESH_AP Set whether or not Mesh AP support is enabled using .Va i_val . .It Dv IEEE80211_IOC_MESH_FWRD Set whether or not packet forwarding support is enabled using .Va i_val . .It Dv IEEE80211_IOC_MESH_ID Set the Mesh ID using the value pointed to by .Va i_data . A Mesh ID can be up to .Dv IEEE80211_MESHID_LEN bytes long. .It Dv IEEE80211_IOC_MESH_PP_METRIC Set the link metric protocol using the value pointed to by .Va i_data . .It Dv IEEE80211_IOC_MESH_PP_PATH Set the path selection protocol using the value pointed to by .Va i_data . .It Dv IEEE80211_IOC_MESH_RTCMD Manipulate the state of the Mesh routing tables. Several requests are supported: .Dv IEEE80211_MESH_RTCMD_FLUSH (flush the contents of the routing table), .Dv IEEE80211_MESH_RTCMD_ADD (add an entry for the MAC address specified in .Va i_data and start the Peer discovery process), and .Dv IEEE80211_MESH_RTCMD_DELETE (delete the entry corresponding to the MAC address specified in .Va i_data ). .It Dv IEEE80211_IOC_MESH_TTL Set the Mesh Time To Live (TTL) setting installed in packets transmitted by this mesh node using .Va i_val . .It Dv IEEE80211_IOC_MLME Explicitly control the MLME state machine for a station using the MLME request pointed to by .Va i_data . There are several MLME operations supported: .Dv IEEE80211_MLME_ASSOC (request association to an access point), .Dv IEEE80211_MLME_DIASSOC (diassociate the specified station), .Dv IEEE80211_MLME_DEAUTH (deauthenticate the specified station), .Dv IEEE80211_MLME_AUHORIZE (mark the specified station authorized to pass data frames), .Dv IEEE80211_MLME_UNAUTHORIZE (revoke the specified station's ability to pass data frames), and .Dv IEEE80211_MLME_AUTH (request authentication to an access point). Note when this facility is used for stations operating in infrastructure mode the roaming mode should be set to manual. .It Dv IEEE80211_IOC_POWERSAVE Set the current powersaving mode to the value in .Va i_val . See .Dv IEEE80211_IOC_POWERSAVE above for valid values. This request causes a running interface to be reset. .It Dv IEEE80211_IOC_POWERSAVESLEEP Set the powersave sleep time in TU to the value in .Va i_val . This request causes a running interface to be reset. .It Dv IEEE80211_IOC_PRIVACY Set the current MLME setting for PRIVACY using the value in .Va i_val . See .Dv IEEE80211_IOC_PRIVACY above for details. .It Dv IEEE80211_IOC_PROTMODE Set the current 802.11g protection mode to the value in .Va i_val . This request causes a running interface to be reset. See .Dv IEEE80211_IOC_PROTMODE above for details. This request causes a running interface to be reset. .It Dv IEEE80211_IOC_PUREG Set whether ``pure 11g'' mode is enabled using the value in .Va i_val . This request causes a running interface to be restarted. See .Dv IEEE80211_IOC_PUREG above for details. .It Dv IEEE80211_IOC_PUREN Set whether ``pure 11n'' mode is enabled using the value in .Va i_val . This request causes a running interface to be restarted. See .Dv IEEE80211_IOC_PUREN above for details. .It Dv IEEE80211_IOC_REGDOMAIN Set the regulatory state using the data referenced by .Va i_data . This request can only be issued when all interfaces cloned from the underlying physical device are marked down; otherwise .Er EBUSY is returned. Note the new regulatory data may invalidate any desired channel. .It Dv IEEE80211_IOC_RIFS Set whether or not Reduced InterFrame Spacing (RIFS) is enabled using the value in .Va i_val . This setting is meaningful only when operating with 802.11n on an HT channel. This request causes a running interface to be reset. .It Dv IEEE80211_IOC_ROAM Set station roaming parameters using the data pointed to by .Va i_data . .It Dv IEEE80211_IOC_ROAMING Set the current roaming mode to the value in .Va i_val . See .Dv IEEE80211_IOC_ROAMING above for details. .It Dv IEEE80211_IOC_RTSTHRESHOLD Set the threshold (in bytes) for enabling transmission of RTS frames to the value in .Va i_val . This request causes a running interface to be reset. See .Dv IEEE80211_IOC_RTSTHRESHOLD above for details. .It Dv IEEE80211_IOC_SCANVALID Set the age (in seconds) that results from a scan operation will be considered valid. When scan results are no longer valid and they are needed (e.g. to roam) the system will initiate a scan operation to replenish the scan cache. .It Dv IEEE80211_IOC_SCAN_REQ Request a scan operation using the parameters pointed to by .Va i_val . The underlying device must be running or .Er ENXIO will be returned. Values for .Va sr_duration , .Va sr_mindwell , and .Va sr_maxdwell shorter than 1 clock tick are rounded up to a tick. If more SSID's are supplied than the system is capable of handling the extra ones are silently ignored. If a scan operation is already in progress the request will be (silently) ignored. .It Dv IEEE80211_IOC_SCAN_CANCEL Cancel any pending/active scan operation. .It Dv IEEE80211_IOC_SHORTGI Set whether or not Short Guard Interval (SGI) is enabled using the value in .Va i_val . Note SGI is only used when operating on an HT (802.11n) channel. This request causes a running interface to be reset. .It Dv IEEE80211_IOC_SMPS Set the Spatial Multiplexing Power Save (SMPS) setting to the value in .Va i_val . This request causes a running interface to be reset. See .Dv IEEE80211_IOC_SMPS above for details. .It Dv IEEE80211_IOC_SSID Set the desired SSID using the value pointed to by .Va i_data . The string may be at most IEEE80211_NWID_LEN bytes. This request causes a running interface to be restarted. .It Dv IEEE80211_IOC_STA_STATS Clear accumulated statistics for the specified station. .It Dv IEEE80211_IOC_STA_VLAN Set the VLAN tag for the specified station using the information pointed to by .Va i_data . .It Dv IEEE80211_IOC_TDMA_BINTERVAL Set the interval between Beacon frames to the value in .Va i_val . Values must be positive. This request causes a running interface to be reset. .It Dv IEEE80211_IOC_TDMA_SLOT Set the current TDMA slot to the value in .Va i_val . Values must be in the range [0-slotcnt]. Slot 0 identifies the master in the TDMA network; if it running it will immediately start sending Beacon frames. .It Dv IEEE80211_IOC_TDMA_SLOTCNT Set the number of slots in the TDMA network to the value in .Va i_val . This request causes a running interface to be reset. .It Dv IEEE80211_IOC_TDMA_SLOTLEN Set the length of the TDMA slot assigned to each station in the network to the value in .Va i_val . Slot lengths must be in the range 200 usecs to 1024 milliseconds (though values outside the range 1-200ms are unlikely to work well). This request causes a running interface to be reset. .It Dv IEEE80211_IOC_TSN Set whether or not Transitional Security Network (TSN) is enabled using the value in .Va i_val . .It Dv IEEE80211_IOC_TURBOP Set whether Atheros Dynamic Turbo mode is enabled using the value in .Va i_val . This request causes a running interface to be restarted. .It Dv IEEE80211_IOC_TXPARAMS Set transmit parameters using the data pointed to be .Va i_data . This request causes a running interface to be restarted. .It Dv IEEE80211_IOC_TXPOWER Set the maximum transmit power limit in .5 dBm units to the value in .Va i_val . This request causes a running interface to be reset. .It Dv IEEE80211_IOC_WEP Set the current WEP mode to the value in .Va i_val . See .Dv IEEE80211_IOC_WEP above for valid values. This request causes a running interface to be restarted. Note this request is deprecated; use .Dv IEEE80211_IOC_PRIVACY and .Dv IEEE80211_IOC_DROPUNENCRYPTED instead. .It Dv IEEE80211_IOC_WEPKEY Set the WEP key indicated by .Va i_val using the data pointed to by .Va i_data . Note this request is deprecated; use .Dv IEEE80211_IOC_WPAKEY instead. .It Dv IEEE80211_IOC_WEPTXKEY Set the default transmit key used for transmission to the value in .Va i_val . .It Dv IEEE80211_IOC_WME Set whether or not WME/WMM support is enabled using the value in .Va i_val . This request causes a running interface to be reset. .It Dv IEEE80211_IOC_WME_ACKPOLICY Set the WME ACK Policy for the Access Class (AC) specified in .Va i_len using the value in .Va i_val . .It Dv IEEE80211_IOC_WME_ACM Set the WME Admission Control Mechanism for the Access Class (AC) specified in .Va i_len using the value in .Va i_val . .It Dv IEEE80211_IOC_WME_AIFS Set the WME AIFS parameter for the Access Class (AC) specified in .Va i_len using the value in .Va i_val . .It Dv IEEE80211_IOC_WME_CWMAX Set the WME CWmax parameter for the Access Class (AC) specified in .Va i_len using the value in .Va i_val . .It Dv IEEE80211_IOC_WME_CWMIN Set the WME CWmin parameter for the Access Class (AC) specified in .Va i_len using the value in .Va i_val . .It Dv IEEE80211_IOC_WME_TXOPLIMIT Set the WME TxOpLimit parameter for the Access Class (AC) specified in .Va i_len using the value in .Va i_val . .It Dv IEEE80211_IOC_WPA Set the WPA configuration using the value in .Va i_val . This request causes a running interface to be reset. See .Dv IEEE80211_IOC_WPA above for details. .It Dv IEEE80211_IOC_WPAKEY Set the requested cryptographic key using data in the buffer pointed to by .Va i_data . See .Dv IEEE80211_IOC_WPAKEY for details. .It Dv IEEE80211_IOC_WPS Set whether or not Wi-FI Protected Setup (WPS) is enabled using the value in .Va i_val . .El .Sh SEE ALSO .Xr ioctl 2 , .Xr wlan 4 , .Xr wlan_acl 4 , .Xr wlan_xauth 4 , -.Xr ifconfig 8 , .Xr hostapd 8 , -.Xr wpa_supplicant 8 . +.Xr ifconfig 8 , +.Xr wpa_supplicant 8 Index: head/share/man/man4/netmap.4 =================================================================== --- head/share/man/man4/netmap.4 (revision 275989) +++ head/share/man/man4/netmap.4 (revision 275990) @@ -1,1075 +1,1067 @@ .\" Copyright (c) 2011-2014 Matteo Landi, Luigi Rizzo, Universita` di Pisa .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON 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 ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" This document is derived in part from the enet man page (enet.4) .\" distributed with 4.3BSD Unix. .\" .\" $FreeBSD$ .\" .Dd February 13, 2014 .Dt NETMAP 4 .Os .Sh NAME .Nm netmap .Nd a framework for fast packet I/O .br .Nm VALE .Nd a fast VirtuAl Local Ethernet using the netmap API .br .Nm netmap pipes .Nd a shared memory packet transport channel .Sh SYNOPSIS .Cd device netmap .Sh DESCRIPTION .Nm is a framework for extremely fast and efficient packet I/O for both userspace and kernel clients. It runs on FreeBSD and Linux, and includes .Nm VALE , a very fast and modular in-kernel software switch/dataplane, and .Nm netmap pipes , a shared memory packet transport channel. All these are accessed interchangeably with the same API. .Pp .Nm , VALE and .Nm netmap pipes are at least one order of magnitude faster than standard OS mechanisms (sockets, bpf, tun/tap interfaces, native switches, pipes), reaching 14.88 million packets per second (Mpps) with much less than one core on a 10 Gbit NIC, about 20 Mpps per core for VALE ports, and over 100 Mpps for netmap pipes. .Pp Userspace clients can dynamically switch NICs into .Nm mode and send and receive raw packets through memory mapped buffers. Similarly, .Nm VALE switch instances and ports, and .Nm netmap pipes can be created dynamically, providing high speed packet I/O between processes, virtual machines, NICs and the host stack. .Pp .Nm suports both non-blocking I/O through .Xr ioctls() , synchronization and blocking I/O through a file descriptor and standard OS mechanisms such as .Xr select 2 , .Xr poll 2 , .Xr epoll 2 , .Xr kqueue 2 . .Nm VALE and .Nm netmap pipes are implemented by a single kernel module, which also emulates the .Nm API over standard drivers for devices without native .Nm support. For best performance, .Nm requires explicit support in device drivers. .Pp In the rest of this (long) manual page we document various aspects of the .Nm and .Nm VALE architecture, features and usage. -.Pp .Sh ARCHITECTURE .Nm supports raw packet I/O through a .Em port , which can be connected to a physical interface .Em ( NIC ) , to the host stack, or to a .Nm VALE switch). Ports use preallocated circular queues of buffers .Em ( rings ) residing in an mmapped region. There is one ring for each transmit/receive queue of a NIC or virtual port. An additional ring pair connects to the host stack. .Pp After binding a file descriptor to a port, a .Nm client can send or receive packets in batches through the rings, and possibly implement zero-copy forwarding between ports. .Pp All NICs operating in .Nm mode use the same memory region, accessible to all processes who own .Nm /dev/netmap file descriptors bound to NICs. Independent .Nm VALE and .Nm netmap pipe ports by default use separate memory regions, but can be independently configured to share memory. -.Pp .Sh ENTERING AND EXITING NETMAP MODE The following section describes the system calls to create and control .Nm netmap ports (including .Nm VALE and .Nm netmap pipe ports). Simpler, higher level functions are described in section .Xr LIBRARIES . .Pp Ports and rings are created and controlled through a file descriptor, created by opening a special device .Dl fd = open("/dev/netmap"); and then bound to a specific port with an .Dl ioctl(fd, NIOCREGIF, (struct nmreq *)arg); .Pp .Nm has multiple modes of operation controlled by the .Vt struct nmreq argument. .Va arg.nr_name specifies the port name, as follows: .Bl -tag -width XXXX .It Dv OS network interface name (e.g. 'em0', 'eth1', ... ) the data path of the NIC is disconnected from the host stack, and the file descriptor is bound to the NIC (one or all queues), or to the host stack; .It Dv valeXXX:YYY (arbitrary XXX and YYY) the file descriptor is bound to port YYY of a VALE switch called XXX, both dynamically created if necessary. The string cannot exceed IFNAMSIZ characters, and YYY cannot be the name of any existing OS network interface. .El .Pp On return, .Va arg indicates the size of the shared memory region, and the number, size and location of all the .Nm data structures, which can be accessed by mmapping the memory .Dl char *mem = mmap(0, arg.nr_memsize, fd); .Pp Non blocking I/O is done with special .Xr ioctl 2 .Xr select 2 and .Xr poll 2 on the file descriptor permit blocking I/O. .Xr epoll 2 and .Xr kqueue 2 are not supported on .Nm file descriptors. .Pp While a NIC is in .Nm mode, the OS will still believe the interface is up and running. OS-generated packets for that NIC end up into a .Nm ring, and another ring is used to send packets into the OS network stack. A .Xr close 2 on the file descriptor removes the binding, and returns the NIC to normal mode (reconnecting the data path to the host stack), or destroys the virtual port. -.Pp .Sh DATA STRUCTURES The data structures in the mmapped memory region are detailed in .Xr sys/net/netmap.h , which is the ultimate reference for the .Nm API. The main structures and fields are indicated below: .Bl -tag -width XXX .It Dv struct netmap_if (one per interface) .Bd -literal struct netmap_if { ... const uint32_t ni_flags; /* properties */ ... const uint32_t ni_tx_rings; /* NIC tx rings */ const uint32_t ni_rx_rings; /* NIC rx rings */ uint32_t ni_bufs_head; /* head of extra bufs list */ ... }; .Ed .Pp Indicates the number of available rings .Pa ( struct netmap_rings ) and their position in the mmapped region. The number of tx and rx rings .Pa ( ni_tx_rings , ni_rx_rings ) normally depends on the hardware. NICs also have an extra tx/rx ring pair connected to the host stack. .Em NIOCREGIF can also request additional unbound buffers in the same memory space, to be used as temporary storage for packets. .Pa ni_bufs_head contains the index of the first of these free rings, which are connected in a list (the first uint32_t of each buffer being the index of the next buffer in the list). A 0 indicates the end of the list. .Pp .It Dv struct netmap_ring (one per ring) .Bd -literal struct netmap_ring { ... const uint32_t num_slots; /* slots in each ring */ const uint32_t nr_buf_size; /* size of each buffer */ ... uint32_t head; /* (u) first buf owned by user */ uint32_t cur; /* (u) wakeup position */ const uint32_t tail; /* (k) first buf owned by kernel */ ... uint32_t flags; struct timeval ts; /* (k) time of last rxsync() */ ... struct netmap_slot slot[0]; /* array of slots */ } .Ed .Pp Implements transmit and receive rings, with read/write pointers, metadata and and an array of .Pa slots describing the buffers. .Pp .It Dv struct netmap_slot (one per buffer) .Bd -literal struct netmap_slot { uint32_t buf_idx; /* buffer index */ uint16_t len; /* packet length */ uint16_t flags; /* buf changed, etc. */ uint64_t ptr; /* address for indirect buffers */ }; .Ed .Pp Describes a packet buffer, which normally is identified by an index and resides in the mmapped region. .It Dv packet buffers Fixed size (normally 2 KB) packet buffers allocated by the kernel. .El .Pp The offset of the .Pa struct netmap_if in the mmapped region is indicated by the .Pa nr_offset field in the structure returned by .Pa NIOCREGIF . From there, all other objects are reachable through relative references (offsets or indexes). Macros and functions in help converting them into actual pointers: .Pp .Dl struct netmap_if *nifp = NETMAP_IF(mem, arg.nr_offset); .Dl struct netmap_ring *txr = NETMAP_TXRING(nifp, ring_index); .Dl struct netmap_ring *rxr = NETMAP_RXRING(nifp, ring_index); .Pp .Dl char *buf = NETMAP_BUF(ring, buffer_index); .Sh RINGS, BUFFERS AND DATA I/O .Va Rings are circular queues of packets with three indexes/pointers .Va ( head , cur , tail ) ; one slot is always kept empty. The ring size .Va ( num_slots ) should not be assumed to be a power of two. .br (NOTE: older versions of netmap used head/count format to indicate the content of a ring). .Pp .Va head is the first slot available to userspace; .br .Va cur is the wakeup point: select/poll will unblock when .Va tail passes .Va cur ; .br .Va tail is the first slot reserved to the kernel. .Pp Slot indexes MUST only move forward; for convenience, the function .Dl nm_ring_next(ring, index) returns the next index modulo the ring size. .Pp .Va head and .Va cur are only modified by the user program; .Va tail is only modified by the kernel. The kernel only reads/writes the .Vt struct netmap_ring slots and buffers during the execution of a netmap-related system call. The only exception are slots (and buffers) in the range .Va tail\ . . . head-1 , that are explicitly assigned to the kernel. .Pp .Ss TRANSMIT RINGS On transmit rings, after a .Nm system call, slots in the range .Va head\ . . . tail-1 are available for transmission. User code should fill the slots sequentially and advance .Va head and .Va cur past slots ready to transmit. .Va cur may be moved further ahead if the user code needs more slots before further transmissions (see .Sx SCATTER GATHER I/O ) . .Pp At the next NIOCTXSYNC/select()/poll(), slots up to .Va head-1 are pushed to the port, and .Va tail may advance if further slots have become available. Below is an example of the evolution of a TX ring: .Pp .Bd -literal after the syscall, slots between cur and tail are (a)vailable head=cur tail | | v v TX [.....aaaaaaaaaaa.............] user creates new packets to (T)ransmit head=cur tail | | v v TX [.....TTTTTaaaaaa.............] NIOCTXSYNC/poll()/select() sends packets and reports new slots head=cur tail | | v v TX [..........aaaaaaaaaaa........] .Ed .Pp select() and poll() wlll block if there is no space in the ring, i.e. .Dl ring->cur == ring->tail and return when new slots have become available. .Pp High speed applications may want to amortize the cost of system calls by preparing as many packets as possible before issuing them. .Pp A transmit ring with pending transmissions has .Dl ring->head != ring->tail + 1 (modulo the ring size). The function .Va int nm_tx_pending(ring) implements this test. -.Pp .Ss RECEIVE RINGS On receive rings, after a .Nm system call, the slots in the range .Va head\& . . . tail-1 contain received packets. User code should process them and advance .Va head and .Va cur past slots it wants to return to the kernel. .Va cur may be moved further ahead if the user code wants to wait for more packets without returning all the previous slots to the kernel. .Pp At the next NIOCRXSYNC/select()/poll(), slots up to .Va head-1 are returned to the kernel for further receives, and .Va tail may advance to report new incoming packets. .br Below is an example of the evolution of an RX ring: .Bd -literal after the syscall, there are some (h)eld and some (R)eceived slots head cur tail | | | v v v RX [..hhhhhhRRRRRRRR..........] user advances head and cur, releasing some slots and holding others head cur tail | | | v v v RX [..*****hhhRRRRRR...........] NICRXSYNC/poll()/select() recovers slots and reports new packets head cur tail | | | v v v RX [.......hhhRRRRRRRRRRRR....] .Ed -.Pp .Sh SLOTS AND PACKET BUFFERS Normally, packets should be stored in the netmap-allocated buffers assigned to slots when ports are bound to a file descriptor. One packet is fully contained in a single buffer. .Pp The following flags affect slot and buffer processing: .Bl -tag -width XXX .It NS_BUF_CHANGED it MUST be used when the buf_idx in the slot is changed. This can be used to implement zero-copy forwarding, see .Sx ZERO-COPY FORWARDING . .Pp .It NS_REPORT reports when this buffer has been transmitted. Normally, .Nm notifies transmit completions in batches, hence signals can be delayed indefinitely. This flag helps detecting when packets have been send and a file descriptor can be closed. .It NS_FORWARD When a ring is in 'transparent' mode (see .Sx TRANSPARENT MODE ) , packets marked with this flags are forwarded to the other endpoint at the next system call, thus restoring (in a selective way) the connection between a NIC and the host stack. .It NS_NO_LEARN tells the forwarding code that the SRC MAC address for this packet must not be used in the learning bridge code. .It NS_INDIRECT indicates that the packet's payload is in a user-supplied buffer, whose user virtual address is in the 'ptr' field of the slot. The size can reach 65535 bytes. .br This is only supported on the transmit ring of .Nm VALE ports, and it helps reducing data copies in the interconnection of virtual machines. .It NS_MOREFRAG indicates that the packet continues with subsequent buffers; the last buffer in a packet must have the flag clear. .El .Sh SCATTER GATHER I/O Packets can span multiple slots if the .Va NS_MOREFRAG flag is set in all but the last slot. The maximum length of a chain is 64 buffers. This is normally used with .Nm VALE ports when connecting virtual machines, as they generate large TSO segments that are not split unless they reach a physical device. .Pp NOTE: The length field always refers to the individual fragment; there is no place with the total length of a packet. .Pp On receive rings the macro .Va NS_RFRAGS(slot) indicates the remaining number of slots for this packet, including the current one. Slots with a value greater than 1 also have NS_MOREFRAG set. .Sh IOCTLS .Nm uses two ioctls (NIOCTXSYNC, NIOCRXSYNC) for non-blocking I/O. They take no argument. Two more ioctls (NIOCGINFO, NIOCREGIF) are used to query and configure ports, with the following argument: .Bd -literal struct nmreq { char nr_name[IFNAMSIZ]; /* (i) port name */ uint32_t nr_version; /* (i) API version */ uint32_t nr_offset; /* (o) nifp offset in mmap region */ uint32_t nr_memsize; /* (o) size of the mmap region */ uint32_t nr_tx_slots; /* (i/o) slots in tx rings */ uint32_t nr_rx_slots; /* (i/o) slots in rx rings */ uint16_t nr_tx_rings; /* (i/o) number of tx rings */ uint16_t nr_rx_rings; /* (i/o) number of tx rings */ uint16_t nr_ringid; /* (i/o) ring(s) we care about */ uint16_t nr_cmd; /* (i) special command */ uint16_t nr_arg1; /* (i/o) extra arguments */ uint16_t nr_arg2; /* (i/o) extra arguments */ uint32_t nr_arg3; /* (i/o) extra arguments */ uint32_t nr_flags /* (i/o) open mode */ ... }; .Ed .Pp A file descriptor obtained through .Pa /dev/netmap also supports the ioctl supported by network devices, see .Xr netintro 4 . .Pp .Bl -tag -width XXXX .It Dv NIOCGINFO returns EINVAL if the named port does not support netmap. Otherwise, it returns 0 and (advisory) information about the port. Note that all the information below can change before the interface is actually put in netmap mode. .Pp .Bl -tag -width XX .It Pa nr_memsize indicates the size of the .Nm memory region. NICs in .Nm mode all share the same memory region, whereas .Nm VALE ports have independent regions for each port. .It Pa nr_tx_slots , nr_rx_slots indicate the size of transmit and receive rings. .It Pa nr_tx_rings , nr_rx_rings indicate the number of transmit and receive rings. Both ring number and sizes may be configured at runtime using interface-specific functions (e.g. .Xr ethtool ). .El .It Dv NIOCREGIF binds the port named in .Va nr_name to the file descriptor. For a physical device this also switches it into .Nm mode, disconnecting it from the host stack. Multiple file descriptors can be bound to the same port, with proper synchronization left to the user. .Pp .Dv NIOCREGIF can also bind a file descriptor to one endpoint of a .Em netmap pipe , consisting of two netmap ports with a crossover connection. A netmap pipe share the same memory space of the parent port, and is meant to enable configuration where a master process acts as a dispatcher towards slave processes. .Pp To enable this function, the .Pa nr_arg1 field of the structure can be used as a hint to the kernel to indicate how many pipes we expect to use, and reserve extra space in the memory region. .Pp On return, it gives the same info as NIOCGINFO, with .Pa nr_ringid and .Pa nr_flags indicating the identity of the rings controlled through the file descriptor. .Pp .Va nr_flags .Va nr_ringid selects which rings are controlled through this file descriptor. Possible values of .Pa nr_flags are indicated below, together with the naming schemes that application libraries (such as the .Nm nm_open indicated below) can use to indicate the specific set of rings. In the example below, "netmap:foo" is any valid netmap port name. .Pp .Bl -tag -width XXXXX .It NR_REG_ALL_NIC "netmap:foo" (default) all hardware ring pairs .It NR_REG_SW "netmap:foo^" the ``host rings'', connecting to the host stack. .It NR_REG_NIC_SW "netmap:foo+" all hardware rings and the host rings .It NR_REG_ONE_NIC "netmap:foo-i" only the i-th hardware ring pair, where the number is in .Pa nr_ringid ; .It NR_REG_PIPE_MASTER "netmap:foo{i" the master side of the netmap pipe whose identifier (i) is in .Pa nr_ringid ; .It NR_REG_PIPE_SLAVE "netmap:foo}i" the slave side of the netmap pipe whose identifier (i) is in .Pa nr_ringid . .Pp The identifier of a pipe must be thought as part of the pipe name, and does not need to be sequential. On return the pipe will only have a single ring pair with index 0, irrespective of the value of i. .El .Pp By default, a .Xr poll 2 or .Xr select 2 call pushes out any pending packets on the transmit ring, even if no write events are specified. The feature can be disabled by or-ing .Va NETMAP_NO_TX_POLL to the value written to .Va nr_ringid. When this feature is used, packets are transmitted only on .Va ioctl(NIOCTXSYNC) or select()/poll() are called with a write event (POLLOUT/wfdset) or a full ring. .Pp When registering a virtual interface that is dynamically created to a .Xr vale 4 switch, we can specify the desired number of rings (1 by default, and currently up to 16) on it using nr_tx_rings and nr_rx_rings fields. .It Dv NIOCTXSYNC tells the hardware of new packets to transmit, and updates the number of slots available for transmission. .It Dv NIOCRXSYNC tells the hardware of consumed packets, and asks for newly available packets. .El .Sh SELECT, POLL, EPOLL, KQUEUE. .Xr select 2 and .Xr poll 2 on a .Nm file descriptor process rings as indicated in .Sx TRANSMIT RINGS and .Sx RECEIVE RINGS , respectively when write (POLLOUT) and read (POLLIN) events are requested. Both block if no slots are available in the ring .Va ( ring->cur == ring->tail ) . Depending on the platform, .Xr epoll 2 and .Xr kqueue 2 are supported too. .Pp Packets in transmit rings are normally pushed out (and buffers reclaimed) even without requesting write events. Passing the NETMAP_NO_TX_POLL flag to .Em NIOCREGIF disables this feature. By default, receive rings are processed only if read events are requested. Passing the NETMAP_DO_RX_POLL flag to .Em NIOCREGIF updates receive rings even without read events. Note that on epoll and kqueue, NETMAP_NO_TX_POLL and NETMAP_DO_RX_POLL only have an effect when some event is posted for the file descriptor. .Sh LIBRARIES The .Nm API is supposed to be used directly, both because of its simplicity and for efficient integration with applications. .Pp For conveniency, the .Va header provides a few macros and functions to ease creating a file descriptor and doing I/O with a .Nm port. These are loosely modeled after the .Xr pcap 3 API, to ease porting of libpcap-based applications to .Nm . To use these extra functions, programs should .Dl #define NETMAP_WITH_LIBS before .Dl #include .Pp The following functions are available: .Bl -tag -width XXXXX .It Va struct nm_desc * nm_open(const char *ifname, const struct nmreq *req, uint64_t flags, const struct nm_desc *arg) similar to .Xr pcap_open , binds a file descriptor to a port. .Bl -tag -width XX .It Va ifname is a port name, in the form "netmap:XXX" for a NIC and "valeXXX:YYY" for a .Nm VALE port. .It Va req provides the initial values for the argument to the NIOCREGIF ioctl. The nm_flags and nm_ringid values are overwritten by parsing ifname and flags, and other fields can be overridden through the other two arguments. .It Va arg points to a struct nm_desc containing arguments (e.g. from a previously open file descriptor) that should override the defaults. The fields are used as described below .It Va flags can be set to a combination of the following flags: .Va NETMAP_NO_TX_POLL , .Va NETMAP_DO_RX_POLL (copied into nr_ringid); .Va NM_OPEN_NO_MMAP (if arg points to the same memory region, avoids the mmap and uses the values from it); .Va NM_OPEN_IFNAME (ignores ifname and uses the values in arg); .Va NM_OPEN_ARG1 , .Va NM_OPEN_ARG2 , .Va NM_OPEN_ARG3 (uses the fields from arg); .Va NM_OPEN_RING_CFG (uses the ring number and sizes from arg). .El .It Va int nm_close(struct nm_desc *d) closes the file descriptor, unmaps memory, frees resources. .It Va int nm_inject(struct nm_desc *d, const void *buf, size_t size) similar to pcap_inject(), pushes a packet to a ring, returns the size of the packet is successful, or 0 on error; .It Va int nm_dispatch(struct nm_desc *d, int cnt, nm_cb_t cb, u_char *arg) similar to pcap_dispatch(), applies a callback to incoming packets .It Va u_char * nm_nextpkt(struct nm_desc *d, struct nm_pkthdr *hdr) similar to pcap_next(), fetches the next packet -.Pp .El .Sh SUPPORTED DEVICES .Nm natively supports the following devices: .Pp On FreeBSD: .Xr em 4 , .Xr igb 4 , .Xr ixgbe 4 , .Xr lem 4 , .Xr re 4 . .Pp On Linux .Xr e1000 4 , .Xr e1000e 4 , .Xr igb 4 , .Xr ixgbe 4 , .Xr mlx4 4 , .Xr forcedeth 4 , .Xr r8169 4 . .Pp NICs without native support can still be used in .Nm mode through emulation. Performance is inferior to native netmap mode but still significantly higher than sockets, and approaching that of in-kernel solutions such as Linux's .Xr pktgen . .Pp Emulation is also available for devices with native netmap support, which can be used for testing or performance comparison. The sysctl variable .Va dev.netmap.admode globally controls how netmap mode is implemented. .Sh SYSCTL VARIABLES AND MODULE PARAMETERS Some aspect of the operation of .Nm are controlled through sysctl variables on FreeBSD .Em ( dev.netmap.* ) and module parameters on Linux .Em ( /sys/module/netmap_lin/parameters/* ) : .Pp .Bl -tag -width indent .It Va dev.netmap.admode: 0 Controls the use of native or emulated adapter mode. 0 uses the best available option, 1 forces native and fails if not available, 2 forces emulated hence never fails. .It Va dev.netmap.generic_ringsize: 1024 Ring size used for emulated netmap mode .It Va dev.netmap.generic_mit: 100000 Controls interrupt moderation for emulated mode .It Va dev.netmap.mmap_unreg: 0 .It Va dev.netmap.fwd: 0 Forces NS_FORWARD mode .It Va dev.netmap.flags: 0 .It Va dev.netmap.txsync_retry: 2 .It Va dev.netmap.no_pendintr: 1 Forces recovery of transmit buffers on system calls .It Va dev.netmap.mitigate: 1 Propagates interrupt mitigation to user processes .It Va dev.netmap.no_timestamp: 0 Disables the update of the timestamp in the netmap ring .It Va dev.netmap.verbose: 0 Verbose kernel messages .It Va dev.netmap.buf_num: 163840 .It Va dev.netmap.buf_size: 2048 .It Va dev.netmap.ring_num: 200 .It Va dev.netmap.ring_size: 36864 .It Va dev.netmap.if_num: 100 .It Va dev.netmap.if_size: 1024 Sizes and number of objects (netmap_if, netmap_ring, buffers) for the global memory region. The only parameter worth modifying is .Va dev.netmap.buf_num as it impacts the total amount of memory used by netmap. .It Va dev.netmap.buf_curr_num: 0 .It Va dev.netmap.buf_curr_size: 0 .It Va dev.netmap.ring_curr_num: 0 .It Va dev.netmap.ring_curr_size: 0 .It Va dev.netmap.if_curr_num: 0 .It Va dev.netmap.if_curr_size: 0 Actual values in use. .It Va dev.netmap.bridge_batch: 1024 Batch size used when moving packets across a .Nm VALE switch. Values above 64 generally guarantee good performance. .El .Sh SYSTEM CALLS .Nm uses .Xr select 2 , .Xr poll 2 , .Xr epoll and .Xr kqueue to wake up processes when significant events occur, and .Xr mmap 2 to map memory. .Xr ioctl 2 is used to configure ports and .Nm VALE switches . .Pp Applications may need to create threads and bind them to specific cores to improve performance, using standard OS primitives, see .Xr pthread 3 . In particular, .Xr pthread_setaffinity_np 3 may be of use. .Sh CAVEATS No matter how fast the CPU and OS are, achieving line rate on 10G and faster interfaces requires hardware with sufficient performance. Several NICs are unable to sustain line rate with small packet sizes. Insufficient PCIe or memory bandwidth can also cause reduced performance. .Pp Another frequent reason for low performance is the use of flow control on the link: a slow receiver can limit the transmit speed. Be sure to disable flow control when running high speed experiments. .Pp .Ss SPECIAL NIC FEATURES .Nm is orthogonal to some NIC features such as multiqueue, schedulers, packet filters. .Pp Multiple transmit and receive rings are supported natively and can be configured with ordinary OS tools, such as .Xr ethtool or device-specific sysctl variables. The same goes for Receive Packet Steering (RPS) and filtering of incoming traffic. .Pp .Nm .Em does not use features such as .Em checksum offloading , TCP segmentation offloading , .Em encryption , VLAN encapsulation/decapsulation , etc. . When using netmap to exchange packets with the host stack, make sure to disable these features. .Sh EXAMPLES .Ss TEST PROGRAMS .Nm comes with a few programs that can be used for testing or simple applications. See the .Va examples/ directory in .Nm distributions, or .Va tools/tools/netmap/ directory in FreeBSD distributions. .Pp .Xr pkt-gen is a general purpose traffic source/sink. .Pp As an example .Dl pkt-gen -i ix0 -f tx -l 60 can generate an infinite stream of minimum size packets, and .Dl pkt-gen -i ix0 -f rx is a traffic sink. Both print traffic statistics, to help monitor how the system performs. .Pp .Xr pkt-gen has many options can be uses to set packet sizes, addresses, rates, and use multiple send/receive threads and cores. .Pp .Xr bridge is another test program which interconnects two .Nm ports. It can be used for transparent forwarding between interfaces, as in .Dl bridge -i ix0 -i ix1 or even connect the NIC to the host stack using netmap .Dl bridge -i ix0 -i ix0 .Ss USING THE NATIVE API The following code implements a traffic generator .Pp .Bd -literal -compact #include ... void sender(void) { struct netmap_if *nifp; struct netmap_ring *ring; struct nmreq nmr; struct pollfd fds; fd = open("/dev/netmap", O_RDWR); bzero(&nmr, sizeof(nmr)); strcpy(nmr.nr_name, "ix0"); nmr.nm_version = NETMAP_API; ioctl(fd, NIOCREGIF, &nmr); p = mmap(0, nmr.nr_memsize, fd); nifp = NETMAP_IF(p, nmr.nr_offset); ring = NETMAP_TXRING(nifp, 0); fds.fd = fd; fds.events = POLLOUT; for (;;) { poll(&fds, 1, -1); while (!nm_ring_empty(ring)) { i = ring->cur; buf = NETMAP_BUF(ring, ring->slot[i].buf_index); ... prepare packet in buf ... ring->slot[i].len = ... packet length ... ring->head = ring->cur = nm_ring_next(ring, i); } } } .Ed .Ss HELPER FUNCTIONS A simple receiver can be implemented using the helper functions .Bd -literal -compact #define NETMAP_WITH_LIBS #include ... void receiver(void) { struct nm_desc *d; struct pollfd fds; u_char *buf; struct nm_pkthdr h; ... d = nm_open("netmap:ix0", NULL, 0, 0); fds.fd = NETMAP_FD(d); fds.events = POLLIN; for (;;) { poll(&fds, 1, -1); while ( (buf = nm_nextpkt(d, &h)) ) consume_pkt(buf, h->len); } nm_close(d); } .Ed .Ss ZERO-COPY FORWARDING Since physical interfaces share the same memory region, it is possible to do packet forwarding between ports swapping buffers. The buffer from the transmit ring is used to replenish the receive ring: .Bd -literal -compact uint32_t tmp; struct netmap_slot *src, *dst; ... src = &src_ring->slot[rxr->cur]; dst = &dst_ring->slot[txr->cur]; tmp = dst->buf_idx; dst->buf_idx = src->buf_idx; dst->len = src->len; dst->flags = NS_BUF_CHANGED; src->buf_idx = tmp; src->flags = NS_BUF_CHANGED; rxr->head = rxr->cur = nm_ring_next(rxr, rxr->cur); txr->head = txr->cur = nm_ring_next(txr, txr->cur); ... .Ed .Ss ACCESSING THE HOST STACK The host stack is for all practical purposes just a regular ring pair, which you can access with the netmap API (e.g. with .Dl nm_open("netmap:eth0^", ... ) ; All packets that the host would send to an interface in .Nm mode end up into the RX ring, whereas all packets queued to the TX ring are send up to the host stack. .Ss VALE SWITCH A simple way to test the performance of a .Nm VALE switch is to attach a sender and a receiver to it, e.g. running the following in two different terminals: .Dl pkt-gen -i vale1:a -f rx # receiver .Dl pkt-gen -i vale1:b -f tx # sender The same example can be used to test netmap pipes, by simply changing port names, e.g. .Dl pkt-gen -i vale:x{3 -f rx # receiver on the master side .Dl pkt-gen -i vale:x}3 -f tx # sender on the slave side .Pp The following command attaches an interface and the host stack to a switch: .Dl vale-ctl -h vale2:em0 Other .Nm clients attached to the same switch can now communicate with the network card or the host. -.Pp .Sh SEE ALSO -.Pp -http://info.iet.unipi.it/~luigi/netmap/ +.Pa http://info.iet.unipi.it/~luigi/netmap/ .Pp Luigi Rizzo, Revisiting network I/O APIs: the netmap framework, Communications of the ACM, 55 (3), pp.45-51, March 2012 .Pp Luigi Rizzo, netmap: a novel framework for fast packet I/O, Usenix ATC'12, June 2012, Boston .Pp Luigi Rizzo, Giuseppe Lettieri, VALE, a switched ethernet for virtual machines, ACM CoNEXT'12, December 2012, Nice .Pp Luigi Rizzo, Giuseppe Lettieri, Vincenzo Maffione, Speeding up packet I/O in virtual machines, ACM/IEEE ANCS'13, October 2013, San Jose .Sh AUTHORS .An -nosplit The .Nm framework has been originally designed and implemented at the Universita` di Pisa in 2011 by .An Luigi Rizzo , and further extended with help from .An Matteo Landi , .An Gaetano Catalli , .An Giuseppe Lettieri , .An Vincenzo Maffione . .Pp .Nm and .Nm VALE have been funded by the European Commission within FP7 Projects CHANGE (257422) and OPENLAB (287581). Index: head/share/man/man4/nfe.4 =================================================================== --- head/share/man/man4/nfe.4 (revision 275989) +++ head/share/man/man4/nfe.4 (revision 275990) @@ -1,200 +1,200 @@ .\" $OpenBSD: nfe.4,v 1.7 2006/02/28 08:13:47 jsg Exp $ .\" .\" Copyright (c) 2006 Jonathan Gray .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" .\" $FreeBSD$ .\" .Dd January 15, 2011 .Dt NFE 4 .Os .Sh NAME .Nm nfe .Nd "NVIDIA nForce MCP Ethernet driver" .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device miibus" .Cd "device nfe" .Ed .Pp Alternatively, to load the driver as a module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent if_nfe_load="YES" .Ed .Sh DESCRIPTION The .Nm driver supports PCI Ethernet adapters based on the NVIDIA nForce Media and Communications Processors (MCP), such as the nForce, nForce 2, nForce 3, CK804, MCP04, MCP51, MCP55, MCP61, MCP65, MCP67, MCP73, MCP77 and MCP79 Ethernet controller chips. .Pp Supported features include (hardware support provided): .Pp .Bl -bullet -compact .It Receive/Transmit IP/TCP/UDP checksum offload .It Hardware VLAN tag insertion/stripping .It TCP segmentation offload (TSO) .It MSI/MSI-X .It Jumbo Frames .El .Pp Support for Jumbo Frames is provided via the interface MTU setting. Selecting an MTU larger than 1500 bytes with the .Xr ifconfig 8 utility configures the adapter to receive and transmit Jumbo Frames. .Pp The .Nm driver supports the following media types: .Bl -tag -width "10baseT/UTP" .It Cm autoselect Enable autoselection of the media type and options. .It Cm 10baseT/UTP Set 10Mbps operation. .It Cm 100baseTX Set 100Mbps (Fast Ethernet) operation. .It Cm 1000baseT Set 1000Mbps (Gigabit Ethernet) operation (recent models only). .El .Pp The .Nm driver supports the following media options: .Bl -tag -width ".Cm 10baseT/UTP" .It Cm half-duplex Force half duplex operation. .It Cm full-duplex Force full duplex operation. .El .Pp For more information on configuring this device, see .Xr ifconfig 8 . .Sh HARDWARE The .Nm driver supports the following NVIDIA MCP onboard adapters: .Pp .Bl -bullet -compact .It NVIDIA nForce MCP Networking Adapter .It NVIDIA nForce MCP04 Networking Adapter .It NVIDIA nForce 430 MCP12 Networking Adapter .It NVIDIA nForce 430 MCP13 Networking Adapter .It NVIDIA nForce MCP51 Networking Adapter .It NVIDIA nForce MCP55 Networking Adapter .It NVIDIA nForce MCP61 Networking Adapter .It NVIDIA nForce MCP65 Networking Adapter .It NVIDIA nForce MCP67 Networking Adapter .It NVIDIA nForce MCP73 Networking Adapter .It NVIDIA nForce MCP77 Networking Adapter .It NVIDIA nForce MCP79 Networking Adapter .It NVIDIA nForce2 MCP2 Networking Adapter .It NVIDIA nForce2 400 MCP4 Networking Adapter .It NVIDIA nForce2 400 MCP5 Networking Adapter .It NVIDIA nForce3 MCP3 Networking Adapter .It NVIDIA nForce3 250 MCP6 Networking Adapter .It NVIDIA nForce3 MCP7 Networking Adapter .It NVIDIA nForce4 CK804 MCP8 Networking Adapter .It NVIDIA nForce4 CK804 MCP9 Networking Adapter .El .Sh LOADER TUNABLES Tunables can be set at the .Xr loader 8 prompt before booting the kernel or stored in .Xr loader.conf 5 . .Bl -tag -width indent .It Va hw.nfe.msi_disable Whether or not MSI support is enabled in the driver. The default value is 0. .It Va hw.nfe.msix_disable Whether or not MSI-X support is enabled in the driver. The default value is 0. .El .Sh SYSCTL VARIABLES The following .Xr sysctl 8 variables can be used to modify or monitor .Nm behavior. .Bl -tag -width indent .It Va dev.nfe.%d.process_limit Maximum number of Rx events to be processed in the event loop before rescheduling a taskqueue. The accepted range is 50 to 255, the default value is 192. The interface does not need to be brought down and up again before a change takes effect. .El .Sh SEE ALSO .Xr altq 4 , .Xr arp 4 , .Xr intro 4 , .Xr miibus 4 , .Xr netintro 4 , .Xr pci 4 , .Xr polling 4 , .Xr rgephy 4 , -.Xr sysctl 8 , -.Xr ifconfig 8 +.Xr ifconfig 8 , +.Xr sysctl 8 .Sh HISTORY The .Nm device driver first appeared in .Ox 3.9 , and then in .Fx 7.0 . .Sh AUTHORS .An -nosplit The .Nm driver was written by .An Jonathan Gray Aq Mt jsg@openbsd.org and .An Damien Bergamini Aq Mt damien@openbsd.org . The .Nm driver was ported to .Fx by .An Shigeaki Tagashira Aq Mt shigeaki@se.hiroshima-u.ac.jp . Index: head/share/man/man4/ng_ether_echo.4 =================================================================== --- head/share/man/man4/ng_ether_echo.4 (revision 275989) +++ head/share/man/man4/ng_ether_echo.4 (revision 275990) @@ -1,77 +1,77 @@ .\" Copyright (c) 1996-1999 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 .\" .\" $FreeBSD$ .\" $Whistle: ng_echo.8,v 1.4 1999/01/25 23:46:26 archie Exp $ .\" .Dd December 24, 2008 .Dt NG_ETHER_ECHO 4 .Os .Sh NAME .Nm ng_ether_echo .Nd netgraph ether_echo node type .Sh SYNOPSIS .In netgraph/ng_ether_echo.h .Sh DESCRIPTION The .Nm ether_echo node type reflects all data and control messages back to the sender. It assumes (and does not check) that the packet is an ethernet frame, and swaps the source and destination addresses before echoing it. This node type is used for testing and debugging. .Sh HOOKS A .Nm ether_echo node accepts any request to connect, regardless of the hook name, as long as the name is unique. .Sh CONTROL MESSAGES This node type supports only the generic control messages. Any other control messages are reflected back to the sender. .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message, or when all hooks have been disconnected. .Sh SEE ALSO .Xr netgraph 4 , -.Xr ng_hole 4 , .Xr ng_echo 4 , .Xr ng_ether 4 , +.Xr ng_hole 4 , .Xr ngctl 8 .Sh HISTORY The .Nm node type was implemented in .Fx 8.0 . .Sh AUTHORS .An Julian Elischer Aq Mt julian@FreeBSD.org Index: head/share/man/man4/ng_netflow.4 =================================================================== --- head/share/man/man4/ng_netflow.4 (revision 275989) +++ head/share/man/man4/ng_netflow.4 (revision 275990) @@ -1,356 +1,356 @@ .\" Copyright (c) 2004-2005 Gleb Smirnoff .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON 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 ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd December 10, 2012 .Dt NG_NETFLOW 4 .Os .Sh NAME .Nm ng_netflow .Nd Cisco's NetFlow implementation .Sh SYNOPSIS .In sys/types.h .In netinet/in.h .In netgraph/netflow/ng_netflow.h .Sh DESCRIPTION The .Nm node implements Cisco's NetFlow export protocol on a router running .Fx . The .Nm node listens for incoming traffic and identifies unique flows in it. Flows are distinguished by endpoint IP addresses, TCP/UDP port numbers, ToS and input interface. Expired flows are exported out of the node in NetFlow version 5/9 UDP datagrams. Expiration reason can be one of the following: .Bl -dash .It RST or FIN TCP segment. .It Active timeout. Flows cannot live more than the specified period of time. The default is 1800 seconds (30 minutes). .It Inactive timeout. A flow was inactive for the specified period of time. The default is 15 seconds. .El .Pp Node supports IPv6 accounting (NetFlow v9 only) and is aware of multiple fibs. Different fibs are mapped to different domain_id in NetFlow V9 and different engine_id in NetFlow V5. .Sh HOOKS This node type supports up to .Dv NG_NETFLOW_MAXIFACES (default 65536) hooks named .Va iface0 , iface1 , etc., and the same number of hooks named .Va out0 , out1 , etc., plus two export hooks: .Va export (for NetFlow version 5) and .Va export9 (for NetFlow version 9). Export can be done simultaneously for all supported export hooks. By default (ingress NetFlow enabled) node does NetFlow accounting of data received on .Va iface* hooks. If corresponding .Va out hook is connected, unmodified data is bypassed to it, otherwise data is freed. If data is received on .Va out hook, it is bypassed to corresponding .Va iface hook without any processing (egress NetFlow disabled by default). When full export datagram for an export protocol is built it is sent to the .Va export or .Va export9 hook. In normal operation, one (or more) export hook is connected to the .Va inet/dgram/udp hook of the .Xr ng_ksocket 4 node. .Sh CONTROL MESSAGES This node type supports the generic control messages, plus the following: .Bl -tag -width foo .It Dv NGM_NETFLOW_INFO Pq Ic info Returns some node statistics and the current timeout values in a .Vt "struct ng_netflow_info" . .It Dv NGM_NETFLOW_IFINFO Pq Ic ifinfo Returns information about the .Va iface Ns Ar N hook. The hook number is passed as an argument. .It Dv NGM_NETFLOW_SETDLT Pq Ic setdlt Sets data link type on the .Va iface Ns Ar N hook. Currently, supported types are .Cm DLT_RAW (raw IP datagrams) and .Cm DLT_EN10MB (Ethernet). DLT_ definitions can be found in .In net/bpf.h header. Currently used values are 1 for .Cm DLT_EN10MB and 12 for .Cm DLT_RAW . This message type uses .Vt "struct ng_netflow_setdlt" as an argument: .Bd -literal -offset 4n struct ng_netflow_setdlt { uint16_t iface; /* which iface dlt change */ uint8_t dlt; /* DLT_XXX from bpf.h */ }; .Ed .Pp The requested .Va iface Ns Ar N hook must already be connected, otherwise message send operation will return an error. .It Dv NGM_NETFLOW_SETIFINDEX Pq Ic setifindex In some cases, .Nm may be unable to determine the input interface index of a packet. This can happen if traffic enters the .Nm node before it comes to the system interface's input queue. An example of such a setup is capturing a traffic .Em between synchronous data line and .Xr ng_iface 4 . In this case, the input index should be associated with a given hook. The interface's index can be determined via .Xr if_nametoindex 3 from userland. This message requires .Vt "struct ng_netflow_setifindex" as an argument: .Bd -literal -offset 4n struct ng_netflow_setifindex { uint16_t iface; /* which iface index change */ uint16_t index; /* new index */ }; .Ed .Pp The requested .Va iface Ns Ar N hook must already be connected, otherwise the message send operation will return an error. .It Dv NGM_NETFLOW_SETTIMEOUTS Pq Ic settimeouts Sets values in seconds for NetFlow active/inactive timeouts. This message requires .Vt "struct ng_netflow_settimeouts" as an argument: .Bd -literal -offset 4n struct ng_netflow_settimeouts { uint32_t inactive_timeout; /* flow inactive timeout */ uint32_t active_timeout; /* flow active timeout */ }; .Ed .It Dv NGM_NETFLOW_SETCONFIG Pq Ic setconfig Sets configuration for the specified interface. This message requires .Vt "struct ng_netflow_setconfig" as an argument: .Bd -literal -offset 4n struct ng_netflow_setconfig { uint16_t iface; /* which iface config change */ uint32_t conf; /* new config */ #define NG_NETFLOW_CONF_INGRESS 1 #define NG_NETFLOW_CONF_EGRESS 2 #define NG_NETFLOW_CONF_ONCE 4 #define NG_NETFLOW_CONF_THISONCE 8 #define NG_NETFLOW_CONF_NOSRCLOOKUP 16 #define NG_NETFLOW_CONF_NODSTLOOKUP 32 }; .Ed .Pp Configuration is a bitmask of several options. Option NG_NETFLOW_CONF_INGRESS enabled by default enables ingress NetFlow generation (for data coming from ifaceX hook). Option .Va NG_NETFLOW_CONF_EGRESS enables egress NetFlow (for data coming from outX hook). Option .Va NG_NETFLOW_CONF_ONCE defines that packet should be accounted only once if it several times passes via netflow node. Option .Va NG_NETFLOW_CONF_THISONCE defines that packet should be accounted only once if it several times passes via exactly this netflow node. These two options are important to avoid duplicate accounting when both ingress and egress NetFlow are enabled. Option .Va NG_NETFLOW_CONF_NOSRCLOOKUP skips radix lookup on flow source address used to fill in network mask. Option .Va NG_NETFLOW_CONF_NODSTLOOKUP skips radix lookup on destination (which fills egress interface id, destination mask and gateway). If one doesn't need data provided by lookups, he/she can disable them, to reduce load on routers. .It Dv NGM_NETFLOW_SETTEMPLATE Pq Ic settemplate Sets various timeouts to announce data flow templates (NetFlow v9-specific). This message requires .Vt "struct ng_netflow_settemplate" as an argument: .Bd -literal -offset 4n struct ng_netflow_settemplate { uint16_t time; /* max time between announce */ uint16_t packets; /* max packets between announce */ }; .Ed .Pp Value of time field represents time in seconds to re-announce data templates. Value of packets field represents maximum packets count between re-announcing data templates. .It Dv NGM_NETFLOW_SETMTU Pq Ic setmtu Sets export interface MTU to build packets of specified size (NetFlow v9-specific). This message requires .Vt "struct ng_netflow_setmtu" as an argument: .Bd -literal -offset 4n struct ng_netflow_setemtu { uint16_t mtu; /* MTU for packet */ }; .Ed .Pp Default is 1500 bytes. .It Dv NGM_NETFLOW_SHOW This control message asks a node to dump the entire contents of the flow cache. It is called from .Xr flowctl 8 , not directly from .Xr ngctl 8 . .It Dv NGM_NETFLOW_V9INFO Pq Ic v9info Returns some NetFlow v9 related values in a .Bd -literal -offset 4n struct ng_netflow_v9info { uint16_t templ_packets; /* v9 template packets */ uint16_t templ_time; /* v9 template time */ uint16_t mtu; /* v9 MTU */ }; .Ed .El .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message, or when all hooks have been disconnected. .Sh EXAMPLES The simplest possible configuration is one Ethernet interface, where flow collecting is enabled. .Bd -literal -offset indent /usr/sbin/ngctl -f- <<-SEQ mkpeer fxp0: netflow lower iface0 name fxp0:lower netflow connect fxp0: netflow: upper out0 mkpeer netflow: ksocket export inet/dgram/udp msg netflow:export connect inet/10.0.0.1:4444 SEQ .Ed .Pp This is a more complicated example of a router with 2 NetFlow-enabled interfaces .Li fxp0 and .Li ng0 . Note that the .Va ng0: node in this example is connected to .Xr ng_tee 4 . The latter sends us a copy of IP packets, which we analyze and free. On .Va fxp0: we do not use tee, but send packets back to either node. .Bd -literal -offset indent /usr/sbin/ngctl -f- <<-SEQ # connect ng0's tee to iface0 hook mkpeer ng0:inet netflow right2left iface0 name ng0:inet.right2left netflow # set DLT to raw mode msg netflow: setdlt { iface=0 dlt=12 } # set interface index (5 in this example) msg netflow: setifindex { iface=0 index=5 } # Connect fxp0: to iface1 and out1 hook connect fxp0: netflow: lower iface1 connect fxp0: netflow: upper out1 # Create ksocket node on export hook, and configure it # to send exports to proper destination mkpeer netflow: ksocket export inet/dgram/udp msg netflow:export connect inet/10.0.0.1:4444 SEQ .Ed .Sh SEE ALSO -.Xr netgraph 4 , .Xr setfib 2 , +.Xr netgraph 4 , .Xr ng_ether 4 , .Xr ng_iface 4 , .Xr ng_ksocket 4 , .Xr ng_tee 4 , .Xr flowctl 8 , .Xr ngctl 8 .Rs .%A B. Claise, Ed .%T "Cisco Systems NetFlow Services Export Version 9" .%O RFC 3954 .Re .Pp .Pa http://www.cisco.com/en/US/docs/ios/solutions_docs/netflow/nfwhite.html .Sh AUTHORS .An -nosplit The .Nm node type was written by .An Gleb Smirnoff Aq Mt glebius@FreeBSD.org , .An Alexander Motin Aq Mt mav@FreeBSD.org , .An Alexander Chernikov Aq Mt melifaro@ipfw.ru . The initial code was based on .Nm ng_ipacct written by .An Roman V. Palagin Aq Mt romanp@unshadow.net . .Sh BUGS Cache snapshot obtained via .Dv NGM_NETFLOW_SHOW command may lack some percentage of entries under severe load. .Pp The .Nm node type does not fill in AS numbers. This is due to the lack of necessary information in the kernel routing table. However, this information can be injected into the kernel from a routing daemon such as GNU Zebra. This functionality may become available in future releases. Index: head/share/man/man4/nvram2env.4 =================================================================== --- head/share/man/man4/nvram2env.4 (revision 275989) +++ head/share/man/man4/nvram2env.4 (revision 275990) @@ -1,116 +1,116 @@ .\" Copyright (c) 2011 Aleksandr Rybalko .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON 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 ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd April 3, 2011 .Dt NVRAM2ENV 4 .Os .Sh NAME .Nm nvram2env .Nd "copy nvram-like data into kernel environment" .Sh SYNOPSIS .Cd "device nvram2env" .Sh DESCRIPTION .Nm implements a simple method of reading the NVRAM-like data and information stored in flash and storing it in the kernel environment. It can then be used by various device drivers at boot-time. .Pp The NVRAM-like data is an array of zero terminated strings. Each string contains the string name, "=" delimiter and the string value. .Pp .Nm copies the environment values into kernel environment using the kernel setenv call. .Pp Configuration of .Nm is done in .Xr device.hints 5 defining the NVRAM base address, fallback base address, maxsize and flags. .Pp .Nm is currently MIPS-specific. .Ss base base - physical address where data block is stored. .Ss fallbackbase fallbackbase - physical address where data block is stored, but only if not found at base. .Ss maxsize maxsize - maximum size of data block. .Ss flags flags - control flags, used to select nvram type and enable/disable CRC check. .Bl -tag -width indent .It Fa 0x0001 Avoid CRC checking. Currently CRC checking is not implemented, so to be future compatible, please set it to "1". .It Fa 0x0002 Use format "Generic", skip uint32_t field, then zero terminating array of strings. .It Fa 0x0004 Use Broadcom CFE format. uint32_t signature "FLSH", uint32_t size, three unused fields uint32_t, then data. .It Fa 0x0008 Use U-Boot format, uint32_t crc, then zero terminating array of strings. .El .Sh EXAMPLES Usage in U-Boot case: .Bd -literal -offset indent hint.nvram.0.base=0x1f030000 hint.nvram.0.maxsize=0x2000 hint.nvram.0.flags=3 # 1 = No check, 2 = Format Generic hint.nvram.1.base=0x1f032000 hint.nvram.1.maxsize=0x4000 hint.nvram.1.flags=3 # 1 = No check, 2 = Format Generic .Ed .Pp CFE nvram with fallback: .Bd -literal -offset indent hint.nvram.0.base=0x1fff8000 hint.nvram.0.fallbackbase=0x1fc00400 hint.nvram.0.flags=4 # 4 = Format Broadcom .Ed .Pp but seems for CFE nvram preferred to read both blocks: .Pp NVRAM partition: Static, CFE internal .Bd -literal -offset indent hint.nvram.0.flags=0x05 # Broadcom + nocheck hint.nvram.0.base=0x1fc00400 .Ed .Pp Dynamic, editable form CFE, override values from first .Bd -literal -offset indent hint.nvram.1.flags=0x05 # Broadcom + nocheck hint.nvram.1.base=0x1cff8000 .Ed .Sh SEE ALSO .Xr kenv 1 , -.Xr kenv 2 . +.Xr kenv 2 .Sh HISTORY .Nm first appeared in .Fx 9.0 . .Sh AUTHORS .An Aleksandr Rybalko Aq Mt ray@ddteam.net Index: head/share/man/man4/pass.4 =================================================================== --- head/share/man/man4/pass.4 (revision 275989) +++ head/share/man/man4/pass.4 (revision 275990) @@ -1,120 +1,120 @@ .\" .\" Copyright (c) 1998, 1999 Kenneth D. Merry. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON 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 ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd October 10, 1998 .Dt PASS 4 .Os .Sh NAME .Nm pass .Nd CAM application passthrough driver .Sh SYNOPSIS .Cd device pass .Sh DESCRIPTION The .Nm driver provides a way for userland applications to issue CAM CCBs to the kernel. .Pp Since the .Nm driver allows direct access to the CAM subsystem, system administrators should exercise caution when granting access to this driver. If used improperly, this driver can allow userland applications to crash a machine or cause data loss. .Pp The .Nm driver attaches to every .Tn SCSI device found in the system. Since it attaches to every device, it provides a generic means of accessing .Tn SCSI devices, and allows the user to access devices which have no "standard" peripheral driver associated with them. .Sh KERNEL CONFIGURATION It is only necessary to configure one .Nm device in the kernel; .Nm devices are automatically allocated as .Tn SCSI devices are found. .Sh IOCTLS .Bl -tag -width 012345678901234 .It CAMIOCOMMAND This ioctl takes most kinds of CAM CCBs and passes them through to the CAM transport layer for action. Note that some CCB types are not allowed through the passthrough device, and must be sent through the .Xr xpt 4 device instead. Some examples of xpt-only CCBs are XPT_SCAN_BUS, XPT_DEV_MATCH, XPT_RESET_BUS, XPT_SCAN_LUN, XPT_ENG_INQ, and XPT_ENG_EXEC. These CCB types have various attributes that make it illogical or impossible to service them through the passthrough interface. .It CAMGETPASSTHRU This ioctl takes an XPT_GDEVLIST CCB, and returns the passthrough device corresponding to the device in question. Although this ioctl is available through the .Nm driver, it is of limited use, since the caller must already know that the device in question is a passthrough device if they are issuing this ioctl. It is probably more useful to issue this ioctl through the .Xr xpt 4 device. .El .Sh FILES .Bl -tag -width /dev/passn -compact .It Pa /dev/pass Ns Ar n Character device nodes for the .Nm driver. There should be one of these for each device accessed through the CAM subsystem. .El .Sh DIAGNOSTICS None. .Sh SEE ALSO .Xr cam 3 , -.Xr cam 4 , .Xr cam_cdbparse 3 , +.Xr cam 4 , .Xr xpt 4 , .Xr camcontrol 8 .Sh HISTORY The CAM passthrough driver first appeared in .Fx 3.0 . .Sh AUTHORS .An Kenneth Merry Aq Mt ken@FreeBSD.org .Sh BUGS It might be nice to have a way to asynchronously send CCBs through the passthrough driver. This would probably require some sort of read/write interface or an asynchronous ioctl interface. Index: head/share/man/man4/pccbb.4 =================================================================== --- head/share/man/man4/pccbb.4 (revision 275989) +++ head/share/man/man4/pccbb.4 (revision 275990) @@ -1,183 +1,183 @@ .\" .\" Copyright (c) 2002-2003 M. Warner Losh .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON 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 ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd July 21, 2004 .Dt PCCBB 4 .Os .Sh NAME .Nm pccbb .Nd cardbus bridge driver .Sh SYNOPSIS .Cd device cbb .Cd device pccard .Cd device cardbus .Cd device exca .Sh DESCRIPTION The .Nm driver implements the Yenta specification for CardBus bridges. .Pp The following PCI cardbus and pcmcia bridges are supported: .Pp .Bl -item -compact .It Cirrus Logic PD6832 .It Cirrus Logic PD6833 .It Cirrus Logic PD6834 .Pp .It O2micro OZ6812 .It O2micro OZ6832 .It O2micro OZ6833 .It O2micro OZ6836 .It O2micro OZ6860 .It O2micro OZ6872 .It O2micro OZ6912 .It O2micro OZ6922 .It O2micro OZ6933 .It O2micro OZ6972 .It O2Micro OZ711E1 .It O2Micro OZ711M1 .El .Bl -item -compact .It Ricoh RL4C475 .It Ricoh RL4C476 .It Ricoh RL4C477 .It Ricoh RL4C478 .Pp .It TI PCI-1031 .It TI PCI-1130 .It TI PCI-1131 .It TI PCI-1210 .It TI PCI-1211 .It TI PCI-1220 .It TI PCI-1221 .It TI PCI-1225 .It TI PCI-1250 .It TI PCI-1251 .It TI PCI-1251B .It TI PCI-1260 .It TI PCI-1260B .It TI PCI-1410 .It TI PCI-1420 .It TI PCI-1450 .It TI PCI-1451 .It TI PCI-1510 .It TI PCI-1515 .It TI PCI-1520 .It TI PCI-1530 .It TI PCI-1620 .It TI PCI-4410 .It TI PCI-4450 .It TI PCI-4451 .It TI PCI-4510 .It TI PCI-4520 .It TI PCI-[67]x[12]1 .It TI PCI-[67]x20 .It ENE CB710 .It ENE CB720 .It ENE CB1211 .It ENE CB1255 .It ENE CB1410 .It ENE CB1420 .Pp .It Toshiba ToPIC95 .It Toshiba ToPIC95B .It Toshiba ToPIC97 .It Toshiba ToPIC100 .El .Sh TUNABLES The driver supports the following tunable parameters, which may be added to .Pa /boot/loader.conf or set via the .Xr sysctl 8 command: .Bl -tag -width ".Cm hw.cbb.debug" -compact .It Cm hw.cbb.debug Non-zero values cause more verbose information to be printed to aid in debugging problems with the bridge chipset. .El .Sh SEE ALSO .Xr cardbus 4 , -.Xr pccard 4 , -.Xr exca 4 +.Xr exca 4 , +.Xr pccard 4 Index: head/share/man/man4/pflog.4 =================================================================== --- head/share/man/man4/pflog.4 (revision 275989) +++ head/share/man/man4/pflog.4 (revision 275990) @@ -1,107 +1,107 @@ .\" $OpenBSD: pflog.4,v 1.10 2007/05/31 19:19:51 jmc Exp $ .\" .\" Copyright (c) 2001 Tobias Weingartner .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 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 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" -.Dd May 31 2007 +.Dd May 31, 2007 .Dt PFLOG 4 .Os .Sh NAME .Nm pflog .Nd packet filter logging interface .Sh SYNOPSIS .Cd "device pflog" .Sh DESCRIPTION The .Nm pflog interface is a device which makes visible all packets logged by the packet filter, .Xr pf 4 . Logged packets can easily be monitored in real time by invoking .Xr tcpdump 1 on the .Nm interface, or stored to disk using .Xr pflogd 8 . .Pp The pflog0 interface is created automatically at boot if both .Xr pf 4 and .Xr pflogd 8 are enabled; further instances can be created using .Xr ifconfig 8 . .Pp Each packet retrieved on this interface has a header associated with it of length .Dv PFLOG_HDRLEN . This header documents the address family, interface name, rule number, reason, action, and direction of the packet that was logged. This structure, defined in .Aq Pa net/if_pflog.h looks like .Bd -literal -offset indent struct pfloghdr { u_int8_t length; sa_family_t af; u_int8_t action; u_int8_t reason; char ifname[IFNAMSIZ]; char ruleset[PF_RULESET_NAME_SIZE]; u_int32_t rulenr; u_int32_t subrulenr; uid_t uid; pid_t pid; uid_t rule_uid; pid_t rule_pid; u_int8_t dir; u_int8_t pad[3]; }; .Ed .Sh EXAMPLES Create a .Nm interface and monitor all packets logged on it: .Bd -literal -offset indent # ifconfig pflog1 up # tcpdump -n -e -ttt -i pflog1 .Ed .Sh SEE ALSO .Xr inet 4 , .Xr inet6 4 , .Xr netintro 4 , .Xr pf 4 , .Xr ifconfig 8 , .Xr pflogd 8 , .Xr tcpdump 1 .Sh HISTORY The .Nm device first appeared in .Ox 3.0 . .\" .Sh BUGS .\" Anything here? Index: head/share/man/man4/pfsync.4 =================================================================== --- head/share/man/man4/pfsync.4 (revision 275989) +++ head/share/man/man4/pfsync.4 (revision 275990) @@ -1,229 +1,229 @@ .\" $OpenBSD: pfsync.4,v 1.28 2009/02/17 10:05:18 dlg Exp $ .\" .\" Copyright (c) 2002 Michael Shalayeff .\" Copyright (c) 2003-2004 Ryan McBride .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF MIND, .\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 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 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" -.Dd December 20 2011 +.Dd December 20, 2011 .Dt PFSYNC 4 .Os .Sh NAME .Nm pfsync .Nd packet filter state table sychronisation interface .Sh SYNOPSIS .Cd "device pfsync" .Sh DESCRIPTION The .Nm interface is a pseudo-device which exposes certain changes to the state table used by .Xr pf 4 . State changes can be viewed by invoking .Xr tcpdump 1 on the .Nm interface. If configured with a physical synchronisation interface, .Nm will also send state changes out on that interface, and insert state changes received on that interface from other systems into the state table. .Pp By default, all local changes to the state table are exposed via .Nm . State changes from packets received by .Nm over the network are not rebroadcast. Updates to states created by a rule marked with the .Ar no-sync keyword are ignored by the .Nm interface (see .Xr pf.conf 5 for details). .Pp The .Nm interface will attempt to collapse multiple state updates into a single packet where possible. The maximum number of times a single state can be updated before a .Nm packet will be sent out is controlled by the .Ar maxupd parameter to ifconfig (see .Xr ifconfig 8 and the example below for more details). The sending out of a .Nm packet will be delayed by a maximum of one second. .Sh NETWORK SYNCHRONISATION States can be synchronised between two or more firewalls using this interface, by specifying a synchronisation interface using .Xr ifconfig 8 . For example, the following command sets fxp0 as the synchronisation interface: .Bd -literal -offset indent # ifconfig pfsync0 syncdev fxp0 .Ed .Pp By default, state change messages are sent out on the synchronisation interface using IP multicast packets to the 244.0.0.240 group address. An alternative destination address for .Nm packets can be specified using the .Ic syncpeer keyword. This can be used in combination with .Xr ipsec 4 to protect the synchronisation traffic. In such a configuration, the syncdev should be set to the .Xr enc 4 interface, as this is where the traffic arrives when it is decapsulated, e.g.: .Bd -literal -offset indent # ifconfig pfsync0 syncpeer 10.0.0.2 syncdev enc0 .Ed .Pp It is important that the pfsync traffic be well secured as there is no authentication on the protocol and it would be trivial to spoof packets which create states, bypassing the pf ruleset. Either run the pfsync protocol on a trusted network \- ideally a network dedicated to pfsync messages such as a crossover cable between two firewalls, or specify a peer address and protect the traffic with .Xr ipsec 4 . .Pp .Nm has the following .Xr sysctl 8 tunables: .Bl -tag -width ".Va net.pfsync" .It Va net.pfsync.carp_demotion_factor Value added to .Va net.inet.carp.demotion while .Nm tries to perform its bulk update. See .Xr carp 4 for more information. Default value is 240. .El .Sh EXAMPLES .Nm and .Xr carp 4 can be used together to provide automatic failover of a pair of firewalls configured in parallel. One firewall will handle all traffic until it dies, is shut down, or is manually demoted, at which point the second firewall will take over automatically. .Pp Both firewalls in this example have three .Xr sis 4 interfaces. sis0 is the external interface, on the 10.0.0.0/24 subnet; sis1 is the internal interface, on the 192.168.0.0/24 subnet; and sis2 is the .Nm interface, using the 192.168.254.0/24 subnet. A crossover cable connects the two firewalls via their sis2 interfaces. On all three interfaces, firewall A uses the .254 address, while firewall B uses .253. The interfaces are configured as follows (firewall A unless otherwise indicated): .Pp Interfaces configuration in .Pa /etc/rc.conf : .Bd -literal -offset indent network_interfaces="lo0 sis0 sis1 sis2" ifconfig_sis0="10.0.0.254/24" ifconfig_sis0_alias0="inet 10.0.0.1/24 vhid 1 pass foo" ifconfig_sis1="192.168.0.254/24" ifconfig_sis1_alias0="inet 192.168.0.1/24 vhid 2 pass bar" ifconfig_sis2="192.168.254.254/24" pfsync_enable="YES" pfsync_syncdev="sis2" .Ed .Pp .Xr pf 4 must also be configured to allow .Nm and .Xr carp 4 traffic through. The following should be added to the top of .Pa /etc/pf.conf : .Bd -literal -offset indent pass quick on { sis2 } proto pfsync keep state (no-sync) pass on { sis0 sis1 } proto carp keep state (no-sync) .Ed .Pp It is preferable that one firewall handle the forwarding of all the traffic, therefore the .Ar advskew on the backup firewall's .Xr carp 4 vhids should be set to something higher than the primary's. For example, if firewall B is the backup, its carp1 configuration would look like this: would look like this: .Bd -literal -offset indent ifconfig_sis1_alias0="inet 192.168.0.1/24 vhid 2 pass bar advskew 100" .Ed .Pp The following must also be added to .Pa /etc/sysctl.conf : .Bd -literal -offset indent net.inet.carp.preempt=1 .Ed .Sh SEE ALSO .Xr bpf 4 , .Xr carp 4 , .Xr enc 4 , .Xr inet 4 , .Xr inet6 4 , .Xr ipsec 4 , .Xr netintro 4 , .Xr pf 4 , .Xr pf.conf 5 , .Xr protocols 5 , .Xr rc.conf 5 , .Xr ifconfig 8 , .Xr tcpdump 1 .Sh HISTORY The .Nm device first appeared in .Ox 3.3 . It was first imported to .Fx 5.3 . .Pp The .Nm protocol and kernel implementation were significantly modified in .Fx 9.0 . The newer protocol is not compatible with older one and will not interoperate with it. Index: head/share/man/man4/pts.4 =================================================================== --- head/share/man/man4/pts.4 (revision 275989) +++ head/share/man/man4/pts.4 (revision 275990) @@ -1,158 +1,158 @@ .\" Copyright (c) 1983, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON 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 ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)pty.4 8.2 (Berkeley) 11/30/93 .\" $FreeBSD$ .\" .Dd August 20, 2008 .Dt PTS 4 .Os .Sh NAME .Nm pts .Nd pseudo-terminal driver .Sh DESCRIPTION The .Nm driver provides support for a device-pair termed a .Em pseudo-terminal . A pseudo-terminal is a pair of character devices, a .Em master device and a .Em slave device. The slave device provides to a process an interface identical to that described in .Xr tty 4 . However, whereas all other devices which provide the interface described in .Xr tty 4 have a hardware device of some sort behind them, the slave device has, instead, another process manipulating it through the master half of the pseudo-terminal. That is, anything written on the master device is given to the slave device as input and anything written on the slave device is presented as input on the master device. .Pp The following .Xr ioctl 2 calls apply only to pseudo-terminals: .Bl -tag -width TIOCPTMASTER .It Dv TIOCPKT Enable/disable .Em packet mode. Packet mode is enabled by specifying (by reference) a nonzero parameter and disabled by specifying (by reference) a zero parameter. When applied to the master side of a pseudo-terminal, each subsequent .Xr read 2 from the terminal will return data written on the slave part of the pseudo-terminal preceded by a zero byte (symbolically defined as .Dv TIOCPKT_DATA ) , or a single byte reflecting control status information. In the latter case, the byte is an inclusive-or of zero or more of the bits: .Bl -tag -width TIOCPKT_FLUSHWRITE .It Dv TIOCPKT_FLUSHREAD whenever the read queue for the terminal is flushed. .It Dv TIOCPKT_FLUSHWRITE whenever the write queue for the terminal is flushed. .It Dv TIOCPKT_STOP whenever output to the terminal is stopped a la .Ql ^S . .It Dv TIOCPKT_START whenever output to the terminal is restarted. .It Dv TIOCPKT_DOSTOP whenever .Dv VSTOP is .Ql ^S and .Dv VSTART is .Ql ^Q . .It Dv TIOCPKT_NOSTOP whenever the start and stop characters are not .Ql ^S/^Q . .El .Pp While this mode is in use, the presence of control status information to be read from the master side may be detected by a .Xr select 2 for exceptional conditions. .Pp This mode is used by .Xr rlogin 1 and .Xr rlogind 8 to implement a remote-echoed, locally .Ql ^S/^Q flow-controlled remote login with proper back-flushing of output; it can be used by other similar programs. .It Dv TIOCGPTN Obtain device unit number, which can be used to generate the filename of the pseudo-terminal slave device. This .Xr ioctl 2 should not be used directly. Instead, the .Xr ptsname 3 function should be used. .It Dv TIOCPTMASTER Determine whether the file descriptor is pointing to a pseudo-terminal master device. This .Xr ioctl 2 should not be used directly. It is used to implement routines like .Xr grantpt 3 . .El .Sh FILES The files used by this pseudo-terminals implementation are: .Bl -tag -width ".Pa /dev/pts/[num]" .It Pa /dev/pts/[num] Pseudo-terminal slave devices. .El .Sh DIAGNOSTICS None. .Sh SEE ALSO -.Xr grantpt 3 , .Xr posix_openpt 2 , +.Xr grantpt 3 , .Xr ptsname 3 , .Xr pty 4 , .Xr tty 4 .Sh HISTORY A pseudo-terminal driver appeared in .Bx 4.2 . In .Fx 8.0 , it was replaced with the .Nm driver. Index: head/share/man/man4/sa.4 =================================================================== --- head/share/man/man4/sa.4 (revision 275989) +++ head/share/man/man4/sa.4 (revision 275990) @@ -1,311 +1,311 @@ .\" Copyright (c) 1996 .\" Julian Elischer . All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON 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 ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd August 23, 2013 .Dt SA 4 .Os .Sh NAME .Nm sa .Nd SCSI Sequential Access device driver .Sh SYNOPSIS .Cd device sa .Sh DESCRIPTION The .Nm driver provides support for all .Tn SCSI devices of the sequential access class that are attached to the system through a supported .Tn SCSI Host Adapter. The sequential access class includes tape and other linear access devices. .Pp A .Tn SCSI Host adapter must also be separately configured into the system before a .Tn SCSI sequential access device can be configured. .Sh MOUNT SESSIONS The .Nm driver is based around the concept of a .Dq Em mount session , which is defined as the period between the time that a tape is mounted, and the time when it is unmounted. Any parameters set during a mount session remain in effect for the remainder of the session or until replaced. The tape can be unmounted, bringing the session to a close in several ways. These include: .Bl -enum .It Closing a `rewind device', referred to as sub-mode 00 below. An example is .Pa /dev/sa0 . .It Using the MTOFFL .Xr ioctl 2 command, reachable through the .Sq Cm offline command of .Xr mt 1 . .El .Pp It should be noted that tape devices are exclusive open devices, except in the case where a control mode device is opened. In the latter case, exclusive access is only sought when needed (e.g., to set parameters). .Sh SUB-MODES Bits 0 and 1 of the minor number are interpreted as .Sq sub-modes . The sub-modes differ in the action taken when the device is closed: .Bl -tag -width XXXX .It 00 A close will rewind the device; if the tape has been written, then a file mark will be written before the rewind is requested. The device is unmounted. .It 01 A close will leave the tape mounted. If the tape was written to, a file mark will be written. No other head positioning takes place. Any further reads or writes will occur directly after the last read, or the written file mark. .It 10 A close will rewind the device. If the tape has been written, then a file mark will be written before the rewind is requested. On completion of the rewind an unload command will be issued. The device is unmounted. .El .Sh BLOCKING MODES .Tn SCSI tapes may run in either .Sq Em variable or .Sq Em fixed block-size modes. Most .Tn QIC Ns -type devices run in fixed block-size mode, where most nine-track tapes and many new cartridge formats allow variable block-size. The difference between the two is as follows: .Bl -inset .It Variable block-size: Each write made to the device results in a single logical record written to the tape. One can never read or write .Em part of a record from tape (though you may request a larger block and read a smaller record); nor can one read multiple blocks. Data from a single write is therefore read by a single read. The block size used may be any value supported by the device, the .Tn SCSI adapter and the system (usually between 1 byte and 64 Kbytes, sometimes more). .Pp When reading a variable record/block from the tape, the head is logically considered to be immediately after the last item read, and before the next item after that. If the next item is a file mark, but it was never read, then the next process to read will immediately hit the file mark and receive an end-of-file notification. .It Fixed block-size: Data written by the user is passed to the tape as a succession of fixed size blocks. It may be contiguous in memory, but it is considered to be a series of independent blocks. One may never write an amount of data that is not an exact multiple of the blocksize. One may read and write the same data as a different set of records. In other words, blocks that were written together may be read separately, and vice-versa. .Pp If one requests more blocks than remain in the file, the drive will encounter the file mark. As there is some data to return (unless there were no records before the file mark), the read will succeed, returning that data. The next read will return immediately with a value of 0. (As above, if the file mark is never read, it remains for the next process to read if in no-rewind mode.) .El .Sh BLOCK SIZES By default, the driver will NOT accept reads or writes to a tape device that are larger than may be written to or read from the mounted tape using a single write or read request. Because of this, the application author may have confidence that his wishes are respected in terms of the block size written to tape. For example, if the user tries to write a 256KB block to the tape, but the controller can handle no more than 128KB, the write will fail. The previous .Fx behavior, prior to .Fx 10.0, was to break up large reads or writes into smaller blocks when going to the tape. The problem with that behavior, though, is that it hides the actual on-tape block size from the application writer, at least in variable block mode. .Pp If the user would like his large reads and writes broken up into separate pieces, he may set the following loader tunables. Note that these tunables WILL GO AWAY in .Fx 11.0 . They are provided for transition purposes only. .Bl -tag -width 12 .It kern.cam.sa.allow_io_split .Pp This variable, when set to 1, will configure all .Nm devices to split large buffers into smaller pieces when needed. .It kern.cam.sa.%d.allow_io_split .Pp This variable, when set to 1, will configure the given .Nm unit to split large buffers into multiple pieces. This will override the global setting, if it exists. .El .Pp There are several .Xr sysctl 8 variables available to view block handling parameters: .Bl -tag -width 12 .It kern.cam.sa.%d.allow_io_split .Pp This variable allows the user to see, but not modify, the current I/O split setting. The user is not permitted to modify this setting so that there is no chance of behavior changing for the application while a tape is mounted. .It kern.cam.sa.%d.maxio .Pp This variable shows the maximum I/O size in bytes that is allowed by the combination of kernel tuning parameters (MAXPHYS, DFLTPHYS) and the capabilities of the controller that is attached to the tape drive. Applications may look at this value for a guide on how large an I/O may be permitted, but should keep in mind that the actual maximum may be restricted further by the tape drive via the .Tn SCSI READ BLOCK LIMITS command. .It kern.cam.sa.%d.cpi_maxio .Pp This variable shows the maximum I/O size supported by the controller, in bytes, that is reported via the CAM Path Inquiry CCB (XPT_PATH_INQ). If this is 0, that means that the controller has not reported a maximum I/O size. .El .Sh FILE MARK HANDLING The handling of file marks on write is automatic. If the user has written to the tape, and has not done a read since the last write, then a file mark will be written to the tape when the device is closed. If a rewind is requested after a write, then the driver assumes that the last file on the tape has been written, and ensures that there are two file marks written to the tape. The exception to this is that there seems to be a standard (which we follow, but do not understand why) that certain types of tape do not actually write two file marks to tape, but when read, report a `phantom' file mark when the last file is read. These devices include the QIC family of devices. (It might be that this set of devices is the same set as that of fixed block devices. This has not been determined yet, and they are treated as separate behaviors by the driver at this time.) .Sh IOCTLS The .Nm driver supports all of the ioctls of .Xr mtio 4 . .Sh FILES .Bl -tag -width /dev/[n][e]sa[0-9] -compact .It Pa /dev/[n][e]sa[0-9] general form: .It Pa /dev/sa0 Rewind on close .It Pa /dev/nsa0 No rewind on close .It Pa /dev/esa0 Eject on close (if capable) .It Pa /dev/sa0.ctl Control mode device (to examine state while another program is accessing the device, e.g.). .El .Sh DIAGNOSTICS None. .Sh SEE ALSO -.Xr cam 4 , -.Xr mt 1 +.Xr mt 1 , +.Xr cam 4 .Sh AUTHORS .An -nosplit The .Nm driver was written for the .Tn CAM .Tn SCSI subsystem by .An Justin T. Gibbs and .An Kenneth Merry . Many ideas were gleaned from the .Nm st device driver written and ported from .Tn Mach 2.5 by .An Julian Elischer . .Pp The current owner of record is .An Matthew Jacob who has suffered too many years of breaking tape drivers. .Sh BUGS This driver lacks many of the hacks required to deal with older devices. Many older .Tn SCSI-1 devices may not work properly with this driver yet. .Pp Additionally, certain tapes (QIC tapes mostly) that were written under .Fx 2.X are not automatically read correctly with this driver: you may need to explicitly set variable block mode or set to the blocksize that works best for your device in order to read tapes written under .Fx 2.X. .Pp Fine grained density and compression mode support that is bound to specific device names needs to be added. .Pp Support for fast indexing by use of partitions is missing. Index: head/share/man/man4/send.4 =================================================================== --- head/share/man/man4/send.4 (revision 275989) +++ head/share/man/man4/send.4 (revision 275990) @@ -1,214 +1,214 @@ .\"- .\" Copyright (c) 2010 Ana Kukec .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON 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 ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd September 19, 2010 .Dt SEND 4 .Os .Sh NAME .Nm send .Nd "Kernel side support for Secure Neighbor Discovery (SeND)" .Sh SYNOPSIS .In sys/socket.h .In netinet/in.h .In netinet6/send.h .Ft int .Fn socket PF_INET6 SOCK_RAW IPPROTO_SEND .Pp To load the driver as a module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent send_load="YES" .Ed .Sh DESCRIPTION IPv6 nodes use the Neighbor Discovery Protocol (NDP) to discover other nodes on the link, to determine their link-layer addresses to find routers, and to maintain reachability information about the paths to active members. NDP is vulnerable to various attacks [RFC3756]. Secure Neighbor Discovery is a set of extensions to NDP that counter threats to NDP [RFC3971]. .Pp Kernel side support for SeND consists of a kernel module with hooks that divert relevant packets (Neighbor Solicitations, Neighbor Advertisements, Router Solicitations, Router Advertisements and Redirects) from the NDP stack, send them to user space on a dedicated socket and reinject them back for further processing. Hooks are triggered only if the .Nm module is loaded. .Pp The native SeND socket is similar to a raw IP socket, but with its own, internal pseudo-protocol (IPPROTO_SEND). Struct sockaddr_send is defined in .In netinet6/send.h . It defines the total length of the structure, the address family, packet's incoming or outgoing direction from the interface's point of view, and the interface index. .Bd -literal struct sockaddr_send { unsigned char send_len; /* total length */ sa_family_t send_family; /* address family */ int send_direction; int send_ifidx; char send_zero[8]; }; .Ed .Pp The address family is always .Va AF_INET6 . The .Va send_direction variable denotes the direction of the packet from the interface's point of view and has either the value .Dv SND_IN or .Dv SND_OUT . The .Va send_ifidx variable is the interface index of the receiving or sending interface. The .Va send_zero variable is padding and must always be zero. .Pp In case that no user space application is connected to the send socket, processing continues normally as if the module was not loaded. .Sh INPUT HOOK The input hook is named after the input path of the incoming or outgoing NDP packets, on the way from the wire, through the nd6 stack, to user space. Relevant packets are identified by adding an mbuf_tag (see .Xr mbuf_tags 9 ) to the .Xr mbuf 9 , if the .Nm module is loaded. It is then passed on to the kernel-userland interface for either cryptographic protection or validation by the SeND application. The hook takes an argument that describes the direction of the packet, both in case of incoming and outgoing packets. .Dv SND_IN is the direction of the incoming packets that are usually protected by the SeND options and then sent to user space for cryptographic validation. .Dv SND_OUT is the outgoing direction. It describes both reply and locally originated outgoing packets that are sent to user space for the addition of SeND options. .Sh INCOMING PACKETS The incoming ND packet from the wire: .Bd -literal kernelspace ( userspace ) incoming SeND/ND packet ( | ) v ( SND_IN ) ( icmp6_input() -> send_input_hook ---> send socket ----+ : ) | : # # ( | normal : # # ) v processing : # send.ko # ( SeND application path : # # ) | : # # ( | v ) | icmp6/nd6_??_input() <- protocol switch <--- send socket <---+ | structure (IPPPROTO_SEND) ) | ( SND_IN ) ( v ) continue normal ND processing ( .Ed .Sh OUTGOING PACKETS Outgoing ND packet (reply or locally triggered): .Bd -literal kernelspace ( userspace ) nd6_na_input() ( +PACKET_TAG_ND_OUTGOING ) | ) | outgoing packet ( | | ) | v ( | icmp6_redirect_output() ) | nd6_ns_output() ( | nd6_na_output() ) | +PACKET_TAG_ND_OUTGOING ( | | ) | +-----------<- rip6_output() <----------)----- rtsol/rtadvd/.. | | +PACKET_TAG_ND_OUTGOING ( | v ) | ip6_output() ( | | ) +-------->-+ ( | ) v ( SND_OUT ) ( nd6_output_lle() -> send_input_hook ---> send socket ----+ -PACKET_TAG_ND_OUTGOING ) | : # # ( | normal : # # ) v processing : # send.ko # ( SeND application path : # # ) | : # # ( | v ) | (*ifp->if_output)() <- protocol switch <--- send socket <---+ | structure (IPPPROTO_SEND) ) | ( SND_OUT ) ( v ) continue with normal packet output ( .Ed .Sh ERRORS A socket operation may fail with one of the following errors returned: .Bl -tag -width Er .It Bq Er EEXIST Another user space SeND application is bound to the socket. .It Bq Er ENOBUFS Shortage of space to receive the incoming (SeND-protected) or outgoing (SeND-validated) packet from the SeND application. .It Bq Er ENOSYS A packet received from user space and passed to the NDP stack for further processing is neither Neighbor Solicitation, Neighbor Advertisement, Router Solicitation, Router Advertisement nor Redirect. .It Bq Er ENOENT Occurs if interface output routines fail to send the packet out of the interface. .El .Sh SEE ALSO -.Xr recvfrom 2 -.Xr sendto 2 -.Xr socket 2 +.Xr recvfrom 2 , +.Xr sendto 2 , +.Xr socket 2 , .Xr loader.conf 5 .Sh HISTORY The .Nm module first appeared in .Fx 9.0 . .Sh AUTHORS .An Ana Kukec Aq Mt anchie@FreeBSD.org , University of Zagreb .Sh BUGS Due to the lack of NDP locking, it is currently not possible to unload the .Nm module. Index: head/share/man/man4/sfxge.4 =================================================================== --- head/share/man/man4/sfxge.4 (revision 275989) +++ head/share/man/man4/sfxge.4 (revision 275990) @@ -1,129 +1,129 @@ .\" Copyright (c) 2011 Solarflare Communications, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON 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 ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd September 30, 2014 .Dt SFXGE 4 .Os .Sh NAME .Nm sfxge .Nd "Solarflare 10Gb Ethernet adapter driver" .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device sfxge" .Ed .Pp To load the driver as a module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent sfxge_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for 10Gb Ethernet adapters based on Solarflare SFC9000 family controllers. The driver supports jumbo frames, transmit/receive checksum offload, TCP Segmentation Offload (TSO), Large Receive Offload (LRO), VLAN checksum offload, VLAN TSO, and Receive Side Scaling (RSS) using MSI-X interrupts. .Pp The driver allocates 1 receive queue, transmit queue, event queue and IRQ per CPU up to a maximum of 64. IRQ affinities should be spread out using .Xr cpuset 1 . Interrupt moderation may be controlled through the sysctl .Va dev.sfxge.%d.int_mod (units are microseconds). .Pp For more information on configuring this device, see .Xr ifconfig 8 . .Pp A large number of MAC, PHY and data path statistics are available under the sysctl .Va dev.sfxge.%d.stats . The adapter's VPD fields including its serial number are available under the sysctl .Va dev.sfxge.%d.vpd . .Sh HARDWARE The .Nm driver supports all 10Gb Ethernet adapters based on Solarflare SFC9000 family controllers. .Sh LOADER TUNABLES Tunables can be set at the .Xr loader 8 prompt before booting the kernel or stored in .Xr loader.conf 5 . Actual values can be obtained using .Xr sysctl 8 . .Bl -tag -width indent .It Va hw.sfxge.rx_ring The maximum number of descriptors in a receive queue ring. Supported values are: 512, 1024, 2048 and 4096. .It Va hw.sfxge.tx_ring The maximum number of descriptors in a transmit queue ring. Supported values are: 512, 1024, 2048 and 4096. .It Va hw.sfxge.tx_dpl_get_max The maximum length of the deferred packet .Dq get-list for queued transmit packets, used only if the transmit queue lock can be acquired. If a packet is dropped, the .Va tx_early_drops counter is incremented and the local sender receives ENOBUFS. The value must be greater than 0. .It Va hw.sfxge.tx_dpl_put_max The maximum length of the deferred packet .Dq put-list for queued transmit packets, used if the transmit queue lock cannot be acquired. If a packet is dropped, the .Va tx_early_drops counter is incremented and the local sender receives ENOBUFS. The value must be greater than or equal to 0. .El .Sh SUPPORT For general information and support, go to the Solarflare support website at: .Pa https://support.solarflare.com . .Sh SEE ALSO +.Xr cpuset 1 , .Xr arp 4 , .Xr netintro 4 , .Xr ng_ether 4 , .Xr vlan 4 , -.Xr cpuset 1 , .Xr ifconfig 8 .Sh AUTHORS The .Nm driver was written by .An Philip Paeps and .An Solarflare Communications, Inc. Index: head/share/man/man4/snd_hda.4 =================================================================== --- head/share/man/man4/snd_hda.4 (revision 275989) +++ head/share/man/man4/snd_hda.4 (revision 275990) @@ -1,635 +1,635 @@ .\" Copyright (c) 2006-2008 Joel Dahl .\" Copyright (c) 2008 Alexander Motin .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON 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 ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd January 25, 2012 .Dt SND_HDA 4 .Os .Sh NAME .Nm snd_hda .Nd "Intel High Definition Audio bridge device driver" .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device sound" .Cd "device snd_hda" .Ed .Pp Alternatively, to load the driver as a module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent snd_hda_load="YES" .Ed .Sh DESCRIPTION The High Definition (HD) Audio specification was developed by Intel as the logical successor of the old AC'97 specification and has several advantages, such as higher bandwidth which allows more channels and more detailed formats, support for several logical audio devices, and general purpose DMA channels. .Pp The .Nm driver includes HDA bus controller driver (hdac), HDA codec driver (hdacc) and HDA codecs audio functions bridge driver (hdaa) that allows the generic audio driver, .Xr sound 4 , to be used with this hardware. Only audio functions are supported by .Nm . Modem and other possible functions are not implemented. .Pp The .Nm driver supports hardware that conforms with revision 1.0 of the Intel High Definition Audio specification and tries to behave much like the Microsoft Universal Audio Architecture (UAA) draft (revision 0.7b) for handling audio devices. .Pp According to HDA and UAA specifications, depending on the number of HDA buses and codecs present in system, their audio capabilities and BIOS provided configuration, the .Nm driver often provides several PCM audio devices. For example, one device for main rear 7.1 output and inputs, one device for independent headset connectors at front and one device for SPDIF or HDMI audio input/output. The assignment of audio inputs and outputs may be tuned with .Xr device.hints 5 or .Xr sysctl 8 . The driver's verbose boot messages provide a lot of information about the operation of the driver and present audio setup. .Pp The default audio device may be tuned by setting the .Ar hw.snd.default_unit sysctl, as described in .Xr sound 4 , or explicitly specified in application settings. .Ss Boot-time Configuration The following variables are available at boot-time through the .Xr device.hints 5 file: .Bl -tag -width ".Va hint.hdac.%d.config"-offset indent .It Va hint.hdac.%d.config Configures a range of possible controller options. Possible values are: .Dq Li 64bit , .Dq Li dmapos , .Dq Li msi . An option prefixed with .Dq Li no , such as .Dq Li nomsi , will do the opposite and takes precedence. Options can be separated by whitespace and commas. .It Va hint.hdac.%d.msi Controls MSI (Message Signaled Interrupts) support. .It Va hint.hdac.%d.cad%d.nid%d.config Same as .Va hint.hdaa.%d.nid%d.config .It Va hint.hdaa.%d.config Configures a range of possible audio function options. Possible values are: .Dq Li eapdinv , .Dq Li ivref , .Dq Li ivref50 , .Dq Li ivref80 , .Dq Li ivref100 , .Dq Li fixedrate , .Dq Li forcestereo , .Dq Li ovref , .Dq Li ovref50 , .Dq Li ovref80 , .Dq Li ovref100 , .Dq Li senseinv , .Dq Li softpcmvol , and .Dq Li vref . An option prefixed with .Dq Li no , such as .Dq Li nofixedrate , will do the opposite and takes precedence. Options can be separated by whitespace and commas. .Pp The .Dq Li eapdinv option inverts External Amplifier Power Down signal. The .Dq Li fixedrate denies all sampling rates except 48KHz. The .Dq Li forcestereo denies mono playback/recording. The .Dq Li senseinv option inverts jack sensing logic. The .Dq Li ivref Ns Ar X and .Dq Li ovref Ns Ar X options control the voltage used to power external microphones. .It Va hint.hdaa.%d.gpio_config Overrides audio function GPIO pins configuration set by BIOS. May be specified as a set of space-separated .Dq Ar num Ns = Ns Ar value pairs, where .Ar num is GPIO line number, and .Ar value is one of: .Dq Li keep , .Dq Li set , .Dq Li clear , .Dq Li disable and .Dq Li input . .Pp .Dq Li GPIO Ns s are a codec's General Purpose I/O pins which system integrators sometimes use to control external muters, amplifiers and so on. If you have no sound, or sound volume is not adequate, you may have to experiment a bit with the GPIO setup to find the optimal setup for your system. .It Va hint.hdaa.%d.nid%d.config Overrides audio function pin configuration set by BIOS. May be specified as a 32-bit hexadecimal value with a leading .Dq 0x , or as a set of space-separated .Dq Ar option Ns = Ns Ar value pairs. .It Va hint.pcm.%d.rec.autosrc Controls automatic recording source feature: .Bl -tag -width 2n -compact .It 0 disabled, .It 1 once on attach, .It 2 enabled. .El When enabled, driver will automatically set recording source of the mixer to connected input using jack presence detection statuses. .El .Pp Pin configuration is the UAA driver's main source of information about codec usage. This information is usually provided by the codec manufacturer and tuned by system integrators for specific system requirements. The .Nm driver allows users to override it to fix integrator mistakes or to use the available codec in alternative ways (for example to get stereo output and 2 inputs instead of a single 5.1 output). .Pp The following options are supported: .Bl -tag -width ".Va device=" -offset indent .It Va as Association number. Associations are used to group individual pins to form a complex multi-pin device. For example, to group 4 connectors for 7.1 input/output, or to treat several input connectors as sources for the same input device. Association numbers can be specified as numeric values from 0 to 15. A value of 0 means disabled pin. A value of 15 is a set of independent unassociated pins. Each association includes only pins of the same direction (in/out) and is detected atomically (all pins or none). A separate PCM audio device is created for every pair of input and output associations. .It Va seq Sequence number. A unique, per-association number used to order pins inside the particular association. Sequence numbers can be specified as numeric values from 0 to 15. .Pp The sequence number 15 has a special meaning for output associations. Output pins with this number and device type .Dq Ar Headphones will duplicate (with automatic mute if jack detection is supported) the first pin in that association. .Pp The sequence numbers 14 and 15 has a special meaning for input associations. Their presence in association defines it as multiplexed or mixed respectively. If none of them are present and there are more than one pin in association, the association will provide multichannel input. .Pp For multichannel input/output associations sequence numbers encode channel pairs positions: 0 - Front, 1 - Center/LFE, 2 - Back, 3 - Front Wide Center, 4 - Side. Standard combinations are: (0) - Stereo; (0, 2), (0, 4) - Quadro; (0, 1, 2), (0, 1, 4) - 5.1; (0, 1, 2, 4) - 7.1. .It Va device Device type. Can be specified as a number from 0 to 15 or as a name: .Dq Li Line-out , .Dq Li Speaker , .Dq Li Headphones, .Dq Li CD , .Dq Li SPDIF-out , .Dq Li Digital-out , .Dq Li Modem-line , .Dq Li Modem-handset , .Dq Li Line-in , .Dq Li AUX , .Dq Li Mic , .Dq Li Telephony , .Dq Li SPDIF-in , .Dq Li Digital-in , .Dq Li Res.E , or .Dq Li Other . The device type also describes the pin direction (in/out). For example, .Dq Li CD always means an input pin, while .Dq Li Headphones always means an output. .It Va conn Connection type. Can be specified as a number from 0 to 3. The connection type can also be specified as one of the special names .Dq Li Jack , .Dq Li None , .Dq Li Fixed , or .Dq Li Both . Pins with a connection type of .Dq Li None are disabled. .It Va ctype Connector physical type. Can be specified as a number from 0 to 15. This is a reference only value. It is ignored by the .Nm driver. .It Va color Connector color. Can be specified as a number from 0 to 15 or as one of the names .Dq Li Unknown , .Dq Li Black , .Dq Li Grey , .Dq Li Blue , .Dq Li Green , .Dq Li Red , .Dq Li Orange , .Dq Li Yellow , .Dq Li Purple , .Dq Li Pink , .Dq Li Res.A , .Dq Li Res.B , .Dq Li Res.C , .Dq Li Res.D , .Dq Li White , or .Dq Li Other . This is a reference only value. It is ignored by the .Nm driver. .It Va loc Connector physical location. Can be specified as a number from 0 to 63. This is a reference only value. It is ignored by the .Nm driver. .It Va misc Misc bits. Can be specified as a number from 0 to 15. Bit 0 has a special meaning. When set it means that jack detection is not implemented in hardware. .El .Ss Runtime Configuration The following .Xr sysctl 8 variables are available in addition to those available to all .Xr sound 4 devices: .Bl -tag -width ".Va dev.hdaa.%d.nid%d_original" -offset indent .It Va dev.hdac.%d.pindump Setting this to a non-zero value dumps the current pin configuration, main capabilities and jack sense status of all audio functions on the controller to console and syslog. .It Va dev.hdac.%d.polling Enables polling mode. In this mode the driver operates by querying the device state on timer ticks using .Xr callout 9 instead of interrupts. Polling is disabled by default. Do not enable it unless you are facing weird interrupt problems or if the device cannot generate interrupts at all. .It Va dev.hdaa.%d.config Run-time equivalent of the .Va hint.hdaa.%d.config tunable. .It Va dev.hdaa.%d.gpi_state Current state of GPI lines. .It Va dev.hdaa.%d.gpio_state Current state of GPIO lines. .It Va dev.hdaa.%d.gpio_config Run-time equivalent of the .Va hint.hdaa.%d.gpio.config tunable. .It Va dev.hdaa.%d.gpo_state Current state of GPO lines. .It Va dev.hdaa.%d.nid%d_config Run-time equivalent of the .Va hint.hdaa.%d.nid%d.config tunable. .It Va dev.hdaa.%d.nid%d_original Original pin configuration written by BIOS. .It Va dev.hdaa.%d.reconfig Setting this to a non-zero value makes driver to destroy existing pcm devices and process new pins configuration set via .Va dev.hdaa.%d.nid%d_config . .It Va dev.pcm.%d.play.32bit , dev.pcm.%d.rec.32bit HDA controller uses 32bit representation for all samples of more then 16 bits. These variables allow to specify how many bits of these 32 should be used by CODEC. Depending on codec capabilities, possible values are 20, 24 and 32 bit. The default value is 24. .It Va dev.pcm.%d.rec.autosrc Run-time equivalent of the .Va hint.pcm.%d.rec.autosrc tunable. .El .Sh EXAMPLES Taking HP Compaq DX2300 with Realtek ALC888 HDA codec for example. This system has two audio connectors on a front side, three audio connectors on a rear side and one internal speaker. According to verbose driver output and the codec datasheet, this codec has five stereo DACs and two stereo ADCs, all of them are routable to any codec pin (external connector). All codec pins are reversible (could be configured either as input or output). .Pp So high codec uniformity and flexibility allow driver to configure it in many different ways, depending on requested pins usage described by pins configuration. The driver reports such default pin configuration when verbose messages enabled: .Bd -literal hdaa0: nid 0x as seq device conn jack loc color misc hdaa0: 20 01014020 2 0 Line-out Jack 1/8 Rear Green 0 hdaa0: 21 99130110 1 0 Speaker Fixed ATAPI Onboard Unknown 1 hdaa0: 22 411111f0 15 0 Speaker None 1/8 Rear Black 1 DISA hdaa0: 23 411111f0 15 0 Speaker None 1/8 Rear Black 1 DISA hdaa0: 24 01a19830 3 0 Mic Jack 1/8 Rear Pink 8 hdaa0: 25 02a1983f 3 15 Mic Jack 1/8 Front Pink 8 hdaa0: 26 01813031 3 1 Line-in Jack 1/8 Rear Blue 0 hdaa0: 27 0221401f 1 15 Headphones Jack 1/8 Front Green 0 hdaa0: 28 411111f0 15 0 Speaker None 1/8 Rear Black 1 DISA hdaa0: 30 411111f0 15 0 Speaker None 1/8 Rear Black 1 DISA hdaa0: 31 411111f0 15 0 Speaker None 1/8 Rear Black 1 DISA .Ed .Pp Here we can see, that the nodes with ID (nid) 25 and 27 are front panel connectors (Jack, Front), nids 20, 24 and 26 are rear panel connectors (Jack, Rear) and nid 21 is a built-in speaker (Fixed, Onboard). Pins with nids 22, 23, 28, 30 and 31 will be disabled by driver due to "None" connectivity. So the pin count and description matches to connectors that we have. .Pp Using association (as) and sequence (seq) fields values pins are grouped into 3 associations: .Bd -literal hdaa0: Association 0 (1) out: hdaa0: Pin nid=21 seq=0 hdaa0: Pin nid=27 seq=15 hdaa0: Association 1 (2) out: hdaa0: Pin nid=20 seq=0 hdaa0: Association 2 (3) in: hdaa0: Pin nid=24 seq=0 hdaa0: Pin nid=26 seq=1 hdaa0: Pin nid=25 seq=15 .Ed .Pp Each .Xr pcm 4 device uses two associations: one for playback and one for recording. Associations processed and assigned to .Xr pcm 4 devices in increasing numerical order. In this case association #0 (1) will become .Li pcm0 device playback, using the internal speakers and .Ar Headphones jack with speaker automute on the headphones jack connection. Association #1 (2) will become .Li pcm1 playback, using the .Ar Line-out jack. Association #2 (3) will become .Li pcm0 recording, using the external microphones and the .Ar Line-in jack. .Pp The .Nm driver provides extensive verbose messages to diagnose its operation logic and describe its current codec configuration. .Pp Using .Xr device.hints 5 it is possible to modify the configuration of the existing pins, allowing a broad range of different audio setups. Here are a few examples of some setups possible for this particular hardware: .Ss Example 1 Setting the .Xr device.hints 5 options .Bd -literal hint.hdac.0.cad0.nid20.config="as=1" hint.hdac.0.cad0.nid21.config="as=2" .Ed .Pp will swap line-out and speaker functions. So the .Li pcm0 device will play to the line-out and headphones jacks. Line-out will be muted on the headphones jack connection. Recording on .Li pcm0 will go from two external microphones and line-in jacks. .Li pcm1 playback will go to the internal speaker. .Ss Example 2 Setting the .Xr device.hints 5 options .Bd -literal hint.hdac.0.cad0.nid20.config="as=1 seq=15 device=Headphones" hint.hdac.0.cad0.nid27.config="as=2 seq=0" hint.hdac.0.cad0.nid25.config="as=4 seq=0" .Ed .Pp will split the headphones and one of the microphones to a separate device. The .Li pcm0 device will play to the internal speaker and to the line-out jack, with speaker automute on the line-out jack connection. Recording on .Li pcm0 will use input from one external microphone and the line-in jacks. The .Li pcm1 device will be completely dedicated to a headset (headphones and mic) connected to the front connectors. .Ss Example 3 Setting the .Xr device.hints 5 options .Bd -literal hint.hdac.0.cad0.nid20.config="as=1 seq=0" hint.hdac.0.cad0.nid26.config="as=2 seq=0" hint.hdac.0.cad0.nid27.config="as=3 seq=0" hint.hdac.0.cad0.nid25.config="as=4 seq=0" hint.hdac.0.cad0.nid24.config="as=5 seq=0 device=Line-out" hint.hdac.0.cad0.nid21.config="as=6 seq=0" .Ed .Pp will give 4 independent devices: .Li pcm0 .Pq line-out and line-in , .Li pcm1 .Pq headphones and mic , .Li pcm2 .Pq additional line-out via retasked rear mic jack , and .Li pcm3 .Pq internal speaker . .Ss Example 4 Setting the .Xr device.hints 5 options .Bd -literal hint.hdac.0.cad0.nid20.config="as=1 seq=0" hint.hdac.0.cad0.nid24.config="as=1 seq=1 device=Line-out" hint.hdac.0.cad0.nid26.config="as=1 seq=2 device=Line-out" hint.hdac.0.cad0.nid21.config="as=2 seq=0" .Ed .Pp will give 2 devices: .Li pcm0 for 5.1 playback via 3 rear connectors (line-out and retasked mic and line-in) and headset (headphones and mic) at front connectors. .Li pcm1 for internal speaker playback. On headphones connection rear connectors will be muted. .Sh MIXER CONTROLS Depending on codec configuration, these controls and signal sources could be reported to .Xr sound 4 : .Bl -tag -width ".Va speaker" -offset indent .It Va vol overall output level (volume) .It Va rec overall recording level .It Va igain input-to-output monitoring loopback level .It Va ogain external amplifier control .It Va pcm PCM playback .It Va mix input mix .It Va mic first external or second internal microphone input .It Va monitor first internal or second external microphone input .It Va line , Va line1 , Va line2, Va line3 analog (line) inputs .It Va dig1 , Va dig2 , Va dig3 digital (S/PDIF, HDMI or DisplayPort) inputs .It Va cd CD input .It Va speaker PC speaker input .It Va phin , Va phout , Va radio . Va video other random inputs .El .Pp Controls have different precision. Some could be just an on/off triggers. Most of controls use logarithmic scale. .Sh HARDWARE The .Nm driver supports controllers having PCI class 4 (multimedia) and subclass 3 (HDA), compatible with Intel HDA specification. .Pp The .Nm driver supports more than two hundred different controllers and CODECs. There is no sense to list all of them here, as in most cases specific CODEC configuration and wiring are more important then type of the CODEC itself. .Sh SEE ALSO -.Xr sound 4 , .Xr snd_ich 4 , +.Xr sound 4 , .Xr device.hints 5 , .Xr loader.conf 5 , .Xr sysctl 8 .Sh HISTORY The .Nm device driver first appeared in .Fx 6.3 . .Sh AUTHORS .An -nosplit The .Nm driver was written by .An Stephane E. Potvin Aq Mt sepotvin@videotron.ca , .An Ariff Abdullah Aq Mt ariff@FreeBSD.org and .An Alexander Motin Aq Mt mav@FreeBSD.org . This manual page was written by .An Joel Dahl Aq Mt joel@FreeBSD.org , .An Alexander Motin Aq Mt mav@FreeBSD.org and .An Giorgos Keramidas Aq Mt keramida@FreeBSD.org . .Sh BUGS Some Hardware/OEM vendors tend to screw up BIOS settings or use custom unusual CODEC wiring that create problems to the driver. This may result in missing pcm devices, or a state where the .Nm driver seems to attach and work, but no sound is played. Some cases can be solved by tuning .Pa loader.conf variables. But before trying to fix problem that way, make sure that there really is a problem and that the PCM audio device in use really corresponds to the expected audio connector. .Pp Some vendors use non-standardized General Purpose I/O (GPIO) pins of the codec to control external amplifiers. In some cases setting a combination of GPIO bits may be needed to make sound work on a specific device. .Pp HDMI and DisplayPort audio may also require support from video driver. Index: head/share/man/man4/snd_ich.4 =================================================================== --- head/share/man/man4/snd_ich.4 (revision 275989) +++ head/share/man/man4/snd_ich.4 (revision 275990) @@ -1,111 +1,111 @@ .\" Copyright (c) 2004 Jorge Mario G. Mazo .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON 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 ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd January 6, 2009 .Dt SND_ICH 4 .Os .Sh NAME .Nm snd_ich .Nd "Intel ICH AC'97 and compatible bridge device driver" .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device sound" .Cd "device snd_ich" .Ed .Pp Alternatively, to load the driver as a module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent snd_ich_load="YES" .Ed .Sh DESCRIPTION The .Nm bridge driver allows the generic audio driver .Xr sound 4 to attach to Intel ICH AC'97 and compatible audio devices. .Pp Some later chips, like ICH6/ICH7, depending on wiring can instead implement newer Intel HD Audio specification, which is supported by .Xr snd_hda 4 driver. .Sh HARDWARE The .Nm driver supports the following audio devices: .Pp .Bl -bullet -compact .It AMD 768 .It AMD 8111 .It Intel 443MX .It Intel ICH .It Intel ICH revision 1 .It Intel ICH2 .It Intel ICH3 .It Intel ICH4 .It Intel ICH5 .It Intel ICH6 .It Intel ICH7 .It NVIDIA nForce .It NVIDIA nForce2 .It NVIDIA nForce2 400 .It NVIDIA nForce3 .It NVIDIA nForce3 250 .It NVIDIA nForce4 .It SiS 7012 .El .Sh SEE ALSO -.Xr sound 4 , -.Xr snd_hda 4 +.Xr snd_hda 4 , +.Xr sound 4 .Sh HISTORY The .Nm device driver first appeared in .Fx 4.2 . .Sh AUTHORS This manual page was written by .An Jorge Mario G. Mazo Aq Mt jgutie11@eafit.edu.co . Index: head/share/man/man4/ural.4 =================================================================== --- head/share/man/man4/ural.4 (revision 275989) +++ head/share/man/man4/ural.4 (revision 275990) @@ -1,165 +1,165 @@ .\" Copyright (c) 2005, 2006 .\" Damien Bergamini .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" .\" $FreeBSD$ .\" .Dd April 13, 2008 .Dt URAL 4 .Os .Sh NAME .Nm ural .Nd "Ralink Technology RT2500USB IEEE 802.11 driver" .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device ehci" .Cd "device uhci" .Cd "device ohci" .Cd "device usb" .Cd "device ural" .Cd "device wlan" .Cd "device wlan_amrr" .Ed .Pp Alternatively, to load the driver as a module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent if_ural_load="YES" .Ed .Sh DESCRIPTION The .Nm driver supports USB 2.0 wireless adapters based on the RT2500USB chipset. .Pp The RT2500USB chipset consists of two integrated chips, a RT2570 MAC/BBP and a radio transceiver (the model of which depends on the card revision). .Pp The RT2522, RT2523, RT2524, RT2525, RT2525e and RT2526 radio transceivers operate in the 2.4GHz band (802.11b/g) whereas the RT5222 is a dual-band radio transceiver that can operate in the 2.4GHz and 5.2GHz bands (802.11a). .Pp .Nm supports .Cm station , .Cm adhoc , .Cm hostap , and .Cm monitor mode operation. Only one virtual interface may be configured at any time. For more information on configuring this device, see .Xr ifconfig 8 . .Sh HARDWARE The .Nm driver supports USB 2.0 wireless adapters based on the Ralink Technology RT2500USB chipset, including: .Pp .Bl -column -compact ".Li Atlantis Land A02-PCM-W54" "Bus" .It Em Card Ta Em Bus .It "AMIT WL532U" Ta USB .It "ASUS WL-167g" Ta USB .It "Belkin F5D7050 v2000" Ta USB .It "Buffalo WLI-U2-KG54-AI" Ta USB .It "CNet CWD-854" Ta USB .It "Compex WLU54G 2A1100" Ta USB .It "Conceptronic C54RU" Ta USB .It "D-Link DWL-G122 b1" Ta USB .It "Dynalink WLG25USB" Ta USB .It "E-Tech WGUS02" Ta USB .It "Gigabyte GN-WBKG" Ta USB .It "Hercules HWGUSB2-54" Ta USB .It "KCORP LifeStyle KLS-685" Ta USB .It "Linksys WUSB54G v4" Ta USB .It "Linksys WUSB54GP v4" Ta USB .It "MSI MS-6861" Ta USB .It "MSI MS-6865" Ta USB .It "MSI MS-6869" Ta USB .It "NovaTech NV-902" Ta USB .It "OvisLink Evo-W54USB" Ta USB .It "SerComm UB801R" Ta USB .It "SparkLAN WL-685R" Ta USB .It "Surecom EP-9001-g" Ta USB .It "Sweex LC100060" Ta USB .It "Tonze UW-6200C" Ta USB .It "Zinwell ZWX-G261" Ta USB .It "Zonet ZEW2500P" Ta USB .El .Pp An up to date list can be found at .Pa http://ralink.rapla.net/ . .Sh EXAMPLES Join an existing BSS network (i.e., connect to an access point): .Bd -literal -offset indent ifconfig wlan create wlandev ural0 inet 192.168.0.20 \e netmask 0xffffff00 .Ed .Pp Join a specific BSS network with network name .Dq Li my_net : .Pp .Dl "ifconfig wlan create wlandev ural0 ssid my_net up" .Pp Join a specific BSS network with 64-bit WEP encryption: .Bd -literal -offset indent ifconfig wlan create wlandev ural0 ssid my_net \e wepmode on wepkey 0x1234567890 weptxkey 1 up .Ed .Pp Join a specific BSS network with 128-bit WEP encryption: .Bd -literal -offset indent ifconfig wlan create wlandev ural0 wlanmode adhoc ssid my_net \e wepmode on wepkey 0x01020304050607080910111213 weptxkey 1 .Ed .Sh DIAGNOSTICS .Bl -diag .It "ural%d: device timeout" The driver will reset the hardware. This should not happen. .El .Sh SEE ALSO .Xr intro 4 , .Xr netintro 4 , .Xr usb 4 , .Xr wlan 4 , .Xr wlan_amrr 4 , .Xr wlan_ccmp 4 , .Xr wlan_tkip 4 , .Xr wlan_wep 4 , .Xr wlan_xauth 4 , -.Xr ifconfig 8 , .Xr hostapd 8 , -.Xr wpa_supplicant 8 . +.Xr ifconfig 8 , +.Xr wpa_supplicant 8 .Rs .%T "Ralink Technology" .%U http://www.ralinktech.com/ .Re .Sh HISTORY The .Nm driver first appeared in .Ox 3.7 . .Sh AUTHORS The original .Nm driver was written by .An Damien Bergamini Aq Mt damien.bergamini@free.fr . .Sh BUGS Host AP mode doesn't support client power save. Clients using power save mode will experience packet loss (disabling power saving on the client will fix this). Index: head/share/man/man4/usfs.4 =================================================================== --- head/share/man/man4/usfs.4 (revision 275989) +++ head/share/man/man4/usfs.4 (revision 275990) @@ -1,62 +1,62 @@ .\" .\" Copyright (c) 2014 Hans Petter Selasky .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON 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 ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd March 18, 2014 .Dt USFS 4 .Os .Sh NAME .Nm usfs .Nd USB device side support for bulk only transport mass storage .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device usb" .Cd "device usfs" .Ed .Pp Alternatively, to load the driver as a module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent usfs_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for emulating an USB mass storage device when the USB stack is activated in USB device side mode. .Pp Upon attach the driver creates a RAM disk which can be read and written. .Sh SEE ALSO -.Xr umass 4 +.Xr umass 4 , .Xr usb 4 .Sh HISTORY The .Nm driver appeared in FreeBSD 8. Index: head/share/man/man4/virtio_console.4 =================================================================== --- head/share/man/man4/virtio_console.4 (revision 275989) +++ head/share/man/man4/virtio_console.4 (revision 275990) @@ -1,67 +1,67 @@ .\" Copyright (c) 2014 Bryan Venteicher .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON 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 ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd October 22, 2014 .Dt VIRTIO_CONSOLE 4 .Os .Sh NAME .Nm virtio_console .Nd VirtIO Console driver .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device virtio_console" .Ed .Pp Alternatively, to load the driver as a module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent virtio_console_load="YES" .Ed .Sh DESCRIPTION The .Nm device driver provides support for VirtIO console devices. .Pp The console device may have one or more ports. Each port is similar to a simple serial interface, and each port is accessible through .Xr tty 4 . .Sh FILES .Bl -tag -width ".Pa /dev/ttyV?.??" -compact .It Pa /dev/ttyV?.?? .El .Sh SEE ALSO -.Xr tty 4 +.Xr tty 4 , .Xr virtio 4 .Sh HISTORY The .Nm driver was written by .An Bryan Venteicher Aq bryanv@FreeBSD.org . Index: head/share/man/man4/virtio_random.4 =================================================================== --- head/share/man/man4/virtio_random.4 (revision 275989) +++ head/share/man/man4/virtio_random.4 (revision 275990) @@ -1,61 +1,61 @@ .\" Copyright (c) 2013 Bryan Venteicher .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON 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 ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd December 28, 2013 .Dt VIRTIO_RANDOM 4 .Os .Sh NAME .Nm virtio_random .Nd VirtIO Entropy driver .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device virtio_random" .Ed .Pp Alternatively, to load the driver as a module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent virtio_random_load="YES" .Ed .Sh DESCRIPTION The .Nm device driver provides support for VirtIO entropy devices. .Pp The entropy device supplies high-quality randomness from the hypervisor to the guest. .Sh SEE ALSO -.Xr random 4 +.Xr random 4 , .Xr virtio 4 .Sh HISTORY The .Nm driver was written by .An Bryan Venteicher Aq Mt bryanv@FreeBSD.org . Index: head/share/man/man4/vxlan.4 =================================================================== --- head/share/man/man4/vxlan.4 (revision 275989) +++ head/share/man/man4/vxlan.4 (revision 275990) @@ -1,235 +1,235 @@ .\" Copyright (c) 2014 Bryan Venteicher .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON 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 ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd December 16, 2014 .Dt VXLAN 4 .Os .Sh NAME .Nm vxlan .Nd "Virtual eXtensible LAN interface" .Sh SYNOPSIS To compile this driver into the kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "device vxlan" .Ed .Pp Alternatively, to load the driver as a module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent if_vxlan_load="YES" .Ed .Sh DESCRIPTION The .Nm driver creates a virtual tunnel endpoint in a .Nm segment. A .Nm segment is a virtual Layer 2 (Ethernet) network that is overlaid in a Layer 3 (IP/UDP) network. .Nm is analogous to .Xr vlan 4 but is designed to be better suited for large, multiple tenant data center environments. .Pp Each .Nm interface is created at runtime using interface cloning. This is most easily done with the .Xr ifconfig 8 .Cm create command or using the .Va cloned_interfaces variable in .Xr rc.conf 5 . The interface may be removed with the .Xr ifconfig 8 .Cm destroy command. .Pp The .Nm driver creates a pseudo Ethernet network interface that supports the usual network .Xr ioctl 2 Ns s and is thus can be used with .Xr ifconfig 8 like any other Ethernet interface. The .Nm interface encapsulates the Ethernet frame by prepending IP/UDP and .Nm headers. Thus, the encapsulated (inner) frame is able to transmitted over a routed, Layer 3 network to the remote host. .Pp The .Nm interface may be configured in either unicast or multicast mode. When in unicast mode, the interface creates a tunnel to a single remote host, and all traffic is transmitted to that host. When in multicast mode, the interface joins an IP multicast group, and receives packets sent to the group address, and transmits packets to either the multicast group address, or directly the remote host if there is an appropriate forwarding table entry. .Pp When the .Nm interface is brought up, a .Xr UDP 4 .Xr socket 9 is created based on the configuration, such as the local address for unicast mode or the group address for multicast mode, and the listening (local) port number. Since multiple .Nm interfaces may be created that either use the same local address or join the same group address, and use the same port, the driver may share a socket among multiple interfaces. However, each interface within a socket must belong to a unique .Nm segment. The analogous .Xr vlan 4 configuration would be a physical interface configured as the parent device for multiple VLAN interfaces, each with a unique VLAN tag. Each .Nm segment is identified by a 24-bit value in the .Nm header called the .Dq VXLAN Network Identifier , or VNI. .Pp When configured with the .Xr ifconfig 8 .Cm vxlanlearn parameter, the interface dynamically creates forwarding table entries from received packets. An entry in the forwarding table maps the inner source MAC address to the outer remote IP address. During transmit, the interface attempts to lookup an entry for the encapsulated destination MAC address. If an entry is found, the IP address in the entry is used to directly transmit the encapsulated frame to the destination. Otherwise, when configured in multicast mode, the interface must flood the frame to all hosts in the group. The maximum number of entries in the table is configurable with the .Xr ifconfig 8 .Cm vxlanmaxaddr command. Stale entries in the table periodically pruned. The timeout is configurable with the .Xr ifconfig 8 .Cm vxlantimeout command. The table may be viewed with the .Xr sysctl 8 .Cm net.link.vxlan.N.ftable.dump command. .Sh MTU Since the .Nm interface encapsulates the Ethernet frame with an IP, UDP, and .Nm header, the resulting frame may be larger than the MTU of the physical network. The .Nm specification recommends the physical network MTU be configured to use jumbo frames to accommodate the encapsulated frame size. Alternatively, the .Xr ifconfig 8 .Cm mtu command may be used to reduce the MTU size on the .Nm interface to allow the encapsulated frame to fit in the current MTU of the physical network. .Sh EXAMPLES Create a .Nm interface in unicast mode with the .Cm vxlanlocal tunnel address of 192.168.100.1, and the .Cm vxlanremote tunnel address of 192.168.100.2. .Bd -literal -offset indent ifconfig vxlan create vxlanid 108 vxlanlocal 192.168.100.1 vxlanremote 192.168.100.2 .Ed .Pp Create a .Nm interface in multicast mode, with the .Cm local address of 192.168.10.95, and the .Cm group address of 224.0.2.6. The em0 interface will be used to transmit multicast packets. .Bd -literal -offset indent ifconfig vxlan create vxlanid 42 vxlanlocal 192.168.10.95 vxlangroup 224.0.2.6 vxlandev em0 .Ed .Pp Once created, the .Nm interface can be configured with .Xr ifconfig 8 . .Sh SEE ALSO -.Xr ifconfig 8 , .Xr inet 4 , -.Xr inet 6 , +.Xr inet6 4 , +.Xr ifconfig 8 , .Xr sysctl 8 , .Xr vlan 8 .Rs .%A "M. Mahalingam" .%A "et al" .%T "Virtual eXtensible Local Area Network (VXLAN): A Framework for Overlaying Virtualized Layer 2 Networks over Layer 3 Networks" .%D August 2014 .%O "RFC 7348" .Re .Sh AUTHOR .An -nosplit The .Nm driver was written by .An Bryan Venteicher Aq bryanv@freebsd.org . Index: head/share/man/man4/wpi.4 =================================================================== --- head/share/man/man4/wpi.4 (revision 275989) +++ head/share/man/man4/wpi.4 (revision 275990) @@ -1,144 +1,144 @@ .\" Copyright (c) 2004-2007 .\" Damien Bergamini . All rights reserved. .\" Benjamin Close . All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice unmodified, this list of conditions, and the following .\" disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON 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 ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd October 5, 2008 .Dt WPI 4 .Os .Sh NAME .Nm wpi .Nd "Intel 3945ABG Wireless LAN IEEE 802.11 driver" .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device wpi" .Cd "device wpifw" .Cd "device pci" .Cd "device wlan" .Cd "device wlan_amrr" .Cd "device firmware" .Ed .Pp Alternatively, to load the driver as a module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent if_wpi_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for the .Tn Intel 3945ABG Wireless network adapter. .Nm supports .Cm station , .Cm adhoc , and .Cm monitor mode operation. Only one virtual interface may be configured at any time. For more information on configuring this device, see .Xr ifconfig 8 . .Pp This driver requires the firmware built with the .Nm wpifw module to work. .Sh FILES .Bl -tag -width ".Pa /usr/share/doc/legal/intel_wpi/LICENSE" -compact .It Pa /usr/share/doc/legal/intel_wpi/LICENSE .Nm firmware license .El .Sh EXAMPLES Join an existing BSS network (i.e., connect to an access point): .Bd -literal -offset indent ifconfig wlan0 create wlandev wpi0 inet 192.168.0.20 \e netmask 0xffffff00 .Ed .Pp Join a specific BSS network with network name .Dq Li my_net : .Pp .Dl "ifconfig wlan0 create wlandev wpi0 ssid my_net up" .Pp Join a specific BSS network with 64-bit WEP encryption: .Bd -literal -offset indent ifconfig wlan0 create wlandev wpi0 ssid my_net \e wepmode on wepkey 0x1234567890 weptxkey 1 up .Ed .Pp Join a specific BSS network with 128-bit WEP encryption: .Bd -literal -offset indent ifconfig wlan0 create wlandev wpi0 wlanmode adhoc ssid my_net \e wepmode on wepkey 0x01020304050607080910111213 weptxkey 1 .Ed .Sh DIAGNOSTICS .Bl -diag .It "wpi%d: could not load firmware image '%s'" The driver failed to load the firmware image using the .Xr firmware 9 subsystem. Verify the .Xr wpifw firmware module is installed. .It "wpi%d: fatal firmware error" An unknown error has occurred in the uploaded firmware, you may have to unload/reload the driver to continue. .It "wpi%d: Radio transmitter is switched off" The hardware switch controlling the radio is currently turned off. Data transmission is not possible in this state. .El .Sh SEE ALSO -.Xr wpifw 4 , .Xr pci 4 , .Xr wlan 4 , .Xr wlan_ccmp 4 , .Xr wlan_tkip 4 , .Xr wlan_wep 4 , +.Xr wpifw 4 , .Xr ifconfig 8 , .Xr wpa_supplicant 8 .Sh AUTHORS .An -nosplit The original .Nm driver was written for .Ox by .An Damien Bergamini Aq Mt damien.bergamini@free.fr . .An Benjamin Close Aq Mt benjsc@FreeBSD.org ported .Nm to .Fx . .Sh BUGS Not all the error messages are documented here. .Pp Background scanning is not currently supported.