Index: head/share/man/man4/cloudabi.4 =================================================================== --- head/share/man/man4/cloudabi.4 (revision 286662) +++ head/share/man/man4/cloudabi.4 (revision 286663) @@ -1,103 +1,102 @@ .\" Copyright (c) 2015 Nuxi, https://nuxi.nl/ .\" .\" 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 July 31, 2015 .Dt CLOUDABI 4 .Os .Sh NAME .Nm cloudabi , .Nm cloudabi64 .Nd CloudABI support .Sh SYNOPSIS Support for 64-bit CloudABI executables can be compiled into the kernel by adding this line to the kernel configuration file: .Bd -ragged -offset indent .Cd "options COMPAT_CLOUDABI64" .Ed .Pp CloudABI support can also be loaded at boot time from .Xr loader.conf 5 : .Bd -literal -offset indent cloudabi_load="YES" cloudabi64_load="YES" .Ed .Sh DESCRIPTION CloudABI is a POSIX-like pure capability-based runtime environment, similar to .Xr capsicum 4 . It can be used to develop applications that are cross-platform, easier to test, and hardened against security exploits. .Pp Support for CloudABI on .Fx consists of two separate kernel modules. The .Nm cloudabi kernel module implements all of the system calls that do not depend on data structures that differ between architectures. .Pp The .Nm cloudabi64 kernel module provides implementations of all of the machine-dependent system calls. It assumes that pointers stored in data structures provided as system call arguments are 64 bits in size. It also provides the image activator that loads and starts 64-bit ELF executables. .Pp Though the .Nm cloudabi module can be loaded on any architecture supported by .Fx , the .Nm cloudabi64 module is only available for amd64. .Pp A full cross compilation toolchain for CloudABI is available in the .Pa devel/cloudabi-toolchain port. .Pp The .Pa sysutils/cloudabi-utils port provides the .Xr cloudabi-run 1 utility. .Xr cloudabi-run 1 can be used to safely execute CloudABI processes with access to a restricted set of resources. .Sh SEE ALSO .Xr cloudabi-run 1 , .Xr capsicum 4 , .Xr linux 4 , .Xr elf 5 .Pp cloudlibc on GitHub: .Pa https://github.com/NuxiNL/cloudlibc . .Sh HISTORY CloudABI support first appeared in .Fx 11.0 . .Sh AUTHORS -Nuxi: -.Pa https://nuxi.nl/ . +.An Nuxi : Pa https://nuxi.nl/ . Index: head/share/man/man4/ctl.4 =================================================================== --- head/share/man/man4/ctl.4 (revision 286662) +++ head/share/man/man4/ctl.4 (revision 286663) @@ -1,135 +1,136 @@ .\" Copyright (c) 2013 Edward Tomasz Napierala .\" 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 9, 2015 .Dt CTL 4 .Os .Sh NAME .Nm ctl .Nd CAM Target Layer / iSCSI target .Sh SYNOPSIS To compile this driver into the kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "device iscsi" .Cd "device ctl" .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 ctl_load="YES" .Ed .Sh DESCRIPTION The .Nm subsystem provides SCSI disk and processor emulation. It supports features such as: .Pp .Bl -bullet -compact .It Disk and processor device emulation .It Tagged queueing .It SCSI task attribute support (ordered, head of queue, simple tags) .It SCSI implicit command ordering support .It Full task management support (abort, LUN reset, target reset, etc.) .It Support for multiple ports .It Support for multiple simultaneous initiators .It Support for multiple simultaneous backing stores .It Support for VMWare VAAI: COMPARE AND WRITE, XCOPY, WRITE SAME, and UNMAP commands .It Support for Microsoft ODX: POPULATE TOKEN/WRITE USING TOKEN, WRITE SAME, and UNMAP commands .It Persistent reservation support .It Mode sense/select support .It Error injection support .It All I/O handled in-kernel, no userland context switch overhead .El .Pp It also serves as a kernel component of the native iSCSI target. .Sh SYSCTL VARIABLES The following variables are available as both .Xr sysctl 8 variables and .Xr loader 8 tunables: .Bl -tag -width indent .It Va kern.cam.ctl.debug Bit mask of enabled CTL log levels: .Bl -tag -offset indent -compact .It 1 log commands with errors; .It 2 log all commands; .It 4 log received data for commands except READ/WRITE. .El Defaults to 0. .It Va kern.cam.ctl.iscsi.debug Verbosity level for log messages from the kernel part of iSCSI target. Set to 0 to disable logging or 1 to warn about potential problems. Larger values enable debugging output. Defaults to 1. .It Va kern.cam.ctl.iscsi.maxcmdsn_delta The number of outstanding commands to advertise to the iSCSI initiator. Technically, it is the difference between ExpCmdSN and MaxCmdSN fields in the iSCSI PDU. Defaults to 256. .It Va kern.cam.ctl.iscsi.ping_timeout The number of seconds to wait for the iSCSI initiator to respond to a NOP-In PDU. In the event that there is no response within that time the session gets forcibly terminated. Set to 0 to disable sending NOP-In PDUs. Defaults to 5. +.El .Sh SEE ALSO .Xr ctladm 8 , .Xr ctld 8 , .Xr ctlstat 8 .Sh HISTORY The .Nm subsystem first appeared in .Fx 9.1 . .Sh AUTHORS The .Nm subsystem was written by .An Kenneth Merry Aq Mt ken@FreeBSD.org . Index: head/share/man/man4/em.4 =================================================================== --- head/share/man/man4/em.4 (revision 286662) +++ head/share/man/man4/em.4 (revision 286663) @@ -1,311 +1,310 @@ .\" Copyright (c) 2001-2003, Intel Corporation .\" 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 Intel Corporation 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 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 OWNER 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. .\" .\" * Other names and brands may be claimed as the property of others. .\" .\" $FreeBSD$ .\" .Dd October 11, 2011 .Dt EM 4 .Os .Sh NAME .Nm em .Nd "Intel(R) PRO/1000 Gigabit Ethernet adapter driver" .Sh SYNOPSIS To compile this driver into the kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "device em" .Ed .Pp Optional multiqueue support is available via the following kernel compile options: .Bd -ragged -offset indent .Cd "options EM_MULTIQUEUE" .Ed .Pp Note: Activating EM_MULTIQUEUE support is not supported by Intel. .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_em_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for PCI Gigabit Ethernet adapters based on the Intel 82540, 82541ER, 82541PI, 82542, 82543, 82544, 82545, 82546, 82546EB, 82546GB, 82547, 82571, 81572, 82573, and 82574 Ethernet controller chips. The driver supports Transmit/Receive checksum offload and Jumbo Frames on all but 82542-based adapters. Furthermore it supports TCP segmentation offload (TSO) on all adapters but those based on the 82543, 82544 and 82547 controller chips. The identification LEDs of the adapters supported by the .Nm driver can be controlled via the .Xr led 4 API for localization purposes. For further hardware information, see the .Pa README included with the driver. .Pp For questions related to hardware requirements, refer to the documentation supplied with your Intel PRO/1000 adapter. All hardware requirements listed apply to use with .Fx . .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. The maximum MTU size for Jumbo Frames is 16114. .Pp This driver version supports VLANs. The .Nm driver supports the following media types: .Bl -tag -width ".Cm 10baseT/UTP" .It Cm autoselect Enables auto-negotiation for speed and duplex. .It Cm 10baseT/UTP Sets 10Mbps operation. Use the .Cm mediaopt option to select .Cm full-duplex mode. .It Cm 100baseTX Sets 100Mbps operation. Use the .Cm mediaopt option to select .Cm full-duplex mode. .It Cm 1000baseSX Sets 1000Mbps operation. Only .Cm full-duplex mode is supported at this speed. .It Cm 1000baseTX Sets 1000Mbps operation. Only .Cm full-duplex mode is supported at this speed. .El .Pp The .Nm driver supports the following media options: .Bl -tag -width ".Cm full-duplex" .It Cm full-duplex Forces full-duplex operation .It Cm half-duplex Forces half-duplex operation. .El .Pp Only use .Cm mediaopt to set the driver to .Cm full-duplex . If .Cm mediaopt is not specified, the driver defaults to .Cm half-duplex . .Pp For more information on configuring this device, see .Xr ifconfig 8 . .Sh HARDWARE The .Nm driver supports Gigabit Ethernet adapters based on the Intel 82540, 82541ER, 82541PI, 82542, 82543, 82544, 82545, 82546, 82546EB, 82546GB, 82547, 82571, 82572, 82573, and 82574 controller chips: .Pp .Bl -bullet -compact .It Intel PRO/1000 CT Network Connection (82547) .It Intel PRO/1000 F Server Adapter (82543) .It Intel PRO/1000 Gigabit Server Adapter (82542) .It Intel PRO/1000 GT Desktop Adapter (82541PI) .It Intel PRO/1000 MF Dual Port Server Adapter (82546) .It Intel PRO/1000 MF Server Adapter (82545) .It Intel PRO/1000 MF Server Adapter (LX) (82545) .It Intel PRO/1000 MT Desktop Adapter (82540) .It Intel PRO/1000 MT Desktop Adapter (82541) .It Intel PRO/1000 MT Dual Port Server Adapter (82546) .It Intel PRO/1000 MT Quad Port Server Adapter (82546EB) .It Intel PRO/1000 MT Server Adapter (82545) .It Intel PRO/1000 PF Dual Port Server Adapter (82571) .It Intel PRO/1000 PF Quad Port Server Adapter (82571) .It Intel PRO/1000 PF Server Adapter (82572) .It Intel PRO/1000 PT Desktop Adapter (82572) .It Intel PRO/1000 PT Dual Port Server Adapter (82571) .It Intel PRO/1000 PT Quad Port Server Adapter (82571) .It Intel PRO/1000 PT Server Adapter (82572) .It Intel PRO/1000 T Desktop Adapter (82544) .It Intel PRO/1000 T Server Adapter (82543) .It Intel PRO/1000 XF Server Adapter (82544) .It Intel PRO/1000 XT Server Adapter (82544) .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.em.eee_setting Disable or enable Energy Efficient Ethernet. Default 1 (disabled). .It Va hw.em.msix Enable or disable MSI-X style interrupts. Default 1 (enabled). .It Va hw.em.smart_pwr_down Enable or disable smart power down features on newer adapters. Default 0 (disabled). .It Va hw.em.sbp Show bad packets when in promiscuous mode. Default 0 (off). .It Va hw.em.rxd Number of receive descriptors allocated by the driver. The default value is 1024 for adapters newer than 82547, and 256 for older ones. The 82542 and 82543-based adapters can handle up to 256 descriptors, while others can have up to 4096. .It Va hw.em.txd Number of transmit descriptors allocated by the driver. The default value is 1024 for adapters newer than 82547, and 256 for older ones. The 82542 and 82543-based adapters can handle up to 256 descriptors, while others can have up to 4096. .It Va hw.em.rx_int_delay This value delays the generation of receive interrupts in units of 1.024 microseconds. The default value is 0, since adapters may hang with this feature being enabled. .It Va hw.em.rx_abs_int_delay If .Va hw.em.rx_int_delay is non-zero, this tunable limits the maximum delay in which a receive interrupt is generated. .It Va hw.em.tx_int_delay This value delays the generation of transmit interrupts in units of 1.024 microseconds. The default value is 64. .It Va hw.em.tx_abs_int_delay If .Va hw.em.tx_int_delay is non-zero, this tunable limits the maximum delay in which a transmit interrupt is generated. .It Va hw.em.num_queues Number of hardware queues that will be configured on this adapter (maximum of 2) Defaults to 1. Only valid with kernel configuration .Cd "options EM_MULTIQUEUE". .El .Sh FILES .Bl -tag -width /dev/led/em* .It Pa /dev/led/em* identification LED device nodes .El .Sh EXAMPLES Make the identification LED of em0 blink: .Pp .Dl "echo f2 > /dev/led/em0" .Pp Turn the identification LED of em0 off again: .Pp .Dl "echo 0 > /dev/led/em0" .Sh DIAGNOSTICS .Bl -diag .It "em%d: Unable to allocate bus resource: memory" A fatal initialization error has occurred. .It "em%d: Unable to allocate bus resource: interrupt" A fatal initialization error has occurred. .It "em%d: watchdog timeout -- resetting" The device has stopped responding to the network, or there is a problem with the network connection (cable). .El .Sh SUPPORT For general information and support, go to the Intel support website at: .Pa http://support.intel.com . .Pp If an issue is identified with the released source code on the supported kernel with a supported adapter, email the specific information related to the issue to .Aq Mt freebsd@intel.com . .Sh SEE ALSO .Xr altq 4 , .Xr arp 4 , .Xr igb 4 , .Xr led 4 , .Xr netintro 4 , .Xr ng_ether 4 , .Xr polling 4 , .Xr vlan 4 , .Xr ifconfig 8 .Sh HISTORY The .Nm device driver first appeared in .Fx 4.4 . .Sh AUTHORS The .Nm driver was written by .An Intel Corporation Aq Mt freebsd@intel.com . .Sh BUGS -.Pp Activating EM_MULTIQUEUE support requires MSI-X features. Index: head/share/man/man4/gre.4 =================================================================== --- head/share/man/man4/gre.4 (revision 286662) +++ head/share/man/man4/gre.4 (revision 286663) @@ -1,195 +1,194 @@ .\" $NetBSD: gre.4,v 1.28 2002/06/10 02:49:35 itojun Exp $ .\" .\" Copyright 1998 (c) The NetBSD Foundation, Inc. .\" All rights reserved. .\" .\" This code is derived from software contributed to The NetBSD Foundation .\" by Heiko W.Rupp .\" .\" 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. .\" .\" $FreeBSD$ .\" .Dd June 2, 2015 .Dt GRE 4 .Os .Sh NAME .Nm gre .Nd encapsulating network device .Sh SYNOPSIS To compile the driver into the kernel, place the following line in the kernel configuration file: .Bd -ragged -offset indent .Cd "device gre" .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_gre_load="YES" .Ed .Sh DESCRIPTION The .Nm network interface pseudo device encapsulates datagrams into IP. These encapsulated datagrams are routed to a destination host, where they are decapsulated and further routed to their final destination. The .Dq tunnel appears to the inner datagrams as one hop. .Pp .Nm interfaces are dynamically created and destroyed with the .Xr ifconfig 8 .Cm create and .Cm destroy subcommands. .Pp This driver corresponds to RFC 2784. Encapsulated datagrams are prepended an outer datagram and a GRE header. The GRE header specifies the type of the encapsulated datagram and thus allows for tunneling other protocols than IP. GRE mode is also the default tunnel mode on Cisco routers. .Nm also supports Cisco WCCP protocol, both version 1 and version 2. .Pp The .Nm interfaces support a number of additional parameters to the .Xr ifconfig 8 : .Bl -tag -width "enable_csum" .It Ar grekey Set the GRE key used for outgoing packets. A value of 0 disables the key option. .It Ar enable_csum Enables checksum calculation for outgoing packets. .It Ar enable_seq Enables use of sequence number field in the GRE header for outgoing packets. .El .Sh EXAMPLES .Bd -literal 192.168.1.* --- Router A -------tunnel-------- Router B --- 192.168.2.* \\ / \\ / +------ the Internet ------+ .Ed .Pp Assuming router A has the (external) IP address A and the internal address 192.168.1.1, while router B has external address B and internal address 192.168.2.1, the following commands will configure the tunnel: .Pp On router A: .Bd -literal -offset indent ifconfig greN create ifconfig greN inet 192.168.1.1 192.168.2.1 ifconfig greN inet tunnel A B route add -net 192.168.2 -netmask 255.255.255.0 192.168.2.1 .Ed .Pp On router B: .Bd -literal -offset indent ifconfig greN create ifconfig greN inet 192.168.2.1 192.168.1.1 ifconfig greN inet tunnel B A route add -net 192.168.1 -netmask 255.255.255.0 192.168.1.1 .Ed .Pp In case when internal and external IP addresses are the same, different routing tables (FIB) should be used. The default FIB will be applied to IP packets before GRE encapsulation. After encapsulation GRE interface should set different FIB number to outgoing packet. Then different FIB will be applied to such encapsulated packets. According to this FIB packet should be routed to tunnel endpoint. .Bd -literal Host X -- Host A (198.51.100.1) ---tunnel--- Cisco D (203.0.113.1) -- Host E \\ / \\ / +----- Host B ----- Host C -----+ (198.51.100.254) .Ed .Pp On Host A (FreeBSD): .Pp First of multiple FIBs should be configured via loader.conf: .Bd -literal -offset indent net.fibs=2 net.add_addr_allfibs=0 .Ed .Pp Then routes to the gateway and remote tunnel endpoint via this gateway should be added to the second FIB: .Bd -literal -offset indent route add -net 198.51.100.0 -netmask 255.255.255.0 -fib 1 -iface em0 route add -host 203.0.113.1 -fib 1 198.51.100.254 .Ed .Pp And GRE tunnel should be configured to change FIB for encapsulated packets: .Bd -literal -offset indent ifconfig greN create ifconfig greN inet 198.51.100.1 203.0.113.1 ifconfig greN inet tunnel 198.51.100.1 203.0.113.1 tunnelfib 1 .Ed -.Pp .Sh NOTES The MTU of .Nm interfaces is set to 1476 by default, to match the value used by Cisco routers. This may not be an optimal value, depending on the link between the two tunnel endpoints. It can be adjusted via .Xr ifconfig 8 . .Pp For correct operation, the .Nm device needs a route to the decapsulating host that does not run over the tunnel, as this would be a loop. .Pp The kernel must be set to forward datagrams by setting the .Va net.inet.ip.forwarding .Xr sysctl 8 variable to non-zero. .Sh SEE ALSO .Xr gif 4 , .Xr inet 4 , .Xr ip 4 , .Xr me 4 , .Xr netintro 4 , .Xr protocols 5 , .Xr ifconfig 8 , .Xr sysctl 8 .Pp A description of GRE encapsulation can be found in RFC 2784 and RFC 2890. .Sh AUTHORS .An Andrey V. Elsukov Aq Mt ae@FreeBSD.org .An Heiko W.Rupp Aq Mt hwr@pilhuhn.de .Sh BUGS The current implementation uses the key only for outgoing packets. Incoming packets with a different key or without a key will be treated as if they would belong to this interface. .Pp The sequence number field also used only for outgoing packets. Index: head/share/man/man4/hptiop.4 =================================================================== --- head/share/man/man4/hptiop.4 (revision 286662) +++ head/share/man/man4/hptiop.4 (revision 286663) @@ -1,138 +1,139 @@ .\" Copyright (c) 2007 Christian Brueffer .\" 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 July 5, 2013 .Dt HPTIOP 4 .Os .Sh NAME .Nm hptiop .Nd "HighPoint RocketRAID 3xxx/4xxx device driver" .Sh SYNOPSIS To compile this driver into the kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "device hptiop" .Cd "device scbus" .Cd "device da" .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 hptiop_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for the HighPoint RocketRAID 3xxx/4xxx series of SAS and SATA RAID controllers. .Sh HARDWARE The .Nm driver supports the following SAS and SATA RAID controllers: .Pp .Bl -bullet -compact .It HighPoint RocketRAID 4522 .It HighPoint RocketRAID 4521 .It HighPoint RocketRAID 4520 .It HighPoint RocketRAID 4322 .It HighPoint RocketRAID 4321 .It HighPoint RocketRAID 4320 .It HighPoint RocketRAID 4311 .It HighPoint RocketRAID 4310 .It HighPoint RocketRAID 3640 .It HighPoint RocketRAID 3622 .It HighPoint RocketRAID 3620 .El .Pp The .Nm driver also supports the following SAS and SATA RAID controllers that are already End-of-Life: .Pp .Bl -bullet -compact .It HighPoint RocketRAID 4211 .It HighPoint RocketRAID 4210 .It HighPoint RocketRAID 3560 .It HighPoint RocketRAID 3540 .It HighPoint RocketRAID 3530 .It HighPoint RocketRAID 3522 .It HighPoint RocketRAID 3521 .It HighPoint RocketRAID 3520 .It HighPoint RocketRAID 3511 .It HighPoint RocketRAID 3510 .It HighPoint RocketRAID 3410 .It HighPoint RocketRAID 3320 .It HighPoint RocketRAID 3220 .It HighPoint RocketRAID 3122 .It HighPoint RocketRAID 3120 .It HighPoint RocketRAID 3020 .El .Sh NOTES The .Nm driver has only been tested on the i386 and amd64 platforms. .Sh SEE ALSO .Xr cam 4 , .Xr hptmv 4 .Sh HISTORY The .Nm device driver first appeared in .Fx 7.0 . .Sh AUTHORS The .Nm -driver was written by HighPoint Technologies, Inc. +driver was written by +.An HighPoint Technologies, Inc. Index: head/share/man/man4/man4.i386/wl.4 =================================================================== --- head/share/man/man4/man4.i386/wl.4 (revision 286662) +++ head/share/man/man4/man4.i386/wl.4 (revision 286663) @@ -1,191 +1,193 @@ .\" .\" Copyright (c) 1997, Jim Binkley .\" 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. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by Jim Binkley .\" 4. 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 September 29, 2006 .Dt WL 4 i386 .Os .Sh NAME .Nm wl .Nd T1 speed ISA/radio lan card .Sh SYNOPSIS .Cd "device wl0 at isa? port 0x300 irq 5" .Sh DESCRIPTION The .Nm driver controls a radio lan card system made originally by NCR, then ATT, now Lucent. The system is spread-spectrum radio at around 915 MHz (or 2.4 GHz). With the supplied omni-directional antennae, about 400 feet (indoors, more outdoors) can be covered in circumference. This card can talk to the companion (wlp0) pccard. Speeds vary from 1 megabit to theoretically 2 megabits (roughly T1 in speed). .Pp The card has three fundamental hardware units, a so-called PSA or programmable storage area, a radio modem, and a Ethernet lan controller. The latter component is the ancient (and not very honorable) Intel 82586 Ethernet chip. Fundamentally it appears to the operating system as an Ethernet system, and speaks IEEE MAC addresses. The radio modem simply translates Ethernet packets to/from radio packets, that are either at 2.4 GHz or 915 MHz depending on the radio modem. It supports a collision avoidance scheme. The lan controller supports promiscuous mode, broadcast, and multicasting (although there is a glitch in the latter). "It thinks it is Ethernet". .Pp How it is used depends on the kind of antennae deployed with it. Point to point applications are possible as are Ethernet-like lan use. The vendor ships an omni-directional antennae that works in the vicinity of 400 feet (indoors). Point to point antennae can be purchased that will go miles. .Sh SETUP The card can either be initialized with the vendor supplied DOS setup software. Typically minimally an IRQ, port, and Network ID must be supplied. Michael Smith's .Xr wlconfig 8 utility can now be used to do this work from the UNIX side. The card is "not" plug and play. The network id controls whether one set of cards can hear another. If different, cards will read physical packets, but they will be discarded by the radio modem. .Sh CONTROL In addition to the config utility, there are several sysctl switches that can be used to modify runtime parameters. The .Xr sysctl 8 variables are as follows: .Bl -diag .It "machdep.wl_xmit_delay " This variable will cause the driver to insert a delay on transmit. 250 is the default. The delay should probably be a bit longer on faster cpus and less on slower cpus. It exists because the 82586 was not designed to work with Pentium-speed cpu systems and if overdriven will have copious xmit side errors. .It machdep.wl_ignore_nwid <0 | 1> This switch defaults to 0; i.e., the nwid is not ignored. It can be set to 1 to cause the nwid to not be used. This may be useful when the device is in promiscuous mode as one can watch for all packets and ignore nwid differences. .It machdep.wl_xmit_watch This switch is not currently useful. .It machdep.wl_gather_snr This switch is not currently useful. .Pp There is also a signal strength cache in the driver. It may be interrogated with .Xr wlconfig 8 . Incoming packets are checked for certain hardware radio-modem values including signal strength, silence, and quality, which range fro 0..63, 0..63, and 0..15 respectively. Thus one can read out signal strenth values to see how close/far peer nodes are. The signal strength cache is indexed by sender MAC address. There are two sysctls that change how it filters packets. Both are on by default. .It machdep.wl_wlcache_mcastonly <0 | 1> By default this switch is on. It forces the cache to filter out unicast packets. Only broadcast or multicast packets are accepted. .It machdep.wl_wlcache_iponly <0 | 1> By default this switch is on. It forces the driver to discard non-IP packets and also stores the IP src address. ARP packets are ignored, as are any other network protocol barring IPv4 packets. .El .Sh SEE ALSO .Xr sysctl 8 , .Xr wlconfig 8 .Pp .Pa http://www.wavelan.com .Sh HISTORY The .Nm driver was written by .An Anders Klemets (thousands of years ago?) and appears to be based on an even older Intel 82586 driver. The 82586 controller was one of the first (if not the first?) integrated lan controller on the block. That does not mean it was the best either. Anders ported and or created a driver for the ISA wavelan and PCCARD wavelan system too (wlp). .An Robert T. Morris, Jr. ported the Mach drivers to BSDI. .An Jim Binkley ported them to .Fx 2.1 . .An Michael Smith -ported the wl driver only to 2.2.2. +ported the +.Nm +driver only to 2.2.2. Jim and Michael have been maintaining them. The current state of the driver is NOT ANYONE'S FAULT. Thanks to .An Bernie Doehner and .An Robert Buaas for contributions. .Sh AUTHORS Too numerous to mention. See above. .Sh CAVEATS The 82586 has numerous defects. It may experience transmit-side errors when modern faster cpus send packets at it faster than it can handle. The driver (and probably the chip) does not support an all multicast mode. As a result, it can be used with applications like .Xr mrouted 8 Pq Pa ports/net/mrouted , but it must go into promiscuous mode for that to work. The driver is slow to change modes from "normal" to promiscuous mode, presumably due to delays in the configuration code. Index: head/share/man/man4/ng_btsocket.4 =================================================================== --- head/share/man/man4/ng_btsocket.4 (revision 286662) +++ head/share/man/man4/ng_btsocket.4 (revision 286663) @@ -1,354 +1,354 @@ .\" Copyright (c) 2001-2002 Maksim Yevmenkin .\" 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. .\" .\" $Id: ng_btsocket.4,v 1.7 2003/05/21 19:37:35 max Exp $ .\" $FreeBSD$ .\" .Dd November 13, 2012 .Dt NG_BTSOCKET 4 .Os .Sh NAME .Nm ng_btsocket .Nd Bluetooth sockets layer .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .In sys/bitstring.h .In netgraph/bluetooth/include/ng_hci.h .In netgraph/bluetooth/include/ng_l2cap.h .In netgraph/bluetooth/include/ng_btsocket.h .Sh DESCRIPTION The .Nm module implements three Netgraph node types. Each type in its turn implements one protocol within .Dv PF_BLUETOOTH domain. -.Sh Dv BLUETOOTH_PROTO_HCI Sh protocol -.Ss Dv SOCK_RAW Ss HCI sockets +.Sh Dv BLUETOOTH_PROTO_HCI protocol +.Ss Dv SOCK_RAW HCI sockets Implemented by .Nm btsock_hci_raw Netgraph type. Raw HCI sockets allow sending of raw HCI command datagrams only to correspondents named in .Xr send 2 calls. Raw HCI datagrams (HCI commands, events and data) are generally received with .Xr recvfrom 2 , which returns the next datagram with its return address. Raw HCI sockets can also be used to control HCI nodes. .Pp The Bluetooth raw HCI socket address is defined as follows: .Bd -literal -offset indent /* Bluetooth version of struct sockaddr for raw HCI sockets */ struct sockaddr_hci { u_char hci_len; /* total length */ u_char hci_family; /* address family */ char hci_node[32]; /* address (size == NG_NODESIZ ) */ }; .Ed .Pp Raw HCI sockets support a number of .Xr ioctl 2 requests such as: .Bl -tag -width foo .It Dv SIOC_HCI_RAW_NODE_GET_STATE Returns current state for the HCI node. .It Dv SIOC_HCI_RAW_NODE_INIT Turn on .Dq inited bit for the HCI node. .It Dv SIOC_HCI_RAW_NODE_GET_DEBUG Returns current debug level for the HCI node. .It Dv SIOC_HCI_RAW_NODE_SET_DEBUG Sets current debug level for the HCI node. .It Dv SIOC_HCI_RAW_NODE_GET_BUFFER Returns current state of data buffers for the HCI node. .It Dv SIOC_HCI_RAW_NODE_GET_BDADDR Returns BD_ADDR for the HCI node. .It Dv SIOC_HCI_RAW_NODE_GET_FEATURES Returns the list of features supported by hardware for the HCI node. .It Dv SIOC_HCI_RAW_NODE_GET_STAT Returns various statistic counters for the HCI node. .It Dv SIOC_HCI_RAW_NODE_RESET_STAT Resets all statistic counters for the HCI node to zero. .It Dv SIOC_HCI_RAW_NODE_FLUSH_NEIGHBOR_CACHE Remove all neighbor cache entries for the HCI node. .It Dv SIOC_HCI_RAW_NODE_GET_NEIGHBOR_CACHE Returns content of the neighbor cache for the HCI node. .It Dv SIOC_HCI_RAW_NODE_GET_CON_LIST Returns list of active baseband connections (i.e., ACL and SCO links) for the HCI node. .It SIOC_HCI_RAW_NODE_GET_LINK_POLICY_MASK Returns current link policy settings mask for the HCI node. .It SIOC_HCI_RAW_NODE_SET_LINK_POLICY_MASK Sets current link policy settings mask for the HCI node. .It SIOC_HCI_RAW_NODE_GET_PACKET_MASK Returns current packet mask for the HCI node. .It SIOC_HCI_RAW_NODE_SET_PACKET_MASK Sets current packet mask for the HCI node. .It SIOC_HCI_RAW_NODE_GET_ROLE_SWITCH Returns current value of the role switch parameter for the HCI node. .It SIOC_HCI_RAW_NODE_SET_ROLE_SWITCH Sets new value of the role switch parameter for the HCI node. .El .Pp The .Va net.bluetooth.hci.sockets.raw.ioctl_timeout variable, that can be examined and set via .Xr sysctl 8 , controls the control request timeout (in seconds) for raw HCI sockets. .Pp Raw HCI sockets support filters. The application can filter certain HCI datagram types. For HCI event datagrams the application can set additional filter. The raw HCI socket filter defined as follows: .Bd -literal -offset indent /* * Raw HCI socket filter. * * For packet mask use (1 << (HCI packet indicator - 1)) * For event mask use (1 << (Event - 1)) */ struct ng_btsocket_hci_raw_filter { bitstr_t bit_decl(packet_mask, 32); bitstr_t bit_decl(event_mask, (NG_HCI_EVENT_MASK_SIZE * 8)); }; .Ed .Pp The .Dv SO_HCI_RAW_FILTER option defined at .Dv SOL_HCI_RAW level can be used to obtain via .Xr getsockopt 2 or change via .Xr setsockopt 2 raw HCI socket's filter. -.Sh Dv BLUETOOTH_PROTO_L2CAP Sh protocol +.Sh Dv BLUETOOTH_PROTO_L2CAP protocol The Bluetooth L2CAP socket address is defined as follows: .Bd -literal -offset indent /* Bluetooth version of struct sockaddr for L2CAP sockets */ struct sockaddr_l2cap { u_char l2cap_len; /* total length */ u_char l2cap_family; /* address family */ uint16_t l2cap_psm; /* Protocol/Service Multiplexor */ bdaddr_t l2cap_bdaddr; /* address */ }; .Ed -.Ss Dv SOCK_RAW Ss L2CAP sockets +.Ss Dv SOCK_RAW L2CAP sockets Implemented by .Nm btsock_l2c_raw Netgraph type. Raw L2CAP sockets do not provide access to raw L2CAP datagrams. These sockets used to control L2CAP nodes and to issue special L2CAP requests such as .Dv ECHO_REQUEST and .Dv GET_INFO request. .Pp Raw L2CAP sockets support number of .Xr ioctl 2 requests such as: .Bl -tag -width foo .It Dv SIOC_L2CAP_NODE_GET_FLAGS Returns current state for the L2CAP node. .It Dv SIOC_L2CAP_NODE_GET_DEBUG Returns current debug level for the L2CAP node. .It Dv SIOC_L2CAP_NODE_SET_DEBUG Sets current debug level for the L2CAP node. .It Dv SIOC_L2CAP_NODE_GET_CON_LIST Returns list of active baseband connections (i.e., ACL links) for the L2CAP node. .It Dv SIOC_L2CAP_NODE_GET_CHAN_LIST Returns list of active channels for the L2CAP node. .It Dv SIOC_L2CAP_NODE_GET_AUTO_DISCON_TIMO Returns current value of the auto disconnect timeout for the L2CAP node. .It Dv SIOC_L2CAP_NODE_SET_AUTO_DISCON_TIMO Sets current value of the auto disconnect timeout for the L2CAP node. .It Dv SIOC_L2CAP_L2CA_PING Issues L2CAP .Dv ECHO_REQUEST . .It Dv SIOC_L2CAP_L2CA_GET_INFO Issues L2CAP .Dv GET_INFO request. .El .Pp The .Va net.bluetooth.l2cap.sockets.raw.ioctl_timeout variable, that can be examined and set via .Xr sysctl 8 , controls the control request timeout (in seconds) for raw L2CAP sockets. -.Ss Dv SOCK_SEQPACKET Ss L2CAP sockets +.Ss Dv SOCK_SEQPACKET L2CAP sockets Implemented by .Nm btsock_l2c Netgraph type. L2CAP sockets are either .Dq active or .Dq passive . Active sockets initiate connections to passive sockets. By default, L2CAP sockets are created active; to create a passive socket, the .Xr listen 2 system call must be used after binding the socket with the .Xr bind 2 system call. Only passive sockets may use the .Xr accept 2 call to accept incoming connections. Only active sockets may use the .Xr connect 2 call to initiate connections. .Pp L2CAP sockets support .Dq "wildcard addressing" . In this case, socket must be bound to .Dv NG_HCI_BDADDR_ANY address. Note that PSM (Protocol/Service Multiplexor) field is always required. Once a connection has been established, the socket's address is fixed by the peer entity's location. The address assigned to the socket is the address associated with the Bluetooth device through which packets are being transmitted and received, and PSM (Protocol/Service Multiplexor). .Pp L2CAP sockets support number of options defined at .Dv SOL_L2CAP level which can be set with .Xr setsockopt 2 and tested with .Xr getsockopt 2 : .Bl -tag -width foo .It Dv SO_L2CAP_IMTU Get (set) maximum payload size the local socket is capable of accepting. .It Dv SO_L2CAP_OMTU Get maximum payload size the remote socket is capable of accepting. .It Dv SO_L2CAP_IFLOW Get incoming flow specification for the socket. .Bf -emphasis Not implemented. .Ef .It Dv SO_L2CAP_OFLOW Get (set) outgoing flow specification for the socket. .Bf -emphasis Not implemented. .Ef .It Dv SO_L2CAP_FLUSH Get (set) value of the flush timeout. .Bf -emphasis Not implemented. .Ef .El -.Sh Dv BLUETOOTH_PROTO_RFCOMM Sh protocol +.Sh Dv BLUETOOTH_PROTO_RFCOMM protocol The Bluetooth RFCOMM socket address is defined as follows: .Bd -literal -offset indent /* Bluetooth version of struct sockaddr for RFCOMM sockets */ struct sockaddr_rfcomm { u_char rfcomm_len; /* total length */ u_char rfcomm_family; /* address family */ bdaddr_t rfcomm_bdaddr; /* address */ uint8_t rfcomm_channel; /* channel */ }; .Ed -.Ss Dv SOCK_STREAM Ss RFCOMM sockets +.Ss Dv SOCK_STREAM RFCOMM sockets Note that RFCOMM sockets do not have associated Netgraph node type. RFCOMM sockets are implemented as additional layer on top of L2CAP sockets. RFCOMM sockets are either .Dq active or .Dq passive . Active sockets initiate connections to passive sockets. By default, RFCOMM sockets are created active; to create a passive socket, the .Xr listen 2 system call must be used after binding the socket with the .Xr bind 2 system call. Only passive sockets may use the .Xr accept 2 call to accept incoming connections. Only active sockets may use the .Xr connect 2 call to initiate connections. .Pp RFCOMM sockets support .Dq "wildcard addressing" . In this case, socket must be bound to .Dv NG_HCI_BDADDR_ANY address. Note that RFCOMM channel field is always required. Once a connection has been established, the socket's address is fixed by the peer entity's location. The address assigned to the socket is the address associated with the Bluetooth device through which packets are being transmitted and received, and RFCOMM channel. .Pp The following options, which can be tested with .Xr getsockopt 2 call, are defined at .Dv SOL_RFCOMM level for RFCOMM sockets: .Bl -tag -width foo .It Dv SO_RFCOMM_MTU Returns the maximum transfer unit size (in bytes) for the underlying RFCOMM channel. Note that application still can write/read bigger chunks to/from the socket. .It Dv SO_RFCOMM_FC_INFO Return the flow control information for the underlying RFCOMM channel. .El .Pp The .Va net.bluetooth.rfcomm.sockets.stream.timeout variable, that can be examined and set via .Xr sysctl 8 , controls the connection timeout (in seconds) for RFCOMM sockets. .Sh HOOKS These node types support hooks with arbitrary names (as long as they are unique) and always accept hook connection requests. .Sh NETGRAPH CONTROL MESSAGES These node types support the generic control messages. .Sh SHUTDOWN These nodes are persistent and cannot be shut down. .Sh SEE ALSO .Xr btsockstat 1 , .Xr socket 2 , .Xr netgraph 4 , .Xr ng_bluetooth 4 , .Xr ng_hci 4 , .Xr ng_l2cap 4 , .Xr ngctl 8 , .Xr sysctl 8 .Sh HISTORY The .Nm module was implemented in .Fx 5.0 . .Sh AUTHORS .An Maksim Yevmenkin Aq Mt m_evmenkin@yahoo.com .Sh BUGS Most likely. Please report if found. Index: head/share/man/man4/siftr.4 =================================================================== --- head/share/man/man4/siftr.4 (revision 286662) +++ head/share/man/man4/siftr.4 (revision 286663) @@ -1,777 +1,777 @@ .\" .\" Copyright (c) 2010 The FreeBSD Foundation .\" All rights reserved. .\" .\" Portions of this software were developed at the Centre for Advanced .\" Internet Architectures, Swinburne University of Technology, Melbourne, .\" Australia by Lawrence Stewart under sponsorship from the FreeBSD .\" Foundation. .\" .\" 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, immediately at the beginning of the file. .\" 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 March 18, 2015 .Dt SIFTR 4 .Os .Sh NAME .Nm SIFTR .Nd Statistical Information For TCP Research .Sh SYNOPSIS To load the driver as a module at run-time, run the following command as root: .Bd -literal -offset indent kldload siftr .Ed .Pp Alternatively, to load the driver as a module at boot time, add the following line into the .Xr loader.conf 5 file: .Bd -literal -offset indent siftr_load="YES" .Ed .Sh DESCRIPTION The .Nm .Po .Em S Ns tatistical .Em I Ns nformation .Em F Ns or .Em T Ns CP .Em R Ns esearch .Pc kernel module logs a range of statistics on active TCP connections to a log file. It provides the ability to make highly granular measurements of TCP connection state, aimed at system administrators, developers and researchers. .Ss Compile-time Configuration The default operation of .Nm is to capture IPv4 TCP/IP packets. .Nm can be configured to support IPv4 and IPv6 by uncommenting: .Bd -literal -offset indent CFLAGS+=-DSIFTR_IPV6 .Ed .Pp in .Aq sys/modules/siftr/Makefile and recompiling. .Pp In the IPv4-only (default) mode, standard dotted decimal notation (e.g. "136.186.229.95") is used to format IPv4 addresses for logging. In IPv6 mode, standard dotted decimal notation is used to format IPv4 addresses, and standard colon-separated hex notation (see RFC 4291) is used to format IPv6 addresses for logging. Note that SIFTR uses uncompressed notation to format IPv6 addresses. For example, the address "fe80::20f:feff:fea2:531b" would be logged as "fe80:0:0:0:20f:feff:fea2:531b". .Ss Run-time Configuration .Nm utilises the .Xr sysctl 8 interface to export its configuration variables to user-space. The following variables are available: .Bl -tag -offset indent -width Va .It Va net.inet.siftr.enabled controls whether the module performs its measurements or not. By default, the value is set to 0, which means the module will not be taking any measurements. Having the module loaded with .Va net.inet.siftr.enabled set to 0 will have no impact on the performance of the network stack, as the packet filtering hooks are only inserted when .Va net.inet.siftr.enabled is set to 1. .El .Bl -tag -offset indent -width Va .It Va net.inet.siftr.ppl controls how many inbound/outbound packets for a given TCP connection will cause a log message to be generated for the connection. By default, the value is set to 1, which means the module will log a message for every packet of every TCP connection. The value can be set to any integer in the range [1,2^32], and can be changed at any time, even while the module is enabled. .El .Bl -tag -offset indent -width Va .It Va net.inet.siftr.logfile controls the path to the file that the module writes its log messages to. By default, the file /var/log/siftr.log is used. The path can be changed at any time, even while the module is enabled. .El .Bl -tag -offset indent -width Va .It Va net.inet.siftr.genhashes controls whether a hash is generated for each TCP packet seen by .Nm . By default, the value is set to 0, which means no hashes are generated. The hashes are useful to correlate which TCP packet triggered the generation of a particular log message, but calculating them adds additional computational overhead into the fast path. .El .Ss Log Format A typical .Nm log file will contain 3 different types of log message. All messages are written in plain ASCII text. .Pp Note: The .Qq \e present in the example log messages in this section indicates a line continuation and is not part of the actual log message. .Pp The first type of log message is written to the file when the module is enabled and starts collecting data from the running kernel. The text below shows an example module enable log. The fields are tab delimited key-value pairs which describe some basic information about the system. .Bd -literal -offset indent enable_time_secs=1238556193 enable_time_usecs=462104 \\ siftrver=1.2.2 hz=1000 tcp_rtt_scale=32 \\ sysname=FreeBSD sysver=604000 ipmode=4 .Ed .Pp Field descriptions are as follows: .Bl -tag -offset indent -width Va .It Va enable_time_secs time at which the module was enabled, in seconds since the UNIX epoch. .El .Bl -tag -offset indent -width Va .It Va enable_time_usecs time at which the module was enabled, in microseconds since enable_time_secs. .El .Bl -tag -offset indent -width Va .It Va siftrver version of .Nm . .El .Bl -tag -offset indent -width Va .It Va hz tick rate of the kernel in ticks per second. .El .Bl -tag -offset indent -width Va .It Va tcp_rtt_scale smoothed RTT estimate scaling factor. .El .Bl -tag -offset indent -width Va .It Va sysname operating system name. .El .Bl -tag -offset indent -width Va .It Va sysver operating system version. .El .Bl -tag -offset indent -width Va .It Va ipmode IP mode as defined at compile time. An ipmode of "4" means IPv6 is not supported and IP addresses are logged in regular dotted quad format. An ipmode of "6" means IPv6 is supported, and IP addresses are logged in dotted quad or hex format, as described in the .Qq Compile-time Configuration subsection. .El .Pp The second type of log message is written to the file when a data log message is generated. The text below shows an example data log triggered by an IPv4 TCP/IP packet. The data is CSV formatted. .Bd -literal -offset indent o,0xbec491a5,1238556193.463551,172.16.7.28,22,172.16.2.5,55931, \\ 1073725440,172312,6144,66560,66608,8,1,4,1448,936,1,996,255, \\ 33304,208,66608,0,208,0 .Ed .Pp Field descriptions are as follows: .Bl -tag -offset indent -width Va .It Va 1 Direction of packet that triggered the log message. Either .Qq i for in, or .Qq o for out. .El .Bl -tag -offset indent -width Va .It Va 2 Hash of the packet that triggered the log message. .El .Bl -tag -offset indent -width Va .It Va 3 Time at which the packet that triggered the log message was processed by the .Xr pfil 9 hook function, in seconds and microseconds since the UNIX epoch. .El .Bl -tag -offset indent -width Va .It Va 4 The IPv4 or IPv6 address of the local host, in dotted quad (IPv4 packet) or colon-separated hex (IPv6 packet) notation. .El .Bl -tag -offset indent -width Va .It Va 5 The TCP port that the local host is communicating via. .El .Bl -tag -offset indent -width Va .It Va 6 The IPv4 or IPv6 address of the foreign host, in dotted quad (IPv4 packet) or colon-separated hex (IPv6 packet) notation. .El .Bl -tag -offset indent -width Va .It Va 7 The TCP port that the foreign host is communicating via. .El .Bl -tag -offset indent -width Va .It Va 8 The slow start threshold for the flow, in bytes. .El .Bl -tag -offset indent -width Va .It Va 9 The current congestion window for the flow, in bytes. .El .Bl -tag -offset indent -width Va .It Va 10 The current bandwidth-controlled window for the flow, in bytes. .El .Bl -tag -offset indent -width Va .It Va 11 The current sending window for the flow, in bytes. The post scaled value is reported, except during the initial handshake (first few packets), during which time the unscaled value is reported. .El .Bl -tag -offset indent -width Va .It Va 12 The current receive window for the flow, in bytes. The post scaled value is always reported. .El .Bl -tag -offset indent -width Va .It Va 13 The current window scaling factor for the sending window. .El .Bl -tag -offset indent -width Va .It Va 14 The current window scaling factor for the receiving window. .El .Bl -tag -offset indent -width Va .It Va 15 The current state of the TCP finite state machine, as defined in .Aq Pa netinet/tcp_fsm.h . .El .Bl -tag -offset indent -width Va .It Va 16 The maximum segment size for the flow, in bytes. .El .Bl -tag -offset indent -width Va .It Va 17 The current smoothed RTT estimate for the flow, in units of TCP_RTT_SCALE * HZ, where TCP_RTT_SCALE is a define found in tcp_var.h, and HZ is the kernel's tick timer. Divide by TCP_RTT_SCALE * HZ to get the RTT in secs. TCP_RTT_SCALE and HZ are reported in the enable log message. .El .Bl -tag -offset indent -width Va .It Va 18 SACK enabled indicator. 1 if SACK enabled, 0 otherwise. .El .Bl -tag -offset indent -width Va .It Va 19 The current state of the TCP flags for the flow. See .Aq Pa netinet/tcp_var.h for information about the various flags. .El .Bl -tag -offset indent -width Va .It Va 20 The current retransmission timeout length for the flow, in units of HZ, where HZ is the kernel's tick timer. Divide by HZ to get the timeout length in seconds. HZ is reported in the enable log message. .El .Bl -tag -offset indent -width Va .It Va 21 The current size of the socket send buffer in bytes. .El .Bl -tag -offset indent -width Va .It Va 22 The current number of bytes in the socket send buffer. .El .Bl -tag -offset indent -width Va .It Va 23 The current size of the socket receive buffer in bytes. .El .Bl -tag -offset indent -width Va .It Va 24 The current number of bytes in the socket receive buffer. .El .Bl -tag -offset indent -width Va .It Va 25 The current number of unacknowledged bytes in-flight. Bytes acknowledged via SACK are not excluded from this count. .El .Bl -tag -offset indent -width Va .It Va 26 The current number of segments in the reassembly queue. .El .Bl -tag -offset indent -width Va .It Va 27 Flowid for the connection. A caveat: Zero '0' either represents a valid flowid or a default value when it's not being set. There is no easy way to differentiate without looking at actual network interface card and drivers being used. .El .Bl -tag -offset indent -width Va .It Va 28 Flow type for the connection. -Flowtype defines which protocol fields are hashed to produce the flowid. +Flowtype defines which protocol fields are hashed to produce the flowid. A complete listing is available in .Pa sys/mbuf.h under .Dv M_HASHTYPE_* . .El .Pp The third type of log message is written to the file when the module is disabled and ceases collecting data from the running kernel. The text below shows an example module disable log. The fields are tab delimited key-value pairs which provide statistics about operations since the module was most recently enabled. .Bd -literal -offset indent disable_time_secs=1238556197 disable_time_usecs=933607 \\ num_inbound_tcp_pkts=356 num_outbound_tcp_pkts=627 \\ total_tcp_pkts=983 num_inbound_skipped_pkts_malloc=0 \\ num_outbound_skipped_pkts_malloc=0 num_inbound_skipped_pkts_mtx=0 \\ num_outbound_skipped_pkts_mtx=0 num_inbound_skipped_pkts_tcb=0 \\ num_outbound_skipped_pkts_tcb=0 num_inbound_skipped_pkts_icb=0 \\ num_outbound_skipped_pkts_icb=0 total_skipped_tcp_pkts=0 \\ flow_list=172.16.7.28;22-172.16.2.5;55931, .Ed .Pp Field descriptions are as follows: .Bl -tag -offset indent -width Va .It Va disable_time_secs Time at which the module was disabled, in seconds since the UNIX epoch. .El .Bl -tag -offset indent -width Va .It Va disable_time_usecs Time at which the module was disabled, in microseconds since disable_time_secs. .El .Bl -tag -offset indent -width Va .It Va num_inbound_tcp_pkts Number of TCP packets that traversed up the network stack. This only includes inbound TCP packets during the periods when .Nm was enabled. .El .Bl -tag -offset indent -width Va .It Va num_outbound_tcp_pkts Number of TCP packets that traversed down the network stack. This only includes outbound TCP packets during the periods when .Nm was enabled. .El .Bl -tag -offset indent -width Va .It Va total_tcp_pkts The summation of num_inbound_tcp_pkts and num_outbound_tcp_pkts. .El .Bl -tag -offset indent -width Va .It Va num_inbound_skipped_pkts_malloc Number of inbound packets that were not processed because of failed malloc() calls. .El .Bl -tag -offset indent -width Va .It Va num_outbound_skipped_pkts_malloc Number of outbound packets that were not processed because of failed malloc() calls. .El .Bl -tag -offset indent -width Va .It Va num_inbound_skipped_pkts_mtx Number of inbound packets that were not processed because of failure to add the packet to the packet processing queue. .El .Bl -tag -offset indent -width Va .It Va num_outbound_skipped_pkts_mtx Number of outbound packets that were not processed because of failure to add the packet to the packet processing queue. .El .Bl -tag -offset indent -width Va .It Va num_inbound_skipped_pkts_tcb Number of inbound packets that were not processed because of failure to find the TCP control block associated with the packet. .El .Bl -tag -offset indent -width Va .It Va num_outbound_skipped_pkts_tcb Number of outbound packets that were not processed because of failure to find the TCP control block associated with the packet. .El .Bl -tag -offset indent -width Va .It Va num_inbound_skipped_pkts_icb Number of inbound packets that were not processed because of failure to find the IP control block associated with the packet. .El .Bl -tag -offset indent -width Va .It Va num_outbound_skipped_pkts_icb Number of outbound packets that were not processed because of failure to find the IP control block associated with the packet. .El .Bl -tag -offset indent -width Va .It Va total_skipped_tcp_pkts The summation of all skipped packet counters. .El .Bl -tag -offset indent -width Va .It Va flow_list A CSV list of TCP flows that triggered data log messages to be generated since the module was loaded. Each flow entry in the CSV list is formatted as .Qq local_ip;local_port-foreign_ip;foreign_port . If there are no entries in the list (i.e., no data log messages were generated), the value will be blank. If there is at least one entry in the list, a trailing comma will always be present. .El .Pp The total number of data log messages found in the log file for a module enable/disable cycle should equate to total_tcp_pkts - total_skipped_tcp_pkts. .Sh IMPLEMENTATION NOTES .Nm hooks into the network stack using the .Xr pfil 9 interface. In its current incarnation, it hooks into the AF_INET/AF_INET6 (IPv4/IPv6) .Xr pfil 9 filtering points, which means it sees packets at the IP layer of the network stack. This means that TCP packets inbound to the stack are intercepted before they have been processed by the TCP layer. Packets outbound from the stack are intercepted after they have been processed by the TCP layer. .Pp The diagram below illustrates how .Nm inserts itself into the stack. .Bd -literal -offset indent ---------------------------------- Upper Layers ---------------------------------- ^ | | | | | | v TCP in TCP out ---------------------------------- ^ | |________ _________| | | | v --------- | SIFTR | --------- ^ | ________| |__________ | | | v IPv{4/6} in IPv{4/6} out ---------------------------------- ^ | | | | v Layer 2 in Layer 2 out ---------------------------------- Physical Layer ---------------------------------- .Ed .Pp .Nm uses the .Xr alq 9 interface to manage writing data to disk. .Pp At first glance, you might mistakenly think that .Nm extracts information from individual TCP packets. This is not the case. .Nm uses TCP packet events (inbound and outbound) for each TCP flow originating from the system to trigger a dump of the state of the TCP control block for that flow. With the PPL set to 1, we are in effect sampling each TCP flow's control block state as frequently as flow packets enter/leave the system. For example, setting PPL to 2 halves the sampling rate i.e., every second flow packet (inbound OR outbound) causes a dump of the control block state. .Pp The distinction between interrogating individual packets versus interrogating the control block is important, because .Nm does not remove the need for packet capturing tools like .Xr tcpdump 1 . .Nm allows you to correlate and observe the cause-and-affect relationship between what you see on the wire (captured using a tool like .Xr tcpdump 1 Ns ) and changes in the TCP control block corresponding to the flow of interest. It is therefore useful to use .Nm and a tool like .Xr tcpdump 1 to gather the necessary data to piece together the complete picture. Use of either tool on its own will not be able to provide all of the necessary data. .Pp As a result of needing to interrogate the TCP control block, certain packets during the lifecycle of a connection are unable to trigger a .Nm log message. The initial handshake takes place without the existence of a control block and the final ACK is exchanged when the connection is in the TIMEWAIT state. .Pp .Nm was designed to minimise the delay introduced to packets traversing the network stack. This design called for a highly optimised and minimal hook function that extracted the minimal details necessary whilst holding the packet up, and passing these details to another thread for actual processing and logging. .Pp This multithreaded design does introduce some contention issues when accessing the data structure shared between the threads of operation. When the hook function tries to place details in the structure, it must first acquire an exclusive lock. Likewise, when the processing thread tries to read details from the structure, it must also acquire an exclusive lock to do so. If one thread holds the lock, the other must wait before it can obtain it. This does introduce some additional bounded delay into the kernel's packet processing code path. .Pp In some cases (e.g., low memory, connection termination), TCP packets that enter the .Nm .Xr pfil 9 hook function will not trigger a log message to be generated. .Nm refers to this outcome as a .Qq skipped packet . Note that .Nm always ensures that packets are allowed to continue through the stack, even if they could not successfully trigger a data log message. .Nm will therefore not introduce any packet loss for TCP/IP packets traversing the network stack. .Ss Important Behaviours The behaviour of a log file path change whilst the module is enabled is as follows: .Bl -enum .It Attempt to open the new file path for writing. If this fails, the path change will fail and the existing path will continue to be used. .It Assuming the new path is valid and opened successfully: .Bl -dash .It Flush all pending log messages to the old file path. .It Close the old file path. .It Switch the active log file pointer to point at the new file path. .It Commence logging to the new file. .El .El .Pp During the time between the flush of pending log messages to the old file and commencing logging to the new file, new log messages will still be generated and buffered. As soon as the new file path is ready for writing, the accumulated log messages will be written out to the file. .Sh EXAMPLES To enable the module's operations, run the following command as root: sysctl net.inet.siftr.enabled=1 .Pp To change the granularity of log messages such that 1 log message is generated for every 10 TCP packets per connection, run the following command as root: sysctl net.inet.siftr.ppl=10 .Pp To change the log file location to /tmp/siftr.log, run the following command as root: sysctl net.inet.siftr.logfile=/tmp/siftr.log .Sh SEE ALSO .Xr tcpdump 1 , .Xr tcp 4 , .Xr sysctl 8 , .Xr alq 9 , .Xr pfil 9 .Sh ACKNOWLEDGEMENTS Development of this software was made possible in part by grants from the Cisco University Research Program Fund at Community Foundation Silicon Valley, and the FreeBSD Foundation. .Sh HISTORY .Nm first appeared in .Fx 7.4 and .Fx 8.2 . .Pp .Nm was first released in 2007 by Lawrence Stewart and James Healy whilst working on the NewTCP research project at Swinburne University of Technology's Centre for Advanced Internet Architectures, Melbourne, Australia, which was made possible in part by a grant from the Cisco University Research Program Fund at Community Foundation Silicon Valley. More details are available at: .Pp http://caia.swin.edu.au/urp/newtcp/ .Pp Work on .Nm v1.2.x was sponsored by the FreeBSD Foundation as part of the .Qq Enhancing the FreeBSD TCP Implementation project 2008-2009. More details are available at: .Pp http://www.freebsdfoundation.org/ .Pp http://caia.swin.edu.au/freebsd/etcp09/ .Sh AUTHORS .An -nosplit .Nm was written by .An Lawrence Stewart Aq Mt lstewart@FreeBSD.org and .An James Healy Aq Mt jimmy@deefa.com . .Pp This manual page was written by .An Lawrence Stewart Aq Mt lstewart@FreeBSD.org . .Sh BUGS Current known limitations and any relevant workarounds are outlined below: .Bl -dash .It The internal queue used to pass information between the threads of operation is currently unbounded. This allows .Nm to cope with bursty network traffic, but sustained high packet-per-second traffic can cause exhaustion of kernel memory if the processing thread cannot keep up with the packet rate. .It If using .Nm on a machine that is also running other modules utilising the .Xr pfil 9 framework e.g. .Xr dummynet 4 , .Xr ipfw 8 , .Xr pf 4 Ns , the order in which you load the modules is important. You should kldload the other modules first, as this will ensure TCP packets undergo any necessary manipulations before .Nm .Qq sees and processes them. .It There is a known, harmless lock order reversal warning between the .Xr pfil 9 mutex and tcbinfo TCP lock reported by .Xr witness 4 when .Nm is enabled in a kernel compiled with .Xr witness 4 support. .It There is no way to filter which TCP flows you wish to capture data for. Post processing is required to separate out data belonging to particular flows of interest. .It The module does not detect deletion of the log file path. New log messages will simply be lost if the log file being used by .Nm is deleted whilst the module is set to use the file. Switching to a new log file using the .Em net.inet.siftr.logfile variable will create the new file and allow log messages to begin being written to disk again. The new log file path must differ from the path to the deleted file. .It The hash table used within the code is sized to hold 65536 flows. This is not a hard limit, because chaining is used to handle collisions within the hash table structure. However, we suspect (based on analogies with other hash table performance data) that the hash table look up performance (and therefore the module's packet processing performance) will degrade in an exponential manner as the number of unique flows handled in a module enable/disable cycle approaches and surpasses 65536. .It There is no garbage collection performed on the flow hash table. The only way currently to flush it is to disable .Nm . .It The PPL variable applies to packets that make it into the processing thread, not total packets received in the hook function. Packets are skipped before the PPL variable is applied, which means there may be a slight discrepancy in the triggering of log messages. For example, if PPL was set to 10, and the 8th packet since the last log message is skipped, the 11th packet will actually trigger the log message to be generated. This is discussed in greater depth in CAIA technical report 070824A. .It At the time of writing, there was no simple way to hook into the TCP layer to intercept packets. .Nm Ap s use of IP layer hook points means all IP traffic will be processed by the .Nm .Xr pfil 9 hook function, which introduces minor, but nonetheless unnecessary packet delay and processing overhead on the system for non-TCP packets as well. Hooking in at the IP layer is also not ideal from the data gathering point of view. Packets traversing up the stack will be intercepted and cause a log message generation BEFORE they have been processed by the TCP layer, which means we cannot observe the cause-and-affect relationship between inbound events and the corresponding TCP control block as precisely as could be. Ideally, .Nm should intercept packets after they have been processed by the TCP layer i.e. intercept packets coming up the stack after they have been processed by tcp_input(), and intercept packets coming down the stack after they have been processed by tcp_output(). The current code still gives satisfactory granularity though, as inbound events tend to trigger outbound events, allowing the cause-and-effect to be observed indirectly by capturing the state on outbound events as well. .It The .Qq inflight bytes value logged by .Nm does not take into account bytes that have been .No SACK Ap ed by the receiving host. .It Packet hash generation does not currently work for IPv6 based TCP packets. .It Compressed notation is not used for IPv6 address representation. This consumes more bytes than is necessary in log output. .El Index: head/share/man/man4/snp.4 =================================================================== --- head/share/man/man4/snp.4 (revision 286662) +++ head/share/man/man4/snp.4 (revision 286663) @@ -1,100 +1,100 @@ .\" .\" $FreeBSD$ .\" .Dd November 5, 2008 .Dt SNP 4 .Os .Sh NAME .Nm snp .Nd tty snoop interface .Sh SYNOPSIS .In sys/snoop.h .Ft int .Fn ioctl fd SNPSTTY &dev .Ft int .Fn ioctl fd SNPGTTY &dev .Ft int .Fn ioctl fd FIONREAD &result .Sh DESCRIPTION .Pa /dev/snp is a snoop device which allows users to attach to any tty and watch activities on it. The kernel must be compiled with .Cd "device snp" , or the .Nm module must be loaded, for these devices to be available. .Pp To associate a given .Nm device with a tty to be observed, open the .Nm device and a tty device, and then issue the .Dv SNPSTTY ioctl on .Nm device. The argument passed to the .Xr ioctl 2 is the address of a variable of type .Vt int , holding the file descriptor of a tty device. To detach the .Nm device from a tty use a pointer to a value of \-1. .Pp The .Dv SNPGTTY ioctl returns information about the current tty attached to the open .Nm device. .Pp The .Dv FIONREAD ioctl returns a positive value equal to the number of characters in a read buffer. Special values defined are: .Bl -tag -width ".Dv SNP_TTYCLOSE" .It Dv SNP_OFLOW device overflow occurred, device detached. .It Dv SNP_TTYCLOSE tty not attached. .It Dv SNP_DETACH .Nm device has been detached by user or tty device has been closed and detached. .El .Sh SEE ALSO .Xr pty 4 , .Xr sio 4 , .Xr kldload 8 , .Xr watch 8 .Sh HISTORY The .Nm device first appeared in .Fx 2.1 . In .Fx 8.0 the .Nm driver was rewritten to work with the replaced TTY subsystem. .Sh AUTHORS .An -nosplit The author of the current implementation is -.An Ed Schouten Aq Mt ed@FreeBSD.org . +.An \&Ed Schouten Aq Mt ed@FreeBSD.org . Previous versions of .Nm were based on code written by .An Ugen J.S. Antsilevich Aq Mt ugen@NetVision.net.il . .Sh BUGS This version of .Nm does not return proper error codes when calling .Dv FIONREAD . It also does not allow .Dv SNPSTTY to detach itself from the TTY. Index: head/share/man/man4/uftdi.4 =================================================================== --- head/share/man/man4/uftdi.4 (revision 286662) +++ head/share/man/man4/uftdi.4 (revision 286663) @@ -1,256 +1,256 @@ .\" $NetBSD: uftdi.4,v 1.5 2002/02/07 03:15:08 ross Exp $ .\" .\" Copyright (c) 2000 The NetBSD Foundation, Inc. .\" All rights reserved. .\" .\" This code is derived from software contributed to The NetBSD Foundation .\" by Lennart Augustsson. .\" .\" 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. .\" .\" $FreeBSD$ .\" .Dd August 6, 2015 .Dt UFTDI 4 .Os .Sh NAME .Nm uftdi .Nd USB support for serial adapters based on the FTDI family of USB serial adapter chips. .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 ucom" .Cd "device uftdi" .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 uftdi_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for various serial adapters based on the following FTDI chips: .Pp .Bl -bullet -compact .It FT8U100AX .It FT8U232AM .It FT8U232BM .It FT232R .It FT2232C .It FT2232D .It FT2232H .It FT4232H .It FT230X .El .Pp The device is accessed through the .Xr ucom 4 driver which makes it behave like a .Xr tty 4 . .Pp Many of the supported chips provide additional functionality such as bitbang mode and the MPSSE engine for serial bus emulation. The .Nm driver provides access to that functionality with the following .Xr ioctl 2 calls, defined in .In dev/usb/uftdiio.h : .Bl -tag -width indent .It Dv UFTDIIOC_RESET_IO Pq Vt int Reset the channel to its default configuration, flush RX and TX FIFOs. .It Dv UFTDIIOC_RESET_RX Pq Vt int Flush the RX FIFO. .It Dv UFTDIIOC_RESET_TX Pq Vt int Flush the TX FIFO. .It Dv UFTDIIOC_SET_BITMODE Pq Vt "struct uftdi_bitmode" Put the channel into the operating mode specified in .Va mode , and set the pins indicated by ones in .Va iomask to output mode. The .Va mode must be one of the .Va uftdi_bitmodes values. Setting .Va mode to .Dv UFTDI_BITMODE_NONE returns the channel to standard UART mode. .Bd -literal enum uftdi_bitmodes { UFTDI_BITMODE_ASYNC = 0, UFTDI_BITMODE_MPSSE = 1, UFTDI_BITMODE_SYNC = 2, UFTDI_BITMODE_CPU_EMUL = 3, UFTDI_BITMODE_FAST_SERIAL = 4, UFTDI_BITMODE_CBUS = 5, UFTDI_BITMODE_NONE = 0xff, }; struct uftdi_bitmode { uint8_t mode; uint8_t iomask; }; .Ed .Pp Manuals and application notes published by FTDI describe these modes in detail. To use most of these modes, you first put the channel into the desired mode, then you .Xr read 2 and .Xr write 2 data which either reflects pin state or is interpreted as MPSSE commands and parameters, depending on the mode. .It Dv UFTDIIOC_GET_BITMODE Pq Vt "struct uftdi_bitmode" Return the current bitbang mode in the .Va mode member, and the state of the DBUS0..DBUS7 pins at the time of the call in the .Va iomask member. The pin state can be read while the chip is in any mode, including .Dv UFTDI_BITMODE_NONE (UART) mode. .It Dv UFTDIIOC_SET_ERROR_CHAR Pq Vt int Set the character which is inserted into the buffer to mark the point of an error such as FIFO overflow. .It Dv UFTDIIOC_SET_EVENT_CHAR Pq Vt int Set the character which causes a partial FIFO full of data to be returned immediately even if the FIFO is not full. .It Dv UFTDIIOC_SET_LATENCY Pq Vt int Set the amount of time to wait for a full FIFO, in milliseconds. If more than this much time elapses without receiving a new character, any characters in the FIFO are returned. .It Dv UFTDIIOC_GET_LATENCY Pq Vt int Get the current value of the latency timer. .It Dv UFTDIIOC_GET_HWREV Pq Vt int Get the hardware revision number. This is the .Va bcdDevice value from the .Va usb_device_descriptor . .It Dv UFTDIIOC_READ_EEPROM Pq Vt "struct uftdi_eeio" Read one or more words from the configuration eeprom. The FTDI chip performs eeprom I/O in 16-bit words. Set .Va offset and .Va length to values evenly divisible by two before the call, and the .Va data array will contain the requested values from eeprom after the call. .Bd -literal struct uftdi_eeio { uint16_t offset; uint16_t length; uint16_t data[64]; }; .Ed .Pp The FT232R chip has an internal eeprom. An external serial eeprom is optional on other FTDI chips. -The eeprom may contain 64, 128, or 256 words, +The eeprom may contain 64, 128, or 256 words, depending on the part used. Multiple calls may be needed to read or write the larger parts. When no eeprom is present, all words in the returned data are 0xffff. An erased eeprom also reads as all 0xffff. .It Dv UFTDIIOC_WRITE_EEPROM Pq Vt "struct uftdi_eeio" Write one or more words to the configuration eeprom. The .Va uftdi_eeio values are as described for .Dv UFTDIIOC_READ_EEPROM . .Pp The FTDI chip does a blind write to the eeprom, and it will appear to succeed even when no eeprom is present. To ensure a good write you must read back and verify the data. It is .Em not necessary to erase before writing. Any position within the eeprom can be overwritten at any time. .It Dv UFTDIIOC_ERASE_EEPROM Pq Vt int Erase the entire eeprom. This is useful primarily for test and debugging, as there is no need to erase before writing. To help prevent accidental erasure caused by calling the wrong ioctl, you must pass the special value .Dv UFTDI_CONFIRM_ERASE as the argument to this ioctl. .El .Sh HARDWARE The .Nm driver supports the following adapters: .Pp .Bl -bullet -compact .It B&B Electronics USB->RS422/485 adapter .It Elexol USB MOD1 and USB MOD3 .It HP USB-Serial adapter shipped with some HP laptops .It Inland UAS111 .It QVS USC-1000 .It Buffalo PC-OP-RS / Kurouto-shikou KURO-RS universal remote .It Prologix GPIB-USB Controller .El .Sh SEE ALSO .Xr tty 4 , .Xr ucom 4 , .Xr usb 4 .Sh HISTORY The .Nm driver appeared in .Fx 4.8 from .Nx 1.5 . Index: head/share/man/man4/vt.4 =================================================================== --- head/share/man/man4/vt.4 (revision 286662) +++ head/share/man/man4/vt.4 (revision 286663) @@ -1,345 +1,345 @@ .\" Copyright (c) 2014 Warren Block .\" 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 AUTHORS 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 AUTHORS 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 20, 2014 .Dt "VIRTUAL TERMINALS" 4 .Os .Sh NAME .Nm vt .Nd virtual terminal console driver .Sh SYNOPSIS .Cd "options TERMINAL_KERN_ATTR=_attribute_" .Cd "options TERMINAL_NORM_ATTR=_attribute_" .Cd "options VT_MAXWINDOWS=N" .Cd "options VT_ALT_TO_ESC_HACK=1" .Cd "options VT_TWOBUTTON_MOUSE" .Cd "options VT_FB_DEFAULT_WIDTH=X" .Cd "options VT_FB_DEFAULT_HEIGHT=Y" .Cd "options SC_NO_CUTPASTE" .Cd "device vt" .Pp In .Xr loader.conf 5 : .Cd hw.vga.textmode=1 .Cd kern.vty=vt .Cd kern.vt.fb.default_mode="x" .Cd kern.vt.fb.modes.="x" .Pp In .Xr loader.conf 5 or .Xr sysctl.conf 5 : .Cd kern.vt.kbd_halt=1 .Cd kern.vt.kbd_poweroff=1 .Cd kern.vt.kbd_reboot=1 .Cd kern.vt.kbd_debug=1 .Cd kern.vt.kbd_panic=0 .Sh DESCRIPTION The .Nm device provides multiple virtual terminals with an extensive feature set: .Bl -item -offset indent .It Unicode UTF-8 text with double-width characters. .It Large font maps in graphics mode, including support for Asian character sets. .It Graphics-mode consoles. .It Integration with KMS .Pq Kernel Mode Setting video drivers for switching between the .Em X Window System and virtual terminals. .El .Ss Virtual Terminals Multiple virtual terminals are provided on a single computer. Up to sixteen virtual terminals can be defined. A single virtual terminal is connected to the screen and keyboard at a time. Key combinations are used to select a virtual terminal. Alt-F1 through Alt-F12 correspond to the first twelve virtual terminals. If more than twelve virtual terminals are created, Shift-Alt-F1 through Shift-Alt-F4 are used to switch to the additional terminals. .Ss Copying and Pasting Text with a Mouse Copying and pasting text from the screen with a mouse is supported. Press and hold down mouse button 1, usually the left button, while moving the mouse to select text. Selected text is highlighted with reversed foreground and background colors. To select more text after releasing mouse button 1, press mouse button 3, usually the right button. To paste text that has been selected, press mouse button 2, usually the middle button. The text is entered as if it were typed at the keyboard. The .Dv VT_TWOBUTTON_MOUSE kernel option can be used with mice that only have two buttons. Setting this option makes the second mouse button into the paste button. See .Xr moused 8 for more information. .Ss Scrolling Back Output that has scrolled off the screen can be reviewed by pressing the Scroll Lock key, then scrolling up and down with the arrow keys. The Page Up and Page Down keys scroll up or down a full screen at a time. The Home and End keys jump to the beginning or end of the scrollback buffer. When finished reviewing, press the Scroll Lock key again to return to normal use. .Sh DRIVER CONFIGURATION .Ss Kernel Configuration Options These kernel options control the .Nm driver. .Bl -tag -width MAXCONS .It Dv TERMINAL_NORM_ATTR= Ns Pa attribute .It Dv TERMINAL_KERN_ATTR= Ns Pa attribute These options allow changing the default colors used for normal and kernel text. Available colors are defined in .In sys/terminal.h . See .Sx EXAMPLES below. .It Dv VT_MAXWINDOWS=N Set the number of virtual terminals to be created to .Fa N . The value defaults to 12. .It Dv VT_ALT_TO_ESC_HACK=1 When the Alt key is held down while pressing another key, send an ESC sequence instead of the Alt key. .It Dv VT_TWOBUTTON_MOUSE If defined, swap the functions of mouse buttons 2 and 3. In effect, this makes the right-hand mouse button perform a paste. These options are checked in the order shown. .It Dv SC_NO_CUTPASTE Disable mouse support. .It VT_FB_DEFAULT_WIDTH=X Set the default width to .Fa X . .It VT_FB_DEFAULT_HEIGHT=Y Set the default height to .Fa Y . .El .Sh BACKWARDS COMPATIBILITY Several options are provided for compatibility with the previous console device, .Xr sc 4 . These options will be removed in a future .Fx version. .Bl -column -offset indent ".Sy vt VT_TWOBUTTON_MOUSE" ".Sy SC_TWOBUTTON_MOUSE" .It Sy vt Option Name Ta Sy sc Option Name .It Dv TERMINAL_KERN_ATTR Ta Dv SC_KERNEL_CONS_ATTR .It Dv TERMINAL_NORM_ATTR Ta Dv SC_NORM_ATTR .It Dv VT_TWOBUTTON_MOUSE Ta Dv SC_TWOBUTTON_MOUSE .It Dv VT_MAXWINDOWS Ta Dv MAXCONS .It none Ta Dv SC_NO_CUTPASTE .El .Sh START-UP OPERATION WITH X86 BIOS SYSTEMS The computer BIOS starts in text mode, and the .Fx .Xr loader 8 runs, loading the kernel. If .Va hw.vga.textmode is set, the system remains in text mode. Otherwise, .Nm switches to 640x480x16 VGA mode using .Cm vt_vga . If a KMS .Pq Kernel Mode Setting video driver is available, the display is switched to high resolution and the KMS driver takes over. When a KMS driver is not available, .Cm vt_vga remains active. .Sh LOADER TUNABLES These settings can be entered at the .Xr loader 8 prompt or in .Xr loader.conf 5 . .Bl -tag -width indent .It Va hw.vga.textmode Set to 1 to use virtual terminals in text mode instead of graphics mode. Features that require graphics mode, like loadable fonts, will be disabled. .It Va kern.vty Set this value to .Ql vt or .Ql sc to override the default driver used for the system console. By default, .Xr sc 4 is used on computers that boot from BIOS, and .Nm is used on computers that boot from UEFI. .It Va kern.vt.fb.default_mode Set this value to a graphic mode to override the default mode picked by the .Nm backend. The mode is applied to all output connectors. This is currently only supported by the .Cm vt_fb backend when it's paired with a KMS video driver. .It Va kern.vt.fb.modes. Ns Pa connector_name Set this value to a graphic mode to override the default mode picked by the .Nm backend. This mode is applied to the output connector .Pa connector_name only. It has precedence over .Va kern.vt.fb.default_mode . The names of available connector names can be found in .Xr dmesg 8 after loading the KMS driver. It will contain a list of connectors and their associated tunables. This is currently only supported by the .Cm vt_fb backend when it's paired with a KMS video driver. .El .Sh KEYBOARD SYSCTL TUNABLES These settings control whether certain special key combinations are enabled or ignored. The specific key combinations can be configured by using a .Xr keymap 5 file. .Pp These settings can be entered at the .Xr loader 8 prompt or in .Xr loader.conf 5 and can also be changed at runtime with the .Xr sysctl 8 command. .Bl -tag -width indent .It Va kern.vt.kbd_halt Enable halt keyboard combination. .It Va kern.vt.kbd_poweroff Enable power off key combination. .It Va kern.vt.kbd_reboot. Enable reboot key combination, usually Ctrl+Alt+Del. .It Va kern.vt.kbd_debug Enable debug request key combination, usually Ctrl+Alt+Esc. .It Va kern.vt.kbd_panic Enable panic key combination. .El .Sh FILES .Bl -tag -width /usr/share/vt/keymaps/* -compact .It Pa /dev/console .It Pa /dev/consolectl .It Pa /dev/ttyv* virtual terminals .It Pa /etc/ttys terminal initialization information .It Pa /usr/share/vt/fonts/*.fnt console fonts .It Pa /usr/share/vt/keymaps/*.kbd keyboard layouts .El .Sh EXAMPLES This example changes the default color of normal text to green on a black background, or black on a green background when reversed. Note that white space cannot be used inside the attribute string because of the current implementation of .Xr config 8 . .Pp .Dl "options TERMINAL_NORM_ATTR=(FG_GREEN|BG_BLACK)" .Pp This line changes the default color of kernel messages to be bright red on a black background, or black on a bright red background when reversed. .Pp .Dl "options TERMINAL_KERN_ATTR=(FG_LIGHTRED|BG_BLACK)" .Pp To set a 1024x768 mode on all output connectors, put the following line in .Pa /boot/loader.conf : .Pp .Dl kern.vt.fb.default_mode="1024x768" .Pp To set a 800x600 only on a laptop builtin screen, use the following line instead: .Pp .Dl kern.vt.fb.modes.LVDS-1="800x600" .Pp The connector name was found in .Xr dmesg 8 : .Pp .Dl info: [drm] Connector LVDS-1: get mode from tunables: .Dl info: [drm] - kern.vt.fb.modes.LVDS-1 .Dl info: [drm] - kern.vt.fb.default_mode .Sh SEE ALSO .Xr kbdcontrol 1 , .Xr login 1 , .Xr vidcontrol 1 , .Xr atkbd 4 , .Xr atkbdc 4 , .Xr keyboard 4 , .Xr screen 4 , .Xr splash 4 , .Xr syscons 4 , .Xr ukbd 4 , .Xr kbdmap 5 , .Xr rc.conf 5 , .Xr ttys 5 , .Xr config 8 , .Xr getty 8 , .Xr kbdmux 8 , .Xr kldload 8 , .Xr moused 8 , .Xr vtfontcvt 8 .Sh HISTORY The .Nm driver first appeared in .Fx 9.3 . .Sh AUTHORS .An -nosplit The .Nm device driver was developed by -.An Ed Schouten Aq Mt ed@FreeBSD.org , -.An Ed Maste Aq Mt emaste@FreeBSD.org , +.An \&Ed Schouten Aq Mt ed@FreeBSD.org , +.An \&Ed Maste Aq Mt emaste@FreeBSD.org , and .An Aleksandr Rybalko Aq Mt ray@FreeBSD.org , with sponsorship provided by the .Fx Foundation. This manual page was written by .An Warren Block Aq Mt wblock@FreeBSD.org . .Sh CAVEATS Paste buffer size is limited by the system value .Brq Dv MAX_INPUT , the number of bytes that can be stored in the terminal input queue, usually 1024 bytes (see .Xr termios 4 ) . Index: head/share/man/man7/release.7 =================================================================== --- head/share/man/man7/release.7 (revision 286662) +++ head/share/man/man7/release.7 (revision 286663) @@ -1,798 +1,797 @@ .\" Copyright (c) 2002 Murray Stokely .\" 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 February 20, 2015 .Dt RELEASE 7 .Os .Sh NAME .Nm release .Nd "release building infrastructure" .Sh DESCRIPTION .Fx provides a complete build environment suitable for users to make full releases of the .Fx operating system. All of the tools necessary to build a release are available from the .Fx source code repository in .Pa src/release . A complete release can actually be built with only a single command, including the creation of ISO images suitable for burning to CD-ROM, memory stick images, and an FTP install directory. This command is aptly named .Dq Li "make release" . .Pp For some users, it may be desirable to provide an absolutely clean build environment, with no local modifications to the source tree or to .Xr make.conf 5 , and with clean checkouts of specific versions of the doc, src, and ports trees. For this purpose, a script .Pq Pa src/release/release.sh is provided to automate these checkouts and then execute .Dq Li "make release" in a clean .Xr chroot 8 . .Pp Before attempting to build a release, the user is expected to be familiar with the contents of .Xr build 7 , and should have experience upgrading systems from source. .Pp The release build process requires that .Pa /usr/obj be populated with the output of .Dq Li "make buildworld" and .Dq Li "make buildkernel" . This is necessary to provide the object files for the release or, when using .Pa release.sh , so that the object files for a complete system can be installed into a clean .Xr chroot 8 environment. .Pp If the target release build is for a different architecture or machine type, the .Va TARGET and .Va TARGET_ARCH variables must be used. See the supported .Fa release.conf variables for more information. .Pp The release procedure on some architectures may also require that the .Xr md 4 (memory disk) device driver be present in the kernel .Pq either by being compiled in or available as a module . .Pp This document does not cover source code management, quality assurance, or other aspects of the release engineering process. .Sh CLEAN RELEASE GENERATION Official releases of .Fx are produced in a totally clean environment to ensure consistency between the versions of the src, ports, and doc trees and to avoid contamination from the host system .Po such as local patches, changes to .Xr make.conf 5 , etc. .Pc . This is accomplished using the wrapper script .Pa src/release/release.sh . .Pp .Ic release.sh .Op Fl c Ar release.conf .Pp .Ic release.sh checks out the .Li src/ , .Li ports/ , and .Li doc/ trees to .Va CHROOTDIR , then calls .Dq Li "make buildworld" and .Dq Li "make installworld" to generate a .Xr chroot 8 environment. Next, .Dq Li "make release" is run within the .Xr chroot 8 environment and places the result in .Pa $CHROOTDIR/R . .Pp The optional .Fa release.conf configuration file supports the following variables: .Bl -tag -width Ev .It Va CHROOTDIR The directory within which the release will be built. .It Va CHROOT_MAKEENV Additional .Xr make 1 arguments to pass through, which directly affect the tuning of the build chroot. .It Va SVNROOT The .Xr svn 1 host used to check out the various trees. Defaults to .Pa svn://svn.FreeeBSD.org . .It Va SRCBRANCH The .Li src/ branch to use. Defaults to .Va head/@rHEAD . .It Va DOCBRANCH The .Li doc/ branch to use. Defaults to .Va head/@rHEAD . .It Va PORTBRANCH The .Li ports/ branch to use. Defaults to .Va head/@rHEAD . .It Va TARGET The target machine type for cross-building a release. .It Va TARGET_ARCH The target machine architecture for cross-building a release. .Pp For the supported list of .Va TARGET and .Va TARGET_ARCH combinations, consult the output of .Dq make targets as documented in .Xr build 7 . .It Va KERNEL The target kernel configuration to use. Defaults to .Va GENERIC . Multiple .Va KERNEL entries may be specified. .It Va MAKE_CONF The .Xr make.conf 5 to use for the release build. Defaults to .Fa /dev/null to prevent polluting the release with local system changes. .It Va SRC_CONF The .Xr src.conf 5 to use for the release build. Defaults to .Fa /dev/null to prevent polluting the release with local system changes. .It Va MAKE_FLAGS Additional flags to pass to .Xr make 1 . .It Va WORLD_FLAGS Additional flags to pass to .Xr make 1 during the .Dq buildworld phase. Defaults to setting the number of .Xr make 1 jobs .Pq Ar -j to the number of CPUs available on a SMP-capable system. .It Va KERNEL_FLAGS Additional flags to pass to .Xr make 1 during the .Dq buildkernel phase. Defaults to setting the number of .Xr make 1 jobs .Pq Ar -j to half the number of CPUs available on a SMP-capable system. .It Va NODOC Set to a non-empty value to skip the .Li doc/ tree checkout. When set, .Va NODOC will prevent the .Fa doc.txz distribution package from being created. .It Va NOPORTS Set to a non-empty value to skip the .Li ports/ tree checkout. When set, .Va NOPORTS will prevent the .Fa ports.txz distribution package from being created. Setting this also sets .Va NODOC . .It Va WITH_DVD Set to a non-empty value to include the .Cm dvdrom target. .It Va WITH_COMPRESSED_IMAGES Set to a non-empty value to compress the release images with .Xr xz 1 . The original .Pq uncompressed images are not removed. .It Va XZ_THREADS Pq Vt int Set to the number of threads .Xr xz 1 should use when compressing images. By default, .Va XZ_THREADS is set to .Va 0 , which uses all available cores on the system. .It Va VCSCMD The command run to obtain the source trees. Defaults to .Qq Cm svn checkout . .It Va CHROOTBUILD_SKIP If defined, the .Li buildworld , .Li installworld , and .Li distribution stages of the .Xr chroot 8 build environment setup are skipped. This is intended solely for cases where the .Xr chroot 8 userland are provided by alternate means. .It Va SRC_UPDATE_SKIP Set to a non-empty value to prevent checkout or update of .Fa /usr/src within the .Xr chroot 8 . This is intended for use only when .Fa /usr/src is expected to exist by alternative means. .It Va DOC_UPDATE_SKIP Set to a non-empty value to prevent checkout or update of .Fa /usr/doc within the .Xr chroot 8 . This is intended for use only when .Fa /usr/doc is expected to exist by alternative means. .It Va PORTS_UPDATE_SKIP Set to a non-empty value to prevent checkout or update of .Fa /usr/ports within the .Xr chroot 8 . This is intended for use only when .Fa /usr/ports is expected to exist by alternative means. .El .Sh EMBEDDED BUILDS The following .Fa release.conf variables are relevant only to release builds for embedded systems: .Bl -tag -width Ev .It Va EMBEDDEDBUILD Set to a non-null value to enable functionality for embedded device release builds. .Pq This option is considered highly experimental. .Pp When set, .Va WITH_DVD is unset, and .Va NODOC is defined. Additionally, .Va XDEV and .Va XDEV_ARCH must also be defined. When the build environment is created, .Fa release.sh runs a separate build script located in an architecture-specific directory in .Pa src/release/${XDEV}/ . .It Va EMBEDDEDPORTS Set to the list of any ports that are required for the target device in the format of .Fa category/port . The .Fa devel/subversion port is built by default. .It Va CROCHETSRC Set to the source URL for the Crochet build tool. .It Va CROCHETBRANCH Set to the subversion branch from .Va ${CROCHETSRC} to use. Defaults to .Pa trunk . .It Va UBOOTSRC Set to the source URL of u-boot, if required. .It Va UBOOTBRANCH Set to the subversion branch from .Va ${UBOOTSRC} to use. Defaults to .Pa trunk . .It Va UBOOTDIR Set to the target directory within .Va ${CHROOTDIR} to check out .Va ${UBOOTSRC}/${UBOOTBRANCH} . .El .Sh VIRTUAL MACHINE DISK IMAGES The following .Fa release.conf variables are relevant only to virtual machine disk image builds: .Bl -tag -width Ev .It Va WITH_VMIMAGES Set to a non-null value to build virtual machine disk images as part of the release build. .Va WITH_VMIMAGES may also be specified as an envirionment variable passed to .Xr make 1 . .Pp The option requires .Xr mkimg 1 version 20140927 or later. .It Va WITH_COMPRESSED_VMIMAGES Set to a non-null value to compress the virtual machine disk images with .Xr xz 1 as part of the .Cm install .Xr make 1 target. Note that compressing virtual machine disk images may take a very long time on some systems. .It Va VMBASE Set to change the name of the resulting virtual machine disk image file. The default value is .Va vm . .It Va VMSIZE Set to change the size of the virtual machine disk capacity. The default value is .Va 20G . See .Xr truncate 1 for valid values. .Pp Virtual machine disk images are, by default, created as sparse images. When .Va WITH_COMPRESSED_VMIMAGES is used, the resulting files compressed with .Xr xz 1 compress to roughly the same size, regardless of the specified disk image size. .It Va VMFORMATS Set to the target virtual disk image format(s) to create. By default, the .Va vhdf , Va vmdk , Va qcow2 , and .Va raw formats are created. See .Xr mkimg 1 for valid format values .Pq requires version 20140927 or later . .El .Pp For a list of supported .Va VMFORMATS values .Pq including cloud hosting provider formats along with a brief description, run: .Bd -literal -offset indent cd /usr/src make -C release list-vmtargets .Ed .Sh CLOUD HOSTING MACHINE IMAGES The .Fx release build tools support building virtual machine images for various cloud hosting providers, each with their own specific configuration to include support for each hosting provider by default. .Pp The following .Xr make 1 environment variables are supported: -.Pp .Bl -tag -width Ev .It Va CLOUDWARE Set to a list of one or more cloud hosting providers, enclosed in quotes. Requires .Va WITH_CLOUDWARE to also be set. .It Va WITH_CLOUDWARE Set to a non-empty value to enable building virtual machine images for various cloud hosting providers. Requires .Va CLOUDWARE to also be set. .El .Pp Additionally, the .Va CLOUDWARE and .Va WITH_CLOUDWARE variables can be added to .Pa release.conf , and used in conjunction with .Pa release.sh . .Pp For a list of supported .Va CLOUDWARE values, run: .Bd -literal -offset indent cd /usr/src make -C release list-cloudware .Ed .Sh MAKEFILE TARGETS The release makefile .Pq Pa src/release/Makefile is fairly abstruse. Most developers will only be concerned with the .Cm release and .Cm install targets. .\" XXX: Some sort of introduction to this list? All the others have one. .Bl -tag -width ".Cm packagesystem" .It Cm release Meta-target to build all release media and distributions applicable to this platform. .It Cm install Copy all produced release media to .Pa ${DESTDIR} . .It Cm cdrom Builds installation CD-ROM images. This may require the .Xr md 4 (memory disk) device driver be present in the kernel (either by being compiled in or available as a module). This target produces files called .Pa disc1.iso and .Pa bootonly.iso as its output. .It Cm dvdrom Builds installation DVD-ROM images. This may require the .Xr md 4 (memory disk) device driver be present in the kernel (either by being compiled in or available as a module). This target produces the .Pa dvd1.iso file as its output. .It Cm memstick Builds an installation memory stick image named .Pa memstick.img . Not applicable on all platforms. Requires that the .Xr md 4 .Pq memory disk device driver be present in the kernel .Pq either by being compiled in or available as a module . .It Cm mini-memstick Similar to .Cm memstick , with the exception that the installation distribution sets are not included. .It Cm ftp Creates a directory named .Pa ftp containing the distribution files used in network installations and suitable for upload to an FTP mirror. .It Cm vm-image Creates virtual machine disk images in various formats. The .Cm vm-image target requires the .Va WITH_VMIMAGES .Xr make 1 envirionment variable to be set to a non-null value. .It Cm vm-cloudware Builds .Fx virtual machine images for various cloud hosting providers. See .Qq CLOUD HOSTING MACHINE IMAGES for implementation details. .It Cm list-cloudware Displays the list of valid .Va CLOUDWARE values. .It Cm list-vmtargets Displays the list of valid .Va VMFORMAT and .Va CLOUDWARE values. .El .Pp Major subtargets called by targets above: .Bl -tag -width ".Cm packagesystem" .It Cm packagesystem Generates all the distribution archives .Pq base, kernel, ports, doc applicable on this platform. .It Cm disc1 Builds a bootable installation system containing all the distribution files packaged by the .Cm packagesystem target, and suitable for imaging by the .Cm cdrom , .Cm dvdrom and .Cm memstick targets. .It Cm reldoc Builds the release documentation. This includes the release notes, hardware guide, and installation instructions. Other documentation, such as the Handbook, is built during the .Cm base.txz target invoked by .Cm packagesystem . .El .Sh ENVIRONMENT Optional variables: .Bl -tag -width ".Ev TARGET_ARCH" .It Ev OSRELEASE Optional base name for generated media images .Pq e.g., FreeBSD-9.0-RC2-amd64 . Defaults to the output of .Ic `uname -s`-`uname -r`-`uname -p` within the chroot. .It Ev WORLDDIR Location of a directory containing the src tree. By default, the directory above the one containing the makefile .Pq Pa src . .It Ev PORTSDIR Location of a directory containing the ports tree. By default, .Pa /usr/ports . If it is unset or cannot be found, ports will not be included in the release. .It Ev DOCDIR Location of a directory containing the doc tree. By default, .Pa /usr/doc . If it is unset or cannot be found, most documentation will not be included in the release; see .Ev NODOC below. .It Ev NOPORTS If defined, the Ports Collection will be omitted from the release. .It Ev NOSRC If set, do not include system source code in the release. .It Ev NODOC If defined, the XML-based documentation from the .Fx Documentation Project will not be built. However, the .Dq doc distribution will still be created with the minimal documentation set provided in .Pa src/share/doc . .It Ev TARGET The target hardware platform. This is analogous to the .Dq Nm uname Fl m output. This is necessary to cross-build some target architectures. For example, cross-building for PC98 machines requires .Ev TARGET_ARCH Ns = Ns Li i386 and .Ev TARGET Ns = Ns Li pc98 . If not set, .Ev TARGET defaults to the current hardware platform. .It Ev TARGET_ARCH The target machine processor architecture. This is analogous to the .Dq Nm uname Fl p output. Set this to cross-build for a different architecture. If not set, .Ev TARGET_ARCH defaults to the current machine architecture, unless .Ev TARGET is also set, in which case it defaults to the appropriate value for that platform. Typically, one only needs to set .Ev TARGET . .El .Sh FILES .Bl -tag -compact -width Pa .It Pa /usr/doc/Makefile .It Pa /usr/doc/share/mk/doc.project.mk .It Pa /usr/ports/Mk/bsd.port.mk .It Pa /usr/ports/Mk/bsd.sites.mk .It Pa /usr/share/examples/etc/make.conf .It Pa /usr/src/Makefile .It Pa /usr/src/Makefile.inc1 .It Pa /usr/src/release/Makefile .It Pa /usr/src/release/Makefile.vm .It Pa /usr/src/release/release.sh .It Pa /usr/src/release/release.conf.sample .It Pa /usr/src/release/tools/*.conf .It Pa /usr/src/release/tools/vmimage.subr .El .Sh EXAMPLES The following sequence of commands can be used to build a .Dq "-CURRENT snapshot": .Bd -literal -offset indent cd /usr svn co svn://svn.freebsd.org/base/head src cd src make buildworld buildkernel cd release make release make install DESTDIR=/var/freebsd-snapshot .Ed .Pp After running these commands, all produced distribution files (tarballs for FTP, CD-ROM images, etc.) are available in the .Pa /var/freebsd-snapshot directory. .Pp The following sequence of commands can be used to build a .Dq "-CURRENT snapshot" in a clean environment, including ports and documentation: .Bd -literal -offset indent cd /usr/src/release sh release.sh .Ed .Pp Optionally, a configuration file can be used customize the release build, such as the subversion revision to use, the branch of the subversion tree for .Li src/ , .Li ports/ , and .Li doc/ . .Bd -literal -offset indent cd /usr/src/release sh release.sh -c $HOME/release.conf .Ed .Pp After running these commands, all prepared release files are available in the .Pa /scratch directory. The target directory can be changed by specifying the .Va CHROOTDIR variable in .Li release.conf . .Sh SEE ALSO .Xr cc 1 , .Xr install 1 , .Xr make 1 , .Xr svn 1 Pq Pa ports/devel/subversion , .Xr uname 1 , .Xr md 4 , .Xr make.conf 5 , .Xr build 7 , .Xr ports 7 , .Xr chroot 8 , .Xr mtree 8 , .Xr sysctl 8 .Rs .%T "FreeBSD Release Engineering" .%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/ .Re .Rs .%T "FreeBSD Release Engineering of Third Party Packages" .%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/ .Re .Rs .%T "FreeBSD Developers' Handbook" .%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/ .Re .Sh HISTORY .Fx 1.x used a manual checklist, compiled by .An Rod Grimes , to produce a release. Apart from being incomplete, the list put a lot of specific demands on available file systems and was quite torturous to execute. .Pp As part of the .Fx 2.0 release engineering effort, significant effort was spent getting .Pa src/release/Makefile into a shape where it could at least automate most of the tediousness of building a release in a sterile environment. .Pp For the .Fx 9.0 release, .Pa src/release/Makefile was overhauled and the wrapper script .Pa src/release/generate-release.sh introduced to support the introduction of a new installer. .Pp For the .Fx 9.2 release, .Pa src/release/release.sh was introduced to support per-build configuration files. .Pa src/release/release.sh is heavily based on the .Pa src/release/generate-release.sh script. .Pp At near 1000 revisions spread over multiple branches, the .Xr svn 1 log of .Pa src/release/Makefile contains a vivid historical record of some of the hardships release engineers go through. .Sh AUTHORS .Pa src/release/Makefile was originally written by .An -nosplit .An Rod Grimes , .An Jordan Hubbard , and .An Poul-Henning Kamp . .Pp This manual page was originally written by .An Murray Stokely Aq Mt murray@FreeBSD.org . .Pp It was updated by .An Nathan Whitehorn Aq Mt nwhitehorn@FreeBSD.org to include the .Fa generate-release.sh script used for the .Fx 9.0 release cycle. .Pp It was later updated by .An Glen Barber Aq Mt gjb@FreeBSD.org to include the .Fa release.sh script used for the .Fx 9.2 release cycle. Index: head/share/man/man8/nanobsd.8 =================================================================== --- head/share/man/man8/nanobsd.8 (revision 286662) +++ head/share/man/man8/nanobsd.8 (revision 286663) @@ -1,339 +1,339 @@ .\" Copyright (c) 2006 Daniel Gerzo .\" 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 AUTHORS 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 AUTHORS 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 May 20, 2010 .Dt NANOBSD 8 .Os .Sh NAME .Nm nanobsd.sh .Nd utility used to create a FreeBSD system image suitable for embedded applications .Sh SYNOPSIS .Nm .Op Fl bhknw .Op Fl c Ar config-file .Sh DESCRIPTION The .Nm utility is a script which produces a minimal implementation of .Fx (called .Nm NanoBSD ) , which typically fits on a small media such as a Compact Flash card, or other mass storage medium. It can be used to build specialized install images, designed for easy installation and maintenance. .Pp The following options are available: .Bl -tag -width ".Fl c Ar config-file" -offset indent .It Fl b Skip the build stages (both for kernel and world). .It Fl c Ar config-file Specify the configuration file to use. .It Fl h Display usage information. .It Fl k Skip the .Cm buildkernel stage of the build. .It Fl n Do not cleanup before each build stage. This suppresses the normal cleanup work done before the .Cm buildworld stage and adds -DNO_CLEAN to the make command line used for each build stage (world and kernel). .It Fl w Skip the .Cm buildworld stage of the build. .El .Pp The features of .Nm NanoBSD include: .Pp .Bl -bullet -offset indent -compact .It Ports and packages work as in .Fx . Every single application can be installed and used in a .Nm NanoBSD image, the same way as in .Fx . .It No missing functionality. If it is possible to do something with .Fx , it is possible to do the same thing with .Nm NanoBSD , unless the specific feature or features were explicitly removed from the .Nm NanoBSD image when it was created. .It Everything is read-only at run-time. It is safe to pull the power-plug. There is no necessity to run .Xr fsck 8 after a non-graceful shutdown of the system. .It Easy to build and customize. Making use of just one shell script and one configuration file it is possible to build reduced and customized images satisfying any arbitrary set of requirements. .El -.Ss Nm NanoBSD Ss Media Layout +.Ss NanoBSD Media Layout The mass storage medium is divided into three parts by default (which are normally mounted read-only): .Pp .Bl -bullet -offset indent -compact .It Two image partitions: .Li code#1 and .Li code#2 . .It The configuration file partition, which can be mounted under the .Pa /cfg directory at run time. .El .Pp The .Pa /etc and .Pa /var directories are .Xr md 4 (malloc backed) disks. .Pp The configuration file partition persists under the .Pa /cfg directory. It contains files for .Pa /etc directory and is briefly mounted read-only right after the system boot, therefore it is required to copy modified files from .Pa /etc back to the .Pa /cfg directory if changes are expected to persist after the system restarts. .Sh BUILDING Nm NanoBSD A .Nm NanoBSD image is built using a simple .Nm shell script, which can be found in the .Pa src/tools/tools/nanobsd directory. This script creates a bootable image, which can be copied on the storage medium using the .Xr dd 1 utility. .Pp The necessary commands to build and install a .Nm NanoBSD image are: .Bd -literal -offset indent cd /usr/src/tools/tools/nanobsd sh nanobsd.sh cd /usr/obj/nanobsd.full dd if=_.disk.full of=/dev/da0 bs=64k .Ed .Sh CUSTOMIZING Nm NanoBSD This is probably the most important and most interesting feature of .Nm NanoBSD . This is also where you will be spending most of the time when developing with .Nm NanoBSD . .Pp Customization is done in two ways: .Pp .Bl -bullet -offset indent -compact .It Configuration options. .It Custom functions. .El .Pp With configuration settings, it is possible to configure options passed to both the .Cm buildworld and .Cm installworld stages of the .Nm NanoBSD build process, as well as internal options passed to the main build process of .Nm NanoBSD . Through these options it is possible to cut the system down, so it will fit on as little as 64MB. You can use the configuration options to trim down the system even more, until it will consist of just the kernel and two or three files in the userland. .Pp The configuration file consists of configuration options, which override the default values. The most important directives are: .Bl -tag -width ".Va CONF_INSTALL" -offset indent .It Va NANO_NAME Build name (used to construct the working directory names). .It Va NANO_SRC Path to the source tree used to build the image. .It Va NANO_KERNEL Name of the kernel configuration file used to build the kernel. .It Va NANO_ARCH Machine processor architecture to build. Defaults to output of .Cm uname -p . .It Va NANO_BOOT0CFG Controls the options passed to .Xr boot0cfg 8 ; these dictate .Nm boot0 Ns 's behaviour. .It Va NANO_BOOTLOADER The .Nm boot0 loader to use relative to the .Va NANO_WORLDDIR variable. This defaults to .Pa boot/boot0sio and should be overridden to .Pa boot/boot0 to provide a VGA console. .It Va CONF_BUILD Options passed to the .Cm buildworld stage of the build. .It Va CONF_INSTALL Options passed to the .Cm installworld stage of the build. .It Va CONF_WORLD Options passed to both the .Cm buildworld and .Cm installworld stages of the build. .It Va FlashDevice Defines the type of media to use. Check the .Pa FlashDevice.sub file for more details. .El .Pp For more configuration options, please check the .Nm script. .Pp To build .Nm NanoBSD image using the .Pa nanobsd.conf configuration file, use the following command: .Bd -literal -offset indent sh nanobsd.sh -c nanobsd.conf .Ed .Pp It is possible to fine-tune .Nm NanoBSD using shell functions in the configuration file. The following example illustrates the basic model of custom functions: .Bd -literal -offset indent cust_foo () ( echo "bar=topless" > \\ ${NANO_WORLDDIR}/etc/foo ) customize_cmd cust_foo .Ed .Pp There are a few pre-defined customization functions ready for use: .Bl -tag -width ".Cm cust_allow_ssh_root" -offset indent .It Cm cust_comconsole Disables .Xr getty 8 on the virtual .Xr syscons 4 or .Xr vt 4 terminals .Pq Pa /dev/ttyv* and enables the use of the first serial port as the system console. .It Cm cust_allow_ssh_root Allow root to log in via .Xr sshd 8 . .It Cm cust_install_files Installs files from the .Pa nanobsd/Files directory, which contains some useful scripts for system administration. .El .Sh FILES .Bl -tag -width ".Pa src/tools/tools/nanobsd" -compact .It Pa src/tools/tools/nanobsd Base directory of the .Nm NanoBSD build script. .El .Sh EXAMPLES Making persistent changes to .Pa /etc/resolv.conf : .Bd -literal -offset indent vi /etc/resolv.conf \&... mount /cfg cp /etc/resolv.conf /cfg umount /cfg .Ed .Pp A more useful example of a customization function is the following, which changes the default size of the .Pa /etc directory from 5MB to 30MB: .Bd -literal -offset indent cust_etc_size () ( cd ${NANO_WORLDDIR}/conf echo 30000 > default/etc/md_size ) customize_cmd cust_etc_size .Ed .Sh SEE ALSO .Xr make.conf 5 , .Xr boot 8 , .Xr boot0cfg 8 , .Xr picobsd 8 .Sh HISTORY The .Nm utility first appeared in .Fx 6.0 . .Sh AUTHORS .An -nosplit .Nm NanoBSD was developed by .An Poul-Henning Kamp Aq Mt phk@FreeBSD.org . This manual page was written by .An Daniel Gerzo Aq Mt danger@FreeBSD.org . Index: head/share/man/man8/uefi.8 =================================================================== --- head/share/man/man8/uefi.8 (revision 286662) +++ head/share/man/man8/uefi.8 (revision 286663) @@ -1,153 +1,153 @@ .\" Copyright (c) 2014 The FreeBSD Foundation .\" 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 AUTHORS 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 AUTHORS 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 26, 2015 .Dt UEFI 8 .Os .Sh NAME .Nm UEFI .Nd Unified Extensible Firmware Interface bootstrapping procedures .Sh DESCRIPTION The .Nm Unified Extensible Firmware Interface provides boot- and run-time services to operating systems. .Nm is a replacement for the legacy BIOS on the i386 and amd64 CPU architectures, and is also used on arm64 and ia64. .Pp The .Nm boot process loads system bootstrap code located in an EFI System Partition (ESP). The ESP is a GPT or MBR partition with a specific identifier that contains an .Xr msdosfs 5 FAT file system with a specified file hierarchy. .Bl -column -offset indent ".Sy Partition Scheme" ".Sy ESP Identifier" .It Sy "Partition Scheme" Ta Sy "ESP Identifier" .It GPT Ta C12A7328-F81F-11D2-BA4B-00A0C93EC93B .It MBR Ta 0xEF .El .Pp The .Nm boot process proceeds as follows: .Bl -enum -offset indent -compact .It .Nm firmware runs at power up and searches for an OS loader in the EFI system partition. The path to the loader may be set by an EFI environment variable. If not set, the default is .Pa /EFI/BOOT/BOOTX64.EFI . The default .Nm boot configuration for .Fx installs .Pa boot1.efi as .Pa /EFI/BOOT/BOOTX64.EFI . .It .Pa boot1.efi locates the first partition with the type .Li freebsd-ufs , and from it loads .Pa loader.efi . .It .Pa loader.efi loads and boots the kernel, as described in .Xr loader 8 . .El .Pp The .Xr vt 4 system console is automatically selected when booting via .Nm . .Sh FILES .Bl -tag -width /boot/loader -compact .It Pa /boot/boot1.efi First stage .Nm bootstrap .It Pa /boot/boot1.efifat .Xr msdosfs 5 FAT file system image containing .Pa boot1.efi for use by .Xr bsdinstall 8 and the .Ar bootcode argument to .Xr gpart 8 . .It Pa /boot/loader.efi Final stage bootstrap .It Pa /boot/kernel/kernel default kernel .It Pa /boot/kernel.old/kernel typical non-default kernel (optional) .El .Sh SEE ALSO .Xr vt 4 , .Xr msdosfs 5 , .Xr boot 8 , -.Xr gpart 8 , +.Xr gpart 8 , .Xr uefisign 8 .Sh HISTORY .Nm boot support first appeared in .Fx 10.1 . .Sh AUTHORS .An -nosplit .Nm boot support was developed by .An Benno Rice Aq Mt benno@FreeBSD.org , -.An Ed Maste Aq Mt emaste@FreeBSD.org , +.An \&Ed Maste Aq Mt emaste@FreeBSD.org , and .An Nathan Whitehorn Aq Mt nwhitehorn@FreeBSD.org . The .Fx Foundation sponsored portions of the work. .Sh CAVEATS EFI environment variables are not supported by .Xr loader 8 or the kernel. .Pp .Pa boot1.efi loads .Pa loader.efi from the first FreeBSD-UFS file system it locates, even if it is on a different disk. .Pp .Pa boot1.efi cannot load .Pa loader.efi from a .Xr ZFS 8 file system. As a result, .Nm does not support a typical root file system on ZFS configuration. Index: head/share/man/man8/yp.8 =================================================================== --- head/share/man/man8/yp.8 (revision 286662) +++ head/share/man/man8/yp.8 (revision 286663) @@ -1,588 +1,591 @@ .\" Copyright (c) 1992/3 Theo de Raadt .\" 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 ``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. .\" .\" from: @(#)yp.8 1.0 (deraadt) 4/26/93 .\" $FreeBSD$ .\" .Dd December 14, 2011 .Dt YP 8 .Os .Sh NAME .Nm yp .Nd description of the YP/NIS system .Sh SYNOPSIS .Nm .Sh DESCRIPTION The .Nm YP subsystem allows network management of passwd, group, netgroup, hosts, services, rpc, bootparams and ethers file entries through the functions .Xr getpwent 3 , .Xr getgrent 3 , .Xr getnetgrent 3 , .Xr gethostent 3 , .Xr getnetent 3 , .Xr getrpcent 3 , and .Xr ethers 3 . The .Xr bootparamd 8 daemon makes direct .Tn NIS library calls since there are no functions in the standard C library for reading bootparams. .Tn NIS support is enabled in .Xr nsswitch.conf 5 . .Pp The .Nm YP subsystem is started automatically in .Pa /etc/rc if it has been initialized in .Pa /etc/rc.conf and if the directory .Pa /var/yp exists (which it does in the default distribution). The default .Tn NIS domain must also be set with the .Xr domainname 1 command, which will happen automatically at system startup if it is specified in .Pa /etc/rc.conf . .Pp .Tn NIS is an .Tn RPC Ns -based client/server system that allows a group of machines within an .Tn NIS domain to share a common set of configuration files. This permits a system administrator to set up .Tn NIS client systems with only minimal configuration data and add, remove or modify configuration data from a single location. .Pp The canonical copies of all .Tn NIS information are stored on a single machine called the .Tn NIS .Em "master server" . The databases used to store the information are called .Tn NIS .Em maps . In .Fx , these maps are stored in .Pa /var/yp/ Ns Aq Ar domainname where .Aq Ar domainname is the name of the .Tn NIS domain being served. A single .Tn NIS server can support several domains at once, therefore it is possible to have several such directories, one for each supported domain. Each domain will have its own independent set of maps. .Pp In .Fx , the .Tn NIS maps are Berkeley DB hashed database files (the same format used for the .Xr passwd 5 database files). Other operating systems that support .Tn NIS use old-style .Nm ndbm databases instead (largely because Sun Microsystems originally based their .Tn NIS implementation on .Nm ndbm , and other vendors have simply licensed Sun's code rather than design their own implementation with a different database format). On these systems, the databases are generally split into .Pa .dir and .Pa .pag files which the .Nm ndbm code uses to hold separate parts of the hash database. The Berkeley DB hash method instead uses a single file for both pieces of information. This means that while you may have .Pa passwd.byname.dir and .Pa passwd.byname.pag files on other operating systems (both of which are really parts of the same map), .Fx will have only one file called .Pa passwd.byname . The difference in format is not significant: only the .Tn NIS server, .Xr ypserv 8 , and related tools need to know the database format of the .Tn NIS maps. Client .Tn NIS systems receive all .Tn NIS data in .Tn ASCII form. .Pp There are three main types of .Tn NIS systems: .Bl -enum .It .Tn NIS clients, which query .Tn NIS servers for information. .It .Tn NIS master servers, which maintain the canonical copies of all .Tn NIS maps. .It .Tn NIS slave servers, which maintain backup copies of .Tn NIS maps that are periodically updated by the master. .El .Pp A .Tn NIS client establishes what is called a .Em binding to a particular .Tn NIS server using the .Xr ypbind 8 daemon. The .Xr ypbind 8 utility checks the system's default domain (as set by the .Xr domainname 1 command) and begins broadcasting .Tn RPC requests on the local network. These requests specify the name of the domain for which .Xr ypbind 8 is attempting to establish a binding. If a server that has been configured to serve the requested domain receives one of the broadcasts, it will respond to .Xr ypbind 8 , which will record the server's address. If there are several servers available (a master and several slaves, for example), .Xr ypbind 8 will use the address of the first one to respond. From that point on, the client system will direct all of its .Tn NIS requests to that server. The .Xr ypbind 8 utility will occasionally .Dq ping the server to make sure it is still up and running. If it fails to receive a reply to one of its pings within a reasonable amount of time, .Xr ypbind 8 will mark the domain as unbound and begin broadcasting again in the hopes of locating another server. .Pp .Tn NIS master and slave servers handle all .Tn NIS requests with the .Xr ypserv 8 daemon. The .Xr ypserv 8 utility is responsible for receiving incoming requests from .Tn NIS clients, translating the requested domain and map name to a path to the corresponding database file and transmitting data from the database back to the client. There is a specific set of requests that .Xr ypserv 8 is designed to handle, most of which are implemented as functions within the standard C library: .Bl -tag -width ".Fn yp_master" .It Fn yp_order check the creation date of a particular map .It Fn yp_master obtain the name of the .Tn NIS master server for a given map/domain .It Fn yp_match lookup the data corresponding to a given in key in a particular map/domain .It Fn yp_first obtain the first key/data pair in a particular map/domain .It Fn yp_next pass .Xr ypserv 8 a key in a particular map/domain and have it return the key/data pair immediately following it (the functions .Fn yp_first and .Fn yp_next can be used to do a sequential search of an .Tn NIS map) .It Fn yp_all retrieve the entire contents of a map .El .Pp There are a few other requests which .Xr ypserv 8 is capable of handling (i.e., acknowledge whether or not you can handle a particular domain .Pq Dv YPPROC_DOMAIN , or acknowledge only if you can handle the domain and be silent otherwise .Pq Dv YPPROC_DOMAIN_NONACK ) but these requests are usually generated only by .Xr ypbind 8 and are not meant to be used by standard utilities. .Pp On networks with a large number of hosts, it is often a good idea to use a master server and several slaves rather than just a single master server. A slave server provides the exact same information as a master server: whenever the maps on the master server are updated, the new data should be propagated to the slave systems using the .Xr yppush 8 command. The .Tn NIS .Pa Makefile .Pq Pa /var/yp/Makefile will do this automatically if the administrator creates .Pa /var/yp/Makefile.local and empties the .Va NOPUSH variable: .Bd -literal -offset four .Li NOPUSH= .Ed .Pp .Va ( NOPUSH is set to true by default because the default configuration is for a small network with only one .Tn NIS server). The .Xr yppush 8 command will initiate a transaction between the master and slave during which the slave will transfer the specified maps from the master server using .Xr ypxfr 8 . (The slave server calls .Xr ypxfr 8 automatically from within .Xr ypserv 8 ; therefore it is not usually necessary for the administrator to use it directly. It can be run manually if desired, however.) Maintaining slave servers helps improve .Tn NIS performance on large networks by: .Bl -bullet .It Providing backup services in the event that the .Tn NIS master crashes or becomes unreachable .It Spreading the client load out over several machines instead of causing the master to become overloaded .It Allowing a single .Tn NIS domain to extend beyond a local network (the .Xr ypbind 8 daemon might not be able to locate a server automatically if it resides on a network outside the reach of its broadcasts. It is possible to force .Xr ypbind 8 to bind to a particular server with .Xr ypset 8 but this is sometimes inconvenient. This problem can be avoided simply by placing a slave server on the local network.) .El .Pp The .Fx .Xr ypserv 8 is specially designed to provide enhanced security (compared to other .Tn NIS implementations) when used exclusively with .Fx client systems. The .Fx password database system (which is derived directly from .Bx 4.4 ) includes support for .Em "shadow passwords" . The standard password database does not contain users' encrypted passwords: these are instead stored (along with other information) in a separate database which is accessible only by the super-user. If the encrypted password database were made available as an .Tn NIS map, this security feature would be totally disabled, since any user is allowed to retrieve .Tn NIS data. .Pp To help prevent this, .Fx Ns 's .Tn NIS server handles the shadow password maps .Pa ( master.passwd.byname , .Pa master.passwd.byuid , .Pa shadow.byname and .Pa shadow.byuid ) in a special way: the server will only provide access to these maps in response to requests that originate on privileged ports. Since only the super-user is allowed to bind to a privileged port, the server assumes that all such requests come from privileged users. All other requests are denied: requests from non-privileged ports will receive only an error code from the server. Additionally, .Fx Ns 's .Xr ypserv 8 includes support for .An Wietse Venema Ns 's tcp wrapper package; with tcp wrapper support enabled, the administrator can configure .Xr ypserv 8 to respond only to selected client machines. .Pp While these enhancements provide better security than stock .Tn NIS , they are by no means 100% effective. It is still possible for someone with access to your network to spoof the server into disclosing the shadow password maps. .Pp On the client side, .Fx Ns 's .Xr getpwent 3 functions will automatically search for the .Pa master.passwd maps and use them if they exist. If they do, they will be used, and all fields in these special maps (class, password age and account expiration) will be decoded. If they are not found, the standard .Pa passwd maps will be used instead. .Sh COMPATIBILITY When using a .No non- Ns Fx .Tn NIS server for .Xr passwd 5 files, it is unlikely that the default MD5-based format that .Fx uses for passwords will be accepted by it. If this is the case, the value of the .Va passwd_format setting in .Xr login.conf 5 should be changed to .Qq Li des for compatibility. .Pp Some systems, such as .Tn SunOS 4.x, need .Tn NIS to be running in order for their hostname resolution functions -.Fn ( gethostbyname , +.Po Fn gethostbyname , .Fn gethostbyaddr , -etc.) to work properly. +etc. +.Pc +to work properly. On these systems, .Xr ypserv 8 performs .Tn DNS lookups when asked to return information about a host that does not exist in its .Pa hosts.byname or .Pa hosts.byaddr maps. .Fx Ns 's resolver uses .Tn DNS by default (it can be made to use .Tn NIS , if desired), therefore its .Tn NIS server does not do .Tn DNS lookups by default. However, .Xr ypserv 8 can be made to perform .Tn DNS lookups if it is started with a special flag. It can also be made to register itself as an .Tn NIS v1 server in order to placate certain systems that insist on the presence of a v1 server -.No ( Fx +.Po Fx uses only .Tn NIS v2, but many other systems, including .Tn SunOS -4.x, search for both a v1 and v2 server when binding). +4.x, search for both a v1 and v2 server when binding +.Pc . .Fx Ns 's .Xr ypserv 8 does not actually handle .Tn NIS v1 requests, but this .Dq "kludge mode" is useful for silencing stubborn systems that search for both a v1 and v2 server. .Pp (Please see the .Xr ypserv 8 manual page for a detailed description of these special features and flags.) .Sh SEE ALSO .Xr domainname 1 , .Xr ypcat 1 , .Xr ypmatch 1 , .Xr ypwhich 1 , .Xr nsswitch.conf 5 , .Xr yp_mkdb 8 , .Xr ypbind 8 , .Xr ypinit 8 , .Xr yppoll 8 , .Xr yppush 8 , .Xr ypserv 8 , .Xr ypset 8 , .Xr ypxfr 8 .Sh HISTORY The .Nm YP subsystem was written from the ground up by .An Theo de Raadt to be compatible to Sun's implementation. Bug fixes, improvements and .Tn NIS server support were later added by .An Bill Paul . The server-side code was originally written by .An Peter Eriksson and .An Tobias Reber and is subject to the GNU Public License. No Sun code was referenced. .Sh BUGS While .Fx now has both .Tn NIS client and server capabilities, it does not yet have support for .Xr ypupdated 8 or the .Fn yp_update function. Both of these require secure .Tn RPC , which .Fx does not support yet either. .Pp The .Xr getservent 3 and .Xr getprotoent 3 functions do not yet have .Tn NIS support. Fortunately, these files do not need to be updated that often. .Pp Many more manual pages should be written, especially .Xr ypclnt 3 . For the time being, seek out a local Sun machine and read the manuals for there. .Pp Neither Sun nor this author have found a clean way to handle the problems that occur when ypbind cannot find its server upon bootup. Index: head/share/man/man9/PCI_IOV_ADD_VF.9 =================================================================== --- head/share/man/man9/PCI_IOV_ADD_VF.9 (revision 286662) +++ head/share/man/man9/PCI_IOV_ADD_VF.9 (revision 286663) @@ -1,112 +1,112 @@ .\" .\" Copyright (c) 2014 Sandvine 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 May 28, 2015 .Dt PCI_IOV_ADD_VF 9 .Os .Sh NAME .Nm PCI_IOV_ADD_VF .Nd inform a PF driver that a VF is being created .Sh SYNOPSIS .In sys/bus.h .In machine/stdarg.h .In sys/nv.h .In dev/pci/pci_iov.h .Ft int .Fn PCI_IOV_ADD_VF "device_t dev" "uint16_t vfnum" "const nvlist_t *vf_config" .Sh DESCRIPTION The .Fn PCI_IOV_ADD_VF method is called by the PCI Single-Root I/O Virtualization .Pq SR-IOV infrastructure when it is initializating a new Virtual Function (VF) as a child of the given Physical Function (PF) device. This method will not be called until a successful call to .Xr PCI_IOV_INIT 9 has been made. It is not guaranteed that this method will be called following a successful call to .Xr PCI_IOV_INIT 9 . If the infrastructure encounters a failure to allocate resources following the call to .Xr PCI_IOV_INIT 9 , the VF creation will be aborted and .Xr PCI_IOV_UNINIT 9 will be called immediately without any preceding calls to .Nm . .Pp The index of the VF being initialized is passed in the .Fa vfnum argument. VFs are always numbered sequentially starting at 0. .Pp If the driver requested device-specific configuration parameters via a VF schema in its call to .Xr pci_iov_attach 9 , those parameters will be contained in the .Pa vf_config argument. All configuration parameters that were either set as required parameters or that had a default value set in the VF schema are guaranteed to be present in .Fa vf_config . Configuration parameters that were neither set as required nor were given a default value are optional and may or may not be present in .Fa vf_config . .Fa vf_config will not contain any configuration parameters that were not specified in the VF schema. All configuration parameters will have the correct type and will be in the range of valid values specified in the schema. .Pp Note that it is possible for the user to set different configuration values on different VF devices that are children of the same PF. The PF driver must not cache configuration parameters passed in previous calls to .Fn PCI_IOV_ADD_VF for other VFs and apply those parameters to the current VF. .Pp This function will not be called twice for the same .Fa vf_num on the same PF device without .Xr PCI_IOV_UNINIT 9 and .Xr PCI_IOV_INIT 9 first being called, in that order. .Sh RETURN VALUES This method returns 0 on success, otherwise an appropriate error is returned. If this method returns an error then the current VF device will be destroyed but the rest of the VF devices will be created and SR-IOV will be enabled on the PF. .Sh SEE ALSO .Xr nv 9 , .Xr pci 9 , -.Xr pci_iov_schema 9 , .Xr PCI_IOV_INIT 9 , +.Xr pci_iov_schema 9 , .Xr PCI_IOV_UNINIT 9 .Sh AUTHORS This manual page was written by .An Ryan Stone Aq Mt rstone@FreeBSD.org . Index: head/share/man/man9/PCI_IOV_INIT.9 =================================================================== --- head/share/man/man9/PCI_IOV_INIT.9 (revision 286662) +++ head/share/man/man9/PCI_IOV_INIT.9 (revision 286663) @@ -1,85 +1,85 @@ .\" .\" Copyright (c) 2014 Sandvine 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 May 28, 2015 .Dt PCI_IOV_INIT 9 .Os .Sh NAME .Nm PCI_IOV_INIT .Nd enable SR-IOV on a PF device .Sh SYNOPSIS .In sys/bus.h .In machine/stdarg.h .In sys/nv.h .In dev/pci/pci_iov.h .Ft int .Fn PCI_IOV_INIT "device_t dev" "uint16_t num_vfs" "const nvlist_t *pf_config" .Sh DESCRIPTION The .Fn PCI_IOV_INIT method is called by the PCI Single-Root I/O Virtualization (SR-IOV) infrastucture when the user requests that SR-IOV be enabled on a Physical Function (PF). The number of Virtual Functions (VFs) that will be created is passed to this method in the .Fa num_vfs argument. .Pp If the driver requested device-specific PF configuration parameters via a PF schema in its call to .Xr pci_iov_attach 9 , those parameters will be available in the .Fa pf_config argument. All configuration parameters that were either set as required parameters or that had a default value set in the PF schema are guaranteed to be present in .Fa pf_config . Configuration parameters that were neither set as required nor were given a default value are optional and may or may not be present in .Fa pf_config . .Fa pf_config will not contain any configuration parameters that were not specified in the PF schema. All configuration parameters will have the correct type and are in the range of valid values specified in the schema. .Pp If this method returns successfully, then this method will not be called again on the same device until after a call to .Xr PCI_IOV_UNINIT . .Sh RETURN VALUES Returns 0 on success, otherwise an appropriate error is returned. If this method returns an error then the SR-IOV configuration will be aborted and no VFs will be created. .Sh SEE ALSO .Xr nv 9 , .Xr pci 9 , -.Xr pci_iov_schema 9 , .Xr PCI_IOV_ADD_VF 9 , +.Xr pci_iov_schema 9 , .Xr PCI_IOV_UNINIT 9 .Sh AUTHORS This manual page was written by .An Ryan Stone Aq Mt rstone@FreeBSD.org . Index: head/share/man/man9/altq.9 =================================================================== --- head/share/man/man9/altq.9 (revision 286662) +++ head/share/man/man9/altq.9 (revision 286663) @@ -1,598 +1,598 @@ .\" $NetBSD: altq.9,v 1.8 2002/05/28 11:41:45 wiz Exp $ .\" $OpenBSD: altq.9,v 1.4 2001/07/12 12:41:42 itojun Exp $ .\" .\" Copyright (C) 2004 Max Laier. All rights reserved. .\" Copyright (C) 2001 .\" Sony Computer Science Laboratories 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 SONY CSL 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 SONY CSL 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 25, 2004 .Dt ALTQ 9 .Os .\" .Sh NAME .Nm ALTQ .Nd kernel interfaces for manipulating output queues on network interfaces .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .In net/if.h .In net/if_var.h .\" .Ss Enqueue macros .Fn IFQ_ENQUEUE "struct ifaltq *ifq" "struct mbuf *m" "int error" .Fn IFQ_HANDOFF "struct ifnet *ifp" "struct mbuf *m" "int error" .Fo IFQ_HANDOFF_ADJ .Fa "struct ifnet *ifp" "struct mbuf *m" "int adjust" "int error" .Fc .\" .Ss Dequeue macros .Fn IFQ_DEQUEUE "struct ifaltq *ifq" "struct mbuf *m" .Fn IFQ_POLL_NOLOCK "struct ifaltq *ifq" "struct mbuf *m" .Fn IFQ_PURGE "struct ifaltq *ifq" .Fn IFQ_IS_EMPTY "struct ifaltq *ifq" .\" .Ss Driver managed dequeue macros .Fn IFQ_DRV_DEQUEUE "struct ifaltq *ifq" "struct mbuf *m" .Fn IFQ_DRV_PREPEND "struct ifaltq *ifq" "struct mbuf *m" .Fn IFQ_DRV_PURGE "struct ifaltq *ifq" .Fn IFQ_DRV_IS_EMPTY "struct ifaltq *ifq" .\" .Ss General setup macros .Fn IFQ_SET_MAXLEN "struct ifaltq *ifq" "int len" .Fn IFQ_INC_LEN "struct ifaltq *ifq" .Fn IFQ_DEC_LEN "struct ifaltq *ifq" .Fn IFQ_INC_DROPS "struct ifaltq *ifq" .Fn IFQ_SET_READY "struct ifaltq *ifq" .Sh DESCRIPTION The .Nm system is a framework to manage queuing disciplines on network interfaces. .Nm introduces new macros to manipulate output queues. The output queue macros are used to abstract queue operations and not to touch the internal fields of the output queue structure. The macros are independent from the .Nm implementation, and compatible with the traditional .Vt ifqueue macros for ease of transition. .Pp .Fn IFQ_ENQUEUE , .Fn IFQ_HANDOFF and .Fn IFQ_HANDOFF_ADJ enqueue a packet .Fa m to the queue .Fa ifq . The underlying queuing discipline may discard the packet. The .Fa error argument is set to 0 on success, or .Er ENOBUFS if the packet is discarded. The packet pointed to by .Fa m will be freed by the device driver on success, or by the queuing discipline on failure, so the caller should not touch .Fa m after enqueuing. .Fn IFQ_HANDOFF and .Fn IFQ_HANDOFF_ADJ combine the enqueue operation with statistic generation and call .Fn if_start upon successful enqueue to initiate the actual send. .Pp .Fn IFQ_DEQUEUE dequeues a packet from the queue. The dequeued packet is returned in .Fa m , or .Fa m is set to .Dv NULL if no packet is dequeued. The caller must always check .Fa m since a non-empty queue could return .Dv NULL under rate-limiting. .Pp .Fn IFQ_POLL_NOLOCK returns the next packet without removing it from the queue. The caller must hold the queue mutex when calling .Fn IFQ_POLL_NOLOCK in order to guarantee that a subsequent call to .Fn IFQ_DEQUEUE_NOLOCK dequeues the same packet. .Pp .Fn IFQ_*_NOLOCK variants (if available) always assume that the caller holds the queue mutex. They can be grabbed with .Fn IFQ_LOCK and released with .Fn IFQ_UNLOCK . .Pp .Fn IFQ_PURGE discards all the packets in the queue. The purge operation is needed since a non-work conserving queue cannot be emptied by a dequeue loop. .Pp .Fn IFQ_IS_EMPTY can be used to check if the queue is empty. Note that .Fn IFQ_DEQUEUE could still return .Dv NULL if the queuing discipline is non-work conserving. .Pp .Fn IFQ_DRV_DEQUEUE moves up to .Fa ifq->ifq_drv_maxlen packets from the queue to the .Dq "driver managed" queue and returns the first one via .Fa m . As for .Fn IFQ_DEQUEUE , .Fa m can be .Dv NULL even for a non-empty queue. Subsequent calls to .Fn IFQ_DRV_DEQUEUE pass the packets from the .Dq "driver managed" queue without obtaining the queue mutex. It is the responsibility of the caller to protect against concurrent access. Enabling .Nm for a given queue sets .Va ifq_drv_maxlen to 0 as the .Dq "bulk dequeue" performed by .Fn IFQ_DRV_DEQUEUE for higher values of .Va ifq_drv_maxlen is adverse to .Nm ALTQ Ns 's internal timing. Note that a driver must not mix .Fn IFQ_DRV_* macros with the default dequeue macros as the default macros do not look at the .Dq "driver managed" queue which might lead to an mbuf leak. .Pp .Fn IFQ_DRV_PREPEND prepends .Fa m to the .Dq "driver managed" queue from where it will be obtained with the next call to .Fn IFQ_DRV_DEQUEUE . .Pp .Fn IFQ_DRV_PURGE flushes all packets in the .Dq "driver managed" queue and calls to .Fn IFQ_PURGE afterwards. .Pp .Fn IFQ_DRV_IS_EMPTY checks for packets in the .Dq "driver managed" part of the queue. If it is empty, it forwards to .Fn IFQ_IS_EMPTY . .Pp .Fn IFQ_SET_MAXLEN sets the queue length limit to the default FIFO queue. The .Va ifq_drv_maxlen member of the .Vt ifaltq structure controls the length limit of the .Dq "driver managed" queue. .Pp .Fn IFQ_INC_LEN and .Fn IFQ_DEC_LEN increment or decrement the current queue length in packets. This is mostly for internal purposes. .Pp .Fn IFQ_INC_DROPS increments the drop counter and is identical to .Fn IF_DROP . It is defined for naming consistency only. .Pp .Fn IFQ_SET_READY sets a flag to indicate that a driver was converted to use the new macros. .Nm can be enabled only on interfaces with this flag. .Sh COMPATIBILITY -.Ss Vt ifaltq Ss structure +.Ss Vt ifaltq structure In order to keep compatibility with the existing code, the new output queue structure .Vt ifaltq has the same fields. The traditional .Fn IF_* macros and the code directly referencing the fields within .Va if_snd still work with .Vt ifaltq . .Bd -literal ##old-style## ##new-style## | struct ifqueue { | struct ifaltq { struct mbuf *ifq_head; | struct mbuf *ifq_head; struct mbuf *ifq_tail; | struct mbuf *ifq_tail; int ifq_len; | int ifq_len; int ifq_maxlen; | int ifq_maxlen; }; | /* driver queue fields */ | ...... | /* altq related fields */ | ...... | }; | .Ed The new structure replaces .Vt "struct ifqueue" in .Vt "struct ifnet" . .Bd -literal ##old-style## ##new-style## | struct ifnet { | struct ifnet { .... | .... | struct ifqueue if_snd; | struct ifaltq if_snd; | .... | .... }; | }; | .Ed The (simplified) new .Fn IFQ_* macros look like: .Bd -literal #define IFQ_DEQUEUE(ifq, m) \e if (ALTQ_IS_ENABLED((ifq)) \e ALTQ_DEQUEUE((ifq), (m)); \e else \e IF_DEQUEUE((ifq), (m)); .Ed .Ss Enqueue operation The semantics of the enqueue operation is changed. In the new style, enqueue and packet drop are combined since they cannot be easily separated in many queuing disciplines. The new enqueue operation corresponds to the following macro that is written with the old macros. .Bd -literal #define IFQ_ENQUEUE(ifq, m, error) \e do { \e if (IF_QFULL((ifq))) { \e m_freem((m)); \e (error) = ENOBUFS; \e IF_DROP(ifq); \e } else { \e IF_ENQUEUE((ifq), (m)); \e (error) = 0; \e } \e } while (0) .Ed .Pp .Fn IFQ_ENQUEUE does the following: .Pp .Bl -hyphen -compact .It queue a packet, .It drop (and free) a packet if the enqueue operation fails. .El .Pp If the enqueue operation fails, .Fa error is set to .Er ENOBUFS . The .Fa m mbuf is freed by the queuing discipline. The caller should not touch mbuf after calling .Fn IFQ_ENQUEUE so that the caller may need to copy .Va m_pkthdr.len or .Va m_flags field beforehand for statistics. .Fn IFQ_HANDOFF and .Fn IFQ_HANDOFF_ADJ can be used if only default interface statistics and an immediate call to .Fn if_start are desired. The caller should not use .Fn senderr since mbuf was already freed. .Pp The new style .Fn if_output looks as follows: .Bd -literal ##old-style## ##new-style## | int | int ether_output(ifp, m0, dst, rt0) | ether_output(ifp, m0, dst, rt0) { | { ...... | ...... | | mflags = m->m_flags; | len = m->m_pkthdr.len; s = splimp(); | s = splimp(); if (IF_QFULL(&ifp->if_snd)) { | IFQ_ENQUEUE(&ifp->if_snd, m, | error); IF_DROP(&ifp->if_snd); | if (error != 0) { splx(s); | splx(s); senderr(ENOBUFS); | return (error); } | } IF_ENQUEUE(&ifp->if_snd, m); | ifp->if_obytes += | ifp->if_obytes += len; m->m_pkthdr.len; | if (m->m_flags & M_MCAST) | if (mflags & M_MCAST) ifp->if_omcasts++; | ifp->if_omcasts++; | if ((ifp->if_flags & IFF_OACTIVE) | if ((ifp->if_flags & IFF_OACTIVE) == 0) | == 0) (*ifp->if_start)(ifp); | (*ifp->if_start)(ifp); splx(s); | splx(s); return (error); | return (error); | bad: | bad: if (m) | if (m) m_freem(m); | m_freem(m); return (error); | return (error); } | } | .Ed .Sh HOW TO CONVERT THE EXISTING DRIVERS First, make sure the corresponding .Fn if_output is already converted to the new style. .Pp Look for .Va if_snd in the driver. Probably, you need to make changes to the lines that include .Va if_snd . .Ss Empty check operation If the code checks .Va ifq_head to see whether the queue is empty or not, use .Fn IFQ_IS_EMPTY . .Bd -literal ##old-style## ##new-style## | if (ifp->if_snd.ifq_head != NULL) | if (!IFQ_IS_EMPTY(&ifp->if_snd)) | .Ed .Fn IFQ_IS_EMPTY only checks if there is any packet stored in the queue. Note that even when .Fn IFQ_IS_EMPTY is .Dv FALSE , .Fn IFQ_DEQUEUE could still return .Dv NULL if the queue is under rate-limiting. .Ss Dequeue operation Replace .Fn IF_DEQUEUE by .Fn IFQ_DEQUEUE . Always check whether the dequeued mbuf is .Dv NULL or not. Note that even when .Fn IFQ_IS_EMPTY is .Dv FALSE , .Fn IFQ_DEQUEUE could return .Dv NULL due to rate-limiting. .Bd -literal ##old-style## ##new-style## | IF_DEQUEUE(&ifp->if_snd, m); | IFQ_DEQUEUE(&ifp->if_snd, m); | if (m == NULL) | return; | .Ed A driver is supposed to call .Fn if_start from transmission complete interrupts in order to trigger the next dequeue. .Ss Poll-and-dequeue operation If the code polls the packet at the head of the queue and actually uses the packet before dequeuing it, use .Fn IFQ_POLL_NOLOCK and .Fn IFQ_DEQUEUE_NOLOCK . .Bd -literal ##old-style## ##new-style## | | IFQ_LOCK(&ifp->if_snd); m = ifp->if_snd.ifq_head; | IFQ_POLL_NOLOCK(&ifp->if_snd, m); if (m != NULL) { | if (m != NULL) { | /* use m to get resources */ | /* use m to get resources */ if (something goes wrong) | if (something goes wrong) | IFQ_UNLOCK(&ifp->if_snd); return; | return; | IF_DEQUEUE(&ifp->if_snd, m); | IFQ_DEQUEUE_NOLOCK(&ifp->if_snd, m); | IFQ_UNLOCK(&ifp->if_snd); | /* kick the hardware */ | /* kick the hardware */ } | } | .Ed It is guaranteed that .Fn IFQ_DEQUEUE_NOLOCK under the same lock as a previous .Fn IFQ_POLL_NOLOCK returns the same packet. Note that they need to be guarded by .Fn IFQ_LOCK . .Ss Eliminating Fn IF_PREPEND If the code uses .Fn IF_PREPEND , you have to eliminate it unless you can use a .Dq "driver managed" queue which allows the use of .Fn IFQ_DRV_PREPEND as a substitute. A common usage of .Fn IF_PREPEND is to cancel the previous dequeue operation. You have to convert the logic into poll-and-dequeue. .Bd -literal ##old-style## ##new-style## | | IFQ_LOCK(&ifp->if_snd); IF_DEQUEUE(&ifp->if_snd, m); | IFQ_POLL_NOLOCK(&ifp->if_snd, m); if (m != NULL) { | if (m != NULL) { | if (something_goes_wrong) { | if (something_goes_wrong) { IF_PREPEND(&ifp->if_snd, m); | IFQ_UNLOCK(&ifp->if_snd); return; | return; } | } | | /* at this point, the driver | * is committed to send this | * packet. | */ | IFQ_DEQUEUE_NOLOCK(&ifp->if_snd, m); | IFQ_UNLOCK(&ifp->if_snd); | /* kick the hardware */ | /* kick the hardware */ } | } | .Ed .Ss Purge operation Use .Fn IFQ_PURGE to empty the queue. Note that a non-work conserving queue cannot be emptied by a dequeue loop. .Bd -literal ##old-style## ##new-style## | while (ifp->if_snd.ifq_head != NULL) {| IFQ_PURGE(&ifp->if_snd); IF_DEQUEUE(&ifp->if_snd, m); | m_freem(m); | } | | .Ed .Ss Conversion using a driver managed queue Convert .Fn IF_* macros to their equivalent .Fn IFQ_DRV_* and employ .Fn IFQ_DRV_IS_EMPTY where appropriate. .Bd -literal ##old-style## ##new-style## | if (ifp->if_snd.ifq_head != NULL) | if (!IFQ_DRV_IS_EMPTY(&ifp->if_snd)) | .Ed Make sure that calls to .Fn IFQ_DRV_DEQUEUE , .Fn IFQ_DRV_PREPEND and .Fn IFQ_DRV_PURGE are protected with a mutex of some kind. .Ss Attach routine Use .Fn IFQ_SET_MAXLEN to set .Va ifq_maxlen to .Fa len . Initialize .Va ifq_drv_maxlen with a sensible value if you plan to use the .Fn IFQ_DRV_* macros. Add .Fn IFQ_SET_READY to show this driver is converted to the new style. (This is used to distinguish new-style drivers.) .Bd -literal ##old-style## ##new-style## | ifp->if_snd.ifq_maxlen = qsize; | IFQ_SET_MAXLEN(&ifp->if_snd, qsize); | ifp->if_snd.ifq_drv_maxlen = qsize; | IFQ_SET_READY(&ifp->if_snd); if_attach(ifp); | if_attach(ifp); | .Ed .Ss Other issues The new macros for statistics: .Bd -literal ##old-style## ##new-style## | IF_DROP(&ifp->if_snd); | IFQ_INC_DROPS(&ifp->if_snd); | ifp->if_snd.ifq_len++; | IFQ_INC_LEN(&ifp->if_snd); | ifp->if_snd.ifq_len--; | IFQ_DEC_LEN(&ifp->if_snd); | .Ed .Sh QUEUING DISCIPLINES Queuing disciplines need to maintain .Fa ifq_len (used by .Fn IFQ_IS_EMPTY ) . Queuing disciplines also need to guarantee that the same mbuf is returned if .Fn IFQ_DEQUEUE is called immediately after .Fn IFQ_POLL . .Sh SEE ALSO .Xr pf 4 , .Xr pf.conf 5 , .Xr pfctl 8 .Sh HISTORY The .Nm system first appeared in March 1997. Index: head/share/man/man9/ifnet.9 =================================================================== --- head/share/man/man9/ifnet.9 (revision 286662) +++ head/share/man/man9/ifnet.9 (revision 286663) @@ -1,1530 +1,1530 @@ .\" -*- Nroff -*- .\" Copyright 1996, 1997 Massachusetts Institute of Technology .\" .\" Permission to use, copy, modify, and distribute this software and .\" its documentation for any purpose and without fee is hereby .\" granted, provided that both the above copyright notice and this .\" permission notice appear in all copies, that both the above .\" copyright notice and this permission notice appear in all .\" supporting documentation, and that the name of M.I.T. not be used .\" in advertising or publicity pertaining to distribution of the .\" software without specific, written prior permission. M.I.T. makes .\" no representations about the suitability of this software for any .\" purpose. It is provided "as is" without express or implied .\" warranty. .\" .\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''. M.I.T. DISCLAIMS .\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE, .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT .\" SHALL M.I.T. 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 29, 2014 .Dt IFNET 9 .Os .Sh NAME .Nm ifnet , .Nm ifaddr , .Nm ifqueue , .Nm if_data .Nd kernel interfaces for manipulating network interfaces .Sh SYNOPSIS .In sys/param.h .In sys/time.h .In sys/socket.h .In net/if.h .In net/if_var.h .In net/if_types.h .\" .Ss "Interface Manipulation Functions" .Ft "struct ifnet *" .Fn if_alloc "u_char type" .Ft void .Fn if_attach "struct ifnet *ifp" .Ft void .Fn if_detach "struct ifnet *ifp" .Ft void .Fn if_free "struct ifnet *ifp" .Ft void .Fn if_free_type "struct ifnet *ifp" "u_char type" .Ft void .Fn if_down "struct ifnet *ifp" .Ft int .Fn ifioctl "struct socket *so" "u_long cmd" "caddr_t data" "struct thread *td" .Ft int .Fn ifpromisc "struct ifnet *ifp" "int pswitch" .Ft int .Fn if_allmulti "struct ifnet *ifp" "int amswitch" .Ft "struct ifnet *" .Fn ifunit "const char *name" .Ft "struct ifnet *" .Fn ifunit_ref "const char *name" .Ft void .Fn if_up "struct ifnet *ifp" .\" .Ss "Interface Address Functions" .Ft "struct ifaddr *" .Fn ifaddr_byindex "u_short idx" .Ft "struct ifaddr *" .Fn ifa_ifwithaddr "struct sockaddr *addr" .Ft "struct ifaddr *" .Fn ifa_ifwithdstaddr "struct sockaddr *addr" "int fib" .Ft "struct ifaddr *" .Fn ifa_ifwithnet "struct sockaddr *addr" "int ignore_ptp" "int fib" .Ft "struct ifaddr *" .Fn ifaof_ifpforaddr "struct sockaddr *addr" "struct ifnet *ifp" .Ft void .Fn ifa_ref "struct ifaddr *ifa" .Ft void .Fn ifa_free "struct ifaddr *ifa" .\" .Ss "Interface Multicast Address Functions" .Ft int .Fn if_addmulti "struct ifnet *ifp" "struct sockaddr *sa" "struct ifmultiaddr **ifmap" .Ft int .Fn if_delmulti "struct ifnet *ifp" "struct sockaddr *sa" .Ft "struct ifmultiaddr *" .Fn if_findmulti "struct ifnet *ifp" "struct sockaddr *sa" .Ss "Output queue macros" .Fn IF_DEQUEUE "struct ifqueue *ifq" "struct mbuf *m" .\" .Ss "struct ifnet Member Functions" .Ft void .Fn \*(lp*if_input\*(rp "struct ifnet *ifp" "struct mbuf *m" .Ft int .Fo \*(lp*if_output\*(rp .Fa "struct ifnet *ifp" "struct mbuf *m" .Fa "const struct sockaddr *dst" "struct route *ro" .Fc .Ft void .Fn \*(lp*if_start\*(rp "struct ifnet *ifp" .Ft int .Fn \*(lp*if_transmit\*(rp "struct ifnet *ifp" "struct mbuf *m" .Ft void .Fn \*(lp*if_qflush\*(rp "struct ifnet *ifp" .Ft int .Fn \*(lp*if_ioctl\*(rp "struct ifnet *ifp" "u_long cmd" "caddr_t data" .Ft void .Fn \*(lp*if_init\*(rp "void *if_softc" .Ft int .Fo \*(lp*if_resolvemulti\*(rp .Fa "struct ifnet *ifp" "struct sockaddr **retsa" "struct sockaddr *addr" .Fc .Ss "struct ifaddr member function" .Ft void .Fo \*(lp*ifa_rtrequest\*(rp .Fa "int cmd" "struct rtentry *rt" "struct rt_addrinfo *info" .Fc .\" .Ss "Global Variables" .Vt extern struct ifnethead ifnet ; .\" extern struct ifindex_entry *ifindex_table ; .Vt extern int if_index ; .Vt extern int ifqmaxlen ; .Sh DATA STRUCTURES The kernel mechanisms for handling network interfaces reside primarily in the .Vt ifnet , if_data , ifaddr , and .Vt ifmultiaddr structures in .In net/if.h and .In net/if_var.h and the functions named above and defined in .Pa /sys/net/if.c . Those interfaces which are intended to be used by user programs are defined in .In net/if.h ; these include the interface flags, the .Vt if_data structure, and the structures defining the appearance of interface-related messages on the .Xr route 4 routing socket and in .Xr sysctl 3 . The header file .In net/if_var.h defines the kernel-internal interfaces, including the .Vt ifnet , ifaddr , and .Vt ifmultiaddr structures and the functions which manipulate them. (A few user programs will need .In net/if_var.h because it is the prerequisite of some other header file like .In netinet/if_ether.h . Most references to those two files in particular can be replaced by .In net/ethernet.h . ) .Pp The system keeps a linked list of interfaces using the .Li TAILQ macros defined in .Xr queue 3 ; this list is headed by a .Vt "struct ifnethead" called .Va ifnet . The elements of this list are of type .Vt "struct ifnet" , and most kernel routines which manipulate interface as such accept or return pointers to these structures. Each interface structure contains an .Vt if_data structure used for statistics and information. Each interface also has a .Li TAILQ of interface addresses, described by .Vt ifaddr structures. An .Dv AF_LINK address (see .Xr link_addr 3 ) describing the link layer implemented by the interface (if any) is accessed by the .Fn ifaddr_byindex function or .Va if_addr structure. (Some trivial interfaces do not provide any link layer addresses; this structure, while still present, serves only to identify the interface name and index.) .Pp Finally, those interfaces supporting reception of multicast datagrams have a .Li TAILQ of multicast group memberships, described by .Vt ifmultiaddr structures. These memberships are reference-counted. .Pp Interfaces are also associated with an output queue, defined as a .Vt "struct ifqueue" ; this structure is used to hold packets while the interface is in the process of sending another. .Pp -.Ss The Vt ifnet Ss structure +.Ss The ifnet Structure The fields of .Vt "struct ifnet" are as follows: .Bl -tag -width ".Va if_capabilities" -offset indent .It Va if_softc .Pq Vt "void *" A pointer to the driver's private state block. (Initialized by driver.) .It Va if_l2com .Pq Vt "void *" A pointer to the common data for the interface's layer 2 protocol. (Initialized by .Fn if_alloc . ) .It Va if_vnet .Pq Vt "struct vnet *" A pointer to the virtual network stack instance. (Initialized by .Fn if_attach . ) .It Va if_home_vnet .Pq Vt "struct vnet *" A pointer to the parent virtual network stack, where this .Vt "struct ifnet" originates from. (Initialized by .Fn if_attach . ) .It Va if_link .Pq Fn TAILQ_ENTRY ifnet .Xr queue 3 macro glue. .It Va if_xname .Pq Vt "char *" The name of the interface, (e.g., .Dq Li fxp0 or .Dq Li lo0 ) . (Initialized by driver (usually via .Fn if_initname ) . ) .It Va if_dname .Pq Vt "const char *" The name of the driver. (Initialized by driver (usually via .Fn if_initname ) . ) .It Va if_dunit .Pq Vt int A unique number assigned to each interface managed by a particular driver. Drivers may choose to set this to .Dv IF_DUNIT_NONE if a unit number is not associated with the device. (Initialized by driver (usually via .Fn if_initname ) . ) .It Va if_refcount .Pq Vt u_int The reference count. (Initialized by .Fn if_alloc . ) .It Va if_addrhead .Pq Vt "struct ifaddrhead" The head of the .Xr queue 3 .Li TAILQ containing the list of addresses assigned to this interface. .It Va if_pcount .Pq Vt int A count of promiscuous listeners on this interface, used to reference-count the .Dv IFF_PROMISC flag. .It Va if_carp .Pq Vt "struct carp_if *" A pointer to the CARP interface structure, .Xr carp 4 . (Initialized by the driver-specific .Fn if_ioctl routine.) .It Va if_bpf .Pq Vt "struct bpf_if *" Opaque per-interface data for the packet filter, .Xr bpf 4 . (Initialized by .Fn bpf_attach . ) .It Va if_index .Pq Vt u_short A unique number assigned to each interface in sequence as it is attached. This number can be used in a .Vt "struct sockaddr_dl" to refer to a particular interface by index (see .Xr link_addr 3 ) . (Initialized by .Fn if_alloc . ) .It Va if_vlantrunk .Pq Vt struct ifvlantrunk * A pointer to 802.1Q trunk structure, .Xr vlan 4 . (Initialized by the driver-specific .Fn if_ioctl routine.) .It Va if_flags .Pq Vt int Flags describing operational parameters of this interface (see below). (Manipulated by generic code.) .It Va if_drv_flags .Pq Vt int Flags describing operational status of this interface (see below). (Manipulated by driver.) .It Va if_capabilities .Pq Vt int Flags describing the capabilities the interface supports (see below). .It Va if_capenable .Pq Vt int Flags describing the enabled capabilities of the interface (see below). .It Va if_linkmib .Pq Vt "void *" A pointer to an interface-specific MIB structure exported by .Xr ifmib 4 . (Initialized by driver.) .It Va if_linkmiblen .Pq Vt size_t The size of said structure. (Initialized by driver.) .It Va if_data .Pq Vt "struct if_data" More statistics and information; see .Sx "The if_data structure" , below. (Initialized by driver, manipulated by both driver and generic code.) .It Va if_multiaddrs .Pq Vt struct ifmultihead The head of the .Xr queue 3 .Li TAILQ containing the list of multicast addresses assigned to this interface. .It Va if_amcount .Pq Vt int A number of multicast requests on this interface, used to reference-count the .Dv IFF_ALLMULTI flag. .It Va if_addr .Pq Vt "struct ifaddr *" A pointer to the link-level interface address. (Initialized by .Fn if_alloc . ) .\" .It Va if_llsoftc .\" .Pq Vt "void *" .\" The purpose of the field is unclear. .It Va if_snd .Pq Vt "struct ifaltq" The output queue. (Manipulated by driver.) .It Va if_broadcastaddr .Pq Vt "const u_int8_t *" A link-level broadcast bytestring for protocols with variable address length. .It Va if_bridge .Pq Vt "void *" A pointer to the bridge interface structure, .Xr if_bridge 4 . (Initialized by the driver-specific .Fn if_ioctl routine.) .It Va if_label .Pq Vt "struct label *" A pointer to the MAC Framework label structure, .Xr mac 4 . (Initialized by .Fn if_alloc . ) .It Va if_afdata .Pq Vt "void *" An address family dependent data region. .It Va if_afdata_initialized .Pq Vt int Used to track the current state of address family initialization. .It Va if_afdata_lock .Pq Vt "struct rwlock" An .Xr rwlock 9 lock used to protect .Va if_afdata internals. .It Va if_linktask .Pq Vt "struct task" A .Xr taskqueue 9 task scheduled for link state change events of the interface. .It Va if_addr_lock .Pq Vt "struct rwlock" An .Xr rwlock 9 lock used to protect interface-related address lists. .It Va if_clones .Pq Fn LIST_ENTRY ifnet .Xr queue 3 macro glue for the list of clonable network interfaces. .It Va if_groups .Pq Fn TAILQ_HEAD "" "ifg_list" The head of the .Xr queue 3 .Li TAILQ containing the list of groups per interface. .It Va if_pf_kif .Pq Vt "void *" A pointer to the structure used for interface abstraction by .Xr pf 4 . .It Va if_lagg .Pq Vt "void *" A pointer to the .Xr lagg 4 interface structure. .It Va if_alloctype .Pq Vt u_char The type of the interface as it was at the time of its allocation. It is used to cache the type passed to .Fn if_alloc , but unlike .Va if_type , it would not be changed by drivers. .El .Pp References to .Vt ifnet structures are gained by calling the .Fn if_ref function and released by calling the .Fn if_rele function. They are used to allow kernel code walking global interface lists to release the .Vt ifnet lock yet keep the .Vt ifnet structure stable. .Pp There are in addition a number of function pointers which the driver must initialize to complete its interface with the generic interface layer: .Bl -ohang -offset indent .It Fn if_input Pass a packet to an appropriate upper layer as determined from the link-layer header of the packet. This routine is to be called from an interrupt handler or used to emulate reception of a packet on this interface. A single function implementing .Fn if_input can be shared among multiple drivers utilizing the same link-layer framing, e.g., Ethernet. .It Fn if_output Output a packet on interface .Fa ifp , or queue it on the output queue if the interface is already active. .It Fn if_transmit Transmit a packet on an interface or queue it if the interface is in use. This function will return .Dv ENOBUFS if the devices software and hardware queues are both full. This function must be installed after .Fn if_attach to override the default implementation. This function is exposed in order to allow drivers to manage their own queues and to reduce the latency caused by a frequently gratuitous enqueue / dequeue pair to ifq. The suggested internal software queueing mechanism is buf_ring. .It Fn if_qflush Free mbufs in internally managed queues when the interface is marked down. This function must be installed after .Fn if_attach to override the default implementation. This function is exposed in order to allow drivers to manage their own queues and to reduce the latency caused by a frequently gratuitous enqueue / dequeue pair to ifq. The suggested internal software queueing mechanism is buf_ring. .It Fn if_start Start queued output on an interface. This function is exposed in order to provide for some interface classes to share a .Fn if_output among all drivers. .Fn if_start may only be called when the .Dv IFF_DRV_OACTIVE flag is not set. (Thus, .Dv IFF_DRV_OACTIVE does not literally mean that output is active, but rather that the device's internal output queue is full.) Please note that this function will soon be deprecated. .It Fn if_ioctl Process interface-related .Xr ioctl 2 requests (defined in .In sys/sockio.h ) . Preliminary processing is done by the generic routine .Fn ifioctl to check for appropriate privileges, locate the interface being manipulated, and perform certain generic operations like twiddling flags and flushing queues. See the description of .Fn ifioctl below for more information. .It Fn if_init Initialize and bring up the hardware, e.g., reset the chip and enable the receiver unit. Should mark the interface running, but not active .Dv ( IFF_DRV_RUNNING , ~IIF_DRV_OACTIVE ) . .It Fn if_resolvemulti Check the requested multicast group membership, .Fa addr , for validity, and if necessary compute a link-layer group which corresponds to that address which is returned in .Fa *retsa . Returns zero on success, or an error code on failure. .El .Ss "Interface Flags" Interface flags are used for a number of different purposes. Some flags simply indicate information about the type of interface and its capabilities; others are dynamically manipulated to reflect the current state of the interface. Flags of the former kind are marked .Aq S in this table; the latter are marked .Aq D . Flags which begin with .Dq IFF_DRV_ are stored in .Va if_drv_flags ; all other flags are stored in .Va if_flags . .Pp The macro .Dv IFF_CANTCHANGE defines the bits which cannot be set by a user program using the .Dv SIOCSIFFLAGS command to .Xr ioctl 2 ; these are indicated by an asterisk .Pq Ql * in the following listing. .Pp .Bl -tag -width ".Dv IFF_POINTOPOINT" -offset indent -compact .It Dv IFF_UP .Aq D The interface has been configured up by the user-level code. .It Dv IFF_BROADCAST .Aq S* The interface supports broadcast. .It Dv IFF_DEBUG .Aq D Used to enable/disable driver debugging code. .It Dv IFF_LOOPBACK .Aq S The interface is a loopback device. .It Dv IFF_POINTOPOINT .Aq S* The interface is point-to-point; .Dq broadcast address is actually the address of the other end. .It Dv IFF_DRV_RUNNING .Aq D* The interface has been configured and dynamic resources were successfully allocated. Probably only useful internal to the interface. .It Dv IFF_NOARP .Aq D Disable network address resolution on this interface. .It Dv IFF_PROMISC .Aq D* This interface is in promiscuous mode. .It Dv IFF_PPROMISC .Aq D This interface is in the permanently promiscuous mode (implies .Dv IFF_PROMISC ) . .It Dv IFF_ALLMULTI .Aq D* This interface is in all-multicasts mode (used by multicast routers). .It Dv IFF_DRV_OACTIVE .Aq D* The interface's hardware output queue (if any) is full; output packets are to be queued. .It Dv IFF_SIMPLEX .Aq S* The interface cannot hear its own transmissions. .It Dv IFF_LINK0 .It Dv IFF_LINK1 .It Dv IFF_LINK2 .Aq D Control flags for the link layer. (Currently abused to select among multiple physical layers on some devices.) .It Dv IFF_MULTICAST .Aq S* This interface supports multicast. .It Dv IFF_CANTCONFIG .Aq S* The interface is not configurable in a meaningful way. Primarily useful for .Dv IFT_USB interfaces registered at the interface list. .It Dv IFF_MONITOR .Aq D This interface blocks transmission of packets and discards incoming packets after BPF processing. Used to monitor network traffic but not interact with the network in question. .It Dv IFF_STATICARP .Aq D Used to enable/disable ARP requests on this interface. .It Dv IFF_DYING .Aq D* Set when the .Vt ifnet structure of this interface is being released and still has .Va if_refcount references. .It Dv IFF_RENAMING .Aq D* Set when this interface is being renamed. .El .Ss "Interface Capabilities Flags" Interface capabilities are specialized features an interface may or may not support. These capabilities are very hardware-specific and allow, when enabled, to offload specific network processing to the interface or to offer a particular feature for use by other kernel parts. .Pp It should be stressed that a capability can be completely uncontrolled (i.e., stay always enabled with no way to disable it) or allow limited control over itself (e.g., depend on another capability's state.) Such peculiarities are determined solely by the hardware and driver of a particular interface. Only the driver possesses the knowledge on whether and how the interface capabilities can be controlled. Consequently, capabilities flags in .Va if_capenable should never be modified directly by kernel code other than the interface driver. The command .Dv SIOCSIFCAP to .Fn ifioctl is the dedicated means to attempt altering .Va if_capenable on an interface. Userland code shall use .Xr ioctl 2 . .Pp The following capabilities are currently supported by the system: .Bl -tag -width ".Dv IFCAP_POLLING_NOCOUNT" -offset indent .It Dv IFCAP_RXCSUM This interface can do checksum validation on receiving data. Some interfaces do not have sufficient buffer storage to store frames above a certain MTU-size completely. The driver for the interface might disable hardware checksum validation if the MTU is set above the hardcoded limit. .It Dv IFCAP_TXCSUM This interface can do checksum calculation on transmitting data. .It Dv IFCAP_HWCSUM A shorthand for .Pq Dv IFCAP_RXCSUM | IFCAP_TXCSUM . .It Dv IFCAP_NETCONS This interface can be a network console. .It Dv IFCAP_VLAN_MTU The .Xr vlan 4 driver can operate over this interface in software tagging mode without having to decrease MTU on .Xr vlan 4 interfaces below 1500 bytes. This implies the ability of this interface to cope with frames somewhat longer than permitted by the Ethernet specification. .It Dv IFCAP_VLAN_HWTAGGING This interface can do VLAN tagging on output and demultiplex frames by their VLAN tag on input. .It Dv IFCAP_JUMBO_MTU This Ethernet interface can transmit and receive frames up to 9000 bytes long. .It Dv IFCAP_POLLING This interface supports .Xr polling 4 . See below for details. .It Dv IFCAP_VLAN_HWCSUM This interface can do checksum calculation on both transmitting and receiving data on .Xr vlan 4 interfaces (implies .Dv IFCAP_HWCSUM ) . .It Dv IFCAP_TSO4 This Ethernet interface supports TCP4 Segmentation offloading. .It Dv IFCAP_TSO6 This Ethernet interface supports TCP6 Segmentation offloading. .It Dv IFCAP_TSO A shorthand for .Pq Dv IFCAP_TSO4 | IFCAP_TSO6 . .It Dv IFCAP_TOE4 This Ethernet interface supports TCP offloading. .It Dv IFCAP_TOE6 This Ethernet interface supports TCP6 offloading. .It Dv IFCAP_TOE A shorthand for .Pq Dv IFCAP_TOE4 | IFCAP_TOE6 . .It Dv IFCAP_WOL_UCAST This Ethernet interface supports waking up on any Unicast packet. .It Dv IFCAP_WOL_MCAST This Ethernet interface supports waking up on any Multicast packet. .It Dv IFCAP_WOL_MAGIC This Ethernet interface supports waking up on any Magic packet such as those sent by .Xr wake 8 . .It Dv IFCAP_WOL A shorthand for .Pq Dv IFCAP_WOL_UCAST | IFCAP_WOL_MCAST | IFCAP_WOL_MAGIC . .It Dv IFCAP_TOE4 This Ethernet interface supports TCP4 Offload Engine. .It Dv IFCAP_TOE6 This Ethernet interface supports TCP6 Offload Engine. .It Dv IFCAP_TOE A shorthand for .Pq Dv IFCAP_TOE4 | IFCAP_TOE6 . .It Dv IFCAP_VLAN_HWFILTER This interface supports frame filtering in hardware on .Xr vlan 4 interfaces. .It Dv IFCAP_POLLING_NOCOUNT The return value for the number of processed packets should be skipped for this interface. .It Dv IFCAP_VLAN_HWTSO This interface supports TCP Segmentation offloading on .Xr vlan 4 interfaces (implies .Dv IFCAP_TSO ) . .It Dv IFCAP_LINKSTATE This Ethernet interface supports dynamic link state changes. .El .Pp The ability of advanced network interfaces to offload certain computational tasks from the host CPU to the board is limited mostly to TCP/IP. Therefore a separate field associated with an interface (see .Va ifnet.if_data.ifi_hwassist below) keeps a detailed description of its enabled capabilities specific to TCP/IP processing. The TCP/IP module consults the field to see which tasks can be done on an .Em outgoing packet by the interface. The flags defined for that field are a superset of those for .Va mbuf.m_pkthdr.csum_flags , namely: .Bl -tag -width ".Dv CSUM_FRAGMENT" -offset indent .It Dv CSUM_IP The interface will compute IP checksums. .It Dv CSUM_TCP The interface will compute TCP checksums. .It Dv CSUM_UDP The interface will compute UDP checksums. .It Dv CSUM_IP_FRAGS The interface can compute a TCP or UDP checksum for a packet fragmented by the host CPU. Makes sense only along with .Dv CSUM_TCP or .Dv CSUM_UDP . .It Dv CSUM_FRAGMENT The interface will do the fragmentation of IP packets if necessary. The host CPU does not need to care about MTU on this interface as long as a packet to transmit through it is an IP one and it does not exceed the size of the hardware buffer. .El .Pp An interface notifies the TCP/IP module about the tasks the former has performed on an .Em incoming packet by setting the corresponding flags in the field .Va mbuf.m_pkthdr.csum_flags of the .Vt mbuf chain containing the packet. See .Xr mbuf 9 for details. .Pp The capability of a network interface to operate in .Xr polling 4 mode involves several flags in different global variables and per-interface fields. The capability flag .Dv IFCAP_POLLING set in interface's .Va if_capabilities indicates support for .Xr polling 4 on the particular interface. If set in .Va if_capabilities , the same flag can be marked or cleared in the interface's .Va if_capenable within .Fn ifioctl , thus initiating switch of the interface to .Xr polling 4 mode or interrupt mode, respectively. The actual mode change is managed by the driver-specific .Fn if_ioctl routine. The .Xr polling handler returns the number of packets processed. -.Ss The Vt if_data Ss Structure +.Ss The if_data Structure The .Vt if_data structure contains statistics and identifying information used by management programs, and which is exported to user programs by way of the .Xr ifmib 4 branch of the .Xr sysctl 3 MIB. The following elements of the .Vt if_data structure are initialized by the interface and are not expected to change significantly over the course of normal operation: .Bl -tag -width ".Va ifi_lastchange" -offset indent .It Va ifi_type .Pq Vt u_char The type of the interface, as defined in .In net/if_types.h and described below in the .Sx "Interface Types" section. .It Va ifi_physical .Pq Vt u_char Intended to represent a selection of physical layers on devices which support more than one; never implemented. .It Va ifi_addrlen .Pq Vt u_char Length of a link-layer address on this device, or zero if there are none. Used to initialized the address length field in .Vt sockaddr_dl structures referring to this interface. .It Va ifi_hdrlen .Pq Vt u_char Maximum length of any link-layer header which might be prepended by the driver to a packet before transmission. The generic code computes the maximum over all interfaces and uses that value to influence the placement of data in .Vt mbuf Ns s to attempt to ensure that there is always sufficient space to prepend a link-layer header without allocating an additional .Vt mbuf . .It Va ifi_datalen .Pq Vt u_char Length of the .Vt if_data structure. Allows some stabilization of the routing socket ABI in the face of increases in the length of .Vt struct ifdata . .It Va ifi_mtu .Pq Vt u_long The maximum transmission unit of the medium, exclusive of any link-layer overhead. .It Va ifi_metric .Pq Vt u_long A dimensionless metric interpreted by a user-mode routing process. .It Va ifi_baudrate .Pq Vt u_long The line rate of the interface, in bits per second. .It Va ifi_hwassist .Pq Vt u_long A detailed interpretation of the capabilities to offload computational tasks for .Em outgoing packets. The interface driver must keep this field in accord with the current value of .Va if_capenable . .It Va ifi_epoch .Pq Vt time_t The system uptime when interface was attached or the statistics below were reset. This is intended to be used to set the SNMP variable .Va ifCounterDiscontinuityTime . It may also be used to determine if two successive queries for an interface of the same index have returned results for the same interface. .El .Pp The structure additionally contains generic statistics applicable to a variety of different interface types (except as noted, all members are of type .Vt u_long ) : .Bl -tag -width ".Va ifi_lastchange" -offset indent .It Va ifi_link_state .Pq Vt u_char The current link state of Ethernet interfaces. See the .Sx Interface Link States section for possible values. .It Va ifi_ipackets Number of packets received. .It Va ifi_ierrors Number of receive errors detected (e.g., FCS errors, DMA overruns, etc.). More detailed breakdowns can often be had by way of a link-specific MIB. .It Va ifi_opackets Number of packets transmitted. .It Va ifi_oerrors Number of output errors detected (e.g., late collisions, DMA overruns, etc.). More detailed breakdowns can often be had by way of a link-specific MIB. .It Va ifi_collisions Total number of collisions detected on output for CSMA interfaces. (This member is sometimes [ab]used by other types of interfaces for other output error counts.) .It Va ifi_ibytes Total traffic received, in bytes. .It Va ifi_obytes Total traffic transmitted, in bytes. .It Va ifi_imcasts Number of packets received which were sent by link-layer multicast. .It Va ifi_omcasts Number of packets sent by link-layer multicast. .It Va ifi_iqdrops Number of packets dropped on input. Rarely implemented. .It Va ifi_noproto Number of packets received for unknown network-layer protocol. .It Va ifi_lastchange .Pq Vt "struct timeval" The time of the last administrative change to the interface (as required for .Tn SNMP ) . .El .Ss Interface Types The header file .In net/if_types.h defines symbolic constants for a number of different types of interfaces. The most common are: .Pp .Bl -tag -offset indent -width ".Dv IFT_PROPVIRTUAL" -compact .It Dv IFT_OTHER none of the following .It Dv IFT_ETHER Ethernet .It Dv IFT_ISO88023 ISO 8802-3 CSMA/CD .It Dv IFT_ISO88024 ISO 8802-4 Token Bus .It Dv IFT_ISO88025 ISO 8802-5 Token Ring .It Dv IFT_ISO88026 ISO 8802-6 DQDB MAN .It Dv IFT_FDDI FDDI .It Dv IFT_PPP Internet Point-to-Point Protocol .Pq Xr ppp 8 .It Dv IFT_LOOP The loopback .Pq Xr lo 4 interface .It Dv IFT_SLIP Serial Line IP .It Dv IFT_PARA Parallel-port IP .Pq Dq Tn PLIP .It Dv IFT_ATM Asynchronous Transfer Mode .It Dv IFT_USB USB Interface .El .Ss Interface Link States The following link states are currently defined: .Pp .Bl -tag -offset indent -width ".Dv LINK_STATE_UNKNOWN" -compact .It Dv LINK_STATE_UNKNOWN The link is in an invalid or unknown state. .It Dv LINK_STATE_DOWN The link is down. .It Dv LINK_STATE_UP The link is up. .El -.Ss The Vt ifaddr Ss Structure +.Ss The ifaddr Structure Every interface is associated with a list (or, rather, a .Li TAILQ ) of addresses, rooted at the interface structure's .Va if_addrlist member. The first element in this list is always an .Dv AF_LINK address representing the interface itself; multi-access network drivers should complete this structure by filling in their link-layer addresses after calling .Fn if_attach . Other members of the structure represent network-layer addresses which have been configured by means of the .Dv SIOCAIFADDR command to .Xr ioctl 2 , called on a socket of the appropriate protocol family. The elements of this list consist of .Vt ifaddr structures. Most protocols will declare their own protocol-specific interface address structures, but all begin with a .Vt "struct ifaddr" which provides the most-commonly-needed functionality across all protocols. Interface addresses are reference-counted. .Pp The members of .Vt "struct ifaddr" are as follows: .Bl -tag -width ".Va ifa_rtrequest" -offset indent .It Va ifa_addr .Pq Vt "struct sockaddr *" The local address of the interface. .It Va ifa_dstaddr .Pq Vt "struct sockaddr *" The remote address of point-to-point interfaces, and the broadcast address of broadcast interfaces. .Va ( ifa_broadaddr is a macro for .Va ifa_dstaddr . ) .It Va ifa_netmask .Pq Vt "struct sockaddr *" The network mask for multi-access interfaces, and the confusion generator for point-to-point interfaces. .It Va ifa_ifp .Pq Vt "struct ifnet *" A link back to the interface structure. .It Va ifa_link .Pq Fn TAILQ_ENTRY ifaddr .Xr queue 3 glue for list of addresses on each interface. .It Va ifa_rtrequest See below. .It Va ifa_flags .Pq Vt u_short Some of the flags which would be used for a route representing this address in the route table. .It Va ifa_refcnt .Pq Vt short The reference count. .El .Pp References to .Vt ifaddr structures are gained by calling the .Fn ifa_ref function and released by calling the .Fn ifa_free function. .Pp .Fn ifa_rtrequest is a pointer to a function which receives callouts from the routing code .Pq Fn rtrequest to perform link-layer-specific actions upon requests to add, or delete routes. The .Fa cmd argument indicates the request in question: .Dv RTM_ADD , or .Dv RTM_DELETE . The .Fa rt argument is the route in question; the .Fa info argument contains the specific destination being manipulated. .Sh FUNCTIONS The functions provided by the generic interface code can be divided into two groups: those which manipulate interfaces, and those which manipulate interface addresses. In addition to these functions, there may also be link-layer support routines which are used by a number of drivers implementing a specific link layer over different hardware; see the documentation for that link layer for more details. -.Ss The Vt ifmultiaddr Ss Structure +.Ss The ifmultiaddr Structure Every multicast-capable interface is associated with a list of multicast group memberships, which indicate at a low level which link-layer multicast addresses (if any) should be accepted, and at a high level, in which network-layer multicast groups a user process has expressed interest. .Pp The elements of the structure are as follows: .Bl -tag -width ".Va ifma_refcount" -offset indent .It Va ifma_link .Pq Fn LIST_ENTRY ifmultiaddr .Xr queue 3 macro glue. .It Va ifma_addr .Pq Vt "struct sockaddr *" A pointer to the address which this record represents. The memberships for various address families are stored in arbitrary order. .It Va ifma_lladdr .Pq Vt "struct sockaddr *" A pointer to the link-layer multicast address, if any, to which the network-layer multicast address in .Va ifma_addr is mapped, else a null pointer. If this element is non-nil, this membership also holds an invisible reference to another membership for that link-layer address. .It Va ifma_refcount .Pq Vt u_int A reference count of requests for this particular membership. .El .Ss Interface Manipulation Functions .Bl -ohang -offset indent .It Fn if_alloc Allocate and initialize .Vt "struct ifnet" . Initialization includes the allocation of an interface index and may include the allocation of a .Fa type specific structure in .Va if_l2com . .It Fn if_attach Link the specified interface .Fa ifp into the list of network interfaces. Also initialize the list of addresses on that interface, and create a link-layer .Vt ifaddr structure to be the first element in that list. (A pointer to this address structure is saved in the .Vt ifnet structure and is accessed by the .Fn ifaddr_byindex function.) The .Fa ifp must have been allocated by .Fn if_alloc . .It Fn if_detach Shut down and unlink the specified .Fa ifp from the interface list. .It Fn if_free Free the given .Fa ifp back to the system. The interface must have been previously detached if it was ever attached. .It Fn if_free_type Identical to .Fn if_free except that the given .Fa type is used to free .Va if_l2com instead of the type in .Va if_type . This is intended for use with drivers that change their interface type. .It Fn if_down Mark the interface .Fa ifp as down (i.e., .Dv IFF_UP is not set), flush its output queue, notify protocols of the transition, and generate a message from the .Xr route 4 routing socket. .It Fn if_up Mark the interface .Fa ifp as up, notify protocols of the transition, and generate a message from the .Xr route 4 routing socket. .It Fn ifpromisc Add or remove a promiscuous reference to .Fa ifp . If .Fa pswitch is true, add a reference; if it is false, remove a reference. On reference count transitions from zero to one and one to zero, set the .Dv IFF_PROMISC flag appropriately and call .Fn if_ioctl to set up the interface in the desired mode. .It Fn if_allmulti As .Fn ifpromisc , but for the all-multicasts .Pq Dv IFF_ALLMULTI flag instead of the promiscuous flag. .It Fn ifunit Return an .Vt ifnet pointer for the interface named .Fa name . .It Fn ifunit_ref Return a reference-counted (via .Fn ifa_ref ) .Vt ifnet pointer for the interface named .Fa name . This is the preferred function over .Fn ifunit . The caller is responsible for releasing the reference with .Fn if_rele when it is finished with the ifnet. .It Fn ifioctl Process the ioctl request .Fa cmd , issued on socket .Fa so by thread .Fa td , with data parameter .Fa data . This is the main routine for handling all interface configuration requests from user mode. It is ordinarily only called from the socket-layer .Xr ioctl 2 handler, and only for commands with class .Sq Li i . Any unrecognized commands will be passed down to socket .Fa so Ns 's protocol for further interpretation. The following commands are handled by .Fn ifioctl : .Pp .Bl -tag -width ".Dv SIOCGIFNETMASK" -offset indent -compact .It Dv SIOCGIFCONF Get interface configuration. (No call-down to driver.) .Pp .It Dv SIOCSIFNAME Set the interface name. .Dv RTM_IFANNOUNCE departure and arrival messages are sent so that routing code that relies on the interface name will update its interface list. Caller must have appropriate privilege. (No call-down to driver.) .It Dv SIOCGIFCAP .It Dv SIOCGIFFIB .It Dv SIOCGIFFLAGS .It Dv SIOCGIFMETRIC .It Dv SIOCGIFMTU .It Dv SIOCGIFPHYS Get interface capabilities, FIB, flags, metric, MTU, medium selection. (No call-down to driver.) .Pp .It Dv SIOCSIFCAP Enable or disable interface capabilities. Caller must have appropriate privilege. Before a call to the driver-specific .Fn if_ioctl routine, the requested mask for enabled capabilities is checked against the mask of capabilities supported by the interface, .Va if_capabilities . Requesting to enable an unsupported capability is invalid. The rest is supposed to be done by the driver, which includes updating .Va if_capenable and .Va if_data.ifi_hwassist appropriately. .Pp .It Dv SIOCSIFFIB Sets interface FIB. Caller must have appropriate privilege. FIB values start at 0 and values greater or equals than .Va net.fibs are considered invalid. .It Dv SIOCSIFFLAGS Change interface flags. Caller must have appropriate privilege. If a change to the .Dv IFF_UP flag is requested, .Fn if_up or .Fn if_down is called as appropriate. Flags listed in .Dv IFF_CANTCHANGE are masked off, and the field .Va if_flags in the interface structure is updated. Finally, the driver .Fn if_ioctl routine is called to perform any setup requested. .Pp .It Dv SIOCSIFMETRIC .It Dv SIOCSIFPHYS Change interface metric or medium. Caller must have appropriate privilege. .Pp .It Dv SIOCSIFMTU Change interface MTU. Caller must have appropriate privilege. MTU values less than 72 or greater than 65535 are considered invalid. The driver .Fn if_ioctl routine is called to implement the change; it is responsible for any additional sanity checking and for actually modifying the MTU in the interface structure. .Pp .It Dv SIOCADDMULTI .It Dv SIOCDELMULTI Add or delete permanent multicast group memberships on the interface. Caller must have appropriate privilege. The .Fn if_addmulti or .Fn if_delmulti function is called to perform the operation; qq.v. .Pp .It Dv SIOCAIFADDR .It Dv SIOCDIFADDR The socket's protocol control routine is called to implement the requested action. .El .El .Pp .Fn if_down , .Fn ifioctl , .Fn ifpromisc , and .Fn if_up must be called at .Fn splnet or higher. .Ss "Interface Address Functions" Several functions exist to look up an interface address structure given an address. .Fn ifa_ifwithaddr returns an interface address with either a local address or a broadcast address precisely matching the parameter .Fa addr . .Fn ifa_ifwithdstaddr returns an interface address for a point-to-point interface whose remote .Pq Dq destination address is .Fa addr and a fib is .Fa fib . If .Fa fib is .Dv RT_ALL_FIBS , then the first interface address matching .Fa addr will be returned. .Pp .Fn ifa_ifwithnet returns the most specific interface address which matches the specified address, .Fa addr , subject to its configured netmask, or a point-to-point interface address whose remote address is .Fa addr if one is found. If .Fa ignore_ptp is true, skip point-to-point interface addresses. The .Fa fib parameter is handled the same way as by .Fn ifa_ifwithdstaddr . .Pp .Fn ifaof_ifpforaddr returns the most specific address configured on interface .Fa ifp which matches address .Fa addr , subject to its configured netmask. If the interface is point-to-point, only an interface address whose remote address is precisely .Fa addr will be returned. .Pp .Fn ifaddr_byindex returns the link-level address of the interface with the given index .Fa idx . .Pp All of these functions return a null pointer if no such address can be found. .Ss "Interface Multicast Address Functions" The .Fn if_addmulti , .Fn if_delmulti , and .Fn if_findmulti functions provide support for requesting and relinquishing multicast group memberships, and for querying an interface's membership list, respectively. The .Fn if_addmulti function takes a pointer to an interface, .Fa ifp , and a generic address, .Fa sa . It also takes a pointer to a .Vt "struct ifmultiaddr *" which is filled in on successful return with the address of the group membership control block. The .Fn if_addmulti function performs the following four-step process: .Bl -enum -offset indent .It Call the interface's .Fn if_resolvemulti entry point to determine the link-layer address, if any, corresponding to this membership request, and also to give the link layer an opportunity to veto this membership request should it so desire. .It Check the interface's group membership list for a pre-existing membership for this group. If one is not found, allocate a new one; if one is, increment its reference count. .It If the .Fn if_resolvemulti routine returned a link-layer address corresponding to the group, repeat the previous step for that address as well. .It If the interface's multicast address filter needs to be changed because a new membership was added, call the interface's .Fn if_ioctl routine (with a .Fa cmd argument of .Dv SIOCADDMULTI ) to request that it do so. .El .Pp The .Fn if_delmulti function, given an interface .Fa ifp and an address, .Fa sa , reverses this process. Both functions return zero on success, or a standard error number on failure. .Pp The .Fn if_findmulti function examines the membership list of interface .Fa ifp for an address matching .Fa sa , and returns a pointer to that .Vt "struct ifmultiaddr" if one is found, else it returns a null pointer. .Sh SEE ALSO .Xr ioctl 2 , .Xr link_addr 3 , .Xr queue 3 , .Xr sysctl 3 , .Xr bpf 4 , .Xr ifmib 4 , .Xr lo 4 , .Xr netintro 4 , .Xr polling 4 , .Xr config 8 , .Xr ppp 8 , .Xr mbuf 9 , .Xr rtentry 9 .Rs .%A Gary R. Wright .%A W. Richard Stevens .%B TCP/IP Illustrated .%V Vol. 2 .%O Addison-Wesley, ISBN 0-201-63354-X .Re .Sh AUTHORS This manual page was written by .An Garrett A. Wollman .