diff --git a/lib/libc/gen/posix_spawn.3 b/lib/libc/gen/posix_spawn.3 index 55559ae7222b..278fee88463a 100644 --- a/lib/libc/gen/posix_spawn.3 +++ b/lib/libc/gen/posix_spawn.3 @@ -1,492 +1,492 @@ .\" Copyright (c) 2008 Ed Schouten .\" 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. .\" .\" Portions of this text are reprinted and reproduced in electronic form .\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- .\" Portable Operating System Interface (POSIX), The Open Group Base .\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of .\" Electrical and Electronics Engineers, Inc and The Open Group. In the .\" event of any discrepancy between this version and the original IEEE and .\" The Open Group Standard, the original IEEE and The Open Group Standard is .\" the referee document. The original Standard can be obtained online at .\" http://www.opengroup.org/unix/online.html. .\" .Dd March 4, 2024 .Dt POSIX_SPAWN 3 .Os .Sh NAME .Nm posix_spawn , .Nm posix_spawnp .Nd "spawn a process" .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In spawn.h .Ft int .Fo posix_spawn .Fa "pid_t *restrict pid" .Fa "const char *restrict path" .Fa "const posix_spawn_file_actions_t *file_actions" .Fa "const posix_spawnattr_t *restrict attrp" .Fa "char *const argv[restrict]" .Fa "char *const envp[restrict]" .Fc .Ft int .Fo posix_spawnp .Fa "pid_t *restrict pid" .Fa "const char *restrict file" .Fa "const posix_spawn_file_actions_t *file_actions" .Fa "const posix_spawnattr_t *restrict attrp" .Fa "char *const argv[restrict]" .Fa "char *const envp[restrict]" .Fc .Sh DESCRIPTION The .Fn posix_spawn and .Fn posix_spawnp functions create a new process (child process) from the specified process image. The new process image is constructed from a regular executable file called the new process image file. .Pp When a C program is executed as the result of this call, it is entered as a C-language function call as follows: .Bd -literal -offset indent int main(int argc, char *argv[]); .Ed .Pp where .Fa argc is the argument count and .Fa argv is an array of character pointers to the arguments themselves. In addition, the variable: .Bd -literal -offset indent extern char **environ; .Ed .Pp points to an array of character pointers to the environment strings. .Pp The argument .Fa argv is an array of character pointers to null-terminated strings. The last member of this array is a null pointer and is not counted in .Fa argc . These strings constitute the argument list available to the new process image. The value in .Fa argv Ns [0] should point to a filename that is associated with the process image being started by the .Fn posix_spawn or .Fn posix_spawnp function. .Pp The argument .Fa envp is an array of character pointers to null-terminated strings. These strings constitute the environment for the new process image. The environment array is terminated by a null pointer. .Pp The .Fa path argument to .Fn posix_spawn is a pathname that identifies the new process image file to execute. .Pp The .Fa file parameter to .Fn posix_spawnp is used to construct a pathname that identifies the new process image file. If the file parameter contains a slash character, the file parameter is used as the pathname for the new process image file. Otherwise, the path prefix for this file is obtained by a search of the directories passed as the environment variable .Dq Ev PATH . If this variable is not specified, the default path is set according to the .Dv _PATH_DEFPATH definition in .In paths.h , which is set to .Dq Ev /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin . .Pp If .Fa file_actions is a null pointer, then file descriptors open in the calling process remain open in the child process, except for those whose close-on-exec flag .Dv FD_CLOEXEC is set (see .Fn fcntl ) . For those file descriptors that remain open, all attributes of the corresponding open file descriptions, including file locks (see .Fn fcntl ) , remain unchanged. .Pp If .Fa file_actions is not NULL, then the file descriptors open in the child process are those open in the calling process as modified by the spawn file actions object pointed to by .Fa file_actions and the .Dv FD_CLOEXEC flag of each remaining open file descriptor after the spawn file actions have been processed. The effective order of processing the spawn file actions are: .Bl -enum .It The set of open file descriptors for the child process initially are the same set as is open for the calling process. All attributes of the corresponding open file descriptions, including file locks (see .Fn fcntl ) , remain unchanged. .It The signal mask, signal default actions, and the effective user and group IDs for the child process are changed as specified in the attributes object referenced by .Fa attrp . .It The file actions specified by the spawn file actions object are performed in the order in which they were added to the spawn file actions object. .It Any file descriptor that has its .Dv FD_CLOEXEC flag set (see .Fn fcntl ) is closed. .El .Pp The .Vt posix_spawnattr_t spawn attributes object type is defined in .In spawn.h . It contains the attributes defined below. .Pp If the .Dv POSIX_SPAWN_SETPGROUP flag is set in the spawn-flags attribute of the object referenced by .Fa attrp , and the spawn-pgroup attribute of the same object is non-zero, then the child's process group is as specified in the spawn-pgroup attribute of the object referenced by .Fa attrp . .Pp As a special case, if the .Dv POSIX_SPAWN_SETPGROUP flag is set in the spawn-flags attribute of the object referenced by .Fa attrp , and the spawn-pgroup attribute of the same object is set to zero, then the child is in a new process group with a process group ID equal to its process ID. .Pp If the .Dv POSIX_SPAWN_SETPGROUP flag is not set in the spawn-flags attribute of the object referenced by .Fa attrp , the new child process inherits the parent's process group. .Pp If the .Dv POSIX_SPAWN_SETSCHEDPARAM flag is set in the spawn-flags attribute of the object referenced by .Fa attrp , but .Dv POSIX_SPAWN_SETSCHEDULER is not set, the new process image initially has the scheduling policy of the calling process with the scheduling parameters specified in the spawn-schedparam attribute of the object referenced by .Fa attrp . .Pp If the .Dv POSIX_SPAWN_SETSCHEDULER flag is set in the spawn-flags attribute of the object referenced by .Fa attrp (regardless of the setting of the .Dv POSIX_SPAWN_SETSCHEDPARAM flag), the new process image initially has the scheduling policy specified in the spawn-schedpolicy attribute of the object referenced by .Fa attrp and the scheduling parameters specified in the spawn-schedparam attribute of the same object. .Pp The .Dv POSIX_SPAWN_RESETIDS flag in the spawn-flags attribute of the object referenced by .Fa attrp governs the effective user ID of the child process. If this flag is not set, the child process inherits the parent process' effective user ID. If this flag is set, the child process' effective user ID is reset to the parent's real user ID. In either case, if the set-user-ID mode bit of the new process image file is set, the effective user ID of the child process becomes that file's owner ID before the new process image begins execution. .Pp The .Dv POSIX_SPAWN_RESETIDS flag in the spawn-flags attribute of the object referenced by .Fa attrp also governs the effective group ID of the child process. If this flag is not set, the child process inherits the parent process' effective group ID. If this flag is set, the child process' effective group ID is reset to the parent's real group ID. In either case, if the set-group-ID mode bit of the new process image file is set, the effective group ID of the child process becomes that file's group ID before the new process image begins execution. .Pp If the .Dv POSIX_SPAWN_SETSIGMASK flag is set in the spawn-flags attribute of the object referenced by .Fa attrp , the child process initially has the signal mask specified in the spawn-sigmask attribute of the object referenced by .Fa attrp . .Pp If the .Dv POSIX_SPAWN_SETSIGDEF flag is set in the spawn-flags attribute of the object referenced by .Fa attrp , the signals specified in the spawn-sigdefault attribute of the same object are set to their default actions in the child process. Signals set to the default action in the parent process are set to the default action in the child process. .Pp Signals set to be caught by the calling process are set to the default action in the child process. .Pp Signals set to be ignored by the calling process image are set to be ignored by the child process, unless otherwise specified by the .Dv POSIX_SPAWN_SETSIGDEF flag being set in the spawn-flags attribute of the object referenced by .Fa attrp and the signals being indicated in the spawn-sigdefault attribute of the object referenced by .Fa attrp . .Pp The Address Space Layout Randomization for the newly spawned process can be disabled by specifying the .Dv POSIX_SPAWN_DISABLE_ASLR_NP flag in the spawn-flags attribute. This setting is inherited by future children of the child as well. See .Xr procctl 2 for more details. .Pp If the value of the .Fa attrp pointer is NULL, then the default values are used. .Pp All process attributes, other than those influenced by the attributes set in the object referenced by .Fa attrp as specified above or by the file descriptor manipulations specified in .Fa file_actions , appear in the new process image as though .Fn vfork had been called to create a child process and then .Fn execve had been called by the child process to execute the new process image. .Pp The implementation uses .Fn vfork , thus the fork handlers are not run when .Fn posix_spawn or .Fn posix_spawnp is called. .Sh RETURN VALUES Upon successful completion, .Fn posix_spawn and .Fn posix_spawnp return the process ID of the child process to the parent process, in the variable pointed to by a non-NULL .Fa pid argument, and return zero as the function return value. Otherwise, no child process is created, no value is stored into the variable pointed to by .Fa pid , and an error number is returned as the function return value to indicate the error. If the .Fa pid argument is a null pointer, the process ID of the child is not returned to the caller. .Sh ERRORS .Bl -enum .It If .Fn posix_spawn and .Fn posix_spawnp fail for any of the reasons that would cause .Fn vfork or one of the .Nm exec to fail, an error value is returned as described by .Fn vfork and .Nm exec , respectively (or, if the error occurs after the calling process successfully returns, the child process exits with exit status 127). .It If .Nm POSIX_SPAWN_SETPGROUP is set in the spawn-flags attribute of the object referenced by attrp, and .Fn posix_spawn or .Fn posix_spawnp fails while changing the child's process group, an error value is returned as described by .Fn setpgid (or, if the error occurs after the calling process successfully returns, the child process exits with exit status 127). .It If .Nm POSIX_SPAWN_SETSCHEDPARAM is set and .Nm POSIX_SPAWN_SETSCHEDULER is not set in the spawn-flags attribute of the object referenced by attrp, then if .Fn posix_spawn or .Fn posix_spawnp fails for any of the reasons that would cause .Fn sched_setparam to fail, an error value is returned as described by .Fn sched_setparam (or, if the error occurs after the calling process successfully returns, the child process exits with exit status 127). .It If .Nm POSIX_SPAWN_SETSCHEDULER is set in the spawn-flags attribute of the object referenced by attrp, and if .Fn posix_spawn or .Fn posix_spawnp fails for any of the reasons that would cause .Fn sched_setscheduler to fail, an error value is returned as described by .Fn sched_setscheduler (or, if the error occurs after the calling process successfully returns, the child process exits with exit status 127). .It If the .Fa file_actions argument is not NULL, and specifies any dup2 or open actions to be performed, and if .Fn posix_spawn or .Fn posix_spawnp fails for any of the reasons that would cause .Fn dup2 or .Fn open to fail, an error value is returned as described by .Fn dup2 and .Fn open , respectively (or, if the error occurs after the calling process successfully returns, the child process exits with exit status 127). An open file action may, by itself, result in any of the errors described by .Fn dup2 , in addition to those described by .Fn open . This implementation ignores any errors from .Fn close , including trying to close a descriptor that is not open. The ignore extends to any errors from individual file descriptors .Fn close executed as part of the .Fn closefrom action. .El .Sh SEE ALSO .Xr close 2 , .Xr dup2 2 , .Xr execve 2 , .Xr fcntl 2 , .Xr open 2 , .Xr procctl 2 , .Xr sched_setparam 2 , .Xr sched_setscheduler 2 , .Xr setpgid 2 , .Xr vfork 2 , +.Xr posix_spawn_file_actions_addchdir_np 3 , .Xr posix_spawn_file_actions_addclose 3 , .Xr posix_spawn_file_actions_addclosefrom_np 3 , .Xr posix_spawn_file_actions_adddup2 3 , -.Xr posix_spawn_file_actions_addopen 3 , -.Xr posix_spawn_file_actions_addchdir_np 3 , .Xr posix_spawn_file_actions_addfchdir_np 3 , +.Xr posix_spawn_file_actions_addopen 3 , .Xr posix_spawn_file_actions_destroy 3 , .Xr posix_spawn_file_actions_init 3 , .Xr posix_spawnattr_destroy 3 , .Xr posix_spawnattr_getflags 3 , .Xr posix_spawnattr_getpgroup 3 , .Xr posix_spawnattr_getschedparam 3 , .Xr posix_spawnattr_getschedpolicy 3 , .Xr posix_spawnattr_getsigdefault 3 , .Xr posix_spawnattr_getsigmask 3 , .Xr posix_spawnattr_init 3 , .Xr posix_spawnattr_setflags 3 , .Xr posix_spawnattr_setpgroup 3 , .Xr posix_spawnattr_setschedparam 3 , .Xr posix_spawnattr_setschedpolicy 3 , .Xr posix_spawnattr_setsigdefault 3 , .Xr posix_spawnattr_setsigmask 3 .Sh STANDARDS The .Fn posix_spawn and .Fn posix_spawnp functions conform to .St -p1003.1-2001 , except that they ignore all errors from .Fn close . A future update of the Standard is expected to require that these functions not fail because a file descriptor to be closed (via .Fn posix_spawn_file_actions_addclose ) is not open. .Sh HISTORY The .Fn posix_spawn and .Fn posix_spawnp functions first appeared in .Fx 8.0 . .Sh AUTHORS .An \&Ed Schouten Aq Mt ed@FreeBSD.org diff --git a/lib/libc/gen/setproctitle.3 b/lib/libc/gen/setproctitle.3 index 15bafa23a982..087cbe4b84e9 100644 --- a/lib/libc/gen/setproctitle.3 +++ b/lib/libc/gen/setproctitle.3 @@ -1,139 +1,139 @@ .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" Copyright (c) 1995 Peter Wemm .\" .\" 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. .\" .\" The following requests are required for all man pages. .Dd November 28, 2022 .Dt SETPROCTITLE 3 .Os .Sh NAME .Nm setproctitle .Nm setproctitle_fast .Nd set process title .Sh SYNOPSIS .In unistd.h .Ft void .Fn setproctitle "const char *fmt" "..." .Ft void .Fn setproctitle_fast "const char *fmt" "..." .Sh DESCRIPTION The .Fn setproctitle library routine sets the process title that appears on the .Xr ps 1 command. The .Fn setproctitle_fast variant is optimized for high frequency updates, but may make the .Xr ps 1 command slightly slower by not updating the kernel cache of the program arguments. .Pp The title is set from the executable's name, followed by the result of a .Xr printf 3 style expansion of the arguments as specified by the .Va fmt argument. If the .Va fmt argument begins with a .Dq - character, the executable's name is skipped. .Pp If .Va fmt is NULL, the process title is restored. .Sh EXAMPLES To set the title on a daemon to indicate its activity: .Bd -literal -offset indent setproctitle("talking to %s", inet_ntoa(addr)); .Ed .Sh SEE ALSO .Xr ps 1 , .Xr w 1 , -.Xr setprogname 3 , .Xr kvm 3 , .Xr kvm_getargv 3 , -.Xr printf 3 +.Xr printf 3 , +.Xr setprogname 3 .Sh STANDARDS The .Fn setproctitle function is implicitly non-standard. Other methods of causing the .Xr ps 1 command line to change, including copying over the argv[0] string are also implicitly non-portable. It is preferable to use an operating system supplied .Fn setproctitle if present. .Pp Unfortunately, it is possible that there are other calling conventions to other versions of .Fn setproctitle , although none have been found by the author as yet. This is believed to be the predominant convention. .Pp It is thought that the implementation is compatible with other systems, including .Nx and .Bsx . .Sh HISTORY The .Fn setproctitle function first appeared in .Fx 2.2 . The .Fn setproctitle_fast function first appeared in .Fx 12 . Other operating systems have similar functions. .Sh AUTHORS .An -nosplit .An Peter Wemm Aq Mt peter@FreeBSD.org stole the idea from the .Sy "Sendmail 8.7.3" source code by .An Eric Allman Aq Mt eric@sendmail.org . .Sh BUGS Never pass a string with user-supplied data as a format without using .Ql %s . An attacker can put format specifiers in the string to mangle your stack, leading to a possible security hole. This holds true even if the string was built using a function like .Fn snprintf , as the resulting string may still contain user-supplied conversion specifiers for later interpolation by .Fn setproctitle . .Pp Always use the proper secure idiom: .Pp .Dl setproctitle("%s", string); diff --git a/lib/libc/string/bstring.3 b/lib/libc/string/bstring.3 index bb1a0505fafd..dc3034db1d6c 100644 --- a/lib/libc/string/bstring.3 +++ b/lib/libc/string/bstring.3 @@ -1,113 +1,112 @@ .\" Copyright (c) 1990, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" This code is derived from software contributed to Berkeley by .\" Chris Torek. .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)bstring.3 8.1 (Berkeley) 6/4/93 .\" .Dd December 5, 2023 .Dt BSTRING 3 .Os .Sh NAME .Nm bcmp , .Nm bcopy , .Nm bzero , .Nm memccpy , .Nm memchr , .Nm memcmp , .Nm memcpy , .Nm memmove , .Nm memset .Nd byte string operations .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In string.h .Ft int .Fn bcmp "const void *b1" "const void *b2" "size_t len" .Ft void .Fn bcopy "const void *src" "void *dst" "size_t len" .Ft void .Fn bzero "void *b" "size_t len" .Ft void * .Fn memchr "const void *b" "int c" "size_t len" .Ft int .Fn memcmp "const void *b1" "const void *b2" "size_t len" .Ft void * .Fo memccpy .Fa "void * restrict dst" .Fa "const void * restrict src" .Fa "int c" .Fa "size_t len" .Fc .Ft void * .Fn memcpy "void *dst" "const void *src" "size_t len" .Ft void * .Fn memmove "void *dst" "const void *src" "size_t len" .Ft void * .Fn memset "void *b" "int c" "size_t len" .Sh DESCRIPTION These functions operate on variable length strings of bytes. They do not check for terminating null bytes as the routines listed in .Xr string 3 do. .Pp See the specific manual pages for more information. .Sh SEE ALSO .Xr bcmp 3 , .Xr bcopy 3 , .Xr bzero 3 , .Xr memccpy 3 , .Xr memchr 3 , .Xr memcmp 3 , -.Xr memccpy 3 , .Xr memcpy 3 , .Xr memmove 3 , .Xr memset 3 .Sh STANDARDS The functions .Fn memchr , .Fn memcmp , .Fn memcpy , .Fn memmove , and .Fn memset conform to .St -isoC . .Sh HISTORY The functions .Fn bzero and .Fn memccpy appeared in .Bx 4.3 ; the functions .Fn bcmp , .Fn bcopy , appeared in .Bx 4.2 . diff --git a/lib/libc/sys/fhreadlink.2 b/lib/libc/sys/fhreadlink.2 index 222142de223e..2d8db95685da 100644 --- a/lib/libc/sys/fhreadlink.2 +++ b/lib/libc/sys/fhreadlink.2 @@ -1,95 +1,95 @@ .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" Copyright (c) 2018 Gandi .\" .\" 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. .\" .Dd November 30, 2022 .Dt FHREADLINK 2 .Os .Sh NAME .Nm fhreadlink .Nd read value of a symbolic link .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/param.h .In sys/mount.h .Ft int .Fn fhreadlink "fhandle_t *fhp" "char *buf" "size_t bufsize" .Sh DESCRIPTION The .Fn fhreadlink system call places the contents of the symbolic link .Fa fhp in the buffer .Fa buf , which has size .Fa bufsiz . The .Fn fhreadlink system call does not append a .Dv NUL character to .Fa buf . .Pp .Sh RETURN VALUES The call returns the count of characters placed in the buffer if it succeeds, or a \-1 if an error occurs, placing the error code in the global variable .Va errno . .Sh ERRORS The .Fn readlink system call will fail if: .Bl -tag -width Er .It Bq Er ENOENT The named file does not exist. .It Bq Er ELOOP Too many symbolic links were encountered in translating the file handle .Fa fhp . .It Bq Er EINVAL The named file is not a symbolic link. .It Bq Er EIO An I/O error occurred while reading from the file system. .It Bq Er EINTEGRITY Corrupted data was detected while reading from the file system. .It Bq Er EFAULT The .Fa buf argument extends outside the process's allocated address space. .It Bq Er ESTALE The file handle .Fa fhp is no longer valid .El .Sh SEE ALSO -.Xr fhstat 2 , .Xr fhlink 2 , +.Xr fhstat 2 .Sh HISTORY The .Fn fhreadlink system call first appeared in .Fx 12.1 . diff --git a/lib/libc/sys/getrlimitusage.2 b/lib/libc/sys/getrlimitusage.2 index 2e3dc744ab23..e82e7b4443fd 100644 --- a/lib/libc/sys/getrlimitusage.2 +++ b/lib/libc/sys/getrlimitusage.2 @@ -1,100 +1,100 @@ .\" Copyright (c) 2024 The FreeBSD Foundation, Inc. .\" .\" This documentation was written by .\" Konstantin Belousov 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. .\" 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 September 27, 2024 .Dt GETRLIMITUSAGE 2 .Os .Sh NAME .Nm getrlimitusage .Nd Query usage of the current process' limited resources .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/resource.h .Ft int .Fn getrlimitusage "unsigned which" "int flags" "rlim_t *res" .Sh DESCRIPTION The .Nm system call allows the process to query current consumption of the resources limited by the .Xr setrlimit 2 call. .Pp The .Fa which argument specifies the resource, same as for .Xr getrlimit 2 and .Xr setrlimit 2 calls, see their man page for the list of enforced resource types. .Pp The .Fa flags argument modifies the behavior of the call in the following ways: .Bl -tag -width GETRLIMITUSAGE_XXXXXX .It Va GETRLIMITUSAGE_EUID Query the resource usage for user identified by effective UID of the process, instead of the real UID (which is default for accounting). .El .Sh RETURN VALUES .Rv -std .Sh ERRORS The .Fn getrlimitusage system call will fail if: .Bl -tag -width Er .It Bq Er EFAULT The address specified for .Fa res is invalid. .It Bq Er EINVAL The resource specified to .Fn getrlimitusage in the .Fa which argument is unknown. .It Bq Er ENXIO The resource specified to .Fn getrlimitusage in the .Fa which argument is not accounted, but only enforced in specific situations. Examples of such resources are .Va RLIMIT_FSIZE and .Va RLIMIT_CORE . .El .Sh SEE ALSO .Xr procstat 1 , .Xr getrlimit 2 , -.Xr setrlimit 2 . +.Xr setrlimit 2 .Sh HISTORY The .Fn getrlimitusage system call appeared in .Bx 15.0 . diff --git a/lib/libc/sys/socket.2 b/lib/libc/sys/socket.2 index 3e2206aefe72..9c2b2f8f925b 100644 --- a/lib/libc/sys/socket.2 +++ b/lib/libc/sys/socket.2 @@ -1,351 +1,351 @@ .\" Copyright (c) 1983, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" From: @(#)socket.2 8.1 (Berkeley) 6/4/93 .\" .Dd January 15, 2023 .Dt SOCKET 2 .Os .Sh NAME .Nm socket .Nd create an endpoint for communication .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/socket.h .Ft int .Fn socket "int domain" "int type" "int protocol" .Sh DESCRIPTION The .Fn socket system call creates an endpoint for communication and returns a descriptor. .Pp The .Fa domain argument specifies a communications domain within which communication will take place; this selects the protocol family which should be used. These families are defined in the include file .In sys/socket.h . The currently understood formats are: .Pp .Bd -literal -offset indent -compact PF_LOCAL Host-internal protocols (alias for PF_UNIX), PF_UNIX Host-internal protocols, PF_INET Internet version 4 protocols, PF_INET6 Internet version 6 protocols, PF_DIVERT Firewall packet diversion/re-injection, PF_ROUTE Internal routing protocol, PF_KEY Internal key-management function, PF_NETGRAPH Netgraph sockets, PF_NETLINK Netlink protocols, PF_BLUETOOTH Bluetooth protocols, PF_INET_SDP OFED socket direct protocol (IPv4), AF_HYPERV HyperV sockets .Ed .Pp Each protocol family is connected to an address family, which has the same name except that the prefix is .Dq Dv AF_ in place of .Dq Dv PF_ . Other protocol families may be also defined, beginning with .Dq Dv PF_ , with corresponding address families. .Pp The socket has the indicated .Fa type , which specifies the semantics of communication. Currently defined types are: .Pp .Bd -literal -offset indent -compact SOCK_STREAM Stream socket, SOCK_DGRAM Datagram socket, SOCK_RAW Raw-protocol interface, SOCK_SEQPACKET Sequenced packet stream .Ed .Pp A .Dv SOCK_STREAM type provides sequenced, reliable, two-way connection based byte streams. An out-of-band data transmission mechanism may be supported. A .Dv SOCK_DGRAM socket supports datagrams (connectionless, unreliable messages of a fixed (typically small) maximum length). A .Dv SOCK_SEQPACKET socket may provide a sequenced, reliable, two-way connection-based data transmission path for datagrams of fixed maximum length; a consumer may be required to read an entire packet with each read system call. This facility may have protocol-specific properties. .Dv SOCK_RAW sockets provide access to internal network protocols and interfaces. The .Dv SOCK_RAW type is available only to the super-user and is described in .Xr ip 4 and .Xr ip6 4 . .Pp Additionally, the following flags are allowed in the .Fa type argument: .Pp .Bd -literal -offset indent -compact SOCK_CLOEXEC Set close-on-exec on the new descriptor, SOCK_NONBLOCK Set non-blocking mode on the new socket .Ed .Pp The .Fa protocol argument specifies a particular protocol to be used with the socket. Normally only a single protocol exists to support a particular socket type within a given protocol family. However, it is possible that many protocols may exist, in which case a particular protocol must be specified in this manner. The protocol number to use is particular to the .Dq "communication domain" in which communication is to take place; see .Xr protocols 5 . .Pp The .Fa protocol argument may be set to zero (0) to request the default implementation of a socket type for the protocol, if any. .Pp Sockets of type .Dv SOCK_STREAM are full-duplex byte streams, similar to pipes. A stream socket must be in a .Em connected state before any data may be sent or received on it. A connection to another socket is created with a .Xr connect 2 system call. Once connected, data may be transferred using .Xr read 2 and .Xr write 2 calls or some variant of the .Xr send 2 and .Xr recv 2 functions. (Some protocol families, such as the Internet family, support the notion of an .Dq implied connect , which permits data to be sent piggybacked onto a connect operation by using the .Xr sendto 2 system call.) When a session has been completed a .Xr close 2 may be performed. Out-of-band data may also be transmitted as described in .Xr send 2 and received as described in .Xr recv 2 . .Pp The communications protocols used to implement a .Dv SOCK_STREAM ensure that data is not lost or duplicated. If a piece of data for which the peer protocol has buffer space cannot be successfully transmitted within a reasonable length of time, then the connection is considered broken and calls will indicate an error with -1 returns and with .Er ETIMEDOUT as the specific code in the global variable .Va errno . The protocols optionally keep sockets .Dq warm by forcing transmissions roughly every minute in the absence of other activity. An error is then indicated if no response can be elicited on an otherwise idle connection for an extended period (e.g.\& 5 minutes). By default, a .Dv SIGPIPE signal is raised if a process sends on a broken stream, but this behavior may be inhibited via .Xr setsockopt 2 . .Pp .Dv SOCK_SEQPACKET sockets employ the same system calls as .Dv SOCK_STREAM sockets. The only difference is that .Xr read 2 calls will return only the amount of data requested, and any remaining in the arriving packet will be discarded. .Pp .Dv SOCK_DGRAM and .Dv SOCK_RAW sockets allow sending of datagrams to correspondents named in .Xr send 2 calls. Datagrams are generally received with .Xr recvfrom 2 , which returns the next datagram with its return address. .Pp An .Xr fcntl 2 system call can be used to specify a process group to receive a .Dv SIGURG signal when the out-of-band data arrives. It may also enable non-blocking I/O and asynchronous notification of I/O events via .Dv SIGIO . .Pp The operation of sockets is controlled by socket level .Em options . These options are defined in the file .In sys/socket.h . The .Xr setsockopt 2 and .Xr getsockopt 2 system calls are used to set and get options, respectively. .Sh RETURN VALUES A -1 is returned if an error occurs, otherwise the return value is a descriptor referencing the socket. .Sh ERRORS The .Fn socket system call fails if: .Bl -tag -width Er .It Bq Er EACCES Permission to create a socket of the specified type and/or protocol is denied. .It Bq Er EAFNOSUPPORT The address family (domain) is not supported or the specified domain is not supported by this protocol family. .It Bq Er EMFILE The per-process descriptor table is full. .It Bq Er ENFILE The system file table is full. .It Bq Er ENOBUFS Insufficient buffer space is available. The socket cannot be created until sufficient resources are freed. .It Bq Er EPERM User has insufficient privileges to carry out the requested operation. .It Bq Er EPROTONOSUPPORT The protocol type or the specified protocol is not supported within this domain. .It Bq Er EPROTOTYPE The socket type is not supported by the protocol. .El .Sh SEE ALSO .Xr accept 2 , .Xr bind 2 , .Xr connect 2 , -.Xr divert 4 , .Xr getpeername 2 , .Xr getsockname 2 , .Xr getsockopt 2 , .Xr ioctl 2 , -.Xr ip 4 , -.Xr ip6 4 , .Xr listen 2 , .Xr read 2 , .Xr recv 2 , .Xr select 2 , .Xr send 2 , .Xr shutdown 2 , .Xr socketpair 2 , .Xr write 2 , .Xr CMSG_DATA 3 , .Xr getprotoent 3 , +.Xr divert 4 , +.Xr ip 4 , +.Xr ip6 4 , .Xr netgraph 4 , .Xr protocols 5 .Rs .%T "An Introductory 4.3 BSD Interprocess Communication Tutorial" .%B PS1 .%N 7 .Re .Rs .%T "BSD Interprocess Communication Tutorial" .%B PS1 .%N 8 .Re .Sh STANDARDS The .Fn socket function conforms to .St -p1003.1-2008 . The .Tn POSIX standard specifies only the .Dv AF_INET , .Dv AF_INET6 , and .Dv AF_UNIX constants for address families, and requires the use of .Dv AF_* constants for the .Fa domain argument of .Fn socket . The .Dv SOCK_CLOEXEC flag is expected to conform to the next revision of the .Tn POSIX standard. The .Dv SOCK_RDM .Fa type , the .Dv PF_* constants, and other address families are .Fx extensions. .Sh HISTORY The .Fn socket system call appeared in .Bx 4.2 . diff --git a/lib/libc/sys/thr_kill.2 b/lib/libc/sys/thr_kill.2 index a18e53e61008..3252de13ed8c 100644 --- a/lib/libc/sys/thr_kill.2 +++ b/lib/libc/sys/thr_kill.2 @@ -1,137 +1,137 @@ .\" Copyright (c) 2016 The FreeBSD Foundation, Inc. .\" .\" This documentation was written by .\" Konstantin Belousov 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. .\" 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 May 5, 2020 .Dt THR_kill 2 .Os .Sh NAME .Nm thr_kill .Nd send signal to thread .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/thr.h .Ft int .Fn thr_kill "long id" "int sig" .Ft int .Fn thr_kill2 "pid_t pid" "long id" "int sig" .Sh DESCRIPTION The .Fn thr_kill and .Fn thr_kill2 system calls allow sending a signal, specified by the .Fa sig argument, to some threads in a process. For the .Fn thr_kill function, signalled threads are always limited to the current process. For the .Fn thr_kill2 function, the .Fa pid argument specifies the process with threads to be signalled. .Pp The .Fa id argument specifies which threads get the signal. If .Fa id is equal to \-1, all threads in the specified process are signalled. Otherwise, only the thread with the thread identifier equal to the argument is signalled. .Pp The .Fa sig argument defines the delivered signal. It must be a valid signal number or zero. In the latter case no signal is actually sent, and the call is used to verify the liveness of the thread. .Pp The signal is delivered with .Dv siginfo .Dv si_code set to .Dv SI_LWP . .Sh RETURN VALUES If successful, .Fn thr_kill and .Fn thr_kill2 will return zero, otherwise \-1 is returned, and .Va errno is set to indicate the error. .Sh ERRORS The .Fn thr_kill and .Fn thr_kill2 operations return the following errors: .Bl -tag -width Er .It Bq Er EINVAL The .Fa sig argument is not zero and does not specify valid signal. .It Bq Er ESRCH The specified process or thread was not found. .El .Pp Additionally, the .Fn thr_kill2 may return the following errors: .Bl -tag -width Er .It Bq Er EPERM The current process does not have sufficient privilege to check existence or send a signal to the specified process. .El .Sh SEE ALSO +.Xr _umtx_op 2 , .Xr kill 2 , .Xr thr_exit 2 , .Xr thr_new 2 , .Xr thr_self 2 , .Xr thr_set_name 2 , -.Xr _umtx_op 2 , .Xr pthread_kill 3 , .Xr signal 3 .Sh STANDARDS The .Fn thr_kill and .Fn thr_kill2 system calls are non-standard and are used by the .Lb libthr to implement .St -p1003.1-2001 .Xr pthread 3 functionality. .Sh HISTORY The .Fn thr_kill and .Fn thr_kill2 system calls first appeared in .Fx 5.2 . diff --git a/lib/libc/x86/sys/pkru.3 b/lib/libc/x86/sys/pkru.3 index 2bcb6a64baaa..7b5ceb025d62 100644 --- a/lib/libc/x86/sys/pkru.3 +++ b/lib/libc/x86/sys/pkru.3 @@ -1,203 +1,203 @@ .\" Copyright (c) 2019 The FreeBSD Foundation, Inc. .\" .\" This documentation was written by .\" Konstantin Belousov 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. .\" 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 February 16, 2019 .Dt PKRU 3 .Os .Sh NAME .Nm Protection Key Rights for User pages .Nd provide fast user-managed key-based access control for pages .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In machine/sysarch.h .Ft int .Fn x86_pkru_get_perm "unsigned int keyidx" "int *access" "int *modify" .Ft int .Fn x86_pkru_set_perm "unsigned int keyidx" "int access" "int modify" .Ft int .Fo x86_pkru_protect_range .Fa "void *addr" .Fa "unsigned long len" .Fa "unsigned int keyidx" .Fa "int flag" .Fc .Ft int .Fn x86_pkru_unprotect_range "void *addr" "unsigned long len" .Sh DESCRIPTION The protection keys feature provides an additional mechanism, besides the normal page permissions as established by .Xr mmap 2 and .Xr mprotect 2 , to control access to user-mode addresses. The mechanism gives safety measures which can be used to avoid incidental read or modification of sensitive memory, or as a debugging feature. It cannot guard against conscious accesses since permissions are user-controllable. .Pp If supported by hardware, each mapped user linear address has an associated 4-bit protection key. A new per-thread PKRU hardware register determines, for each protection key, whether user-mode addresses with that protection key may be read or written. .Pp Only one key may apply to a given range at a time. The default protection key index is zero, it is used even if no key was explicitly assigned to the address, or if the key was removed. .Pp The protection prevents the system from accessing user addresses as well as the user applications. When a system call was unable to read or write user memory due to key protection, it returns the .Er EFAULT error code. Note that some side effects may have occurred if this error is reported. .Pp Protection keys require that the system uses 4-level paging (also called long mode), which means that it is only available on amd64 system. Both 64-bit and 32-bit applications can use protection keys. More information about the hardware feature is provided in the IA32 Software Developer's Manual published by Intel Corp. .Pp The key indexes written into the page table entries are managed by the .Fn sysarch syscall. Per-key permissions are managed using the user-mode instructions .Em RDPKRU and .Em WRPKRU . The system provides convenient library helpers for both the syscall and the instructions, described below. .Pp The .Fn x86_pkru_protect_range function assigns key .Fa keyidx to the range starting at .Fa addr and having length .Fa len . Starting address is truncated to the page start, and the end is rounded up to the end of the page. After a successful call, the range has the specified key assigned, even if the key is zero and it did not change the page table entries. .Pp The .Fa flags argument takes the logical OR of the following values: .Bl -tag -width .It Bq Va AMD64_PKRU_EXCL Only assign the key if the range does not have any other keys assigned (including the zero key). You must first remove any existing key with .Fn x86_pkru_unprotect_range in order for this request to succeed. If the .Va AMD64_PKRU_EXCL flag is not specified, .Fn x86_pkru_protect_range replaces any existing key. .It Bq Va AMD64_PKRU_PERSIST The keys assigned to the range are persistent. They are re-established when the current mapping is destroyed and a new mapping is created in any sub-range of the specified range. You must use a .Fn x86_pkru_unprotect_range call to forget the key. .El .Pp The .Fn x86_pkru_unprotect_range function removes any keys assigned to the specified range. Existing mappings are changed to use key index zero in page table entries. Keys are no longer considered installed for all mappings in the range, for the purposes of .Fn x86_pkru_protect_range with the .Va AMD64_PKRU_EXCL flag. .Pp The .Fn x86_pkru_get_perm function returns access rights for the key specified by the .Fa keyidx argument. If the value pointed to by .Fa access is zero after the call, no read or write permissions is granted for mappings which are assigned the key .Fa keyidx . If .Fa access is not zero, read access is permitted. The non-zero value of the variable pointed to by the .Fa modify argument indicates that write access is permitted. .Pp Conversely, the .Fn x86_pkru_set_perm establishes the access and modify permissions for the given key index as specified by its arguments. .Sh RETURN VALUES .Rv -std .Sh ERRORS .Bl -tag -width Er .It Bq Er EOPNOTSUPP The hardware does not support protection keys. .It Bq Er EINVAL The supplied key index is invalid (greater than 15). .It Bq Er EINVAL The supplied .Fa flags argument for .Fn x86_pkru_protect_range has reserved bits set. .It Bq Er EFAULT The supplied address range does not completely fit into the user-managed address range. .It Bq Er ENOMEM The memory shortage prevents the completion of the operation. .It Bq Er EBUSY The .Va AMD64_PKRU_EXCL flag was specified for .Fn x86_pkru_protect_range and the range already has defined protection keys. .El .Sh SEE ALSO .Xr mmap 2 , .Xr mprotect 2 , .Xr munmap 2 , -.Xr sysarch 2 . +.Xr sysarch 2 .Sh STANDARDS The .Nm functions are non-standard and first appeared in .Fx 13.0 . diff --git a/lib/libjail/jail.3 b/lib/libjail/jail.3 index 3c3c24d75dc4..820e378eb625 100644 --- a/lib/libjail/jail.3 +++ b/lib/libjail/jail.3 @@ -1,282 +1,282 @@ .\" Copyright (c) 2009 James Gritton. .\" 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. .\" .Dd August 31, 2010 .Dt JAIL 3 .Os .Sh NAME .Nm jail_getid , .Nm jail_getname , .Nm jail_setv , .Nm jail_getv , .Nm jailparam_all , .Nm jailparam_init , .Nm jailparam_import , .Nm jailparam_import_raw , .Nm jailparam_set , .Nm jailparam_get , .Nm jailparam_export , .Nm jailparam_free .Nd create and manage system jails .Sh LIBRARY .Lb libjail .Sh SYNOPSIS .In sys/param.h .In sys/jail.h .In jail.h .Vt extern char jail_errmsg[] ; .Ft int .Fn jail_getid "const char *name" .Ft char * .Fn jail_getname "int jid" .Ft int .Fn jail_setv "int flags" ... .Ft int .Fn jail_getv "int flags" ... .Ft int .Fn jailparam_all "struct jailparam **jpp" .Ft int .Fn jailparam_init "struct jailparam *jp" "const char *name" .Ft int .Fn jailparam_import "struct jailparam *jp" "const char *value" .Ft int .Fn jailparam_import_raw "struct jailparam *jp" "void *value" "size_t valuelen" .Ft int .Fn jailparam_set "struct jailparam *jp" "unsigned njp" "int flags" .Ft int .Fn jailparam_get "struct jailparam *jp" "unsigned njp" "int flags" .Ft char * .Fn jailparam_export "struct jailparam *jp" .Ft void .Fn jailparam_free "struct jailparam *jp" "unsigned njp" .Sh DESCRIPTION The .Nm jail library is an interface to the .Xr jail_set 2 and .Xr jail_get 2 system calls, and the .Va security.jail.param MIB entries. It simplifies the conversion of prison parameters between internal and string formats, allowing the setting and querying of prisons without knowing the parameter formats. .Pp The .Fn jail_getid function returns the JID of the jail identified by .Fa name , or \-1 if the jail does not exist. .Pp The .Fn jail_getname function returns the name of the jail identified by .Fa jid , or .Dv NULL if the jail does not exist. .Pp The .Fn jail_setv function takes a null-terminated list of name and value strings, and passes it to .Xr jail_set 2 . .Pp The .Fn jail_getv function takes a null-terminated list of name and value strings, and passes it to .Xr jail_get 2 . It is the caller's responsibility to ensure that the value strings point to buffers large enough to hold the string representation of the returned parameters. .Pp The .Fn jailparam_all function sets .Fa jpp to a list of all known jail parameters, and returns the number of parameters. The list should later be freed with .Fn jailparam_free and .Xr free 3 . .Pp The .Fn jailparam_init function clears a parameter record and copies the .Fa name to it. After use, it should be freed with .Fn jailparam_free . .Pp The .Fn jailparam_import function adds a .Fa value to a parameter record, converting it from a string to its native form. The .Fn jailparam_import_raw function adds a value without performing any conversion. .Pp The .Fn jailparam_set function passes a list of parameters to .Xr jail_set 2 . The parameters are assumed to have been created with .Fn jailparam_init and .Fn jailparam_import . .Pp The .Fn jailparam_get function passes a list of parameters to .Xr jail_get 2 . The parameters are assumed to have been created with .Fn jailparam_init or .Fn jailparam_list , with one parameter (the key) having been given a value with .Fn jailparam_import . .Pp The .Fn jailparam_export function returns the string equivalent of a parameter value. The returned string should be freed after use. .Pp The .Fn jailparam_free function frees the stored names and values in a parameter list. If the list itself came from .Fn jailparam_all , it should be freed as well. .Sh RETURN VALUES The .Fn jail_getid , .Fn jail_setv , .Fn jail_getv , .Fn jailparam_set and .Fn jailparam_get functions return a JID on success, or \-1 on error. .Pp The .Fn jail_getname and .Fn jailparam_export functions return a dynamically allocated string on success, or .Dv NULL on error. .Pp The .Fn jailparam_all function returns the number of parameters on success, or \-1 on error. .Pp The .Fn jailparam_init , .Fn jailparam_import and .Fn jailparam_import_raw functions return 0 on success, or \-1 on error. .Pp Whenever an error is returned, .Va errno is set, and the global string .Va jail_errmsg contains a description of the error, possibly from .Xr jail_set 2 or .Xr jail_get 2 . .Sh EXAMPLES Set the hostname of jail .Dq foo to .Dq foo.bar : .Bd -literal -offset indent jail_setv(JAIL_UPDATE, "name", "foo", "host.hostname", "foo.bar", NULL); .Ed .Pp OR: .Bd -literal -offset indent struct jailparam params[2]; jailparam_init(¶ms[0], "name"); jailparam_import(¶ms[0], "foo"); jailparam_init(¶ms[1], "host.hostname"); jailparam_import(¶ms[1], "foo.bar"); jailparam_set(params, 2, JAIL_UPDATE); jailparam_free(params, 2); .Ed .Pp Retrieve the hostname of jail .Dq foo : .Bd -literal -offset indent char hostname[MAXHOSTNAMELEN]; jail_getv(0, "name", "foo", "host.hostname", hostname, NULL); .Ed .Pp OR: .Bd -literal -offset indent struct jailparam params[2]; jailparam_init(¶ms[0], "name"); jailparam_import(¶ms[0], "foo"); jailparam_init(¶ms[1], "host.hostname"); jailparam_get(params, 2, 0); hostname = jailparam_export(¶ms[1]); jailparam_free(params, 2); \&... free(hostname); .Ed .Sh ERRORS The .Nm jail functions may return errors from .Xr jail_set 2 , .Xr jail_get 2 , .Xr malloc 3 or .Xr sysctl 3 . In addition, the following errors are possible: .Bl -tag -width Er .It Bq Er EINVAL A parameter value cannot be converted from the passed string to its internal form. .It Bq Er ENOENT The named parameter does not exist. .It Bq Er ENOENT A parameter is of an unknown type. .El .Sh SEE ALSO .Xr jail 2 , -.Xr jail 3lua , .Xr sysctl 3 , +.Xr jail 3lua , .Xr jail 8 .Sh HISTORY The .Nm jail library first appeared in .Fx 8.0 . .Sh AUTHORS .An James Gritton diff --git a/lib/libpam/modules/pam_chroot/pam_chroot.8 b/lib/libpam/modules/pam_chroot/pam_chroot.8 index e65c513b7b77..1f614264ba8e 100644 --- a/lib/libpam/modules/pam_chroot/pam_chroot.8 +++ b/lib/libpam/modules/pam_chroot/pam_chroot.8 @@ -1,92 +1,92 @@ .\" Copyright (c) 2003 Networks Associates Technology, Inc. .\" All rights reserved. .\" .\" Portions of this software were developed for the FreeBSD Project by .\" ThinkSec AS and NAI Labs, the Security Research Division of Network .\" Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 .\" ("CBOSS"), as part of the DARPA CHATS research program. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. The name of the author may not be used to endorse or promote .\" products derived from this software without specific prior written .\" permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd February 10, 2003 .Dt PAM_CHROOT 8 .Os .Sh NAME .Nm pam_chroot .Nd Chroot PAM module .Sh SYNOPSIS .Op Ar service-name .Ar module-type .Ar control-flag .Pa pam_chroot .Op Ar arguments .Sh DESCRIPTION The chroot service module for PAM chroots users into either a predetermined directory or one derived from their home directory. If a user's home directory as specified in the .Vt passwd structure returned by .Xr getpwnam 3 contains the string .Dq Li /./ , the portion of the directory name to the left of that string is used as the chroot directory, and the portion to the right will be the current working directory inside the chroot tree. Otherwise, the directories specified by the .Cm dir and .Cm cwd options (see below) are used. .Bl -tag -width ".Cm also_root" .It Cm also_root Do not hold user ID 0 exempt from the chroot requirement. .It Cm always Report a failure if a chroot directory could not be derived from the user's home directory, and the .Cm dir option was not specified. .It Cm cwd Ns = Ns Ar directory Specify the directory to .Xr chdir 2 into after a successful .Xr chroot 2 call. .It Cm dir Ns = Ns Ar directory Specify the chroot directory to use if one could not be derived from the user's home directory. .El .Sh SEE ALSO -.Xr pam.conf 5 , -.Xr pam 3 +.Xr pam 3 , +.Xr pam.conf 5 .Sh AUTHORS The .Nm module and this manual page were developed for the .Fx Project by ThinkSec AS and NAI Labs, the Security Research Division of Network Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035 .Pq Dq CBOSS , as part of the DARPA CHATS research program. diff --git a/lib/libpam/modules/pam_deny/pam_deny.8 b/lib/libpam/modules/pam_deny/pam_deny.8 index 530bae05c1f3..5d70bde200d9 100644 --- a/lib/libpam/modules/pam_deny/pam_deny.8 +++ b/lib/libpam/modules/pam_deny/pam_deny.8 @@ -1,78 +1,78 @@ .\" Copyright (c) 2001 Mark R V Murray .\" 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. .\" .Dd July 7, 2001 .Dt PAM_DENY 8 .Os .Sh NAME .Nm pam_deny .Nd Deny PAM module .Sh SYNOPSIS .Op Ar service-name .Ar module-type .Ar control-flag .Pa pam_deny .Op Ar options .Sh DESCRIPTION The Deny authentication service module for PAM, .Nm provides functionality for all the PAM categories: authentication, account management, session management and password management. In terms of the .Ar module-type parameter, these are the .Dq Li auth , .Dq Li account , .Dq Li session , and .Dq Li password features. .Pp The Deny module will universally deny all requests. It is primarily of use during testing, and to .Dq null-out unwanted functionality. .Pp The following options may be passed to the module: .Bl -tag -width ".Cm no_warn" .It Cm debug .Xr syslog 3 debugging information at .Dv LOG_DEBUG level. .It Cm no_warn suppress warning messages to the user. These messages include reasons why the user's authentication attempt was declined. .El .Sh SEE ALSO +.Xr pam 3 , .Xr syslog 3 , -.Xr pam.conf 5 , -.Xr pam 3 +.Xr pam.conf 5 diff --git a/lib/libpam/modules/pam_echo/pam_echo.8 b/lib/libpam/modules/pam_echo/pam_echo.8 index c38d4d8cee55..19c083917bbf 100644 --- a/lib/libpam/modules/pam_echo/pam_echo.8 +++ b/lib/libpam/modules/pam_echo/pam_echo.8 @@ -1,91 +1,91 @@ .\" Copyright (c) 2001,2003 Networks Associates Technology, Inc. .\" All rights reserved. .\" .\" Portions of this software were developed for the FreeBSD Project by .\" ThinkSec AS and NAI Labs, the Security Research Division of Network .\" Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 .\" ("CBOSS"), as part of the DARPA CHATS research program. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. The name of the author may not be used to endorse or promote .\" products derived from this software without specific prior written .\" permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd February 6, 2003 .Dt PAM_ECHO 8 .Os .Sh NAME .Nm pam_echo .Nd Echo PAM module .Sh SYNOPSIS .Op Ar service-name .Ar module-type .Ar control-flag .Pa pam_echo .Op Ar arguments .Sh DESCRIPTION The echo service module for PAM displays its arguments to the user, separated by spaces, using the current conversation function. .Pp If the .Cm % character occurs anywhere in the arguments to .Nm , it is assumed to introduce one of the following escape sequences: .Bl -tag -width 4n .It Cm %H The name of the host on which the client runs .Pq Dv PAM_RHOST . .\".It Cm %h .\"The name of the host on which the server runs. .It Cm %s The current service name .Pq Dv PAM_SERVICE . .It Cm %t The name of the controlling tty .Pq Dv PAM_TTY . .It Cm \&%U The applicant's user name .Pq Dv PAM_RUSER . .It Cm %u The target account's user name .Pq Dv PAM_USER . .El .Pp Any other two-character sequence beginning with .Cm % expands to the character following the .Cm % character. .Sh SEE ALSO -.Xr pam.conf 5 , -.Xr pam 3 +.Xr pam 3 , +.Xr pam.conf 5 .Sh AUTHORS The .Nm module and this manual page were developed for the .Fx Project by ThinkSec AS and NAI Labs, the Security Research Division of Network Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035 .Pq Dq CBOSS , as part of the DARPA CHATS research program. diff --git a/lib/libpam/modules/pam_exec/pam_exec.8 b/lib/libpam/modules/pam_exec/pam_exec.8 index c77162955730..be5666003557 100644 --- a/lib/libpam/modules/pam_exec/pam_exec.8 +++ b/lib/libpam/modules/pam_exec/pam_exec.8 @@ -1,169 +1,169 @@ .\" Copyright (c) 2001,2003 Networks Associates Technology, Inc. .\" Copyright (c) 2017-2019 Dag-Erling Smørgrav .\" Copyright (c) 2018 Thomas Munro .\" All rights reserved. .\" .\" Portions of this software were developed for the FreeBSD Project by .\" ThinkSec AS and NAI Labs, the Security Research Division of Network .\" Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 .\" ("CBOSS"), as part of the DARPA CHATS research program. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. The name of the author may not be used to endorse or promote .\" products derived from this software without specific prior written .\" permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd May 24, 2019 .Dt PAM_EXEC 8 .Os .Sh NAME .Nm pam_exec .Nd Exec PAM module .Sh SYNOPSIS .Op Ar service-name .Ar module-type .Ar control-flag .Pa pam_exec .Op Ar arguments .Sh DESCRIPTION The exec service module for PAM executes the program designated by its first argument if no options are specified, with its remaining arguments as command-line arguments. If options are specified, the program and its arguments follow the last option or .Cm -- if the program name conflicts with an option name. .Pp The following options may be passed before the program and its arguments: .Bl -tag -width indent .It Cm capture_stderr Capture text printed by the program to its standard error stream and pass it to the conversation function as error messages. No attempt is made at buffering the text, so results may vary. .It Cm capture_stdout Capture text printed by the program to its standard output stream and pass it to the conversation function as informational messages. No attempt is made at buffering the text, so results may vary. .It Cm debug Ignored for compatibility reasons. .It Cm no_warn Ignored for compatibility reasons. .It Cm return_prog_exit_status Use the program exit status as the return code of the pam_sm_* function. It must be a valid return value for this function. .It Cm expose_authtok Write the authentication token to the program's standard input stream, followed by a NUL character. Ignored for .Fn pam_sm_setcred . .It Cm use_first_pass If .Cm expose_authtok was specified, do not prompt for an authentication token if one is not already available. .It Cm -- Stop options parsing; program and its arguments follow. .El .Pp The child's environment is set to the current PAM environment list, as returned by .Xr pam_getenvlist 3 . In addition, the following PAM items are exported as environment variables: .Ev PAM_RHOST , .Ev PAM_RUSER , .Ev PAM_SERVICE , .Ev PAM_SM_FUNC , .Ev PAM_TTY and .Ev PAM_USER . .Pp The .Ev PAM_SM_FUNC variable contains the name of the PAM service module function being called. It may be: .Bl -dash -offset indent -compact .It pam_sm_acct_mgmt .It pam_sm_authenticate .It pam_sm_chauthtok .It pam_sm_close_session .It pam_sm_open_session .It pam_sm_setcred .El .Pp If .Cm return_prog_exit_status is not set (default), the .Ev PAM_SM_FUNC function returns .Er PAM_SUCCESS if the program exit status is 0, .Er PAM_PERM_DENIED otherwise. .Pp If .Cm return_prog_exit_status is set, the program exit status is used. It should be .Er PAM_SUCCESS or one of the error codes allowed by the calling .Ev PAM_SM_FUNC function. The valid codes are documented in each function man page. If the exit status is not a valid return code, .Er PAM_SERVICE_ERR is returned. Each valid codes numerical value is available as an environment variable (eg.\& .Ev PAM_SUCESS , .Ev PAM_USER_UNKNOWN , etc). This is useful in shell scripts for instance. .Sh SEE ALSO -.Xr pam_get_item 3 , -.Xr pam.conf 5 , .Xr pam 3 , +.Xr pam_get_item 3 , .Xr pam_sm_acct_mgmt 3 , .Xr pam_sm_authenticate 3 , .Xr pam_sm_chauthtok 3 , .Xr pam_sm_close_session 3 , .Xr pam_sm_open_session 3 , -.Xr pam_sm_setcred 3 +.Xr pam_sm_setcred 3 , +.Xr pam.conf 5 .Sh AUTHORS The .Nm module and this manual page were developed for the .Fx Project by ThinkSec AS and NAI Labs, the Security Research Division of Network Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035 .Pq Dq CBOSS , as part of the DARPA CHATS research program. diff --git a/lib/libpam/modules/pam_ftpusers/pam_ftpusers.8 b/lib/libpam/modules/pam_ftpusers/pam_ftpusers.8 index a5c810fd2de5..d5a0f0f1fd2e 100644 --- a/lib/libpam/modules/pam_ftpusers/pam_ftpusers.8 +++ b/lib/libpam/modules/pam_ftpusers/pam_ftpusers.8 @@ -1,97 +1,97 @@ .\" Copyright (c) 2001 Mark R V Murray .\" All rights reserved. .\" Copyright (c) 2002 Networks Associates Technology, Inc. .\" All rights reserved. .\" .\" Portions of this software were developed for the FreeBSD Project by .\" ThinkSec AS and NAI Labs, the Security Research Division of Network .\" Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 .\" ("CBOSS"), as part of the DARPA CHATS research program. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. The name of the author may not be used to endorse or promote .\" products derived from this software without specific prior written .\" permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd April 17, 2002 .Dt PAM_FTPUSERS 8 .Os .Sh NAME .Nm pam_ftpusers .Nd ftpusers PAM module .Sh SYNOPSIS .Op Ar service-name .Ar module-type .Ar control-flag .Pa pam_ftpusers .Op Ar options .Sh DESCRIPTION The .Pa ftpusers service module for PAM, .Nm provides functionality for only one PAM category: account management. In terms of the .Ar module-type parameter, this is the .Dq Li account feature. .Ss Ftpusers Account Management Module The .Pa ftpusers account management component .Pq Fn pam_sm_acct_mgmt , succeeds if and only if the user is listed in .Pa /etc/ftpusers . .Pp The following options may be passed to the authentication module: .Bl -tag -width ".Cm disallow" .It Cm debug .Xr syslog 3 debugging information at .Dv LOG_DEBUG level. .It Cm no_warn suppress warning messages to the user. These messages include reasons why the user's authentication attempt was declined. .It Cm disallow reverse the semantics; .Nm will succeed if and only if the user is not listed in .Pa /etc/ftpusers . .El .Sh SEE ALSO +.Xr pam 3 , .Xr ftpusers 5 , -.Xr pam.conf 5 , -.Xr pam 3 +.Xr pam.conf 5 .Sh AUTHORS The .Nm module and this manual page were developed for the .Fx Project by ThinkSec AS and NAI Labs, the Security Research Division of Network Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035 .Pq Dq CBOSS , as part of the DARPA CHATS research program. diff --git a/lib/libpam/modules/pam_group/pam_group.8 b/lib/libpam/modules/pam_group/pam_group.8 index ed96d45db503..315aaa6cc267 100644 --- a/lib/libpam/modules/pam_group/pam_group.8 +++ b/lib/libpam/modules/pam_group/pam_group.8 @@ -1,100 +1,100 @@ .\" Copyright (c) 2003 Networks Associates Technology, Inc. .\" Copyright (c) 2004-2011 Dag-Erling Smørgrav .\" All rights reserved. .\" .\" Portions of this software were developed for the FreeBSD Project by .\" ThinkSec AS and NAI Labs, the Security Research Division of Network .\" Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 .\" ("CBOSS"), as part of the DARPA CHATS research program. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. The name of the author may not be used to endorse or promote .\" products derived from this software without specific prior written .\" permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd July 19, 2014 .Dt PAM_GROUP 8 .Os .Sh NAME .Nm pam_group .Nd Group PAM module .Sh SYNOPSIS .Op Ar service-name .Ar module-type .Ar control-flag .Pa pam_group .Op Ar arguments .Sh DESCRIPTION The group service module for PAM accepts or rejects users based on their membership in a particular file group. .Nm pam_group provides functionality for two PAM categories: authentication and account management. In terms of the module-type parameter, they are the ``auth'' and ``account'' features. .Pp The following options may be passed to the .Nm module: .Bl -tag -width ".Cm fail_safe" .It Cm deny Reverse the meaning of the test, i.e., reject the applicant if and only if he or she is a member of the specified group. This can be useful to exclude certain groups of users from certain services. .It Cm fail_safe If the specified group does not exist, or has no members, act as if it does exist and the applicant is a member. .It Cm group Ns = Ns Ar groupname Specify the name of the group to check. The default is .Dq Li wheel . .It Cm luser Accept or reject based on the target user's group membership. .It Cm root_only Skip this module entirely if the target account is not the superuser account. .It Cm ruser Accept or reject based on the supplicant's group membership. This is the default. .El .Pp Note that the .Cm luser and .Cm ruser options are mutually exclusive, and that .Nm will fail if both are specified. .Sh SEE ALSO -.Xr pam.conf 5 , -.Xr pam 3 +.Xr pam 3 , +.Xr pam.conf 5 .Sh AUTHORS The .Nm module and this manual page were developed for the .Fx Project by ThinkSec AS and NAI Labs, the Security Research Division of Network Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035 .Pq Dq CBOSS , as part of the DARPA CHATS research program. diff --git a/lib/libpam/modules/pam_guest/pam_guest.8 b/lib/libpam/modules/pam_guest/pam_guest.8 index 541fd299ba8b..c626187d5b19 100644 --- a/lib/libpam/modules/pam_guest/pam_guest.8 +++ b/lib/libpam/modules/pam_guest/pam_guest.8 @@ -1,96 +1,96 @@ .\" Copyright (c) 2003 Networks Associates Technology, Inc. .\" All rights reserved. .\" .\" Portions of this software were developed for the FreeBSD Project by .\" ThinkSec AS and NAI Labs, the Security Research Division of Network .\" Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 .\" ("CBOSS"), as part of the DARPA CHATS research program. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. The name of the author may not be used to endorse or promote .\" products derived from this software without specific prior written .\" permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd May 26, 2003 .Dt PAM_GUEST 8 .Os .Sh NAME .Nm pam_guest .Nd Guest PAM module .Sh SYNOPSIS .Op Ar service-name .Ar module-type .Ar control-flag .Pa pam_guest .Op Ar arguments .Sh DESCRIPTION The guest service module for PAM allows guest logins. If successful, the .Nm module sets the PAM environment variable .Ev GUEST to the login name. The application can check this variable using .Xr pam_getenv 3 to differentiate guest logins from normal logins. .Pp The following options may be passed to the .Nm module: .Bl -tag -width ".Cm pass_as_ruser" .It Cm guests Ns = Ns Ar list Comma-separated list of guest account names. The default is .Dq Li guest . A typical value for .Xr ftpd 8 would be .Dq Li anonymous,ftp . .It Cm nopass Omits the password prompt if the target account is on the list of guest accounts. .It Cm pass_as_ruser The password typed in by the user is exported as the .Dv PAM_RUSER item. This is useful for applications like .Xr ftpd 8 where guest users are encouraged to use their email address as password. .It Cm pass_is_user Requires the guest user to type in the guest account name as password. .El .Sh SEE ALSO +.Xr pam 3 , .Xr pam_get_item 3 , .Xr pam_getenv 3 , -.Xr pam.conf 5 , -.Xr pam 3 +.Xr pam.conf 5 .Sh AUTHORS The .Nm module and this manual page were developed for the .Fx Project by ThinkSec AS and NAI Labs, the Security Research Division of Network Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035 .Pq Dq CBOSS , as part of the DARPA CHATS research program. diff --git a/lib/libpam/modules/pam_krb5/pam_krb5.8 b/lib/libpam/modules/pam_krb5/pam_krb5.8 index b59fdbdee9c4..7c1770961272 100644 --- a/lib/libpam/modules/pam_krb5/pam_krb5.8 +++ b/lib/libpam/modules/pam_krb5/pam_krb5.8 @@ -1,235 +1,235 @@ .\" .\" $Id: pam_krb5.5,v 1.5 2000/01/05 00:59:56 fcusack Exp $ .Dd May 3, 2010 .Dt PAM_KRB5 8 .Os .Sh NAME .Nm pam_krb5 .Nd Kerberos 5 PAM module .Sh SYNOPSIS .Pa /usr/lib/pam_krb5.so .Sh DESCRIPTION The Kerberos 5 service module for PAM, typically .Pa /usr/lib/pam_krb5.so , provides functionality for three PAM categories: authentication, account management, and password management. It also provides null functions for session management. The .Pa pam_krb5.so module is a shared object that can be dynamically loaded to provide the necessary functionality upon demand. Its path is specified in the PAM configuration file. .Ss Kerberos 5 Authentication Module The Kerberos 5 authentication component provides functions to verify the identity of a user .Pq Fn pam_sm_authenticate and to set user specific credentials .Pq Fn pam_sm_setcred . .Fn pam_sm_authenticate converts the supplied username into a Kerberos principal, by appending the default local realm name. It also supports usernames with explicit realm names. If a realm name is supplied, then upon a successful return, it changes the username by mapping the principal name into a local username (calling .Fn krb5_aname_to_localname ) . This typically just means the realm name is stripped. .Pp It prompts the user for a password and obtains a new Kerberos TGT for the principal. The TGT is verified by obtaining a service ticket for the local host. .Pp When prompting for the current password, the authentication module will use the prompt .Dq Li "Password for :" . .Pp The .Fn pam_sm_setcred function stores the newly acquired credentials in a credentials cache, and sets the environment variable .Ev KRB5CCNAME appropriately. The credentials cache should be destroyed by the user at logout with .Xr kdestroy 1 . .Pp The following options may be passed to the authentication module: .Bl -tag -width ".Cm use_first_pass" .It Cm debug .Xr syslog 3 debugging information at .Dv LOG_DEBUG level. .It Cm no_warn suppress warning messages to the user. These messages include reasons why the user's authentication attempt was declined. .It Cm use_first_pass If the authentication module is not the first in the stack, and a previous module obtained the user's password, that password is used to authenticate the user. If this fails, the authentication module returns failure without prompting the user for a password. This option has no effect if the authentication module is the first in the stack, or if no previous modules obtained the user's password. .It Cm try_first_pass This option is similar to the .Cm use_first_pass option, except that if the previously obtained password fails, the user is prompted for another password. .It Cm forwardable Obtain forwardable Kerberos credentials for the user. .It Cm no_ccache Do not save the obtained credentials in a credentials cache. This is a useful option if the authentication module is used for services such as ftp or pop, where the user would not be able to destroy them. [This is not a recommendation to use the module for those services.] .It Cm ccache Ns = Ns Ar name Use .Ar name as the credentials cache. .Ar name must be in the form .Ar type : Ns Ar residual . The special tokens .Ql %u , to designate the decimal UID of the user; and .Ql %p , to designate the current process ID; can be used in .Ar name . .It Cm allow_kdc_spoof Allow .Nm to succeed even if there is no host or service key available in a keytab to authenticate the Kerberos KDC's ticket. If there is no such key, for example on a host with no keytabs, .Nm will fail immediately without prompting the user. .Pp .Sy Warning : If the host has not been configured with a keytab from the KDC, setting this option makes it vulnerable to malicious KDCs, e.g. via DNS flooding, because .Nm has no way to distinguish the legitimate KDC from a spoofed KDC. .It Cm no_user_check Do not verify if a user exists on the local system. This option implies the .Cm no_ccache option because there is no secure local uid/gid for the cache file. .El .Ss Kerberos 5 Account Management Module The Kerberos 5 account management component provides a function to perform account management, .Fn pam_sm_acct_mgmt . The function verifies that the authenticated principal is allowed to login to the local user account by calling .Fn krb5_kuserok (which checks the user's .Pa .k5login file). .Ss Kerberos 5 Password Management Module The Kerberos 5 password management component provides a function to change passwords .Pq Fn pam_sm_chauthtok . The username supplied (the user running the .Xr passwd 1 command, or the username given as an argument) is mapped into a Kerberos principal name, using the same technique as in the authentication module. Note that if a realm name was explicitly supplied during authentication, but not during a password change, the mapping done by the password management module may not result in the same principal as was used for authentication. .Pp Unlike when changing a .Ux password, the password management module will allow any user to change any principal's password (if the user knows the principal's old password, of course). Also unlike .Ux , root is always prompted for the principal's old password. .Pp The password management module uses the same heuristics as .Xr kpasswd 1 to determine how to contact the Kerberos password server. .Pp The following options may be passed to the password management module: .Bl -tag -width ".Cm use_first_pass" .It Cm debug .Xr syslog 3 debugging information at .Dv LOG_DEBUG level. .It Cm use_first_pass If the password management module is not the first in the stack, and a previous module obtained the user's old password, that password is used to authenticate the user. If this fails, the password management module returns failure without prompting the user for the old password. If successful, the new password entered to the previous module is also used as the new Kerberos password. If the new password fails, the password management module returns failure without prompting the user for a new password. .It Cm try_first_pass This option is similar to the .Cm use_first_pass option, except that if the previously obtained old or new passwords fail, the user is prompted for them. .El .Ss Kerberos 5 Session Management Module The Kerberos 5 session management component provides functions to initiate .Pq Fn pam_sm_open_session and terminate .Pq Fn pam_sm_close_session sessions. Since session management is not defined under Kerberos 5, both of these functions simply return success. They are provided only because of the naming conventions for PAM modules. .Sh ENVIRONMENT .Bl -tag -width "KRB5CCNAME" .It Ev KRB5CCNAME Location of the credentials cache. .El .Sh FILES .Bl -tag -width ".Pa /tmp/krb5cc_ Ns Ar uid" -compact .It Pa /tmp/krb5cc_ Ns Ar uid default credentials cache .Ar ( uid is the decimal UID of the user). .It Pa $HOME/.k5login file containing Kerberos principals that are allowed access. .El .Sh SEE ALSO .Xr kdestroy 1 , .Xr passwd 1 , +.Xr pam 3 , .Xr syslog 3 , -.Xr pam.conf 5 , -.Xr pam 3 +.Xr pam.conf 5 .Sh NOTES Applications should not call .Fn pam_authenticate more than once between calls to .Fn pam_start and .Fn pam_end when using the Kerberos 5 PAM module. diff --git a/lib/libpam/modules/pam_ksu/pam_ksu.8 b/lib/libpam/modules/pam_ksu/pam_ksu.8 index 36d6936423b1..ace570ea5b5b 100644 --- a/lib/libpam/modules/pam_ksu/pam_ksu.8 +++ b/lib/libpam/modules/pam_ksu/pam_ksu.8 @@ -1,120 +1,120 @@ .\" Copyright (c) 2001 Mark R V Murray .\" All rights reserved. .\" Copyright (c) 2001 Networks Associates Technology, Inc. .\" All rights reserved. .\" .\" This software was developed for the FreeBSD Project by ThinkSec AS and .\" NAI Labs, the Security Research Division of Network Associates, Inc. .\" under DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the .\" DARPA CHATS research program. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. The name of the author may not be used to endorse or promote .\" products derived from this software without specific prior written .\" permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd May 15, 2002 .Dt PAM_KSU 8 .Os .Sh NAME .Nm pam_ksu .Nd Kerberos 5 SU PAM module .Sh SYNOPSIS .Op Ar service-name .Ar module-type .Ar control-flag .Pa pam_ksu .Op Ar options .Sh DESCRIPTION The Kerberos 5 SU authentication service module for PAM, .Nm for only one PAM category: authentication. In terms of the .Ar module-type parameter, this is the .Dq Li auth feature. The module is specifically designed to be used with the .Xr su 1 utility. .\" It also provides a null function for session management. .Ss Kerberos 5 SU Authentication Module The Kerberos 5 SU authentication component provides functions to verify the identity of a user .Pq Fn pam_sm_authenticate , and determine whether or not the user is authorized to obtain the privileges of the target account. If the target account is .Dq root , then the Kerberos 5 principal used for authentication and authorization will be the .Dq root instance of the current user, e.g.\& .Dq Li user/root@REAL.M . Otherwise, the principal will simply be the current user's default principal, e.g.\& .Dq Li user@REAL.M . .Pp The user is prompted for a password if necessary. Authorization is performed by comparing the Kerberos 5 principal with those listed in the .Pa .k5login file in the target account's home directory (e.g.\& .Pa /root/.k5login for root). .Pp The following options may be passed to the authentication module: .Bl -tag -width ".Cm use_first_pass" .It Cm debug .Xr syslog 3 debugging information at .Dv LOG_DEBUG level. .It Cm use_first_pass If the authentication module is not the first in the stack, and a previous module obtained the user's password, that password is used to authenticate the user. If this fails, the authentication module returns failure without prompting the user for a password. This option has no effect if the authentication module is the first in the stack, or if no previous modules obtained the user's password. .It Cm try_first_pass This option is similar to the .Cm use_first_pass option, except that if the previously obtained password fails, the user is prompted for another password. .El .Sh SEE ALSO .Xr su 1 , +.Xr pam 3 , .Xr syslog 3 , -.Xr pam.conf 5 , -.Xr pam 3 +.Xr pam.conf 5 diff --git a/lib/libpam/modules/pam_lastlog/pam_lastlog.8 b/lib/libpam/modules/pam_lastlog/pam_lastlog.8 index 6e5ba8770ada..e924016151fa 100644 --- a/lib/libpam/modules/pam_lastlog/pam_lastlog.8 +++ b/lib/libpam/modules/pam_lastlog/pam_lastlog.8 @@ -1,99 +1,99 @@ .\" Copyright (c) 2001 Mark R V Murray .\" All rights reserved. .\" Copyright (c) 2001 Networks Associates Technology, Inc. .\" All rights reserved. .\" .\" Portions of this software were developed for the FreeBSD Project by .\" ThinkSec AS and NAI Labs, the Security Research Division of Network .\" Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 .\" ("CBOSS"), as part of the DARPA CHATS research program. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. The name of the author may not be used to endorse or promote .\" products derived from this software without specific prior written .\" permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd January 21, 2010 .Dt PAM_LASTLOG 8 .Os .Sh NAME .Nm pam_lastlog .Nd login accounting PAM module .Sh SYNOPSIS .Op Ar service-name .Ar module-type .Ar control-flag .Pa pam_lastlog .Op Ar options .Sh DESCRIPTION The login accounting service module for PAM, .Nm provides functionality for only one PAM category: session management. In terms of the .Ar module-type parameter, this is the .Dq Li session feature. .Ss Login Accounting Session Management Module The login accounting session management component provides functions to initiate .Pq Fn pam_sm_open_session and terminate .Pq Fn pam_sm_close_session sessions. The .Fn pam_sm_open_session function records the session in the user accounting database. The .Fn pam_sm_close_session function does nothing. .Pp The following options may be passed to the authentication module: .Bl -tag -width ".Cm no_warn" .It Cm debug .Xr syslog 3 debugging information at .Dv LOG_DEBUG level. .It Cm no_warn suppress warning messages to the user. .It Cm no_fail Ignore I/O failures. .El .Sh SEE ALSO .Xr last 1 , .Xr w 1 , .Xr getutxent 3 , +.Xr pam 3 , .Xr ulog_login 3 , .Xr ulog_logout 3 , .Xr pam.conf 5 , -.Xr lastlogin 8 , -.Xr pam 3 +.Xr lastlogin 8 .Sh AUTHORS The .Nm module and this manual page were developed for the FreeBSD Project by ThinkSec AS and NAI Labs, the Security Research Division of Network Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035 .Pq Dq CBOSS , as part of the DARPA CHATS research program. diff --git a/lib/libpam/modules/pam_nologin/pam_nologin.8 b/lib/libpam/modules/pam_nologin/pam_nologin.8 index 30f87a65b63e..ff49749e50f1 100644 --- a/lib/libpam/modules/pam_nologin/pam_nologin.8 +++ b/lib/libpam/modules/pam_nologin/pam_nologin.8 @@ -1,88 +1,88 @@ .\" Copyright (c) 2001 Mark R V Murray .\" 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. .\" .Dd June 10, 2007 .Dt PAM_NOLOGIN 8 .Os .Sh NAME .Nm pam_nologin .Nd NoLogin PAM module .Sh SYNOPSIS .Op Ar service-name .Ar module-type .Ar control-flag .Pa pam_nologin .Op Ar options .Sh DESCRIPTION The NoLogin service module for PAM, .Nm provides functionality for only one PAM category: account management. In terms of the .Ar module-type parameter, this is the .Dq Li account feature. .Ss NoLogin Account Management Module The NoLogin account management component, .Fn pam_sm_acct_mgmt , verifies whether logins are administratively disabled via .Xr nologin 5 . It returns success if the user's login class has an "ignorenologin" capability specified in .Xr login.conf 5 or the .Xr nologin 5 file does not exist. If neither condition is met, then the contents of .Xr nologin 5 are echoed before failure is returned. The location of .Xr nologin 5 is specified by a "nologin" capability in .Xr login.conf 5 , which defaults to .Pa /var/run/nologin . .Pp The following options may be passed to the module: .Bl -tag -width ".Cm no_warn" .It Cm debug .Xr syslog 3 debugging information at .Dv LOG_DEBUG level. .It Cm no_warn suppress warning messages to the user. These messages include reasons why the user's login attempt was declined. .El .Sh SEE ALSO +.Xr pam 3 , .Xr syslog 3 , .Xr login.conf 5 , .Xr nologin 5 , -.Xr pam.conf 5 , -.Xr pam 3 +.Xr pam.conf 5 diff --git a/lib/libpam/modules/pam_passwdqc/pam_passwdqc.8 b/lib/libpam/modules/pam_passwdqc/pam_passwdqc.8 index f2ec1747d1f8..755e93520427 100644 --- a/lib/libpam/modules/pam_passwdqc/pam_passwdqc.8 +++ b/lib/libpam/modules/pam_passwdqc/pam_passwdqc.8 @@ -1,265 +1,265 @@ .\" Copyright (c) 2000-2002 Solar Designer. .\" All rights reserved. .\" Copyright (c) 2001 Networks Associates Technology, Inc. .\" All rights reserved. .\" .\" Portions of this software were developed for the FreeBSD Project by .\" ThinkSec AS and NAI Labs, the Security Research Division of Network .\" Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 .\" ("CBOSS"), as part of the DARPA CHATS research program. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. The name of the author may not be used to endorse or promote .\" products derived from this software without specific prior written .\" permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd April 15, 2002 .Dt PAM_PASSWDQC 8 .Os .Sh NAME .Nm pam_passwdqc .Nd Password quality-control PAM module .Sh SYNOPSIS .Op Ar service-name .Ar module-type .Ar control-flag .Pa pam_passwdqc .Op Ar options .Sh DESCRIPTION The .Nm module is a simple password strength checking module for PAM. In addition to checking regular passwords, it offers support for passphrases and can provide randomly generated passwords. .Pp The .Nm module provides functionality for only one PAM category: password changing. In terms of the .Ar module-type parameter, this is the .Dq Li password feature. .Pp The .Fn pam_chauthtok service function will ask the user for a new password, and verify that it meets certain minimum standards. If the chosen password is unsatisfactory, the service function returns .Dv PAM_AUTHTOK_ERR . .Pp The following options may be passed to the authentication module: .Bl -tag -width indent .It Xo .Sm off .Cm min No = Ar N0 , N1 , N2 , N3 , N4 .Sm on .Xc .Sm off .Pq Cm min No = Cm disabled , No 24 , 12 , 8 , 7 .Sm on The minimum allowed password lengths for different kinds of passwords/passphrases. The keyword .Cm disabled can be used to disallow passwords of a given kind regardless of their length. Each subsequent number is required to be no larger than the preceding one. .Pp .Ar N0 is used for passwords consisting of characters from one character class only. The character classes are: digits, lower-case letters, upper-case letters, and other characters. There is also a special class for .No non- Ns Tn ASCII characters which could not be classified, but are assumed to be non-digits. .Pp .Ar N1 is used for passwords consisting of characters from two character classes, which do not meet the requirements for a passphrase. .Pp .Ar N2 is used for passphrases. A passphrase must consist of sufficient words (see the .Cm passphrase option below). .Pp .Ar N3 and .Ar N4 are used for passwords consisting of characters from three and four character classes, respectively. .Pp When calculating the number of character classes, upper-case letters used as the first character and digits used as the last character of a password are not counted. .Pp In addition to being sufficiently long, passwords are required to contain enough different characters for the character classes and the minimum length they have been checked against. .It Cm max Ns = Ns Ar N .Pq Cm max Ns = Ns 40 The maximum allowed password length. This can be used to prevent users from setting passwords which may be too long for some system services. The value 8 is treated specially: if .Cm max is set to 8, passwords longer than 8 characters will not be rejected, but will be truncated to 8 characters for the strength checks and the user will be warned. This is for compatibility with the traditional DES password hashes, which truncate the password at 8 characters. .Pp It is important that you do set .Cm max Ns = Ns 8 if you are using the traditional hashes, or some weak passwords will pass the checks. .It Cm passphrase Ns = Ns Ar N .Pq Cm passphrase Ns = Ns 3 The number of words required for a passphrase, or 0 to disable passphrase support. .It Cm match Ns = Ns Ar N .Pq Cm match Ns = Ns 4 The length of common substring required to conclude that a password is at least partially based on information found in a character string, or 0 to disable the substring search. Note that the password will not be rejected once a weak substring is found; it will instead be subjected to the usual strength requirements with the weak substring removed. .Pp The substring search is case-insensitive and is able to detect and remove a common substring spelled backwards. .It Xo .Sm off .Cm similar No = Cm permit | deny .Sm on .Xc .Pq Cm similar Ns = Ns Cm deny Whether a new password is allowed to be similar to the old one. The passwords are considered to be similar when there is a sufficiently long common substring and the new password with the substring removed would be weak. .It Xo .Sm off .Cm random No = Ar N Op , Cm only .Sm on .Xc .Pq Cm random Ns = Ns 42 The size of randomly-generated passwords in bits, or 0 to disable this feature. Passwords that contain the offered randomly-generated string will be allowed regardless of other possible restrictions. .Pp The .Cm only modifier can be used to disallow user-chosen passwords. .It Xo .Sm off .Cm enforce No = Cm none | users | everyone .Sm on .Xc .Pq Cm enforce Ns = Ns Cm everyone The module can be configured to warn of weak passwords only, but not actually enforce strong passwords. The .Cm users setting will enforce strong passwords for non-root users only. .It Cm non-unix Normally, .Nm uses .Xr getpwnam 3 to obtain the user's personal login information and use that during the password strength checks. This behavior can be disabled with the .Cm non-unix option. .It Cm retry Ns = Ns Ar N .Pq Cm retry Ns = Ns 3 The number of times the module will ask for a new password if the user fails to provide a sufficiently strong password and enter it twice the first time. .It Cm ask_oldauthtok Ns Op = Ns Cm update Ask for the old password as well. Normally, .Nm leaves this task for subsequent modules. With no argument, the .Cm ask_oldauthtok option will cause .Nm to ask for the old password during the preliminary check phase. If the .Cm ask_oldauthtok option is specified with the .Cm update argument, .Nm will do that during the update phase. .It Cm check_oldauthtok This tells .Nm to validate the old password before giving a new password prompt. Normally, this task is left for subsequent modules. .Pp The primary use for this option is when .Cm ask_oldauthtok Ns = Ns Cm update is also specified, in which case no other modules gets a chance to ask for and validate the password. Of course, this will only work with .Ux passwords. .It Cm use_first_pass , use_authtok Use the new password obtained by modules stacked before .Nm . This disables user interaction within .Nm . The only difference between .Cm use_first_pass and .Cm use_authtok is that the former is incompatible with .Cm ask_oldauthtok . .El .Sh SEE ALSO .Xr getpwnam 3 , -.Xr pam.conf 5 , -.Xr pam 3 +.Xr pam 3 , +.Xr pam.conf 5 .Sh AUTHORS The .Nm module was written by .An Solar Designer Aq Mt solar@openwall.com . This manual page, derived from the author's documentation, was written for the .Fx Project by ThinkSec AS and NAI Labs, the Security Research Division of Network Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035 .Pq Dq CBOSS , as part of the DARPA CHATS research program. diff --git a/lib/libpam/modules/pam_permit/pam_permit.8 b/lib/libpam/modules/pam_permit/pam_permit.8 index f0b2f5527066..270eaee8361d 100644 --- a/lib/libpam/modules/pam_permit/pam_permit.8 +++ b/lib/libpam/modules/pam_permit/pam_permit.8 @@ -1,73 +1,73 @@ .\" Copyright (c) 2001 Mark R V Murray .\" 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. .\" .Dd July 7, 2001 .Dt PAM_PERMIT 8 .Os .Sh NAME .Nm pam_permit .Nd Promiscuous PAM module .Sh SYNOPSIS .Op Ar service-name .Ar module-type .Ar control-flag .Pa pam_permit .Op Ar options .Sh DESCRIPTION The Promiscuous authentication service module for PAM, .Nm provides functionality for all the PAM categories: authentication, account management, session management and password management. In terms of the .Ar module-type parameter, these are the .Dq Li auth , .Dq Li account , .Dq Li session , and .Dq Li password features. .Pp The Promiscuous module will universally allow all requests. It is primarily of use during testing, and to silence .Dq noisy PAM-enabled applications. .Pp The following options may be passed to the module: .Bl -tag -width ".Cm debug" .It Cm debug .Xr syslog 3 debugging information at .Dv LOG_DEBUG level. .El .Sh SEE ALSO +.Xr pam 3 , .Xr syslog 3 , -.Xr pam.conf 5 , -.Xr pam 3 +.Xr pam.conf 5 diff --git a/lib/libpam/modules/pam_radius/pam_radius.8 b/lib/libpam/modules/pam_radius/pam_radius.8 index 6b2d1ef1fa55..abc916dcfff6 100644 --- a/lib/libpam/modules/pam_radius/pam_radius.8 +++ b/lib/libpam/modules/pam_radius/pam_radius.8 @@ -1,148 +1,148 @@ .\"- .\" Copyright (c) 1992, 1993, 1994 .\" The Regents of the University of California. All rights reserved. .\" Copyright (c) 1999 Andrzej Bialecki .\" All rights reserved. .\" Copyright (c) 2018 The University of Oslo .\" All rights reserved. .\" .\" This code is derived from software donated to Berkeley by .\" Jan-Simon Pendry. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd May 16, 2018 .Dt PAM_RADIUS 8 .Os .Sh NAME .Nm pam_radius .Nd RADIUS authentication PAM module .Sh SYNOPSIS .Op Ar service-name .Ar module-type .Ar control-flag .Pa pam_radius .Op Ar options .Sh DESCRIPTION The .Nm module provides authentication services based upon the RADIUS (Remote Authentication Dial In User Service) protocol for the PAM (Pluggable Authentication Module) framework. .Pp The .Nm module accepts these optional parameters: .Bl -tag -width Fl .It Cm use_first_pass causes .Nm to use a previously entered password instead of prompting for a new one. If no password has been entered then authentication fails. .It Cm try_first_pass causes .Nm to use a previously entered password, if one is available. If no password has been entered, .Nm prompts for one as usual. .It Cm echo_pass causes echoing to be left on if .Nm prompts for a password. .It Cm conf Ns = Ns Ar pathname specifies a non-standard location for the RADIUS client configuration file (normally located in .Pa /etc/radius.conf ) . .It Cm nas_id Ns = Ns Ar identifier specifies a NAS identifier to send instead of the hostname. .It Cm nas_ipaddr Ns Op No = Ns Ar address specifies a NAS IP address to be sent. If option is present, but there is no value provided then IP address corresponding to the current hostname will be used. .It Cm template_user Ns = Ns Ar username specifies a user whose .Xr passwd 5 entry will be used as a template to create the session environment if the supplied username does not exist in local password database. The user will be authenticated with the supplied username and password, but his credentials to the system will be presented as the ones for .Ar username , i.e., his login class, home directory, resource limits, etc.\& will be set to ones defined for .Ar username . .Pp If this option is omitted, and there is no username in the system databases equal to the supplied one (as determined by call to .Xr getpwnam 3 ) , the authentication will fail. .It Cm no_reply_message suppress printing of the contents of any .Cm Reply-Message attributes found in .Cm Access-Accept and .Cm Access-Reject responses. These are normally conveyed to the user as either informational or error messages, depending on whether the access request was accepted or rejected. .It Cm no_warn suppress warning messages to the user. These messages include reasons why the user's authentication attempt was declined. .El .Sh FILES .Bl -tag -width /etc/radius.conf -compact .It Pa /etc/radius.conf The standard RADIUS client configuration file for .Nm .El .Sh SEE ALSO +.Xr pam 3 , .Xr passwd 5 , -.Xr radius.conf 5 , -.Xr pam 3 +.Xr radius.conf 5 .Sh HISTORY The .Nm module first appeared in .Fx 3.1 . The .Nm manual page first appeared in .Fx 3.3 . .Sh AUTHORS .An -nosplit The .Nm manual page was written by .An Andrzej Bialecki Aq Mt abial@FreeBSD.org . .Pp The .Nm module was written by .An John D. Polstra Aq Mt jdp@FreeBSD.org . diff --git a/lib/libpam/modules/pam_rhosts/pam_rhosts.8 b/lib/libpam/modules/pam_rhosts/pam_rhosts.8 index ea005738840c..1f9716b9a0ca 100644 --- a/lib/libpam/modules/pam_rhosts/pam_rhosts.8 +++ b/lib/libpam/modules/pam_rhosts/pam_rhosts.8 @@ -1,93 +1,93 @@ .\" Copyright (c) 2001 Mark R V Murray .\" All rights reserved. .\" Copyright (c) 2001 Networks Associates Technology, Inc. .\" All rights reserved. .\" .\" Portions of this software were developed for the FreeBSD Project by .\" ThinkSec AS and NAI Labs, the Security Research Division of Network .\" Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 .\" ("CBOSS"), as part of the DARPA CHATS research program. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. The name of the author may not be used to endorse or promote .\" products derived from this software without specific prior written .\" permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd December 5, 2001 .Dt PAM_RHOSTS 8 .Os .Sh NAME .Nm pam_rhosts .Nd Rhosts PAM module .Sh SYNOPSIS .Op Ar service-name .Ar module-type .Ar control-flag .Pa pam_rhosts .Op Ar options .Sh DESCRIPTION The rhosts authentication service module for PAM, .Nm provides functionality for only one PAM category: authentication. In terms of the .Ar module-type parameter, this is the .Dq Li auth feature. .Ss Rhosts Authentication Module The Rhosts authentication component .Pq Fn pam_sm_authenticate , returns success if and only if the target user's UID is not 0 and the remote host and user are listed in .Pa /etc/hosts.equiv or in the target user's .Pa ~/.rhosts . .Pp The following options may be passed to the authentication module: .Bl -tag -width ".Cm allow_root" .It Cm debug .Xr syslog 3 debugging information at .Dv LOG_DEBUG level. .It Cm no_warn suppress warning messages to the user. These messages include reasons why the user's authentication attempt was declined. .It Cm allow_root do not automatically fail if the target user's UID is 0. .El .Sh SEE ALSO +.Xr pam 3 , .Xr hosts.equiv 5 , -.Xr pam.conf 5 , -.Xr pam 3 +.Xr pam.conf 5 .Sh AUTHORS The .Nm module and this manual page were developed for the .Fx Project by ThinkSec AS and NAI Labs, the Security Research Division of Network Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035 .Pq Dq CBOSS , as part of the DARPA CHATS research program. diff --git a/lib/libpam/modules/pam_rootok/pam_rootok.8 b/lib/libpam/modules/pam_rootok/pam_rootok.8 index d1ab8226e2ca..fd0a6dd3791f 100644 --- a/lib/libpam/modules/pam_rootok/pam_rootok.8 +++ b/lib/libpam/modules/pam_rootok/pam_rootok.8 @@ -1,73 +1,73 @@ .\" Copyright (c) 2001 Mark R V Murray .\" 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. .\" .Dd July 8, 2001 .Dt PAM_ROOTOK 8 .Os .Sh NAME .Nm pam_rootok .Nd RootOK PAM module .Sh SYNOPSIS .Op Ar service-name .Ar module-type .Ar control-flag .Pa pam_rootok .Op Ar options .Sh DESCRIPTION The RootOK authentication service module for PAM, .Nm provides functionality for only one PAM category: authentication. In terms of the .Ar module-type parameter, this is the .Dq Li auth feature. It also provides a null function for session management. .Ss RootOK Authentication Module The RootOK authentication component .Pq Fn pam_sm_authenticate , always returns success for the superuser; i.e., if .Xr getuid 2 returns 0. .Pp The following options may be passed to the authentication module: .Bl -tag -width ".Cm no_warn" .It Cm debug .Xr syslog 3 debugging information at .Dv LOG_DEBUG level. .It Cm no_warn suppress warning messages to the user. These messages include reasons why the user's authentication attempt was declined. .El .Sh SEE ALSO .Xr getuid 2 , -.Xr pam.conf 5 , -.Xr pam 3 +.Xr pam 3 , +.Xr pam.conf 5 diff --git a/lib/libpam/modules/pam_securetty/pam_securetty.8 b/lib/libpam/modules/pam_securetty/pam_securetty.8 index b19979000978..582389cf101d 100644 --- a/lib/libpam/modules/pam_securetty/pam_securetty.8 +++ b/lib/libpam/modules/pam_securetty/pam_securetty.8 @@ -1,90 +1,90 @@ .\" Copyright (c) 2001 Mark R V Murray .\" All rights reserved. .\" Copyright (c) 2002 Networks Associates Technology, Inc. .\" All rights reserved. .\" .\" Portions of this software were developed for the FreeBSD Project by .\" ThinkSec AS and NAI Labs, the Security Research Division of Network .\" Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 .\" ("CBOSS"), as part of the DARPA CHATS research program. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. The name of the author may not be used to endorse or promote .\" products derived from this software without specific prior written .\" permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd July 8, 2001 .Dt PAM_SECURETTY 8 .Os .Sh NAME .Nm pam_securetty .Nd SecureTTY PAM module .Sh SYNOPSIS .Op Ar service-name .Ar module-type .Ar control-flag .Pa pam_securetty .Op Ar options .Sh DESCRIPTION The SecureTTY service module for PAM, .Nm provides functionality for only one PAM category: account management. In terms of the .Ar module-type parameter, this is the .Dq Li account feature. It also provides null functions for authentication and session management. .Ss SecureTTY Account Management Module The SecureTTY account management component .Pq Fn pam_sm_acct_mgmt , returns failure if the user is attempting to authenticate as superuser, and the process is attached to an insecure TTY. In all other cases, the module returns success. .Pp A TTY is considered secure if it is listed in .Pa /etc/ttys and has the .Dv TTY_SECURE flag set. .Pp The following options may be passed to the authentication module: .Bl -tag -width ".Cm no_warn" .It Cm debug .Xr syslog 3 debugging information at .Dv LOG_DEBUG level. .It Cm no_warn suppress warning messages to the user. These messages include reasons why the user's authentication attempt was declined. .El .Sh SEE ALSO .Xr getttynam 3 , +.Xr pam 3 , .Xr syslog 3 , .Xr pam.conf 5 , -.Xr ttys 5 , -.Xr pam 3 +.Xr ttys 5 diff --git a/lib/libpam/modules/pam_self/pam_self.8 b/lib/libpam/modules/pam_self/pam_self.8 index c3623998f0be..f875d671286b 100644 --- a/lib/libpam/modules/pam_self/pam_self.8 +++ b/lib/libpam/modules/pam_self/pam_self.8 @@ -1,94 +1,94 @@ .\" Copyright (c) 2001 Mark R V Murray .\" All rights reserved. .\" Copyright (c) 2001 Networks Associates Technology, Inc. .\" All rights reserved. .\" .\" Portions of this software were developed for the FreeBSD Project by .\" ThinkSec AS and NAI Labs, the Security Research Division of Network .\" Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 .\" ("CBOSS"), as part of the DARPA CHATS research program. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. The name of the author may not be used to endorse or promote .\" products derived from this software without specific prior written .\" permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd December 5, 2001 .Dt PAM_SELF 8 .Os .Sh NAME .Nm pam_self .Nd Self PAM module .Sh SYNOPSIS .Op Ar service-name .Ar module-type .Ar control-flag .Pa pam_self .Op Ar options .Sh DESCRIPTION The Self authentication service module for PAM, .Nm provides functionality for only one PAM category: authentication. In terms of the .Ar module-type parameter, this is the .Dq Li auth feature. .Ss Self Authentication Module The Self authentication component .Pq Fn pam_sm_authenticate , returns success if and only if the target user's user ID is identical with the current real user ID. If the current real user ID is zero, authentication will fail, unless the .Cm allow_root option was specified. .Pp The following options may be passed to the authentication module: .Bl -tag -width ".Cm allow_root" .It Cm debug .Xr syslog 3 debugging information at .Dv LOG_DEBUG level. .It Cm no_warn suppress warning messages to the user. These messages include reasons why the user's authentication attempt was declined. .It Cm allow_root do not automatically fail if the current real user ID is 0. .El .Sh SEE ALSO .Xr getuid 2 , -.Xr pam.conf 5 , -.Xr pam 3 +.Xr pam 3 , +.Xr pam.conf 5 .Sh AUTHORS The .Nm module and this manual page were developed for the .Fx Project by ThinkSec AS and NAI Labs, the Security Research Division of Network Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035 .Pq Dq CBOSS , as part of the DARPA CHATS research program. diff --git a/lib/libpam/modules/pam_ssh/pam_ssh.8 b/lib/libpam/modules/pam_ssh/pam_ssh.8 index e63930eb5340..3ef44d8b687b 100644 --- a/lib/libpam/modules/pam_ssh/pam_ssh.8 +++ b/lib/libpam/modules/pam_ssh/pam_ssh.8 @@ -1,157 +1,157 @@ .\" Copyright (c) 2001 Mark R V Murray .\" Copyright (c) 2001-2003 Networks Associates Technology, Inc. .\" Copyright (c) 2004-2011 Dag-Erling Smørgrav .\" All rights reserved. .\" .\" This software was developed for the FreeBSD Project by ThinkSec AS and .\" NAI Labs, the Security Research Division of Network Associates, Inc. .\" under DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the .\" DARPA CHATS research program. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. The name of the author may not be used to endorse or promote .\" products derived from this software without specific prior written .\" permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd October 7, 2011 .Dt PAM_SSH 8 .Os .Sh NAME .Nm pam_ssh .Nd authentication and session management with SSH private keys .Sh SYNOPSIS .Op Ar service-name .Ar module-type .Ar control-flag .Pa pam_ssh .Op Ar options .Sh DESCRIPTION The SSH authentication service module for PAM, .Nm provides functionality for two PAM categories: authentication and session management. In terms of the .Ar module-type parameter, they are the .Dq Li auth and .Dq Li session features. .Ss SSH Authentication Module The SSH authentication component provides a function to verify the identity of a user .Pq Fn pam_sm_authenticate , by prompting the user for a passphrase and verifying that it can decrypt the target user's SSH key using that passphrase. .Pp The following options may be passed to the authentication module: .Bl -tag -width ".Cm use_first_pass" .It Cm use_first_pass If the authentication module is not the first in the stack, and a previous module obtained the user's password, that password is used to authenticate the user. If this fails, the authentication module returns failure without prompting the user for a password. This option has no effect if the authentication module is the first in the stack, or if no previous modules obtained the user's password. .It Cm try_first_pass This option is similar to the .Cm use_first_pass option, except that if the previously obtained password fails, the user is prompted for another password. .It Cm nullok Normally, keys with no passphrase are ignored for authentication purposes. If this option is set, keys with no passphrase will be taken into consideration, allowing the user to log in with a blank password. .El .Ss SSH Session Management Module The SSH session management component provides functions to initiate .Pq Fn pam_sm_open_session and terminate .Pq Fn pam_sm_close_session sessions. The .Fn pam_sm_open_session function starts an SSH agent, passing it any private keys it decrypted during the authentication phase, and sets the environment variables the agent specifies. The .Fn pam_sm_close_session function kills the previously started SSH agent by sending it a .Dv SIGTERM . .Pp The following options may be passed to the session management module: .Bl -tag -width ".Cm want_agent" .It Cm want_agent Start an agent even if no keys were decrypted during the authentication phase. .El .Sh FILES .Bl -tag -width ".Pa $HOME/.ssh/id_ed25519" -compact .It Pa $HOME/.ssh/id_rsa SSH2 RSA key .It Pa $HOME/.ssh/id_dsa SSH2 DSA key .It Pa $HOME/.ssh/id_ecdsa SSH2 ECDSA key .It Pa $HOME/.ssh/id_ed25519 SSH2 Ed25519 key .El .Sh SEE ALSO .Xr ssh-agent 1 , -.Xr pam.conf 5 , -.Xr pam 3 +.Xr pam 3 , +.Xr pam.conf 5 .Sh AUTHORS The .Nm module was originally written by .An -nosplit .An Andrew J. Korty Aq Mt ajk@iu.edu . The current implementation was developed for the .Fx Project by ThinkSec AS and NAI Labs, the Security Research Division of Network Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035 .Pq Dq CBOSS , as part of the DARPA CHATS research program. This manual page was written by .An Mark R V Murray Aq Mt markm@FreeBSD.org . diff --git a/lib/libpam/modules/pam_unix/pam_unix.8 b/lib/libpam/modules/pam_unix/pam_unix.8 index 170cf65f34db..5c2ae5cf52e2 100644 --- a/lib/libpam/modules/pam_unix/pam_unix.8 +++ b/lib/libpam/modules/pam_unix/pam_unix.8 @@ -1,215 +1,215 @@ .\" Copyright (c) 2001 Mark R V Murray .\" All rights reserved. .\" Copyright (c) 2001 Networks Associates Technology, Inc. .\" All rights reserved. .\" .\" This software was developed for the FreeBSD Project by ThinkSec AS and .\" NAI Labs, the Security Research Division of Network Associates, Inc. .\" under DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the .\" DARPA CHATS research program. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. The name of the author may not be used to endorse or promote .\" products derived from this software without specific prior written .\" permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd April 3, 2020 .Dt PAM_UNIX 8 .Os .Sh NAME .Nm pam_unix .Nd UNIX PAM module .Sh SYNOPSIS .Op Ar service-name .Ar module-type .Ar control-flag .Pa pam_unix .Op Ar options .Sh DESCRIPTION The .Ux authentication service module for PAM, .Nm provides functionality for three PAM categories: authentication, account management, and password management. In terms of the .Ar module-type parameter, they are the .Dq Li auth , .Dq Li account , and .Dq Li password features. It also provides a null function for session management. .Ss Ux Ss Authentication Module The .Ux authentication component provides functions to verify the identity of a user .Pq Fn pam_sm_authenticate , which obtains the relevant .Xr passwd 5 entry. It prompts the user for a password and verifies that this is correct with .Xr crypt 3 . .Pp The following options may be passed to the authentication module: .Bl -tag -width ".Cm use_first_pass" .It Cm debug .Xr syslog 3 debugging information at .Dv LOG_DEBUG level. .It Cm use_first_pass If the authentication module is not the first in the stack, and a previous module obtained the user's password, that password is used to authenticate the user. If this fails, the authentication module returns failure without prompting the user for a password. This option has no effect if the authentication module is the first in the stack, or if no previous modules obtained the user's password. .It Cm try_first_pass This option is similar to the .Cm use_first_pass option, except that if the previously obtained password fails, the user is prompted for another password. .It Cm auth_as_self This option will require the user to authenticate themselves as themselves, not as the account they are attempting to access. This is primarily for services like .Xr su 1 , where the user's ability to retype their own password might be deemed sufficient. .It Cm nullok If the password database has no password for the entity being authenticated, then this option will forgo password prompting, and silently allow authentication to succeed. .Pp .Sy NOTE: If .Nm is invoked by a process that does not have the privileges required to access the password database (in most cases, this means root privileges), the .Cm nullok option may cause .Nm to allow any user to log in with any password. .It Cm emptyok If the password database contains the password for the entity being authenticated, but the password matches an empty string, then this option will forgo password prompting, and silently allow authentication to succeed. .Pp The difference between this and .Cm nullok is that it avoids prompting for password when the password is set to an empty string, as opposed to not being set. .It Cm local_pass Use only the local password database, even if NIS is in use. This will cause an authentication failure if the system is configured to only use NIS. .It Cm nis_pass Use only the NIS password database. This will cause an authentication failure if the system is not configured to use NIS. .El .Ss Ux Ss Account Management Module The .Ux account management component provides a function to perform account management, .Fn pam_sm_acct_mgmt . The function verifies that the authenticated user is allowed to log into the local user account by checking the following criteria: .Bl -dash -offset indent .It locked status of the account compatible with .Xr pw 8 .Cm lock ; .It the password expiry date from .Xr passwd 5 ; .It .Xr login.conf 5 restrictions on the remote host, login time, and tty. .El .Pp The following options may be passed to the management module: .Bl -tag -width ".Cm use_first_pass" .It Cm debug .Xr syslog 3 debugging information at .Dv LOG_DEBUG level. .El .Ss Ux Ss Password Management Module The .Ux password management component provides a function to perform password management, .Fn pam_sm_chauthtok . The function changes the user's password. .Pp The following options may be passed to the password module: .Bl -tag -width ".Cm use_first_pass" .It Cm debug .Xr syslog 3 debugging information at .Dv LOG_DEBUG level. .It Cm no_warn suppress warning messages to the user. These messages include reasons why the user's authentication attempt was declined. .It Cm local_pass forces the password module to change a local password in favour of a NIS one. .It Cm nis_pass forces the password module to change a NIS password in favour of a local one. .El .Sh FILES .Bl -tag -width ".Pa /etc/master.passwd" -compact .It Pa /etc/master.passwd default .Ux password database. .El .Sh SEE ALSO .Xr passwd 1 , .Xr getlogin 2 , .Xr crypt 3 , .Xr getpwent 3 , +.Xr pam 3 , .Xr syslog 3 , .Xr nsswitch.conf 5 , .Xr passwd 5 , -.Xr pam 3 , .Xr pw 8 , .Xr yp 8 .Sh BUGS The .Nm module ignores the .Dv PAM_CHANGE_EXPIRED_AUTHTOK flag. diff --git a/lib/libsysdecode/sysdecode_sctp_sinfo_flags.3 b/lib/libsysdecode/sysdecode_sctp_sinfo_flags.3 index e5995bff8329..4eb25187f0d0 100644 --- a/lib/libsysdecode/sysdecode_sctp_sinfo_flags.3 +++ b/lib/libsysdecode/sysdecode_sctp_sinfo_flags.3 @@ -1,50 +1,50 @@ .\" .\" Copyright (c) 2018 Michael Tuexen .\" 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. .\" .Dd January 14, 2018 .Dt sysdecode_sctp_sinfo_flags 3 .Os .Sh NAME .Nm sysdecode_sctp_sinfo_flags .Nd output textual description of the sinfo_flags field of struct sctp_sndrcvinfo .Sh LIBRARY .Lb libsysdecode .Sh SYNOPSIS .In sysdecode.h .Ft void .Fn sysdecode_sctp_sinfo_flags "FILE *fp" "int sinfo_flags" .Sh DESCRIPTION The .Fn sysdecode_sctp_sinfo_flags function outputs a textual description of the .Fa sinfo_flags member of a .Vt struct sctp_sndrcvinfo to the stream .Fa fp . In particular, the embedded PR-SCTP policies are handled. .Sh SEE ALSO -.Xr sysdecode 3 +.Xr sysdecode 3 , .Xr sysdecode_sctp_pr_policy 3 diff --git a/lib/libthr/libthr.3 b/lib/libthr/libthr.3 index 7d0c7669654a..6d33f4c378ce 100644 --- a/lib/libthr/libthr.3 +++ b/lib/libthr/libthr.3 @@ -1,362 +1,362 @@ .\" Copyright (c) 2005 Robert N. M. Watson .\" Copyright (c) 2014,2015,2021 The FreeBSD Foundation, Inc. .\" All rights reserved. .\" .\" Part of this documentation was written by .\" Konstantin Belousov 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. .\" 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 October 1, 2021 .Dt LIBTHR 3 .Os .Sh NAME .Nm libthr .Nd "1:1 POSIX threads library" .Sh LIBRARY .Lb libthr .Sh SYNOPSIS .In pthread.h .Sh DESCRIPTION The .Nm library provides a 1:1 implementation of the .Xr pthread 3 library interfaces for application threading. It has been optimized for use by applications expecting system scope thread semantics. .Pp The library is tightly integrated with the run-time link editor .Xr ld-elf.so.1 1 and .Lb libc ; all three components must be built from the same source tree. Mixing .Li libc and .Nm libraries from different versions of .Fx is not supported. The run-time linker .Xr ld-elf.so.1 1 has some code to ensure backward-compatibility with older versions of .Nm . .Pp The man page documents the quirks and tunables of the .Nm . When linking with .Li -lpthread , the run-time dependency .Li libthr.so.3 is recorded in the produced object. .Sh MUTEX ACQUISITION A locked mutex (see .Xr pthread_mutex_lock 3 ) is represented by a volatile variable of type .Dv lwpid_t , which records the global system identifier of the thread owning the lock. .Nm performs a contested mutex acquisition in three stages, each of which is more resource-consuming than the previous. The first two stages are only applied for a mutex of .Dv PTHREAD_MUTEX_ADAPTIVE_NP type and .Dv PTHREAD_PRIO_NONE protocol (see .Xr pthread_mutexattr 3 ) . .Pp First, on SMP systems, a spin loop is performed, where the library attempts to acquire the lock by .Xr atomic 9 operations. The loop count is controlled by the .Ev LIBPTHREAD_SPINLOOPS environment variable, with a default value of 2000. .Pp If the spin loop was unable to acquire the mutex, a yield loop is executed, performing the same .Xr atomic 9 acquisition attempts as the spin loop, but each attempt is followed by a yield of the CPU time of the thread using the .Xr sched_yield 2 syscall. By default, the yield loop is not executed. This is controlled by the .Ev LIBPTHREAD_YIELDLOOPS environment variable. .Pp If both the spin and yield loops failed to acquire the lock, the thread is taken off the CPU and put to sleep in the kernel with the .Xr _umtx_op 2 syscall. The kernel wakes up a thread and hands the ownership of the lock to the woken thread when the lock becomes available. .Sh THREAD STACKS Each thread is provided with a private user-mode stack area used by the C runtime. The size of the main (initial) thread stack is set by the kernel, and is controlled by the .Dv RLIMIT_STACK process resource limit (see .Xr getrlimit 2 ) . .Pp By default, the main thread's stack size is equal to the value of .Dv RLIMIT_STACK for the process. If the .Ev LIBPTHREAD_SPLITSTACK_MAIN environment variable is present in the process environment (its value does not matter), the main thread's stack is reduced to 4MB on 64bit architectures, and to 2MB on 32bit architectures, when the threading library is initialized. The rest of the address space area which has been reserved by the kernel for the initial process stack is used for non-initial thread stacks in this case. The presence of the .Ev LIBPTHREAD_BIGSTACK_MAIN environment variable overrides .Ev LIBPTHREAD_SPLITSTACK_MAIN ; it is kept for backward-compatibility. .Pp The size of stacks for threads created by the process at run-time with the .Xr pthread_create 3 call is controlled by thread attributes: see .Xr pthread_attr 3 , in particular, the .Xr pthread_attr_setstacksize 3 , .Xr pthread_attr_setguardsize 3 and .Xr pthread_attr_setstackaddr 3 functions. If no attributes for the thread stack size are specified, the default non-initial thread stack size is 2MB for 64bit architectures, and 1MB for 32bit architectures. .Sh RUN-TIME SETTINGS The following environment variables are recognized by .Nm and adjust the operation of the library at run-time: .Bl -tag -width "Ev LIBPTHREAD_SPLITSTACK_MAIN" .It Ev LIBPTHREAD_BIGSTACK_MAIN Disables the reduction of the initial thread stack enabled by .Ev LIBPTHREAD_SPLITSTACK_MAIN . .It Ev LIBPTHREAD_SPLITSTACK_MAIN Causes a reduction of the initial thread stack, as described in the section .Sx THREAD STACKS . This was the default behaviour of .Nm before .Fx 11.0 . .It Ev LIBPTHREAD_SPINLOOPS The integer value of the variable overrides the default count of iterations in the .Li spin loop of the mutex acquisition. The default count is 2000, set by the .Dv MUTEX_ADAPTIVE_SPINS constant in the .Nm sources. .It Ev LIBPTHREAD_YIELDLOOPS A non-zero integer value enables the yield loop in the process of the mutex acquisition. The value is the count of loop operations. .It Ev LIBPTHREAD_QUEUE_FIFO The integer value of the variable specifies how often blocked threads are inserted at the head of the sleep queue, instead of its tail. Bigger values reduce the frequency of the FIFO discipline. The value must be between 0 and 255. .It Dv LIBPTHREAD_UMTX_MIN_TIMEOUT The minimal amount of time, in nanoseconds, the thread is required to sleep for pthread operations specifying a timeout. If the operation requests a timeout less than the value provided, it is silently increased to the value. The value of zero means no minimum (default). .Pp .El The following .Dv sysctl MIBs affect the operation of the library: .Bl -tag -width "Dv debug.umtx.robust_faults_verbose" .It Dv kern.ipc.umtx_vnode_persistent By default, a shared lock backed by a mapped file in memory is automatically destroyed on the last unmap of the corresponding file's page, which is allowed by POSIX. Setting the sysctl to 1 makes such a shared lock object persist until the vnode is recycled by the Virtual File System. Note that in case file is not opened and not mapped, the kernel might recycle it at any moment, making this sysctl less useful than it sounds. .It Dv kern.ipc.umtx_max_robust The maximal number of robust mutexes allowed for one thread. The kernel will not unlock more mutexes than specified, see .Xr _umtx_op for more details. The default value is large enough for most useful applications. .It Dv debug.umtx.robust_faults_verbose A non zero value makes kernel emit some diagnostic when the robust mutexes unlock was prematurely aborted after detecting some inconsistency, as a measure to prevent memory corruption. .El .Pp The .Dv RLIMIT_UMTXP limit (see .Xr getrlimit 2 ) defines how many shared locks a given user may create simultaneously. .Sh INTERACTION WITH RUN-TIME LINKER On load, .Nm installs interposing handlers into the hooks exported by .Li libc . The interposers provide real locking implementation instead of the stubs for single-threaded processes in .Li libc , cancellation support and some modifications to the signal operations. .Pp .Nm cannot be unloaded; the .Xr dlclose 3 function does not perform any action when called with a handle for .Nm . One of the reasons is that the internal interposing of .Li libc functions cannot be undone. .Sh SIGNALS The implementation interposes the user-installed .Xr signal 3 handlers. This interposing is done to postpone signal delivery to threads which entered (libthr-internal) critical sections, where the calling of the user-provided signal handler is unsafe. An example of such a situation is owning the internal library lock. When a signal is delivered while the signal handler cannot be safely called, the call is postponed and performed until after the exit from the critical section. This should be taken into account when interpreting .Xr ktrace 1 logs. .Sh PROCESS-SHARED SYNCHRONIZATION OBJECTS In the .Li libthr implementation, user-visible types for all synchronization objects (e.g. pthread_mutex_t) are pointers to internal structures, allocated either by the corresponding .Fn pthread__init method call, or implicitly on first use when a static initializer was specified. The initial implementation of process-private locking object used this model with internal allocation, and the addition of process-shared objects was done in a way that did not break the application binary interface. .Pp For process-private objects, the internal structure is allocated using either .Xr malloc 3 or, for .Xr pthread_mutex_init 3 , an internal memory allocator implemented in .Nm . The internal allocator for mutexes is used to avoid bootstrap issues with many .Xr malloc 3 implementations which need working mutexes to function. The same allocator is used for thread-specific data, see .Xr pthread_setspecific 3 , for the same reason. .Pp For process-shared objects, the internal structure is created by first allocating a shared memory segment using .Xr _umtx_op 2 operation .Dv UMTX_OP_SHM , and then mapping it into process address space with .Xr mmap 2 with the .Dv MAP_SHARED flag. The POSIX standard requires that: .Bd -literal only the process-shared synchronization object itself can be used for performing synchronization. It need not be referenced at the address used to initialize it (that is, another mapping of the same object can be used). .Ed .Pp With the .Fx implementation, process-shared objects require initialization in each process that use them. In particular, if you map the shared memory containing the user portion of a process-shared object already initialized in different process, locking functions do not work on it. .Pp Another broken case is a forked child creating the object in memory shared with the parent, which cannot be used from parent. Note that processes should not use non-async-signal safe functions after .Xr fork 2 anyway. .Sh SEE ALSO .Xr ktrace 1 , .Xr ld-elf.so.1 1 , -.Xr getrlimit 2 , +.Xr _umtx_op 2 , .Xr errno 2 , +.Xr getrlimit 2 , .Xr thr_exit 2 , .Xr thr_kill 2 , .Xr thr_kill2 2 , .Xr thr_new 2 , .Xr thr_self 2 , .Xr thr_set_name 2 , -.Xr _umtx_op 2 , .Xr dlclose 3 , .Xr dlopen 3 , .Xr getenv 3 , .Xr pthread_attr 3 , .Xr pthread_attr_setstacksize 3 , .Xr pthread_create 3 , .Xr signal 3 , .Xr atomic 9 .Sh HISTORY The .Nm library first appeared in .Fx 5.2 . .Sh AUTHORS .An -nosplit The .Nm library was originally created by .An Jeff Roberson Aq Mt jeff@FreeBSD.org , and enhanced by .An Jonathan Mini Aq Mt mini@FreeBSD.org and .An Mike Makonnen Aq Mt mtm@FreeBSD.org . It has been substantially rewritten and optimized by .An David Xu Aq Mt davidxu@FreeBSD.org . diff --git a/lib/libveriexec/veriexec.3 b/lib/libveriexec/veriexec.3 index 8fd5822c8067..b367fc5ea40f 100644 --- a/lib/libveriexec/veriexec.3 +++ b/lib/libveriexec/veriexec.3 @@ -1,63 +1,63 @@ .\" Copyright (c) 2018, Juniper Networks, 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. .\" .Dd June 19, 2018 .Dt VERIEXEC 3 .Os .Sh NAME .Nm veriexec_check_fd , .Nm veriexec_check_path .Nd Verified execution routines .Sh LIBRARY .Lb libveriexec .Sh SYNOPSIS .In libveriexec.h .Ft int .Fn veriexec_check_fd "int fd" .Ft int .Fn veriexec_check_path "const char *file" .Sh DESCRIPTION The .Fn veriexec_check_fd function checks the signature of the file represented by the .Fa fd file descriptor. .Pp The .Fn veriexec_check_path function checks the signature of the file path .Fa file . .Pp The .Fn veriexec_check_fd and .Fn veriexec_check_path functions return zero on a successful signature match or if veriexec is not enabled. If the signature does not match, .Va errno is set to the reason for the mismatch. .Sh SEE ALSO -.Xr mac_veriexec 4 +.Xr mac_veriexec 4 , .Xr veriexec 4 diff --git a/sbin/comcontrol/comcontrol.8 b/sbin/comcontrol/comcontrol.8 index 46c7f987d774..e050452498b9 100644 --- a/sbin/comcontrol/comcontrol.8 +++ b/sbin/comcontrol/comcontrol.8 @@ -1,63 +1,63 @@ .Dd May 15, 1994 .Dt COMCONTROL 8 .Os .Sh NAME .Nm comcontrol .Nd control a special tty device .Sh SYNOPSIS .Nm .Ar special_device .Op dtrwait Ar number .Op drainwait Ar number .Sh DESCRIPTION The .Nm utility is used to examine and modify some of the special characteristics of the specified tty device. If no arguments other than the device (or "-" for stdin) are specified, it prints the settings of all controllable characteristics. This usage requires only read access on the device. Only the superuser can change the settings. .Pp The following options are available: .Bl -tag -width indent .It Cm dtrwait Ar number Set the time to wait after dropping DTR to the given number. The units are hundredths of a second. The default is 300 hundredths, i.e., 3 seconds. This option needed mainly to set proper recover time after modem reset. .It Cm drainwait Ar number Set the time to wait for output drain to the given number. The units are seconds. The default is 5 minutes, 0 means waiting forever. This option needed mainly to specify upper limit of minutes to prevent modem hanging. .El .Pp The standard way to use .Nm is to put invocations of it in the .Pa /etc/rc.d/serial startup script. .Sh FILES .Bl -tag -width /dev/ttyd? -compact .It Pa /dev/ttyd? dialin devices, hardwired terminals .It Pa /dev/cuau? dialout devices .El .Sh SEE ALSO -.Xr stty 1 , +.Xr stty 1 .Sh HISTORY Originally part of cgd's com package patches, version 0.2.1, to .Bx 386 0.1 . Once controlled bidirectional capabilities. Little is left to control now that these capabilities are standard. .Sh AUTHORS .An Christopher G. Demetriou diff --git a/sbin/newfs/newfs.8 b/sbin/newfs/newfs.8 index 0dc93cb8b78d..4ac6e56879b4 100644 --- a/sbin/newfs/newfs.8 +++ b/sbin/newfs/newfs.8 @@ -1,387 +1,387 @@ .\" Copyright (c) 1983, 1987, 1991, 1993, 1994 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)newfs.8 8.6 (Berkeley) 5/3/95 .\" .Dd May 18, 2024 .Dt NEWFS 8 .Os .Sh NAME .Nm newfs .Nd construct a new UFS1/UFS2 file system .Sh SYNOPSIS .Nm .Op Fl EJNUjlnt .Op Fl L Ar volname .Op Fl O Ar filesystem-type .Op Fl S Ar sector-size .Op Fl T Ar disktype .Op Fl a Ar maxcontig .Op Fl b Ar block-size .Op Fl c Ar blocks-per-cylinder-group .Op Fl d Ar max-extent-size .Op Fl e Ar maxbpg .Op Fl f Ar frag-size .Op Fl g Ar avgfilesize .Op Fl h Ar avgfpdir .Op Fl i Ar bytes .Op Fl k Ar held-for-metadata-blocks .Op Fl m Ar free-space .Op Fl o Ar optimization .Op Fl p Ar partition .Op Fl r Ar reserved .Op Fl s Ar size .Ar special .Sh DESCRIPTION The .Nm utility is used to initialize and clear file systems before first use. The .Nm utility builds a file system on the specified special file. (We often refer to the .Dq special file as the .Dq disk , although the special file need not be a physical disk. In fact, it need not even be special.) Typically the defaults are reasonable, however .Nm has numerous options to allow the defaults to be selectively overridden. .Pp The following options define the general layout policies: .Bl -tag -width indent .It Fl E Erase the content of the disk before making the filesystem. The reserved area in front of the superblock (for bootcode) will not be erased. Erasing is only relevant to flash-memory or thinly provisioned devices. Erasing may take a long time. If the device does not support BIO_DELETE, the command will fail. .It Fl J Enable journaling on the new file system via gjournal. See .Xr gjournal 8 for details. .It Fl L Ar volname Add a volume label to the new file system. Legal characters are alphanumerics, dashes, and underscores. .It Fl N Cause the file system parameters to be printed out without really creating the file system. .It Fl O Ar filesystem-type Use 1 to specify that a UFS1 format file system be built; use 2 to specify that a UFS2 format file system be built. The default format is UFS2. .It Fl T Ar disktype For backward compatibility. .It Fl U Enable soft updates on the new file system. Soft updates are enabled by default for UFS2 format file systems. Use .Xr tunefs 8 to disable soft updates if they are not wanted. .It Fl a Ar maxcontig Specify the maximum number of contiguous blocks that will be laid out before forcing a rotational delay. The default value is 16. See .Xr tunefs 8 for more details on how to set this option. .It Fl b Ar block-size The block size of the file system, in bytes. It must be a power of 2. .\" If changing the default block size and it causes the default .\" fragment size to change, be sure to update the location of .\" the first backup superblock on the fsck_ffs.8 manual page. The default size is 32768 bytes, and the smallest allowable size is 4096 bytes. The optimal block:fragment ratio is 8:1. Other ratios are possible, but are not recommended, and may produce poor results. .It Fl c Ar blocks-per-cylinder-group The number of blocks per cylinder group in a file system. The default is to compute the maximum allowed by the other parameters. This value is dependent on a number of other parameters, in particular the block size and the number of bytes per inode. .It Fl d Ar max-extent-size The file system may choose to store large files using extents. This parameter specifies the largest extent size that may be used. The default value is the file system blocksize. It is presently limited to a maximum value of 16 times the file system blocksize and a minimum value of the file system blocksize. .It Fl e Ar maxbpg Indicate the maximum number of blocks any single file can allocate out of a cylinder group before it is forced to begin allocating blocks from another cylinder group. The default is about one quarter of the total blocks in a cylinder group. See .Xr tunefs 8 for more details on how to set this option. .It Fl f Ar frag-size The fragment size of the file system in bytes. It must be a power of two ranging in value between .Ar blocksize Ns /8 and .Ar blocksize . .\" If changing the default fragment size or it changes because of a .\" change to the default block size, be sure to update the location .\" of the first backup superblock on the fsck_ffs.8 manual page. The default is 4096 bytes. .It Fl g Ar avgfilesize The expected average file size for the file system. .It Fl h Ar avgfpdir The expected average number of files per directory on the file system. .It Fl i Ar bytes Specify the density of inodes in the file system. The default is to create an inode for every .Pq 2 * Ar frag-size bytes of data space. If fewer inodes are desired, a larger number should be used; to create more inodes a smaller number should be given. One inode is required for each distinct file, so this value effectively specifies the average file size on the file system. .It Fl j Enable soft updates journaling on the new file system. This flag is implemented by running the .Xr tunefs 8 utility found in the user's .Dv $PATH . .Pp Enabling journaling reduces the time spent by .Xr fsck_ffs 8 cleaning up a filesystem after a crash to a few seconds from minutes to hours. Without journaling, the time to recover after a crash is a function of the number of files in the filesystem and the size of the filesystem. With journaling, the time to recover after a crash is a function of the amount of activity in the filesystem in the minute before the crash. Journaled recovery time is usually only a few seconds and never exceeds a minute. .Pp The drawback to using journaling is that the writes to its log adds an extra write load to the media containing the filesystem. Thus a write-intensive workload will have reduced throughput on a filesystem running with journaling. .Pp Like all journaling filesystems, the journal recovery will only fix issues known to the journal. Specifically if a media error occurs, the journal will not know about it and hence will not fix it. Thus when using journaling, it is still necessary to run a full fsck every few months or after a filesystem panic to check for and fix any errors brought on by media failure. A full fsck can be done by running a background fsck on a live filesystem or by running with the .Fl f flag on an unmounted filesystem. When running .Xr fsck_ffs 8 in background on a live filesystem the filesystem performance will be about half of normal during the time that the background .Xr fsck_ffs 8 is running. Running a full fsck on a UFS filesystem is the equivalent of running a scrub on a ZFS filesystem. .It Fl k Ar held-for-metadata-blocks Set the amount of space to be held for metadata blocks in each cylinder group. When set, the file system preference routines will try to save the specified amount of space immediately following the inode blocks in each cylinder group for use by metadata blocks. Clustering the metadata blocks speeds up random file access and decreases the running time of .Xr fsck 8 . By default .Nm sets it to half of the space reserved to minfree. .It Fl l Enable multilabel MAC on the new file system. .It Fl m Ar free-space The percentage of space reserved from normal users; the minimum free space threshold. The default value used is defined by .Dv MINFREE from .In ufs/ffs/fs.h , currently 8%. See .Xr tunefs 8 for more details on how to set this option. .It Fl n Do not create a .Pa .snap directory on the new file system. The resulting file system will not support snapshot generation, so .Xr dump 8 in live mode and background .Xr fsck 8 will not function properly. The traditional .Xr fsck 8 and offline .Xr dump 8 will work on the file system. This option is intended primarily for memory or vnode-backed file systems that do not require .Xr dump 8 or .Xr fsck 8 support. .It Fl o Ar optimization .Cm ( space or .Cm time ) . The file system can either be instructed to try to minimize the time spent allocating blocks, or to try to minimize the space fragmentation on the disk. If the value of minfree (see above) is less than 8%, the default is to optimize for .Cm space ; if the value of minfree is greater than or equal to 8%, the default is to optimize for .Cm time . See .Xr tunefs 8 for more details on how to set this option. .It Fl p Ar partition The partition name (a..h) you want to use in case the underlying image is a file, so you do not have access to individual partitions through the filesystem. Can also be used with a device, e.g., .Nm .Fl p Ar f .Ar /dev/da1s3 is equivalent to .Nm .Ar /dev/da1s3f . .It Fl r Ar reserved The size, in sectors, of reserved space at the end of the partition specified in .Ar special . This space will not be occupied by the file system; it can be used by other consumers such as .Xr geom 4 . Defaults to 0. .It Fl s Ar size The size of the file system in sectors. This value defaults to the size of the raw partition specified in .Ar special less the .Ar reserved space at its end (see .Fl r ) . A .Ar size of 0 can also be used to choose the default value. A valid .Ar size value cannot be larger than the default one, which means that the file system cannot extend into the reserved space. .It Fl t Turn on the TRIM enable flag. If enabled, and if the underlying device supports the BIO_DELETE command, the file system will send a delete request to the underlying device for each freed block. The trim enable flag is typically set for flash-memory devices to reduce write amplification which reduces wear on write-limited flash-memory and often improves long-term performance. Thinly provisioned storage also benefits by returning unused blocks to the global pool. .El .Pp The following options override the standard sizes for the disk geometry. Their default values are taken from the disk label. Changing these defaults is useful only when using .Nm to build a file system whose raw image will eventually be used on a different type of disk than the one on which it is initially created (for example on a write-once disk). Note that changing any of these values from their defaults will make it impossible for .Xr fsck 8 to find the alternate superblocks if the standard superblock is lost. .Bl -tag -width indent .It Fl S Ar sector-size The size of a sector in bytes (almost never anything but 512). .El .Sh NOTES ON THE NAMING .Dq newfs is a common name prefix for utilities creating filesystems, with the suffix indicating the type of the filesystem, for instance .Xr newfs_msdos 8 . The .Nm utility is a special case which predates that convention. .Sh EXAMPLES .Dl newfs /dev/ada3s1a .Pp Creates a new ufs file system on .Pa ada3s1a . The .Nm utility will use a block size of 32768 bytes, a fragment size of 4096 bytes and the largest possible number of blocks per cylinders group. These values tend to produce better performance for most applications than the historical defaults (8192 byte block size and 1024 byte fragment size). This large fragment size may lead to much wasted space on file systems that contain many small files. .Sh SEE ALSO -.Xr fdformat 8 , .Xr geom 4 , .Xr disktab 5 , .Xr fs 5 , .Xr camcontrol 8 , .Xr dump 8 , .Xr dumpfs 8 , +.Xr fdformat 8 , .Xr fsck 8 , .Xr gjournal 8 , .Xr gpart 8 , .Xr growfs 8 , .Xr gvinum 8 , .Xr makefs 8 , .Xr mount 8 , .Xr newfs_msdos 8 , .Xr tunefs 8 .Rs .%A M. McKusick .%A W. Joy .%A S. Leffler .%A R. Fabry .%T A Fast File System for UNIX .%J ACM Transactions on Computer Systems 2 .%V 3 .%P pp 181-197 .%D August 1984 .%O (reprinted in the BSD System Manager's Manual) .Re .Sh HISTORY The .Nm utility appeared in .Bx 4.2 . diff --git a/sbin/umount/umount.8 b/sbin/umount/umount.8 index 086980151d60..2c26ca868dae 100644 --- a/sbin/umount/umount.8 +++ b/sbin/umount/umount.8 @@ -1,196 +1,196 @@ .\" Copyright (c) 1980, 1989, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd January 16, 2024 .Dt UMOUNT 8 .Os .Sh NAME .Nm umount .Nd unmount file systems .Sh SYNOPSIS .Nm .Op Fl dfNnv .Ar special ... | node ... | fsid ... .Nm .Fl a | A .Op Fl F Ar fstab .Op Fl fnv .Op Fl h Ar host .Op Fl t Ar type .Sh DESCRIPTION The .Nm utility calls the .Xr unmount 2 system call to remove a file system from the file system tree. The file system can be specified by its .Ar special device or remote node .Pq Ar rhost Ns Cm \& : Ns Ar path , the path to the mount point .Ar node or by the file system ID .Ar fsid as reported by .Dq mount -v when run by root. .Pp The options are as follows: .Bl -tag -width "-F fstab" .It Fl a All the file systems described in .Xr fstab 5 are unmounted. .It Fl A All the currently mounted file systems are unmounted, except for those mounted at .Pa / or .Pa /dev . .It Fl d If the filesystem is mounted on an .Xr md 4 device (a memory disk), detach it after .Xr unmount 2 . .It Fl F Ar fstab Specify the .Pa fstab file to use. .It Fl f The file system is forcibly unmounted. Active special devices continue to work, but all other files return errors if further accesses are attempted. The root file system cannot be forcibly unmounted. For NFS, a forced dismount can take up to 1 minute or more to complete against an unresponsive server and may throw away data not yet written to the server for this case. If a process, such as .Nm without the .Fl f flag is hung on an .Tn NFS mount point, use the .Fl N flag instead. Also, doing a forced dismount of an NFSv3 mount when .Xr rpc.lockd 8 is running is unsafe and can result in a crash. .It Fl h Ar host Only file systems mounted from the specified host will be unmounted. This option implies the .Fl A option and, unless otherwise specified with the .Fl t option, will only unmount .Tn NFS file systems. .It Fl N Do a forced dismount of an .Tn NFS mount point without checking the mount path. This option can only be used with the path to the mount point .Ar node and the path must be specified exactly as it was at mount time. This option is useful when a process is hung waiting for an unresponsive .Tn NFS server while holding a vnode lock on the mounted-on vnode, such that .Nm with the .Fl f flag can't complete. Using this option can result in a loss of file updates that have not been flushed to the .Tn NFS server. .It Fl n Unless the .Fl f is used, the .Nm will not unmount an active file system. It will, however, perform a flush. This flag disables this behaviour, preventing the flush if there are any files open. .It Fl t Ar type Is used to indicate the actions should only be taken on file systems of the specified type. More than one type may be specified in a comma separated list. The list of file system types can be prefixed with .Dq no to specify the file system types for which action should .Em not be taken. For example, the .Nm command: .Bd -literal -offset indent umount -a -t nfs,nullfs .Ed .Pp unmounts all file systems of the type .Tn NFS and .Tn NULLFS that are listed in the .Xr fstab 5 file. .It Fl v Verbose, additional information is printed out as each file system is unmounted. .El .Sh ENVIRONMENT .Bl -tag -width ".Ev PATH_FSTAB" .It Ev PATH_FSTAB If the environment variable .Ev PATH_FSTAB is set, all operations are performed against the specified file. .Ev PATH_FSTAB will not be honored if the process environment or memory address space is considered .Dq tainted . (See .Xr issetugid 2 for more information.) .El .Sh FILES .Bl -tag -width /etc/fstab -compact .It Pa /etc/fstab file system table .El .Sh SEE ALSO .Xr unmount 2 , .Xr fstab 5 , .Xr autounmountd 8 , -.Xr mount 8 , -.Xr mdconfig 8 +.Xr mdconfig 8 , +.Xr mount 8 .Sh HISTORY A .Nm utility appeared in .At v1 . diff --git a/share/man/man4/atopcase.4 b/share/man/man4/atopcase.4 index fc93b7094466..830c67f872a4 100644 --- a/share/man/man4/atopcase.4 +++ b/share/man/man4/atopcase.4 @@ -1,134 +1,134 @@ .\" Copyright (c) 2023 Vladimir Kondratyev .\" .\" 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. .\" .Dd August 17, 2023 .Dt ATOPCASE 4 .Os .Sh NAME .Nm atopcase .Nd Apple HID-over-SPI transport driver .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device atopcase" .Cd "device intelspi" .Cd "device spibus" .Cd "device hidbus" .Cd "device hkbd" .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 atopcase_load="YES" hkbd_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for Human Interface Devices (HID) on Serial Peripheral Interface (SPI) buses on Apple Intel Macs. .Sh HARDWARE The .Nm driver supports the following MacBooks produced in 2015-2018 years: .Pp .Bl -bullet -compact .It Macbook8,1 .It Macbook9,1 .It Macbook10,1 .It MacbookPro11,4 .It MacbookPro12,1 .It MacbookPro13,1 .It MacbookPro13,2 .It MacbookPro13,3 .It MacbookPro14,1 .It MacbookPro14,2 .It MacbookPro14,3 .El .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 hw.hid.atopcase.debug Debug output level, where 0 is debugging disabled and larger values increase debug message verbosity. Default is 0. .El .Sh FILES .Bl -tag -width ".Pa /dev/backlight/atopcase0" -compact .It Pa /dev/backlight/atopcase0 Keyboard .Xr backlight 8 device node. .El .Sh SEE ALSO .Xr acpi 4 , +.Xr loader.conf 5 , .Xr backlight 8 , -.Xr loader 8 , -.Xr loader.conf 5 . +.Xr loader 8 .Sh HISTORY The .Nm driver first appeared in .Fx 14.0. .Sh AUTHORS .An -nosplit The .Nm driver was originally written by .An Val Packett Aq Mt val@packett.cool and marginally improved upon by .An Vladimir Kondratyev Aq Mt wulf@FreeBSD.org . .Pp This manual page was written by .An Vladimir Kondratyev Aq Mt wulf@FreeBSD.org . .Sh BUGS Device interrupts are not acknowledged on some hardware that results in interrupt storm. Installation of Darwin OSI in .Xr acpi 4 driver fixes the issue. To install Darwin OSI add following lines to .Xr loader.conf 5 : .Bl -tag -width indent .It Va hw.acpi.install_interface="Darwin" .It Va hw.acpi.remove_interface="Windows 2009, Windows 2012" .El diff --git a/share/man/man4/cd.4 b/share/man/man4/cd.4 index 7c3fa6ed9850..0260d5ec5a8f 100644 --- a/share/man/man4/cd.4 +++ b/share/man/man4/cd.4 @@ -1,361 +1,362 @@ .\" Copyright (c) 1996 .\" Julian Elischer . All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd April 8, 2022 .Dt CD 4 .Os .Sh NAME .Nm cd .Nd SCSI CD-ROM driver .Sh SYNOPSIS .Cd device cd .Sh DESCRIPTION The .Nm driver provides support for a .Tn SCSI .Tn CD-ROM (Compact Disc-Read Only Memory) drive. In an attempt to look like a regular disk, the .Nm driver synthesizes a partition table, with one partition covering the entire .Tn CD-ROM . It is possible to modify this partition table using .Xr disklabel 8 , but it will only last until the .Tn CD-ROM is unmounted. In general the interfaces are similar to those described by .Xr ada 4 and .Xr da 4 . .Pp As the .Tn SCSI adapter is probed during boot, the .Tn SCSI bus is scanned for devices. Any devices found which answer as CDROM (type 5) or WORM (type 4) type devices will be `attached' to the .Nm driver. Prior to .Fx 2.1 , the first device found will be attached as .Li cd0 the next, .Li cd1 , etc. Beginning in .Fx 2.1 it is possible to specify what cd unit a device should come on line as; refer to .Xr scsi 4 for details on kernel configuration. .Pp The system utility .Xr disklabel 8 may be used to read the synthesized disk label structure, which will contain correct figures for the size of the .Tn CD-ROM should that information be required. .Sh KERNEL CONFIGURATION Any number of .Tn CD-ROM devices may be attached to the system regardless of system configuration as all resources are dynamically allocated. .Sh IOCTLS The following .Xr ioctl 2 calls which apply to .Tn SCSI .Tn CD-ROM drives are defined in the header files .In sys/cdio.h and .In sys/disklabel.h . .Bl -tag -width CDIOCREADSUBCHANNEL .It Dv CDIOCPLAYTRACKS .Pq Li "struct ioc_play_track" Start audio playback given a track address and length. The structure is defined as follows: .Bd -literal -offset indent struct ioc_play_track { u_char start_track; u_char start_index; u_char end_track; u_char end_index; }; .Ed .It Dv CDIOCPLAYBLOCKS .Pq Li "struct ioc_play_blocks" Start audio playback given a block address and length. The structure is defined as follows: .Bd -literal -offset indent struct ioc_play_blocks { int blk; int len; }; .Ed .It Dv CDIOCPLAYMSF .Pq Li "struct ioc_play_msf" Start audio playback given a `minutes-seconds-frames' address and length. The structure is defined as follows: .Bd -literal -offset indent struct ioc_play_msf { u_char start_m; u_char start_s; u_char start_f; u_char end_m; u_char end_s; u_char end_f; }; .Ed .It Dv CDIOCREADSUBCHANNEL .Pq Li "struct ioc_read_subchannel" Read information from the subchannel at the location specified by this structure: .Bd -literal -offset indent struct ioc_read_subchannel { u_char address_format; #define CD_LBA_FORMAT 1 #define CD_MSF_FORMAT 2 u_char data_format; #define CD_SUBQ_DATA 0 #define CD_CURRENT_POSITION 1 #define CD_MEDIA_CATALOG 2 #define CD_TRACK_INFO 3 u_char track; int data_len; struct cd_sub_channel_info *data; }; .Ed .It Dv CDIOREADTOCHEADER .Pq Li "struct ioc_toc_header" Return summary information about the table of contents for the mounted .Tn CD-ROM . The information is returned into the following structure: .Bd -literal -offset indent struct ioc_toc_header { u_short len; u_char starting_track; u_char ending_track; }; .Ed .It Dv CDIOREADTOCENTRYS .Pq Li "struct ioc_read_toc_entry" Return information from the table of contents entries mentioned. .Pq Yes, this command name is misspelled. The argument structure is defined as follows: .Bd -literal -offset indent struct ioc_read_toc_entry { u_char address_format; u_char starting_track; u_short data_len; struct cd_toc_entry *data; }; .Ed The requested data is written into an area of size .Li data_len and pointed to by .Li data . .It Dv CDIOCSETPATCH .Pq Li "struct ioc_patch" Attach various audio channels to various output channels. The argument structure is defined thusly: .Bd -literal -offset indent struct ioc_patch { u_char patch[4]; /* one for each channel */ }; .Ed .It Dv CDIOCGETVOL .It Dv CDIOCSETVOL .Pq Li "struct ioc_vol" Get (set) information about the volume settings of the output channels. The argument structure is as follows: .Bd -literal -offset indent struct ioc_vol { u_char vol[4]; /* one for each channel */ }; .Ed .It Dv CDIOCSETMONO Patch all output channels to all source channels. .It Dv CDIOCSETSTEREO Patch left source channel to the left output channel and the right source channel to the right output channel. .It Dv CDIOCSETMUTE Mute output without changing the volume settings. .It Dv CDIOCSETLEFT .It Dv CDIOCSETRIGHT Attach both output channels to the left (right) source channel. .It Dv CDIOCSETDEBUG .It Dv CDIOCCLRDEBUG Turn on (off) debugging for the appropriate device. .It Dv CDIOCPAUSE .It Dv CDIOCRESUME Pause (resume) audio play, without resetting the location of the read-head. .It Dv CDIOCRESET Reset the drive. .It Dv CDIOCSTART .It Dv CDIOCSTOP Tell the drive to spin-up (-down) the .Tn CD-ROM . .It Dv CDIOCALLOW .It Dv CDIOCPREVENT Tell the drive to allow (prevent) manual ejection of the .Tn CD-ROM disc. Not all drives support this feature. .It Dv CDIOCEJECT Eject the .Tn CD-ROM . .It Dv CDIOCCLOSE Tell the drive to close its door and load the media. Not all drives support this feature. .El .Sh NOTES When a .Tn CD-ROM is changed in a drive controlled by the .Nm driver, then the act of changing the media will invalidate the disklabel and information held within the kernel. To stop corruption, all accesses to the device will be discarded until there are no more open file descriptors referencing the device. During this period, all new open attempts will be rejected. When no more open file descriptors reference the device, the first next open will load a new set of parameters (including disklabel) for the drive. .Pp The audio code in the .Nm driver only support .Tn SCSI-2 standard audio commands. As many .Tn CD-ROM manufacturers have not followed the standard, there are many .Tn CD-ROM drives for which audio will not work. Some work is planned to support some of the more common `broken' .Tn CD-ROM drives; however, this is not yet under way. .Sh SYSCTL VARIABLES The following variables are available as both .Xr sysctl 8 variables and .Xr loader 8 tunables: .Bl -tag -width 12 .It kern.cam.cd.retry_count .Pp This variable determines how many times the .Nm driver will retry a READ or WRITE command. This does not affect the number of retries used during probe time or for the .Nm driver dump routine. This value currently defaults to 4. .It kern.cam.cd.%d.minimum_cmd_size .Pp The .Nm driver attempts to automatically determine whether the drive it is talking to supports 6 byte or 10 byte MODE SENSE/MODE SELECT operations. Many .Tn SCSI drives only support 6 byte commands, and .Tn ATAPI drives only support 10 byte commands. The .Nm driver first attempts to determine whether the protocol in use typically supports 6 byte commands by issuing a CAM Path Inquiry CCB. It will then default to 6 byte or 10 byte commands as appropriate. After that, the .Nm driver defaults to using 6 byte commands (assuming the protocol the drive speaks claims to support 6 byte commands), until one fails with a .Tn SCSI ILLEGAL REQUEST error. Then it tries the 10 byte version of the command to see if that works instead. Users can change the default via per-drive sysctl variables and loader tunables. Where .Dq %d is the unit number of the drive in question. Valid minimum command sizes are 6 and 10. Any value above 6 will be rounded to 10, and any value below 6 will be rounded to 6. .El .Sh FILES .Bl -tag -width /dev/cd[0-9][a-h] -compact .It Pa /dev/cd[0-9][a-h] raw mode .Tn CD-ROM devices .El .Sh DIAGNOSTICS None. .Sh SEE ALSO .Xr cam 4 , +.Xr cd9660 4 , .Xr da 4 , .Xr cd9660 5 , .Xr disklabel 8 , .Xr cd 9 .Sh HISTORY This .Nm driver is based upon the .Nm driver written by Julian Elischer, which appeared in .Bx 386 0.1 . The CAM version of the .Nm driver was written by Kenneth Merry and first appeared in .Fx 3.0 . .Sh BUGS The names of the structures used for the third argument to .Fn ioctl were poorly chosen, and a number of spelling errors have survived in the names of the .Fn ioctl commands. diff --git a/share/man/man4/cdce.4 b/share/man/man4/cdce.4 index 9d842e475d85..87a6f5da4b08 100644 --- a/share/man/man4/cdce.4 +++ b/share/man/man4/cdce.4 @@ -1,182 +1,182 @@ .\" Copyright (c) 2004 Daniel Hartmeier .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" .\" - Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" - Redistributions in binary form must reproduce the above .\" copyright notice, this list of conditions and the following .\" disclaimer in the documentation and/or other materials provided .\" with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS .\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER .\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN .\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" .\" $NetBSD: cdce.4,v 1.4 2004/12/08 18:35:56 peter Exp $ .\" .Dd May 3, 2024 .Dt CDCE 4 .Os .Sh NAME .Nm cdce .Nd "USB Communication Device Class Ethernet (CDC ECM/NCM) driver" .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device uhci" .Cd "device ohci" .Cd "device usb" .Cd "device miibus" .Cd "device uether" .Cd "device cdce" .Ed .Pp Mobile Devices (eg. Huawei E3372, E5573 and others) may need additionally the u3g command port: .Bd -ragged -offset indent .Cd "device ucom" .Cd "device u3g" .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_cdce_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for USB Host-to-Host (aka USB-to-USB) and USB-to-Ethernet bridges based on the USB Communication Device Class Ethernet Control Model (CDC ECM) and Network Control Model (CDC NCM) specifications. It also provides device-side CDC ECM support. .Pp The USB bridge appears as a regular network interface on both sides, transporting Ethernet frames. .Pp For more information on configuring this device, see .Xr ifconfig 8 . .Pp USB 1.x bridges support speeds of up to 12Mbps, and USB 2.0 speeds of up to 480Mbps. .Pp Packets are received and transmitted over separate USB bulk transfer endpoints. .Pp The .Nm driver does not support different media types or options. .Pp Mobile .Nm Network Devices may need a connect command sequence via u3g serial command port before they activate the NCM/ECM/ACM network interface. For example: .Dl echo 'AT^NDISUP=1,1,"internet"' > /dev/cuaU[0].0 where .Dq internet is your providers apn name. .Sh HARDWARE The following devices are supported by the .Nm driver: .Pp .Bl -bullet -compact .It Prolific PL-2501 Host-to-Host Bridge Controller .It Sharp Zaurus PDA .It Terayon TJ-715 DOCSIS Cable Modem .It Huawei 3G/4G LTE (eg. E3372, E5573) and other mobile network devices .El .Sh DIAGNOSTICS .Bl -diag .It "cdce%d: no union descriptor" The driver could not fetch an interface descriptor from the USB device. For a manually added USB vendor/product, the CDCE_NO_UNION flag can be tried to work around the missing descriptor. .It "cdce%d: no data interface" .It "cdce%d: could not read endpoint descriptor" .It "cdce%d: unexpected endpoint" .It "cdce%d: could not find data bulk in/out" For a manually added USB vendor/product, these errors indicate that the bridge is not compatible with the driver. .It "cdce%d: watchdog timeout" A packet was queued for transmission and a transmit command was issued, however the device failed to acknowledge the transmission before a timeout expired. .It "cdce%d: no memory for rx list -- packet dropped!" Memory allocation through MGETHDR or MCLGET failed, the system is running low on mbufs. .It "cdce%d: abort/close rx/tx pipe failed" .It "cdce%d: rx/tx list init failed" .It "cdce%d: open rx/tx pipe failed" .It "cdce%d: usb error on rx/tx" .El .Sh SEE ALSO .Xr arp 4 , .Xr cdceem 4 , .Xr intro 4 , .Xr ipheth 4 , .Xr netintro 4 , +.Xr u3g 4 , +.Xr ucom 4 , .Xr urndis 4 , .Xr usb 4 , -.Xr ucom 4 , -.Xr u3g 4 , .Xr ifconfig 8 .Rs .%T "Universal Serial Bus Class Definitions for Communication Devices" .%U http://www.usb.org/developers/devclass_docs/usbcdc11.pdf .Re .Rs .%T "Data sheet Prolific PL-2501 Host-to-Host Bridge/Network Controller" .%U http://tech.prolific.com.tw/visitor/fcabdl.asp?fid=20679530 .Re .Sh HISTORY The .Nm device driver first appeared in .Ox 3.6 , .Nx 3.0 and .Fx 6.0 . .Sh AUTHORS .An -nosplit The .Nm driver was written by .An Craig Boston Aq Mt craig@tobuj.gank.org based on the .Xr aue 4 driver written by .An Bill Paul Aq Mt wpaul@windriver.com and ported to .Ox by .An Daniel Hartmeier Aq Mt dhartmei@openbsd.org . .Sh CAVEATS Many USB devices notoriously fail to report their class and interfaces correctly. Undetected products might work flawlessly when their vendor and product IDs are added to the driver manually. diff --git a/share/man/man4/dummynet.4 b/share/man/man4/dummynet.4 index 81b1b33efb6e..ad82cb80011d 100644 --- a/share/man/man4/dummynet.4 +++ b/share/man/man4/dummynet.4 @@ -1,80 +1,80 @@ .\" .Dd September 10, 2021 .Dt DUMMYNET 4 .Os .Sh NAME .Nm dummynet .Nd traffic shaper, bandwidth manager and delay emulator .Sh DESCRIPTION The .Nm system facility permits the control of traffic going through the various network interfaces, by applying bandwidth and queue size limitations, implementing different scheduling and queue management policies, and emulating delays and losses. .Pp The user interface for .Nm is implemented by the .Xr dnctl 8 utility, so please refer to the .Xr dnctl 8 manpage for a complete description of the .Nm capabilities and how to use it. .Ss Kernel Options The following options in the kernel configuration file are related to .Nm operation: .Pp .Bl -tag -width ".Dv IPFIREWALL_VERBOSE_LIMIT" -offset indent -compact .It Dv IPFIREWALL enable ipfirewall (if .Nm is to be used with ipfw) .It Dv IPFIREWALL_VERBOSE enable firewall output .It Dv IPFIREWALL_VERBOSE_LIMIT limit firewall output .It Dv DUMMYNET enable .Nm operation .It Dv HZ set the timer granularity .El .Pp Generally, the following options are required: .Bd -literal -offset indent options IPFIREWALL options DUMMYNET options HZ=1000 # strongly recommended .Ed .Pp Additionally, one may want to increase the number of mbuf clusters (used to store network packets) according to the sum of the bandwidth-delay products and queue sizes of all configured pipes. .Sh SEE ALSO .Xr setsockopt 2 , .Xr if_bridge 4 , .Xr ip 4 , -.Xr ipfw 8 , -.Xr dnctl 8 , .Xr pf.conf 5 , +.Xr dnctl 8 , +.Xr ipfw 8 , .Xr sysctl 8 .Sh HISTORY The .Nm facility was initially implemented as a testing tool for .Tn TCP congestion control by .An Luigi Rizzo Aq Mt luigi@iet.unipi.it , as described on ACM Computer Communication Review, Jan.97 issue. Later it has been modified to work at the .Tn IP and bridging levels, integrated with the .Xr ipfw 4 packet filter, and extended to support multiple queueing and scheduling policies. diff --git a/share/man/man4/ftgpio.4 b/share/man/man4/ftgpio.4 index e31457673fa5..7a5562841732 100644 --- a/share/man/man4/ftgpio.4 +++ b/share/man/man4/ftgpio.4 @@ -1,54 +1,54 @@ .\" Copyright (c) 2022, Stormshield .\" 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. .\" .Dd December 28, 2022 .Dt FTGPIO 4 .Os .Sh NAME .Nm ftgpio .Nd GPIO Controller on Fintek Super I/O", .Sh SYNOPSIS .Cd "device ftgpio" .Cd "device gpio" .Cd "device gpioled" .Sh DESCRIPTION The .Nm is a driver for the GPIO controller found on Fintek Super I/O chips. .Sh SEE ALSO .Xr gpio 3 , .Xr gpio 4 , .Xr gpioled 4 , -.Xr gpioctl 8 .Xr superio 4 , +.Xr gpioctl 8 .Sh HISTORY The .Nm manual page first appeared in .Fx 14.0 . .Sh AUTHORS The .Nm driver was partially written by .An StĂ©phane Rochoy Aq Mt stĂ©phane.rochoy@stormshield.eu . diff --git a/share/man/man4/ipfirewall.4 b/share/man/man4/ipfirewall.4 index bfc571bcb595..691ed3d331c0 100644 --- a/share/man/man4/ipfirewall.4 +++ b/share/man/man4/ipfirewall.4 @@ -1,160 +1,160 @@ .\" .Dd August 19, 2020 .Dt IPFW 4 .Os .Sh NAME .Nm ipfw .Nd IP packet filter and traffic accounting .Sh SYNOPSIS To compile the driver into the kernel, place the following option in the kernel configuration file: .Bd -ragged -offset indent .Cd "options IPFIREWALL" .Ed .Pp Other related kernel options which may also be useful are: .Bd -ragged -offset indent .Cd "options IPFIREWALL_DEFAULT_TO_ACCEPT" .Cd "options IPDIVERT" .Cd "options IPFIREWALL_NAT" .Cd "options IPFIREWALL_NAT64" .Cd "options IPFIREWALL_NPTV6" .Cd "options IPFIREWALL_PMOD" .Cd "options IPFIREWALL_VERBOSE" .Cd "options IPFIREWALL_VERBOSE_LIMIT=100" .Cd "options LIBALIAS" .Ed .Pp 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 ipfw_load="YES" .Ed .Sh DESCRIPTION The .Nm system facility allows filtering, redirecting, and other operations on .Tn IP packets travelling through network interfaces. .Pp The default behavior of .Nm is to block all incoming and outgoing traffic. This behavior can be modified, to allow all traffic through the .Nm firewall by default, by enabling the .Dv IPFIREWALL_DEFAULT_TO_ACCEPT kernel option. This option may be useful when configuring .Nm for the first time. If the default .Nm behavior is to allow everything, it is easier to cope with firewall-tuning mistakes which may accidentally block all traffic. .Pp When using .Xr natd 8 in conjunction with .Nm as .Tn NAT facility, the kernel option .Dv IPDIVERT enables diverting packets to .Xr natd 8 for translation. .Pp When using the in-kernel .Tn NAT facility of .Nm , the kernel option .Dv IPFIREWALL_NAT enables basic .Xr libalias 3 functionality in the kernel. .Pp When using any of the .Tn IPv4 to .Tn IPv6 transition mechanisms in .Nm , the kernel option .Dv IPFIREWALL_NAT64 enables all of these .Tn NAT64 methods in the kernel. .Pp When using the .Tn IPv6 network prefix translation facility of .Nm , the kernel option .Dv IPFIREWALL_NPTV6 enables this functionality in the kernel. .Pp When using the packet modification facility of .Nm , the kernel option .Dv IPFIREWALL_PMOD enables this functionality in the kernel. .Pp To enable logging of packets passing through .Nm , enable the .Dv IPFIREWALL_VERBOSE kernel option. The .Dv IPFIREWALL_VERBOSE_LIMIT option will prevent .Xr syslogd 8 from flooding system logs or causing local Denial of Service. This option may be set to the number of packets which will be logged on a per-entry basis before the entry is rate-limited. .Pp When using the in-kernel .Tn NAT facility of .Nm , the kernel option .Dv LIBALIAS enables full .Xr libalias 3 functionality in the kernel. Full functionality refers to included support for ftp, bbt, skinny, irc, pptp and smedia packets, which are missing in the basic .Xr libalias 3 functionality accomplished with the .Dv IPFIREWALL_NAT kernel option. .Pp The user interface for .Nm is implemented by the .Xr ipfw 8 utility, so please refer to the .Xr ipfw 8 man page for a complete description of the .Nm capabilities and how to use it. .Sh SEE ALSO .Xr setsockopt 2 , +.Xr libalias 3 , .Xr divert 4 , .Xr ip 4 , .Xr ip6 4 , .Xr ipfw 8 , -.Xr libalias 3 , .Xr natd 8 , .Xr sysctl 8 , .Xr syslogd 8 , .Xr pfil 9 diff --git a/share/man/man4/ipsec.4 b/share/man/man4/ipsec.4 index 952d7b925388..96a10dfb7700 100644 --- a/share/man/man4/ipsec.4 +++ b/share/man/man4/ipsec.4 @@ -1,444 +1,444 @@ .\" $KAME: ipsec.4,v 1.17 2001/06/27 15:25:10 itojun Exp $ .\" .\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project. .\" 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 project 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 PROJECT AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd February 6, 2017 .Dt IPSEC 4 .Os .Sh NAME .Nm ipsec .Nd Internet Protocol Security protocol .Sh SYNOPSIS .Cd "options IPSEC" .Cd "options IPSEC_SUPPORT" .Cd "device crypto" .Pp .In sys/types.h .In netinet/in.h .In netipsec/ipsec.h .In netipsec/ipsec6.h .Sh DESCRIPTION .Nm is a security protocol implemented within the Internet Protocol layer of the networking stack. .Nm is defined for both IPv4 and IPv6 .Xr ( inet 4 and .Xr inet6 4 ) . .Nm is a set of protocols, .Tn ESP (for Encapsulating Security Payload) .Tn AH (for Authentication Header), and .Tn IPComp (for IP Payload Compression Protocol) that provide security services for IP datagrams. AH both authenticates and guarantees the integrity of an IP packet by attaching a cryptographic checksum computed using one-way hash functions. ESP, in addition, prevents unauthorized parties from reading the payload of an IP packet by also encrypting it. IPComp tries to increase communication performance by compressing IP payload, thus reducing the amount of data sent. This will help nodes on slow links but with enough computing power. .Nm operates in one of two modes: transport mode or tunnel mode. Transport mode is used to protect peer-to-peer communication between end nodes. Tunnel mode encapsulates IP packets within other IP packets and is designed for security gateways such as VPN endpoints. .Pp System configuration requires the .Xr crypto 4 subsystem. .Pp The packets can be passed to a virtual .Xr enc 4 interface, to perform packet filtering before outbound encryption and after decapsulation inbound. .Pp To properly filter on the inner packets of an .Nm tunnel with firewalls, you can change the values of the following sysctls .Bl -column net.inet6.ipsec6.filtertunnel default enable .It Sy "Name Default Enable" .It "net.inet.ipsec.filtertunnel 0 1" .It "net.inet6.ipsec6.filtertunnel 0 1" .El .\" .Ss Kernel interface .Nm is controlled by a key management and policy engine, that reside in the operating system kernel. Key management is the process of associating keys with security associations, also know as SAs. Policy management dictates when new security associations created or destroyed. .Pp The key management engine can be accessed from userland by using .Dv PF_KEY sockets. The .Dv PF_KEY socket API is defined in RFC2367. .Pp The policy engine is controlled by an extension to the .Dv PF_KEY API, .Xr setsockopt 2 operations, and .Xr sysctl 3 interface. The kernel implements an extended version of the .Dv PF_KEY interface and allows the programmer to define IPsec policies which are similar to the per-packet filters. The .Xr setsockopt 2 interface is used to define per-socket behavior, and .Xr sysctl 3 interface is used to define host-wide default behavior. .Pp The kernel code does not implement a dynamic encryption key exchange protocol such as IKE (Internet Key Exchange). Key exchange protocols are beyond what is necessary in the kernel and should be implemented as daemon processes which call the .Nm APIs. .\" .Ss Policy management IPsec policies can be managed in one of two ways, either by configuring per-socket policies using the .Xr setsockopt 2 system calls, or by configuring kernel level packet filter-based policies using the .Dv PF_KEY interface, via the .Xr setkey 8 you can define IPsec policies against packets using rules similar to packet filtering rules. Refer to .Xr setkey 8 on how to use it. .Pp Depending on the socket's address family, IPPROTO_IP or IPPROTO_IPV6 transport level and IP_IPSEC_POLICY or IPV6_IPSEC_POLICY socket options may be used to configure per-socket security policies. A properly-formed IPsec policy specification structure can be created using .Xr ipsec_set_policy 3 function and used as socket option value for the .Xr setsockopt 2 call. .Pp When setting policies using the .Xr setkey 8 command, the .Dq Li default option instructs the system to use its default policy, as explained below, for processing packets. The following sysctl variables are available for configuring the system's IPsec behavior. The variables can have one of two values. A .Li 1 means .Dq Li use , which means that if there is a security association then use it but if there is not then the packets are not processed by IPsec. The value .Li 2 is synonymous with .Dq Li require , which requires that a security association must exist for the packets to move, and not be dropped. These terms are defined in .Xr ipsec_set_policy 3 . .Bl -column net.inet6.ipsec6.esp_trans_deflev integerxxx .It Sy "Name Type Changeable" .It "net.inet.ipsec.esp_trans_deflev integer yes" .It "net.inet.ipsec.esp_net_deflev integer yes" .It "net.inet.ipsec.ah_trans_deflev integer yes" .It "net.inet.ipsec.ah_net_deflev integer yes" .It "net.inet6.ipsec6.esp_trans_deflev integer yes" .It "net.inet6.ipsec6.esp_net_deflev integer yes" .It "net.inet6.ipsec6.ah_trans_deflev integer yes" .It "net.inet6.ipsec6.ah_net_deflev integer yes" .El .Pp If the kernel does not find a matching, system wide, policy then the default value is applied. The system wide default policy is specified by the following .Xr sysctl 8 variables. .Li 0 means .Dq Li discard which asks the kernel to drop the packet. .Li 1 means .Dq Li none . .Bl -column net.inet6.ipsec6.def_policy integerxxx .It Sy "Name Type Changeable" .It "net.inet.ipsec.def_policy integer yes" .It "net.inet6.ipsec6.def_policy integer yes" .El .\" .Ss Miscellaneous sysctl variables When the .Nm protocols are configured for use, all protocols are included in the system. To selectively enable/disable protocols, use .Xr sysctl 8 . .Bl -column net.inet.ipcomp.ipcomp_enable .It Sy "Name Default" .It "net.inet.esp.esp_enable On" .It "net.inet.ah.ah_enable On" .It "net.inet.ipcomp.ipcomp_enable On" .El .Pp In addition the following variables are accessible via .Xr sysctl 8 , for tweaking the kernel's IPsec behavior: .Bl -column net.inet6.ipsec6.inbonud_call_ike integerxxx .It Sy "Name Type Changeable" .It "net.inet.ipsec.ah_cleartos integer yes" .It "net.inet.ipsec.ah_offsetmask integer yes" .It "net.inet.ipsec.dfbit integer yes" .It "net.inet.ipsec.ecn integer yes" .It "net.inet.ipsec.debug integer yes" .It "net.inet.ipsec.natt_cksum_policy integer yes" .It "net.inet.ipsec.check_policy_history integer yes" .It "net.inet6.ipsec6.ecn integer yes" .It "net.inet6.ipsec6.debug integer yes" .El .Pp The variables are interpreted as follows: .Bl -tag -width 6n .It Li ipsec.ah_cleartos If set to non-zero, the kernel clears the type-of-service field in the IPv4 header during AH authentication data computation. This variable is used to get current systems to inter-operate with devices that implement RFC1826 AH. It should be set to non-zero (clear the type-of-service field) for RFC2402 conformance. .It Li ipsec.ah_offsetmask During AH authentication data computation, the kernel will include a 16bit fragment offset field (including flag bits) in the IPv4 header, after computing logical AND with the variable. The variable is used for inter-operating with devices that implement RFC1826 AH. It should be set to zero (clear the fragment offset field during computation) for RFC2402 conformance. .It Li ipsec.dfbit This variable configures the kernel behavior on IPv4 IPsec tunnel encapsulation. If set to 0, the DF bit on the outer IPv4 header will be cleared while 1 means that the outer DF bit is set regardless from the inner DF bit and 2 indicates that the DF bit is copied from the inner header to the outer one. The variable is supplied to conform to RFC2401 chapter 6.1. .It Li ipsec.ecn If set to non-zero, IPv4 IPsec tunnel encapsulation/decapsulation behavior will be friendly to ECN (explicit congestion notification), as documented in .Li draft-ietf-ipsec-ecn-02.txt . .Xr gif 4 talks more about the behavior. .It Li ipsec.debug If set to non-zero, debug messages will be generated via .Xr syslog 3 . .It Li ipsec.natt_cksum_policy Controls how the kernel handles TCP and UDP checksums when ESP in UDP encapsulation is used for IPsec transport mode. If set to a non-zero value, the kernel fully recomputes checksums for inbound TCP segments and UDP datagrams after they are decapsulated and decrypted. If set to 0 and original addresses were configured for corresponding SA by the IKE daemon, the kernel incrementally recomputes checksums for inbound TCP segments and UDP datagrams. If addresses were not configured, the checksums are ignored. .It Li ipsec.check_policy_history Enables strict policy checking for inbound packets. By default, inbound security policies check that packets handled by IPsec have been decrypted and authenticated. If this variable is set to a non-zero value, each packet handled by IPsec is checked against the history of IPsec security associations. The IPsec security protocol, mode, and SA addresses must match. .El .Pp Variables under the .Li net.inet6.ipsec6 tree have similar meanings to those described above. .\" .Sh PROTOCOLS The .Nm protocol acts as a plug-in to the .Xr inet 4 and .Xr inet6 4 protocols and therefore supports most of the protocols defined upon those IP-layer protocols. The .Xr icmp 4 and .Xr icmp6 4 protocols may behave differently with .Nm because .Nm can prevent .Xr icmp 4 or .Xr icmp6 4 routines from looking into the IP payload. .\" .Sh SEE ALSO .Xr ioctl 2 , .Xr socket 2 , .Xr ipsec_set_policy 3 , .Xr crypto 4 , .Xr enc 4 , -.Xr if_ipsec 4 , .Xr icmp6 4 , +.Xr if_ipsec 4 , .Xr intro 4 , .Xr ip6 4 , .Xr setkey 8 , .Xr sysctl 8 .\".Xr racoon 8 .Rs .%A "S. Kent" .%A "R. Atkinson" .%T "IP Authentication Header" .%O "RFC 2404" .Re .Rs .%A "S. Kent" .%A "R. Atkinson" .%T "IP Encapsulating Security Payload (ESP)" .%O "RFC 2406" .Re .Sh STANDARDS .Rs .%A Daniel L. McDonald .%A Craig Metz .%A Bao G. Phan .%T "PF_KEY Key Management API, Version 2" .%R RFC .%N 2367 .Re .Pp .Rs .%A "D. L. McDonald" .%T "A Simple IP Security API Extension to BSD Sockets" .%R internet draft .%N "draft-mcdonald-simple-ipsec-api-03.txt" .%O work in progress material .Re .Sh HISTORY The original .Nm implementation appeared in the WIDE/KAME IPv6/IPsec stack. .Pp For .Fx 5.0 a fully locked IPsec implementation called fast_ipsec was brought in. The protocols drew heavily on the .Ox implementation of the .Tn IPsec protocols. The policy management code was derived from the .Tn KAME implementation found in their .Tn IPsec protocols. The fast_ipsec implementation lacked .Xr ip6 4 support but made use of the .Xr crypto 4 subsystem. .Pp For .Fx 7.0 .Xr ip6 4 support was added to fast_ipsec. After this the old KAME IPsec implementation was dropped and fast_ipsec became what now is the only .Nm implementation in .Fx . .Sh BUGS There is no single standard for the policy engine API, so the policy engine API described herein is just for this implementation. .Pp AH and tunnel mode encapsulation may not work as you might expect. If you configure inbound .Dq require policy with an AH tunnel or any IPsec encapsulating policy with AH (like .Dq Li esp/tunnel/A-B/use ah/transport/A-B/require ) , tunnelled packets will be rejected. This is because the policy check is enforced on the inner packet on reception, and AH authenticates encapsulating (outer) packet, not the encapsulated (inner) packet (so for the receiving kernel there is no sign of authenticity). The issue will be solved when we revamp our policy engine to keep all the packet decapsulation history. .Pp When a large database of security associations or policies is present in the kernel the .Dv SADB_DUMP and .Dv SADB_SPDDUMP operations on .Dv PF_KEY sockets may fail due to lack of space. Increasing the socket buffer size may alleviate this problem. .Pp The .Tn IPcomp protocol may occasionally error because of .Xr zlib 3 problems. .Pp This documentation needs more review. diff --git a/share/man/man4/mac_do.4 b/share/man/man4/mac_do.4 index ce9f8cf25a4a..aa84a71b4953 100644 --- a/share/man/man4/mac_do.4 +++ b/share/man/man4/mac_do.4 @@ -1,78 +1,78 @@ .\"- .\" Copyright (c) 2024 Baptiste Daroussin .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" .Dd May 22, 2024 .Dt MAC_DO 4 .Os .Sh NAME .Nm mac_do .Nd "policy allowing user to execute program as another user" .Sh SYNOPSIS To compile the .Nm policy into your kernel, place the following lines in your kernel configruation file: .Bd -ragged -offset indent .Cd "options MAC" .Cd "options MAC_DO" .Ed .Sh DESCRIPTION The .Nm policy grants users the ability to run processs as other users according to predefined rules. .Pp The exact set of kernel privileges granted are: .Bl -inset -compact -offset indent .It Dv PRIV_CRED_SETGROUPS .It Dv PRIV_CRED_SETUID .El .Pp The following .Xr sysctl 8 MIBs are available: .Bl -tag -width indent .It Va security.mac.do.enabled Enable the .Nm policy. (Default: 1). .It Va security.mac.do.rules The set of rules. .El .Pp The rules consist of a list of elements separated by .So , Sc . Each element is of the form .Sm off .Do .Op Cm uid | Cm gid .Li = .Ar fid .Li : .Ar tid .Dc .Sm on . Where .Ar fid is the uid or gid of the user or group the rule applies to, and .Ar tid is the uid of the targetted user. Two special forms are accepted for .Ar tid : .Va any or .Va * , which allow to target any user. .Sh EXAMPLES The following rule: .Pp .Dl security.mac.do.rules=uid=1001:80,gid=0:any .Pp means the user with the uid 1001 can execute processes as user with uid 80, all the users which belongs to the group gid 0 can execute processes as any user. .Sh SEE ALSO -.Xr mac 4 , -.Xr mdo 1 +.Xr mdo 1 , +.Xr mac 4 diff --git a/share/man/man4/man4.aarch64/rk_gpio.4 b/share/man/man4/man4.aarch64/rk_gpio.4 index 69bcb1671f85..b5648662cf5e 100644 --- a/share/man/man4/man4.aarch64/rk_gpio.4 +++ b/share/man/man4/man4.aarch64/rk_gpio.4 @@ -1,60 +1,60 @@ .\"- .\" Copyright (c) 2018 Emmanuel Vadot .\" .\" 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. .\" .Dd Apr 26, 2018 .Dt RK_GPIO 4 .Os .Sh NAME .Nm rk_gpio .Nd driver for the gpio controller on RockChip SoCs .Sh SYNOPSIS .Cd "options SOC_ROCKCHIP_RK3328" .Sh DESCRIPTION The .Nm device driver provides support for the gpio controller device present on RockChip SoC. .Sh HARDWARE The current version of the .Nm driver supports the gpio banks with one of the following compatible strings : .Pp .Bl -bullet -compact .It rockchip,gpio-bank .El .Sh SEE ALSO .Xr gpiobus 4 , -.Xr gpioctl 8 , +.Xr gpioctl 8 .Sh HISTORY The .Nm device driver first appeared in .Fx 12.0 . .Sh AUTHORS The .Nm device driver and manpage was written by .An Emmanuel Vadot Aq Mt manu@freebsd.org . diff --git a/share/man/man4/man4.aarch64/rk_i2c.4 b/share/man/man4/man4.aarch64/rk_i2c.4 index f30b510e7655..be1a0fab943e 100644 --- a/share/man/man4/man4.aarch64/rk_i2c.4 +++ b/share/man/man4/man4.aarch64/rk_i2c.4 @@ -1,62 +1,62 @@ .\"- .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" Copyright (c) 2018 Emmanuel Vadot .\" .\" 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. .\" .Dd June 14, 2018 .Dt RK_I2C 4 .Os .Sh NAME .Nm rk_i2c .Nd driver for the i2c controller on RockChip SoCs .Sh SYNOPSIS .Cd "options SOC_ROCKCHIP_RK3328" .Sh DESCRIPTION The .Nm device driver provides support for the i2c controller device present on RockChip SoC. .Sh HARDWARE The current version of the .Nm driver supports the i2c controller with one of the following compatible strings : .Pp .Bl -bullet -compact .It rockchip,rk3328-i2c .El .Sh SEE ALSO .Xr iic 4 , -.Xr iicbus 4 , +.Xr iicbus 4 .Sh HISTORY The .Nm device driver first appeared in .Fx 12.0 . .Sh AUTHORS The .Nm device driver and manpage was written by .An Emmanuel Vadot Aq Mt manu@freebsd.org . diff --git a/share/man/man4/man4.aarch64/rk_pinctrl.4 b/share/man/man4/man4.aarch64/rk_pinctrl.4 index c196c00d52b7..519b3e793cd1 100644 --- a/share/man/man4/man4.aarch64/rk_pinctrl.4 +++ b/share/man/man4/man4.aarch64/rk_pinctrl.4 @@ -1,59 +1,59 @@ .\"- .\" Copyright (c) 2018 Emmanuel Vadot .\" .\" 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. .\" .Dd Apr 26, 2018 .Dt RK_PINCTRL 4 .Os .Sh NAME .Nm rk_pinctrl .Nd driver for the pin multiplexing on RockChip SoCs .Sh SYNOPSIS .Cd "options SOC_ROCKCHIP_RK3328" .Sh DESCRIPTION The .Nm device driver provides support for the pin multiplexing device present on RockChip SoC. .Sh HARDWARE The current version of the .Nm driver supports the pin controller with one of the following compatible strings : .Pp .Bl -bullet -compact .It rockchip,rk3328-pinctrl .El .Sh SEE ALSO -.Xr fdt_pinctrl 4 , +.Xr fdt_pinctrl 4 .Sh HISTORY The .Nm device driver first appeared in .Fx 12.0 . .Sh AUTHORS The .Nm device driver and manpage was written by .An Emmanuel Vadot Aq Mt manu@freebsd.org . diff --git a/share/man/man4/man4.arm/imx6_ahci.4 b/share/man/man4/man4.arm/imx6_ahci.4 index cfe8a87deb6f..9979cef50d79 100644 --- a/share/man/man4/man4.arm/imx6_ahci.4 +++ b/share/man/man4/man4.arm/imx6_ahci.4 @@ -1,63 +1,63 @@ .\" .\" Copyright (c) 2018 Ian Lepore .\" 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. .\" .Dd July 7, 2018 .Dt IMX6_AHCI 4 .Os .Sh NAME .Nm imx6_ahci .Nd device driver for the NXP i.MX6 on-chip SATA controller .Sh SYNOPSIS To compile this driver into the kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "device ahci" .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 imx6_ahci_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for the on-chip SATA controller found on some models of the NXP i.MX6 chip. The driver is a thin glue layer to interpret the platform's FDT data and marshall resources for the standard .Xr ahci 4 driver. .Sh SEE ALSO .Xr ahci 4 , -.Xr fdt 4 , +.Xr fdt 4 .Sh HISTORY The .Nm driver first appeared in .Fx 12.0 . diff --git a/share/man/man4/mpi3mr.4 b/share/man/man4/mpi3mr.4 index 981979e37187..f07ce13d2f23 100644 --- a/share/man/man4/mpi3mr.4 +++ b/share/man/man4/mpi3mr.4 @@ -1,81 +1,81 @@ .\" .\" Copyright (c) 2023 Netflix, Inc .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" mpi3mr driver man page. .\" .Dd June 14, 2023 .Dt MPI3MR 4 .Os .Sh NAME .Nm mpi3mr .Nd "Broadcom MPIMR 3.0 IT/IR 24Gb/s SAS Tri-Mode RAID PCIe 4.0 driver" .Sh SYNOPSIS .\" To compile this driver into the kernel, place these lines in the kernel .\" configuration file: .\" .Bd -ragged -offset indent .\" .Cd "device pci" .\" .Cd "device scbus" .\" .Cd "device mpi3mr" .\" .Ed .\" .Pp The driver can be loaded as a module at boot time by placing this line in .Xr loader.conf 5 : .Bd -literal -offset indent mpi3mr_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for Broadcom Ltd. MPIMR 3.0 IT/IR PCIe 4 controller. .Sh HARDWARE These controllers are supported by the .Nm driver: .Pp .Bl -bullet -compact .It Broadcom Ltd. SAS 4116 Tri-Mode RAID Adapter .It Broadcom Ltd. 9670W-16i 24G PCIe 4.0 Tri-Mode RAID Adapters .It Broadcom Ltd. 9670-24i 24G PCIe 4.0 Tri-Mode RAID Adapters .It Broadcom Ltd. 9660-16i 24G PCIe 4.0 Tri-Mode RAID Adapters .It Broadcom Ltd. 9620-16i 24G PCIe 4.0 Tri-Mode RAID Adapters .It Broadcom Ltd. 9600-24i 24G PCIe 4.0 Tri-Mode RAID Adapters .It Broadcom Ltd. 9600-16i 24G PCIe 4.0 Tri-Mode RAID Adapters .It Broadcom Ltd. 9600W-16e 24G PCIe 4.0 Tri-Mode RAID Adapters .It Broadcom Ltd. 9600-16e 24G PCIe 4.0 Tri-Mode RAID Adapters .It Broadcom Ltd. 9600-8i8e 24G PCIe 4.0 Tri-Mode RAID Adapters .El .Sh SEE ALSO .Xr cam 4 , .Xr cd 4 , .Xr ch 4 , .Xr da 4 , .Xr mpr 4 , .Xr pci 4 , .Xr sa 4 , -.Xr scsi 4 . +.Xr scsi 4 .Sh HISTORY The .Nm driver first appeared in .Fx 14.0 . .Sh AUTHORS The .Nm driver was written by .An Sumit Saxena Aq Mt sumit.saxena@broadcom.com , and .An Chandrakanth Patil Aq Mt chandrakanth.patil@broadcom.com . This manual page was written by .An Warner Losh Aq Mt imp@FreeBSD.org . diff --git a/share/man/man4/netmap.4 b/share/man/man4/netmap.4 index 5a12f8f32465..6be0c8662d59 100644 --- a/share/man/man4/netmap.4 +++ b/share/man/man4/netmap.4 @@ -1,1200 +1,1200 @@ .\" Copyright (c) 2011-2014 Matteo Landi, Luigi Rizzo, Universita` di Pisa .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" This document is derived in part from the enet man page (enet.4) .\" distributed with 4.3BSD Unix. .\" .Dd October 10, 2024 .Dt NETMAP 4 .Os .Sh NAME .Nm netmap .Nd a framework for fast packet I/O .Sh SYNOPSIS .Cd device netmap .Sh DESCRIPTION .Nm is a framework for extremely fast and efficient packet I/O for userspace and kernel clients, and for Virtual Machines. It runs on .Fx , Linux and some versions of Windows, and supports a variety of .Nm netmap ports , including .Bl -tag -width XXXX .It Nm physical NIC ports to access individual queues of network interfaces; .It Nm host ports to inject packets into the host stack; .It Nm VALE ports implementing a very fast and modular in-kernel software switch/dataplane; .It Nm netmap pipes a shared memory packet transport channel; .It Nm netmap monitors a mechanism similar to .Xr bpf 4 to capture traffic .El .Pp All these .Nm netmap ports are accessed interchangeably with the same API, and are at least one order of magnitude faster than standard OS mechanisms (sockets, bpf, tun/tap interfaces, native switches, pipes). With suitably fast hardware (NICs, PCIe buses, CPUs), packet I/O using .Nm on supported NICs reaches 14.88 million packets per second (Mpps) with much less than one core on 10 Gbit/s NICs; 35-40 Mpps on 40 Gbit/s NICs (limited by the hardware); about 20 Mpps per core for VALE ports; and over 100 Mpps for .Nm netmap pipes . NICs without native .Nm support can still use the API in emulated mode, which uses unmodified device drivers and is 3-5 times faster than .Xr bpf 4 or raw sockets. .Pp Userspace clients can dynamically switch NICs into .Nm mode and send and receive raw packets through memory mapped buffers. Similarly, .Nm VALE switch instances and ports, .Nm netmap pipes and .Nm netmap monitors can be created dynamically, providing high speed packet I/O between processes, virtual machines, NICs and the host stack. .Pp .Nm supports both non-blocking I/O through .Xr ioctl 2 , synchronization and blocking I/O through a file descriptor and standard OS mechanisms such as .Xr select 2 , .Xr poll 2 , .Xr kqueue 2 and .Xr epoll 7 . All types of .Nm netmap ports and the .Nm VALE switch are implemented by a single kernel module, which also emulates the .Nm API over standard drivers. For best performance, .Nm requires native support in device drivers. A list of such devices is at the end of this document. .Pp In the rest of this (long) manual page we document various aspects of the .Nm and .Nm VALE architecture, features and usage. .Sh ARCHITECTURE .Nm supports raw packet I/O through a .Em port , which can be connected to a physical interface .Em ( NIC ) , to the host stack, or to a .Nm VALE switch. Ports use preallocated circular queues of buffers .Em ( rings ) residing in an mmapped region. There is one ring for each transmit/receive queue of a NIC or virtual port. An additional ring pair connects to the host stack. .Pp After binding a file descriptor to a port, a .Nm client can send or receive packets in batches through the rings, and possibly implement zero-copy forwarding between ports. .Pp All NICs operating in .Nm mode use the same memory region, accessible to all processes who own .Pa /dev/netmap file descriptors bound to NICs. Independent .Nm VALE and .Nm netmap pipe ports by default use separate memory regions, but can be independently configured to share memory. .Sh ENTERING AND EXITING NETMAP MODE The following section describes the system calls to create and control .Nm netmap ports (including .Nm VALE and .Nm netmap pipe ports). Simpler, higher level functions are described in the .Sx LIBRARIES section. .Pp Ports and rings are created and controlled through a file descriptor, created by opening a special device .Dl fd = open("/dev/netmap"); and then bound to a specific port with an .Dl ioctl(fd, NIOCREGIF, (struct nmreq *)arg); .Pp .Nm has multiple modes of operation controlled by the .Vt struct nmreq argument. .Va arg.nr_name specifies the netmap port name, as follows: .Bl -tag -width XXXX .It Dv OS network interface name (e.g., 'em0', 'eth1', ... ) the data path of the NIC is disconnected from the host stack, and the file descriptor is bound to the NIC (one or all queues), or to the host stack; .It Dv valeSSS:PPP the file descriptor is bound to port PPP of VALE switch SSS. Switch instances and ports are dynamically created if necessary. .Pp Both SSS and PPP have the form [0-9a-zA-Z_]+ , the string cannot exceed IFNAMSIZ characters, and PPP cannot be the name of any existing OS network interface. .El .Pp On return, .Va arg indicates the size of the shared memory region, and the number, size and location of all the .Nm data structures, which can be accessed by mmapping the memory .Dl char *mem = mmap(0, arg.nr_memsize, fd); .Pp Non-blocking I/O is done with special .Xr ioctl 2 .Xr select 2 and .Xr poll 2 on the file descriptor permit blocking I/O. .Pp While a NIC is in .Nm mode, the OS will still believe the interface is up and running. OS-generated packets for that NIC end up into a .Nm ring, and another ring is used to send packets into the OS network stack. A .Xr close 2 on the file descriptor removes the binding, and returns the NIC to normal mode (reconnecting the data path to the host stack), or destroys the virtual port. .Sh DATA STRUCTURES The data structures in the mmapped memory region are detailed in .In sys/net/netmap.h , which is the ultimate reference for the .Nm API. The main structures and fields are indicated below: .Bl -tag -width XXX .It Dv struct netmap_if (one per interface ) .Bd -literal struct netmap_if { ... const uint32_t ni_flags; /* properties */ ... const uint32_t ni_tx_rings; /* NIC tx rings */ const uint32_t ni_rx_rings; /* NIC rx rings */ uint32_t ni_bufs_head; /* head of extra bufs list */ ... }; .Ed .Pp Indicates the number of available rings .Pa ( struct netmap_rings ) and their position in the mmapped region. The number of tx and rx rings .Pa ( ni_tx_rings , ni_rx_rings ) normally depends on the hardware. NICs also have an extra tx/rx ring pair connected to the host stack. .Em NIOCREGIF can also request additional unbound buffers in the same memory space, to be used as temporary storage for packets. The number of extra buffers is specified in the .Va arg.nr_arg3 field. On success, the kernel writes back to .Va arg.nr_arg3 the number of extra buffers actually allocated (they may be less than the amount requested if the memory space ran out of buffers). .Pa ni_bufs_head contains the index of the first of these extra buffers, which are connected in a list (the first uint32_t of each buffer being the index of the next buffer in the list). A .Dv 0 indicates the end of the list. The application is free to modify this list and use the buffers (i.e., binding them to the slots of a netmap ring). When closing the netmap file descriptor, the kernel frees the buffers contained in the list pointed by .Pa ni_bufs_head , irrespectively of the buffers originally provided by the kernel on .Em NIOCREGIF . .It Dv struct netmap_ring (one per ring ) .Bd -literal struct netmap_ring { ... const uint32_t num_slots; /* slots in each ring */ const uint32_t nr_buf_size; /* size of each buffer */ ... uint32_t head; /* (u) first buf owned by user */ uint32_t cur; /* (u) wakeup position */ const uint32_t tail; /* (k) first buf owned by kernel */ ... uint32_t flags; struct timeval ts; /* (k) time of last rxsync() */ ... struct netmap_slot slot[0]; /* array of slots */ } .Ed .Pp Implements transmit and receive rings, with read/write pointers, metadata and an array of .Em slots describing the buffers. .It Dv struct netmap_slot (one per buffer ) .Bd -literal struct netmap_slot { uint32_t buf_idx; /* buffer index */ uint16_t len; /* packet length */ uint16_t flags; /* buf changed, etc. */ uint64_t ptr; /* address for indirect buffers */ }; .Ed .Pp Describes a packet buffer, which normally is identified by an index and resides in the mmapped region. .It Dv packet buffers Fixed size (normally 2 KB) packet buffers allocated by the kernel. .El .Pp The offset of the .Pa struct netmap_if in the mmapped region is indicated by the .Pa nr_offset field in the structure returned by .Dv NIOCREGIF . From there, all other objects are reachable through relative references (offsets or indexes). Macros and functions in .In net/netmap_user.h help converting them into actual pointers: .Pp .Dl struct netmap_if *nifp = NETMAP_IF(mem, arg.nr_offset); .Dl struct netmap_ring *txr = NETMAP_TXRING(nifp, ring_index); .Dl struct netmap_ring *rxr = NETMAP_RXRING(nifp, ring_index); .Pp .Dl char *buf = NETMAP_BUF(ring, buffer_index); .Sh RINGS, BUFFERS AND DATA I/O .Va Rings are circular queues of packets with three indexes/pointers .Va ( head , cur , tail ) ; one slot is always kept empty. The ring size .Va ( num_slots ) should not be assumed to be a power of two. .Pp .Va head is the first slot available to userspace; .Pp .Va cur is the wakeup point: select/poll will unblock when .Va tail passes .Va cur ; .Pp .Va tail is the first slot reserved to the kernel. .Pp Slot indexes .Em must only move forward; for convenience, the function .Dl nm_ring_next(ring, index) returns the next index modulo the ring size. .Pp .Va head and .Va cur are only modified by the user program; .Va tail is only modified by the kernel. The kernel only reads/writes the .Vt struct netmap_ring slots and buffers during the execution of a netmap-related system call. The only exception are slots (and buffers) in the range .Va tail\ . . . head-1 , that are explicitly assigned to the kernel. .Ss TRANSMIT RINGS On transmit rings, after a .Nm system call, slots in the range .Va head\ . . . tail-1 are available for transmission. User code should fill the slots sequentially and advance .Va head and .Va cur past slots ready to transmit. .Va cur may be moved further ahead if the user code needs more slots before further transmissions (see .Sx SCATTER GATHER I/O ) . .Pp At the next NIOCTXSYNC/select()/poll(), slots up to .Va head-1 are pushed to the port, and .Va tail may advance if further slots have become available. Below is an example of the evolution of a TX ring: .Bd -literal after the syscall, slots between cur and tail are (a)vailable head=cur tail | | v v TX [.....aaaaaaaaaaa.............] user creates new packets to (T)ransmit head=cur tail | | v v TX [.....TTTTTaaaaaa.............] NIOCTXSYNC/poll()/select() sends packets and reports new slots head=cur tail | | v v TX [..........aaaaaaaaaaa........] .Ed .Pp .Fn select and .Fn poll will block if there is no space in the ring, i.e., .Dl ring->cur == ring->tail and return when new slots have become available. .Pp High speed applications may want to amortize the cost of system calls by preparing as many packets as possible before issuing them. .Pp A transmit ring with pending transmissions has .Dl ring->head != ring->tail + 1 (modulo the ring size). The function .Va int nm_tx_pending(ring) implements this test. .Ss RECEIVE RINGS On receive rings, after a .Nm system call, the slots in the range .Va head\& . . . tail-1 contain received packets. User code should process them and advance .Va head and .Va cur past slots it wants to return to the kernel. .Va cur may be moved further ahead if the user code wants to wait for more packets without returning all the previous slots to the kernel. .Pp At the next NIOCRXSYNC/select()/poll(), slots up to .Va head-1 are returned to the kernel for further receives, and .Va tail may advance to report new incoming packets. .Pp Below is an example of the evolution of an RX ring: .Bd -literal after the syscall, there are some (h)eld and some (R)eceived slots head cur tail | | | v v v RX [..hhhhhhRRRRRRRR..........] user advances head and cur, releasing some slots and holding others head cur tail | | | v v v RX [..*****hhhRRRRRR...........] NICRXSYNC/poll()/select() recovers slots and reports new packets head cur tail | | | v v v RX [.......hhhRRRRRRRRRRRR....] .Ed .Sh SLOTS AND PACKET BUFFERS Normally, packets should be stored in the netmap-allocated buffers assigned to slots when ports are bound to a file descriptor. One packet is fully contained in a single buffer. .Pp The following flags affect slot and buffer processing: .Bl -tag -width XXX .It NS_BUF_CHANGED .Em must be used when the .Va buf_idx in the slot is changed. This can be used to implement zero-copy forwarding, see .Sx ZERO-COPY FORWARDING . .It NS_REPORT reports when this buffer has been transmitted. Normally, .Nm notifies transmit completions in batches, hence signals can be delayed indefinitely. This flag helps detect when packets have been sent and a file descriptor can be closed. .It NS_FORWARD When a ring is in 'transparent' mode, packets marked with this flag by the user application are forwarded to the other endpoint at the next system call, thus restoring (in a selective way) the connection between a NIC and the host stack. .It NS_NO_LEARN tells the forwarding code that the source MAC address for this packet must not be used in the learning bridge code. .It NS_INDIRECT indicates that the packet's payload is in a user-supplied buffer whose user virtual address is in the 'ptr' field of the slot. The size can reach 65535 bytes. .Pp This is only supported on the transmit ring of .Nm VALE ports, and it helps reducing data copies in the interconnection of virtual machines. .It NS_MOREFRAG indicates that the packet continues with subsequent buffers; the last buffer in a packet must have the flag clear. .El .Sh SCATTER GATHER I/O Packets can span multiple slots if the .Va NS_MOREFRAG flag is set in all but the last slot. The maximum length of a chain is 64 buffers. This is normally used with .Nm VALE ports when connecting virtual machines, as they generate large TSO segments that are not split unless they reach a physical device. .Pp NOTE: The length field always refers to the individual fragment; there is no place with the total length of a packet. .Pp On receive rings the macro .Va NS_RFRAGS(slot) indicates the remaining number of slots for this packet, including the current one. Slots with a value greater than 1 also have NS_MOREFRAG set. .Sh IOCTLS .Nm uses two ioctls (NIOCTXSYNC, NIOCRXSYNC) for non-blocking I/O. They take no argument. Two more ioctls (NIOCGINFO, NIOCREGIF) are used to query and configure ports, with the following argument: .Bd -literal struct nmreq { char nr_name[IFNAMSIZ]; /* (i) port name */ uint32_t nr_version; /* (i) API version */ uint32_t nr_offset; /* (o) nifp offset in mmap region */ uint32_t nr_memsize; /* (o) size of the mmap region */ uint32_t nr_tx_slots; /* (i/o) slots in tx rings */ uint32_t nr_rx_slots; /* (i/o) slots in rx rings */ uint16_t nr_tx_rings; /* (i/o) number of tx rings */ uint16_t nr_rx_rings; /* (i/o) number of rx rings */ uint16_t nr_ringid; /* (i/o) ring(s) we care about */ uint16_t nr_cmd; /* (i) special command */ uint16_t nr_arg1; /* (i/o) extra arguments */ uint16_t nr_arg2; /* (i/o) extra arguments */ uint32_t nr_arg3; /* (i/o) extra arguments */ uint32_t nr_flags /* (i/o) open mode */ ... }; .Ed .Pp A file descriptor obtained through .Pa /dev/netmap also supports the ioctl supported by network devices, see .Xr netintro 4 . .Bl -tag -width XXXX .It Dv NIOCGINFO returns EINVAL if the named port does not support netmap. Otherwise, it returns 0 and (advisory) information about the port. Note that all the information below can change before the interface is actually put in netmap mode. .Bl -tag -width XX .It Pa nr_memsize indicates the size of the .Nm memory region. NICs in .Nm mode all share the same memory region, whereas .Nm VALE ports have independent regions for each port. .It Pa nr_tx_slots , nr_rx_slots indicate the size of transmit and receive rings. .It Pa nr_tx_rings , nr_rx_rings indicate the number of transmit and receive rings. Both ring number and sizes may be configured at runtime using interface-specific functions (e.g., .Xr ethtool 8 ). .El .It Dv NIOCREGIF binds the port named in .Va nr_name to the file descriptor. For a physical device this also switches it into .Nm mode, disconnecting it from the host stack. Multiple file descriptors can be bound to the same port, with proper synchronization left to the user. .Pp The recommended way to bind a file descriptor to a port is to use function .Va nm_open(..) (see .Sx LIBRARIES ) which parses names to access specific port types and enable features. In the following we document the main features. .Pp .Dv NIOCREGIF can also bind a file descriptor to one endpoint of a .Em netmap pipe , consisting of two netmap ports with a crossover connection. A netmap pipe share the same memory space of the parent port, and is meant to enable configuration where a master process acts as a dispatcher towards slave processes. .Pp To enable this function, the .Pa nr_arg1 field of the structure can be used as a hint to the kernel to indicate how many pipes we expect to use, and reserve extra space in the memory region. .Pp On return, it gives the same info as NIOCGINFO, with .Pa nr_ringid and .Pa nr_flags indicating the identity of the rings controlled through the file descriptor. .Pp .Va nr_flags .Va nr_ringid selects which rings are controlled through this file descriptor. Possible values of .Pa nr_flags are indicated below, together with the naming schemes that application libraries (such as the .Nm nm_open indicated below) can use to indicate the specific set of rings. In the example below, "netmap:foo" is any valid netmap port name. .Bl -tag -width XXXXX .It NR_REG_ALL_NIC "netmap:foo" (default) all hardware ring pairs .It NR_REG_SW "netmap:foo^" the ``host rings'', connecting to the host stack. .It NR_REG_NIC_SW "netmap:foo*" all hardware rings and the host rings .It NR_REG_ONE_NIC "netmap:foo-i" only the i-th hardware ring pair, where the number is in .Pa nr_ringid ; .It NR_REG_PIPE_MASTER "netmap:foo{i" the master side of the netmap pipe whose identifier (i) is in .Pa nr_ringid ; .It NR_REG_PIPE_SLAVE "netmap:foo}i" the slave side of the netmap pipe whose identifier (i) is in .Pa nr_ringid . .Pp The identifier of a pipe must be thought as part of the pipe name, and does not need to be sequential. On return the pipe will only have a single ring pair with index 0, irrespective of the value of .Va i . .El .Pp By default, a .Xr poll 2 or .Xr select 2 call pushes out any pending packets on the transmit ring, even if no write events are specified. The feature can be disabled by or-ing .Va NETMAP_NO_TX_POLL to the value written to .Va nr_ringid . When this feature is used, packets are transmitted only on .Va ioctl(NIOCTXSYNC) or .Va select() / .Va poll() are called with a write event (POLLOUT/wfdset) or a full ring. .Pp When registering a virtual interface that is dynamically created to a .Nm VALE switch, we can specify the desired number of rings (1 by default, and currently up to 16) on it using nr_tx_rings and nr_rx_rings fields. .It Dv NIOCTXSYNC tells the hardware of new packets to transmit, and updates the number of slots available for transmission. .It Dv NIOCRXSYNC tells the hardware of consumed packets, and asks for newly available packets. .El .Sh SELECT, POLL, EPOLL, KQUEUE .Xr select 2 and .Xr poll 2 on a .Nm file descriptor process rings as indicated in .Sx TRANSMIT RINGS and .Sx RECEIVE RINGS , respectively when write (POLLOUT) and read (POLLIN) events are requested. Both block if no slots are available in the ring .Va ( ring->cur == ring->tail ) . Depending on the platform, .Xr epoll 7 and .Xr kqueue 2 are supported too. .Pp Packets in transmit rings are normally pushed out (and buffers reclaimed) even without requesting write events. Passing the .Dv NETMAP_NO_TX_POLL flag to .Em NIOCREGIF disables this feature. By default, receive rings are processed only if read events are requested. Passing the .Dv NETMAP_DO_RX_POLL flag to .Em NIOCREGIF updates receive rings even without read events. Note that on .Xr epoll 7 and .Xr kqueue 2 , .Dv NETMAP_NO_TX_POLL and .Dv NETMAP_DO_RX_POLL only have an effect when some event is posted for the file descriptor. .Sh LIBRARIES The .Nm API is supposed to be used directly, both because of its simplicity and for efficient integration with applications. .Pp For convenience, the .In net/netmap_user.h header provides a few macros and functions to ease creating a file descriptor and doing I/O with a .Nm port. These are loosely modeled after the .Xr pcap 3 API, to ease porting of libpcap-based applications to .Nm . To use these extra functions, programs should .Dl #define NETMAP_WITH_LIBS before .Dl #include .Pp The following functions are available: .Bl -tag -width XXXXX .It Va struct nm_desc * nm_open(const char *ifname, const struct nmreq *req, uint64_t flags, const struct nm_desc *arg ) similar to .Xr pcap_open_live 3 , binds a file descriptor to a port. .Bl -tag -width XX .It Va ifname is a port name, in the form "netmap:PPP" for a NIC and "valeSSS:PPP" for a .Nm VALE port. .It Va req provides the initial values for the argument to the NIOCREGIF ioctl. The nm_flags and nm_ringid values are overwritten by parsing ifname and flags, and other fields can be overridden through the other two arguments. .It Va arg points to a struct nm_desc containing arguments (e.g., from a previously open file descriptor) that should override the defaults. The fields are used as described below .It Va flags can be set to a combination of the following flags: .Va NETMAP_NO_TX_POLL , .Va NETMAP_DO_RX_POLL (copied into nr_ringid); .Va NM_OPEN_NO_MMAP (if arg points to the same memory region, avoids the mmap and uses the values from it); .Va NM_OPEN_IFNAME (ignores ifname and uses the values in arg); .Va NM_OPEN_ARG1 , .Va NM_OPEN_ARG2 , .Va NM_OPEN_ARG3 (uses the fields from arg); .Va NM_OPEN_RING_CFG (uses the ring number and sizes from arg). .El .It Va int nm_close(struct nm_desc *d ) closes the file descriptor, unmaps memory, frees resources. .It Va int nm_inject(struct nm_desc *d, const void *buf, size_t size ) similar to .Va pcap_inject() , pushes a packet to a ring, returns the size of the packet is successful, or 0 on error; .It Va int nm_dispatch(struct nm_desc *d, int cnt, nm_cb_t cb, u_char *arg ) similar to .Va pcap_dispatch() , applies a callback to incoming packets .It Va u_char * nm_nextpkt(struct nm_desc *d, struct nm_pkthdr *hdr ) similar to .Va pcap_next() , fetches the next packet .El .Sh SUPPORTED DEVICES .Nm natively supports the following devices: .Pp On .Fx : .Xr cxgbe 4 , .Xr em 4 , .Xr iflib 4 .Pq providing Xr igb 4 and Xr em 4 , .Xr ix 4 , .Xr ixl 4 , .Xr re 4 , .Xr vtnet 4 . .Pp On Linux e1000, e1000e, i40e, igb, ixgbe, ixgbevf, r8169, virtio_net, vmxnet3. .Pp NICs without native support can still be used in .Nm mode through emulation. Performance is inferior to native netmap mode but still significantly higher than various raw socket types (bpf, PF_PACKET, etc.). Note that for slow devices (such as 1 Gbit/s and slower NICs, or several 10 Gbit/s NICs whose hardware is unable to sustain line rate), emulated and native mode will likely have similar or same throughput. .Pp When emulation is in use, packet sniffer programs such as tcpdump could see received packets before they are diverted by netmap. This behaviour is not intentional, being just an artifact of the implementation of emulation. Note that in case the netmap application subsequently moves packets received from the emulated adapter onto the host RX ring, the sniffer will intercept those packets again, since the packets are injected to the host stack as they were received by the network interface. .Pp Emulation is also available for devices with native netmap support, which can be used for testing or performance comparison. The sysctl variable .Va dev.netmap.admode globally controls how netmap mode is implemented. .Sh SYSCTL VARIABLES AND MODULE PARAMETERS Some aspects of the operation of .Nm and .Nm VALE are controlled through sysctl variables on .Fx .Em ( dev.netmap.* ) and module parameters on Linux .Em ( /sys/module/netmap/parameters/* ) : .Bl -tag -width indent .It Va dev.netmap.admode: 0 Controls the use of native or emulated adapter mode. .Pp 0 uses the best available option; .Pp 1 forces native mode and fails if not available; .Pp 2 forces emulated hence never fails. .It Va dev.netmap.generic_rings: 1 Number of rings used for emulated netmap mode .It Va dev.netmap.generic_ringsize: 1024 Ring size used for emulated netmap mode .It Va dev.netmap.generic_mit: 100000 Controls interrupt moderation for emulated mode .It Va dev.netmap.fwd: 0 Forces NS_FORWARD mode .It Va dev.netmap.txsync_retry: 2 Number of txsync loops in the .Nm VALE flush function .It Va dev.netmap.no_pendintr: 1 Forces recovery of transmit buffers on system calls .It Va dev.netmap.no_timestamp: 0 Disables the update of the timestamp in the netmap ring .It Va dev.netmap.verbose: 0 Verbose kernel messages .It Va dev.netmap.buf_num: 163840 .It Va dev.netmap.buf_size: 2048 .It Va dev.netmap.ring_num: 200 .It Va dev.netmap.ring_size: 36864 .It Va dev.netmap.if_num: 100 .It Va dev.netmap.if_size: 1024 Sizes and number of objects (netmap_if, netmap_ring, buffers) for the global memory region. The only parameter worth modifying is .Va dev.netmap.buf_num as it impacts the total amount of memory used by netmap. .It Va dev.netmap.buf_curr_num: 0 .It Va dev.netmap.buf_curr_size: 0 .It Va dev.netmap.ring_curr_num: 0 .It Va dev.netmap.ring_curr_size: 0 .It Va dev.netmap.if_curr_num: 0 .It Va dev.netmap.if_curr_size: 0 Actual values in use. .It Va dev.netmap.priv_buf_num: 4098 .It Va dev.netmap.priv_buf_size: 2048 .It Va dev.netmap.priv_ring_num: 4 .It Va dev.netmap.priv_ring_size: 20480 .It Va dev.netmap.priv_if_num: 2 .It Va dev.netmap.priv_if_size: 1024 Sizes and number of objects (netmap_if, netmap_ring, buffers) for private memory regions. A separate memory region is used for each .Nm VALE port and each pair of .Nm netmap pipes . .It Va dev.netmap.bridge_batch: 1024 Batch size used when moving packets across a .Nm VALE switch. Values above 64 generally guarantee good performance. .It Va dev.netmap.max_bridges: 8 Max number of .Nm VALE switches that can be created. This tunable can be specified at loader time. .It Va dev.netmap.ptnet_vnet_hdr: 1 Allow ptnet devices to use virtio-net headers .It Va dev.netmap.port_numa_affinity: 0 On .Xr numa 4 systems, allocate memory for netmap ports from the local NUMA domain when possible. This can improve performance by reducing the number of remote memory accesses. However, when forwarding packets between ports attached to different NUMA domains, this will prevent zero-copy forwarding optimizations and thus may hurt performance. Note that this setting must be specified as a loader tunable at boot time. .El .Sh SYSTEM CALLS .Nm uses .Xr select 2 , .Xr poll 2 , .Xr epoll 7 and .Xr kqueue 2 to wake up processes when significant events occur, and .Xr mmap 2 to map memory. .Xr ioctl 2 is used to configure ports and .Nm VALE switches . .Pp Applications may need to create threads and bind them to specific cores to improve performance, using standard OS primitives, see .Xr pthread 3 . In particular, .Xr pthread_setaffinity_np 3 may be of use. .Sh EXAMPLES .Ss TEST PROGRAMS .Nm comes with a few programs that can be used for testing or simple applications. See the .Pa examples/ directory in .Nm distributions, or .Pa tools/tools/netmap/ directory in .Fx distributions. .Pp .Xr pkt-gen 8 is a general purpose traffic source/sink. .Pp As an example .Dl pkt-gen -i ix0 -f tx -l 60 can generate an infinite stream of minimum size packets, and .Dl pkt-gen -i ix0 -f rx is a traffic sink. Both print traffic statistics, to help monitor how the system performs. .Pp .Xr pkt-gen 8 has many options can be uses to set packet sizes, addresses, rates, and use multiple send/receive threads and cores. .Pp .Xr bridge 4 is another test program which interconnects two .Nm ports. It can be used for transparent forwarding between interfaces, as in .Dl bridge -i netmap:ix0 -i netmap:ix1 or even connect the NIC to the host stack using netmap .Dl bridge -i netmap:ix0 .Ss USING THE NATIVE API The following code implements a traffic generator: .Pp .Bd -literal -compact #include \&... void sender(void) { struct netmap_if *nifp; struct netmap_ring *ring; struct nmreq nmr; struct pollfd fds; fd = open("/dev/netmap", O_RDWR); bzero(&nmr, sizeof(nmr)); strcpy(nmr.nr_name, "ix0"); nmr.nm_version = NETMAP_API; ioctl(fd, NIOCREGIF, &nmr); p = mmap(0, nmr.nr_memsize, fd); nifp = NETMAP_IF(p, nmr.nr_offset); ring = NETMAP_TXRING(nifp, 0); fds.fd = fd; fds.events = POLLOUT; for (;;) { poll(&fds, 1, -1); while (!nm_ring_empty(ring)) { i = ring->cur; buf = NETMAP_BUF(ring, ring->slot[i].buf_index); ... prepare packet in buf ... ring->slot[i].len = ... packet length ... ring->head = ring->cur = nm_ring_next(ring, i); } } } .Ed .Ss HELPER FUNCTIONS A simple receiver can be implemented using the helper functions: .Pp .Bd -literal -compact #define NETMAP_WITH_LIBS #include \&... void receiver(void) { struct nm_desc *d; struct pollfd fds; u_char *buf; struct nm_pkthdr h; ... d = nm_open("netmap:ix0", NULL, 0, 0); fds.fd = NETMAP_FD(d); fds.events = POLLIN; for (;;) { poll(&fds, 1, -1); while ( (buf = nm_nextpkt(d, &h)) ) consume_pkt(buf, h.len); } nm_close(d); } .Ed .Ss ZERO-COPY FORWARDING Since physical interfaces share the same memory region, it is possible to do packet forwarding between ports swapping buffers. The buffer from the transmit ring is used to replenish the receive ring: .Pp .Bd -literal -compact uint32_t tmp; struct netmap_slot *src, *dst; ... src = &src_ring->slot[rxr->cur]; dst = &dst_ring->slot[txr->cur]; tmp = dst->buf_idx; dst->buf_idx = src->buf_idx; dst->len = src->len; dst->flags = NS_BUF_CHANGED; src->buf_idx = tmp; src->flags = NS_BUF_CHANGED; rxr->head = rxr->cur = nm_ring_next(rxr, rxr->cur); txr->head = txr->cur = nm_ring_next(txr, txr->cur); ... .Ed .Ss ACCESSING THE HOST STACK The host stack is for all practical purposes just a regular ring pair, which you can access with the netmap API (e.g., with .Dl nm_open("netmap:eth0^", ... ) ; All packets that the host would send to an interface in .Nm mode end up into the RX ring, whereas all packets queued to the TX ring are send up to the host stack. .Ss VALE SWITCH A simple way to test the performance of a .Nm VALE switch is to attach a sender and a receiver to it, e.g., running the following in two different terminals: .Dl pkt-gen -i vale1:a -f rx # receiver .Dl pkt-gen -i vale1:b -f tx # sender The same example can be used to test netmap pipes, by simply changing port names, e.g., .Dl pkt-gen -i vale2:x{3 -f rx # receiver on the master side .Dl pkt-gen -i vale2:x}3 -f tx # sender on the slave side .Pp The following command attaches an interface and the host stack to a switch: .Dl valectl -h vale2:em0 Other .Nm clients attached to the same switch can now communicate with the network card or the host. .Sh SEE ALSO .Xr vale 4 , .Xr bridge 8 , -.Xr valectl 8 , .Xr lb 8 , .Xr nmreplay 8 , -.Xr pkt-gen 8 +.Xr pkt-gen 8 , +.Xr valectl 8 .Pp .Pa http://info.iet.unipi.it/~luigi/netmap/ .Pp Luigi Rizzo, Revisiting network I/O APIs: the netmap framework, Communications of the ACM, 55 (3), pp.45-51, March 2012 .Pp Luigi Rizzo, netmap: a novel framework for fast packet I/O, Usenix ATC'12, June 2012, Boston .Pp Luigi Rizzo, Giuseppe Lettieri, VALE, a switched ethernet for virtual machines, ACM CoNEXT'12, December 2012, Nice .Pp Luigi Rizzo, Giuseppe Lettieri, Vincenzo Maffione, Speeding up packet I/O in virtual machines, ACM/IEEE ANCS'13, October 2013, San Jose .Sh AUTHORS .An -nosplit The .Nm framework has been originally designed and implemented at the Universita` di Pisa in 2011 by .An Luigi Rizzo , and further extended with help from .An Matteo Landi , .An Gaetano Catalli , .An Giuseppe Lettieri , and .An Vincenzo Maffione . .Pp .Nm and .Nm VALE have been funded by the European Commission within FP7 Projects CHANGE (257422) and OPENLAB (287581). .Sh CAVEATS No matter how fast the CPU and OS are, achieving line rate on 10G and faster interfaces requires hardware with sufficient performance. Several NICs are unable to sustain line rate with small packet sizes. Insufficient PCIe or memory bandwidth can also cause reduced performance. .Pp Another frequent reason for low performance is the use of flow control on the link: a slow receiver can limit the transmit speed. Be sure to disable flow control when running high speed experiments. .Ss SPECIAL NIC FEATURES .Nm is orthogonal to some NIC features such as multiqueue, schedulers, packet filters. .Pp Multiple transmit and receive rings are supported natively and can be configured with ordinary OS tools, such as .Xr ethtool 8 or device-specific sysctl variables. The same goes for Receive Packet Steering (RPS) and filtering of incoming traffic. .Pp .Nm .Em does not use features such as .Em checksum offloading , TCP segmentation offloading , .Em encryption , VLAN encapsulation/decapsulation , etc. When using netmap to exchange packets with the host stack, make sure to disable these features. diff --git a/share/man/man4/ng_nat.4 b/share/man/man4/ng_nat.4 index 10615b3b387d..53cd841a7392 100644 --- a/share/man/man4/ng_nat.4 +++ b/share/man/man4/ng_nat.4 @@ -1,407 +1,407 @@ .\" Copyright (c) 2005 Gleb Smirnoff .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd January 24, 2021 .Dt NG_NAT 4 .Os .Sh NAME .Nm ng_nat .Nd "NAT netgraph node type" .Sh SYNOPSIS .In netgraph/ng_nat.h .Sh DESCRIPTION An .Nm node performs network address translation (NAT) of IPv4 packets passing through it. A .Nm nat node uses .Xr libalias 3 engine for packet aliasing. .Sh HOOKS This node type has two hooks: .Bl -tag -width ".Va out" .It Va out Packets received on this hook are considered outgoing and will be masqueraded to a configured address. .It Va in Packets coming on this hook are considered incoming and will be dealiased. .El .Sh CONTROL MESSAGES This node type supports the generic control messages, plus the following: .Bl -tag -width foo .It Dv NGM_NAT_SET_IPADDR Pq Ic setaliasaddr Configure aliasing address for a node. After both hooks have been connected and aliasing address was configured, a node is ready for aliasing operation. .It Dv NGM_NAT_SET_MODE Pq Ic setmode Set node's operation mode using supplied .Vt "struct ng_nat_mode" . .Bd -literal struct ng_nat_mode { uint32_t flags; uint32_t mask; }; /* Supported flags: */ #define NG_NAT_LOG 0x01 #define NG_NAT_DENY_INCOMING 0x02 #define NG_NAT_SAME_PORTS 0x04 #define NG_NAT_UNREGISTERED_ONLY 0x10 #define NG_NAT_RESET_ON_ADDR_CHANGE 0x20 #define NG_NAT_PROXY_ONLY 0x40 #define NG_NAT_REVERSE 0x80 #define NG_NAT_UNREGISTERED_CGN 0x100 .Ed .Pp The corresponding libalias flags can be found by replacing the .Vt "NG_NAT" prefix with .Vt "PKT_ALIAS" . .It Dv NGM_NAT_SET_TARGET Pq Ic settarget Configure target address for a node. When an incoming packet not associated with any pre-existing aliasing link arrives at the host machine, it will be sent to the specified address. .It Dv NGM_NAT_REDIRECT_PORT Pq Ic redirectport Redirect incoming connections arriving to given port(s) to another host and port(s). The following .Vt "struct ng_nat_redirect_port" must be supplied as argument. .Bd -literal #define NG_NAT_DESC_LENGTH 64 struct ng_nat_redirect_port { struct in_addr local_addr; struct in_addr alias_addr; struct in_addr remote_addr; uint16_t local_port; uint16_t alias_port; uint16_t remote_port; uint8_t proto; char description[NG_NAT_DESC_LENGTH]; }; .Ed .Pp Redirection is assigned an unique ID which is returned as response to this message, and information about redirection added to list of static redirects which later can be retrieved by .Dv NGM_NAT_LIST_REDIRECTS message. .It Dv NGM_NAT_REDIRECT_ADDR Pq Ic redirectaddr Redirect traffic for public IP address to a machine on the local network. This function is known as .Em static NAT . The following .Vt "struct ng_nat_redirect_addr" must be supplied as argument. .Bd -literal struct ng_nat_redirect_addr { struct in_addr local_addr; struct in_addr alias_addr; char description[NG_NAT_DESC_LENGTH]; }; .Ed .Pp Unique ID for this redirection is returned as response to this message. .It Dv NGM_NAT_REDIRECT_PROTO Pq Ic redirectproto Redirect incoming IP packets of protocol .Va proto (see .Xr protocols 5 ) to a machine on the local network. The following .Vt "struct ng_nat_redirect_proto" must be supplied as argument. .Bd -literal struct ng_nat_redirect_proto { struct in_addr local_addr; struct in_addr alias_addr; struct in_addr remote_addr; uint8_t proto; char description[NG_NAT_DESC_LENGTH]; }; .Ed .Pp Unique ID for this redirection is returned as response to this message. .It Dv NGM_NAT_REDIRECT_DYNAMIC Pq Ic redirectdynamic Mark redirection with specified ID as dynamic, i.e., it will serve for exactly one next connection and then will be automatically deleted from internal links table. Only fully specified links can be made dynamic. The redirection with this ID is also immediately deleted from user-visible list of static redirects (available through .Dv NGM_NAT_LIST_REDIRECTS message). .It Dv NGM_NAT_REDIRECT_DELETE Pq Ic redirectdelete Delete redirection with specified ID (currently active connections are not affected). .It Dv NGM_NAT_ADD_SERVER Pq Ic addserver Add another server to a pool. This is used to transparently offload network load on a single server and distribute the load across a pool of servers, also known as .Em LSNAT (RFC 2391). The following .Vt "struct ng_nat_add_server" must be supplied as argument. .Bd -literal struct ng_nat_add_server { uint32_t id; struct in_addr addr; uint16_t port; }; .Ed .Pp First, the redirection is set up by .Dv NGM_NAT_REDIRECT_PORT or .Dv NGM_NAT_REDIRECT_ADDR . Then, ID of that redirection is used in multiple .Dv NGM_NAT_ADD_SERVER messages to add necessary number of servers. For redirections created by .Dv NGM_NAT_REDIRECT_ADDR , the .Va port is ignored and could have any value. Original redirection's parameters .Va local_addr and .Va local_port are also ignored after .Dv NGM_NAT_ADD_SERVER was used (they are effectively replaced by server pool). .It Dv NGM_NAT_LIST_REDIRECTS Pq Ic listredirects Return list of configured static redirects as .Vt "struct ng_nat_list_redirects" . .Bd -literal struct ng_nat_listrdrs_entry { uint32_t id; /* Anything except zero */ struct in_addr local_addr; struct in_addr alias_addr; struct in_addr remote_addr; uint16_t local_port; uint16_t alias_port; uint16_t remote_port; uint16_t proto; /* Valid proto or NG_NAT_REDIRPROTO_ADDR */ uint16_t lsnat; /* LSNAT servers count */ char description[NG_NAT_DESC_LENGTH]; }; struct ng_nat_list_redirects { uint32_t total_count; struct ng_nat_listrdrs_entry redirects[]; }; #define NG_NAT_REDIRPROTO_ADDR (IPPROTO_MAX + 3) .Ed .Pp Entries of the .Va redirects array returned in the unified format for all redirect types. Ports are meaningful only if protocol is either TCP or UDP and .Em static NAT redirection (created by .Dv NGM_NAT_REDIRECT_ADDR ) is indicated by .Va proto set to .Dv NG_NAT_REDIRPROTO_ADDR . If .Va lsnat servers counter is greater than zero, then .Va local_addr and .Va local_port are also meaningless. .It Dv NGM_NAT_PROXY_RULE Pq Ic proxyrule Specify a transparent proxying rule (string must be supplied as argument). See .Xr libalias 3 for details. .It Dv NGM_NAT_LIBALIAS_INFO Pq Ic libaliasinfo Return internal statistics of .Xr libalias 3 instance as .Vt "struct ng_nat_libalias_info" . .Bd -literal struct ng_nat_libalias_info { uint32_t icmpLinkCount; uint32_t udpLinkCount; uint32_t tcpLinkCount; uint32_t sctpLinkCount; uint32_t pptpLinkCount; uint32_t protoLinkCount; uint32_t fragmentIdLinkCount; uint32_t fragmentPtrLinkCount; uint32_t sockCount; }; .Ed In case of .Nm failed to retrieve a certain counter from its .Xr libalias instance, the corresponding field is returned as .Va UINT32_MAX . .It Dv NGM_NAT_SET_DLT Pq Ic setdlt Sets the data link type on the .Va in and .Va out hooks. Currently, supported types are .Cm DLT_RAW (raw IP datagrams , no offset applied, the default) and .Cm DLT_EN10MB (Ethernet). DLT_ definitions can be found in .In net/bpf.h . If you want to work on the .Xr ipfw 8 level you must use no additional offset by specifying .Cm DLT_RAW . If, however, you attach .Nm to a network interface directly and .Cm EN10MB is specified, then the extra offset will be applied to take into account link-level header. In this mode the .Nm would also inspect appropriate type field in the Ethernet header and pass-through any datagrams that are not IP packets. .It Dv NGM_NAT_GET_DLT Pq Ic getdlt This control message returns the current data link type of the .Va in and .Va out hooks. .El .Pp In all redirection messages .Va local_addr and .Va local_port mean address and port of target machine in the internal network, respectively. If .Va alias_addr is zero, then default aliasing address (set by .Dv NGM_NAT_SET_IPADDR ) is used. Connections can also be restricted to be accepted only from specific external machines by using non-zero .Va remote_addr and/or .Va remote_port . Each redirection assigned an ID which can be later used for redirection manipulation on individual basis (e.g., removal). This ID guaranteed to be unique until the node shuts down (it will not be reused after deletion), and is returned to user after making each new redirection or can be found in the stored list of all redirections. The .Va description passed to and from node unchanged, together with ID providing a way for several entities to concurrently manipulate redirections in automated way. .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message, or when both hooks are disconnected. .Sh EXAMPLES In the following example, the packets are injected into a .Nm nat node using the .Xr ng_ipfw 4 node. .Bd -literal -offset indent # Create NAT node ngctl mkpeer ipfw: nat 60 out ngctl name ipfw:60 nat ngctl connect ipfw: nat: 61 in ngctl msg nat: setaliasaddr x.y.35.8 # Divert traffic into NAT node ipfw add 300 netgraph 61 all from any to any in via fxp0 ipfw add 400 netgraph 60 all from any to any out via fxp0 # Let packets continue with after being (de)aliased sysctl net.inet.ip.fw.one_pass=0 .Ed .Pp The .Nm node can be inserted right after the .Xr ng_iface 4 node in the graph. In the following example, we perform masquerading on a serial line with HDLC encapsulation. .Bd -literal -offset indent /usr/sbin/ngctl -f- <<-SEQ mkpeer cp0: cisco rawdata downstream name cp0:rawdata hdlc mkpeer hdlc: nat inet in name hdlc:inet nat mkpeer nat: iface out inet msg nat: setaliasaddr x.y.8.35 SEQ ifconfig ng0 x.y.8.35 x.y.8.1 .Ed .Pp The .Nm node can also be attached directly to the physical interface via .Xr ng_ether 4 node in the graph. In the following example, we perform masquerading on a Ethernet interface connected to a public network. .Bd -literal -offset indent ifconfig igb0 inet x.y.8.35 netmask 0xfffff000 route add default x.y.0.1 /usr/sbin/ngctl -f- <<-SEQ mkpeer igb0: nat lower in name igb0:lower igb0_NAT connect igb0: igb0_NAT: upper out msg igb0_NAT: setdlt 1 msg igb0_NAT: setaliasaddr x.y.8.35 SEQ .Ed .Sh SEE ALSO .Xr libalias 3 , .Xr ng_ipfw 4 , .Xr natd 8 , -.Xr ngctl 8 , -.Xr ng_ether 8 +.Xr ng_ether 8 , +.Xr ngctl 8 .Sh HISTORY The .Nm node type was implemented in .Fx 6.0 . .Sh AUTHORS .An Gleb Smirnoff Aq Mt glebius@FreeBSD.org diff --git a/share/man/man4/ng_pppoe.4 b/share/man/man4/ng_pppoe.4 index 346b2bfbe279..5b5f0dd64de2 100644 --- a/share/man/man4/ng_pppoe.4 +++ b/share/man/man4/ng_pppoe.4 @@ -1,587 +1,587 @@ .\" Copyright (c) 1996-1999 Whistle Communications, Inc. .\" All rights reserved. .\" .\" Subject to the following obligations and disclaimer of warranty, use and .\" redistribution of this software, in source or object code forms, with or .\" without modifications are expressly permitted by Whistle Communications; .\" provided, however, that: .\" 1. Any and all reproductions of the source or object code must include the .\" copyright notice above and the following disclaimer of warranties; and .\" 2. No rights are granted, in any manner or form, to use Whistle .\" Communications, Inc. trademarks, including the mark "WHISTLE .\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as .\" such appears in the above copyright notice or in the software. .\" .\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, .\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. .\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY .\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS .\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. .\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES .\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING .\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, .\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY .\" OF SUCH DAMAGE. .\" .\" Author: Archie Cobbs .\" $Whistle: ng_pppoe.8,v 1.1 1999/01/25 23:46:27 archie Exp $ .\" .Dd May 1, 2022 .Dt NG_PPPOE 4 .Os .Sh NAME .Nm ng_pppoe .Nd RFC 2516 PPPoE protocol netgraph node type .Sh SYNOPSIS .In sys/types.h .In net/ethernet.h .In netgraph.h .In netgraph/ng_pppoe.h .Sh DESCRIPTION The .Nm pppoe node type performs the PPPoE protocol. It is used in conjunction with the .Xr netgraph 4 extensions to the Ethernet framework to divert and inject Ethernet packets to and from a PPP agent (which is not specified). .Pp The .Dv NGM_PPPOE_GET_STATUS control message can be used at any time to query the current status of the PPPoE module. The only statistics presently available are the total packet counts for input and output. This node does not yet support the .Dv NGM_TEXT_STATUS control message. .Sh HOOKS This node type supports the following hooks: .Bl -tag -width ".Va [unspecified]" .It Va ethernet The hook that should normally be connected to an .Xr ng_ether 4 node. Once connected, .Nm will send a message down this hook to determine Ethernet address of the underlying node. Obtained address will be stored and then used for outgoing datagrams. .It Va debug Presently no use. .It Va [unspecified] Any other name is assumed to be a session hook that will be connected to a PPP client agent, or a PPP server agent. .El .Sh CONTROL MESSAGES This node type supports the generic control messages, plus the following: .Bl -tag -width 3n .It Dv NGM_PPPOE_GET_STATUS This command returns status information in a .Dv "struct ngpppoestat" : .Bd -literal -offset 4n struct ngpppoestat { u_int packets_in; /* packets in from Ethernet */ u_int packets_out; /* packets out towards Ethernet */ }; .Ed .It Dv NGM_TEXT_STATUS This generic message returns a human-readable version of the node status. (not yet) .It Dv NGM_PPPOE_CONNECT Pq Ic pppoe_connect Tell a nominated newly created hook that its session should enter the state machine as a client. It must be newly created and a service name can be given as an argument. It is legal to specify a zero-length service name, this is common on some DSL setups. It is possible to request a connection to a specific access concentrator, and/or set a specific Host-Uniq tag, required by some Internet providers, using the .Qq Li [AC-Name\\][Host-Uniq|]Service-Name syntax. To set a binary Host-Uniq, it must be encoded as a hexadecimal lowercase string and prefixed with .Qq Li 0x , for example .Qq Li 0x6d792d746167 is equivalent to .Qq Li my-tag . A session request packet will be broadcast on the Ethernet. This command uses the .Dv ngpppoe_init_data structure shown below. For example, this init data argument can be used to connect to .Qq Li my-isp service with .Qq Li my-host uniq tag, accepting only .Qq Li remote-ac as access concentrator: .Bd -literal -offset indent "remote-ac\\my-host|my-isp" .Ed .It Dv NGM_PPPOE_LISTEN Pq Ic pppoe_listen Tell a nominated newly created hook that its session should enter the state machine as a server listener. The argument given is the name of the service to listen for. A zero-length service name will match all requests for service. A matching service request packet will be passed unmodified back to the process responsible for starting the service. It can then examine it and pass it on to the session that is started to answer the request. This command uses the .Dv ngpppoe_init_data structure shown below. .It Dv NGM_PPPOE_OFFER Pq Ic pppoe_offer Tell a nominated newly created hook that its session should enter the state machine as a server. The argument given is the name of the service to offer. A zero-length service is legal. The State machine will progress to a state where it will await a request packet to be forwarded to it from the startup server, which in turn probably received it from a LISTEN mode hook (see above). This is so that information that is required for the session that is embedded in the original session request packet, is made available to the state machine that eventually answers the request. When the Session request packet is received, the session negotiation will proceed. This command uses the .Dv ngpppoe_init_data structure shown below. .El .Pp The three commands above use a common data structure: .Bd -literal -offset 4n struct ngpppoe_init_data { char hook[NG_HOOKSIZ]; /* hook to monitor on */ uint16_t data_len; /* length of the service name */ char data[0]; /* init data goes here */ }; .Ed .Bl -tag -width 3n .It Dv NGM_PPPOE_SUCCESS Pq Ic pppoe_success This command is sent to the node that started this session with one of the above messages, and reports a state change. This message reports successful Session negotiation. It uses the structure shown below, and reports back the hook name corresponding to the successful session. .It Dv NGM_PPPOE_FAIL Pq Ic pppoe_fail This command is sent to the node that started this session with one of the above messages, and reports a state change. This message reports failed Session negotiation. It uses the structure shown below, and reports back the hook name corresponding to the failed session. The hook will probably have been removed immediately after sending this message. .It Dv NGM_PPPOE_CLOSE Pq Ic pppoe_close This command is sent to the node that started this session with one of the above messages, and reports a state change. This message reports a request to close a session. It uses the structure shown below, and reports back the hook name corresponding to the closed session. The hook will probably have been removed immediately after sending this message. At present this message is not yet used and a .Dv NGM_PPPOE_FAIL message will be received at closure instead. .It Dv NGM_PPPOE_ACNAME This command is sent to the node that started this session with one of the above messages, and reports the Access Concentrator Name. .El .Pp The four commands above use a common data structure: .Bd -literal -offset 4n struct ngpppoe_sts { char hook[NG_HOOKSIZ]; }; .Ed .Bl -tag -width 3n .It Dv NGM_PPPOE_GETMODE Pq Ic pppoe_getmode This command returns the current compatibility mode of the node as a string. .Tn ASCII form of this message is .Qq Li pppoe_getmode . The following keywords can be returned: .Bl -tag -width 3n .It Qq standard The node operates according to RFC 2516. .It Qq 3Com When .Nm is a PPPoE client, it initiates a session encapsulating packets into incorrect 3Com ethertypes. This compatibility option does not affect server mode. In server mode .Nm supports both modes simultaneously, depending on the ethertype, the client used when connecting. .It Qq D-Link When .Nm is a PPPoE server serving only specific Service-Name(s), it will respond to a PADI requests with empty Service-Name tag, returning all available Service-Name(s) on node. This option is necessary for compatibility with D-Link DI-614+ and DI-624+ SOHO routers as clients, when serving only specific Service-Name. This compatibility option does not affect client mode. .El .It Dv NGM_PPPOE_SETMODE Pq Ic pppoe_setmode Configure node to the specified mode. The string argument is required. This command understands the same keywords that are returned by the .Dv NGM_PPPOE_GETMODE command. .Tn ASCII form of this message is .Qq Li pppoe_setmode . For example, the following command will configure the node to initiate the next session in the proprietary 3Com mode: .Bd -literal -offset indent ngctl msg fxp0:orphans pppoe_setmode '"3Com"' .Ed .It Dv NGM_PPPOE_SETENADDR Pq Ic setenaddr Set the node Ethernet address for outgoing datagrams. This message is important when a node has failed to obtain an Ethernet address from its peer on the .Dv ethernet hook, or when user wants to override this address with another one. .Tn ASCII form of this message is .Qq Li setenaddr . .It Dv NGM_PPPOE_SETMAXP Pq Ic setmaxp Set the node PPP-Max-Payload value as described in RFC 4638. This message applies only to a client configuration. .Tn ASCII form of this message is .Qq Li setmaxp . .Pp Data structure returned to client is: .Bd -literal -offset 4n struct ngpppoe_maxp { char hook[NG_HOOKSIZ]; uint16_t data; }; .Ed .It Dv NGM_PPPOE_SEND_HURL Pq Ic send_hurl Tell a nominated hook with an active session to send a PADM message with a HURL tag. The argument is the URL to be delivered to the client: .Bd -literal -offset indent ngctl msg fxp0:orphans send_hurl '{ hook="myHook" data="http://example.net/cpe" }' .Ed .It Dv NGM_PPPOE_SEND_MOTM Pq Ic send_motm Tell a nominated hook with an active session to send a PADM message with a MOTM tag. The argument is the message to be delivered to the client: .Bd -literal -offset indent ngctl msg fxp0:orphans send_motm '{ hook="myHook" data="Welcome aboard" }' .Ed .El .Pp The two commands above use the same ngpppoe_init_data structure described above. .Bl -tag -width 3n .It Dv NGM_PPPOE_HURL This command is sent to the node that started this session when a PADM message with a HURL tag is received, and contains a URL that the host can pass to a web browser for presentation to the user. .It Dv NGM_PPPOE_MOTM This command is sent to the node that started this session when a PADM message with a MOTM tag is received, and contains a Message Of The Minute that the host can display to the user. .El .Pp The two commands above use a common data structure: .Bd -literal -offset 4n struct ngpppoe_padm { char msg[PPPOE_PADM_VALUE_SIZE]; }; .Ed .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message, when all session have been disconnected or when the .Dv ethernet hook is disconnected. .Sh SYSCTL VARIABLES The node can mark transmitted LCP Ethernet packets (protocol 0xc021) with 3-bit Priority Code Point (PCP) referring to IEEE 802.1p class of service with following .Xr sysctl 8 variable. .Bl -tag -width indent .It Va net.graph.pppoe.lcp_pcp: 0..7 (default: 0) Set it to non-zero value to be used by parent network interface driver like .Xr vlan 4 .El .Sh EXAMPLES The following code uses .Dv libnetgraph to set up a .Nm node and connect it to both a socket node and an Ethernet node. It can handle the case of when a .Nm node is already attached to the Ethernet. It then starts a client session. .Bd -literal #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include static int setup(char *ethername, char *service, char *sessname, int *dfd, int *cfd); int main() { int fd1, fd2; setup("xl0", NULL, "fred", &fd1, &fd2); sleep (30); } static int setup(char *ethername, char *service, char *sessname, int *dfd, int *cfd) { struct ngm_connect ngc; /* connect */ struct ngm_mkpeer mkp; /* mkpeer */ /******** nodeinfo stuff **********/ u_char rbuf[2 * 1024]; struct ng_mesg *const resp = (struct ng_mesg *) rbuf; struct hooklist *const hlist = (struct hooklist *) resp->data; struct nodeinfo *const ninfo = &hlist->nodeinfo; int ch, no_hooks = 0; struct linkinfo *link; struct nodeinfo *peer; /****message to connect PPPoE session*****/ struct { struct ngpppoe_init_data idata; char service[100]; } message; /********tracking our little graph ********/ char path[100]; char source_ID[NG_NODESIZ]; char pppoe_node_name[100]; int k; /* * Create the data and control sockets */ if (NgMkSockNode(NULL, cfd, dfd) < 0) { return (errno); } /* * find the ether node of the name requested by asking it for * it's inquiry information. */ if (strlen(ethername) > 16) return (EINVAL); sprintf(path, "%s:", ethername); if (NgSendMsg(*cfd, path, NGM_GENERIC_COOKIE, NGM_LISTHOOKS, NULL, 0) < 0) { return (errno); } /* * the command was accepted so it exists. Await the reply (It's * almost certainly already waiting). */ if (NgRecvMsg(*cfd, resp, sizeof(rbuf), NULL) < 0) { return (errno); } /** * The following is available about the node: * ninfo->name (string) * ninfo->type (string) * ninfo->id (uint32_t) * ninfo->hooks (uint32_t) (count of hooks) * check it is the correct type. and get it's ID for use * with mkpeer later. */ if (strncmp(ninfo->type, NG_ETHER_NODE_TYPE, strlen(NG_ETHER_NODE_TYPE)) != 0) { return (EPROTOTYPE); } sprintf(source_ID, "[%08x]:", ninfo->id); /* * look for a hook already attached. */ for (k = 0; k < ninfo->hooks; k++) { /** * The following are available about each hook. * link->ourhook (string) * link->peerhook (string) * peer->name (string) * peer->type (string) * peer->id (uint32_t) * peer->hooks (uint32_t) */ link = &hlist->link[k]; peer = &hlist->link[k].nodeinfo; /* Ignore debug hooks */ if (strcmp("debug", link->ourhook) == 0) continue; /* If the orphans hook is attached, use that */ if (strcmp(NG_ETHER_HOOK_ORPHAN, link->ourhook) == 0) { break; } /* the other option is the 'divert' hook */ if (strcmp("NG_ETHER_HOOK_DIVERT", link->ourhook) == 0) { break; } } /* * See if we found a hook there. */ if (k < ninfo->hooks) { if (strcmp(peer->type, NG_PPPOE_NODE_TYPE) == 0) { /* * If it's a type PPPoE, we skip making one * ourself, but we continue, using * the existing one. */ sprintf(pppoe_node_name, "[%08x]:", peer->id); } else { /* * There is already someone hogging the data, * return an error. Some day we'll try * daisy-chaining.. */ return (EBUSY); } } else { /* * Try make a node of type PPPoE against node "ID" * On hook NG_ETHER_HOOK_ORPHAN. */ snprintf(mkp.type, sizeof(mkp.type), "%s", NG_PPPOE_NODE_TYPE); snprintf(mkp.ourhook, sizeof(mkp.ourhook), "%s", NG_ETHER_HOOK_ORPHAN); snprintf(mkp.peerhook, sizeof(mkp.peerhook), "%s", NG_PPPOE_HOOK_ETHERNET); /* Send message */ if (NgSendMsg(*cfd, source_ID, NGM_GENERIC_COOKIE, NGM_MKPEER, &mkp, sizeof(mkp)) < 0) { return (errno); } /* * Work out a name for the new node. */ sprintf(pppoe_node_name, "%s:%s", source_ID, NG_ETHER_HOOK_ORPHAN); } /* * We now have a PPPoE node attached to the Ethernet * card. The Ethernet is addressed as ethername: The PPPoE * node is addressed as pppoe_node_name: attach to it. * Connect socket node to specified node Use the same hook * name on both ends of the link. */ snprintf(ngc.path, sizeof(ngc.path), "%s", pppoe_node_name); snprintf(ngc.ourhook, sizeof(ngc.ourhook), "%s", sessname); snprintf(ngc.peerhook, sizeof(ngc.peerhook), "%s", sessname); if (NgSendMsg(*cfd, ".:", NGM_GENERIC_COOKIE, NGM_CONNECT, &ngc, sizeof(ngc)) < 0) { return (errno); } #ifdef NONSTANDARD /* * In some cases we are speaking to 3Com hardware, so * configure node to non-standard mode. */ if (NgSendMsg(*cfd, ngc.path, NGM_PPPOE_COOKIE, NGM_PPPOE_SETMODE, NG_PPPOE_NONSTANDARD, strlen(NG_PPPOE_NONSTANDARD) + 1) == -1) { return (errno); } #endif /* * Send it a message telling it to start up. */ bzero(&message, sizeof(message)); snprintf(message.idata.hook, sizeof(message.idata.hook), "%s", sessname); if (service == NULL) { message.idata.data_len = 0; } else { snprintf(message.idata.data, sizeof(message.idata.data), "%s", service); message.idata.data_len = strlen(service); } /* Tell session/hook to start up as a client */ if (NgSendMsg(*cfd, ngc.path, NGM_PPPOE_COOKIE, NGM_PPPOE_CONNECT, &message.idata, sizeof(message.idata) + message.idata.data_len) < 0) { return (errno); } return (0); } .Ed .Sh SEE ALSO .Xr netgraph 3 , .Xr netgraph 4 , .Xr ng_ether 4 , .Xr ng_ppp 4 , .Xr ng_socket 4 , +.Xr vlan 4 , .Xr ngctl 8 , -.Xr ppp 8 , -.Xr vlan 4 +.Xr ppp 8 .Rs .%A L. Mamakos .%A K. Lidl .%A J. Evarts .%A D. Carrel .%A D. Simone .%A R. Wheeler .%T "A Method for transmitting PPP over Ethernet (PPPoE)" .%O RFC 2516 .Re .Sh HISTORY The .Nm node type was implemented in .Fx 4.0 . .Sh AUTHORS .An Julian Elischer Aq Mt julian@FreeBSD.org diff --git a/share/man/man4/procdesc.4 b/share/man/man4/procdesc.4 index d0b99e5cbe07..f1f3757aa836 100644 --- a/share/man/man4/procdesc.4 +++ b/share/man/man4/procdesc.4 @@ -1,83 +1,83 @@ .\" .\" Copyright (c) 2013 Robert N. M. Watson .\" All rights reserved. .\" .\" This software was developed by SRI International and the University of .\" Cambridge Computer Laboratory under DARPA/AFRL contract (FA8750-10-C-0237) .\" ("CTSRD"), as part of the DARPA CRASH research programme. .\" .\" 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. .\" .Dd May 15, 2020 .Dt PROCDESC 4 .Os .Sh NAME .Nm procdesc .Nd process descriptor facility .Sh DESCRIPTION .Nm is a file-descriptor-oriented interface to process signalling and control, which supplements historic .Ux .Xr fork 2 and .Xr kill 2 , primitives with new system calls such as .Xr pdfork 2 and .Xr pdkill 2 , .Nm is designed for use with .Xr capsicum 4 , replacing process identifiers with capability-oriented references. However, it can also be used independently of .Xr capsicum 4 , displacing PIDs, which may otherwise suffer from race conditions. Given a process descriptor, it is possible to query its conventional PID using .Xr pdgetpid 2 . .Sh SEE ALSO .Xr fork 2 , .Xr kill 2 , +.Xr kqueue 2 , .Xr pdfork 2 , .Xr pdgetpid 2 , .Xr pdkill 2 , -.Xr kqueue 2 , .Xr wait4 2 , .Xr capsicum 4 .Sh HISTORY .Nm first appeared in .Fx 9.0 , and was developed at the University of Cambridge. .Sh AUTHORS .Nm was developed by .An -nosplit .An Robert Watson Aq Mt rwatson@FreeBSD.org and .An Jonathan Anderson Aq Mt jonathan@FreeBSD.org at the University of Cambridge, and .An Ben Laurie Aq Mt benl@FreeBSD.org and .An Kris Kennaway Aq Mt kris@FreeBSD.org at Google, Inc. diff --git a/share/man/man4/virtio_gpu.4 b/share/man/man4/virtio_gpu.4 index bb34ec419df6..f8d48faa05f0 100644 --- a/share/man/man4/virtio_gpu.4 +++ b/share/man/man4/virtio_gpu.4 @@ -1,54 +1,54 @@ .\"- .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" Copyright (c) 2014 Bryan Venteicher .\" All rights reserved. .\" Copyright (c) 2023 Arm Ltd .\" .\" 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. .\" .Dd August 14, 2023 .Dt VIRTIO_GPU 4 .Os .Sh NAME .Nm virtio_gpu .Nd VirtIO GPU driver .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device virtio_gpu" .Ed .Sh DESCRIPTION The .Nm device driver provides support for VirtIO gpu devices to create a .Xr vt 4 console. .Sh SEE ALSO -.Xr virtio 4 +.Xr virtio 4 , .Xr vt 4 .Sh HISTORY The .Nm driver first appeared in FreeBSD 14.0. diff --git a/share/man/man5/lindebugfs.5 b/share/man/man5/lindebugfs.5 index 8e385be7d743..4e823baff132 100644 --- a/share/man/man5/lindebugfs.5 +++ b/share/man/man5/lindebugfs.5 @@ -1,95 +1,95 @@ .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" Copyright (c) 2022, Jake Freeland .\" .\" 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. .Dd August 10, 2022 .Dt LINDEBUGFS 5 .Os .Sh NAME .Nm lindebugfs .Nd Linux file system for debugging .Sh SYNOPSIS .Bd -literal lindebugfs /sys/kernel/debug lindebugfs rw 0 0 .Ed .Sh DESCRIPTION The debug file system, or debugfs, makes process debugging easier by providing a simple API for data transfer between the kernel and user space. Debugfs is not a general-purpose file system and should not be used as a storage medium. Instead, developers can implement the debugfs interface in their code to generate debug information about their program at runtime. FreeBSD's .Nm uses the .Xr pseudofs 9 file system construction kit to model itself after Linux's debugfs. The .Nm API is intended for use with programs that take advantage of FreeBSD's LinuxKPI compatibility layer. .Pp When mounted, .Nm will populate with pseudo files from any running process that calls .Nm debugfs_create_file() . Since .Nm is a pseudo file system, file contents will be generated dynamically based on program provided file operations. The current .Nm implementation formally supports seq_file and simple_attr_file virtual file formats. .Sh EXAMPLES Load the .Nm kernel module: .Pp .Dl "kldload lindebugfs" .Pp Mount the .Nm file system on .Pa /sys/kernel/debug : .Pp .Dl "mount -t lindebugfs lindebugfs /sys/kernel/debug" .Sh SEE ALSO .Xr linprocfs 5 , .Xr linsysfs 5 , .Xr pseudofs 9 , .Xr linux 4 , -.Xr mount 1 +.Xr pseudofs 9 .Sh HISTORY The .Nm file system first appeared in .Fx 12.1 . .Sh AUTHORS .An -nosplit The initial implementation for .Nm was created by Matthew Macy. This manual page was written by Jake Freeland. diff --git a/share/man/man5/pf.conf.5 b/share/man/man5/pf.conf.5 index 3193c18760c8..7e2db95fd961 100644 --- a/share/man/man5/pf.conf.5 +++ b/share/man/man5/pf.conf.5 @@ -1,3424 +1,3424 @@ .\" $OpenBSD: pf.conf.5,v 1.406 2009/01/31 19:37:12 sobrado Exp $ .\" .\" Copyright (c) 2002, Daniel Hartmeier .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" .\" - Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" - Redistributions in binary form must reproduce the above .\" copyright notice, this list of conditions and the following .\" disclaimer in the documentation and/or other materials provided .\" with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS .\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER .\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN .\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" .Dd November 17, 2023 .Dt PF.CONF 5 .Os .Sh NAME .Nm pf.conf .Nd packet filter configuration file .Sh DESCRIPTION The .Xr pf 4 packet filter modifies, drops or passes packets according to rules or definitions specified in .Nm pf.conf . .Sh STATEMENT ORDER There are eight types of statements in .Nm pf.conf : .Bl -tag -width xxxx .It Cm Macros User-defined variables may be defined and used later, simplifying the configuration file. Macros must be defined before they are referenced in .Nm pf.conf . .It Cm Tables Tables provide a mechanism for increasing the performance and flexibility of rules with large numbers of source or destination addresses. .It Cm Options Options tune the behaviour of the packet filtering engine. .It Cm Ethernet Filtering Ethernet filtering provides rule-based blocking or passing of Ethernet packets. .It Cm Traffic Normalization Li (e.g. Em scrub ) Traffic normalization protects internal machines against inconsistencies in Internet protocols and implementations. .It Cm Queueing Queueing provides rule-based bandwidth control. .It Cm Translation Li (Various forms of NAT) Translation rules specify how addresses are to be mapped or redirected to other addresses. .It Cm Packet Filtering Packet filtering provides rule-based blocking or passing of packets. .El .Pp With the exception of .Cm macros and .Cm tables , the types of statements should be grouped and appear in .Nm pf.conf in the order shown above, as this matches the operation of the underlying packet filtering engine. By default .Xr pfctl 8 enforces this order (see .Ar set require-order below). .Pp Comments can be put anywhere in the file using a hash mark .Pq Sq # , and extend to the end of the current line. .Pp Additional configuration files can be included with the .Ic include keyword, for example: .Bd -literal -offset indent 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 .Ar pass , .Ar in , .Ar out ) . Macros are not expanded inside quotes. .Pp For example, .Bd -literal -offset indent ext_if = \&"kue0\&" all_ifs = \&"{\&" $ext_if lo0 \&"}\&" pass out on $ext_if from any to any pass in on $ext_if proto tcp from any to any port 25 .Ed .Sh TABLES Tables are named structures which can hold a collection of addresses and networks. Lookups against tables in .Xr pf 4 are relatively fast, making a single rule with tables much more efficient, in terms of processor usage and memory consumption, than a large number of rules which differ only in IP address (either created explicitly or automatically by rule expansion). .Pp Tables can be used as the source or destination of filter rules, .Ar scrub rules or translation rules such as .Ar nat or .Ar rdr (see below for details on the various rule types). Tables can also be used for the redirect address of .Ar nat and .Ar rdr rules and in the routing options of filter rules, but only for .Ar round-robin pools. .Pp Tables can be defined with any of the following .Xr pfctl 8 mechanisms. As with macros, reserved words may not be used as table names. .Bl -tag -width "manually" .It Ar manually Persistent tables can be manually created with the .Ar add or .Ar replace option of .Xr pfctl 8 , before or after the ruleset has been loaded. .It Pa pf.conf Table definitions can be placed directly in this file, and loaded at the same time as other rules are loaded, atomically. Table definitions inside .Nm pf.conf use the .Ar table statement, and are especially useful to define non-persistent tables. The contents of a pre-existing table defined without a list of addresses to initialize it is not altered when .Nm pf.conf is loaded. A table initialized with the empty list, .Li { } , will be cleared on load. .El .Pp Tables may be defined with the following attributes: .Bl -tag -width persist .It Ar persist The .Ar persist flag forces the kernel to keep the table even when no rules refer to it. If the flag is not set, the kernel will automatically remove the table when the last rule referring to it is flushed. .It Ar const The .Ar const flag prevents the user from altering the contents of the table once it has been created. Without that flag, .Xr pfctl 8 can be used to add or remove addresses from the table at any time, even when running with .Xr securelevel 7 = 2. .It Ar counters The .Ar counters flag enables per-address packet and byte counters which can be displayed with .Xr pfctl 8 . Note that this feature carries significant memory overhead for large tables. .El .Pp For example, .Bd -literal -offset indent table \*(Ltprivate\*(Gt const { 10/8, 172.16/12, 192.168/16 } table \*(Ltbadhosts\*(Gt persist block on fxp0 from { \*(Ltprivate\*(Gt, \*(Ltbadhosts\*(Gt } to any .Ed .Pp creates a table called private, to hold RFC 1918 private network blocks, and a table called badhosts, which is initially empty. A filter rule is set up to block all traffic coming from addresses listed in either table. The private table cannot have its contents changed and the badhosts table will exist even when no active filter rules reference it. Addresses may later be added to the badhosts table, so that traffic from these hosts can be blocked by using .Bd -literal -offset indent # pfctl -t badhosts -Tadd 204.92.77.111 .Ed .Pp A table can also be initialized with an address list specified in one or more external files, using the following syntax: .Bd -literal -offset indent table \*(Ltspam\*(Gt persist file \&"/etc/spammers\&" file \&"/etc/openrelays\&" block on fxp0 from \*(Ltspam\*(Gt to any .Ed .Pp The files .Pa /etc/spammers and .Pa /etc/openrelays list IP addresses, one per line. Any lines beginning with a # are treated as comments and ignored. In addition to being specified by IP address, hosts may also be specified by their hostname. When the resolver is called to add a hostname to a table, .Em all resulting IPv4 and IPv6 addresses are placed into the table. IP addresses can also be entered in a table by specifying a valid interface name, a valid interface group or the .Em self keyword, in which case all addresses assigned to the interface(s) will be added to the table. .Sh OPTIONS .Xr pf 4 may be tuned for various situations using the .Ar set command. .Bl -tag -width xxxx .It Ar set timeout .Pp .Bl -tag -width "src.track" -compact .It Ar interval Interval between purging expired states and fragments. .It Ar frag Seconds before an unassembled fragment is expired. .It Ar src.track Length of time to retain a source tracking entry after the last state expires. .El .Pp When a packet matches a stateful connection, the seconds to live for the connection will be updated to that of the .Ar proto.modifier 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. .Pp .Bl -tag -width xxxx -compact .It Ar tcp.first The state after the first packet. .It Ar tcp.opening The state before the destination host ever sends a packet. .It Ar tcp.established The fully established state. .It Ar tcp.closing The state after the first FIN has been sent. .It Ar tcp.finwait The state after both FINs have been exchanged and the connection is closed. Some hosts (notably web servers on Solaris) send TCP packets even after closing the connection. Increasing .Ar tcp.finwait (and possibly .Ar tcp.closing ) can prevent blocking of such packets. .It Ar tcp.closed The state after one endpoint sends an RST. .El .Pp SCTP timeout are handled similar to TCP, but with its own set of states: .Pp .Bl -tag -width xxxx -compact .It Ar sctp.first The state after the first packet. .It Ar sctp.opening The state before the destination host ever sends a packet. .It Ar sctp.established The fully established state. .It Ar sctp.closing The state after the first SHUTDOWN chunk has been sent. .It Ar sctp.closed The state after SHUTDOWN_ACK has been exchanged and the connection is closed. .El .Pp ICMP and UDP are handled in a fashion similar to TCP, but with a much more limited set of states: .Pp .Bl -tag -width xxxx -compact .It Ar udp.first The state after the first packet. .It Ar udp.single The state if the source host sends more than one packet but the destination host has never sent one back. .It Ar udp.multiple The state if both hosts have sent packets. .It Ar icmp.first The state after the first packet. .It Ar icmp.error The state after an ICMP error came back in response to an ICMP packet. .El .Pp Other protocols are handled similarly to UDP: .Pp .Bl -tag -width xxxx -compact .It Ar other.first .It Ar other.single .It Ar other.multiple .El .Pp Timeout values can be reduced adaptively as the number of state table entries grows. .Pp .Bl -tag -width xxxx -compact .It Ar adaptive.start When the number of state entries exceeds this value, adaptive scaling begins. All timeout values are scaled linearly with factor (adaptive.end - number of states) / (adaptive.end - adaptive.start). .It Ar adaptive.end When reaching this number of state entries, all timeout values become zero, effectively purging all state entries immediately. This value is used to define the scale factor, it should not actually be reached (set a lower state limit, see below). .El .Pp Adaptive timeouts are enabled by default, with an adaptive.start value equal to 60% of the state limit, and an adaptive.end value equal to 120% of the state limit. They can be disabled by setting both adaptive.start and adaptive.end to 0. .Pp The adaptive timeout values can be defined both globally and for each rule. When used on a per-rule basis, the values relate to the number of states created by the rule, otherwise to the total number of states. .Pp For example: .Bd -literal -offset indent set timeout tcp.first 120 set timeout tcp.established 86400 set timeout { adaptive.start 6000, adaptive.end 12000 } set limit states 10000 .Ed .Pp With 9000 state table entries, the timeout values are scaled to 50% (tcp.first 60, tcp.established 43200). .It Ar set loginterface Enable collection of packet and byte count statistics for the given interface or interface group. These statistics can be viewed using .Bd -literal -offset indent # pfctl -s info .Ed .Pp In this example .Xr pf 4 collects statistics on the interface named dc0: .Bd -literal -offset indent set loginterface dc0 .Ed .Pp One can disable the loginterface using: .Bd -literal -offset indent set loginterface none .Ed .It Ar set limit Sets hard limits on the memory pools used by the packet filter. See .Xr zone 9 for an explanation of memory pools. .Pp For example, .Bd -literal -offset indent set limit states 20000 .Ed .Pp sets the maximum number of entries in the memory pool used by state table entries (generated by .Ar pass rules which do not specify .Ar no state ) to 20000. Using .Bd -literal -offset indent set limit frags 20000 .Ed .Pp sets the maximum number of entries in the memory pool used for fragment reassembly (generated by the .Ar set reassemble option or .Ar scrub rules) to 20000. Using .Bd -literal -offset indent set limit src-nodes 2000 .Ed .Pp sets the maximum number of entries in the memory pool used for tracking source IP addresses (generated by the .Ar sticky-address and .Ar src.track options) to 2000. Using .Bd -literal -offset indent set limit tables 1000 set limit table-entries 100000 .Ed .Pp sets limits on the memory pools used by tables. The first limits the number of tables that can exist to 1000. The second limits the overall number of addresses that can be stored in tables to 100000. .Pp Various limits can be combined on a single line: .Bd -literal -offset indent set limit { states 20000, frags 20000, src-nodes 2000 } .Ed .It Ar set ruleset-optimization .Bl -tag -width xxxxxxxx -compact .It Ar none Disable the ruleset optimizer. .It Ar basic Enable basic ruleset optimization. This is the default behaviour. Basic ruleset optimization does four things to improve the performance of ruleset evaluations: .Pp .Bl -enum -compact .It remove duplicate rules .It remove rules that are a subset of another rule .It combine multiple rules into a table when advantageous .It re-order the rules to improve evaluation performance .El .Pp .It Ar profile Uses the currently loaded ruleset as a feedback profile to tailor the ordering of quick rules to actual network traffic. .El .Pp It is important to note that the ruleset optimizer will modify the ruleset to improve performance. A side effect of the ruleset modification is that per-rule accounting statistics will have different meanings than before. If per-rule accounting is important for billing purposes or whatnot, either the ruleset optimizer should not be used or a label field should be added to all of the accounting rules to act as optimization barriers. .Pp Optimization can also be set as a command-line argument to .Xr pfctl 8 , overriding the settings in .Nm . .It Ar set optimization Optimize state timeouts for one of the following network environments: .Pp .Bl -tag -width xxxx -compact .It Ar normal A normal network environment. Suitable for almost all networks. .It Ar high-latency A high-latency environment (such as a satellite connection). .It Ar satellite Alias for .Ar high-latency . .It Ar aggressive Aggressively expire connections. This can greatly reduce the memory usage of the firewall at the cost of dropping idle connections early. .It Ar conservative Extremely conservative settings. Avoid dropping legitimate connections at the expense of greater memory utilization (possibly much greater on a busy network) and slightly increased processor utilization. .El .Pp For example: .Bd -literal -offset indent set optimization aggressive .Ed .It Ar set reassemble yes | no Op Cm no-df The .Cm reassemble option is used to enable or disable the reassembly of fragmented packets, and can be set to .Cm yes or .Cm no . If .Cm no-df is also specified, fragments with the .Dq dont-fragment bit set are reassembled too, instead of being dropped; the reassembled packet will have the .Dq dont-fragment bit cleared. The default value is .Cm no . .Pp This option is ignored if there are pre-FreeBSD 14 .Cm scrub rules present. .It Ar set block-policy The .Ar block-policy option sets the default behaviour for the packet .Ar block action: .Pp .Bl -tag -width xxxxxxxx -compact .It Ar drop Packet is silently dropped. .It Ar return A TCP RST is returned for blocked TCP packets, an SCTP ABORT chunk is returned for blocked SCTP packets, an ICMP UNREACHABLE is returned for blocked UDP packets, and all other packets are silently dropped. .El .Pp For example: .Bd -literal -offset indent set block-policy return .Ed .It Ar set fail-policy The .Ar fail-policy option sets the behaviour of rules which should pass a packet but were unable to do so. This might happen when a nat or route-to rule uses an empty table as list of targets or if a rule fails to create state or source node. The following .Ar block actions are possible: .Pp .Bl -tag -width xxxxxxxx -compact .It Ar drop Incoming packet is silently dropped. .It Ar return Incoming packet is dropped and TCP RST is returned for TCP packets, an SCTP ABORT chunk is returned for blocked SCTP packets, an ICMP UNREACHABLE is returned for UDP packets, and no response is sent for other packets. .El .Pp For example: .Bd -literal -offset indent set fail-policy return .Ed .It Ar set state-policy The .Ar state-policy option sets the default behaviour for states: .Pp .Bl -tag -width group-bound -compact .It Ar if-bound States are bound to interface. .It Ar floating States can match packets on any interfaces (the default). .El .Pp For example: .Bd -literal -offset indent set state-policy if-bound .Ed .It Ar set syncookies never | always | adaptive When .Cm syncookies are active, pf will answer each incoming TCP SYN with a syncookie SYNACK, without allocating any resources. Upon reception of the client's ACK in response to the syncookie SYNACK, pf will evaluate the ruleset and create state if the ruleset permits it, complete the three way handshake with the target host and continue the connection with synproxy in place. This allows pf to be resilient against large synflood attacks which would run the state table against its limits otherwise. Due to the blind answers to every incoming SYN syncookies share the caveats of synproxy, namely seemingly accepting connections that will be dropped later on. .Pp .Bl -tag -width adaptive -compact .It Cm never pf will never send syncookie SYNACKs (the default). .It Cm always pf will always send syncookie SYNACKs. .It Cm adaptive pf will enable syncookie mode when a given percentage of the state table is used up by half-open TCP connections, as in, those that saw the initial SYN but didn't finish the three way handshake. The thresholds for entering and leaving syncookie mode can be specified using .Bd -literal -offset indent set syncookies adaptive (start 25%, end 12%) .Ed .El .It Ar set state-defaults The .Ar state-defaults option sets the state options for states created from rules without an explicit .Ar keep state . For example: .Bd -literal -offset indent set state-defaults no-sync .Ed .It Ar set hostid The 32-bit .Ar hostid identifies this firewall's state table entries to other firewalls in a .Xr pfsync 4 failover cluster. By default the hostid is set to a pseudo-random value, however it may be desirable to manually configure it, for example to more easily identify the source of state table entries. .Bd -literal -offset indent set hostid 1 .Ed .Pp The hostid may be specified in either decimal or hexadecimal. .It Ar set require-order By default .Xr pfctl 8 enforces an ordering of the statement types in the ruleset to: .Em options , .Em normalization , .Em queueing , .Em translation , .Em filtering . Setting this option to .Ar no disables this enforcement. There may be non-trivial and non-obvious implications to an out of order ruleset. Consider carefully before disabling the order enforcement. .It Ar set fingerprints Load fingerprints of known operating systems from the given filename. By default fingerprints of known operating systems are automatically loaded from .Xr pf.os 5 in .Pa /etc but can be overridden via this option. Setting this option may leave a small period of time where the fingerprints referenced by the currently active ruleset are inconsistent until the new ruleset finishes loading. .Pp For example: .Pp .Dl set fingerprints \&"/etc/pf.os.devel\&" .It Ar set skip on Aq Ar ifspec List interfaces for which packets should not be filtered. Packets passing in or out on such interfaces are passed as if pf was disabled, i.e. pf does not process them in any way. This can be useful on loopback and other virtual interfaces, when packet filtering is not desired and can have unexpected effects. For example: .Pp .Dl set skip on lo0 .It Ar set debug Set the debug .Ar level to one of the following: .Pp .Bl -tag -width xxxxxxxxxxxx -compact .It Ar none Don't generate debug messages. .It Ar urgent Generate debug messages only for serious errors. .It Ar misc Generate debug messages for various errors. .It Ar loud Generate debug messages for common conditions. .El .It Ar set keepcounters Preserve rule counters across rule updates. Usually rule counters are reset to zero on every update of the ruleset. With .Ar keepcounters set pf will attempt to find matching rules between old and new rulesets and preserve the rule counters. .El .Sh ETHERNET FILTERING .Xr pf 4 has the ability to .Ar block and .Ar pass packets based on attributes of their Ethernet (layer 2) header. .Pp For each packet processed by the packet filter, the filter rules are evaluated in sequential order, from first to last. The last matching rule decides what action is taken. If no rule matches the packet, the default action is to pass the packet. .Pp The following actions can be used in the filter: .Bl -tag -width xxxx .It Ar block The packet is blocked. Unlike for layer 3 traffic the packet is always silently dropped. .It Ar pass The packet is passed; no state is created for layer 2 traffic. .El .Sh PARAMETERS The rule parameters specify the packets to which a rule applies. A packet always comes in on, or goes out through, one interface. Most parameters are optional. If a parameter is specified, the rule only applies to packets with matching attributes. Certain parameters can be expressed as lists, in which case .Xr pfctl 8 generates all needed rule combinations. .Bl -tag -width xxxx .It Ar in No or Ar out This rule applies to incoming or outgoing packets. If neither .Ar in nor .Ar out are specified, the rule will match packets in both directions. .It Ar quick If a packet matches a rule which has the .Ar quick option set, this rule is considered the last matching rule, and evaluation of subsequent rules is skipped. .It Ar on Aq Ar ifspec This rule applies only to packets coming in on, or going out through, this particular interface or interface group. For more information on interface groups, see the .Ic group keyword in .Xr ifconfig 8 . .It Ar bridge-to Aq interface Packets matching this rule will be sent out of the specified interface without further processing. .It Ar proto Aq Ar protocol This rule applies only to packets of this protocol. Note that Ethernet protocol numbers are different from those used in .Xr ip 4 and .Xr ip6 4 . .It Xo .Ar from Aq Ar source .Ar to Aq Ar dest .Xc This rule applies only to packets with the specified source and destination MAC addresses. .It Xo Ar queue Aq Ar queue .Xc Packets matching this rule will be assigned to the specified queue. See .Sx QUEUEING for setup details. .Pp .It Ar tag Aq Ar string Packets matching this rule will be tagged with the specified string. The tag acts as an internal marker that can be used to identify these packets later on. This can be used, for example, to provide trust between interfaces and to determine if packets have been processed by translation rules. Tags are .Qq sticky , meaning that the packet will be tagged even if the rule is not the last matching rule. Further matching rules can replace the tag with a new one but will not remove a previously applied tag. A packet is only ever assigned one tag at a time. .It Ar tagged Aq Ar string Used to specify that packets must already be tagged with the given tag in order to match the rule. Inverse tag matching can also be done by specifying the ! operator before the tagged keyword. .El .Sh TRAFFIC NORMALIZATION Traffic normalization is a broad umbrella term for aspects of the packet filter which deal with verifying packets, packet fragments, spoofed traffic, and other irregularities. .Ss Scrub Scrub involves sanitising packet content in such a way that there are no ambiguities in packet interpretation on the receiving side. It is invoked with the .Cm scrub option, added to filter rules. .Pp Parameters are specified enclosed in parentheses. At least one of the following parameters must be specified: .Bl -tag -width xxxx .It Ar no-df Clears the .Ar dont-fragment bit from a matching IP packet. Some operating systems are known to generate fragmented packets with the .Ar dont-fragment bit set. This is particularly true with NFS. .Ar Scrub will drop such fragmented .Ar dont-fragment packets unless .Ar no-df is specified. .Pp Unfortunately some operating systems also generate their .Ar dont-fragment packets with a zero IP identification field. Clearing the .Ar dont-fragment bit on packets with a zero IP ID may cause deleterious results if an upstream router later fragments the packet. Using the .Ar random-id modifier (see below) is recommended in combination with the .Ar no-df modifier to ensure unique IP identifiers. .It Ar min-ttl Aq Ar number Enforces a minimum TTL for matching IP packets. .It Ar max-mss Aq Ar number Enforces a maximum MSS for matching TCP packets. .It Xo Ar set-tos Aq Ar string .No \*(Ba Aq Ar number .Xc Enforces a .Em TOS for matching IP packets. .Em TOS may be given as one of .Ar critical , .Ar inetcontrol , .Ar lowdelay , .Ar netcontrol , .Ar throughput , .Ar reliability , or one of the DiffServ Code Points: .Ar ef , .Ar va , .Ar af11 No ... Ar af43 , .Ar cs0 No ... Ar cs7 ; or as either hex or decimal. .It Ar random-id Replaces the IP identification field with random values to compensate for predictable values generated by many hosts. This option only applies to packets that are not fragmented after the optional fragment reassembly. .It Ar reassemble tcp Statefully normalizes TCP connections. .Ar reassemble tcp performs the following normalizations: .Pp .Bl -tag -width timeout -compact .It ttl Neither side of the connection is allowed to reduce their IP TTL. An attacker may send a packet such that it reaches the firewall, affects the firewall state, and expires before reaching the destination host. .Ar reassemble tcp will raise the TTL of all packets back up to the highest value seen on the connection. .It timestamp modulation Modern TCP stacks will send a timestamp on every TCP packet and echo the other endpoint's timestamp back to them. Many operating systems will merely start the timestamp at zero when first booted, and increment it several times a second. The uptime of the host can be deduced by reading the timestamp and multiplying by a constant. Also observing several different timestamps can be used to count hosts behind a NAT device. And spoofing TCP packets into a connection requires knowing or guessing valid timestamps. Timestamps merely need to be monotonically increasing and not derived off a guessable base time. .Ar reassemble tcp will cause .Ar scrub to modulate the TCP timestamps with a random number. .It extended PAWS checks There is a problem with TCP on long fat pipes, in that a packet might get delayed for longer than it takes the connection to wrap its 32-bit sequence space. In such an occurrence, the old packet would be indistinguishable from a new packet and would be accepted as such. The solution to this is called PAWS: Protection Against Wrapped Sequence numbers. It protects against it by making sure the timestamp on each packet does not go backwards. .Ar reassemble tcp also makes sure the timestamp on the packet does not go forward more than the RFC allows. By doing this, .Xr pf 4 artificially extends the security of TCP sequence numbers by 10 to 18 bits when the host uses appropriately randomized timestamps, since a blind attacker would have to guess the timestamp as well. .El .El .Pp For example, .Bd -literal -offset indent match in all scrub (no-df random-id max-mss 1440) .Ed .Ss Scrub ruleset (pre-FreeBSD 14) In order to maintain compatibility with older releases of FreeBSD .Ar scrub rules can also be specified in their own ruleset. In such case they are invoked with the .Ar scrub directive. If there are such rules present they determine packet reassembly behaviour. When no such rules are present the option .Ar set reassembly takes precedence. The .Ar scrub rules can take all parameters specified above for a .Ar scrub option of filter rules and 2 more parameters controlling fragment reassembly: .Bl -tag -width xxxx .It Ar fragment reassemble Using .Ar scrub rules, fragments can be reassembled by normalization. In this case, fragments are buffered until they form a complete packet, and only the completed packet is passed on to the filter. The advantage is that filter rules have to deal only with complete packets, and can ignore fragments. The drawback of caching fragments is the additional memory cost. This is the default behaviour unless no fragment reassemble is specified. .It Ar no fragment reassemble Do not reassemble fragments. .El .Pp For example, .Bd -literal -offset indent scrub in on $ext_if all fragment reassemble .Ed .Pp The .Ar no option prefixed to a scrub rule causes matching packets to remain unscrubbed, much in the same way as .Ar drop quick works in the packet filter (see below). This mechanism should be used when it is necessary to exclude specific packets from broader scrub rules. .Pp .Ar scrub rules in the .Ar scrub ruleset are evaluated for every packet before stateful filtering. This means excessive usage of them will cause performance penalty. .Ar scrub reassemble tcp rules must not have the direction (in/out) specified. .Sh QUEUEING with ALTQ The ALTQ system is currently not available in the GENERIC kernel nor as loadable modules. In order to use the herein after called queueing options one has to use a custom built kernel. Please refer to .Xr altq 4 to learn about the related kernel options. .Pp Packets can be assigned to queues for the purpose of bandwidth control. At least two declarations are required to configure queues, and later any packet filtering rule can reference the defined queues by name. During the filtering component of .Nm pf.conf , the last referenced .Ar queue name is where any packets from .Ar pass rules will be queued, while for .Ar block rules it specifies where any resulting ICMP or TCP RST packets should be queued. The .Ar scheduler defines the algorithm used to decide which packets get delayed, dropped, or sent out immediately. There are three .Ar schedulers currently supported. .Bl -tag -width xxxx .It Ar cbq Class Based Queueing. .Ar Queues attached to an interface build a tree, thus each .Ar queue can have further child .Ar queues . Each queue can have a .Ar priority and a .Ar bandwidth assigned. .Ar Priority mainly controls the time packets take to get sent out, while .Ar bandwidth has primarily effects on throughput. .Ar cbq achieves both partitioning and sharing of link bandwidth by hierarchically structured classes. Each class has its own .Ar queue and is assigned its share of .Ar bandwidth . A child class can borrow bandwidth from its parent class as long as excess bandwidth is available (see the option .Ar borrow , below). .It Ar priq Priority Queueing. .Ar Queues are flat attached to the interface, thus, .Ar queues cannot have further child .Ar queues . Each .Ar queue has a unique .Ar priority assigned, ranging from 0 to 15. Packets in the .Ar queue with the highest .Ar priority are processed first. .It Ar hfsc Hierarchical Fair Service Curve. .Ar Queues attached to an interface build a tree, thus each .Ar queue can have further child .Ar queues . Each queue can have a .Ar priority and a .Ar bandwidth assigned. .Ar Priority mainly controls the time packets take to get sent out, while .Ar bandwidth primarily affects throughput. .Ar hfsc supports both link-sharing and guaranteed real-time services. It employs a service curve based QoS model, and its unique feature is an ability to decouple .Ar delay and .Ar bandwidth allocation. .El .Pp The interfaces on which queueing should be activated are declared using the .Ar altq on declaration. .Ar altq on has the following keywords: .Bl -tag -width xxxx .It Aq Ar interface Queueing is enabled on the named interface. .It Aq Ar scheduler Specifies which queueing scheduler to use. Currently supported values are .Ar cbq for Class Based Queueing, .Ar priq for Priority Queueing and .Ar hfsc for the Hierarchical Fair Service Curve scheduler. .It Ar bandwidth Aq Ar bw The maximum bitrate for all queues on an interface may be specified using the .Ar bandwidth keyword. The value can be specified as an absolute value or as a percentage of the interface bandwidth. When using an absolute value, the suffixes .Ar b , .Ar Kb , .Ar Mb , and .Ar Gb are used to represent bits, kilobits, megabits, and gigabits per second, respectively. The value must not exceed the interface bandwidth. If .Ar bandwidth is not specified, the interface bandwidth is used (but take note that some interfaces do not know their bandwidth, or can adapt their bandwidth rates). .It Ar qlimit Aq Ar limit The maximum number of packets held in the queue. The default is 50. .It Ar tbrsize Aq Ar size Adjusts the size, in bytes, of the token bucket regulator. If not specified, heuristics based on the interface bandwidth are used to determine the size. .It Ar queue Aq Ar list Defines a list of subqueues to create on an interface. .El .Pp In the following example, the interface dc0 should queue up to 5Mbps in four second-level queues using Class Based Queueing. Those four queues will be shown in a later example. .Bd -literal -offset indent altq on dc0 cbq bandwidth 5Mb queue { std, http, mail, ssh } .Ed .Pp Once interfaces are activated for queueing using the .Ar altq directive, a sequence of .Ar queue directives may be defined. The name associated with a .Ar queue must match a queue defined in the .Ar altq directive (e.g. mail), or, except for the .Ar priq .Ar scheduler , in a parent .Ar queue declaration. The following keywords can be used: .Bl -tag -width xxxx .It Ar on Aq Ar interface Specifies the interface the queue operates on. If not given, it operates on all matching interfaces. .It Ar bandwidth Aq Ar bw Specifies the maximum bitrate to be processed by the queue. This value must not exceed the value of the parent .Ar queue and can be specified as an absolute value or a percentage of the parent queue's bandwidth. If not specified, defaults to 100% of the parent queue's bandwidth. The .Ar priq scheduler does not support bandwidth specification. .It Ar priority Aq Ar level Between queues a priority level can be set. For .Ar cbq and .Ar hfsc , the range is 0 to 7 and for .Ar priq , the range is 0 to 15. The default for all is 1. .Ar Priq queues with a higher priority are always served first. .Ar Cbq and .Ar Hfsc queues with a higher priority are preferred in the case of overload. .It Ar qlimit Aq Ar limit The maximum number of packets held in the queue. The default is 50. .El .Pp The .Ar scheduler can get additional parameters with .Xo Aq Ar scheduler .Pf ( Aq Ar parameters ) . .Xc Parameters are as follows: .Bl -tag -width Fl .It Ar default Packets not matched by another queue are assigned to this one. Exactly one default queue is required. .It Ar red Enable RED (Random Early Detection) on this queue. RED drops packets with a probability proportional to the average queue length. .It Ar rio Enables RIO on this queue. RIO is RED with IN/OUT, thus running RED two times more than RIO would achieve the same effect. RIO is currently not supported in the GENERIC kernel. .It Ar ecn Enables ECN (Explicit Congestion Notification) on this queue. ECN implies RED. .El .Pp The .Ar cbq .Ar scheduler supports an additional option: .Bl -tag -width Fl .It Ar borrow The queue can borrow bandwidth from the parent. .El .Pp The .Ar hfsc .Ar scheduler supports some additional options: .Bl -tag -width Fl .It Ar realtime Aq Ar sc The minimum required bandwidth for the queue. .It Ar upperlimit Aq Ar sc The maximum allowed bandwidth for the queue. .It Ar linkshare Aq Ar sc The bandwidth share of a backlogged queue. .El .Pp .Aq Ar sc is an acronym for .Ar service curve . .Pp The format for service curve specifications is .Ar ( m1 , d , m2 ) . .Ar m2 controls the bandwidth assigned to the queue. .Ar m1 and .Ar d are optional and can be used to control the initial bandwidth assignment. For the first .Ar d milliseconds the queue gets the bandwidth given as .Ar m1 , afterwards the value given in .Ar m2 . .Pp Furthermore, with .Ar cbq and .Ar hfsc , child queues can be specified as in an .Ar altq declaration, thus building a tree of queues using a part of their parent's bandwidth. .Pp Packets can be assigned to queues based on filter rules by using the .Ar queue keyword. Normally only one .Ar queue is specified; when a second one is specified it will instead be used for packets which have a .Em TOS of .Em lowdelay and for TCP ACKs with no data payload. .Pp To continue the previous example, the examples below would specify the four referenced queues, plus a few child queues. Interactive .Xr ssh 1 sessions get priority over bulk transfers like .Xr scp 1 and .Xr sftp 1 . The queues may then be referenced by filtering rules (see .Sx PACKET FILTERING below). .Bd -literal queue std bandwidth 10% cbq(default) queue http bandwidth 60% priority 2 cbq(borrow red) \e { employees, developers } queue developers bandwidth 75% cbq(borrow) queue employees bandwidth 15% queue mail bandwidth 10% priority 0 cbq(borrow ecn) queue ssh bandwidth 20% cbq(borrow) { ssh_interactive, ssh_bulk } queue ssh_interactive bandwidth 50% priority 7 cbq(borrow) queue ssh_bulk bandwidth 50% priority 0 cbq(borrow) block return out on dc0 inet all queue std pass out on dc0 inet proto tcp from $developerhosts to any port 80 \e queue developers pass out on dc0 inet proto tcp from $employeehosts to any port 80 \e queue employees pass out on dc0 inet proto tcp from any to any port 22 \e queue(ssh_bulk, ssh_interactive) pass out on dc0 inet proto tcp from any to any port 25 \e queue mail .Ed .Sh QUEUEING with dummynet Queueing can also be done with .Xr dummynet 4 . Queues and pipes can be created with .Xr dnctl 8 . .Pp Packets can be assigned to queues and pipes using .Ar dnqueue and .Ar dnpipe respectively. .Pp Both .Ar dnqueue and .Ar dnpipe take either a single pipe or queue number or two numbers as arguments. The first pipe or queue number will be used to shape the traffic in the rule direction, the second will be used to shape the traffic in the reverse direction. If the rule does not specify a direction the first packet to create state will be shaped according to the first number, and the response traffic according to the second. .Pp If the .Xr dummynet 4 module is not loaded any traffic sent into a queue or pipe will be dropped. .Sh TRANSLATION Translation rules modify either the source or destination address of the packets associated with a stateful connection. A stateful connection is automatically created to track packets matching such a rule as long as they are not blocked by the filtering section of .Nm pf.conf . The translation engine modifies the specified address and/or port in the packet, recalculates IP, TCP and UDP checksums as necessary, and passes it to the packet filter for evaluation. .Pp Since translation occurs before filtering the filter engine will see packets as they look after any addresses and ports have been translated. Filter rules will therefore have to filter based on the translated address and port number. Packets that match a translation rule are only automatically passed if the .Ar pass modifier is given, otherwise they are still subject to .Ar block and .Ar pass rules. .Pp The state entry created permits .Xr pf 4 to keep track of the original address for traffic associated with that state and correctly direct return traffic for that connection. .Pp Various types of translation are possible with pf: .Bl -tag -width xxxx .It Ar binat A .Ar binat rule specifies a bidirectional mapping between an external IP netblock and an internal IP netblock. .It Ar nat A .Ar nat rule specifies that IP addresses are to be changed as the packet traverses the given interface. This technique allows one or more IP addresses on the translating host to support network traffic for a larger range of machines on an "inside" network. Although in theory any IP address can be used on the inside, it is strongly recommended that one of the address ranges defined by RFC 1918 be used. These netblocks are: .Bd -literal 10.0.0.0 - 10.255.255.255 (all of net 10, i.e., 10/8) 172.16.0.0 - 172.31.255.255 (i.e., 172.16/12) 192.168.0.0 - 192.168.255.255 (i.e., 192.168/16) .Ed .It Pa rdr The packet is redirected to another destination and possibly a different port. .Ar rdr rules can optionally specify port ranges instead of single ports. rdr ... port 2000:2999 -\*(Gt ... port 4000 redirects ports 2000 to 2999 (inclusive) to port 4000. rdr ... port 2000:2999 -\*(Gt ... port 4000:* redirects port 2000 to 4000, 2001 to 4001, ..., 2999 to 4999. .El .Pp In addition to modifying the address, some translation rules may modify source or destination ports for .Xr tcp 4 or .Xr udp 4 connections; implicitly in the case of .Ar nat rules and explicitly in the case of .Ar rdr rules. Port numbers are never translated with a .Ar binat rule. .Pp Evaluation order of the translation rules is dependent on the type of the translation rules and of the direction of a packet. .Ar binat rules are always evaluated first. Then either the .Ar rdr rules are evaluated on an inbound packet or the .Ar nat rules on an outbound packet. Rules of the same type are evaluated in the same order in which they appear in the ruleset. The first matching rule decides what action is taken. .Pp The .Ar no option prefixed to a translation rule causes packets to remain untranslated, much in the same way as .Ar drop quick works in the packet filter (see below). If no rule matches the packet it is passed to the filter engine unmodified. .Pp Translation rules apply only to packets that pass through the specified interface, and if no interface is specified, translation is applied to packets on all interfaces. For instance, redirecting port 80 on an external interface to an internal web server will only work for connections originating from the outside. Connections to the address of the external interface from local hosts will not be redirected, since such packets do not actually pass through the external interface. Redirections cannot reflect packets back through the interface they arrive on, they can only be redirected to hosts connected to different interfaces or to the firewall itself. .Pp Note that redirecting external incoming connections to the loopback address, as in .Bd -literal -offset indent rdr on ne3 inet proto tcp to port smtp -\*(Gt 127.0.0.1 port spamd .Ed .Pp will effectively allow an external host to connect to daemons bound solely to the loopback address, circumventing the traditional blocking of such connections on a real interface. Unless this effect is desired, any of the local non-loopback addresses should be used as redirection target instead, which allows external connections only to daemons bound to this address or not bound to any address. .Pp See .Sx TRANSLATION EXAMPLES below. .Sh PACKET FILTERING .Xr pf 4 has the ability to .Ar block , .Ar pass and .Ar match packets based on attributes of their layer 3 (see .Xr ip 4 and .Xr ip6 4 ) and layer 4 (see .Xr icmp 4 , .Xr icmp6 4 , .Xr tcp 4 , .Xr sctp 4 , .Xr udp 4 ) headers. In addition, packets may also be assigned to queues for the purpose of bandwidth control. .Pp For each packet processed by the packet filter, the filter rules are evaluated in sequential order, from first to last. For .Ar block and .Ar pass , the last matching rule decides what action is taken. For .Ar match , rules are evaluated every time they match; the pass/block state of a packet remains unchanged. If no rule matches the packet, the default action is to pass the packet. .Pp The following actions can be used in the filter: .Bl -tag -width xxxx .It Ar block The packet is blocked. There are a number of ways in which a .Ar block rule can behave when blocking a packet. The default behaviour is to .Ar drop packets silently, however this can be overridden or made explicit either globally, by setting the .Ar block-policy option, or on a per-rule basis with one of the following options: .Pp .Bl -tag -width xxxx -compact .It Ar drop The packet is silently dropped. .It Ar return-rst This applies only to .Xr tcp 4 packets, and issues a TCP RST which closes the connection. .It Ar return-icmp .It Ar return-icmp6 This causes ICMP messages to be returned for packets which match the rule. By default this is an ICMP UNREACHABLE message, however this can be overridden by specifying a message as a code or number. .It Ar return This causes a TCP RST to be returned for .Xr tcp 4 packets, an SCTP ABORT for SCTP and an ICMP UNREACHABLE for UDP and other packets. .El .Pp Options returning ICMP packets currently have no effect if .Xr pf 4 operates on a .Xr if_bridge 4 , as the code to support this feature has not yet been implemented. .Pp The simplest mechanism to block everything by default and only pass packets that match explicit rules is specify a first filter rule of: .Bd -literal -offset indent block all .Ed .It Ar match The packet is matched. This mechanism is used to provide fine grained filtering without altering the block/pass state of a packet. .Ar match rules differ from .Ar block and .Ar pass rules in that parameters are set for every rule a packet matches, not only on the last matching rule. For the following parameters, this means that the parameter effectively becomes "sticky" until explicitly overridden: .Ar queue , .Ar dnpipe , .Ar dnqueue , .Ar rtable , .Ar scrub . .It Ar pass The packet is passed; state is created unless the .Ar no state option is specified. .El .Pp By default .Xr pf 4 filters packets statefully; the first time a packet matches a .Ar pass rule, a state entry is created; for subsequent packets the filter checks whether the packet matches any state. If it does, the packet is passed without evaluation of any rules. After the connection is closed or times out, the state entry is automatically removed. .Pp This has several advantages. For TCP connections, comparing a packet to a state involves checking its sequence numbers, as well as TCP timestamps if a .Ar scrub reassemble tcp rule applies to the connection. If these values are outside the narrow windows of expected values, the packet is dropped. This prevents spoofing attacks, such as when an attacker sends packets with a fake source address/port but does not know the connection's sequence numbers. Similarly, .Xr pf 4 knows how to match ICMP replies to states. For example, .Bd -literal -offset indent pass out inet proto icmp all icmp-type echoreq .Ed .Pp allows echo requests (such as those created by .Xr ping 8 ) out statefully, and matches incoming echo replies correctly to states. .Pp Also, looking up states is usually faster than evaluating rules. If there are 50 rules, all of them are evaluated sequentially in O(n). Even with 50000 states, only 16 comparisons are needed to match a state, since states are stored in a binary search tree that allows searches in O(log2 n). .Pp Furthermore, correct handling of ICMP error messages is critical to many protocols, particularly TCP. .Xr pf 4 matches ICMP error messages to the correct connection, checks them against connection parameters, and passes them if appropriate. For example if an ICMP source quench message referring to a stateful TCP connection arrives, it will be matched to the state and get passed. .Pp Finally, state tracking is required for .Ar nat , binat No and Ar rdr rules, in order to track address and port translations and reverse the translation on returning packets. .Pp .Xr pf 4 will also create state for other protocols which are effectively stateless by nature. UDP packets are matched to states using only host addresses and ports, and other protocols are matched to states using only the host addresses. .Pp If stateless filtering of individual packets is desired, the .Ar no state keyword can be used to specify that state will not be created if this is the last matching rule. A number of parameters can also be set to affect how .Xr pf 4 handles state tracking. See .Sx STATEFUL TRACKING OPTIONS below for further details. .Sh PARAMETERS The rule parameters specify the packets to which a rule applies. A packet always comes in on, or goes out through, one interface. Most parameters are optional. If a parameter is specified, the rule only applies to packets with matching attributes. Certain parameters can be expressed as lists, in which case .Xr pfctl 8 generates all needed rule combinations. .Bl -tag -width xxxx .It Ar in No or Ar out This rule applies to incoming or outgoing packets. If neither .Ar in nor .Ar out are specified, the rule will match packets in both directions. .It Ar log In addition to the action specified, a log message is generated. Only the packet that establishes the state is logged, unless the .Ar no state option is specified. The logged packets are sent to a .Xr pflog 4 interface, by default .Ar pflog0 . This interface is monitored by the .Xr pflogd 8 logging daemon, which dumps the logged packets to the file .Pa /var/log/pflog in .Xr pcap 3 binary format. .It Ar log (all) Used to force logging of all packets for a connection. This is not necessary when .Ar no state is explicitly specified. As with .Ar log , packets are logged to .Xr pflog 4 . .It Ar log (user) Logs the .Ux user ID of the user that owns the socket and the PID of the process that has the socket open where the packet is sourced from or destined to (depending on which socket is local). This is in addition to the normal information logged. .Pp Only the first packet logged via .Ar log (all, user) will have the user credentials logged when using stateful matching. .It Ar log (to Aq Ar interface ) Send logs to the specified .Xr pflog 4 interface instead of .Ar pflog0 . .It Ar quick If a packet matches a rule which has the .Ar quick option set, this rule is considered the last matching rule, and evaluation of subsequent rules is skipped. .It Ar on Aq Ar interface This rule applies only to packets coming in on, or going out through, this particular interface or interface group. For more information on interface groups, see the .Ic group keyword in .Xr ifconfig 8 . .It Aq Ar af This rule applies only to packets of this address family. Supported values are .Ar inet and .Ar inet6 . .It Ar proto Aq Ar protocol This rule applies only to packets of this protocol. Common protocols are .Xr icmp 4 , .Xr icmp6 4 , .Xr tcp 4 , .Xr sctp 4 , and .Xr udp 4 . For a list of all the protocol name to number mappings used by .Xr pfctl 8 , see the file .Pa /etc/protocols . .It Xo .Ar from Aq Ar source .Ar port Aq Ar source .Ar os Aq Ar source .Ar to Aq Ar dest .Ar port Aq Ar dest .Xc This rule applies only to packets with the specified source and destination addresses and ports. .Pp Addresses can be specified in CIDR notation (matching netblocks), as symbolic host names, interface names or interface group names, or as any of the following keywords: .Pp .Bl -tag -width xxxxxxxxxxxxxx -compact .It Ar any Any address. .It Ar no-route Any address which is not currently routable. .It Ar urpf-failed Any source address that fails a unicast reverse path forwarding (URPF) check, i.e. packets coming in on an interface other than that which holds the route back to the packet's source address. .It Aq Ar table Any address that matches the given table. .El .Pp Ranges of addresses are specified by using the .Sq - operator. For instance: .Dq 10.1.1.10 - 10.1.1.12 means all addresses from 10.1.1.10 to 10.1.1.12, hence addresses 10.1.1.10, 10.1.1.11, and 10.1.1.12. .Pp Interface names and interface group names can have modifiers appended: .Pp .Bl -tag -width xxxxxxxxxxxx -compact .It Ar :network Translates to the network(s) attached to the interface. .It Ar :broadcast Translates to the interface's broadcast address(es). .It Ar :peer Translates to the point-to-point interface's peer address(es). .It Ar :0 Do not include interface aliases. .El .Pp Host names may also have the .Ar :0 option appended to restrict the name resolution to the first of each v4 and non-link-local v6 address found. .Pp Host name resolution and interface to address translation are done at ruleset load-time. When the address of an interface (or host name) changes (under DHCP or PPP, for instance), the ruleset must be reloaded for the change to be reflected in the kernel. Surrounding the interface name (and optional modifiers) in parentheses changes this behaviour. When the interface name is surrounded by parentheses, the rule is automatically updated whenever the interface changes its address. The ruleset does not need to be reloaded. This is especially useful with .Ar nat . .Pp Ports can be specified either by number or by name. For example, port 80 can be specified as .Em www . For a list of all port name to number mappings used by .Xr pfctl 8 , see the file .Pa /etc/services . .Pp Ports and ranges of ports are specified by using these operators: .Bd -literal -offset indent = (equal) != (unequal) \*(Lt (less than) \*(Le (less than or equal) \*(Gt (greater than) \*(Ge (greater than or equal) : (range including boundaries) \*(Gt\*(Lt (range excluding boundaries) \*(Lt\*(Gt (except range) .Ed .Pp .Sq \*(Gt\*(Lt , .Sq \*(Lt\*(Gt and .Sq \&: are binary operators (they take two arguments). For instance: .Bl -tag -width Fl .It Ar port 2000:2004 means .Sq all ports \*(Ge 2000 and \*(Le 2004 , hence ports 2000, 2001, 2002, 2003 and 2004. .It Ar port 2000 \*(Gt\*(Lt 2004 means .Sq all ports \*(Gt 2000 and \*(Lt 2004 , hence ports 2001, 2002 and 2003. .It Ar port 2000 \*(Lt\*(Gt 2004 means .Sq all ports \*(Lt 2000 or \*(Gt 2004 , hence ports 1-1999 and 2005-65535. .El .Pp The operating system of the source host can be specified in the case of TCP rules with the .Ar OS modifier. See the .Sx OPERATING SYSTEM FINGERPRINTING section for more information. .Pp The host, port and OS specifications are optional, as in the following examples: .Bd -literal -offset indent pass in all pass in from any to any pass in proto tcp from any port \*(Le 1024 to any pass in proto tcp from any to any port 25 pass in proto tcp from 10.0.0.0/8 port \*(Gt 1024 \e to ! 10.1.2.3 port != ssh pass in proto tcp from any os "OpenBSD" .Ed .It Ar all This is equivalent to "from any to any". .It Ar group Aq Ar group Similar to .Ar user , this rule only applies to packets of sockets owned by the specified group. .It Ar user Aq Ar user This rule only applies to packets of sockets owned by the specified user. For outgoing connections initiated from the firewall, this is the user that opened the connection. For incoming connections to the firewall itself, this is the user that listens on the destination port. For forwarded connections, where the firewall is not a connection endpoint, the user and group are .Em unknown . .Pp All packets, both outgoing and incoming, of one connection are associated with the same user and group. Only TCP and UDP packets can be associated with users; for other protocols these parameters are ignored. .Pp User and group refer to the effective (as opposed to the real) IDs, in case the socket is created by a setuid/setgid process. User and group IDs are stored when a socket is created; when a process creates a listening socket as root (for instance, by binding to a privileged port) and subsequently changes to another user ID (to drop privileges), the credentials will remain root. .Pp User and group IDs can be specified as either numbers or names. The syntax is similar to the one for ports. The value .Em unknown matches packets of forwarded connections. .Em unknown can only be used with the operators .Cm = and .Cm != . Other constructs like .Cm user \*(Ge unknown are invalid. Forwarded packets with unknown user and group ID match only rules that explicitly compare against .Em unknown with the operators .Cm = or .Cm != . For instance .Cm user \*(Ge 0 does not match forwarded packets. The following example allows only selected users to open outgoing connections: .Bd -literal -offset indent block out proto { tcp, udp } all pass out proto { tcp, udp } all user { \*(Lt 1000, dhartmei } .Ed .It Xo Ar flags Aq Ar a .Pf / Ns Aq Ar b .No \*(Ba / Ns Aq Ar b .No \*(Ba any .Xc This rule only applies to TCP packets that have the flags .Aq Ar a set out of set .Aq Ar b . Flags not specified in .Aq Ar b are ignored. For stateful connections, the default is .Ar flags S/SA . To indicate that flags should not be checked at all, specify .Ar flags any . The flags are: (F)IN, (S)YN, (R)ST, (P)USH, (A)CK, (U)RG, (E)CE, and C(W)R. .Bl -tag -width Fl .It Ar flags S/S Flag SYN is set. The other flags are ignored. .It Ar flags S/SA This is the default setting for stateful connections. Out of SYN and ACK, exactly SYN may be set. SYN, SYN+PSH and SYN+RST match, but SYN+ACK, ACK and ACK+RST do not. This is more restrictive than the previous example. .It Ar flags /SFRA If the first set is not specified, it defaults to none. All of SYN, FIN, RST and ACK must be unset. .El .Pp Because .Ar flags S/SA is applied by default (unless .Ar no state is specified), only the initial SYN packet of a TCP handshake will create a state for a TCP connection. It is possible to be less restrictive, and allow state creation from intermediate .Pq non-SYN packets, by specifying .Ar flags any . This will cause .Xr pf 4 to synchronize to existing connections, for instance if one flushes the state table. However, states created from such intermediate packets may be missing connection details such as the TCP window scaling factor. States which modify the packet flow, such as those affected by .Ar nat , binat No or Ar rdr rules, .Ar modulate No or Ar synproxy state options, or scrubbed with .Ar reassemble tcp will also not be recoverable from intermediate packets. Such connections will stall and time out. .It Xo Ar icmp-type Aq Ar type .Ar code Aq Ar code .Xc .It Xo Ar icmp6-type Aq Ar type .Ar code Aq Ar code .Xc This rule only applies to ICMP or ICMPv6 packets with the specified type and code. Text names for ICMP types and codes are listed in .Xr icmp 4 and .Xr icmp6 4 . This parameter is only valid for rules that cover protocols ICMP or ICMP6. The protocol and the ICMP type indicator .Po .Ar icmp-type or .Ar icmp6-type .Pc must match. .It Xo Ar tos Aq Ar string .No \*(Ba Aq Ar number .Xc This rule applies to packets with the specified .Em TOS bits set. .Em TOS may be given as one of .Ar critical , .Ar inetcontrol , .Ar lowdelay , .Ar netcontrol , .Ar throughput , .Ar reliability , or one of the DiffServ Code Points: .Ar ef , .Ar va , .Ar af11 No ... Ar af43 , .Ar cs0 No ... Ar cs7 ; or as either hex or decimal. .Pp For example, the following rules are identical: .Bd -literal -offset indent pass all tos lowdelay pass all tos 0x10 pass all tos 16 .Ed .It Ar allow-opts By default, IPv4 packets with IP options or IPv6 packets with routing extension headers are blocked. When .Ar allow-opts is specified for a .Ar pass rule, packets that pass the filter based on that rule (last matching) do so even if they contain IP options or routing extension headers. For packets that match state, the rule that initially created the state is used. The implicit .Ar pass rule that is used when a packet does not match any rules does not allow IP options. .It Ar label Aq Ar string Adds a label (name) to the rule, which can be used to identify the rule. For instance, pfctl -s labels shows per-rule statistics for rules that have labels. .Pp The following macros can be used in labels: .Pp .Bl -tag -width $srcaddr -compact -offset indent .It Ar $if The interface. .It Ar $srcaddr The source IP address. .It Ar $dstaddr The destination IP address. .It Ar $srcport The source port specification. .It Ar $dstport The destination port specification. .It Ar $proto The protocol name. .It Ar $nr The rule number. .El .Pp For example: .Bd -literal -offset indent ips = \&"{ 1.2.3.4, 1.2.3.5 }\&" pass in proto tcp from any to $ips \e port \*(Gt 1023 label \&"$dstaddr:$dstport\&" .Ed .Pp expands to .Bd -literal -offset indent pass in inet proto tcp from any to 1.2.3.4 \e port \*(Gt 1023 label \&"1.2.3.4:\*(Gt1023\&" pass in inet proto tcp from any to 1.2.3.5 \e port \*(Gt 1023 label \&"1.2.3.5:\*(Gt1023\&" .Ed .Pp The macro expansion for the .Ar label directive occurs only at configuration file parse time, not during runtime. .It Ar ridentifier Aq Ar number Add an identifier (number) to the rule, which can be used to correlate the rule to pflog entries, even after ruleset updates. .It Xo Ar queue Aq Ar queue .No \*(Ba ( Aq Ar queue , .Aq Ar queue ) .Xc Packets matching this rule will be assigned to the specified queue. If two queues are given, packets which have a .Em TOS of .Em lowdelay and TCP ACKs with no data payload will be assigned to the second one. See .Sx QUEUEING for setup details. .Pp For example: .Bd -literal -offset indent pass in proto tcp to port 25 queue mail pass in proto tcp to port 22 queue(ssh_bulk, ssh_prio) .Ed .It Cm set prio Ar priority | Pq Ar priority , priority Packets matching this rule will be assigned a specific queueing priority. Priorities are assigned as integers 0 through 7. If the packet is transmitted on a .Xr vlan 4 interface, the queueing priority will be written as the priority code point in the 802.1Q VLAN header. If two priorities are given, packets which have a TOS of .Cm lowdelay and TCP ACKs with no data payload will be assigned to the second one. .Pp For example: .Bd -literal -offset indent pass in proto tcp to port 25 set prio 2 pass in proto tcp to port 22 set prio (2, 5) .Ed .It Ar tag Aq Ar string Packets matching this rule will be tagged with the specified string. The tag acts as an internal marker that can be used to identify these packets later on. This can be used, for example, to provide trust between interfaces and to determine if packets have been processed by translation rules. Tags are .Qq sticky , meaning that the packet will be tagged even if the rule is not the last matching rule. Further matching rules can replace the tag with a new one but will not remove a previously applied tag. A packet is only ever assigned one tag at a time. Packet tagging can be done during .Ar nat , .Ar rdr , .Ar binat or .Ar ether rules in addition to filter rules. Tags take the same macros as labels (see above). .It Ar tagged Aq Ar string Used with filter, translation or scrub rules to specify that packets must already be tagged with the given tag in order to match the rule. Inverse tag matching can also be done by specifying the .Cm !\& operator before the .Ar tagged keyword. .It Ar rtable Aq Ar number Used to select an alternate routing table for the routing lookup. Only effective before the route lookup happened, i.e. when filtering inbound. .It Xo Ar divert-to Aq Ar host .Ar port Aq Ar port .Xc Used to .Xr divert 4 packets to the given divert .Ar port . Historically .Ox pf has another meaning for this, and .Fx pf uses this syntax to support .Xr divert 4 instead. Hence, .Ar host has no meaning and can be set to anything like 127.0.0.1. If a packet is re-injected and does not change direction then it will not be re-diverted. .It Ar divert-reply It has no meaning in .Fx pf . .It Ar probability Aq Ar number A probability attribute can be attached to a rule, with a value set between 0 and 1, bounds not included. In that case, the rule will be honoured using the given probability value only. For example, the following rule will drop 20% of incoming ICMP packets: .Bd -literal -offset indent block in proto icmp probability 20% .Ed .It Ar prio Aq Ar number Only match packets which have the given queueing priority assigned. .El .Sh ROUTING If a packet matches a rule with a route option set, the packet filter will route the packet according to the type of route option. When such a rule creates state, the route option is also applied to all packets matching the same connection. .Bl -tag -width xxxx .It Ar route-to The .Ar route-to option routes the packet to the specified interface with an optional address for the next hop. When a .Ar route-to rule creates state, only packets that pass in the same direction as the filter rule specifies will be routed in this way. Packets passing in the opposite direction (replies) are not affected and are routed normally. .It Ar reply-to The .Ar reply-to option is similar to .Ar route-to , but routes packets that pass in the opposite direction (replies) to the specified interface. Opposite direction is only defined in the context of a state entry, and .Ar reply-to is useful only in rules that create state. It can be used on systems with multiple external connections to route all outgoing packets of a connection through the interface the incoming connection arrived through (symmetric routing enforcement). .It Ar dup-to The .Ar dup-to option creates a duplicate of the packet and routes it like .Ar route-to . The original packet gets routed as it normally would. .El .Sh POOL OPTIONS For .Ar nat and .Ar rdr rules, (as well as for the .Ar route-to , .Ar reply-to and .Ar dup-to rule options) for which there is a single redirection address which has a subnet mask smaller than 32 for IPv4 or 128 for IPv6 (more than one IP address), a variety of different methods for assigning this address can be used: .Bl -tag -width xxxx .It Ar bitmask The .Ar bitmask option applies the network portion of the redirection address to the address to be modified (source with .Ar nat , destination with .Ar rdr ) . .It Ar random The .Ar random option selects an address at random within the defined block of addresses. .It Ar source-hash The .Ar source-hash option uses a hash of the source address to determine the redirection address, ensuring that the redirection address is always the same for a given source. An optional key can be specified after this keyword either in hex or as a string; by default .Xr pfctl 8 randomly generates a key for source-hash every time the ruleset is reloaded. .It Ar round-robin The .Ar round-robin option loops through the redirection address(es). .Pp When more than one redirection address is specified, .Ar round-robin is the only permitted pool type. .It Ar static-port With .Ar nat rules, the .Ar static-port option prevents .Xr pf 4 from modifying the source port on TCP and UDP packets. .It Xo Ar map-e-portset Aq Ar psid-offset .No / Aq Ar psid-len .No / Aq Ar psid .Xc With .Ar nat rules, the .Ar map-e-portset option enables the source port translation of MAP-E (RFC 7597) Customer Edge. In order to make the host act as a MAP-E Customer Edge, setting up a tunneling interface and pass rules for encapsulated packets are required in addition to the map-e-portset nat rule. .Pp For example: .Bd -literal -offset indent nat on $gif_mape_if from $int_if:network to any \e -> $ipv4_mape_src map-e-portset 6/8/0x34 .Ed .Pp sets PSID offset 6, PSID length 8, PSID 0x34. .El .Pp Additionally, 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. This option can be used with the .Ar random and .Ar round-robin pool options. Note that by default these associations are destroyed as soon as there are no longer states which refer to them; in order to make the mappings last beyond the lifetime of the states, increase the global options with .Ar set timeout src.track . See .Sx STATEFUL TRACKING OPTIONS for more ways to control the source tracking. .Sh STATE MODULATION Much of the security derived from TCP is attributable to how well the initial sequence numbers (ISNs) are chosen. Some popular stack implementations choose .Em very poor ISNs and thus are normally susceptible to ISN prediction exploits. By applying a .Ar modulate state rule to a TCP connection, .Xr pf 4 will create a high quality random sequence number for each connection endpoint. .Pp The .Ar modulate state directive implicitly keeps state on the rule and is only applicable to TCP connections. .Pp For instance: .Bd -literal -offset indent block all pass out proto tcp from any to any modulate state pass in proto tcp from any to any port 25 flags S/SFRA modulate state .Ed .Pp Note that modulated connections will not recover when the state table is lost (firewall reboot, flushing the state table, etc...). .Xr pf 4 will not be able to infer a connection again after the state table flushes the connection's modulator. When the state is lost, the connection may be left dangling until the respective endpoints time out the connection. It is possible on a fast local network for the endpoints to start an ACK storm while trying to resynchronize after the loss of the modulator. The default .Ar flags settings (or a more strict equivalent) should be used on .Ar modulate state rules to prevent ACK storms. .Pp Note that alternative methods are available to prevent loss of the state table and allow for firewall failover. See .Xr carp 4 and .Xr pfsync 4 for further information. .Sh SYN PROXY By default, .Xr pf 4 passes packets that are part of a .Xr tcp 4 handshake between the endpoints. The .Ar synproxy state option can be used to cause .Xr pf 4 itself to complete the handshake with the active endpoint, perform a handshake with the passive endpoint, and then forward packets between the endpoints. .Pp No packets are sent to the passive endpoint before the active endpoint has completed the handshake, hence so-called SYN floods with spoofed source addresses will not reach the passive endpoint, as the sender can't complete the handshake. .Pp The proxy is transparent to both endpoints, they each see a single connection from/to the other endpoint. .Xr pf 4 chooses random initial sequence numbers for both handshakes. Once the handshakes are completed, the sequence number modulators (see previous section) are used to translate further packets of the connection. .Ar synproxy state includes .Ar modulate state . .Pp Rules with .Ar synproxy will not work if .Xr pf 4 operates on a .Xr bridge 4 . .Pp Example: .Bd -literal -offset indent pass in proto tcp from any to any port www synproxy state .Ed .Sh STATEFUL TRACKING OPTIONS A number of options related to stateful tracking can be applied on a per-rule basis. .Ar keep state , .Ar modulate state and .Ar synproxy state support these options, and .Ar keep state must be specified explicitly to apply options to a rule. .Pp .Bl -tag -width xxxx -compact .It Ar max Aq Ar number Limits the number of concurrent states the rule may create. When this limit is reached, further packets that would create state will not match this rule until existing states time out. .It Ar no-sync Prevent state changes for states created by this rule from appearing on the .Xr pfsync 4 interface. .It Xo Aq Ar timeout .Aq Ar seconds .Xc Changes the timeout values used for states created by this rule. For a list of all valid timeout names, see .Sx OPTIONS above. .It Ar sloppy Uses a sloppy TCP connection tracker that does not check sequence numbers at all, which makes insertion and ICMP teardown attacks way easier. This is intended to be used in situations where one does not see all packets of a connection, e.g. in asymmetric routing situations. Cannot be used with modulate or synproxy state. .El .Pp Multiple options can be specified, separated by commas: .Bd -literal -offset indent pass in proto tcp from any to any \e port www keep state \e (max 100, source-track rule, max-src-nodes 75, \e max-src-states 3, tcp.established 60, tcp.closing 5) .Ed .Pp When the .Ar source-track keyword is specified, the number of states per source IP is tracked. .Pp .Bl -tag -width xxxx -compact .It Ar source-track rule The maximum number of states created by this rule is limited by the rule's .Ar max-src-nodes and .Ar max-src-states options. Only state entries created by this particular rule count toward the rule's limits. .It Ar source-track global The number of states created by all rules that use this option is limited. Each rule can specify different .Ar max-src-nodes and .Ar max-src-states options, however state entries created by any participating rule count towards each individual rule's limits. .El .Pp The following limits can be set: .Pp .Bl -tag -width xxxx -compact .It Ar max-src-nodes Aq Ar number Limits the maximum number of source addresses which can simultaneously have state table entries. .It Ar max-src-states Aq Ar number Limits the maximum number of simultaneous state entries that a single source address can create with this rule. .El .Pp For stateful TCP connections, limits on established connections (connections which have completed the TCP 3-way handshake) can also be enforced per source IP. .Pp .Bl -tag -width xxxx -compact .It Ar max-src-conn Aq Ar number Limits the maximum number of simultaneous TCP connections which have completed the 3-way handshake that a single host can make. .It Xo Ar max-src-conn-rate Aq Ar number .No / Aq Ar seconds .Xc Limit the rate of new connections over a time interval. The connection rate is an approximation calculated as a moving average. .El .Pp Because the 3-way handshake ensures that the source address is not being spoofed, more aggressive action can be taken based on these limits. With the .Ar overload Aq Ar table state option, source IP addresses which hit either of the limits on established connections will be added to the named table. This table can be used in the ruleset to block further activity from the offending host, redirect it to a tarpit process, or restrict its bandwidth. .Pp The optional .Ar flush keyword kills all states created by the matching rule which originate from the host which exceeds these limits. The .Ar global modifier to the flush command kills all states originating from the offending host, regardless of which rule created the state. .Pp For example, the following rules will protect the webserver against hosts making more than 100 connections in 10 seconds. Any host which connects faster than this rate will have its address added to the .Aq bad_hosts table and have all states originating from it flushed. Any new packets arriving from this host will be dropped unconditionally by the block rule. .Bd -literal -offset indent block quick from \*(Ltbad_hosts\*(Gt pass in on $ext_if proto tcp to $webserver port www keep state \e (max-src-conn-rate 100/10, overload \*(Ltbad_hosts\*(Gt flush global) .Ed .Sh OPERATING SYSTEM FINGERPRINTING Passive OS Fingerprinting is a mechanism to inspect nuances of a TCP connection's initial SYN packet and guess at the host's operating system. Unfortunately these nuances are easily spoofed by an attacker so the fingerprint is not useful in making security decisions. But the fingerprint is typically accurate enough to make policy decisions upon. .Pp The fingerprints may be specified by operating system class, by version, or by subtype/patchlevel. The class of an operating system is typically the vendor or genre and would be .Ox for the .Xr pf 4 firewall itself. The version of the oldest available .Ox release on the main FTP site would be 2.6 and the fingerprint would be written .Pp .Dl \&"OpenBSD 2.6\&" .Pp The subtype of an operating system is typically used to describe the patchlevel if that patch led to changes in the TCP stack behavior. In the case of .Ox , the only subtype is for a fingerprint that was normalized by the .Ar no-df scrub option and would be specified as .Pp .Dl \&"OpenBSD 3.3 no-df\&" .Pp Fingerprints for most popular operating systems are provided by .Xr pf.os 5 . Once .Xr pf 4 is running, a complete list of known operating system fingerprints may be listed by running: .Pp .Dl # pfctl -so .Pp Filter rules can enforce policy at any level of operating system specification assuming a fingerprint is present. Policy could limit traffic to approved operating systems or even ban traffic from hosts that aren't at the latest service pack. .Pp The .Ar unknown class can also be used as the fingerprint which will match packets for which no operating system fingerprint is known. .Pp Examples: .Bd -literal -offset indent pass out proto tcp from any os OpenBSD block out proto tcp from any os Doors block out proto tcp from any os "Doors PT" block out proto tcp from any os "Doors PT SP3" block out from any os "unknown" pass on lo0 proto tcp from any os "OpenBSD 3.3 lo0" .Ed .Pp Operating system fingerprinting is limited only to the TCP SYN packet. This means that it will not work on other protocols and will not match a currently established connection. .Pp Caveat: operating system fingerprints are occasionally wrong. There are three problems: an attacker can trivially craft his packets to appear as any operating system he chooses; an operating system patch could change the stack behavior and no fingerprints will match it until the database is updated; and multiple operating systems may have the same fingerprint. .Sh BLOCKING SPOOFED TRAFFIC "Spoofing" is the faking of IP addresses, typically for malicious purposes. The .Ar antispoof directive expands to a set of filter rules which will block all traffic with a source IP from the network(s) directly connected to the specified interface(s) from entering the system through any other interface. .Pp For example, the line .Bd -literal -offset indent antispoof for lo0 .Ed .Pp expands to .Bd -literal -offset indent block drop in on ! lo0 inet from 127.0.0.1/8 to any block drop in on ! lo0 inet6 from ::1 to any .Ed .Pp For non-loopback interfaces, there are additional rules to block incoming packets with a source IP address identical to the interface's IP(s). For example, assuming the interface wi0 had an IP address of 10.0.0.1 and a netmask of 255.255.255.0, the line .Bd -literal -offset indent antispoof for wi0 inet .Ed .Pp expands to .Bd -literal -offset indent block drop in on ! wi0 inet from 10.0.0.0/24 to any block drop in inet from 10.0.0.1 to any .Ed .Pp Caveat: Rules created by the .Ar antispoof directive interfere with packets sent over loopback interfaces to local addresses. One should pass these explicitly. .Sh FRAGMENT HANDLING The size of IP datagrams (packets) can be significantly larger than the maximum transmission unit (MTU) of the network. In cases when it is necessary or more efficient to send such large packets, the large packet will be fragmented into many smaller packets that will each fit onto the wire. Unfortunately for a firewalling device, only the first logical fragment will contain the necessary header information for the subprotocol that allows .Xr pf 4 to filter on things such as TCP ports or to perform NAT. .Pp Besides the use of .Ar set reassemble option or .Ar scrub rules as described in .Sx TRAFFIC NORMALIZATION above, there are three options for handling fragments in the packet filter. .Pp One alternative is to filter individual fragments with filter rules. If no .Ar scrub rule applies to a fragment or .Ar set reassemble is set to .Cm no , it is passed to the filter. Filter rules with matching IP header parameters decide whether the fragment is passed or blocked, in the same way as complete packets are filtered. Without reassembly, fragments can only be filtered based on IP header fields (source/destination address, protocol), since subprotocol header fields are not available (TCP/UDP port numbers, ICMP code/type). The .Ar fragment option can be used to restrict filter rules to apply only to fragments, but not complete packets. Filter rules without the .Ar fragment option still apply to fragments, if they only specify IP header fields. For instance, the rule .Bd -literal -offset indent pass in proto tcp from any to any port 80 .Ed .Pp never applies to a fragment, even if the fragment is part of a TCP packet with destination port 80, because without reassembly this information is not available for each fragment. This also means that fragments cannot create new or match existing state table entries, which makes stateful filtering and address translation (NAT, redirection) for fragments impossible. .Pp It's also possible to reassemble only certain fragments by specifying source or destination addresses or protocols as parameters in .Ar scrub rules. .Pp In most cases, the benefits of reassembly outweigh the additional memory cost, and it's recommended to use .Ar set reassemble option or .Ar scrub rules with the .Ar fragment reassemble modifier to reassemble all fragments. .Pp The memory allocated for fragment caching can be limited using .Xr pfctl 8 . Once this limit is reached, fragments that would have to be cached are dropped until other entries time out. The timeout value can also be adjusted. .Pp When forwarding reassembled IPv6 packets, pf refragments them with the original maximum fragment size. This allows the sender to determine the optimal fragment size by path MTU discovery. .Sh ANCHORS Besides the main ruleset, .Xr pfctl 8 can load rulesets into .Ar anchor attachment points. An .Ar anchor is a container that can hold rules, address tables, and other anchors. .Pp An .Ar anchor has a name which specifies the path where .Xr pfctl 8 can be used to access the anchor to perform operations on it, such as attaching child anchors to it or loading rules into it. Anchors may be nested, with components separated by .Sq / characters, similar to how file system hierarchies are laid out. The main ruleset is actually the default anchor, so filter and translation rules, for example, may also be contained in any anchor. .Pp An anchor can reference another .Ar anchor attachment point using the following kinds of rules: .Bl -tag -width xxxx .It Ar nat-anchor Aq Ar name Evaluates the .Ar nat rules in the specified .Ar anchor . .It Ar rdr-anchor Aq Ar name Evaluates the .Ar rdr rules in the specified .Ar anchor . .It Ar binat-anchor Aq Ar name Evaluates the .Ar binat rules in the specified .Ar anchor . .It Ar anchor Aq Ar name Evaluates the filter rules in the specified .Ar anchor . .It Xo Ar load anchor .Aq Ar name .Ar from Aq Ar file .Xc Loads the rules from the specified file into the anchor .Ar name . .El .Pp When evaluation of the main ruleset reaches an .Ar anchor rule, .Xr pf 4 will proceed to evaluate all rules specified in that anchor. .Pp Matching filter and translation rules marked with the .Ar quick option are final and abort the evaluation of the rules in other anchors and the main ruleset. If the .Ar anchor itself is marked with the .Ar quick option, ruleset evaluation will terminate when the anchor is exited if the packet is matched by any rule within the anchor. .Pp .Ar anchor rules are evaluated relative to the anchor in which they are contained. For example, all .Ar anchor rules specified in the main ruleset will reference anchor attachment points underneath the main ruleset, and .Ar anchor rules specified in a file loaded from a .Ar load anchor rule will be attached under that anchor point. .Pp Rules may be contained in .Ar anchor attachment points which do not contain any rules when the main ruleset is loaded, and later such anchors can be manipulated through .Xr pfctl 8 without reloading the main ruleset or other anchors. For example, .Bd -literal -offset indent ext_if = \&"kue0\&" block on $ext_if all anchor spam pass out on $ext_if all pass in on $ext_if proto tcp from any \e to $ext_if port smtp .Ed .Pp blocks all packets on the external interface by default, then evaluates all rules in the .Ar anchor named "spam", and finally passes all outgoing connections and incoming connections to port 25. .Bd -literal -offset indent # echo \&"block in quick from 1.2.3.4 to any\&" \&| \e pfctl -a spam -f - .Ed .Pp This loads a single rule into the .Ar anchor , which blocks all packets from a specific address. .Pp The anchor can also be populated by adding a .Ar load anchor rule after the .Ar anchor rule: .Bd -literal -offset indent anchor spam load anchor spam from "/etc/pf-spam.conf" .Ed .Pp When .Xr pfctl 8 loads .Nm pf.conf , it will also load all the rules from the file .Pa /etc/pf-spam.conf into the anchor. .Pp Optionally, .Ar anchor rules can specify packet filtering parameters using the same syntax as filter rules. When parameters are used, the .Ar anchor rule is only evaluated for matching packets. This allows conditional evaluation of anchors, like: .Bd -literal -offset indent block on $ext_if all anchor spam proto tcp from any to any port smtp pass out on $ext_if all pass in on $ext_if proto tcp from any to $ext_if port smtp .Ed .Pp The rules inside .Ar anchor spam are only evaluated for .Ar tcp packets with destination port 25. Hence, .Bd -literal -offset indent # echo \&"block in quick from 1.2.3.4 to any" \&| \e pfctl -a spam -f - .Ed .Pp will only block connections from 1.2.3.4 to port 25. .Pp Anchors may end with the asterisk .Pq Sq * character, which signifies that all anchors attached at that point should be evaluated in the alphabetical ordering of their anchor name. For example, .Bd -literal -offset indent anchor "spam/*" .Ed .Pp will evaluate each rule in each anchor attached to the .Li spam anchor. Note that it will only evaluate anchors that are directly attached to the .Li spam anchor, and will not descend to evaluate anchors recursively. .Pp Since anchors are evaluated relative to the anchor in which they are contained, there is a mechanism for accessing the parent and ancestor anchors of a given anchor. Similar to file system path name resolution, if the sequence .Dq .. appears as an anchor path component, the parent anchor of the current anchor in the path evaluation at that point will become the new current anchor. As an example, consider the following: .Bd -literal -offset indent # echo ' anchor "spam/allowed" ' | pfctl -f - # echo -e ' anchor "../banned" \en pass' | \e pfctl -a spam/allowed -f - .Ed .Pp Evaluation of the main ruleset will lead into the .Li spam/allowed anchor, which will evaluate the rules in the .Li spam/banned anchor, if any, before finally evaluating the .Ar pass rule. .Pp Filter rule .Ar anchors can also be loaded inline in the ruleset within a brace ('{' '}') delimited block. Brace delimited blocks may contain rules or other brace-delimited blocks. When anchors are loaded this way the anchor name becomes optional. .Bd -literal -offset indent anchor "external" on $ext_if { block anchor out { pass proto tcp from any to port { 25, 80, 443 } } pass in proto tcp to any port 22 } .Ed .Pp Since the parser specification for anchor names is a string, any reference to an anchor name containing .Sq / characters will require double quote .Pq Sq \&" characters around the anchor name. .Sh SCTP CONSIDERATIONS .Xr pf 4 supports .Xr sctp 4 connections. It can match ports, track state and NAT SCTP traffic. However, it will not alter port numbers during nat or rdr translations. Doing so would break SCTP multihoming. .Sh TRANSLATION EXAMPLES This example maps incoming requests on port 80 to port 8080, on which a daemon is running (because, for example, it is not run as root, and therefore lacks permission to bind to port 80). .Bd -literal # use a macro for the interface name, so it can be changed easily ext_if = \&"ne3\&" # map daemon on 8080 to appear to be on 80 rdr on $ext_if proto tcp from any to any port 80 -\*(Gt 127.0.0.1 port 8080 .Ed .Pp If the .Ar pass modifier is given, packets matching the translation rule are passed without inspecting the filter rules: .Bd -literal rdr pass on $ext_if proto tcp from any to any port 80 -\*(Gt 127.0.0.1 \e port 8080 .Ed .Pp In the example below, vlan12 is configured as 192.168.168.1; the machine translates all packets coming from 192.168.168.0/24 to 204.92.77.111 when they are going out any interface except vlan12. This has the net effect of making traffic from the 192.168.168.0/24 network appear as though it is the Internet routable address 204.92.77.111 to nodes behind any interface on the router except for the nodes on vlan12. (Thus, 192.168.168.1 can talk to the 192.168.168.0/24 nodes.) .Bd -literal nat on ! vlan12 from 192.168.168.0/24 to any -\*(Gt 204.92.77.111 .Ed .Pp In the example below, the machine sits between a fake internal 144.19.74.* network, and a routable external IP of 204.92.77.100. The .Ar no nat rule excludes protocol AH from being translated. .Bd -literal # NO NAT no nat on $ext_if proto ah from 144.19.74.0/24 to any nat on $ext_if from 144.19.74.0/24 to any -\*(Gt 204.92.77.100 .Ed .Pp In the example below, packets bound for one specific server, as well as those generated by the sysadmins are not proxied; all other connections are. .Bd -literal # NO RDR no rdr on $int_if proto { tcp, udp } from any to $server port 80 no rdr on $int_if proto { tcp, udp } from $sysadmins to any port 80 rdr on $int_if proto { tcp, udp } from any to any port 80 -\*(Gt 127.0.0.1 \e port 80 .Ed .Pp This longer example uses both a NAT and a redirection. The external interface has the address 157.161.48.183. On localhost, we are running .Xr ftp-proxy 8 , waiting for FTP sessions to be redirected to it. The three mandatory anchors for .Xr ftp-proxy 8 are omitted from this example; see the .Xr ftp-proxy 8 manpage. .Bd -literal # NAT # Translate outgoing packets' source addresses (any protocol). # In this case, any address but the gateway's external address is mapped. nat on $ext_if inet from ! ($ext_if) to any -\*(Gt ($ext_if) # NAT PROXYING # Map outgoing packets' source port to an assigned proxy port instead of # an arbitrary port. # In this case, proxy outgoing isakmp with port 500 on the gateway. nat on $ext_if inet proto udp from any port = isakmp to any -\*(Gt ($ext_if) \e port 500 # BINAT # Translate outgoing packets' source address (any protocol). # Translate incoming packets' destination address to an internal machine # (bidirectional). binat on $ext_if from 10.1.2.150 to any -\*(Gt $ext_if # Translate packets arriving on $peer_if addressed to 172.22.16.0/20 # to the corresponding address in 172.21.16.0/20 (bidirectional). binat on $peer_if from 172.21.16.0/20 to any -> 172.22.16.0/20 # RDR # Translate incoming packets' destination addresses. # As an example, redirect a TCP and UDP port to an internal machine. rdr on $ext_if inet proto tcp from any to ($ext_if) port 8080 \e -\*(Gt 10.1.2.151 port 22 rdr on $ext_if inet proto udp from any to ($ext_if) port 8080 \e -\*(Gt 10.1.2.151 port 53 # RDR # Translate outgoing ftp control connections to send them to localhost # for proxying with ftp-proxy(8) running on port 8021. rdr on $int_if proto tcp from any to any port 21 -\*(Gt 127.0.0.1 port 8021 .Ed .Pp In this example, a NAT gateway is set up to translate internal addresses using a pool of public addresses (192.0.2.16/28) and to redirect incoming web server connections to a group of web servers on the internal network. .Bd -literal # NAT LOAD BALANCE # Translate outgoing packets' source addresses using an address pool. # A given source address is always translated to the same pool address by # using the source-hash keyword. nat on $ext_if inet from any to any -\*(Gt 192.0.2.16/28 source-hash # RDR ROUND ROBIN # Translate incoming web server connections to a group of web servers on # the internal network. rdr on $ext_if proto tcp from any to any port 80 \e -\*(Gt { 10.1.2.155, 10.1.2.160, 10.1.2.161 } round-robin .Ed .Sh FILTER EXAMPLES .Bd -literal # The external interface is kue0 # (157.161.48.183, the only routable address) # and the private network is 10.0.0.0/8, for which we are doing NAT. # Reassemble incoming traffic set reassemble yes # use a macro for the interface name, so it can be changed easily ext_if = \&"kue0\&" # block and log everything by default block return log on $ext_if all # block anything coming from source we have no back routes for block in from no-route to any # block packets whose ingress interface does not match the one in # the route back to their source address block in from urpf-failed to any # block and log outgoing packets that do not have our address as source, # they are either spoofed or something is misconfigured (NAT disabled, # for instance), we want to be nice and do not send out garbage. block out log quick on $ext_if from ! 157.161.48.183 to any # silently drop broadcasts (cable modem noise) block in quick on $ext_if from any to 255.255.255.255 # block and log incoming packets from reserved address space and invalid # addresses, they are either spoofed or misconfigured, we cannot reply to # them anyway (hence, no return-rst). block in log quick on $ext_if from { 10.0.0.0/8, 172.16.0.0/12, \e 192.168.0.0/16, 255.255.255.255/32 } to any # ICMP # pass out/in certain ICMP queries and keep state (ping) # state matching is done on host addresses and ICMP id (not type/code), # so replies (like 0/0 for 8/0) will match queries # ICMP error messages (which always refer to a TCP/UDP packet) are # handled by the TCP/UDP states pass on $ext_if inet proto icmp all icmp-type 8 code 0 # UDP # pass out all UDP connections and keep state pass out on $ext_if proto udp all # pass in certain UDP connections and keep state (DNS) pass in on $ext_if proto udp from any to any port domain # TCP # pass out all TCP connections and modulate state pass out on $ext_if proto tcp all modulate state # pass in certain TCP connections and keep state (SSH, SMTP, DNS, IDENT) pass in on $ext_if proto tcp from any to any port { ssh, smtp, domain, \e auth } # Do not allow Windows 9x SMTP connections since they are typically # a viral worm. Alternately we could limit these OSes to 1 connection each. block in on $ext_if proto tcp from any os {"Windows 95", "Windows 98"} \e to any port smtp # IPv6 # pass in/out all IPv6 traffic: note that we have to enable this in two # different ways, on both our physical interface and our tunnel pass quick on gif0 inet6 pass quick on $ext_if proto ipv6 # Packet Tagging # three interfaces: $int_if, $ext_if, and $wifi_if (wireless). NAT is # being done on $ext_if for all outgoing packets. tag packets in on # $int_if and pass those tagged packets out on $ext_if. all other # outgoing packets (i.e., packets from the wireless network) are only # permitted to access port 80. pass in on $int_if from any to any tag INTNET pass in on $wifi_if from any to any block out on $ext_if from any to any pass out quick on $ext_if tagged INTNET pass out on $ext_if proto tcp from any to any port 80 # tag incoming packets as they are redirected to spamd(8). use the tag # to pass those packets through the packet filter. rdr on $ext_if inet proto tcp from \*(Ltspammers\*(Gt to port smtp \e tag SPAMD -\*(Gt 127.0.0.1 port spamd block in on $ext_if pass in on $ext_if inet proto tcp tagged SPAMD .Ed .Sh GRAMMAR Syntax for .Nm in BNF: .Bd -literal line = ( option | ether-rule | pf-rule | nat-rule | binat-rule | rdr-rule | antispoof-rule | altq-rule | queue-rule | trans-anchors | anchor-rule | anchor-close | load-anchor | table-rule | include ) option = "set" ( [ "timeout" ( timeout | "{" timeout-list "}" ) ] | [ "ruleset-optimization" [ "none" | "basic" | "profile" ]] | [ "optimization" [ "default" | "normal" | "high-latency" | "satellite" | "aggressive" | "conservative" ] ] [ "limit" ( limit-item | "{" limit-list "}" ) ] | [ "loginterface" ( interface-name | "none" ) ] | [ "block-policy" ( "drop" | "return" ) ] | [ "state-policy" ( "if-bound" | "floating" ) ] [ "state-defaults" state-opts ] [ "require-order" ( "yes" | "no" ) ] [ "fingerprints" filename ] | [ "skip on" ifspec ] | [ "debug" ( "none" | "urgent" | "misc" | "loud" ) ] [ "keepcounters" ] ) ether-rule = "ether" etheraction [ ( "in" | "out" ) ] [ "quick" ] [ "on" ifspec ] [ "bridge-to" interface-name ] [ etherprotospec ] etherhosts [ "l3" hosts ] [ etherfilteropt-list ] pf-rule = action [ ( "in" | "out" ) ] [ "log" [ "(" logopts ")"] ] [ "quick" ] [ "on" ifspec ] [ route ] [ af ] [ protospec ] hosts [ filteropt-list ] logopts = logopt [ "," logopts ] logopt = "all" | "user" | "to" interface-name etherfilteropt-list = etherfilteropt-list etherfilteropt | etherfilteropt etherfilteropt = "tag" string | "tagged" string | "queue" ( string ) | "ridentifier" number | "label" string filteropt-list = filteropt-list filteropt | filteropt filteropt = user | group | flags | icmp-type | icmp6-type | "tos" tos | ( "no" | "keep" | "modulate" | "synproxy" ) "state" [ "(" state-opts ")" ] | "fragment" | "no-df" | "min-ttl" number | "set-tos" tos | "max-mss" number | "random-id" | "reassemble tcp" | fragmentation | "allow-opts" | "label" string | "tag" string | [ ! ] "tagged" string | "set prio" ( number | "(" number [ [ "," ] number ] ")" ) | "queue" ( string | "(" string [ [ "," ] string ] ")" ) | "rtable" number | "probability" number"%" | "prio" number | "dnpipe" ( number | "(" number "," number ")" ) | "dnqueue" ( number | "(" number "," number ")" ) | "ridentifier" number nat-rule = [ "no" ] "nat" [ "pass" [ "log" [ "(" logopts ")" ] ] ] [ "on" ifspec ] [ af ] [ protospec ] hosts [ "tag" string ] [ "tagged" string ] [ "-\*(Gt" ( redirhost | "{" redirhost-list "}" ) [ portspec ] [ pooltype ] [ "static-port" ] [ "map-e-portset" number "/" number "/" number ] ] binat-rule = [ "no" ] "binat" [ "pass" [ "log" [ "(" logopts ")" ] ] ] [ "on" interface-name ] [ af ] [ "proto" ( proto-name | proto-number ) ] "from" address [ "/" mask-bits ] "to" ipspec [ "tag" string ] [ "tagged" string ] [ "-\*(Gt" address [ "/" mask-bits ] ] rdr-rule = [ "no" ] "rdr" [ "pass" [ "log" [ "(" logopts ")" ] ] ] [ "on" ifspec ] [ af ] [ protospec ] hosts [ "tag" string ] [ "tagged" string ] [ "-\*(Gt" ( redirhost | "{" redirhost-list "}" ) [ portspec ] [ pooltype ] ] antispoof-rule = "antispoof" [ "log" ] [ "quick" ] "for" ifspec [ af ] [ "label" string ] [ "ridentifier" number ] table-rule = "table" "\*(Lt" string "\*(Gt" [ tableopts-list ] tableopts-list = tableopts-list tableopts | tableopts tableopts = "persist" | "const" | "counters" | "file" string | "{" [ tableaddr-list ] "}" tableaddr-list = tableaddr-list [ "," ] tableaddr-spec | tableaddr-spec tableaddr-spec = [ "!" ] tableaddr [ "/" mask-bits ] tableaddr = hostname | ifspec | "self" | ipv4-dotted-quad | ipv6-coloned-hex altq-rule = "altq on" interface-name queueopts-list "queue" subqueue queue-rule = "queue" string [ "on" interface-name ] queueopts-list subqueue anchor-rule = "anchor" [ string ] [ ( "in" | "out" ) ] [ "on" ifspec ] [ af ] [ protospec ] [ hosts ] [ filteropt-list ] [ "{" ] anchor-close = "}" trans-anchors = ( "nat-anchor" | "rdr-anchor" | "binat-anchor" ) string [ "on" ifspec ] [ af ] [ "proto" ] [ protospec ] [ hosts ] load-anchor = "load anchor" string "from" filename queueopts-list = queueopts-list queueopts | queueopts queueopts = [ "bandwidth" bandwidth-spec ] | [ "qlimit" number ] | [ "tbrsize" number ] | [ "priority" number ] | [ schedulers ] schedulers = ( cbq-def | priq-def | hfsc-def ) bandwidth-spec = "number" ( "b" | "Kb" | "Mb" | "Gb" | "%" ) etheraction = "pass" | "block" action = "pass" | "match" | "block" [ return ] | [ "no" ] "scrub" return = "drop" | "return" | "return-rst" [ "( ttl" number ")" ] | "return-icmp" [ "(" icmpcode [ [ "," ] icmp6code ] ")" ] | "return-icmp6" [ "(" icmp6code ")" ] icmpcode = ( icmp-code-name | icmp-code-number ) icmp6code = ( icmp6-code-name | icmp6-code-number ) ifspec = ( [ "!" ] ( interface-name | interface-group ) ) | "{" interface-list "}" interface-list = [ "!" ] ( interface-name | interface-group ) [ [ "," ] interface-list ] route = ( "route-to" | "reply-to" | "dup-to" ) ( routehost | "{" routehost-list "}" ) [ pooltype ] af = "inet" | "inet6" etherprotospec = "proto" ( proto-number | "{" etherproto-list "}" ) etherproto-list = proto-number [ [ "," ] etherproto-list ] protospec = "proto" ( proto-name | proto-number | "{" proto-list "}" ) proto-list = ( proto-name | proto-number ) [ [ "," ] proto-list ] etherhosts = "from" macaddress "to" macaddress macaddress = mac | mac "/" masklen | mac "&" mask hosts = "all" | "from" ( "any" | "no-route" | "urpf-failed" | "self" | host | "{" host-list "}" ) [ port ] [ os ] "to" ( "any" | "no-route" | "self" | host | "{" host-list "}" ) [ port ] ipspec = "any" | host | "{" host-list "}" host = [ "!" ] ( address [ "/" mask-bits ] | "\*(Lt" string "\*(Gt" ) redirhost = address [ "/" mask-bits ] routehost = "(" interface-name [ address [ "/" mask-bits ] ] ")" address = ( interface-name | interface-group | "(" ( interface-name | interface-group ) ")" | hostname | ipv4-dotted-quad | ipv6-coloned-hex ) host-list = host [ [ "," ] host-list ] redirhost-list = redirhost [ [ "," ] redirhost-list ] routehost-list = routehost [ [ "," ] routehost-list ] port = "port" ( unary-op | binary-op | "{" op-list "}" ) portspec = "port" ( number | name ) [ ":" ( "*" | number | name ) ] os = "os" ( os-name | "{" os-list "}" ) user = "user" ( unary-op | binary-op | "{" op-list "}" ) group = "group" ( unary-op | binary-op | "{" op-list "}" ) unary-op = [ "=" | "!=" | "\*(Lt" | "\*(Le" | "\*(Gt" | "\*(Ge" ] ( name | number ) binary-op = number ( "\*(Lt\*(Gt" | "\*(Gt\*(Lt" | ":" ) number op-list = ( unary-op | binary-op ) [ [ "," ] op-list ] os-name = operating-system-name os-list = os-name [ [ "," ] os-list ] flags = "flags" ( [ flag-set ] "/" flag-set | "any" ) flag-set = [ "F" ] [ "S" ] [ "R" ] [ "P" ] [ "A" ] [ "U" ] [ "E" ] [ "W" ] icmp-type = "icmp-type" ( icmp-type-code | "{" icmp-list "}" ) icmp6-type = "icmp6-type" ( icmp-type-code | "{" icmp-list "}" ) icmp-type-code = ( icmp-type-name | icmp-type-number ) [ "code" ( icmp-code-name | icmp-code-number ) ] icmp-list = icmp-type-code [ [ "," ] icmp-list ] tos = ( "lowdelay" | "throughput" | "reliability" | [ "0x" ] number ) state-opts = state-opt [ [ "," ] state-opts ] state-opt = ( "max" number | "no-sync" | timeout | "sloppy" | "source-track" [ ( "rule" | "global" ) ] | "max-src-nodes" number | "max-src-states" number | "max-src-conn" number | "max-src-conn-rate" number "/" number | "overload" "\*(Lt" string "\*(Gt" [ "flush" ] | "if-bound" | "floating" ) fragmentation = [ "fragment reassemble" ] timeout-list = timeout [ [ "," ] timeout-list ] timeout = ( "tcp.first" | "tcp.opening" | "tcp.established" | "tcp.closing" | "tcp.finwait" | "tcp.closed" | "sctp.first" | "sctp.opening" | "sctp.established" | "sctp.closing" | "sctp.closed" | "udp.first" | "udp.single" | "udp.multiple" | "icmp.first" | "icmp.error" | "other.first" | "other.single" | "other.multiple" | "frag" | "interval" | "src.track" | "adaptive.start" | "adaptive.end" ) number limit-list = limit-item [ [ "," ] limit-list ] limit-item = ( "states" | "frags" | "src-nodes" ) number pooltype = ( "bitmask" | "random" | "source-hash" [ ( hex-key | string-key ) ] | "round-robin" ) [ sticky-address ] subqueue = string | "{" queue-list "}" queue-list = string [ [ "," ] string ] cbq-def = "cbq" [ "(" cbq-opt [ [ "," ] cbq-opt ] ")" ] priq-def = "priq" [ "(" priq-opt [ [ "," ] priq-opt ] ")" ] hfsc-def = "hfsc" [ "(" hfsc-opt [ [ "," ] hfsc-opt ] ")" ] cbq-opt = ( "default" | "borrow" | "red" | "ecn" | "rio" ) priq-opt = ( "default" | "red" | "ecn" | "rio" ) hfsc-opt = ( "default" | "red" | "ecn" | "rio" | linkshare-sc | realtime-sc | upperlimit-sc ) linkshare-sc = "linkshare" sc-spec realtime-sc = "realtime" sc-spec upperlimit-sc = "upperlimit" sc-spec sc-spec = ( bandwidth-spec | "(" bandwidth-spec number bandwidth-spec ")" ) include = "include" filename .Ed .Sh FILES .Bl -tag -width "/etc/protocols" -compact .It Pa /etc/hosts Host name database. .It Pa /etc/pf.conf Default location of the ruleset file. The file has to be created manually as it is not installed with a standard installation. .It Pa /etc/pf.os Default location of OS fingerprints. .It Pa /etc/protocols Protocol name database. .It Pa /etc/services Service name database. .El .Sh SEE ALSO .Xr altq 4 , .Xr carp 4 , .Xr icmp 4 , .Xr icmp6 4 , .Xr ip 4 , .Xr ip6 4 , .Xr pf 4 , .Xr pfsync 4 , -.Xr tcp 4 , .Xr sctp 4 , +.Xr tcp 4 , .Xr udp 4 , .Xr hosts 5 , .Xr pf.os 5 , .Xr protocols 5 , .Xr services 5 , .Xr ftp-proxy 8 , .Xr pfctl 8 , .Xr pflogd 8 .Sh HISTORY The .Nm file format first appeared in .Ox 3.0 . diff --git a/share/man/man8/rc.subr.8 b/share/man/man8/rc.subr.8 index 2dd46cf50c2b..844ba0356692 100644 --- a/share/man/man8/rc.subr.8 +++ b/share/man/man8/rc.subr.8 @@ -1,963 +1,964 @@ .\" $NetBSD: rc.subr.8,v 1.12 2004/01/06 00:52:24 lukem Exp $ .\" .\" Copyright (c) 2002-2004 The NetBSD Foundation, Inc. .\" All rights reserved. .\" .\" This code is derived from software contributed to The NetBSD Foundation .\" by Luke Mewburn. .\" .\" 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. .\" .Dd September 22, 2024 .Dt RC.SUBR 8 .Os .Sh NAME .Nm rc.subr .Nd functions used by system shell scripts .Sh SYNOPSIS .Bl -item -compact .It .Ic .\& Pa /etc/rc.subr .Pp .It .Ic backup_file Ar action Ar file Ar current Ar backup .It .Ic checkyesno Ar var .It .Ic check_pidfile Ar pidfile Ar procname Op Ar interpreter .It .Ic check_process Ar procname Op Ar interpreter .It .Ic debug Ar message .It .Ic err Ar exitval Ar message .It .Ic force_depend Ar name .It .Ic info Ar message .It .Ic load_kld Oo Fl e Ar regex Oc Oo Fl m Ar module Oc Ar file .It .Ic load_rc_config Op Ar service .It .Ic load_rc_config_var Ar name Ar var .It .Ic mount_critical_filesystems Ar type .It .Ic rc_usage Ar command ... .It .Ic reverse_list Ar item ... .It .Ic run_rc_command Ar argument .It .Ic run_rc_script Ar file Ar argument .It .Ic startmsg Oo Fl n Oc Ar message .It .Ic wait_for_pids Op Ar pid ... .It .Ic warn Ar message .El .Sh DESCRIPTION The .Nm script contains commonly used shell script functions and variable definitions which are used by various scripts such as .Xr rc 8 . Scripts required by ports in .Pa /usr/local/etc/rc.d will also eventually be rewritten to make use of it. .Pp The .Nm functions were mostly imported from .Nx . .Pp They are accessed by sourcing .Pa /etc/rc.subr into the current shell. .Pp The following shell functions are available: .Bl -tag -width 4n .It Ic backup_file Ar action file current backup Make a backup copy of .Ar file into .Ar current . Save the previous version of .Ar current as .Ar backup . .Pp The .Ar action argument may be one of the following: .Bl -tag -width "remove" .It Cm add .Ar file is now being backed up by or possibly re-entered into this backup mechanism. .Ar current is created. .It Cm update .Ar file has changed and needs to be backed up. If .Ar current exists, it is copied to .Ar backup and then .Ar file is copied to .Ar current . .It Cm remove .Ar file is no longer being tracked by this backup mechanism. .Ar current is moved to .Ar backup . .El .It Ic checkyesno Ar var Return 0 if .Ar var is defined to .Dq Li YES , .Dq Li TRUE , .Dq Li ON , or .Ql 1 . Return 1 if .Ar var is defined to .Dq Li NO , .Dq Li FALSE , .Dq Li OFF , or .Ql 0 . Otherwise, warn that .Ar var is not set correctly. The values are case insensitive. .Em Note : .Ar var should be a variable name, not its value; .Ic checkyesno will expand the variable by itself. .It Ic check_pidfile Ar pidfile procname Op Ar interpreter Parses the first word of the first line of .Ar pidfile for a PID, and ensures that the process with that PID is running and its first argument matches .Ar procname . Prints the matching PID if successful, otherwise nothing. If .Ar interpreter is provided, parse the first line of .Ar procname , ensure that the line is of the form: .Pp .Dl "#! interpreter [...]" .Pp and use .Ar interpreter with its optional arguments and .Ar procname appended as the process string to search for. .It Ic check_process Ar procname Op Ar interpreter Prints the PIDs of any processes that are running with a first argument that matches .Ar procname . .Ar interpreter is handled as per .Ic check_pidfile . .It Ic debug Ar message Display a debugging message to .Va stderr , log it to the system log using .Xr logger 1 , and return to the caller. The error message consists of the script name (from .Va $0 ) , followed by .Dq Li ": DEBUG: " , and then .Ar message . This function is intended to be used by developers as an aid to debugging scripts. It can be turned on or off by the .Xr rc.conf 5 variable .Va rc_debug . .It Ic err Ar exitval message Display an error message to .Va stderr , log it to the system log using .Xr logger 1 , and .Ic exit with an exit value of .Ar exitval . The error message consists of the script name (from .Va $0 ) , followed by .Dq Li ": ERROR: " , and then .Ar message . .It Ic force_depend Ar name Output an advisory message and force the .Ar name service to start. The .Ar name argument is the .Xr basename 1 component of the path to the script located at .Pa /etc/rc.d (scripts stored in other locations such as .Pa /usr/local/etc/rc.d cannot be controlled with .Ic force_depend currently). If the script fails for any reason it will output a warning and return with a return value of 1. If it was successful it will return 0. .It Ic info Ar message Display an informational message to .Va stdout , and log it to the system log using .Xr logger 1 . The message consists of the script name (from .Va $0 ) , followed by .Dq Li ": INFO: " , and then .Ar message . The display of this informational output can be turned on or off by the .Xr rc.conf 5 variable .Va rc_info . .It Ic load_kld Oo Fl e Ar regex Oc Oo Fl m Ar module Oc Ar file Load .Ar file as a kernel module unless it is already loaded. For the purpose of checking the module status, either the exact module name can be specified using .Fl m , or an .Xr egrep 1 regular expression matching the module name can be supplied via .Fl e . By default, the module is assumed to have the same name as .Ar file , which is not always the case. .It Ic load_rc_config Op Ar service Source in the configuration file(s) for .Ar service . If no .Ar service is specified, only the global configuration file(s) will be loaded. First, .Pa /etc/rc.conf is sourced if it has not yet been read in. Then, .Pa /etc/rc.conf.d/ Ns Ar service is sourced if it is an existing file. The latter may also contain other variable assignments to override .Ic run_rc_command arguments defined by the calling script, to provide an easy mechanism for an administrator to override the behaviour of a given .Xr rc.d 8 script without requiring the editing of that script. .It Ic load_rc_config_var Ar name Ar var Read the .Xr rc.conf 5 variable .Ar var for .Ar name and set in the current shell, using .Ic load_rc_config in a sub-shell to prevent unwanted side effects from other variable assignments. .It Ic mount_critical_filesystems Ar type Go through a list of critical file systems, as found in the .Xr rc.conf 5 variable .Va critical_filesystems_ Ns Ar type , mounting each one that is not currently mounted. .It Ic rc_usage Ar command ... Print a usage message for .Va $0 , with .Ar commands being the list of valid arguments prefixed by .Sm off .Dq Bq Li fast | force | one | quiet . .Sm on .It Ic reverse_list Ar item ... Print the list of .Ar items in reverse order. .It Ic run_rc_command Ar argument Run the .Ar argument method for the current .Xr rc.d 8 script, based on the settings of various shell variables. .Ic run_rc_command is extremely flexible, and allows fully functional .Xr rc.d 8 scripts to be implemented in a small amount of shell code. .Pp .Ar argument is searched for in the list of supported commands, which may be one of: .Bl -tag -width "restart" -offset indent .It Cm start Start the service. This should check that the service is to be started as specified by .Xr rc.conf 5 . Also checks if the service is already running and refuses to start if it is. This latter check is not performed by standard .Fx scripts if the system is starting directly to multi-user mode, to speed up the boot process. .It Cm stop If the service is to be started as specified by .Xr rc.conf 5 , stop the service. This should check that the service is running and complain if it is not. .It Cm restart Perform a .Cm stop then a .Cm start . Defaults to displaying the process ID of the program (if running). .It Cm enabled Return 0 if the service is enabled and 1 if it is not. This command does not print anything. .It Cm rcvar Display which .Xr rc.conf 5 variables are used to control the startup of the service (if any). .El .Pp If .Va pidfile or .Va procname is set, also support: .Bl -tag -width "status" -offset indent .It Cm poll Wait for the command to exit. .It Cm status Show the status of the process. .El .Pp Other supported commands are listed in the optional variable .Va extra_commands . .Pp .Ar argument may have one of the following prefixes which alters its operation: .Bl -tag -width "force" -offset indent .It Li fast Skip the check for an existing running process, and sets .Va rc_fast Ns = Ns Li YES . .It Li force Skip the checks for .Va rcvar being set to .Dq Li YES , and sets .Va rc_force Ns = Ns Li YES . This ignores .Ar argument Ns Va _precmd returning non-zero, and ignores any of the .Va required_* tests failing, and always returns a zero exit status. .It Li one Skip the checks for .Va rcvar being set to .Dq Li YES , but performs all the other prerequisite tests. .It Li quiet Inhibits some verbose diagnostics. Currently, this includes messages .Qq Starting ${name} (as checked by .Ic check_startmsgs inside .Nm ) and errors about usage of services that are not enabled in .Xr rc.conf 5 . This prefix also sets .Va rc_quiet Ns = Ns Li YES . .Em Note : .Va rc_quiet is not intended to completely mask all debug and warning messages, but only certain small classes of them. .El .Pp .Ic run_rc_command uses the following shell variables to control its behaviour. Unless otherwise stated, these are optional. .Bl -tag -width "procname" -offset indent .It Va name The name of this script. This is not optional. .It Va rcvar The value of .Va rcvar is checked with .Ic checkyesno to determine if this method should be run. .It Va command Full path to the command. Not required if .Ar argument Ns Va _cmd is defined for each supported keyword. Can be overridden by .Va ${name}_program . .It Va command_args Optional arguments and/or shell directives for .Va command . .It Va command_interpreter .Va command is started with: .Pp .Dl "#! command_interpreter [...]" .Pp which results in its .Xr ps 1 command being: .Pp .Dl "command_interpreter [...] command" .Pp so use that string to find the PID(s) of the running command rather than .Va command . .It Va extra_commands Extra commands/keywords/arguments supported. .It Va pidfile Path to PID file. Used to determine the PID(s) of the running command. If .Va pidfile is set, use: .Pp .Dl "check_pidfile $pidfile $procname" .Pp to find the PID. Otherwise, if .Va command is set, use: .Pp .Dl "check_process $procname" .Pp to find the PID. .It Va procname Process name to check for. Defaults to the value of .Va command . .It Va required_dirs Check for the existence of the listed directories before running the .Cm start method. The list is checked before running .Va start_precmd . .It Va required_files Check for the readability of the listed files before running the .Cm start method. The list is checked before running .Va start_precmd . .It Va required_modules Ensure that the listed kernel modules are loaded before running the .Cm start method. The list is checked after running .Va start_precmd . This is done after invoking the commands from .Va start_precmd so that the missing modules are not loaded in vain if the preliminary commands indicate a error condition. A word in the list can have an optional .Dq Li \&: Ns Ar modname or .Dq Li ~ Ns Ar pattern suffix. The .Ar modname or .Ar pattern parameter is passed to .Ic load_kld through a .Fl m or .Fl e option, respectively. See the description of .Ic load_kld in this document for details. .It Va required_vars Perform .Ic checkyesno on each of the list variables before running the .Cm start method. The list is checked after running .Va start_precmd . .It Va ${name}_chdir Directory to .Ic cd to before running .Va command , if .Va ${name}_chroot is not provided. .It Va ${name}_chroot Directory to .Xr chroot 8 to before running .Va command . Only supported after .Pa /usr is mounted. .It Va ${name}_env A list of environment variables to run .Va command with. Those variables will be passed as arguments to the .Xr env 1 utility unless .Ar argument Ns Va _cmd is defined. In that case the contents of .Va ${name}_env will be exported via the .Xr export 1 builtin of .Xr sh 1 , which puts some limitations on the names of variables (e.g., a variable name may not start with a digit). .It Va ${name}_env_file A file to source for environmental variables to run .Va command with. .Em Note : all the variables which are being assigned in this file are going to be exported into the environment of .Va command . .It Va ${name}_fib FIB .Pa Routing Table number to run .Va command with. See .Xr setfib 1 for more details. .It Va ${name}_flags Arguments to call .Va command with. This is usually set in .Xr rc.conf 5 , and not in the .Xr rc.d 8 script. The environment variable .Sq Ev flags can be used to override this. .It Va ${name}_nice .Xr nice 1 level to run .Va command as. Only supported after .Pa /usr is mounted. .It Va ${name}_limits Resource limits to apply to .Va command . This will be passed as arguments to the .Xr limits 1 utility. By default, the resource limits are based on the login class defined in .Va ${name}_login_class . .It Va ${name}_login_class Login class to use with .Va ${name}_limits . Defaults to .Dq Li daemon . .It Va ${name}_offcmd Shell commands to run during start if a service is not enabled. .It Va ${name}_oomprotect .Xr protect 1 .Va command from being killed when swap space is exhausted. If .Dq Li YES is used, no child processes are protected. If .Dq Li ALL , protect all child processes. .It Va ${name}_program Full path to the command. Overrides .Va command if both are set, but has no effect if .Va command is unset. As a rule, .Va command should be set in the script while .Va ${name}_program should be set in .Xr rc.conf 5 . .It Va ${name}_user User to run .Va command as, using .Xr chroot 8 if .Va ${name}_chroot is set, otherwise uses .Xr su 1 . Only supported after .Pa /usr is mounted. .It Va ${name}_group Group to run the chrooted .Va command as. .It Va ${name}_groups Comma separated list of supplementary groups to run the chrooted .Va command with. .It Va ${name}_prepend Commands to be prepended to .Va command . This is a generic version of .Va ${name}_env , .Va ${name}_fib , or .Va ${name}_nice . .It Va ${name}_setup Command to be run prior to .Va command . .It Ar argument Ns Va _cmd Shell commands which override the default method for .Ar argument . .It Ar argument Ns Va _precmd Shell commands to run just before running .Ar argument Ns Va _cmd or the default method for .Ar argument . If this returns a non-zero exit code, the main method is not performed. If the default method is being executed, this check is performed after the .Va required_* checks and process (non-)existence checks. .It Ar argument Ns Va _postcmd Shell commands to run if running .Ar argument Ns Va _cmd or the default method for .Ar argument returned a zero exit code. .It Va sig_stop Signal to send the processes to stop in the default .Cm stop method. Defaults to .Dv SIGTERM . .It Va sig_reload Signal to send the processes to reload in the default .Cm reload method. Defaults to .Dv SIGHUP . .El .Pp For a given method .Ar argument , if .Ar argument Ns Va _cmd is not defined, then a default method is provided by .Ic run_rc_command : .Bl -column "Argument" "Default Method" -offset indent .It Sy Argument Ta Sy Default method .It Cm start Ta If .Va command is not running and .Ic checkyesno Va rcvar succeeds, start .Va command . .It Cm stop Ta Determine the PIDs of .Va command with .Ic check_pidfile or .Ic check_process (as appropriate), .Ic kill Va sig_stop those PIDs, and run .Ic wait_for_pids on those PIDs. .It Cm reload Ta Similar to .Cm stop , except that it uses .Va sig_reload instead, and does not run .Ic wait_for_pids . Another difference from .Cm stop is that .Cm reload is not provided by default. It can be enabled via .Va extra_commands if appropriate: .Pp .Dl "extra_commands=reload" .It Cm restart Ta Runs the .Cm stop method, then the .Cm start method. .It Cm status Ta Show the PID of .Va command , or some other script specific status operation. .It Cm poll Ta Wait for .Va command to exit. .It Cm rcvar Ta Display which .Xr rc.conf 5 variable is used (if any). This method always works, even if the appropriate .Xr rc.conf 5 variable is set to .Dq Li NO . .El .Pp The following variables are available to the methods (such as .Ar argument Ns Va _cmd ) as well as after .Ic run_rc_command has completed: .Bl -tag -width "rc_service" -offset indent .It Va rc_arg Argument provided to .Ic run_rc_command , after fast and force processing has been performed. .It Va rc_flags Flags to start the default command with. Defaults to .Va ${name}_flags , unless overridden by the environment variable .Sq Ev flags . This variable may be changed by the .Ar argument Ns Va _precmd method. .It Va rc_service Path to the service script being executed, in case it needs to re-invoke itself. .It Va rc_pid PID of .Va command (if appropriate). .It Va rc_fast Not empty if .Dq Li fast prefix was used. .It Va rc_force Not empty if .Dq Li force prefix was used. .El .It Ic run_rc_script Ar file argument Start the script .Ar file with an argument of .Ar argument , and handle the return value from the script. .Pp Various shell variables are unset before .Ar file is started: .Bd -ragged -offset indent .Va name , .Va command , .Va command_args , .Va command_interpreter , .Va extra_commands , .Va pidfile , .Va rcvar , .Va required_dirs , .Va required_files , .Va required_vars , .Ar argument Ns Va _cmd , .Ar argument Ns Va _precmd . .Ar argument Ns Va _postcmd . .Ed .Pp The startup behaviour of .Ar file depends upon the following checks: .Bl -enum .It If .Ar file ends in .Pa .sh , it is sourced into the current shell. .It If .Ar file appears to be a backup or scratch file (e.g., with a suffix of .Pa ~ , # , .OLD , or .Pa .orig ) , ignore it. .It If .Ar file is not executable, ignore it. .It If the .Xr rc.conf 5 variable .Va rc_fast_and_loose is empty, source .Ar file in a sub shell, otherwise source .Ar file into the current shell. .El .It Ic startmsg Oo Fl n Oc Ar message Display a start message to .Va stdout . It should be used instead of .Xr echo 1 . The display of this output can be turned off if the .Xr rc.conf 5 variable .Va rc_startmsgs is set to .Dq Li NO . .It Ic stop_boot Op Ar always Prevent booting to multiuser mode. If the .Va autoboot variable is set to .Ql yes (see .Xr rc 8 to learn more about .Va autoboot ) , or .Ic checkyesno Ar always indicates a truth value, then a .Dv SIGTERM signal is sent to the parent process, which is assumed to be .Xr rc 8 . Otherwise, the shell exits with a non-zero status. .It Ic wait_for_pids Op Ar pid ... Wait until all of the provided .Ar pids do not exist any more, printing the list of outstanding .Ar pids every two seconds. .It Ic warn Ar message Display a warning message to .Va stderr and log it to the system log using .Xr logger 1 . The warning message consists of the script name (from .Va $0 ) , followed by .Dq Li ": WARNING: " , and then .Ar message . .El .Sh FILES .Bl -tag -width "/etc/rc.subr" -compact .It Pa /etc/rc.subr The .Nm file resides in .Pa /etc . .El .Sh SEE ALSO .Xr rc.conf 5 , +.Xr debug.sh 8 , .Xr rc 8 .Sh HISTORY The .Nm script appeared in .Nx 1.3 . The .Xr rc.d 8 support functions appeared in .Nx 1.5 . The .Nm script first appeared in .Fx 5.0 . diff --git a/share/man/man9/VOP_SETLABEL.9 b/share/man/man9/VOP_SETLABEL.9 index e5cf99bebd86..4ab7dd9beaba 100644 --- a/share/man/man9/VOP_SETLABEL.9 +++ b/share/man/man9/VOP_SETLABEL.9 @@ -1,125 +1,125 @@ .\"- .\" Copyright (c) 2021 Robert N. M. Watson .\" 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. .\" .Dd February 27, 2021 .Dt VOP_SETLABEL 9 .Os .Sh NAME .Nm VOP_SETLABEL .Nd persistently store an updated MAC label on a vnode .Sh SYNOPSIS .In sys/param.h .In sys/vnode.h .In security/mac.h .Ft int .Fn VOP_SETLABEL "struct vnode *vp" "label *label" .Sh DESCRIPTION This vnode call is made by .Xr mac 9 file relabeling operation has been authorized, and the filesystem must now be updated. .Ss Single-Label vs. Multi-Label Filesystems Filesystems that do not implement per-file labels -- known as single-label filesystems -- can simply leave the .Xr vnode 9 operation undefined. These filesystems must not set the .Dv MNT_MULTLABEL flag in their .Vt struct mount . .Pp Filesystems that do implement per-vnode label storage -- known as multi-label filesystems -- will set the .Dv MNT_MULTILABEL flag in their .Vt struct mount . The UFS filesystem uses a superblock flag to persisently configure whether a specific filesystem implements a label for each .Xr vnode 9 , and then keys various behaviors on whether that flag is set. .Ss Extended Attributes If the filesystem implements extended attributes, then the MAC Framework's .Fn vop_stdsetlabel_ea function can be used, and maps operations into a series of .Xr VOP_OPENEXTATTR 9 , .Xr VOP_WRITEEXTATTR 9 , and .Xr VOP_CLOSEEXTATTR 9 . .Pp Filesystems will also need to call .Fn mac_vnode_create_extattr when a new filesystem object is created, so that suitable extended attributes can be written out, and .Fn mac_vnode_associate_extattr when a .Xr vnode 9 is associated with a filesystem object for the first time. These utility functions use .Xr VOP_OPENEXTATTR 9 , .Xr VOP_READEXTATTR 9 , .Xr VOP_WRITEEXTATTR 9 , and .Xr VOP_CLOSEEXTATTR 9 as required. .Ss Locking and Crash Safety In all cases, it is important that exclusive .Xr vnode 9 locks be held to prevent concurrent access when a MAC label may not yet be initialized. It is also important that operations are ordered so that a system crash does not leave a file improperly labeled. For example, the extended attribute for a newly created file must be written to disk before the file is linked by its parent directory, so that there is no opportunity for a crash to lead to an unlabeled file. .Sh LOCKS The vnode will be locked on entry and should remain locked on return. .Sh RETURN VALUES If the MAC label is successfully set, then zero is returned. Otherwise, an appropriate error code is returned. .Sh ERRORS .Bl -tag -width Er .It Bq Er EOPNOTSUPP The file system does not support .Fn VOP_SETLABEL . .It Bq Er ENOSPC The file system is out of space. .It Bq Er EROFS The file system is read-only. .El .Pp Depending on the underlying implementation of .Fn VOP_SETLABEL , other errors may also be possible. .Sh SEE ALSO +.Xr mac 9 , +.Xr mount 9 , +.Xr vnode 9 , .Xr VOP_CLOSEEXTATTR 9 , .Xr VOP_OPENEXTATTR 9 , .Xr VOP_READEXTATTR 9 , -.Xr VOP_WRITEXTATTR 9 , -.Xr mac 9 , -.Xr mount 9 , -.Xr vnode 9 +.Xr VOP_WRITEXTATTR 9 .Sh AUTHORS This manual page was written by .An Robert Watson . diff --git a/share/man/man9/cr_bsd_visible.9 b/share/man/man9/cr_bsd_visible.9 index f2d42f3835dc..d16f4bb6dd8f 100644 --- a/share/man/man9/cr_bsd_visible.9 +++ b/share/man/man9/cr_bsd_visible.9 @@ -1,117 +1,117 @@ .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" Copyright (c) 2023 Olivier Certner .\" .\" 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 DEVELOPERS ``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 DEVELOPERS 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 August 18, 2023 .Dt CR_BSD_VISIBLE 9 .Os .Sh NAME .Nm cr_bsd_visible .Nd determine if subjects may see entities according to BSD security policies .Sh SYNOPSIS .In sys/proc.h .Ft int .Fn cr_bsd_visible "struct ucred *u1" "struct ucred *u2" .Sh DESCRIPTION This function determines if a subject with credentials .Fa u1 is denied seeing an object or subject associated to credentials .Fa u2 by the following policies and associated .Xr sysctl 8 knobs: .Bl -tag -width indent .It Va security.bsd.seeotheruids If set to 0, subjects cannot see other subjects or objects if they are not associated with the same real user ID. The corresponding internal function is .Xr cr_canseeotheruids 9 . .It Va security.bsd.seeothergids If set to 0, subjects cannot see other subjects or objects if they are not both a member of at least one common group. The corresponding internal function is .Xr cr_canseeothergids 9 . .It Va security.bsd.see_jail_proc If set to 0, subjects cannot see other subjects or objects that are not associated with the same jail as they are. The corresponding internal function is .Xr cr_canseejailproc 9 . .El .Pp As usual, the superuser (effective user ID 0) is exempt from any of these policies provided that the .Xr sysctl 8 variable .Va security.bsd.suser_enabled is non-zero and no active MAC policy explicitly denies the exemption .Po see .Xr priv_check_cred 9 .Pc . .Pp This function is intended to be used as a helper to implement .Xr cr_cansee 9 and similar functions. .Sh RETURN VALUES This function returns zero if a subject with credentials .Fa u1 may see a subject or object with credentials .Fa u2 by the active above-mentioned policies, or .Er ESRCH otherwise. .Sh ERRORS .Bl -tag -width Er .It Bq Er ESRCH Credentials .Fa u1 and .Fa u2 do not have the same real user ID. .It Bq Er ESRCH Credentials .Fa u1 and .Fa u2 are not members of any common group .Po as determined by .Xr realgroupmember 9 .Pc . .It Bq Er ESRCH Credentials .Fa u1 and .Fa u2 are not in the same jail. .El .Sh SEE ALSO -.Xr cr_canseeotheruids 9 , -.Xr cr_canseeothergids 9 , +.Xr cr_cansee 9 , .Xr cr_canseejailproc 9 , -.Xr priv_check_cred 9 , -.Xr cr_cansee 9 +.Xr cr_canseeothergids 9 , +.Xr cr_canseeotheruids 9 , +.Xr priv_check_cred 9 .Sh AUTHORS This function and its manual page were written by .An Olivier Certner Aq Mt olce.freebsd@certner.fr . diff --git a/share/man/man9/cr_cansee.9 b/share/man/man9/cr_cansee.9 index d5cdfdd6f8e5..a93afb8e5c89 100644 --- a/share/man/man9/cr_cansee.9 +++ b/share/man/man9/cr_cansee.9 @@ -1,83 +1,83 @@ .\" .\" Copyright (c) 2006 Ceri Davies .\" Copyright (c) 2023 Olivier Certner .\" .\" 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 DEVELOPERS ``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 DEVELOPERS 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 August 18, 2023 .Dt CR_CANSEE 9 .Os .Sh NAME .Nm cr_cansee .Nd "determine visibility of objects given their user credentials" .Sh SYNOPSIS .In sys/proc.h .Ft int .Fn cr_cansee "struct ucred *u1" "struct ucred *u2" .Sh DESCRIPTION This function determines if a subject with credential .Fa u1 can see a subject or object associated to credential .Fa u2 . .Pp Specific types of subjects may need to submit to additional or different restrictions. As an example, for processes, see .Xr p_cansee 9 , which calls this function. .Pp The implementation relies on .Xr cr_bsd_visible 9 and consequently the .Xr sysctl 8 variables referenced in its manual page influence the result. .Sh RETURN VALUES This function returns zero if the subject with credential .Fa u1 can .Dq see the subject or object with credential .Fa u2 , or .Er ESRCH otherwise. .Sh ERRORS .Bl -tag -width Er .It Bq Er ESRCH The subject with credential .Fa u1 has been jailed and the subject or object with credential .Fa u2 does not belong to the same jail or one of its sub-jails, as determined by .Xr prison_check 9 . .It Bq Er ESRCH The MAC subsystem denied visibility. .It Bq Er ESRCH .Xr cr_bsd_visible 9 denied visibility according to the BSD security policies in force. .El .Sh SEE ALSO -.Xr prison_check 9 , -.Xr mac 9 , .Xr cr_bsd_visible 9 , -.Xr p_cansee 9 +.Xr mac 9 , +.Xr p_cansee 9 , +.Xr prison_check 9 diff --git a/share/man/man9/cr_canseeothergids.9 b/share/man/man9/cr_canseeothergids.9 index 109d41a8545d..530335d5d5f7 100644 --- a/share/man/man9/cr_canseeothergids.9 +++ b/share/man/man9/cr_canseeothergids.9 @@ -1,83 +1,83 @@ .\" .\" Copyright (c) 2003 Joseph Koshy .\" Copyright (c) 2023 Olivier Certner .\" .\" All rights reserved. .\" .\" This program is free software. .\" .\" 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 DEVELOPERS ``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 DEVELOPERS 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 August 18, 2023 .Dt CR_CANSEEOTHERGIDS 9 .Os .Sh NAME .Nm cr_canseeothergids .Nd determine if subjects may see entities in a disjoint group set .Sh SYNOPSIS .Ft int .Fn cr_canseeothergids "struct ucred *u1" "struct ucred *u2" .Sh DESCRIPTION .Bf -emphasis This function is internal. Its functionality is integrated into the function .Xr cr_bsd_visible 9 , which should be called instead. .Ef .Pp This function checks if a subject associated to credentials .Fa u1 is denied seeing a subject or object associated to credentials .Fa u2 by a policy that requires both credentials to have at least one group in common. For this determination, the real and supplementary group IDs are used, but not the effective group IDs, as per .Xr realgroupmember 9 . .Pp This policy is active if and only if the .Xr sysctl 8 variable .Va security.bsd.see_other_gids is set to zero. .Pp As usual, the superuser (effective user ID 0) is exempt from this policy provided that the .Xr sysctl 8 variable .Va security.bsd.suser_enabled is non-zero and no active MAC policy explicitly denies the exemption .Po see .Xr priv_check_cred 9 .Pc . .Sh RETURN VALUES The .Fn cr_canseeothergids function returns 0 if the policy is disabled, the credentials share at least one common group, or if .Fa u1 has privilege exempting it from the policy. Otherwise, it returns .Er ESRCH . .Sh SEE ALSO .Xr cr_bsd_visible 9 , -.Xr realgroupmember 9 , -.Xr priv_check_cred 9 +.Xr priv_check_cred 9 , +.Xr realgroupmember 9 diff --git a/share/man/man9/groupmember.9 b/share/man/man9/groupmember.9 index b7865a35fdc9..db2138ef088a 100644 --- a/share/man/man9/groupmember.9 +++ b/share/man/man9/groupmember.9 @@ -1,79 +1,79 @@ .\" .\" Copyright (C) 2001 Chad David . All rights reserved. .\" Copyright (C) 2023 Olivier Certner .\" .\" 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 August 18, 2023 .Dt GROUPMEMBER 9 .Os .Sh NAME .Nm groupmember .Nd checks if credentials mandate some group membership .Sh SYNOPSIS .In sys/param.h .In sys/ucred.h .Ft bool .Fn groupmember "gid_t gid" "struct ucred *cred" .Ft bool .Fn realgroupmember "gid_t gid" "struct ucred *cred" .Sh DESCRIPTION The .Fn groupmember function checks if credentials .Fa cred indicate that the associated subject or object is a member of the group designated by the group ID .Fa gid . .Pp Considered groups in .Fa cred are the effective and supplementary groups. The real group is not taken into account. .Pp Function .Fn realgroupmember works the same except that it considers instead the real and supplementary groups, and not the effective one. .Sh RETURN VALUES The .Fn groupmember and .Fn realgroupmember functions return .Dv true if the given credentials indicate membership of the group .Fa gid , or .Dv false otherwise. .Sh SEE ALSO -.Xr getgroups 2 +.Xr getgroups 2 , .Xr setgroups 2 .Sh AUTHORS This manual page was initially written by .An -nosplit .An Chad David Aq Mt davidc@acns.ab.ca and was revised by .An Olivier Certner Aq Mt olce.freebsd@certner.fr . diff --git a/share/man/man9/p_candebug.9 b/share/man/man9/p_candebug.9 index c824db974154..be4710f0a15f 100644 --- a/share/man/man9/p_candebug.9 +++ b/share/man/man9/p_candebug.9 @@ -1,145 +1,145 @@ .\" .\" Copyright (c) 2003 Joseph Koshy .\" Copyright (c) 2023 Olivier Certner .\" .\" All rights reserved. .\" .\" This program is free software. .\" .\" 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 DEVELOPERS ``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 DEVELOPERS 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 August 18, 2023 .Dt P_CANDEBUG 9 .Os .Sh NAME .Nm p_candebug .Nd determine debuggability of a process .Sh SYNOPSIS .In sys/param.h .In sys/proc.h .Ft int .Fn p_candebug "struct thread *td" "struct proc *p" .Sh DESCRIPTION This function determines if a given process .Fa p is debuggable by some thread .Fa td . .Pp The following .Xr sysctl 8 variables directly influence the behaviour of .Fn p_candebug : .Bl -tag -width indent .It Va security.bsd.unprivileged_proc_debug Must be set to a non-zero value to allow unprivileged processes access to the kernel's debug facilities. .It Va kern.securelevel Debugging of the init process is not allowed if this variable is .Li 1 or greater. .El .Pp Other such variables indirectly influence it; see .Xr cr_bsd_visible 9 . .Sh RETURN VALUES The .Fn p_candebug function returns .Li 0 if the process denoted by .Fa p is debuggable by thread .Fa td , or a non-zero error return value otherwise. .Sh ERRORS .Bl -tag -width Er .It Bq Er EPERM An unprivileged process attempted to debug another process but the system is configured to deny it .Po see .Xr sysctl 8 variable .Va security.bsd.unprivileged_proc_debug above .Pc . .It Bq Er ESRCH Thread .Fa td has been jailed and the process to debug does not belong to the same jail or one of its sub-jails, as determined by .Xr prison_check 9 . .It Bq Er ESRCH .Xr cr_bsd_visible 9 denied visibility according to the BSD security policies in force. .It Bq Er EPERM Thread .Fa td lacks superuser credentials and its (effective) group set is not a superset of process .Fa p Ns 's whole group set .Pq "including real, effective and saved group IDs" . .It Bq Er EPERM Thread .Fa td lacks superuser credentials and its (effective) user ID does not match all user IDs of process .Fa p . .It Bq Er EPERM Thread .Fa td lacks superuser credentials and process .Fa p is executing a set-user-ID or set-group-ID executable. .It Bq Er EPERM Process .Fa p denotes the initial process .Fn initproc and the .Xr sysctl 8 variable .Va kern.securelevel is greater than zero. .It Bq Er EBUSY Process .Fa p is in the process of being .Fn exec Ns 'ed. .It Bq Er EPERM Process .Fa p denied debuggability .Po see .Xr procctl 2 , command .Dv PROC_TRACE_CTL .Pc . .El .Sh SEE ALSO -.Xr prison_check 9 , -.Xr mac 9 , -.Xr cr_bsd_visible 9 , .Xr procctl 2 , -.Xr p_cansee 9 +.Xr cr_bsd_visible 9 , +.Xr mac 9 , +.Xr p_cansee 9 , +.Xr prison_check 9 diff --git a/share/man/man9/p_cansee.9 b/share/man/man9/p_cansee.9 index 9fdce460dfea..7de0c9654995 100644 --- a/share/man/man9/p_cansee.9 +++ b/share/man/man9/p_cansee.9 @@ -1,79 +1,79 @@ .\" .\" Copyright (c) 2003 Joseph Koshy .\" Copyright (c) 2006 Ceri Davies .\" .\" 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 DEVELOPERS ``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 DEVELOPERS 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 August 18, 2023 .Dt P_CANSEE 9 .Os .Sh NAME .Nm p_cansee .Nd determine visibility of a process .Sh SYNOPSIS .In sys/proc.h .Ft int .Fn p_cansee "struct thread *td" "struct proc *p" .Sh DESCRIPTION This function determines if a given process .Fa p is visible to the thread .Fa td , where the notion of .Dq visibility may be read as .Dq "awareness of existence" . .Pp This function explicitly allows a thread to always see its own process, even with pending credentials changes .Po see .Xr ucred 9 .Pc . Otherwise, it simply defers to .Xr cr_cansee 9 . .Sh RETURN VALUES The .Fn p_cansee function returns .Li 0 if the process denoted by .Fa p is visible by thread .Fa td , or ESRCH otherwise. .Sh ERRORS .Bl -tag -width Er .It Bq Er ESRCH Thread .Fa td is not part of process .Fa p and cannot see it as determined by .Xr cr_cansee 9 . .El .Sh SEE ALSO -.Xr ucred 9 , .Xr cr_cansee 9 , -.Xr p_candebug 9 +.Xr p_candebug 9 , +.Xr ucred 9 diff --git a/share/man/man9/rtentry.9 b/share/man/man9/rtentry.9 index f9d2b1668da5..3f2e6c9ef656 100644 --- a/share/man/man9/rtentry.9 +++ b/share/man/man9/rtentry.9 @@ -1,249 +1,249 @@ .\" .\" Copyright 1996 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. .\" .Dd March 5, 2014 .Dt RTENTRY 9 .Os .Sh NAME .Nm rtentry .Nd structure of an entry in the kernel routing table .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .In net/route.h .Sh DESCRIPTION The kernel provides a common mechanism by which all protocols can store and retrieve entries from a central table of routes. Parts of this mechanism are also used to interact with user-level processes by means of a socket in the .Xr route 4 pseudo-protocol family. The .In net/route.h header file defines the structures and manifest constants used in this facility. .Pp The basic structure of a route is defined by .Vt "struct rtentry" , which includes the following fields: .Bl -tag -offset indent -width 6n .It Vt "struct radix_node rt_nodes[2]" ; Glue used by the radix-tree routines. These members also include in their substructure the key (i.e., destination address) and mask used when the route was created. The .Fn rt_key rt and .Fn rt_mask rt macros can be used to extract this information (in the form of a .Vt "struct sockaddr *" ) given a .Vt "struct rtentry *" . .It Vt "struct sockaddr *rt_gateway" ; The .Dq target of the route, which can either represent a destination in its own right (some protocols will put a link-layer address here), or some intermediate stop on the way to that destination (if the .Dv RTF_GATEWAY flag is set). .It Vt "int rt_flags" ; See below. If the .Dv RTF_UP flag is not present, the .Fn rtfree function will delete the route from the radix tree when the last reference drops. .It Vt "int rt_refcnt" ; Route entries are reference-counted; this field indicates the number of external (to the radix tree) references. .It Vt "struct ifnet *rt_ifp" ; .It Vt "struct ifaddr *rt_ifa" ; These two fields represent the .Dq answer , as it were, to the question posed by a route lookup; that is, they name the interface and interface address to be used in sending a packet to the destination or set of destinations which this route represents. .It Vt "u_long rt_mtu"; See description of rmx_mtu below. .It Vt "u_long rt_weight"; See description of rmx_weight below. .It Vt "u_long rt_expire"; See description of rmx_expire below. .It Vt "counter64_t rt_pksent"; See description of rmx_pksent below. .It Vt "struct rtentry *rt_gwroute" ; This member is a reference to a route whose destination is .Va rt_gateway . It is only used for .Dv RTF_GATEWAY routes. .It Vt "struct mtx rt_mtx" ; Mutex to lock this routing entry. .El .Pp The following flag bits are defined: .Bl -tag -offset indent -width ".Dv RTF_BLACKHOLE" -compact .It Dv RTF_UP The route is not deleted. .It Dv RTF_GATEWAY The route points to an intermediate destination and not the ultimate recipient; the .Va rt_gateway and .Va rt_gwroute fields name that destination. .It Dv RTF_HOST This is a host route. .It Dv RTF_REJECT The destination is presently unreachable. This should result in an .Er EHOSTUNREACH error from output routines. .It Dv RTF_DYNAMIC This route was created dynamically by .Fn rtredirect . .It Dv RTF_MODIFIED This route was modified by .Fn rtredirect . .It Dv RTF_DONE Used only in the .Xr route 4 protocol, indicating that the request was executed. .It Dv RTF_XRESOLVE When this route is returned as a result of a lookup, send a report on the .Xr route 4 interface requesting that an external process perform resolution for this route. .It Dv RTF_STATIC Indicates that this route was manually added by means of the .Xr route 8 command. .It Dv RTF_BLACKHOLE Requests that output sent via this route be discarded. .It Dv RTF_PROTO1 .It Dv RTF_PROTO2 .It Dv RTF_PROTO3 Protocol-specific. .It Dv RTF_PINNED Indicates that this route is immutable to a routing protocol. .It Dv RTF_LOCAL Indicates that the destination of this route is an address configured as belonging to this system. .It Dv RTF_BROADCAST Indicates that the destination is a broadcast address. .It Dv RTF_MULTICAST Indicates that the destination is a multicast address. .El .Pp Several metrics are supplied in .Vt "struct rt_metrics" passed with routing control messages via .Xr route 4 API. Currently only .Vt rmx_mtu , rmx_expire , and .Vt rmx_pksent metrics are supplied. All others are ignored. .Pp The following metrics are defined by .Vt "struct rt_metrics" : .Bl -tag -offset indent -width 6n .It Vt "u_long rmx_locks" ; Flag bits indicating which metrics the kernel is not permitted to dynamically modify. .It Vt "u_long rmx_mtu" ; MTU for this path. .It Vt "u_long rmx_hopcount" ; Number of intermediate systems on the path to this destination. .It Vt "u_long rmx_expire" ; The time (a la .Xr time 3 ) at which this route should expire, or zero if it should never expire. It is the responsibility of individual protocol suites to ensure that routes are actually deleted once they expire. .It Vt "u_long rmx_recvpipe" ; Nominally, the bandwidth-delay product for the path .Em from the destination .Em to this system. In practice, this value is used to set the size of the receive buffer (and thus the window in sliding-window protocols like .Tn TCP ) . .It Vt "u_long rmx_sendpipe" ; As before, but in the opposite direction. .It Vt "u_long rmx_ssthresh" ; The slow-start threshold used in .Tn TCP congestion-avoidance. .It Vt "u_long rmx_rtt" ; The round-trip time to this destination, in units of .Dv RMX_RTTUNIT per second. .It Vt "u_long rmx_rttvar" ; The average deviation of the round-trip time to this destination, in units of .Dv RMX_RTTUNIT per second. .It Vt "u_long rmx_pksent" ; A count of packets successfully sent via this route. .It Vt "u_long rmx_filler[4]" ; .\" XXX badly named Empty space available for protocol-specific information. .El .Sh SEE ALSO .Xr route 4 , -.Xr route 8 , +.Xr route 8 .Sh HISTORY The .Vt rtentry structure first appeared in .Bx 4.2 . The radix-tree representation of the routing table and the .Vt rt_metrics structure first appeared in .Bx 4.3 reno . .Sh AUTHORS This manual page was written by .An Garrett Wollman . .Sh BUGS There are a number of historical relics remaining in this interface. The .Va rt_gateway and .Va rmx_filler fields could be named better. diff --git a/tools/tools/ether_reflect/ether_reflect.1 b/tools/tools/ether_reflect/ether_reflect.1 index 617ee0b78378..9e94661211aa 100644 --- a/tools/tools/ether_reflect/ether_reflect.1 +++ b/tools/tools/ether_reflect/ether_reflect.1 @@ -1,111 +1,111 @@ .\" Copyright (c) 2008 George V. Neville-Neil .\" 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. .\" .Dd December 23, 2008 .Dt ETHER_REFLECT 1 .Os .Sh NAME .Nm ether_reflect .Nd "reflect ethernet packets" .Sh SYNOPSIS .Nm .Op Fl a Ar ethernet address .Op Fl e Ar ethertype .Op Fl i Ar interface .Op Fl t Ar timeout .Op Fl p .Op Fl d .Sh DESCRIPTION The .Nm command implements a simple ethernet packet reflector using the .Xr pcap 3 library and .Xr bpf 4 , the Berkeley Packet Filter. The program is useful primarily to test the low level round trip time of packets through an Ethernet interface and/or a switch. Network protocols, such as IP, and the network stack in general are never invoked, only the device driver that implements the particular interface is executed. As the .Nm command uses the .Xr bpf 4 device the user must have root privileges to execute this program. .Pp The options are as follows: .Bl -tag -width ".Fl d Ar argument" .It Fl a Ar address Instead of reversing the ethernet destination and source addresses supply a different destination ethernet address for each packet received. .It Fl e Ar ether type Use a different ethertype than the default, 0x8822, which is the IEEE ether type for driver testing. .It Fl i Ar interface Network interface, which can be found with ifconfig(1). .It Fl t Ar timeout The time, in milliseconds, to wait for a packet. Lower times decrease latency at the cost of CPU. .It Fl p Set the device into promiscuous mode before testing. This is not usually necessary. .It Fl d Debug output. Print various small pieces of debug information. .El .Sh EXAMPLES The following is an example of a typical usage of the .Nm command: .Pp .Dl "ether_reflect -i em0 -t 1" .Pp Reflect all test packets, those with an ether type of 0x8822, which are seen on ineterface em0. The timeout is 1 millisecond. .Pp .Dl "ether_reflect -i em0 -a 00:00:00:aa:bb:cc -t 1" .Pp Rewrite the destination address in each packet to 00:00:00:aa:bb:cc before reflecting the packet. .Sh SEE ALSO .Xr tcpdump 1 , -.Xr bpf 4 , .Xr pcap 3 , +.Xr bpf 4 , .Xr ifconfig 8 .Sh HISTORY The .Nm program first appeared in .Fx 8.0 . .Sh AUTHORS This manual page was written by .An George V. Neville-Neil Aq Mt gnn@FreeBSD.org . .Sh BUGS Should be reported to the author or to .Aq Mt net@FreeBSD.org . diff --git a/usr.bin/beep/beep.1 b/usr.bin/beep/beep.1 index 29988c5b271d..732f2ae261cd 100644 --- a/usr.bin/beep/beep.1 +++ b/usr.bin/beep/beep.1 @@ -1,82 +1,82 @@ .\"- .\" Copyright (c) 2021 Hans Petter Selasky .\" .\" 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. .\" .Dd November 4, 2021 .Dt beep 1 .Os .Sh NAME .Nm beep .Nd play a beep sound .Sh SYNOPSIS .Nm .Op Fl F Ar frequency .Op Fl D Ar duration_ms .Op Fl r Ar sample_rate_hz .Op Fl d Ar oss_device .Op Fl g Ar gain .Op Fl B .Op Fl h .Sh DESCRIPTION The .Nm utility is used to playback a beep on the soundcard. .Pp The options are as follows: .Bl -tag -width "-f device" .It Fl F Sets the center frequency of the beep in Hz. The default is 440 Hz . .It Fl D Sets the duration of the beep in milliseconds. The default is 150 ms . .It Fl d Sets the soundcard to use. The default is /dev/dsp . .It Fl r Sets the soundcard samplerate in Hz. The default is 48000 Hz. .It Fl g Sets the waveform gain, between 0 and 100 inclusively. The default is 75. .It Fl B Runs the .Nm utility in the background. .It Fl h Display summary of options. .El .Sh EXAMPLES .Pp Playback default beep sound using /dev/dsp . .Bl -tag -width Ds -offset indent .It $ beep .El .Sh SEE ALSO .Xr mixer 3 , -.Xr sound 4 , +.Xr sound 4 .Sh HISTORY The .Nm utility first appeared in FreeBSD 14.0. .Sh AUTHORS .An Hans Petter Selasky Aq Mt hselasky@FreeBSD.org diff --git a/usr.bin/gzip/gzip.1 b/usr.bin/gzip/gzip.1 index afb1147f3dfe..6f1a99a15b91 100644 --- a/usr.bin/gzip/gzip.1 +++ b/usr.bin/gzip/gzip.1 @@ -1,246 +1,246 @@ .\" $NetBSD: gzip.1,v 1.31 2018/10/26 22:10:15 christos Exp $ .\" .\" Copyright (c) 1997, 2003, 2004, 2008, 2009, 2015, 2017 Matthew R. Green .\" 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. .Dd November 2, 2022 .Dt GZIP 1 .Os .Sh NAME .Nm gzip , .Nm gunzip , .Nm zcat .Nd compression/decompression tool using Lempel-Ziv coding (LZ77) .Sh SYNOPSIS .Nm .Op Fl cdfhkLlNnqrtVv .Op Fl S Ar suffix .Ar file .Oo .Ar file Oo ... .Oc .Oc .Nm gunzip .Op Fl cfhkLNqrtVv .Op Fl S Ar suffix .Ar file .Oo .Ar file Oo ... .Oc .Oc .Nm zcat .Op Fl fhV .Ar file .Oo .Ar file Oo ... .Oc .Oc .Sh DESCRIPTION The .Nm program compresses and decompresses files using Lempel-Ziv coding (LZ77). If no .Ar files are specified, .Nm will compress from standard input, or decompress to standard output. When in compression mode, each .Ar file will be replaced with another file with the suffix, set by the .Fl S Ar suffix option, added, if possible. .Pp In decompression mode, each .Ar file will be checked for existence, as will the file with the suffix added. Each .Ar file argument must contain a separate complete archive; when multiple .Ar files are indicated, each is decompressed in turn. .Pp In the case of .Nm gzcat the resulting data is then concatenated in the manner of .Xr cat 1 . .Pp If invoked as .Nm gunzip then the .Fl d option is enabled. If invoked as .Nm zcat or .Nm gzcat then both the .Fl c and .Fl d options are enabled. .Pp This version of .Nm is also capable of decompressing files compressed using .Xr compress 1 , .Xr bzip2 1 , .Ar lzip , .Xr zstd 1 , or .Xr xz 1 . .Sh OPTIONS The following options are available: .Bl -tag -width XXrXXXrecursiveX .It Fl 1 , Fl Fl fast .It Fl 2 , 3 , 4 , 5 , 6 , 7 , 8 .It Fl 9 , Fl Fl best These options change the compression level used, with the .Fl 1 option being the fastest, with less compression, and the .Fl 9 option being the slowest, with optimal compression. The default compression level is 6. .It Fl c , Fl Fl stdout , Fl Fl to-stdout This option specifies that output will go to the standard output stream, leaving files intact. .It Fl d , Fl Fl decompress , Fl Fl uncompress This option selects decompression rather than compression. .It Fl f , Fl Fl force This option turns on force mode. This allows files with multiple links, symbolic links to regular files, overwriting of pre-existing files, reading from or writing to a terminal, and when combined with the .Fl c option, allowing non-compressed data to pass through unchanged. .It Fl h , Fl Fl help This option prints a usage summary and exits. .It Fl k , Fl Fl keep This option prevents .Nm from deleting input files after (de)compression. .It Fl L , -license This option prints .Nm license. .It Fl l , Fl Fl list This option displays information about the file's compressed and uncompressed size, ratio, uncompressed name. With the .Fl v option, it also displays the compression method, CRC, date and time embedded in the file. .It Fl N , Fl Fl name This option causes the stored filename in the input file to be used as the output file. .It Fl n , Fl Fl no-name This option stops the filename and timestamp from being stored in the output file. .It Fl q , Fl Fl quiet With this option, no warnings or errors are printed. .It Fl r , Fl Fl recursive This option is used to .Nm the files in a directory tree individually, using the .Xr fts 3 library. .It Fl S Ar suffix , Fl Fl suffix Ar suffix This option changes the default suffix from .gz to .Ar suffix . .It Fl t , Fl Fl test This option will test compressed files for integrity. .It Fl V , Fl Fl version This option prints the version of the .Nm program. .It Fl v , Fl Fl verbose This option turns on verbose mode, which prints the compression ratio for each file compressed. .El .Sh ENVIRONMENT If the environment variable .Ev GZIP is set, it is parsed as a white-space separated list of options handled before any options on the command line. Options on the command line will override anything in .Ev GZIP . .Sh EXIT STATUS The .Nm utility exits 0 on success, 1 on errors, and 2 if a warning occurs. .Sh SIGNALS .Nm responds to the following signals: .Bl -tag -width indent .It Dv SIGINFO Report progress to standard error. .El .Sh SEE ALSO .Xr bzip2 1 , .Xr compress 1 , -.Xr zstd 1 , .Xr xz 1 , +.Xr zstd 1 , .Xr fts 3 , .Xr zlib 3 .Sh HISTORY The .Nm program was originally written by Jean-loup Gailly, licensed under the GNU Public Licence. Matthew R. Green wrote a simple front end for .Nx 1.3 distribution media, based on the freely re-distributable zlib library. It was enhanced to be mostly feature-compatible with the original GNU .Nm program for .Nx 2.0 . .Pp This implementation of .Nm was ported based on the .Nx .Nm version 20181111, and first appeared in .Fx 7.0 . .Sh AUTHORS .An -nosplit This implementation of .Nm was written by .An Matthew R. Green Aq Mt mrg@eterna.com.au with unpack support written by .An Xin LI Aq Mt delphij@FreeBSD.org . .Sh BUGS According to RFC 1952, the recorded file size is stored in a 32-bit integer, therefore, it cannot represent files larger than 4GB. This limitation also applies to .Fl l option of .Nm utility. diff --git a/usr.bin/mdo/mdo.1 b/usr.bin/mdo/mdo.1 index 115ce44f4531..ae89481ddb2b 100644 --- a/usr.bin/mdo/mdo.1 +++ b/usr.bin/mdo/mdo.1 @@ -1,44 +1,44 @@ .\"- .\" Copyright(c) 2024 Baptiste Daroussin .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" .Dd May 22, 2024 .Dt MDO 1 .Os .Sh NAME .Nm mdo .Nd execute commands as another user .Sh SYNOPSIS .Nm .Op Fl u Ar username .Op Fl i .Op command Op args .Sh DESCRIPTION The .Nm utility executes the specified .Ar command as user .Ar username . .Pp If no .Ar username is provided it defaults to the .Va root user. If no .Ar command is specified, it will execute the shell specified as .Va SHELL environnement variable, falling back on .Pa /bin/sh . .Pp The .Fl i option can be used to only call .Fn setuid and keep the group from the calling user. .Sh SEE ALSO -.Xr su 1 +.Xr su 1 , .Xr mac_do 4 diff --git a/usr.bin/msgs/msgs.1 b/usr.bin/msgs/msgs.1 index a3a25257ffc7..9d685e12416b 100644 --- a/usr.bin/msgs/msgs.1 +++ b/usr.bin/msgs/msgs.1 @@ -1,231 +1,231 @@ .\" Copyright (c) 1980, 1990, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)msgs.1 8.2 (Berkeley) 4/28/95 .\" .Dd August 8, 2018 .Dt MSGS 1 .Os .Sh NAME .Nm msgs .Nd system messages and junk mail program .Sh SYNOPSIS .Nm .Op Fl fhlpq .Op Ar number .Op Ar \-number .Nm .Op Fl s .Nm .Op Fl c .Op \-days .Sh DESCRIPTION The .Nm utility is used to read system messages. These messages are sent by mailing to the login `msgs' and should be short pieces of information which are suitable to be read once by most users of the system. .Pp The .Nm utility is normally invoked each time you login, by placing it in the file .Pa .login (or .Pa .profile if you use .Xr sh 1 ) . It will then prompt you with the source and subject of each new message. If there is no subject line, the first few non-blank lines of the message will be displayed. If there is more to the message, you will be told how long it is and asked whether you wish to see the rest of the message. The possible responses are: .Bl -tag -width Fl .It Fl y Type the rest of the message. .It Ic RETURN Synonym for y. .It Fl n Skip this message and go on to the next message. .It Fl Redisplay the last message. .It Fl q Drop out of .Nm ; the next time .Nm will pick up where it last left off. .It Fl s Append the current message to the file ``Messages'' in the current directory; `s\-' will save the previously displayed message. A `s' or `s\-' may be followed by a space and a file name to receive the message replacing the default ``Messages''. .It Fl m A copy of the specified message is placed in a temporary mailbox and .Xr mail 1 is invoked on that mailbox. Both `m' and `s' accept a numeric argument in place of the `\-'. .El .Pp The .Nm utility keeps track of the next message you will see by a number in the file .Pa \&.msgsrc in your home directory. In the directory .Pa /var/msgs it keeps a set of files whose names are the (sequential) numbers of the messages they represent. The file .Pa /var/msgs/bounds shows the low and high number of the messages in the directory so that .Nm can quickly determine if there are no messages for you. If the contents of .Pa bounds is incorrect it can be fixed by removing it; .Nm will make a new .Pa bounds file the next time it is run with the .Fl s option. If .Nm is run with any option other than .Fl s , an error will be displayed if .Pa /var/msgs/bounds does not exist. .Pp The .Fl s option is used for setting up the posting of messages. The line .Pp .Dl msgs: \&"\&| /usr/bin/msgs \-s\&" .Pp should be included in .Pa /etc/mail/aliases (see .Xr newaliases 1 ) to enable posting of messages. .Pp The .Fl c option is used for performing cleanup on .Pa /var/msgs . A shell script entry to run .Nm with the .Fl c option should be placed in .Pa /etc/periodic/daily (see .Xr periodic 8 ) to run every night. This will remove all messages over 21 days old. A different expiration may be specified on the command line to override the default. You must be the superuser to use this option. .Pp Options when reading messages include: .Bl -tag -width Fl .It Fl f Do not say ``No new messages.''. This is useful in a .Pa .login file since this is often the case here. .It Fl q Queries whether there are messages, printing ``There are new messages.'' if there are. The command ``msgs \-q'' is often used in login scripts. .It Fl h Print the first part of messages only. .It Fl l Cause only locally originated messages to be reported. .It Ar num A message number can be given on the command line, causing .Nm to start at the specified message rather than at the next message indicated by your .Pa \&.msgsrc file. Thus .Pp .Dl msgs \-h 1 .Pp prints the first part of all messages. .It Ar \-number Start .Ar number messages back from the one indicated in the .Pa \&.msgsrc file, useful for reviews of recent messages. .It Fl p Pipe long messages through .Xr less 1 . .El .Pp Within .Nm you can also go to any specific message by typing its number when .Nm requests input as to what to do. .Sh ENVIRONMENT The .Nm utility uses the .Ev HOME and .Ev TERM environment variables for the default home directory and terminal type. .Sh FILES .Bl -tag -width /var/msgs/* -compact .It Pa /var/msgs/* database .It Pa ~/.msgsrc number of next message to be presented .El .Sh SEE ALSO -.Xr mail 1 , .Xr less 1 , +.Xr mail 1 , .Xr aliases 5 , .Xr periodic 8 .Sh HISTORY The .Nm command appeared in .Bx 3.0 . diff --git a/usr.bin/posixmqcontrol/posixmqcontrol.1 b/usr.bin/posixmqcontrol/posixmqcontrol.1 index ec60230aac6e..6ed36ceffa0a 100644 --- a/usr.bin/posixmqcontrol/posixmqcontrol.1 +++ b/usr.bin/posixmqcontrol/posixmqcontrol.1 @@ -1,180 +1,180 @@ .\"- .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" Copyright (c) 2024 Rick Parrish . .\" .\" 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 February 19, 2024 .Dt POSIXMQCONTROL 1 .Os .Sh NAME .Nm posixmqcontrol .Nd Control POSIX mqueuefs message queues .Sh SYNOPSIS .Nm .Ar create .Fl q Ar queue .Fl s Ar size .Fl d Ar depth .Op Fl m Ar mode .Op Fl g Ar group .Op Fl u Ar user .Nm .Ar info .Fl q Ar queue .Nm .Ar recv .Fl q Ar queue .Nm .Ar rm .Fl q Ar queue .Nm .Ar send .Fl q Ar queue .Fl c Ar content .Op Fl p Ar priority .Sh DESCRIPTION The .Nm command allows separating POSIX message queue administration from application stack. Defining and adjusting queue attributes can be done without touching application code. It allows creating queues, inspecting queue metadata, altering group and user access to queues, dumping queue contents, and unlinking queues. .Pp Unlinking removes the name from the system and frees underlying memory. .Pp The maximum message size, maximum queue size, and current queue size are displayed by the .Ic info subcommand. This output is similar to running .Ic cat on a mqueuefs queue mounted under a mount point. This utility requires the .Ic mqueuefs kernel module to be loaded but does not require .Ic mqueuefs to be mounted as a file system. .Pp The following subcommands are provided: .Bl -tag -width truncate .It Ic create Create the named queues, if they do not already exist. More than one queue name may be created. The same maximum queue depth and maximum message size are used to create all queues. If a queue exists, then depth and size are optional. .Pp The required .Ar size and .Ar depth arguments specify the maximum message size (bytes per message) and maximum queue size (depth or number of messages in the queue). The optional numerical .Ar mode argument specifies the initial access mode. If the queue exists but does not match the requested size and depth, this utility will attempt to recreate the queue by first unlinking and then creating it. This will fail if the queue is not empty or is opened by other processes. .It Ic rm Unlink the queues specified - one attempt per queue. Failure to unlink one queue does not stop this sub-command from attempting to unlink the others. .It Ic info For each named queue, dispay the maximum message size, maximum queue size, current queue depth, user owner id, group owner id, and mode permission bits. .It Ic recv Wait for a message from a single named queue and display the message to standard output. .It Ic send Send messages to one or more named queues. If multiple messages and multiple queues are specified, the utility attempts to send all messages to all queues. The optional -p priority, if omitted, defaults to MQ_PRIO_MAX / 2 or medium priority. .El .Sh NOTES A change of queue geometry (maximum message size and/or maximum number of messages) requires destroying and re-creating the queue. As a safety feature, the create subcommand refuses to destroy a non-empty queue. If you use the rm subcommand to destroy a queue, any queued messages are lost. To avoid down-time when altering queue attributes, consider creating a new queue and configure reading applications to drain both new and old queues. Retire the old queue once all writers have been updated to write to the new queue. .Sh EXIT STATUS .Ex -std .Bl -bullet .It EX_NOTAVAILABLE usually means the mqueuefs kernel module is not loaded. .It EX_USAGE reports one or more incorrect parameters. .El .Sh EXAMPLES .Bl -bullet .It To retrieve the current message from a named queue, .Pa /1 , use the command .Dl "posixmqcontrol recv -q /1" .It To create a queue with the name .Pa /2 with maximum message size 100 and maximum queue depth 10, use the command .Dl "posixmqcontrol create -q /2 -s 100 -d 10" .It To send a message to a queue with the name .Pa /3 use the command .Dl "posixmqcontrol send -q /3 -c 'some choice words.'" .It To examine attributes of a queue named .Pa /4 use the command .Dl "posixmqcontrol info -q /4" .El .Sh SEE ALSO -.Xr mq_open 2 , .Xr mq_getattr 2 , +.Xr mq_open 2 , .Xr mq_receive 2 , .Xr mq_send 2 , .Xr mq_setattr 2 , .Xr mq_unlink 2 , .Xr mqueuefs 5 .Sh BUGS mq_timedsend and mq_timedrecv are not implemented. info reports a worst-case estimate for QSIZE. .Sh HISTORY The .Nm command appeared in .Fx 15.0 . .Sh AUTHORS The .Nm command and this manual page were written by .An Rick Parrish Aq Mt unitrunker@unitrunker.net. diff --git a/usr.sbin/i2c/i2c.8 b/usr.sbin/i2c/i2c.8 index 95aba8e5d105..3415b614f87d 100644 --- a/usr.sbin/i2c/i2c.8 +++ b/usr.sbin/i2c/i2c.8 @@ -1,224 +1,224 @@ .\" .\" Copyright (C) 2008-2009 Semihalf, Michal Hajduk and Bartlomiej Sieka .\" 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 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. .\" .Dd May 22, 2019 .Dt I2C 8 .Os .Sh NAME .Nm i2c .Nd test I2C bus and slave devices .Sh SYNOPSIS .Nm .Cm -a Ar address .Op Fl f Ar device .Op Fl d Ar r|w .Op Fl w Ar 0|8|16|16LE|16BE .Op Fl o Ar offset .Op Fl c Ar count .Op Fl m Ar tr|ss|rs|no .Op Fl b .Op Fl v .Nm .Cm -h .Nm .Cm -i .Op Fl v .Op Ar cmd ... .Op Ar - .Nm .Cm -r .Op Fl f Ar device .Op Fl v .Nm .Cm -s .Op Fl f Ar device .Op Fl n Ar skip_addr .Op Fl v .Sh DESCRIPTION The .Nm utility can be used to perform raw data transfers (read or write) to devices on an I2C bus. It can also scan the bus for available devices and reset the I2C controller. .Pp The options are as follows: .Bl -tag -width ".Fl d Ar direction" .It Fl a Ar address 7-bit address on the I2C device to operate on (hex). .It Fl b binary mode - when performing a read operation, the data read from the device is output in binary format on stdout. .It Fl c Ar count number of bytes to transfer (decimal). .It Fl d Ar r|w transfer direction: r - read, w - write. Data to be written is read from stdin as binary bytes. .It Fl f Ar device I2C bus to use (default is /dev/iic0). .It Fl i Interpreted mode .It Fl h Help .It Fl m Ar tr|ss|rs|no addressing mode, i.e., I2C bus operations performed after the offset for the transfer has been written to the device and before the actual read/write operation. .Bl -tag -compact -offset indent .It Va tr complete-transfer .It Va ss stop then start .It Va rs repeated start .It Va no none .El Some I2C bus hardware does not provide control over the individual start, repeat-start, and stop operations. Such hardware can only perform a complete transfer of the offset and the data as a single operation. The .Va tr mode creates control structures describing the transfer and submits them to the driver as a single complete transaction. This mode works on all types of I2C hardware. .It Fl n Ar skip_addr address(es) to be skipped during bus scan. One or more addresses ([0x]xx) or ranges of addresses ([0x]xx-[0x]xx or [0x]xx..[0x]xx) separated by commas or colons. .It Fl o Ar offset offset within the device for data transfer (hex). The default is zero. Use .Dq -w 0 to disable writing of the offset to the slave. .It Fl r reset the controller. .It Fl s scan the bus for devices. .It Fl v be verbose. .It Fl w Ar 0|8|16|16LE|16BE device offset width (in bits). This is used to determine how to pass .Ar offset specified with .Fl o to the slave. Zero means that the offset is ignored and not passed to the slave at all. The endianness defaults to little-endian. .El .Sh INTERPRETED MODE When started with .Fl i any remaining arguments are interpreted as commands, and if the last argument is '-', or there are no arguments, commands will (also) be read from stdin. .Pp Available commands: .Bl -tag -compact .It 'r' bus address [0|8|16|16LE|16BE] offset count Read command, count bytes are read and hexdumped to stdout. .It 'w' bus address [0|8|16|16LE|16BE] offset hexstring Write command, hexstring (white-space is allowed) is written to device. .It 'p' anything Print command, the entire line is printed to stdout. (This can be used for synchronization.) .El .Pp All numeric fields accept canonical decimal/octal/hex notation. .Pp Without the .Fl v option, all errors are fatal with non-zero exit status. .Pp With the .Fl v option, no errors are fatal, and all commands will return either "OK\en" or "ERROR\en" on stdout. In case of error, detailed diagnostics will precede that on stderr. .Pp Blank lines and lines starting with '#' are ignored. .Sh EXAMPLES .Bl -bullet .It Scan the default bus (/dev/iic0) for devices: .Pp i2c -s .It Scan the default bus (/dev/iic0) for devices and skip addresses 0x45 to 0x47 (inclusive) and 0x56. .Pp i2c -s -n 0x56,45-47 .It Read 8 bytes of data from device at address 0x56 (e.g., an EEPROM): .Pp i2c -a 0x56 -d r -c 8 .It Write 16 bytes of data from file data.bin to device 0x56 at offset 0x10: .Pp i2c -a 0x56 -d w -c 16 -o 0x10 -b < data.bin .It Copy 4 bytes between two EEPROMs (0x56 on /dev/iic1 to 0x57 on /dev/iic0): .Pp i2c -a 0x56 -f /dev/iic1 -d r -c 0x4 -b | i2c -a 0x57 -f /dev/iic0 -d w -c 4 -b .It Reset the controller: .Pp i2c -f /dev/iic1 -r .It Read 8 bytes at address 24 in an EEPROM: .Pp i2c -i 'r 0 0x50 16BE 24 8' .It Read 2x8 bytes at address 24 and 48 in an EEPROM: .Pp echo 'r 0 0x50 16BE 48 8' | i2c -i 'r 0 0x50 16BE 24 8' - .El .Sh WARNING Many systems store critical low-level information in I2C memories, and may contain other I2C devices, such as temperature or voltage sensors. Reading these can disturb the firmware's operation and writing to them can "brick" the hardware. .Sh SEE ALSO .Xr iic 4 , -.Xr iicbus 4 +.Xr iicbus 4 , .Xr smbus 4 .Sh HISTORY The .Nm utility appeared in .Fx 8.0 . .Sh AUTHORS .An -nosplit The .Nm utility and this manual page were written by .An Bartlomiej Sieka Aq Mt tur@semihalf.com and .An Michal Hajduk Aq Mt mih@semihalf.com . .Pp .An Poul-Henning Kamp Aq Mt phk@FreeBSD.org added interpreted mode. diff --git a/usr.sbin/lastlogin/lastlogin.8 b/usr.sbin/lastlogin/lastlogin.8 index 0e18724a8707..3b2d47fdaf76 100644 --- a/usr.sbin/lastlogin/lastlogin.8 +++ b/usr.sbin/lastlogin/lastlogin.8 @@ -1,107 +1,107 @@ .\" $NetBSD: lastlogin.8,v 1.3 1998/02/06 06:20:39 perry Exp $ .\" .\" Copyright (c) 1996 John M. Vinopal .\" 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 for the NetBSD Project .\" by John M. Vinopal. .\" 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 ``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. .\" .Dd August 28, 2018 .Dt LASTLOGIN 8 .Os .Sh NAME .Nm lastlogin .Nd indicate last login time of users .Sh SYNOPSIS .Nm .Op Fl -libxo .Op Fl f Ar file .Op Fl rt .Op Ar user ... .Sh DESCRIPTION The .Nm utility will list the last login session of each specified .Ar user , or for all users by default. Each line of output contains the user name, the tty from which the session was conducted, any hostname, and the start time for the session. .Pp If more than one .Ar user is given, the session information for each user is printed in the order given on the command line. Otherwise, information for all users is printed. By default, the entries are sorted by user name. .Pp The .Nm utility differs from .Xr last 1 in that it only prints information regarding the very last login session. The last login database is never turned over or deleted in standard usage. .Pp The following options are available: .Bl -tag -width indent .It Fl -libxo Generate output via .Xr libxo 3 in a selection of different human and machine readable formats. See .Xr xo_parse_args 3 for details on command line arguments. .It Fl f Ar file Open last login database .Ar file instead of the system-wide database. .It Fl r Print the entries in reverse sorted order. .It Fl t Sort the elements by last login time, instead of user name. .El .Sh FILES .Bl -tag -width /var/log/utx.lastlogin -compact .It Pa /var/log/utx.lastlogin last login database .El .Sh SEE ALSO .Xr last 1 , .Xr getutxent 3 , -.Xr ac 8 , .Xr libxo 3 , -.Xr xo_parse_args 3 +.Xr xo_parse_args 3 , +.Xr ac 8 .Sh AUTHORS .An -nosplit .An John M. Vinopal wrote this program in January 1996 and contributed it to the .Nx project. .An Philip Paeps added .Xr libxo 3 support in August 2018. diff --git a/usr.sbin/mailwrapper/mailwrapper.8 b/usr.sbin/mailwrapper/mailwrapper.8 index 8480c939904c..c0f201318f53 100644 --- a/usr.sbin/mailwrapper/mailwrapper.8 +++ b/usr.sbin/mailwrapper/mailwrapper.8 @@ -1,191 +1,191 @@ .\" $OpenBSD: mailwrapper.8,v 1.12 2014/03/27 22:34:42 jmc Exp $ .\" $NetBSD: mailwrapper.8,v 1.16 2014/09/19 16:05:55 wiz Exp $ .\" .\" Copyright (c) 1998 .\" Perry E. Metzger. 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 acknowledgment: .\" This product includes software developed for the NetBSD Project .\" by Perry E. Metzger. .\" 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 ``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. .\" .Dd October 29, 2014 .Dt MAILWRAPPER 8 .Os .Sh NAME .Nm mailwrapper .Nd invoke appropriate .Tn MTA software based on configuration file .Sh SYNOPSIS Special. See below. .Sh DESCRIPTION Once upon time, the only Mail Transfer Agent .Pq Tn MTA software easily available was .Dq sendmail . This famous .Tn MTA was written by .An Eric Allman and first appeared in .Bx 4.1 . The legacy of this .Tn MTA affected most Mail User Agents .Pq Tn MUAs such as .Xr mail 1 ; the path and calling conventions expected by .Dq sendmail were compiled in. .Pp But times changed. On a modern .Fx system, the administrator may wish to use one of several available .Tn MTAs . .Pp It would be difficult to modify all .Tn MUA software typically available on a system, so most of the authors of alternative .Tn MTAs have written their front end message submission programs that may appear in the place of .Pa /usr/sbin/sendmail , but still follow the same calling conventions as .Dq sendmail . .Pp The .Dq sendmail .Tn MTA also typically has aliases named .Xr mailq 1 and .Xr newaliases 1 linked to it. The program knows to behave differently when its .Va argv[0] is .Dq mailq or .Dq newaliases and behaves appropriately. Typically, replacement .Tn MTAs provide similar functionality, either through a program that also switches behavior based on calling name, or through a set of programs that provide similar functionality. .Pp Although having replacement programs that plug replace .Dq sendmail helps in installing alternative .Tn MTAs , it essentially makes the configuration of the system depend on hand installing new programs in .Pa /usr . This leads to configuration problems for many administrators, since they may wish to install a new .Tn MTA without altering the system provided .Pa /usr . (This may be, for example, to avoid having upgrade problems when a new version of the system is installed over the old.) They may also have a shared .Pa /usr among several machines, and may wish to avoid placing implicit configuration information in a read-only .Pa /usr . .Pp The .Nm program is designed to replace .Pa /usr/sbin/sendmail and to invoke an appropriate .Tn MTA based on configuration information placed in .Pa ${LOCALBASE}/etc/mail/mailer.conf falling back on .Pa /etc/mail/mailer.conf . This permits the administrator to configure which .Tn MTA is to be invoked on the system at run time. .Pp Other configuration files may need to be altered when replacing .Xr sendmail 8 . For example, if the replacement .Tn MTA does not support the .Fl A option with .Xr mailq 1 , .Va daily_status_include_submit_mailq should be turned off in .Pa /etc/periodic.conf . .Sh FILES Configuration for .Nm is kept in .Pa ${LOCALBASE}/etc/mail/mailer.conf or .Pa /etc/mail/mailer.conf . .Pa /usr/sbin/sendmail is typically set up as a symbolic link to .Nm which is not usually invoked on its own. .Sh EXIT STATUS .Ex -std .Sh DIAGNOSTICS The .Nm will print a diagnostic if its configuration file is missing or malformed, or does not contain a mapping for the name under which it was invoked. .Sh SEE ALSO -.Xr dma 8 , .Xr mail 1 , .Xr mailq 1 , .Xr newaliases 1 , .Xr mailer.conf 5 , .Xr periodic.conf 5 , +.Xr dma 8 , .Xr sendmail 8 .Sh HISTORY The .Nm utility first appeared in .Nx 1.4 and then .Fx 4.0 . .Sh AUTHORS .An Perry E. Metzger Aq Mt perry@piermont.com .Sh BUGS The entire reason this program exists is a crock. Instead, a command for how to submit mail should be standardized, and all the .Dq behave differently if invoked with a different name behavior of things like .Xr mailq 1 should go away. diff --git a/usr.sbin/rpc.tlsclntd/rpc.tlsclntd.8 b/usr.sbin/rpc.tlsclntd/rpc.tlsclntd.8 index 5e6f93318ec2..f4e8acc0c5c4 100644 --- a/usr.sbin/rpc.tlsclntd/rpc.tlsclntd.8 +++ b/usr.sbin/rpc.tlsclntd/rpc.tlsclntd.8 @@ -1,218 +1,218 @@ .\" Copyright (c) 2008 Isilon Inc http://www.isilon.com/ .\" Authors: Doug Rabson .\" Developed with Red Inc: Alfred Perlstein .\" .\" 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. .\" .\" Modified from gssd.8 for rpc.tlsclntd.8 by Rick Macklem. .Dd September 23, 2022 .Dt RPC.TLSCLNTD 8 .Os .Sh NAME .Nm rpc.tlsclntd .Nd "Sun RPC over TLS Client Daemon" .Sh SYNOPSIS .Nm .Op Fl 2 .Op Fl C Ar available_ciphers .Op Fl D Ar certdir .Op Fl d .Op Fl l Ar CAfile .Op Fl m .Op Fl p Ar CApath .Op Fl r Ar CRLfile .Op Fl v .Sh DESCRIPTION The .Nm program provides support for the client side of the kernel Sun RPC over TLS implementation. This daemon must be running for the kernel RPC to be able to do a TLS connection to a server for an NFS over TLS mount. This daemon requires that the kernel be built with .Dq options KERNEL_TLS and be running on an architecture such as .Dq amd64 that supports a direct map (not i386) with .Xr ktls 4 enabled. .Pp If either of the .Fl l or .Fl p options have been specified, the daemon will require the server's certificate to verify and have a Fully Qualified Domain Name (FQDN) in it. This FQDN must match the reverse DNS name for the IP address that the server is using for the TCP connection. The FQDN may be in either the DNS field of the subjectAltName or the CN field of the subjectName in the certificate and cannot have a wildcard .Dq * in it. .Pp If a SIGHUP signal is sent to the daemon it will reload the .Dq CRLfile and will shut down any extant connections that presented certificates during TLS handshake that have been revoked. If the .Fl r option was not specified, the SIGHUP signal will be ignored. .Pp The daemon will log failed certificate verifications via .Xr syslogd 8 using LOG_INFO | LOG_DAEMON when the .Fl l or .Fl p option has been specified. .Pp The options are as follows: .Bl -tag -width indent .It Fl 2 , Fl Fl usetls1_2 Specify the use of TLS version 1.2. By default, the client will use TLS version 1.3, as required by the RFC. However, early .Fx .Pq 13.0 and 13.1 servers require this option, since they only support TLS version 1.2. .It Fl C Ar available_ciphers , Fl Fl ciphers= Ns Ar available_ciphers Specify which ciphers are available during TLS handshake. If this option is specified, .Dq SSL_CTX_set_ciphersuites() will be called with .Dq available_ciphers as the argument. If this option is not specified, the cipher will be chosen by .Xr ssl 7 , which should be adequate for most cases. The format for the available ciphers is a simple .So : .Sc separated list, in order of preference. The command .Dq openssl ciphers -s -tls1_3 lists available ciphers. .It Fl D Ar certdir , Fl Fl certdir= Ns Ar certdir Use .Dq certdir instead of /etc/rpc.tlsclntd for the .Fl m option. .It Fl d , Fl Fl debuglevel Run in debug mode. In this mode, .Nm will not fork when it starts. .It Fl l Ar CAfile , Fl Fl verifylocs= Ns Ar CAfile This specifies the path name of a CAfile which holds the information for server certificate verification. This path name is used in .Dq SSL_CTX_load_verify_locations(ctx,CAfile,NULL) and .Dq SSL_CTX_set0_CA_list(ctx,SSL_load_client_CA_file(CAfile)) openssl library calls. Note that this is a path name for the file and is not assumed to be in .Dq certdir . .It Fl m , Fl Fl mutualverf Enable support for mutual authentication. A certificate and associated key must be found in /etc/rpc.tlsclntd (or the directory specified by the .Fl D option) in case a server requests a peer certificate. The first certificate needs to be in a file named .Dq cert.pem and the associated key in a file named .Dq certkey.pem . The .Xr mount_nfs 8 option .Fl tlscertname can be used to override the default certificate for a given NFS mount, where the files use the alternate naming specified by the option. If there is a passphrase on the .Dq certkey.pem file, this daemon will prompt for the passphrase during startup. The keys for alternate certificates cannot have passphrases. .It Fl p Ar CApath , Fl Fl verifydir= Ns Ar CApath This option is similar to the .Fl l option, but specifies the path of a directory with CA certificates in it. When this option is used, .Dq SSL_CTX_set0_CA_list(ctx,SSL_load_client_CA_file()) is not called, so a list of CA names is not be passed to the server during the TLS handshake. The openssl documentation indicates this call is rarely needed. .It Fl r Ar CRLfile , Fl Fl crl= Ns Ar CRLfile This option specifies a Certificate Revocation List (CRL) file that is to be loaded into the verify certificate store and checked during verification of the server's certificate. This option is meaningless unless either the .Fl l or .Fl p have been specified. .It Fl v , Fl Fl verbose Run in verbose mode. In this mode, .Nm will log activity messages to syslog using LOG_INFO | LOG_DAEMON or to stderr, if the .Fl d option has also been specified. .El .Sh EXIT STATUS .Ex -std .Sh SEE ALSO .Xr openssl 1 , .Xr ktls 4 , +.Xr ssl 7 , .Xr mount_nfs 8 , .Xr rpc.tlsservd 8 , -.Xr ssl 7 , .Xr syslogd 8 .Sh STANDARDS The implementation is based on the specification in .Rs .%B "RFC 9289" .%T "Towards Remote Procedure Call Encryption By Default" .Re .Sh HISTORY The .Nm manual page first appeared in .Fx 13.0 . .Sh BUGS This daemon cannot be safely shut down and restarted if there are any active RPC-over-TLS connections. Doing so will orphan the KERNEL_TLS connections, so that they can no longer do upcalls successfully, since the .Dq SSL * structures in userspace have been lost.