diff --git a/lib/libcapsicum/capsicum_helpers.3 b/lib/libcapsicum/capsicum_helpers.3 index 9c4c0bfa0229..fe25e3a460ab 100644 --- a/lib/libcapsicum/capsicum_helpers.3 +++ b/lib/libcapsicum/capsicum_helpers.3 @@ -1,157 +1,156 @@ .\" Copyright (c) 2016 Mariusz Zaborski .\" 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. .\" .Dd January 2, 2020 .Dt CAPSICUM_HELPERS 3 .Os .Sh NAME .Nm caph_limit_stream , .Nm caph_limit_stdin , .Nm caph_limit_stderr , .Nm caph_limit_stdout , .Nm caph_limit_stdio , .Nm caph_stream_rights , .Nm caph_cache_tzdata , .Nm caph_cache_catpages , .Nm caph_enter , .Nm caph_enter_casper , .Nm caph_rights_limit , .Nm caph_ioctls_limit , .Nm caph_fcntls_limit .Nd "set of the capsicum helpers, part of the libcapsicum" .Sh LIBRARY .Lb libcapsicum .Sh SYNOPSIS .In capsicum_helpers.h .Ft int .Fn caph_enter "void" .Ft int .Fn caph_enter_casper "void" .Ft int .Fn caph_rights_limit "int fd" "const cap_rights_t *rights" .Ft int .Fn caph_ioctls_limit "int fd" "const unsigned long *cmds" "size_t ncmds" .Ft int .Fn caph_fcntls_limit "int fd" "uint32_t fcntlrights" .Ft int .Fn caph_limit_stream "int fd" "int flags" .Ft int .Fn caph_limit_stdin "void" .Ft int .Fn caph_limit_stderr "void" .Ft int .Fn caph_limit_stdout "void" .Ft int .Fn caph_limit_stdio "void" .Ft void .Fn caph_stream_rights "cap_rights_t *" "int flags" .Ft void .Fn caph_cache_tzdata "void" .Ft void .Fn caph_cache_catpages "void" .Sh DESCRIPTION The .Nm caph_enter , .Nm caph_rights_limit , .Nm caph_ioctls_limit and .Nm caph_fcntls_limit are respectively equivalent to .Xr cap_enter 2 , .Xr cap_rights_limit 2 , .Xr cap_ioctls_limit 2 and .Xr cap_fcntls_limit 2 , it returns success when the kernel is built without support of the capability mode. .Pp The .Nm caph_enter_casper is equivalent to the .Nm caph_enter it returns success when the system is built without Casper support. .Pp The .Nm capsicum helpers are a set of a inline functions which simplify modifying programs to use Capsicum. The goal is to reduce duplicated code patterns. The .Nm capsicum helpers are part of .Nm libcapsicum but there is no need to link to the library. .Pp .Fn caph_limit_stream restricts capabilities on .Fa fd to only those needed by POSIX stream objects (that is, FILEs). .Pp These flags can be provided: .Pp .Bl -tag -width "CAPH_IGNORE_EBADF" -compact -offset indent .It Dv CAPH_IGNORE_EBADF Do not return an error if file descriptor is invalid. .It Dv CAPH_READ Set CAP_READ on limited descriptor. .It Dv CAPH_WRITE Set CAP_WRITE on limited descriptor. .El .Pp .Fn caph_limit_stdin , .Fn caph_limit_stderr and .Fn caph_limit_stdout limit standard descriptors using the .Nm caph_limit_stream function. .Pp .Fn caph_limit_stdio limits stdin, stderr and stdout. .Pp .Nm caph_stream_rights may be used to initialize .Fa rights with the same rights that a stream would be limited to, as if .Fn caph_limit_stream had been invoked using the same .Fa flags . .Pp .Fn caph_cache_tzdata precaches all timezone data needed to use .Li libc local time functions. .Pp .Fn caph_cache_catpages caches Native Language Support (NLS) data. NLS data is used for localized error printing by .Xr strerror 3 and .Xr err 3 , among others. -.Ed .Sh SEE ALSO .Xr cap_enter 2 , .Xr cap_rights_limit 2 , .Xr rights 4 diff --git a/share/man/man7/networking.7 b/share/man/man7/networking.7 index 03e80793e98d..acd61f2864a7 100644 --- a/share/man/man7/networking.7 +++ b/share/man/man7/networking.7 @@ -1,94 +1,93 @@ .\"- .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" Copyright (c) 2024 Alexander Ziaee. Ohio. .\" .Dd April 17, 2024 .Dt "NETWORKING" 7 .Os .Sh NAME .Nm networking , .Nm wifi .Nd quickstart guide to connecting to a network .Sh DESCRIPTION In the following examples, it is assumed that we are connecting to Ethernet with the first interface found by the .Xr em 4 driver, and Wi-Fi with the first interface found by the .Xr iwn 4 driver, though your hardware will vary. .Sh EXAMPLES .Bl -tag -width 0n .It Sy Connecting to an Ethernet network with DHCP: .Bd -literal -offset 2n .Ic # dhclient em0 .Ed .It Sy Connecting to a cellular network with USB tethering: .Pp Load the USB tethering driver, .Xr urndis 4 : .Bd -literal -offset 2n .Ic # kldload urndis .Ed .Pp Ask for a DHCP lease on the USB tethering interface: .Bd -literal -offset 2n .Ic # dhclient ue0 .Ed .It Sy Connecting to a Wi-Fi network: .Pp Identify your Wi-Fi hardware: .Bd -literal -offset 2n .Ic % sysctl net.wlan.devices .Ed .Pp Configure your Wi-Fi hardware as wlan0 interface: -.Ed .Bd -literal -offset 2n .Ic # sysrc wlans_iwn0="wlan0" .Ed .Pp Set that interface to negotiate a DHCP lease with .Xr wpa_supplicant 8 : .Bd -literal -offset 2n .Ic # sysrc ifconfig_wlan0="WPA SYNCDHCP" .Ed .Pp Enter the details of the Wi-Fi network: .Bd -literal -offset 2n .Ic # wpa_passphrase \(dqmyssid\(dq \(dqmypassphrase\(dq >> wpa_supplicant.conf .Ed .Pp Restart the network interface daemon: .Bd -literal -offset 2n .Ic # service netif restart .Ed .Pp .It Sy Scanning for Wi-Fi networks: .Bd -literal -offset 2n .Ic % ifconfig wlan0 scan .Ed .It Sy Airplane mode: .Bd -literal -offset 2n .Ic # service netif stop .Ed .El .Sh SEE ALSO .Xr bsdconfig 8 , .Xr dhclient 8 , .Xr ifconfig 8 , .Xr wpa_passphrase 8 .Pp The Advanced Networking chapter of the .Fx Handbook. .Sh CAVEATS Shell Special Characters in the .Ar SSID or .Ar passphrase will need to be escaped for .Xr wpa_passphrase 8 , commonly using .Ql \e , see the manual page for your shell for more details. diff --git a/share/man/man9/domain.9 b/share/man/man9/domain.9 index eaa279cef996..dab8cff89e12 100644 --- a/share/man/man9/domain.9 +++ b/share/man/man9/domain.9 @@ -1,228 +1,227 @@ .\" .\" Copyright (C) 2001 Chad David . All rights reserved. .\" Copyright (C) 2022 Gleb Smirnoff .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice(s), this list of conditions and the following disclaimer as .\" the first lines of this file unmodified other than the possible .\" addition of one or more copyright notices. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice(s), this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``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 HOLDER(S) 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. .\" .Dd September 14, 2022 .Dt DOMAIN 9 .Os .Sh NAME .Nm domain , .Nm protosw .Nd "programming interface for kernel socket implementation" .Sh SYNOPSIS .In sys/param.h .In sys/kernel.h .In sys/protosw.h .In sys/domain.h .Ft void .Fn domain_add "struct domain *dom" .Ft void .Fn domain_remove "struct domain *dom" .Ft void .Fn DOMAIN_SET "domain" .Ft int .Fn protosw_register "struct domain *dom" "struct protosw *pr" .Ft int .Fn protosw_unregister "struct protosw *pr" .Sh DESCRIPTION The .Nm subsystem allows implementation of communication protocols that are exposed to the userland via the .Xr socket 2 API. When an application performs a .Fn socket "domain" "type" "protocol" syscall, the kernel searches for a .Nm matching the .Ar domain argument, then within this domain, searches for a protocol matching .Ar type . If the third argument, .Ar protocol , is not .Dv 0 , that value must also match. The structure found must implement certain methods, so that .Xr socket 2 API works for this particular kind of a socket. .Pp A minimal .Nm structure implementing a domain shall be initialized with sparse C99 initializer and has public fields as follows: .Bd -literal struct domain { /* * Mandatory fields. */ int dom_family; /* PF_xxx, first argument of socket(2) */ char *dom_name; /* text name of the domain */ u_int dom_nprotosw; /* length of dom_protosw[] */ /* * Following methods are optional. */ int (*dom_probe)(void); /* check for support */ struct rib_head *(*dom_rtattach)(uint32_t); /* init route table */ void (*dom_rtdetach)(struct rib_head *); /* clean up table */ void *(*dom_ifattach)(struct ifnet *); /* interface attach */ void (*dom_ifdetach)(struct ifnet *, void *);/* & detach callbacks */ int (*dom_ifmtu)(struct ifnet *); /* mtu change */ /* * Mandatory variable size array of pointers to protosw structs. */ struct protosw *dom_protosw[]; }; .Ed .Pp Each domain contains the .Va dom_protosw array of protocol switch structures .Pq Vt "struct protosw *" , one for each socket type supported. The array may have .Dv NULL spacers for loadable protocols. Sparse C99 initializers shall be used to initialize .Nm protosw structures. The structure has mandatory field .Va pr_type and mandatory .Va pr_attach method. The rest of the methods are optional, but a meaningful protocol should implement some. .Bd -literal struct protosw { short pr_type; /* second argument of socket(2) */ short pr_protocol; /* third argument of socket(2) or 0 */ short pr_flags; /* see protosw.h */ pr_soreceive_t *pr_soreceive; /* recv(2) */ pr_rcvd_t *pr_rcvd; /* soreceive_generic() if PR_WANTRCV */ pr_sosend_t *pr_sosend; /* send(2) */ pr_send_t *pr_send; /* send(2) via sosend_generic() */ pr_ready_t *pr_ready; /* sendfile/ktls readyness */ pr_sopoll_t *pr_sopoll; /* poll(2) */ pr_attach_t *pr_attach; /* creation: socreate(), sonewconn() */ pr_detach_t *pr_detach; /* destruction: sofree() */ pr_connect_t *pr_connect; /* connect(2) */ pr_disconnect_t *pr_disconnect; /* sodisconnect() */ pr_close_t *pr_close; /* close(2) */ pr_shutdown_t *pr_shutdown; /* shutdown(2) */ pr_abort_t *pr_abort; /* abrupt tear down: soabort() */ pr_aio_queue_t *pr_aio_queue; /* aio(9) */ pr_bind_t *pr_bind; /* bind(2) */ pr_bindat_t *pr_bindat; /* bindat(2) */ pr_listen_t *pr_listen; /* listen(2) */ pr_accept_t *pr_accept; /* accept(2) */ pr_connectat_t *pr_connectat; /* connectat(2) */ pr_connect2_t *pr_connect2; /* socketpair(2) */ pr_control_t *pr_control; /* ioctl(2) */ pr_rcvoob_t *pr_rcvoob; /* soreceive_rcvoob() */ pr_ctloutput_t *pr_ctloutput; /* control output (from above) */ pr_peeraddr_t *pr_peeraddr; /* getpeername(2) */ pr_sockaddr_t *pr_sockaddr; /* getsockname(2) */ pr_sense_t *pr_sense; /* stat(2) */ }; .Ed .Pp The following functions handle the registration of new domains and protocols. .Pp .Fn domain_add adds a new protocol domain to the system. In most cases .Fn domain_add is not called directly, instead .Fn DOMAIN_SET is used, which is a wrapper around .Fn SYSINIT macro. If the new domain has defined a .Va dom_probe routine, it is called first in .Fn domain_add to determine if the domain should be supported on the current system. If the probe routine returns a non-0 value, then the domain will not be added. Once a domain is added it cannot be completely unloaded. This is because there is no reference counting system in place to determine if there are any active references from sockets within that domain. However, the exprimental .Fn domain_remove exists, and unloadable domains may be supported in the future. .Pp .Fn protosw_register dynamically adds a protocol to a domain, if the latter has an empty slot in its .Va dom_protosw . Dynamically added protocol can later be unloaded with .Fn protosw_unregister . -.Ed .Sh RETURN VALUES The .Fn domain_add never fails, but it may not add a domain if its .Va dom_probe fails. .Pp The .Fn protosw_register function may fail if: .Bl -tag -width Er .It Bq Er EEXIST A protocol with the same value of .Va pr_type and .Va pr_protocol already exists in the domain. .It Bq Er ENOMEM The domain doesn't have any NULL slots in its .Va dom_protosw . .El .Sh SEE ALSO .Xr socket 2 , .Xr SYSINIT 9 .Sh HISTORY The .Nm subsystem first appeared in .Bx 4.3 as the part of the very first .Xr socket 2 API implementation. .Pp The .Nm subsystem and this manual page were significantly rewritten in .Fx 14 . .Sh AUTHORS This manual page was written by .An Chad David Aq Mt davidc@acns.ab.ca and .An Gleb Smirnoff Aq Mt glebius@FreeBSD.org .