diff options
Diffstat (limited to 'share/man')
35 files changed, 940 insertions, 300 deletions
diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile index 519b113b0a2e..f5d7a0e081fc 100644 --- a/share/man/man4/Makefile +++ b/share/man/man4/Makefile @@ -1,13 +1,16 @@ .include <src.opts.mk> MANGROUPS= MAN -MANPACKAGE= kernel +MANPACKAGE= kernel-man # If you add a new file here, please consider adding an entry to the # hardware notes template (website/archetypes/release/hardware.adoc in # the doc repository); otherwise the automatically generated hardware # notes will not include your driver. +# If you enable a driver for a different architecture, please remember +# to update the arch specifier in the document title of the manual. + MAN= aac.4 \ aacraid.4 \ acpi.4 \ @@ -1062,6 +1065,7 @@ MAN+= \ ucom.4 \ ucycom.4 \ udav.4 \ + udbc.4 \ udbp.4 \ udl.4 \ uep.4 \ diff --git a/share/man/man4/blackhole.4 b/share/man/man4/blackhole.4 index bb955fd4497d..777a38eedc86 100644 --- a/share/man/man4/blackhole.4 +++ b/share/man/man4/blackhole.4 @@ -10,15 +10,12 @@ .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" -.Dd May 25, 2024 +.Dd September 24, 2025 .Dt BLACKHOLE 4 .Os .Sh NAME .Nm blackhole -.Nd a -.Xr sysctl 8 -MIB for manipulating behaviour in respect of refused SCTP, TCP, or UDP connection -attempts +.Nd quietly drop refused SCTP, TCP, or UDP packets .Sh SYNOPSIS .Cd sysctl net.inet.sctp.blackhole Ns Op = Ns Brq "0 | 1 | 2" .Cd sysctl net.inet.tcp.blackhole Ns Op = Ns Brq "0 | 1 | 2 | 3" diff --git a/share/man/man4/cdceem.4 b/share/man/man4/cdceem.4 index 6d8caf53cc02..c2a282027241 100644 --- a/share/man/man4/cdceem.4 +++ b/share/man/man4/cdceem.4 @@ -1,3 +1,6 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" .\" Copyright (c) 2019 Edward Tomasz Napierala <trasz@FreeBSD.org> .\" .\" Redistribution and use in source and binary forms, with or without @@ -20,12 +23,12 @@ .\" 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. -.Dd November 7, 2019 +.Dd September 18, 2025 .Dt CDCEEM 4 .Os .Sh NAME .Nm cdceem -.Nd "USB Communication Device Class Ethernet Emulation Model (CDC EEM) driver" +.Nd USB Communication Device Class Ethernet Emulation Model driver .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your diff --git a/share/man/man4/dtrace_lockstat.4 b/share/man/man4/dtrace_lockstat.4 index e308ca6c22ce..448de91a375f 100644 --- a/share/man/man4/dtrace_lockstat.4 +++ b/share/man/man4/dtrace_lockstat.4 @@ -22,12 +22,12 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd August 20, 2019 +.Dd September 3, 2025 .Dt DTRACE_LOCKSTAT 4 .Os .Sh NAME .Nm dtrace_lockstat -.Nd a DTrace provider for tracing CPU scheduling events +.Nd a DTrace provider for tracing kernel locking events .Sh SYNOPSIS .Fn lockstat:::adaptive-acquire "struct mtx *" .Fn lockstat:::adaptive-release "struct mtx *" diff --git a/share/man/man4/epair.4 b/share/man/man4/epair.4 index 342b15b5612a..b406c423361b 100644 --- a/share/man/man4/epair.4 +++ b/share/man/man4/epair.4 @@ -25,7 +25,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd August 12, 2025 +.Dd September 4, 2025 .Dt EPAIR 4 .Os .Sh NAME @@ -108,6 +108,29 @@ As with any other Ethernet interface, can have a .Xr vlan 4 configured on top of it. +.Pp +The +.Nm +has RXCSUM and RXCSUM6 enabled because it may receive a packet where the +checksum has already been validated by a physical interface. +The +.Nm +supports TXCSUM and TXCSUM6 for TCP and UDP, but only by forwarding the order +to compute the checksum. +Thus, when using an +.Nm +interface, a TCP or UDP sender can offload checksum computation +to a physical interface. +Note that, in case the packet does not leave the host, the checksum is +unnecessary and will be ignored if offloaded. +Such packets contain an incorrect checksum, since it is not computed yet. +TXCSUM and TXCSUM6 are synchronized between the +.Nm +interface pair (i.e., enabling/disabling the capability on one end +enables/disables it on the other end). +In case one end is in a bridge and the bridge disabled TXCSUM or TXCSUM6, +this avoids a sender to send packets with checksum offloading into the +bridge by using the other end. .Sh SEE ALSO .Xr ioctl 2 , .Xr altq 4 , diff --git a/share/man/man4/gpioled.4 b/share/man/man4/gpioled.4 index 646e2ff2a8f0..45457d20d298 100644 --- a/share/man/man4/gpioled.4 +++ b/share/man/man4/gpioled.4 @@ -70,7 +70,20 @@ Which pin on the GPIO interface to map to this instance. Please note that this mask should only ever have one bit set (any other bits - i.e., pins - will be ignored). .It Va hint.gpioled.%d.invert -If set to 1, the pin will be set to 0 to light the LED, and 1 to clear it. +Use pin inversion. If set to 1, the pin will be set to 0 to light the LED, and 1 +to clear it. +.It Va hint.gpioled.%d.invmode +Whether or not to use hardware support when pin inversion is requested. Must be +one of: +.Bl -tag +.It Va auto +Use hardware pin inversion if available, else fallback to software pin +inversion. This is the default. +.It Va hw +Use hardware pin inversion. +.It Va sw +Use software pin inversion. +.El .It Va hint.gpioled.%d.state The initial state of the LED when the driver takes control over it. If set to 1 or 0, the LED will be on or off correspondingly. diff --git a/share/man/man4/pci.4 b/share/man/man4/pci.4 index 91fbb557f644..b99747969035 100644 --- a/share/man/man4/pci.4 +++ b/share/man/man4/pci.4 @@ -22,7 +22,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd April 2, 2025 +.Dd August 31, 2025 .Dt PCI 4 .Os .Sh NAME @@ -235,6 +235,17 @@ revision ID. Driver name. .It pd_unit Driver unit number. +.It pd_numa_domain +Driver NUMA domain. +.It pc_reported_len +Length of the valid portion of the encompassing +.Vt pci_conf +structure. +This should always be equivalent to the offset of the +.Va pc_spare +member. +.It pc_spare +Reserved for future use. .El .It offset The offset is passed in by the user to tell the kernel where it should diff --git a/share/man/man4/pfsync.4 b/share/man/man4/pfsync.4 index cc9c350ea875..c12bad74831f 100644 --- a/share/man/man4/pfsync.4 +++ b/share/man/man4/pfsync.4 @@ -162,6 +162,8 @@ FreeBSD releases 13.2 and older. Compatibility with FreeBSD 13.1 has been verified. .It Cm 1400 FreeBSD release 14.0. +.It Cm 1500 +FreeBSD release 15.0. .El .Sh SYSCTL VARIABLES The following variables can be entered at the diff --git a/share/man/man4/random.4 b/share/man/man4/random.4 index 840bc0c3234b..04d46e4d32aa 100644 --- a/share/man/man4/random.4 +++ b/share/man/man4/random.4 @@ -21,7 +21,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd April 19, 2019 +.Dd August 28, 2025 .Dt RANDOM 4 .Os .Sh NAME @@ -132,6 +132,17 @@ are listed in square brackets. See .Xr random_harvest 9 for more on the harvesting of entropy. +.Pp +The +.Va kern.random.nist_healthtest_enabled +tunable can be used to enable the entropy source health tests outlined +in section 4 of NIST Special Publication 800-90B. +When enabled, all entropy sources will be subject to the repetition +count and adaptive proportion tests described in that document. +If one of the tests fails, the source will be disabled, i.e., all +subsequent entropy samples from that source will be discarded. +The implementation performs startup testing, during which entropy +sources are discarded. .Sh FILES .Bl -tag -width ".Pa /dev/urandom" .It Pa /dev/random diff --git a/share/man/man4/syncache.4 b/share/man/man4/syncache.4 index e92502fd15ff..f83e9b083e45 100644 --- a/share/man/man4/syncache.4 +++ b/share/man/man4/syncache.4 @@ -10,7 +10,7 @@ .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" -.Dd April 12, 2021 +.Dd August 30, 2025 .Dt SYNCACHE 4 .Os .Sh NAME @@ -39,6 +39,8 @@ MIBs for controlling TCP SYN caching .Nm sysctl Cm net.inet.tcp.syncache.count .It .Nm sysctl Cm net.inet.tcp.syncache.see_other +.It +.Nm sysctl Cm net.inet.tcp.syncache.rst_on_sock_fail .El .Sh DESCRIPTION The @@ -107,6 +109,18 @@ and run only with set .Va net.inet.tcp.syncookies_only to 1. +To use +.Nm syncookies +to handle bucket overflows in the +.Nm syncache +set +.Va net.inet.tcp.syncookies +to 1. +The default value for +.Va net.inet.tcp.syncookies_only +is 0 and the default value for +.Va net.inet.tcp.syncookies +is 1. .Pp The .Nm @@ -169,6 +183,9 @@ However, extra .Xr ucred 9 referencing is required on every incoming SYN packet processed. The default is off. +.It Va rst_on_sock_fail +Send a TCP RST segment if the socket allocation fails. +The default is on. .El .Pp Statistics on the performance of the @@ -206,8 +223,16 @@ Entries dropped due to ICMP unreachable messages. Failures to allocate new .Nm entry. +.It Li "cookies sent" +SYN cookies sent in SYN ACK segments. .It Li "cookies received" -Connections created from segment containing ACK. +ACK segments with valid syncookies which resulted in TCP connection +establishment. +.It Li "spurious cookies rejected" +Received ACKs, for which the syncache lookup failed and also no syncookie was +recently sent. +.It Li "failed cookies rejected" +Received ACKs for which the syncookie validation failed. .El .Sh SEE ALSO .Xr netstat 1 , diff --git a/share/man/man4/tcp.4 b/share/man/man4/tcp.4 index fcfda42908d8..3c9f4ff83f3d 100644 --- a/share/man/man4/tcp.4 +++ b/share/man/man4/tcp.4 @@ -31,7 +31,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd June 27, 2025 +.Dd September 5, 2025 .Dt TCP 4 .Os .Sh NAME @@ -940,9 +940,6 @@ maximum segment size. This helps throughput in general, but particularly affects short transfers and high-bandwidth large propagation-delay connections. -.It Va rfc6675_pipe -Deprecated and superseded by -.Va sack.revised .It Va sack.enable Enable support for RFC 2018, TCP Selective Acknowledgment option, which allows the receiver to inform the sender about all successfully @@ -974,6 +971,11 @@ recovery, the trailing segment is immediately resent, rather than waiting for a Retransmission timeout. Finally, SACK loss recovery is also engaged, once two segments plus one byte are SACKed - even if no traditional duplicate ACKs were observed. +.Va sack.revised +is deprecated and will be removed in +.Fx 16 . +.Va sack.enable +will always follow RFC6675. .It Va sendbuf_auto Enable automatic send buffer sizing. .It Va sendbuf_auto_lowat diff --git a/share/man/man4/udbc.4 b/share/man/man4/udbc.4 new file mode 100644 index 000000000000..c8fa02ec18f1 --- /dev/null +++ b/share/man/man4/udbc.4 @@ -0,0 +1,132 @@ +.\" +.\" Copyright (c) 2025 The FreeBSD Foundation +.\" +.\" This documentation was written by Tom Jones <thj@freebsd.org> under +.\" sponsorship from the FreeBSD Foundation. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" +.Dd September 3, 2025 +.Dt UDBC 4 +.Os +.Sh NAME +.Nm udbc +.Nd USB Debug Class device driver +.Sh SYNOPSIS +.Cd "device usb" +.Cd "device ucom" +.Cd "device udbc" +.Pp +In +.Xr rc.conf 5 : +.Cd kld_list="udbc" +.Sh DESCRIPTION +The +.Nm +driver provides support for USB Debug Class devices whose +interface class is Diagnostic Class and the subclass is DbC.GP. +.Pp +The USB Debug Class is defined in the USB 3.1 Device Class +Specification for Debug Devices. +This is designed to provide a general-purpose communication channel +for debugging. +It has also been widely implemented in USB xHCs +.Pq USB eXtensible Host Controllers , +which can be found on many commodity computers, +as an optional feature. +Once this feature is enabled on a USB xHC, one of the USB ports will +behave as a USB Debug Class device, +not a host port, +when a USB debug cable is connected. +The supported class in USB xHCs is typically DbC.GP, +while the specification defines several types of Debug Class devices. +The DbC.GP uses IN and OUT endpoint pairs and realizes a single +bidirectional serial communication channel. +On most systems, +including +.Fx , +the DbC.GP is seen as a simple serial device. +.Pp +Most systems with USB xHC can be configured to provide DbC.GP access. +The +.Nm +is a driver that connects to DbC.GP-supported devices, +offering +.Xr tty 4 +devices to connect to them via the +.Xr ucom 4 +device driver. +.Sh HARDWARE CONFIGURATION +A native DbC.GP device can be attached using the +.Nm +driver in a straightforward way. +.Pp +A USB xHC DbC.GP device on a target system needs a special hardware +configuration because all of the ports are supposed to be a USB Host. +There is one method to expose DbC.GP is to use a USB 3.1 A-to-A cable +.Pq section 5.5.2 in USB 3.1 Legacy Cable and Connector Specification . +When this cable is connected to a USB 3.1 port on the target system, +the DbC-enabled USB xHC automatically switches the port as a USB Device. +The +.Nm +driver can find a DbC.GP device on that port. +.Pp +Note that a USB xHC with USB 3.2 support +.Pq USB Type-C connectors +is not compatible with the USB 3.1 A-to-A cable. +Connecting a USB 3.2 C-to-C cable or A-to-C cable does not automatically work, +either, +because it needs role configuration of the port, which is not supported on +.Fx +yet. +.Sh FILES +.Bl -tag -width "/dev/ttyU*.*.init" -compact +.It Pa /dev/ttyU*.* +for callin ports +.It Pa /dev/ttyU*.*.init +.It Pa /dev/ttyU*.*.lock +corresponding callin initial-state and lock-state devices +.Pp +.It Pa /dev/cuaU*.* +for callout ports +.It Pa /dev/cuaU*.*.init +.It Pa /dev/cuaU*.*.lock +corresponding callout initial-state and lock-state devices +.El +.Sh SEE ALSO +.Xr tty 4 , +.Xr ucom 4 , +.Xr usb 4 , +.Xr xhci 4 +.Sh STANDARDS +.Rs +.%T eXtensible Host Controller Interface for Universal Serial Bus (XHCI) +.%U https://www.intel.com/content/dam/www/public/us/en/documents/technical-specifications/extensible-host-controler-interface-usb-xhci.pdf +.Re +.Rs +.%T USB 3.1 Device Class Specification for Debug Devices +.%U https://www.usb.org/sites/default/files/documents/usb_debug_class_rev_1_0_final_0.pdf +.Re +.Rs +.%T USB 3.1 Legacy Cable and Connector Specification +.%U https://www.usb.org/document-library/usb-31-legacy-cable-and-connector-revision-10 +.Re +.Sh HISTORY +The +.Nm +driver first appeared +.Fx +15.0. +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Hiroki Sato Aq Mt hrs@FreeBSD.org . +.Sh BUGS +According to the XHCI specification the host side of USB Debug should work with +any USB 3.0 port, +whether connected directly to a controller or with a hub in between. +Testing on some controllers has encountered issues when using a hub rather than +a directly connected port on the controller. diff --git a/share/man/man4/umb.4 b/share/man/man4/umb.4 index 311a50faf8e7..37c86b3074f5 100644 --- a/share/man/man4/umb.4 +++ b/share/man/man4/umb.4 @@ -17,14 +17,13 @@ .\" .\" $NetBSD: umb.4,v 1.4 2019/08/30 09:22:17 wiz Exp $ .\" -.Dd August 4, 2025 +.Dd September 3, 2025 .Dt UMB 4 .Os .Sh NAME .Nm umb .Nd USB Mobile Broadband Interface Model (MBIM) cellular modem driver .Sh SYNOPSIS -.Cd "device netmap" .Cd "device usb" .Cd "device umb" .Pp diff --git a/share/man/man4/vtnet.4 b/share/man/man4/vtnet.4 index b6f10ddd87cb..636ce4cc9b60 100644 --- a/share/man/man4/vtnet.4 +++ b/share/man/man4/vtnet.4 @@ -22,7 +22,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd August 21, 2025 +.Dd September 26, 2025 .Dt VTNET 4 .Os .Sh NAME @@ -54,6 +54,8 @@ TCP segmentation offload (TSO), TCP large receive offload (LRO), hardware VLAN tag stripping/insertion features, a multicast hash filter, as well as Jumbo Frames (up to 9216 bytes), which can be configured via the interface MTU setting. +TCP/UDP receive checksum offload cannot be configured independently for IPv4 +and IPv6. Selecting an MTU larger than 1500 bytes with the .Xr ifconfig 8 utility configures the adapter to receive and transmit Jumbo Frames. @@ -84,6 +86,8 @@ field of the structure .Vt struct virtio_net_hdr . It also marks the checksum as being correct in the mbuf packet header. The default value is 0. +This tunable is deprecated and will be removed in +.Fx 16 . .It Va hw.vtnet.tso_disable .It Va hw.vtnet. Ns Ar X Ns Va .tso_disable This tunable disables TCP segmentation offloading. @@ -127,7 +131,6 @@ This option applies to all interfaces. The default value is 0. .El .Sh TRANSMIT QUEUE STATISTICS -.Bl -tag -width "xxxxxx" For each transmit queue of each interface the following read-only statistics are provided: .Bl -tag -width "xxxxxx" @@ -154,7 +157,14 @@ The number of times the receive interrupt handler was rescheduled. .It Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .host_lro The number of times TCP large receive offload was performed. .It Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .csum_failed -Currently not used. +The number of times a packet with a request for receive or transmit checksum +offloading was received and this request failed. +The different reasons for the failure are counted by +.Va dev.vtnet. Ns Ar X Ns Va .rx_csum_inaccessible_ipproto , +.Va dev.vtnet. Ns Ar X Ns Va .rx_csum_bad_ipproto , +.Va dev.vtnet. Ns Ar X Ns Va .rx_csum_bad_ethtype , +and +.Va dev.vtnet. Ns Ar X Ns Va .rx_csum_bad_offset . .It Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .csum The number of times receive checksum offloading for UDP or TCP was performed. .It Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .ierrors @@ -214,18 +224,21 @@ over all receive queues of the interface. The sum of .Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .csum_failed over all receive queues of the interface. -.It Va dev.vtnet. Ns Ar X Ns Va .rx_csum_bad_proto -Currently unused. +.It Va dev.vtnet. Ns Ar X Ns Va .rx_csum_inaccessible_ipproto +The number of times a packet with a request for receive or transmit checksum +offloading was received where the IP protocol was not accessible. .It Va dev.vtnet. Ns Ar X Ns Va .rx_csum_bad_offset -Currently unused. -.It Va dev.vtnet. Ns Ar X Ns Va .rx_csum_bad_ipproto -Currently unused. -.It Va dev.vtnet. Ns Ar X Ns Va .rx_csum_bad_ethtype The number of times fixing the checksum required by .Va hw.vtnet.fixup_needs_csum or .Va hw.vtnet. Ns Ar X Ns Va .fixup_needs_csum -was attempted for a packet with an EtherType other than IPv4 or IPv6. +was attempted for a packet where the csum is not located in the first mbuf. +.It Va dev.vtnet. Ns Ar X Ns Va .rx_csum_bad_ipproto +The number of times a packet with a request for receive or transmit checksum +offloading was received where the IP protocol was neither TCP nor UDP. +.It Va dev.vtnet. Ns Ar X Ns Va .rx_csum_bad_ethtype +The number of times a packet with a request for receive or transmit checksum +offloading was received where the EtherType was neither IPv4 nor IPv6. .It Va dev.vtnet. Ns Ar X Ns Va .rx_mergeable_failed The number of times receiving a mergable buffer failed. .It Va dev.vtnet. Ns Ar X Ns Va .rx_enq_replacement_failed diff --git a/share/man/man4/watchdog.4 b/share/man/man4/watchdog.4 index b74640de8469..fc2d600328dd 100644 --- a/share/man/man4/watchdog.4 +++ b/share/man/man4/watchdog.4 @@ -41,24 +41,22 @@ The device supports several optional .Xr ioctl 2 calls for configuration, and -responds to a single operational +responds to a set of operational .Xr ioctl 2 -call, -.Dv WDIOCPATPAT . -It takes a single argument which represents a timeout value specified as a -power of two nanoseconds, or-ed with a flag selecting active or passive control -of the watchdog. +calls: +.Bl -tag -width "WDIOC_CONTROL int " +.It Dv WDIOCPATPAT +Pat the watchdog. +.It Dv WDIOC_CONTROL +Enable, disable, or reset the watchdog. +.El .Pp -.Dv WD_ACTIVE -indicates that the -.Nm -will be kept from timing out from userland, for instance by the -.Xr watchdogd 8 -daemon. -.Dv WD_PASSIVE -indicates that the -.Nm -will be kept from timing out from the kernel. +The +.Dv WDIOCPATPAT +.Xr ioctl 2 +call takes a single argument which represents a timeout value specified as a +.Vt sbintime_t +of the timeout period for the watchdog. .Pp The .Dv WDIOCPATPAT @@ -77,27 +75,43 @@ none of implementations support the timeout length, all watchdogs are disabled and must be explicitly re-enabled. .Pp -To disable the watchdogs pass -.Dv WD_TO_NEVER . +To disable the watchdogs use the +.Dv WDIOC_CONTROL +.Xr ioctl 2 +call with the +.Dv WD_CTRL_DISABLE +flag. If disarming the watchdog(s) failed an error is returned. The watchdog might still be armed! +To reenable the watchdogs use the +.Dv WDIOC_CONTROL +.Xr ioctl 2 +call with the +.Dv WD_CTRL_ENABLE +flag. +Another way to pat the watchdog is with the +.Dv WDIOC_CONTROL +.Xr ioctl 2 +call passing the +.Dv WDIOC_CTRL_RESET +flag. .Pp The optional configuration .Xr ioctl 2 commands are listed here, along with the type of the parameter used. Examples of their use can be found in .Xr watchdogd 8 . -.Bl -tag -width "WDIOC_SETSOFTTIMEOUTACT int " -.It Dv WDIOC_SETTIMEOUT Fa int +.Bl -tag -width "WDIOC_GETPRETTIMEOUT sbintime_t" +.It Dv WDIOC_SETTIMEOUT Fa sbintime_t set/reset the timer -.It Dv WDIOC_GETTIMEOUT Fa int +.It Dv WDIOC_GETTIMEOUT Fa sbintime_t get total timeout -.It Dv WDIOC_GETTIMELEFT Fa int +.It Dv WDIOC_GETTIMELEFT Fa sbintime_t get time left -.It Dv WDIOC_GETPRETIMEOUT Fa int +.It Dv WDIOC_GETPRETIMEOUT Fa sbintime_t get the pre-timeout -.It Dv WDIOC_SETPRETIMEOUT Fa int +.It Dv WDIOC_SETPRETIMEOUT Fa sbintime_t set the pre-timeout .It Dv WDIOC_SETPRETIMEOUTACT Fa int Set the action when a pre-timeout occurs (see diff --git a/share/man/man5/group.5 b/share/man/man5/group.5 index 044164a3c955..8f7c59c59d52 100644 --- a/share/man/man5/group.5 +++ b/share/man/man5/group.5 @@ -25,7 +25,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd February 8, 2013 +.Dd August 29, 2025 .Dt GROUP 5 .Os .Sh NAME @@ -145,6 +145,7 @@ may still have this limit. .Sh SEE ALSO .Xr newgrp 1 , .Xr passwd 1 , +.Xr setcred 2 , .Xr setgroups 2 , .Xr crypt 3 , .Xr getgrent 3 , diff --git a/share/man/man5/pf.conf.5 b/share/man/man5/pf.conf.5 index a9ae823257a4..da02f10aac01 100644 --- a/share/man/man5/pf.conf.5 +++ b/share/man/man5/pf.conf.5 @@ -27,7 +27,7 @@ .\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" -.Dd July 30, 2025 +.Dd August 28, 2025 .Dt PF.CONF 5 .Os .Sh NAME @@ -92,14 +92,20 @@ keyword, for example: include "/etc/pf/sub.filter.conf" .Ed .Sh MACROS -Macros can be defined that will later be expanded in context. -Macro names must start with a letter, and may contain letters, digits -and underscores. -Macro names may not be reserved words (for example +A macro is defined with a command of the form +.Ar name Ns = Ns Ar value . +The macro +.Ar name +can contain letters, digits, and underscores and cannot be a reserved word +(for example, .Ar pass , .Ar in , +or .Ar out ) . -Macros are not expanded inside quotes. +Within unquoted arguments, the string +.Pf $ Ar name +is later expanded to +.Ar value . Ranges of network addresses used in macros that will be expanded in lists later on must be quoted with additional simple quotes. .Pp @@ -267,6 +273,10 @@ which corresponds to the connection state. Each packet which matches this state will reset the TTL. Tuning these values may improve the performance of the firewall at the risk of dropping valid idle connections. +Alternatively, these values may be adjusted collectively +in a manner suitable for a specific environment using +.Cm set optimization +(see above). .Pp .Bl -tag -width xxxx -compact .It Ar tcp.first @@ -274,6 +284,9 @@ The state after the first packet. .It Ar tcp.opening The state after the second packet but before both endpoints have acknowledged the connection. +.It Ar tcp.tsdiff +Maximum allowed time difference between RFC 1323 compliant packet timestamps. +30 seconds by default. .It Ar tcp.established The fully established state. .It Ar tcp.closing @@ -2245,6 +2258,13 @@ When the rate is exceeded, all ICMP is blocked until the rate falls below .It Ar max-pkt-size Aq Ar number Limit each packet to be no more than the specified number of bytes. This includes the IP header, but not any layer 2 header. +.It Ar once +Create a one shot rule. +The first matching packet marks the rule as expired. +Expired rules are skipped and hidden, unless +.Xr pfctl 8 +is used in debug or verbose mode. +.Pp .It Xo Ar queue Aq Ar queue .No \*(Ba ( Aq Ar queue , .Aq Ar queue ) @@ -2470,7 +2490,13 @@ NAT address and port. This feature implements "full-cone" NAT behavior. .El .Pp -Additionally, the +Additionally, options +.Ar sticky-address +and +.Ar prefer-ipv6-nexthop +can be specified to influence how IP addresses selected from pools. +.Pp +The .Ar sticky-address option can be specified to help ensure that multiple connections from the same source are mapped to the same redirection address. @@ -2486,6 +2512,14 @@ beyond the lifetime of the states, increase the global options with See .Sx STATEFUL TRACKING OPTIONS for more ways to control the source tracking. +.Pp +The +.Ar prefer-ipv6-nexthop +option allows for IPv6 addresses to be used as the nexthop +for IPv4 packets routed with the +.Ar route-to +rule option. If a table is used with IPv4 and IPv6 addresses, first the IPv6 addresses +will be used in round-robin fashion, then IPv4 addresses. .Sh STATE MODULATION Much of the security derived from TCP is attributable to how well the initial sequence numbers (ISNs) are chosen. @@ -3416,7 +3450,7 @@ filteropt = user | group | flags | icmp-type | icmp6-type | "tos" tos | [ "(" state-opts ")" ] | "fragment" | "no-df" | "min-ttl" number | "set-tos" tos | "max-mss" number | "random-id" | "reassemble tcp" | - fragmentation | "allow-opts" | + fragmentation | "allow-opts" | "once" | "label" string | "tag" string | [ "!" ] "tagged" string | "max-pkt-rate" number "/" seconds | "set prio" ( number | "(" number [ [ "," ] number ] ")" ) | @@ -3566,7 +3600,7 @@ fragmentation = [ "fragment reassemble" ] timeout-list = timeout [ [ "," ] timeout-list ] timeout = ( "tcp.first" | "tcp.opening" | "tcp.established" | - "tcp.closing" | "tcp.finwait" | "tcp.closed" | + "tcp.closing" | "tcp.finwait" | "tcp.closed" | "tcp.tsdiff" | "sctp.first" | "sctp.opening" | "sctp.established" | "sctp.closing" | "sctp.closed" | "udp.first" | "udp.single" | "udp.multiple" | @@ -3580,7 +3614,7 @@ limit-item = ( "states" | "frags" | "src-nodes" ) number pooltype = ( "bitmask" | "random" | "source-hash" [ ( hex-key | string-key ) ] | - "round-robin" ) [ sticky-address ] + "round-robin" ) [ sticky-address | prefer-ipv6-nexthop ] subqueue = string | "{" queue-list "}" queue-list = string [ [ "," ] string ] diff --git a/share/man/man5/src.conf.5 b/share/man/man5/src.conf.5 index 2895c0cf4746..ded16c9cf436 100644 --- a/share/man/man5/src.conf.5 +++ b/share/man/man5/src.conf.5 @@ -1,5 +1,5 @@ .\" DO NOT EDIT-- this file is @generated by tools/build/options/makeman. -.Dd August 20, 2025 +.Dd September 10, 2025 .Dt SRC.CONF 5 .Os .Sh NAME @@ -29,8 +29,11 @@ variables that control the aspects of how the system builds. .Pp The default location of .Nm -is -.Pa /etc/src.conf , +is the top level of the source tree, or +.Pa /etc/src.conf +if no +.Nm +is found in the source tree itself, though an alternative location can be specified in the .Xr make 1 variable @@ -1212,8 +1215,8 @@ is set explicitly) .It Va WITHOUT_MANCOMPRESS Do not install compressed man pages. Only the uncompressed versions will be installed. -.It Va WITHOUT_MANSPLITPKG -Do not split man pages into their own packages during make package. +.It Va WITH_MANSPLITPKG +Split man pages into their own packages during make package. .It Va WITHOUT_MAN_UTILS Do not build utilities for manual pages, .Xr apropos 1 , diff --git a/share/man/man7/Makefile b/share/man/man7/Makefile index 1e50242a1754..6a426cc29b15 100644 --- a/share/man/man7/Makefile +++ b/share/man/man7/Makefile @@ -1,5 +1,7 @@ .include <src.opts.mk> +MANGROUPS= MAN + #MISSING: eqnchar.7 ms.7 term.7 MAN= arch.7 \ ascii.7 \ @@ -21,6 +23,7 @@ MAN= arch.7 \ named_attribute.7 \ operator.7 \ orders.7 \ + freebsd-base.7 \ ports.7 \ release.7 \ sdoc.7 \ @@ -31,12 +34,12 @@ MAN= arch.7 \ stats.7 \ stdint.7 \ sticky.7 \ - tests.7 \ tracing.7 \ tuning.7 MLINKS= intro.7 miscellaneous.7 MLINKS+= growfs.7 growfs_fstab.7 +MLINKS+= freebsd-base.7 pkgbase.7 MLINKS+= security.7 securelevel.7 MLINKS+= c.7 c78.7 MLINKS+= c.7 c89.7 @@ -54,14 +57,21 @@ MLINKS+= networking.7 wifi.7 .endif .if ${MK_TESTS} != "no" -ATF= ${SRCTOP}/contrib/atf -.PATH: ${ATF}/doc -MAN+= atf.7 +MANGROUPS+= ATF TESTS + +TESTS= tests.7 +TESTSPACKAGE= tests + +ATF= atf.7 +ATFPACKAGE= atf + +ATFPATH= ${SRCTOP}/contrib/atf +.PATH: ${ATFPATH}/doc CLEANFILES+= atf.7 atf.7: atf.7.in sed -e 's,__DOCDIR__,/usr/share/doc/atf,g' \ - <"${ATF}/doc/atf.7.in" >atf.7 + <"${ATFPATH}/doc/atf.7.in" >atf.7 .endif .include <bsd.prog.mk> diff --git a/share/man/man7/arch.7 b/share/man/man7/arch.7 index fe4e8055a8b1..b29fedbfd4ec 100644 --- a/share/man/man7/arch.7 +++ b/share/man/man7/arch.7 @@ -163,7 +163,10 @@ will support execution of .Dv armv7 binaries if the CPU implements .Dv AArch32 -execution state, however older arm binaries are not supported by +execution state. +Binaries targeting +.Dv armv6 +and earlier are no longer supported by .Fx . .Pp On all supported architectures: diff --git a/share/man/man7/build.7 b/share/man/man7/build.7 index 4022b915c972..5e15a528246b 100644 --- a/share/man/man7/build.7 +++ b/share/man/man7/build.7 @@ -1,4 +1,4 @@ -.\"- +.\" .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" Copyright (c) 2000 @@ -25,7 +25,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd August 8, 2025 +.Dd September 25, 2025 .Dt BUILD 7 .Os .Sh NAME @@ -36,34 +36,28 @@ system .Sh DESCRIPTION The sources for the .Fx -system and its applications are contained in three different directories, -normally -.Pa /usr/src , -.Pa /usr/doc , -and -.Pa /usr/ports . -These directories may be initially empty or non-existent until updated with -Git -.Po installed from packages with -.Xr pkg 7 -or from -.Xr ports 7 Pc . -Directory -.Pa /usr/src -contains the -.Dq "base system" -sources, which is loosely defined as the things required to rebuild -the system to a useful state. -Directory -.Pa /usr/doc -contains the source for the system documentation, excluding the manual -pages. -Directory -.Pa /usr/ports -contains a tree that provides a consistent interface for building and -installing third party applications. -For more information about the ports build process, see -.Xr ports 7 . +system and its applications are contained in three directories, +normally: +.Bl -tag -width "/usr/ports" +.It Pa /usr/src +.Dq base system , +loosely defined as everything required to build the system +to a useful state +.It Pa /usr/doc +system documentation, excluding manual pages +.It Pa /usr/ports +third-party software, with a consistent interface for building and +installing them; see +.Xr ports 7 +.El +.Pp +These directories may be initially empty or non-existent until updated +with Git +.Po Pa devel/git +from the +.Fx +Ports Collection +.Pc . .Pp The .Xr make 1 @@ -92,7 +86,9 @@ The canonical object directory is described in the documentation for the .Cm buildworld target below. .Pp -The build may be controlled by defining +The +.Nm +may be controlled by defining .Xr make 1 variables described in the .Sx ENVIRONMENT @@ -193,6 +189,20 @@ the compiler, linker, assembler, headers and libraries) has been built; see the .Cm toolchain target below. +.Pp +.Va BUILDENV_SHELL , +which defaults to +.Pa /bin/sh , +is executed. +This can be set to a command that does something in this build environment, +like cross build an application. +If that application has dependencies, though, the +.Pa devel/poudriere +package or port provides a more generic solution. +.It Cm buildenvvars +Print the shell variables that are set for a +.Cm buildenv +envirnoment and exit. .It Cm buildworld Build everything but the kernel, configure files in .Pa etc , @@ -268,13 +278,31 @@ defaults to and .Sy TARGET_ARCH must be defined. +.It Cm packages +Create a +.Xr freebsd-base 7 +package repository containing packages that can be +used to install or upgrade the base system. +The repository is created in the object directory, under +.Pa ${REPODIR}/${PKG_ABI} +where +.Ev REPODIR +is the base directory where the repository will be created, and +.Va PKG_ABI +is the +.Xr pkg 7 +ABI for the build target, for example, +.Pa /usr/obj/${SRCDIR}/repo/FreeBSD:15:amd64 . .It Cm packageworld Archive the results of .Cm distributeworld , placing the results in .Va DISTDIR . -This target is used while building a release; see -.Xr release 7 . +This target is used while building a +.Xr release 7 +and is unrelated to building +.Xr freebsd-base 7 +packages. .It Cm installworld Install everything built by a preceding .Cm buildworld @@ -355,6 +383,14 @@ and .Va XDDIR defaults to .Pa ${TARGET_ARCH}-freebsd . +.It Cm update-packages +Create or update the +.Xr freebsd-base 7 +package repository for the base system. +If an old repository is being updated, +then packages whose contents have not changed since the previous version +will be copied into the new repository to avoid needless updating of the +version number. .It Cm xdev-build Builds for the .Cm xdev @@ -392,7 +428,7 @@ The target directory under .Pa ${DESTDIR} may be modified using the .Va INSTKERNNAME -and +or .Va KODIR .Xr make 1 variables. @@ -401,26 +437,16 @@ Install the kernel to the directory .Pa ${DISTDIR}/kernel/boot/kernel . This target is used while building a release; see .Xr release 7 . -.It Cm packages -Create a -.Xr pkg 7 -repository containing packages that can be used to create or upgrade an -installation of the base system. -The output repository is placed in the object directory, under -.Pa repo/${PKG_ABI} -where -.Va PKG_ABI -is the -.Xr pkg 7 -ABI for the build target, for example, -.Pa /usr/obj/${SRCDIR}/repo/FreeBSD:15:amd64 . .It Cm packagekernel Archive the results of .Cm distributekernel , placing the results in .Va DISTDIR . -This target is used while building a release; see -.Xr release 7 . +This target is used while building a +.Xr release 7 +and is unrelated to building +.Xr freebsd-base 7 +packages. .It Cm kernel Equivalent to .Cm buildkernel @@ -549,6 +575,9 @@ should be set to the name of the package. LLVM toolchain packages use the name llvm<major version>. GCC toolchains provide separate packages for each architecture and use the name ${MACHINE_ARCH}-gcc<major version>. +.It Va INSTKERNNAME +If set, specify an alternative name to build and install for the various +kernel make targets. .It Va KERNCONF Overrides which kernel to build and install for the various kernel make targets. @@ -583,6 +612,9 @@ then .Va KERNCONF is set to the value of .Va KERNFAST . +.It Va KODIR +If set, +this variable specifies an alternative directory to install the kernel. .It Va LOCAL_DIRS If set, this variable supplies a list of additional directories relative to the root of the source tree to build as part of the @@ -642,11 +674,15 @@ If set, this variable supplies a list of additional directories relative to the root of the source tree to build as part of the .Cm cross-tools target. +.It Va OBJROOT +The object directory root is defined as +.Pa ${OBJDIR}/${SRCDIR}/ . +See +.Pa share/mk/src.sys.obj.mk . .It Va PKG_FORMAT Specify a package compression format when building -.Pa src -into -.Cm packages . +.Xr freebsd-base 7 +packages. Default: .Ql tzst . Consider using @@ -664,9 +700,8 @@ and .Cm installkernel process. This is currently incompatible with building -.Pa src -into -.Cm packages . +.Xr freebsd-base 7 +packages. Each port must be specified as .Ar category Ns Li / Ns Ar port Ns Op Li @ Ns Ar flavor , e.g. @@ -695,6 +730,13 @@ Specify a file to override the default The src.conf file controls the components to build. See .Xr src.conf 5 +.It Va REPODIR +The root directory used to create the package repository for building +.Xr packges 7 . +Defaults to +.Pa ${OBJROOT}/repo/ . +This can also be set in +.Xr src-env.conf 5 . .It Va STRIPBIN Command to use at install time when stripping binaries. Be sure to add any additional tools required to run @@ -931,26 +973,159 @@ fringe uses that do not have a wide appeal. .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 +.Xr make 1 +infrastructure for each tree +.It Pa /usr/ports/UPDATING +.It Pa /usr/src/UPDATING +notable changes in each tree +.It Pa /usr/share/examples/etc/make.conf +example +.Xr make.conf 5 +.It Pa /etc/src.conf +src build configuration, see +.Xr src.conf 5 .El .Sh EXAMPLES -For an -.Dq approved -method of updating your system from the latest sources, please see the -.Sx COMMON ITEMS -section in -.Pa src/UPDATING . +This section describes best practices for common situations. +When manual intervention is necessary, it will be mentioned in +.Pa UPDATING . +Make sure you have full backups before proceeding! +.Ss Example 1: Build and upgrade system in place +If using installed drivers such as graphics or virtual machine guest +drivers, check out the +.Xr ports 7 +tree, and specify the drivers in +.Xr src.conf 5 +so they are built and installed automatically after the kernel: +.Bd -literal -offset indent +git clone https://git.FreeBSD.org/ports.git /usr/ports +cat << EOF >> /etc/src.conf +PORTS_MODULES+=graphics/drm-kmod emulators/virtualbox-ose-kmod +EOF +.Ed +.Pp +Check out the CURRENT branch, build it, and install, +overwriting the current system: +.Bd -literal -offset indent +git clone https://git.FreeBSD.org/src.git /usr/src +cd /usr/src +make buildworld buildkernel +make installkernel +shutdown -r now +.Ed +.Pp +For major version upgrades, boot into single-user mode. +After restarting, install userspace, and merge configurations. +After verifying that you do not need them, delete old files +and libraries: +.Bd -literal -offset indent +cd /usr/src +etcupdate -p +make installworld +etcupdate -B +make delete-old delete-old-libs +shutdown -r now +.Ed +.Ss Example 2: Build and upgrade a custom kernel in place +Create a custom kernel configuration, +.Va MYKERNEL , +by including an existing configuration and using +.Cm device Ns / Ns Cm nodevice +and +.Cm options Ns / Ns Cm nooption +to select and configure components: +.Bd -literal -offset indent +cd /usr/src +cat << EOF > sys/amd64/conf/MYKERNEL +include GENERIC +ident MYKERNEL +nodevice sound +EOF +.Ed +.Pp +After creating the new kernel configuration, build a fresh toolchain, +build the kernel, and install it, moving the old kernel to +.Pa /boot/kernel.old/ : +.Bd -literal -offset indent +make kernel-toolchain +make -DALWAYS_CHECK_MAKE buildkernel KERNCONF=MYKERNEL +make -DALWAYS_CHECK_MAKE installkernel KERNCONF=MYKERNEL +shutdown -r now +.Ed +.Pp +To build the kernel to an alternate location, use the +.Va INSTKERNNAME +variable and boot it once to test via +.Xr nextboot 8 : +.Bd -literal -offset indent +make installkernel KERNCONF=MYKERNEL INSTKERNNAME=testkernel +nextboot -k testkernel +shutdown -r now +.Ed +.Ss Example 3: Build and upgrade a single piece of userspace +Rebuild and reinstall a single piece of userspace, in this case +.Xr ls 1 : +.Bd -literal -offset indent +cd /usr/src/bin/ls +make clean all +make install +.Ed +.Ss Example 4: Build and upgrade a loadable kernel module +Rebuild and reinstall a single loadable kernel module, in this case +.Xr sound 4 : +.Bd -literal -offset indent +cd /usr/src/sys/modules/sound +make all install clean cleandepend KMODDIR=/boot/kernel +.Ed +.Ss Example 5: Quickly rebuild a kernel in place +Quickly rebuild and reinstall the kernel, only recompiling the files +changed since last build; note that this will only work if the full +kernel build has been completed in the past, not on a fresh source tree: +.Bd -literal -offset indent +cd /usr/src +make kernel KERNFAST=1 +.Ed +.Ss Example 6: Cross-compiling for different architectures +To rebuild parts of +.Fx +for another CPU architecture, +first prepare your source tree by building the cross-toolchain: +.Bd -literal -offset indent +cd src +make toolchain TARGET_ARCH=aarch64 +.Ed .Pp -The following sequence of commands can be used to cross-build the system for -the arm64 (aarch64) architecture on a different host architecture, such as -amd64: +The following sequence of commands can be used to cross-build the system +for the arm64 (aarch64) architecture on a different host architecture, +such as amd64: .Bd -literal -offset indent cd /usr/src -make TARGET=arm64 buildworld buildkernel -make TARGET=arm64 DESTDIR=/clients/arm64 installworld installkernel +make TARGET_ARCH=aarch64 buildworld buildkernel +make TARGET_ARCH=aarch64 DESTDIR=/armclient installworld installkernel .Ed +.Pp +Afterwards, to build and install a single piece of userspace, use: +.Bd -literal -offset indent +cd src/bin/ls +make buildenv TARGET_ARCH=aarch64 +make clean all install DESTDIR=/armclient +.Ed +.Pp +Likewise, to quickly rebuild and reinstall the kernel, use: +.Bd -literal -offset indent +cd src +make buildenv TARGET_ARCH=aarch64 +make kernel KERNFAST=1 DESTDIR=/armclient +.Ed +.Sh DIAGNOSTICS +.Bl -diag +.It Bad system call (core dumped) +.It rescue/sh check failed, installation aborted +.Pp +The kernel was not updated due to incorrect build procedure. +Study the examples above. .Sh SEE ALSO .Xr cc 1 , .Xr install 1 , @@ -959,13 +1134,14 @@ make TARGET=arm64 DESTDIR=/clients/arm64 installworld installkernel .Xr src.conf 5 , .Xr arch 7 , .Xr development 7 , +.Xr freebsd-base 7 , .Xr pkg 7 , .Xr ports 7 , .Xr release 7 , .Xr tests 7 , .Xr config 8 , .Xr etcupdate 8 , -.Xr reboot 8 , +.Xr nextboot 8 , .Xr shutdown 8 .Sh HISTORY The @@ -974,3 +1150,23 @@ manpage first appeared in .Fx 4.3 . .Sh AUTHORS .An Mike W. Meyer Aq Mt mwm@mired.org +.Sh CAVEATS +Old objects can cause obscure build problems; try +.Ql make cleandir cleandir . +.Pp +Environment poisioning can cause obscure build problems; try prefixing +.Xr make 1 +commands with +.Ql env -i +.Pp +When doing a major release upgrade, +booting into single user mode for +.Cm installworld +is required. +.Pp +Updating the boot +.Xr loader 8 +is architecture specific. +Consult +.Xr boot 8 +for your architecture for more details. diff --git a/share/man/man7/d.7 b/share/man/man7/d.7 index f4686d98b1d1..c098958ffa56 100644 --- a/share/man/man7/d.7 +++ b/share/man/man7/d.7 @@ -3,7 +3,7 @@ .\" .\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org> .\" -.Dd June 14, 2025 +.Dd September 24, 2025 .Dt D 7 .Os .Sh NAME @@ -18,12 +18,14 @@ .Sm on .Sm off .Oo +.Oo .Cm / .Ar predicate .Cm / .Sm on .Oc -.Op Cm \&{ Ns Ar action Ns Cm \&} +.Cm \&{ Ns Ar action Ns Cm \&} +.Oc .Sh DESCRIPTION .Nm D is the diff --git a/share/man/man7/development.7 b/share/man/man7/development.7 index 1b875fb14bda..348302a50ee7 100644 --- a/share/man/man7/development.7 +++ b/share/man/man7/development.7 @@ -1,4 +1,4 @@ -.\"- +.\" .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" Copyright (c) 2018 Edward Tomasz Napierala <trasz@FreeBSD.org> @@ -24,7 +24,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd January 19, 2025 +.Dd September 24, 2025 .Dt DEVELOPMENT 7 .Os .Sh NAME @@ -75,13 +75,14 @@ There is also a list of public, read-only Git mirrors at: The .Ql main Git branch represents CURRENT; -all changes are first committed to CURRENT and then usually cherry-picked -back to STABLE, which refers to Git branches such as -.Ql stable/13 . +all changes are first committed to CURRENT and then usually +cherry-picked back to STABLE, which refers to Git branches such as +.Ql stable/14 . Every few years a new STABLE is branched from CURRENT, with an incremented major version number. -Releases are then branched off STABLE and numbered with consecutive minor -numbers. +Releases are then branched off STABLE and numbered with consecutive +minor numbers such as +.Ql releng/14.3 .Pp The layout of the source tree is described in its .Pa README.md @@ -107,12 +108,16 @@ such as freebsd-arch@ and freebsd-hackers@: To get your patches integrated into the main .Fx repository use Phabricator; -it is a code review tool that allows other developers to review the changes, -suggest improvements, and, eventually, allows them to pick up the change and -commit it: +it is a code review tool that allows other developers to +review the changes, suggest improvements, and, eventually, +allows them to pick up the change and commit it: .Pp .Lk https://reviews.FreeBSD.org .Pp +Or Github: +.Pp +.Lk https://github.com/freebsd +.Pp To check the latest .Fx build and test status of CURRENT and STABLE branches, @@ -120,77 +125,41 @@ the continuous integration system is at: .Pp .Lk https://ci.FreeBSD.org .Sh FILES -.Bl -compact -tag -width "/usr/src/tools/tools/git/git-arc.sh" +.Bl -tag -compact -width "/usr/ports/devel/freebsd-git-devtools" .It Pa /usr/src/CONTRIBUTING.md .Fx contribution guidelines .It Pa /usr/src/tools/tools/git/git-arc.sh Phabricator review tooling +.It Pa /usr/ports/devel/freebsd-git-devtools +Phabricator review tooling as a port .El .Sh EXAMPLES -Check out the CURRENT branch, build it, and install, overwriting the current -system: -.Bd -literal -offset indent -git clone https://git.FreeBSD.org/src.git src -cd src -make -sj8 buildworld buildkernel installkernel -shutdown -r now -.Ed -.Pp -After reboot: -.Bd -literal -offset indent -cd src -make -j8 installworld -reboot -.Ed -.Pp -Rebuild and reinstall a single piece of userspace, in this -case -.Xr ls 1 : -.Bd -literal -offset indent -cd src/bin/ls -make clean all install -.Ed -.Pp -Rebuild and reinstall a single loadable kernel module, in this case -.Xr sound 4 : -.Bd -literal -offset indent -cd src/sys/modules/sound -make all install clean cleandepend KMODDIR=/boot/kernel -.Ed -.Pp -Quickly rebuild and reinstall the kernel, only recompiling the files -changed since last build; note that this will only work if the full kernel -build has been completed in the past, not on a fresh source tree: -.Bd -literal -offset indent -cd src -make -sj8 kernel KERNFAST=1 -.Ed -.Pp -To rebuild parts of -.Fx -for another CPU architecture, -first prepare your source tree by building the cross-toolchain: -.Bd -literal -offset indent -cd src -make -sj8 toolchain TARGET_ARCH=aarch64 -.Ed -.Pp -Afterwards, to build and install a single piece of userspace, use: -.Bd -literal -offset indent -cd src/bin/ls -make buildenv TARGET_ARCH=aarch64 -make clean all install DESTDIR=/clients/arm -.Ed -.Pp -Likewise, to quickly rebuild and reinstall the kernel, use: -.Bd -literal -offset indent -cd src -make buildenv TARGET_ARCH=aarch64 -make -sj8 kernel KERNFAST=1 DESTDIR=/clients/arm -.Ed +Apply a patch from Github pull #1234, using +.Pa devel/gh : +.Pp +.Dl gh pr checkout 1234 +.Pp +Apply a patch from Phabricator review D1234, using +.Xr git-arc 1 : +.Pp +.Dl git arc patch -c D1234 +.Pp +Apply a manually downloaded +.Xr git-format-patch 1 , +.Pa draft.patch , +from Bugzilla or mail: +.Pp +.Dl git am draft.patch +.Pp +Apply a manually downloaded patch, +.Pa draft.diff , +from Bugzilla or mail: +.Pp +.Dl git apply draft.diff .Sh SEE ALSO .Xr git 1 , +.Xr git-arc 1 , .Xr witness 4 , .Xr build 7 , .Xr hier 7 , diff --git a/share/man/man7/freebsd-base.7 b/share/man/man7/freebsd-base.7 new file mode 100644 index 000000000000..f84cc7239a1d --- /dev/null +++ b/share/man/man7/freebsd-base.7 @@ -0,0 +1,189 @@ +.\" SPDX-License-Identifier: ISC +.\" +.\" Copyright (c) 2025 Lexi Winter. +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd September 25, 2025 +.Dt FREEBSD-BASE 7 +.Os +.Sh NAME +.\" .Nm pkgbase +.Nm freebsd-base +.Nd base system packages +.Sh DESCRIPTION +The +.Fx +base system may be installed as a set of +.Xr pkg 8 +packages, which supersedes the traditional method of installing using +.Xr tar 1 +archives. +.Pp +All base packages have names beginning with the string +.Dq "FreeBSD-" , +and have an origin beginning with +.Dq base/ . +In the default system configuration, the repository containing these +packages is called +.Dq FreeBSD-base , +but any name may be used. +The repository name can be used with +.Xr pkg 8 +to restrict package operations to the base system packages. +.Pp +Packages for all supported +.Fx +releases as well as active +.Dq STABLE +and +.Dq CURRENT +.\" re@ will provide their own repository before release, at which +.\" point this text will need updating. +branches are hosted on the Internet at +.Lk https://pkg.freebsd.org . +These packages are updated when new errata or security updates are +released (for supported release versions), or twice daily for +development branches. +.Pp +Alternatively, packages may be built from the system source tree +according to the instructions in +.Xr build 7 , +allowing the system to be updated from source code using packages. +.Sh PACKAGE ORGANISATION +To allow customisation of the installed system, each package is split +into several subpackages which contain different components of the +package. +For the package +.Sy FreeBSD-foo , +the following subpackages may be available: +.Bl -column "FreeBSD-foo-dev-lib32" "Description" +.It Sy "Package name" Ta Sy "Description" +.It FreeBSD-foo Ta Base files for the package (typically executables) +.It FreeBSD-foo-lib Ta Native runtime libraries +.It FreeBSD-foo-lib32 Ta 32-bit compatibility runtime libraries +.It FreeBSD-foo-dev Ta Development files (headers and static libraries) +.It FreeBSD-foo-dev-lib32 Ta 32-bit development files +.It FreeBSD-foo-dbg Ta Debugging symbols +.It FreeBSD-foo-man Ta Manual pages. +Manual pages are only packaged separately if the +.Sy WITH_MANSPLITPKG +.Xr src.conf 5 +option was enabled when building the system, which is not the default. +.El +.Pp +The exact set of available subpackages differs for each individual +package. For example, some packages may not provide any development +files, in which case the +.Sy -dev +subpackage is not present. +.Sh PACKAGE SETS +Package sets are meta-packages which do not contain any files +themselves, but depend on a selection of other packages, such that each +package set allows the complete set of packages for a supported workload +to be installed. +.Pp +Package sets are provided as packages named +.Sy FreeBSD-set-<name> . +The following package sets are available in the base system: +.Bl -tag -width "minimal-jail" +.It minimal +The minimal set of packages required to bring up a multi-user +.Fx +system. +This includes the core system, along with packages required for +hardware support (such as +.Xr devmatch 8 +and downloadable firmware), and basic networking, including DHCP and +IEEE Std 802.11\(tm wireless networks. +.It minimal-jail +The equivalent of +.Sy minimal +for systems running in a +.Xr jail 8 +environment. +This set excludes hardware support not typically required for jails. +.It devel +Development tools, including C/C++ compilers, the link loader, and +other tools such as +.Xr ar 1 +and +.Xr nm 1 . +This set also includes native development files (headers and static +libraries) for all packages. +.It lib32 +32-compatibility libraries, for running 32-bit applications on a +64-bit host system. +This set includes both runtime libraries and development files. +.It base +The complete base system, excluding tests, the system source code, +and debugging symbols. +.It base-jail +The equivalent of +.Sy base +for systems running in a +.Xr jail 8 +environment. +This set excludes system functionality which typically does not work +or is not useful in a jail. +.It src +The system source tree for the userland and kernel, installed in +.Pa /usr/src . +.It tests +The system test suite, installed in +.Pa /usr/tests . +.It kernels +All available system kernels. +.El +.Sh EXAMPLES +Install the +.Xr vi 1 +text editor on the running system: +.Bd -literal -offset indent +pkg install FreeBSD-vi +.Ed +.Pp +Install a new +.Xr jail 8 +system using the +.Sy minimal-jail +package set: +.Bd -literal -offset indent +pkg -r /jails/myjail install FreeBSD-set-minimal-jail +.Ed +.Pp +Install C/C++ compilers on the running system: +.Bd -literal -offset indent +pkg install FreeBSD-set-devel +.Ed +.Pp +Apply available updates to the running system: +.Bd -literal -offset indent +pkg update -r FreeBSD-base +.Ed +.Pp +Install the development toolchain for FreeBSD/powerpc64le in an +alternate root (for example, to support cross-compiling software +for a different target than the host system): +.Bd -literal -offset indent +pkg -r /ppcdev -oABI=FreeBSD:16:powerpc64le \e + install -r FreeBSD-set-devel +.Ed +.Sh SEE ALSO +.Xr build 7 , +.Xr pkg 8 , +.Xr src.conf 5 +.Sh HISTORY +Support for installing the base system as packages was introduced in +.Fx 15.0 . +Earlier releases supported a subset of this functionality. diff --git a/share/man/man7/ports.7 b/share/man/man7/ports.7 index b681a326f407..75070ce852fe 100644 --- a/share/man/man7/ports.7 +++ b/share/man/man7/ports.7 @@ -25,7 +25,7 @@ .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd March 21, 2025 +.Dd September 10, 2025 .Dt PORTS 7 .Os .Sh NAME @@ -683,7 +683,7 @@ WITH_DEBUG_PORTS= mail/dovecot security/krb5 .Pp It is also possible to use the debug variables on the command line: .Bd -literal -offset 2n -.Li # Ic make -DWITH_DEBUG DEBUG_FLAGS="-g -O0" build +.Li # Ic make WITH_DEBUG DEBUG_FLAGS="-g -O0" build .Ed .Pp See the diff --git a/share/man/man7/release.7 b/share/man/man7/release.7 index 36c14afe0bf1..05f80374926f 100644 --- a/share/man/man7/release.7 +++ b/share/man/man7/release.7 @@ -22,7 +22,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd May 20, 2025 +.Dd September 11, 2025 .Dt RELEASE 7 .Os .Sh NAME @@ -286,6 +286,19 @@ is expected to exist by alternative means. Include base system packages for use with .Xr pkg 8 on the install media, instead of legacy tarball distribution sets. +.It Va PKG_CMD +A path to the +.Xr pkg 8 +executable to use when installing packages in release images as a non-root user. +.It Va PKG_REPOS_DIR +An optional path to a directory containing +.Xr pkg 8 +repository configuration files. +These configuration files will be used when installing packages in release +images as a non-root user. +.It Va PKG_REPO_NAME +The name of the repository configuration to use when installing packages in +release images as a non-root user. .El .Sh EMBEDDED BUILDS The following diff --git a/share/man/man8/nanobsd.8 b/share/man/man8/nanobsd.8 index 838f9ddc9afa..44def2503b84 100644 --- a/share/man/man8/nanobsd.8 +++ b/share/man/man8/nanobsd.8 @@ -25,7 +25,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd July 14, 2025 +.Dd September 9, 2025 .Dt NANOBSD 8 .Os .Sh NAME @@ -33,7 +33,7 @@ .Nd create an embedded FreeBSD system image .Sh SYNOPSIS .Nm -.Op Fl BbfhIiKknqvWwX +.Op Fl BbfhIiKknpqvWwX .Op Fl c Ar config-file .Sh DESCRIPTION The @@ -42,7 +42,7 @@ 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, +which typically fits on a small media such as an SD card, or other mass storage medium. It can be used to build specialized install images, designed for easy installation and maintenance. @@ -77,6 +77,10 @@ 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 p +Don't prepare the image. +Skip running of the customization and early customization scripts for +incremental image refinement from world, kernel, or packages. .It Fl q Make output more quiet. .It Fl v diff --git a/share/man/man9/BUF_ISLOCKED.9 b/share/man/man9/BUF_ISLOCKED.9 index 09dfc458c834..c50d79c889fd 100644 --- a/share/man/man9/BUF_ISLOCKED.9 +++ b/share/man/man9/BUF_ISLOCKED.9 @@ -25,7 +25,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH .\" DAMAGE. .\" -.Dd January 22, 2008 +.Dd September 26, 2025 .Dt BUF_ISLOCKED 9 .Os .Sh NAME @@ -60,8 +60,7 @@ The lock is not held by anyone. .Xr buf 9 , .Xr BUF_LOCK 9 , .Xr BUF_UNLOCK 9 , -.Xr lockmgr 9 , -.Xr lockstatus 9 +.Xr lockmgr 9 .Sh AUTHORS This manual page was written by .An Attilio Rao Aq Mt attilio@FreeBSD.org . diff --git a/share/man/man9/MODULE_PNP_INFO.9 b/share/man/man9/MODULE_PNP_INFO.9 index 529afd70096d..b1cc935b1aca 100644 --- a/share/man/man9/MODULE_PNP_INFO.9 +++ b/share/man/man9/MODULE_PNP_INFO.9 @@ -65,7 +65,7 @@ The second name is encoded by appending a forward slash and the second name after the first.) .Pp Types are one of the following: -.Bl -tag -width U16 +.Bl -tag -width indent .It Dq Vt U8 .Vt uint8_t element. diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index 5bcde3030ebc..d2282b3e5a80 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -1,6 +1,6 @@ .include <src.opts.mk> -PACKAGE= kernel +PACKAGE= kernel-man MAN= accept_filter.9 \ accf_data.9 \ @@ -417,7 +417,7 @@ MAN= accept_filter.9 \ vn_deallocate.9 \ vn_fullpath.9 \ vn_isdisk.9 \ - vnet.9 \ + VNET.9 \ vnode.9 \ vnode_pager_setsize.9 \ vnode_pager_purge_range.9 \ @@ -2474,9 +2474,8 @@ MLINKS+=VOP_OPENCLOSE.9 VOP_CLOSE.9 \ MLINKS+=VOP_RDWR.9 VOP_READ.9 \ VOP_RDWR.9 VOP_WRITE.9 MLINKS+=VOP_REMOVE.9 VOP_RMDIR.9 -MLINKS+=vnet.9 vimage.9 -MLINKS+=vref.9 VREF.9 \ - vref.9 vrefl.9 +MLINKS+=VNET.9 VIMAGE.9 +MLINKS+=vref.9 vrefl.9 MLINKS+=vrele.9 vput.9 \ vrele.9 vunref.9 MLINKS+=vslock.9 vsunlock.9 diff --git a/share/man/man9/vnet.9 b/share/man/man9/VNET.9 index 28e28bfd3242..679ccc3f9a06 100644 --- a/share/man/man9/vnet.9 +++ b/share/man/man9/VNET.9 @@ -25,7 +25,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd December 10, 2020 +.Dd September 19, 2025 .Dt VNET 9 .Os .Sh NAME @@ -162,26 +162,6 @@ .Fa "int priority" .Fc .\" ------------------------------------------------------------ -.Ss "Sysctl Handling" -.Fo SYSCTL_VNET_INT -.Fa parent nbr name access ptr val descr -.Fc -.Fo SYSCTL_VNET_PROC -.Fa parent nbr name access ptr arg handler fmt descr -.Fc -.Fo SYSCTL_VNET_STRING -.Fa parent nbr name access arg len descr -.Fc -.Fo SYSCTL_VNET_STRUCT -.Fa parent nbr name access ptr type descr -.Fc -.Fo SYSCTL_VNET_UINT -.Fa parent nbr name access ptr val descr -.Fc -.Fo VNET_SYSCTL_ARG -.Fa req arg1 -.Fc -.\" ------------------------------------------------------------ .Sh DESCRIPTION .Nm is the name of a technique to virtualize the network stack. @@ -250,9 +230,6 @@ The .Fn VNET_NAME macro returns the offset within the memory region of the virtual network stack instance. -It is usually only used with -.Fn SYSCTL_VNET_* -macros. .\" ------------------------------------------------------------ .Ss "Virtual Instance Selection" .\" @@ -459,30 +436,9 @@ call will be ignored. .\" A .Xr sysctl 9 -can be virtualized by using one of the -.Fn SYSCTL_VNET_* -macros. -.Pp -They take the same arguments as the standard -.Xr sysctl 9 -functions, with the only difference, that the -.Fa ptr -argument has to be passed as -.Ql &VNET_NAME(foo) -instead of -.Ql &foo -so that the variable can be selected from the correct memory -region of the virtual network stack instance of the caller. -.Pp -For the very rare case a sysctl handler function would want to -handle -.Fa arg1 -itself the -.Fn VNET_SYSCTL_ARG req arg1 -is provided that will translate the -.Fa arg1 -argument to the correct memory address in the virtual network stack -context of the caller. +can be virtualized by adding the +.Dv CTLFLAG_VNET +control flag to the ctlflags bitmask of the macros. .\" ------------------------------------------------------------ .Sh SEE ALSO .Xr jail 2 , diff --git a/share/man/man9/backlight.9 b/share/man/man9/backlight.9 index 926a723b3859..c4c338ce56ca 100644 --- a/share/man/man9/backlight.9 +++ b/share/man/man9/backlight.9 @@ -65,6 +65,8 @@ struct. .Bl -tag -width "/dev/backlight/*" .It Pa /dev/backlight/* .El +.Sh SEE ALSO +.Xr backlight 8 .Sh HISTORY The .Nm backlight diff --git a/share/man/man9/g_geom.9 b/share/man/man9/g_geom.9 index 74c6979fceda..c5b0c0aded2d 100644 --- a/share/man/man9/g_geom.9 +++ b/share/man/man9/g_geom.9 @@ -27,12 +27,15 @@ .Os .Sh NAME .Nm g_new_geomf , +.Nm g_new_geom , .Nm g_destroy_geom .Nd "geom management" .Sh SYNOPSIS .In geom/geom.h .Ft "struct g_geom *" .Fn g_new_geomf "struct g_class *mp" "const char *fmt" ... +.Ft "struct g_geom *" +.Fn g_new_geom "struct g_class *mp" "const char *name" .Ft void .Fn g_destroy_geom "struct g_geom *gp" .Sh DESCRIPTION @@ -58,6 +61,14 @@ The geom's name is created in a -like way from the rest of the arguments. .Pp The +.Fn g_new_geom +function is very similar to +.Fn g_new_geomf +except that it accepts a regular string instead of a +.Xr printf 3 Ns +-like format strng as the geom's name. +.Pp +The .Fn g_destroy_geom function destroys the given geom immediately and cancels all related pending events. @@ -94,7 +105,9 @@ and .Va access for it. .Pp -.Fn g_new_geomf : +.Fn g_new_geomf +and +.Fn g_new_geom : .Bl -item -offset indent .It Class diff --git a/share/man/man9/taskqueue.9 b/share/man/man9/taskqueue.9 index 5afeffcb558b..8ffa9a96d816 100644 --- a/share/man/man9/taskqueue.9 +++ b/share/man/man9/taskqueue.9 @@ -530,7 +530,7 @@ If queueing delays cannot be tolerated then a private taskqueue should be created with a dedicated processing thread. .Sh SEE ALSO .Xr callout 9 , -.Xr ithread 9 , +.Xr intr_event 9 , .Xr kthread 9 , .Xr swi 9 .Sh HISTORY diff --git a/share/man/man9/ucred.9 b/share/man/man9/ucred.9 index 38759bddb5b0..453df386ff18 100644 --- a/share/man/man9/ucred.9 +++ b/share/man/man9/ucred.9 @@ -24,7 +24,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH .\" DAMAGE. .\" -.Dd July 29, 2025 +.Dd August 29, 2025 .Dt UCRED 9 .Os .Sh NAME @@ -113,28 +113,26 @@ The actual copying is performed by .Pp The .Fn crsetgroups -and -.Fn crsetgroups_and_egid -functions set the +function sets the .Va cr_groups and .Va cr_ngroups -variables and allocates space as needed. -They also truncate the group list to the current maximum number of -groups. -No other mechanism should be used to modify the -.Va cr_groups -array. -Note that +variables representing the supplementary groups, allocating space as needed. +It also truncates the group list to the current maximum number of groups. +The .Fn crsetgroups_and_egid -will interpret the first element of +function is similar, but interprets separately the first group of .Va groups -as the new effective GID and the rest of the array as the supplementary groups, -and +as the effective GID to set, only setting the subsequent groups as supplementary +ones. +It will use .Va default_egid -will be used as the new effective GID only if +as the new effective GID if .Va groups is empty. +No other mechanism should be used to modify the +.Va cr_groups +array. .Pp The .Fn cru2x |