diff --git a/bin/ps/ps.1 b/bin/ps/ps.1 index 21def154ec00..bac86ad8a882 100644 --- a/bin/ps/ps.1 +++ b/bin/ps/ps.1 @@ -1,812 +1,812 @@ .\"- .\" Copyright (c) 1980, 1990, 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. .\" .Dd November 11, 2023 .Dt PS 1 .Os .Sh NAME .Nm ps .Nd process status .Sh SYNOPSIS .Nm .Op Fl -libxo .Op Fl aCcdefHhjlmrSTuvwXxZ .Op Fl O Ar fmt | Fl o Ar fmt .Op Fl D Ar up | down | both .Op Fl G Ar gid Ns Op , Ns Ar gid Ns Ar ... .Op Fl J Ar jid Ns Op , Ns Ar jid Ns Ar ... .Op Fl M Ar core .Op Fl N Ar system .Op Fl p Ar pid Ns Op , Ns Ar pid Ns Ar ... .Op Fl t Ar tty Ns Op , Ns Ar tty Ns Ar ... .Op Fl U Ar user Ns Op , Ns Ar user Ns Ar ... .Nm .Op Fl -libxo .Fl L .Sh DESCRIPTION The .Nm utility displays a header line, followed by lines containing information about all of your processes that have controlling terminals. If the .Fl x options is specified, .Nm will also display processes that do not have controlling terminals. .Pp A different set of processes can be selected for display by using any combination of the .Fl a , D , G , J , p , T , t , and .Fl U options. If more than one of these options are given, then .Nm will select all processes which are matched by at least one of the given options. .Pp For the processes which have been selected for display, .Nm will usually display one line per process. The .Fl H option may result in multiple output lines (one line per thread) for some processes. By default all of these output lines are sorted first by controlling terminal, then by process ID. The .Fl m , r , u , and .Fl v options will change the sort order. If more than one sorting option was given, then the selected processes will be sorted by the last sorting option which was specified. .Pp For the processes which have been selected for display, the information to display is selected based on a set of keywords (see the .Fl L , O , and .Fl o options). The default output format includes, for each process, the process' ID, controlling terminal, state, CPU time (including both user and system time) and associated command. .Pp If the .Nm process is associated with a terminal, the default output width is that of the terminal; otherwise the output width is unlimited. See also the .Fl w option. .Pp The options are as follows: .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 a Display information about other users' processes as well as your own. If the .Va security.bsd.see_other_uids sysctl is set to zero, this option is honored only if the UID of the user is 0. .It Fl c Change the .Dq command column output to just contain the executable name, rather than the full command line. .It Fl C Change the way the CPU percentage is calculated by using a .Dq raw CPU calculation that ignores .Dq resident time (this normally has no effect). .It Fl d Arrange processes into descendancy order and prefix each command with indentation text showing sibling and parent/child relationships as a tree. If either of the .Fl m and .Fl r options are also used, they control how sibling processes are sorted relative to each other. Note that this option has no effect if the .Dq command column is not the last column displayed. .It Fl D Expand the list of selected processes based on the process tree. .Dq UP will add the ancestor processes, .Dq DOWN will add the descendant processes, and .Dq BOTH will add both the ancestor and the descendant processes. .Fl D does not imply .Fl d , but works well with it. .It Fl e Display the environment as well. .It Fl f Show command-line and environment information about swapped out processes. This option is honored only if the UID of the user is 0. .It Fl G Display information about processes which are running with the specified real group IDs. .It Fl H Show all of the threads associated with each process. .It Fl h Repeat the information header as often as necessary to guarantee one header per page of information. .It Fl j Print information associated with the following keywords: .Cm user , pid , ppid , pgid , sid , jobc , state , tt , time , and .Cm command . .It Fl J Display information about processes which match the specified jail IDs. This may be either the .Cm jid or .Cm name of the jail. Use .Fl J .Sy 0 to display only host processes. This flag implies .Fl x by default. .It Fl L List the set of keywords available for the .Fl O and .Fl o options. .It Fl l Display information associated with the following keywords: .Cm uid , pid , ppid , cpu , pri , nice , vsz , rss , mwchan , state , .Cm tt , time , and .Cm command . .It Fl M Extract values associated with the name list from the specified core instead of the currently running system. .It Fl m Sort by memory usage, instead of the combination of controlling terminal and process ID. .It Fl N Extract the name list from the specified system instead of the default, which is the kernel image the system has booted from. .It Fl O Add the information associated with the space or comma separated list of keywords specified, after the process ID, in the default information display. Keywords may be appended with an equals .Pq Ql = sign and a string. This causes the printed header to use the specified string instead of the standard header. .It Fl o Display information associated with the space or comma separated list of keywords specified. The last keyword in the list may be appended with an equals .Pq Ql = sign and a string that spans the rest of the argument, and can contain space and comma characters. This causes the printed header to use the specified string instead of the standard header. Multiple keywords may also be given in the form of more than one .Fl o option. So the header texts for multiple keywords can be changed. If all keywords have empty header texts, no header line is written. .It Fl p Display information about processes which match the specified process IDs. .It Fl r Sort by current CPU usage, instead of the combination of controlling terminal and process ID. .It Fl S Change the way the process times, namely cputime, systime, and usertime, are calculated by summing all exited children to their parent process. .It Fl T Display information about processes attached to the device associated with the standard input. .It Fl t Display information about processes attached to the specified terminal devices. Full pathnames, as well as abbreviations (see explanation of the .Cm tt keyword) can be specified. .It Fl U Display the processes belonging to the specified usernames. .It Fl u Display information associated with the following keywords: .Cm user , pid , %cpu , %mem , vsz , rss , tt , state , start , time , and .Cm command . The .Fl u option implies the .Fl r option. .It Fl v Display information associated with the following keywords: .Cm pid , state , time , sl , re , pagein , vsz , rss , lim , tsiz , .Cm %cpu , %mem , and .Cm command . The .Fl v option implies the .Fl m option. .It Fl w Use at least 132 columns to display information, instead of the default which is the window size if .Nm is associated with a terminal. If the .Fl w option is specified more than once, .Nm will use as many columns as necessary without regard for the window size. Note that this option has no effect if the .Dq command column is not the last column displayed. .It Fl X When displaying processes matched by other options, skip any processes which do not have a controlling terminal. This is the default behaviour. .It Fl x When displaying processes matched by other options, include processes which do not have a controlling terminal. This is the opposite of the .Fl X option. If both .Fl X and .Fl x are specified in the same command, then .Nm will use the one which was specified last. .It Fl Z Add .Xr mac 4 label to the list of keywords for which .Nm will display information. .El .Pp A complete list of the available keywords are listed below. Some of these keywords are further specified as follows: .Bl -tag -width lockname .It Cm %cpu The CPU utilization of the process; this is a decaying average over up to a minute of previous (real) time. Since the time base over which this is computed varies (since processes may be very young) it is possible for the sum of all .Cm %cpu fields to exceed 100%. .It Cm %mem The percentage of real memory used by this process. .It Cm class Login class associated with the process. .It Cm flags The flags associated with the process as in the include file .In sys/proc.h : .Bl -column P_SINGLE_BOUNDARY 0x40000000 .It Dv "P_ADVLOCK" Ta No "0x00001" Ta "Process may hold a POSIX advisory lock" .It Dv "P_CONTROLT" Ta No "0x00002" Ta "Has a controlling terminal" .It Dv "P_KPROC" Ta No "0x00004" Ta "Kernel process" .It Dv "P_PPWAIT" Ta No "0x00010" Ta "Parent is waiting for child to exec/exit" .It Dv "P_PROFIL" Ta No "0x00020" Ta "Has started profiling" .It Dv "P_STOPPROF" Ta No "0x00040" Ta "Has thread in requesting to stop prof" .It Dv "P_HADTHREADS" Ta No "0x00080" Ta "Has had threads (no cleanup shortcuts)" .It Dv "P_SUGID" Ta No "0x00100" Ta "Had set id privileges since last exec" .It Dv "P_SYSTEM" Ta No "0x00200" Ta "System proc: no sigs, stats or swapping" .It Dv "P_SINGLE_EXIT" Ta No "0x00400" Ta "Threads suspending should exit, not wait" .It Dv "P_TRACED" Ta No "0x00800" Ta "Debugged process being traced" .It Dv "P_WAITED" Ta No "0x01000" Ta "Someone is waiting for us" .It Dv "P_WEXIT" Ta No "0x02000" Ta "Working on exiting" .It Dv "P_EXEC" Ta No "0x04000" Ta "Process called exec" .It Dv "P_WKILLED" Ta No "0x08000" Ta "Killed, shall go to kernel/user boundary ASAP" .It Dv "P_CONTINUED" Ta No "0x10000" Ta "Proc has continued from a stopped state" .It Dv "P_STOPPED_SIG" Ta No "0x20000" Ta "Stopped due to SIGSTOP/SIGTSTP" .It Dv "P_STOPPED_TRACE" Ta No "0x40000" Ta "Stopped because of tracing" .It Dv "P_STOPPED_SINGLE" Ta No "0x80000" Ta "Only one thread can continue" .It Dv "P_PROTECTED" Ta No "0x100000" Ta "Do not kill on memory overcommit" .It Dv "P_SIGEVENT" Ta No "0x200000" Ta "Process pending signals changed" .It Dv "P_SINGLE_BOUNDARY" Ta No "0x400000" Ta "Threads should suspend at user boundary" .It Dv "P_HWPMC" Ta No "0x800000" Ta "Process is using HWPMCs" .It Dv "P_JAILED" Ta No "0x1000000" Ta "Process is in jail" .It Dv "P_TOTAL_STOP" Ta No "0x2000000" Ta "Stopped for system suspend" .It Dv "P_INEXEC" Ta No "0x4000000" Ta Process is in Xr execve 2 .It Dv "P_STATCHILD" Ta No "0x8000000" Ta "Child process stopped or exited" .It Dv "P_INMEM" Ta No "0x10000000" Ta "Loaded into memory" .It Dv "P_SWAPPINGOUT" Ta No "0x20000000" Ta "Process is being swapped out" .It Dv "P_SWAPPINGIN" Ta No "0x40000000" Ta "Process is being swapped in" .It Dv "P_PPTRACE" Ta No "0x80000000" Ta "Vforked child issued ptrace(PT_TRACEME)" .El .It Cm flags2 The flags kept in .Va p_flag2 associated with the process as in the include file .In sys/proc.h : .Bl -column P2_INHERIT_PROTECTED 0x00000001 .It Dv "P2_INHERIT_PROTECTED" Ta No "0x00000001" Ta "New children get P_PROTECTED" .It Dv "P2_NOTRACE" Ta No "0x00000002" Ta "No" Xr ptrace 2 attach or coredumps .It Dv "P2_NOTRACE_EXEC" Ta No "0x00000004" Ta Keep P2_NOPTRACE on Xr execve 2 .It Dv "P2_AST_SU" Ta No "0x00000008" Ta "Handles SU ast for kthreads" .It Dv "P2_PTRACE_FSTP" Ta No "0x00000010" Ta "SIGSTOP from PT_ATTACH not yet handled" .El .It Cm label The MAC label of the process. .It Cm lim The soft limit on memory used, specified via a call to .Xr setrlimit 2 . .It Cm lstart The exact time the command started, using the .Ql %c format described in .Xr strftime 3 . .It Cm lockname The name of the lock that the process is currently blocked on. If the name is invalid or unknown, then .Dq ???\& is displayed. .It Cm logname The login name associated with the session the process is in (see .Xr getlogin 2 ) . .It Cm mwchan The event name if the process is blocked normally, or the lock name if the process is blocked on a lock. See the wchan and lockname keywords for details. .It Cm nice The process scheduling increment (see .Xr setpriority 2 ) . .It Cm rss the real memory (resident set) size of the process (in 1024 byte units). .It Cm start The time the command started. If the command started less than 24 hours ago, the start time is displayed using the .Dq Li %H:%M format described in .Xr strftime 3 . If the command started less than 7 days ago, the start time is displayed using the .Dq Li %a%H format. Otherwise, the start time is displayed using the .Dq Li %e%b%y format. .It Cm state The state is given by a sequence of characters, for example, .Dq Li RWNA . The first character indicates the run state of the process: .Pp .Bl -tag -width indent -compact .It Li D Marks a process in disk (or other short term, uninterruptible) wait. .It Li I Marks a process that is idle (sleeping for longer than about 20 seconds). .It Li L Marks a process that is waiting to acquire a lock. .It Li R Marks a runnable process. .It Li S Marks a process that is sleeping for less than about 20 seconds. .It Li T Marks a stopped process. .It Li W Marks an idle interrupt thread. .It Li Z Marks a dead process (a .Dq zombie ) . .El .Pp Additional characters after these, if any, indicate additional state information: .Pp .Bl -tag -width indent -compact .It Li + The process is in the foreground process group of its control terminal. .It Li < The process has raised CPU scheduling priority. .It Li C The process is in .Xr capsicum 4 capability mode. .It Li E The process is trying to exit. .It Li J Marks a process which is in .Xr jail 2 . The hostname of the prison can be found in .Pa /proc/ Ns Ao Ar pid Ac Ns Pa /status . .It Li L The process has pages locked in core (for example, for raw I/O). .It Li N The process has reduced CPU scheduling priority (see .Xr setpriority 2 ) . .It Li s The process is a session leader. .It Li V The process' parent is suspended during a .Xr vfork 2 , waiting for the process to exec or exit. .It Li W The process is swapped out. .It Li X The process is being traced or debugged. .El .It Cm tt An abbreviation for the pathname of the controlling terminal, if any. The abbreviation consists of the three letters following .Pa /dev/tty , or, for pseudo-terminals, the corresponding entry in .Pa /dev/pts . This is followed by a .Ql - if the process can no longer reach that controlling terminal (i.e., it has been revoked). A .Ql - without a preceding two letter abbreviation or pseudo-terminal device number indicates a process which never had a controlling terminal. The full pathname of the controlling terminal is available via the .Cm tty keyword. .It Cm wchan The event (an address in the system) on which a process waits. When printed numerically, the initial part of the address is trimmed off and the result is printed in hex, for example, 0x80324000 prints as 324000. .El .Pp When printing using the command keyword, a process that has exited and has a parent that has not yet waited for the process (in other words, a zombie) is listed as .Dq Li , and a process which is blocked while trying to exit is listed as .Dq Li . If the arguments cannot be located (usually because it has not been set, as is the case of system processes and/or kernel threads) the command name is printed within square brackets. The .Nm utility first tries to obtain the arguments cached by the kernel (if they were shorter than the value of the .Va kern.ps_arg_cache_limit sysctl). The process can change the arguments shown with .Xr setproctitle 3 . Otherwise, .Nm makes an educated guess as to the file name and arguments given when the process was created by examining memory or the swap area. The method is inherently somewhat unreliable and in any event a process is entitled to destroy this information. The ucomm (accounting) keyword can, however, be depended on. If the arguments are unavailable or do not agree with the ucomm keyword, the value for the ucomm keyword is appended to the arguments in parentheses. .Sh KEYWORDS The following is a complete list of the available keywords and their meanings. Several of them have aliases (keywords which are synonyms). .Pp .Bl -tag -width ".Cm sigignore" -compact .It Cm %cpu percentage CPU usage (alias .Cm pcpu ) .It Cm %mem percentage memory usage (alias .Cm pmem ) .It Cm acflag accounting flag (alias .Cm acflg ) .It Cm args command and arguments .It Cm class login class .It Cm comm command .It Cm command command and arguments .It Cm cow number of copy-on-write faults .It Cm cpu The processor number on which the process is executing (visible only on SMP systems). .It Cm dsiz data size (in Kbytes) .It Cm emul system-call emulation environment (ABI) .It Cm etime elapsed running time, format .Do .Op days- Ns .Op hours\&: Ns minutes:seconds .Dc .It Cm etimes elapsed running time, in decimal integer seconds .It Cm fib default FIB number, see .Xr setfib 1 .It Cm flags the process flags, in hexadecimal (alias .Cm f ) .It Cm flags2 the additional set of process flags, in hexadecimal (alias .Cm f2 ) .It Cm gid effective group ID (alias .Cm egid ) .It Cm group group name (from egid) (alias .Cm egroup ) .It Cm inblk total blocks read (alias .Cm inblock ) .It Cm jail jail name .It Cm jid jail ID .It Cm jobc job control count .It Cm ktrace tracing flags .It Cm label MAC label .It Cm lim memoryuse limit .It Cm lockname lock currently blocked on (as a symbolic name) .It Cm logname login name of user who started the session .It Cm lstart time started .It Cm lwp thread (light-weight process) ID (alias .Cm tid ) .It Cm majflt total page faults .It Cm minflt total page reclaims .It Cm msgrcv total messages received (reads from pipes/sockets) .It Cm msgsnd total messages sent (writes on pipes/sockets) .It Cm mwchan wait channel or lock currently blocked on .It Cm nice nice value (alias .Cm ni ) .It Cm nivcsw total involuntary context switches .It Cm nlwp number of threads (light-weight processes) tied to a process .It Cm nsigs total signals taken (alias .Cm nsignals ) .It Cm nswap total swaps in/out .It Cm nvcsw total voluntary context switches .It Cm nwchan wait channel (as an address) .It Cm oublk total blocks written (alias .Cm oublock ) .It Cm paddr process pointer .It Cm pagein pageins (same as majflt) .It Cm pgid process group number .It Cm pid process ID .It Cm ppid parent process ID .It Cm pri scheduling priority .It Cm re core residency time (in seconds; 127 = infinity) .It Cm rgid real group ID .It Cm rgroup group name (from rgid) .It Cm rss resident set size .It Cm rtprio realtime priority (see .Xr rtprio 1) .It Cm ruid real user ID .It Cm ruser user name (from ruid) .It Cm sid session ID .It Cm sig pending signals (alias .Cm pending ) .It Cm sigcatch caught signals (alias .Cm caught ) .It Cm sigignore ignored signals (alias .Cm ignored ) .It Cm sigmask blocked signals (alias .Cm blocked ) .It Cm sl sleep time (in seconds; 127 = infinity) .It Cm ssiz stack size (in Kbytes) .It Cm start time started .It Cm state symbolic process state (alias .Cm stat ) .It Cm svgid saved gid from a setgid executable .It Cm svuid saved UID from a setuid executable .It Cm systime accumulated system CPU time .It Cm tdaddr thread address .It Cm tdname thread name .It Cm tdev control terminal device number .It Cm time accumulated CPU time, user + system (alias .Cm cputime ) .It Cm tpgid control terminal process group ID .It Cm tracer tracer process ID .\".It Cm trss .\"text resident set size (in Kbytes) .It Cm tsid control terminal session ID .It Cm tsiz text size (in Kbytes) .It Cm tt control terminal name (two letter abbreviation) .It Cm tty full name of control terminal .It Cm ucomm name to be used for accounting .It Cm uid effective user ID (alias .Cm euid ) .It Cm upr scheduling priority on return from system call (alias .Cm usrpri ) .It Cm uprocp process pointer .It Cm user user name (from UID) .It Cm usertime accumulated user CPU time .It Cm vmaddr vmspace pointer .It Cm vsz virtual size in Kbytes (alias .Cm vsize ) .It Cm wchan wait channel (as a symbolic name) .It Cm xstat exit or stop status (valid only for stopped or zombie process) .El .Pp Note that the .Cm pending column displays bitmask of signals pending in the process queue when .Fl H option is not specified, otherwise the per-thread queue of pending signals is shown. .Sh ENVIRONMENT The following environment variables affect the execution of .Nm : .Bl -tag -width ".Ev COLUMNS" .It Ev COLUMNS If set, specifies the user's preferred output width in column positions. By default, .Nm attempts to automatically determine the terminal width. .El .Sh FILES .Bl -tag -width ".Pa /boot/kernel/kernel" -compact .It Pa /boot/kernel/kernel default system namelist .El .Sh EXIT STATUS .Ex -std .Sh EXAMPLES Display information on all system processes: .Pp .Dl $ ps -auxw .Sh SEE ALSO .Xr kill 1 , .Xr pgrep 1 , .Xr pkill 1 , .Xr procstat 1 , .Xr w 1 , .Xr kvm 3 , .Xr libxo 3 , .Xr strftime 3 , .Xr xo_parse_args 3 , .Xr mac 4 , -.Xr procfs 5 , +.Xr procfs 4 , .Xr pstat 8 , .Xr sysctl 8 , .Xr mutex 9 .Sh STANDARDS For historical reasons, the .Nm utility under .Fx supports a different set of options from what is described by .St -p1003.2 , and what is supported on .No non- Ns Bx operating systems. .Sh HISTORY The .Nm command appeared in .At v3 in section 8 of the manual. .Sh BUGS Since .Nm cannot run faster than the system and is run as any other scheduled process, the information it displays can never be exact. .Pp The .Nm utility does not correctly display argument lists containing multibyte characters. diff --git a/contrib/pf/authpf/authpf.8 b/contrib/pf/authpf/authpf.8 index ada4c6a5a11a..70b59ce212c8 100644 --- a/contrib/pf/authpf/authpf.8 +++ b/contrib/pf/authpf/authpf.8 @@ -1,584 +1,584 @@ .\" $FreeBSD$ .\" $OpenBSD: authpf.8,v 1.47 2009/01/06 03:11:50 mcbride Exp $ .\" .\" Copyright (c) 1998-2007 Bob Beck (beck@openbsd.org>. All rights reserved. .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" .Dd January 29 2014 .Dt AUTHPF 8 .Os .Sh NAME .Nm authpf , .Nm authpf-noip .Nd authenticating gateway user shell .Sh SYNOPSIS .Nm authpf .Nm authpf-noip .Sh DESCRIPTION .Nm is a user shell for authenticating gateways. It is used to change .Xr pf 4 rules when a user authenticates and starts a session with .Xr sshd 8 and to undo these changes when the user's session exits. Typical use would be for a gateway that authenticates users before allowing them Internet use, or a gateway that allows different users into different places. Combined with properly set up filter rules and secure switches, .Nm can be used to ensure users are held accountable for their network traffic. It is meant to be used with users who can connect via .Xr ssh 1 only, and requires the .Xr pf 4 subsystem and an -.Xr fdescfs 5 +.Xr fdescfs 4 file system mounted at .Pa /dev/fd to be enabled. .Pp .Nm authpf-noip is a user shell which allows multiple connections to take place from the same IP address. It is useful primarily in cases where connections are tunneled via the gateway system, and can be directly associated with the user name. It cannot ensure accountability when classifying connections by IP address; in this case the client's IP address is not provided to the packet filter via the .Ar client_ip macro or the .Ar authpf_users table. Additionally, states associated with the client IP address are not purged when the session is ended. .Pp To use either .Nm or .Nm authpf-noip , the user's shell needs to be set to .Pa /usr/sbin/authpf or .Pa /usr/sbin/authpf-noip . .Pp .Nm uses the .Xr pf.conf 5 syntax to change filter and translation rules for an individual user or client IP address as long as a user maintains an active .Xr ssh 1 session, and logs the successful start and end of a session to .Xr syslogd 8 . .Nm retrieves the client's connecting IP address via the .Ev SSH_CLIENT environment variable and, after performing additional access checks, reads a template file to determine what filter and translation rules (if any) to add, and maintains the list of IP addresses of connected users in the .Ar authpf_users table. On session exit the same rules and table entries that were added at startup are removed, and all states associated with the client's IP address are purged. .Pp Each .Nm process stores its rules in a separate ruleset inside a .Xr pf 4 .Pa anchor shared by all .Nm processes. By default, the .Pa anchor name "authpf" is used, and the ruleset names equal the username and PID of the .Nm processes as "username(pid)". The following rules need to be added to the main ruleset .Pa /etc/pf.conf in order to cause evaluation of any .Nm rules: .Bd -literal -offset indent nat-anchor "authpf/*" rdr-anchor "authpf/*" binat-anchor "authpf/*" anchor "authpf/*" .Ed .Pp The "/*" at the end of the anchor name is required for .Xr pf 4 to process the rulesets attached to the anchor by .Nm authpf . .Sh FILTER AND TRANSLATION RULES Filter and translation rules for .Nm use the same format described in .Xr pf.conf 5 . The only difference is that these rules may (and probably should) use the macro .Em user_ip , which is assigned the connecting IP address whenever .Nm is run. Additionally, the macro .Em user_id is assigned the user name. .Pp Filter and translation rules are stored in a file called .Pa authpf.rules . This file will first be searched for in .Pa /etc/authpf/users/$USER/ and then in .Pa /etc/authpf/ . Only one of these files will be used if both are present. .Pp Per-user rules from the .Pa /etc/authpf/users/$USER/ directory are intended to be used when non-default rules are needed on an individual user basis. It is important to ensure that a user can not write or change these configuration files. .Pp The .Pa authpf.rules file must exist in one of the above locations for .Nm to run. .Sh CONFIGURATION Options are controlled by the .Pa /etc/authpf/authpf.conf file. If the file is empty, defaults are used for all configuration options. The file consists of pairs of the form .Li name=value , one per line. Currently, the allowed values are as follows: .Bl -tag -width Ds .It anchor=name Use the specified .Pa anchor name instead of "authpf". .It table=name Use the specified .Pa table name instead of "authpf_users". .El .Sh USER MESSAGES On successful invocation, .Nm displays a message telling the user he or she has been authenticated. It will additionally display the contents of the file .Pa /etc/authpf/authpf.message if the file exists and is readable. .Pp There exist two methods for providing additional granularity to the control offered by .Nm - it is possible to set the gateway to explicitly allow users who have authenticated to .Xr ssh 1 and deny access to only a few troublesome individuals. This is done by creating a file with the banned user's login name as the filename in .Pa /etc/authpf/banned/ . The contents of this file will be displayed to a banned user, thus providing a method for informing the user that they have been banned, and where they can go and how to get there if they want to have their service restored. This is the default behaviour. .Pp It is also possible to configure .Nm to only allow specific users access. This is done by listing their login names, one per line, in .Pa /etc/authpf/authpf.allow . A group of users can also be indicated by prepending "%" to the group name, and all members of a login class can be indicated by prepending "@" to the login class name. If "*" is found on a line, then all usernames match. If .Nm is unable to verify the user's permission to use the gateway, it will print a brief message and die. It should be noted that a ban takes precedence over an allow. .Pp On failure, messages will be logged to .Xr syslogd 8 for the system administrator. The user does not see these, but will be told the system is unavailable due to technical difficulties. The contents of the file .Pa /etc/authpf/authpf.problem will also be displayed if the file exists and is readable. .Sh CONFIGURATION ISSUES .Nm maintains the changed filter rules as long as the user maintains an active session. It is important to remember however, that the existence of this session means the user is authenticated. Because of this, it is important to configure .Xr sshd 8 to ensure the security of the session, and to ensure that the network through which users connect is secure. .Xr sshd 8 should be configured to use the .Ar ClientAliveInterval and .Ar ClientAliveCountMax parameters to ensure that a ssh session is terminated quickly if it becomes unresponsive, or if arp or address spoofing is used to hijack the session. Note that TCP keepalives are not sufficient for this, since they are not secure. Also note that the various SSH tunnelling mechanisms, such as .Ar AllowTcpForwarding and .Ar PermitTunnel , should be disabled for .Nm users to prevent them from circumventing restrictions imposed by the packet filter ruleset. .Pp .Nm will remove state table entries that were created during a user's session. This ensures that there will be no unauthenticated traffic allowed to pass after the controlling .Xr ssh 1 session has been closed. .Pp .Nm is designed for gateway machines which typically do not have regular (non-administrative) users using the machine. An administrator must remember that .Nm can be used to modify the filter rules through the environment in which it is run, and as such could be used to modify the filter rules (based on the contents of the configuration files) by regular users. In the case where a machine has regular users using it, as well as users with .Nm as their shell, the regular users should be prevented from running .Nm by using the .Pa /etc/authpf/authpf.allow or .Pa /etc/authpf/banned/ facilities. .Pp .Nm modifies the packet filter and address translation rules, and because of this it needs to be configured carefully. .Nm will not run and will exit silently if the .Pa /etc/authpf/authpf.conf file does not exist. After considering the effect .Nm may have on the main packet filter rules, the system administrator may enable .Nm by creating an appropriate .Pa /etc/authpf/authpf.conf file. .Sh EXAMPLES .Sy Control Files \- To illustrate the user-specific access control mechanisms, let us consider a typical user named bob. Normally, as long as bob can authenticate himself, the .Nm program will load the appropriate rules. Enter the .Pa /etc/authpf/banned/ directory. If bob has somehow fallen from grace in the eyes of the powers-that-be, they can prohibit him from using the gateway by creating the file .Pa /etc/authpf/banned/bob containing a message about why he has been banned from using the network. Once bob has done suitable penance, his access may be restored by moving or removing the file .Pa /etc/authpf/banned/bob . .Pp Now consider a workgroup containing alice, bob, carol and dave. They have a wireless network which they would like to protect from unauthorized use. To accomplish this, they create the file .Pa /etc/authpf/authpf.allow which lists their login ids, group prepended with "%", or login class prepended with "@", one per line. At this point, even if eve could authenticate to .Xr sshd 8 , she would not be allowed to use the gateway. Adding and removing users from the work group is a simple matter of maintaining a list of allowed userids. If bob once again manages to annoy the powers-that-be, they can ban him from using the gateway by creating the familiar .Pa /etc/authpf/banned/bob file. Though bob is listed in the allow file, he is prevented from using this gateway due to the existence of a ban file. .Pp .Sy Distributed Authentication \- It is often desirable to interface with a distributed password system rather than forcing the sysadmins to keep a large number of local password files in sync. The .Xr login.conf 5 mechanism in .Ox can be used to fork the right shell. To make that happen, .Xr login.conf 5 should have entries that look something like this: .Bd -literal -offset indent shell-default:shell=/bin/csh default:\e ... :shell=/usr/sbin/authpf daemon:\e ... :shell=/bin/csh:\e :tc=default: staff:\e ... :shell=/bin/csh:\e :tc=default: .Ed .Pp Using a default password file, all users will get .Nm as their shell except for root who will get .Pa /bin/csh . .Pp .Sy SSH Configuration \- As stated earlier, .Xr sshd 8 must be properly configured to detect and defeat network attacks. To that end, the following options should be added to .Xr sshd_config 5 : .Bd -literal -offset indent Protocol 2 ClientAliveInterval 15 ClientAliveCountMax 3 .Ed .Pp This ensures that unresponsive or spoofed sessions are terminated within a minute, since a hijacker should not be able to spoof ssh keepalive messages. .Pp .Sy Banners \- Once authenticated, the user is shown the contents of .Pa /etc/authpf/authpf.message . This message may be a screen-full of the appropriate use policy, the contents of .Pa /etc/motd or something as simple as the following: .Bd -literal -offset indent This means you will be held accountable by the powers that be for traffic originating from your machine, so please play nice. .Ed .Pp To tell the user where to go when the system is broken, .Pa /etc/authpf/authpf.problem could contain something like this: .Bd -literal -offset indent Sorry, there appears to be some system problem. To report this problem so we can fix it, please phone 1-900-314-1597 or send an email to remove@bulkmailerz.net. .Ed .Pp .Sy Packet Filter Rules \- In areas where this gateway is used to protect a wireless network (a hub with several hundred ports), the default rule set as well as the per-user rules should probably allow very few things beyond encrypted protocols like .Xr ssh 1 , .Xr ssl 8 , or .Xr ipsec 4 . On a securely switched network, with plug-in jacks for visitors who are given authentication accounts, you might want to allow out everything. In this context, a secure switch is one that tries to prevent address table overflow attacks. .Pp Example .Pa /etc/pf.conf : .Bd -literal # by default we allow internal clients to talk to us using # ssh and use us as a dns server. internal_if="fxp1" gateway_addr="10.0.1.1" nat-anchor "authpf/*" rdr-anchor "authpf/*" binat-anchor "authpf/*" block in on $internal_if from any to any pass in quick on $internal_if proto tcp from any to $gateway_addr \e port = ssh pass in quick on $internal_if proto udp from any to $gateway_addr \e port = domain anchor "authpf/*" .Ed .Pp .Sy For a switched, wired net \- This example .Pa /etc/authpf/authpf.rules makes no real restrictions; it turns the IP address on and off, logging TCP connections. .Bd -literal external_if = "xl0" internal_if = "fxp0" pass in log quick on $internal_if proto tcp from $user_ip to any pass in quick on $internal_if from $user_ip to any .Ed .Pp .Sy For a wireless or shared net \- This example .Pa /etc/authpf/authpf.rules could be used for an insecure network (such as a public wireless network) where we might need to be a bit more restrictive. .Bd -literal internal_if="fxp1" ipsec_gw="10.2.3.4" # rdr ftp for proxying by ftp-proxy(8) rdr on $internal_if proto tcp from $user_ip to any port 21 \e -> 127.0.0.1 port 8021 # allow out ftp, ssh, www and https only, and allow user to negotiate # ipsec with the ipsec server. pass in log quick on $internal_if proto tcp from $user_ip to any \e port { 21, 22, 80, 443 } pass in quick on $internal_if proto tcp from $user_ip to any \e port { 21, 22, 80, 443 } pass in quick proto udp from $user_ip to $ipsec_gw port = isakmp pass in quick proto esp from $user_ip to $ipsec_gw .Ed .Pp .Sy Dealing with NAT \- The following .Pa /etc/authpf/authpf.rules shows how to deal with NAT, using tags: .Bd -literal ext_if = "fxp1" ext_addr = 129.128.11.10 int_if = "fxp0" # nat and tag connections... nat on $ext_if from $user_ip to any tag $user_ip -> $ext_addr pass in quick on $int_if from $user_ip to any pass out log quick on $ext_if tagged $user_ip .Ed .Pp With the above rules added by .Nm , outbound connections corresponding to each users NAT'ed connections will be logged as in the example below, where the user may be identified from the ruleset name. .Bd -literal # tcpdump -n -e -ttt -i pflog0 Oct 31 19:42:30.296553 rule 0.bbeck(20267).1/0(match): pass out on fxp1: \e 129.128.11.10.60539 > 198.137.240.92.22: S 2131494121:2131494121(0) win \e 16384 (DF) .Ed .Pp .Sy Using the authpf_users table \- Simple .Nm settings can be implemented without an anchor by just using the "authpf_users" .Pa table . For example, the following .Xr pf.conf 5 lines will give SMTP and IMAP access to logged in users: .Bd -literal table persist pass in on $ext_if proto tcp from \e to port { smtp imap } .Ed .Pp It is also possible to use the "authpf_users" .Pa table in combination with anchors. For example, .Xr pf 4 processing can be sped up by looking up the anchor only for packets coming from logged in users: .Bd -literal table persist anchor "authpf/*" from rdr-anchor "authpf/*" from .Ed .Pp .Sy Tunneled users \- normally .Nm allows only one session per client IP address. However in some cases, such as when connections are tunneled via .Xr ssh 1 or .Xr ipsec 4 , the connections can be authorized based on the userid of the user instead of the client IP address. In this case it is appropriate to use .Nm authpf-noip to allow multiple users behind a NAT gateway to connect. In the .Pa /etc/authpf/authpf.rules example below, the remote user could tunnel a remote desktop session to their workstation: .Bd -literal internal_if="bge0" workstation_ip="10.2.3.4" pass out on $internal_if from (self) to $workstation_ip port 3389 \e user $user_id .Ed .Sh FILES .Bl -tag -width "/etc/authpf/authpf.conf" -compact .It Pa /etc/authpf/authpf.conf .It Pa /etc/authpf/authpf.allow .It Pa /etc/authpf/authpf.rules .It Pa /etc/authpf/authpf.message .It Pa /etc/authpf/authpf.problem .El .Sh SEE ALSO +.Xr fdescfs 4 , .Xr pf 4 , -.Xr fdescfs 5 , .Xr pf.conf 5 , .Xr securelevel 7 , .Xr ftp-proxy 8 .Sh HISTORY The .Nm program first appeared in .Ox 3.1 . .Sh BUGS Configuration issues are tricky. The authenticating .Xr ssh 1 connection may be secured, but if the network is not secured the user may expose insecure protocols to attackers on the same network, or enable other attackers on the network to pretend to be the user by spoofing their IP address. .Pp .Nm is not designed to prevent users from denying service to other users. diff --git a/lib/geom/label/glabel.8 b/lib/geom/label/glabel.8 index 6b089172348f..d6f253342905 100644 --- a/lib/geom/label/glabel.8 +++ b/lib/geom/label/glabel.8 @@ -1,298 +1,298 @@ .\" Copyright (c) 2004-2005 Pawel Jakub Dawidek .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd April 19, 2024 .Dt GLABEL 8 .Os .Sh NAME .Nm glabel .Nd "disk labelization control utility" .Sh SYNOPSIS .Nm .Cm create .Op Fl v .Ar name .Ar dev .Nm .Cm destroy .Op Fl fv .Ar name ... .Nm .Cm label .Op Fl v .Ar name .Ar dev .Nm .Cm stop .Op Fl fv .Ar name ... .Nm .Cm clear .Op Fl v .Ar dev ... .Nm .Cm dump .Ar dev ... .Nm .Cm refresh .Ar dev ... .Nm .Cm list .Nm .Cm status .Nm .Cm load .Nm .Cm unload .Sh DESCRIPTION The .Nm utility is used for GEOM provider labelization. A label can be set up on a GEOM provider in two ways: .Dq manual or .Dq automatic . When using the .Dq manual method, no metadata are stored on the devices, so a label has to be configured by hand every time it is needed. The .Dq automatic method uses on-disk metadata to store the label and detect it automatically in the future. .Pp This GEOM class also provides volume label detection for file systems. Those labels cannot be set with .Nm , but must be set with the appropriate file system utility, e.g.\& for UFS the file system label is set with .Xr tunefs 8 . Currently supported file systems are: .Pp .Bl -bullet -offset indent -compact .It UFS1 volume names (directory .Pa /dev/ufs/ ) . .It UFS2 volume names (directory .Pa /dev/ufs/ ) . .It UFS1 file system IDs (directory .Pa /dev/ufsid/ ) . .It UFS2 file system IDs (directory .Pa /dev/ufsid/ ) . .It MSDOSFS (FAT12, FAT16, FAT32) (directory .Pa /dev/msdosfs/ ) . .It CD ISO9660 (directory .Pa /dev/iso9660/ ) . .It EXT2FS (directory .Pa /dev/ext2fs/ ) . .It NTFS (directory .Pa /dev/ntfs/ ) . .It Swap Linux (directory .Pa /dev/swaplinux/ ) . .El .Pp Support for partition metadata is implemented for: .Pp .Bl -bullet -offset indent -compact .It GPT labels (directory .Pa /dev/gpt/ ) . .It GPT UUIDs (directory .Pa /dev/gptid/ ) . .El .Pp Generic disk ID strings are exported as labels in the format .Pa /dev/diskid/GEOM_CLASS-ident e.g. .Pa /dev/diskid/DISK-6QG3Z026 . .Pp Generic labels created and managed solely by .Xr glabel 8 are created in the .Pa /dev/label/ directory. Note that generic, automatic labels occupy some space on the device and thus should not be added to a device already containing a file system. In particular, .Nm reserves the last sector of the device to store the label information. If the device already contains a file system, .Nm will overwrite the last sector, possibly damaging the file system, and the file system may later overwrite the label sector. Instead, create a label before initializing the file system, and initialize that file system on the device created by .Nm under the .Pa /dev/label/ directory. Then the file system will correctly account for the space occupied by the generic label, since the .Nm device will be one sector smaller than the device from which it was created. .Pp Note that for all label types, nested GEOM classes will cause additional device nodes to be created, with context-specific data appended to their names. E.g. for every node like .Pa /dev/label/bigdisk there will be additional entries for any partitions which the device contains, like .Pa /dev/label/bigdiskp1 and .Pa /dev/label/bigdiskp1a . .Pp The first argument to .Nm indicates an action to be performed: .Bl -tag -width ".Cm destroy" .It Cm create Create temporary label .Ar name for the given provider. This is the .Dq manual method. The kernel module .Pa geom_label.ko will be loaded if it is not loaded already. .It Cm label Set up a label .Ar name for the given provider. This is the .Dq automatic method, where metadata is stored in a provider's last sector. The kernel module .Pa geom_label.ko will be loaded if it is not loaded already. .It Cm stop Turn off the given label by its .Ar name . This command does not touch on-disk metadata! .It Cm destroy Same as .Cm stop . .It Cm clear Clear metadata on the given devices. .It Cm dump Dump metadata stored on the given devices. .It Cm refresh Refresh / rediscover metadata from the given devices. .It Cm list See .Xr geom 8 . .It Cm status See .Xr geom 8 . .It Cm load See .Xr geom 8 . .It Cm unload See .Xr geom 8 . .El .Pp Additional options: .Bl -tag -width indent .It Fl f Force the removal of the specified labels. .It Fl v Be more verbose. .El .Sh SYSCTL VARIABLES The following .Xr sysctl 8 variables can be used to control the behavior of the .Nm LABEL GEOM class. The default value is shown next to each variable. .Bl -tag -width indent .It Va kern.geom.label.debug : No 0 Debug level of the .Nm LABEL GEOM class. This can be set to a number between 0 and 2 inclusive. If set to 0 minimal debug information is printed, and if set to 2 the maximum amount of debug information is printed. .El .Bl -tag -width indent .It Va kern.geom.label.*.enable : No 1 Most .Nm LABEL providers implement a .Xr sysctl 8 flag and a tunable variable named in the above format. This flag controls if the label provider will be active, tasting devices and creating label nodes in the -.Xr devfs 5 +.Xr devfs 4 tree. It is sometimes desirable to disable certain label types if they conflict with other classes in complex GEOM topologies. .El .Sh EXIT STATUS Exit status is 0 on success, and 1 if the command fails. .Sh EXAMPLES The following example shows how to set up a label for disk .Dq Li da2 , create a file system on it, and mount it: .Bd -literal -offset indent glabel label -v usr /dev/da2 newfs /dev/label/usr mount /dev/label/usr /usr [...] umount /usr glabel stop usr glabel unload .Ed .Pp The next example shows how to set up a label for a UFS file system: .Bd -literal -offset indent tunefs -L data /dev/da4s1a mount /dev/ufs/data /mnt/data .Ed .Sh SEE ALSO .Xr geom 4 , .Xr loader.conf 5 , .Xr geom 8 , .Xr mount 8 , .Xr newfs 8 , .Xr sysctl 8 , .Xr tunefs 8 , .Xr umount 8 .Sh HISTORY The .Nm utility appeared in .Fx 5.3 . .Sh AUTHORS .An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org diff --git a/lib/libc/posix1e/posix1e.3 b/lib/libc/posix1e/posix1e.3 index 8eef3bb21724..1dbe12427da1 100644 --- a/lib/libc/posix1e/posix1e.3 +++ b/lib/libc/posix1e/posix1e.3 @@ -1,116 +1,116 @@ .\"- .\" Copyright (c) 2000, 2009 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 25, 2016 .Dt POSIX1E 3 .Os .Sh NAME .Nm posix1e .Nd introduction to the POSIX.1e security API .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In sys/acl.h .In sys/mac.h .Sh DESCRIPTION POSIX.1e describes five security extensions to the POSIX.1 API: Access Control Lists (ACLs), Auditing, Capabilities, Mandatory Access Control, and Information Flow Labels. While IEEE POSIX.1e D17 specification has not been standardized, several of its interfaces are widely used. .Pp .Fx implements POSIX.1e interface for access control lists, described in .Xr acl 3 , and supports ACLs on the -.Xr ffs 7 +.Xr ffs 4 file system; ACLs must be administratively enabled using .Xr tunefs 8 . .Pp .Fx implements a POSIX.1e-like mandatory access control interface, described in .Xr mac 3 , although with a number of extensions and important semantic differences. .Pp .Fx does not implement the POSIX.1e audit, privilege (capability), or information flow label APIs. However, .Fx does implement the .Xr libbsm 3 audit API. It also provides .Xr capsicum 4 , a lightweight OS capability and sandbox framework implementing a hybrid capability system model. .Sh ENVIRONMENT POSIX.1e assigns security attributes to all objects, extending the security functionality described in POSIX.1. These additional attributes store fine-grained discretionary access control information and mandatory access control labels; for files, they are stored in extended attributes, described in .Xr extattr 3 . .Pp POSIX.2c describes a set of userland utilities for manipulating these attributes, including .Xr getfacl 1 and .Xr setfacl 1 for access control lists, and .Xr getfmac 8 and .Xr setfmac 8 for mandatory access control labels. .Sh SEE ALSO .Xr getfacl 1 , .Xr setfacl 1 , .Xr extattr 2 , .Xr acl 3 , .Xr extattr 3 , .Xr libbsm 3 , .Xr libcasper 3 , .Xr mac 3 , .Xr capsicum 4 , -.Xr ffs 7 , +.Xr ffs 4 , .Xr getfmac 8 , .Xr setfmac 8 , .Xr tunefs 8 , .Xr acl 9 , .Xr extattr 9 , .Xr mac 9 .Sh STANDARDS POSIX.1e is described in IEEE POSIX.1e draft 17. .Sh HISTORY POSIX.1e support was introduced in .Fx 4.0 ; most features were available as of .Fx 5.0 . .Sh AUTHORS .An Robert N M Watson .An Chris D. Faulhaber .An Thomas Moestl .An Ilmar S Habibulin diff --git a/lib/libsys/execve.2 b/lib/libsys/execve.2 index 8fc1f2529197..5a35980e9555 100644 --- a/lib/libsys/execve.2 +++ b/lib/libsys/execve.2 @@ -1,379 +1,379 @@ .\" Copyright (c) 1980, 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 26, 2022 .Dt EXECVE 2 .Os .Sh NAME .Nm execve , .Nm fexecve .Nd execute a file .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In unistd.h .Ft int .Fn execve "const char *path" "char *const argv[]" "char *const envp[]" .Ft int .Fn fexecve "int fd" "char *const argv[]" "char *const envp[]" .Sh DESCRIPTION The .Fn execve system call transforms the calling process into a new process. The new process is constructed from an ordinary file, whose name is pointed to by .Fa path , called the .Em new process file . The .Fn fexecve system call is equivalent to .Fn execve except that the file to be executed is determined by the file descriptor .Fa fd instead of a .Fa path . This file is either an executable object file, or a file of data for an interpreter. An executable object file consists of an identifying header, followed by pages of data representing the initial program (text) and initialized data pages. Additional pages may be specified by the header to be initialized with zero data; see .Xr elf 5 and .Xr a.out 5 . .Pp An interpreter file begins with a line of the form: .Pp .Bd -ragged -offset indent -compact .Sy \&#! .Em interpreter .Bq Em arg .Ed .Pp When an interpreter file is .Sy execve Ap d , the system actually .Sy execve Ap s the specified .Em interpreter . If the optional .Em arg is specified, it becomes the first argument to the .Em interpreter , and the name of the originally .Sy execve Ap d file becomes the second argument; otherwise, the name of the originally .Sy execve Ap d file becomes the first argument. The original arguments are shifted over to become the subsequent arguments. The zeroth argument is set to the specified .Em interpreter . .Pp The argument .Fa argv is a pointer to a null-terminated array of character pointers to null-terminated character strings. These strings construct the argument list to be made available to the new process. At least one argument must be present in the array; by custom, the first element should be the name of the executed program (for example, the last component of .Fa path ) . .Pp The argument .Fa envp is also a pointer to a null-terminated array of character pointers to null-terminated strings. A pointer to this array is normally stored in the global variable .Va environ . These strings pass information to the new process that is not directly an argument to the command (see .Xr environ 7 ) . .Pp File descriptors open in the calling process image remain open in the new process image, except for those for which the close-on-exec flag is set (see .Xr close 2 and .Xr fcntl 2 ) . Descriptors that remain open are unaffected by .Fn execve . If any of the standard descriptors (0, 1, and/or 2) are closed at the time .Fn execve is called, and the process will gain privilege as a result of set-id semantics, those descriptors will be re-opened automatically. No programs, whether privileged or not, should assume that these descriptors will remain closed across a call to .Fn execve . .Pp Signals set to be ignored in the calling process are set to be ignored in the new process. Signals which are set to be caught in the calling process image are set to default action in the new process image. Blocked signals remain blocked regardless of changes to the signal action. The signal stack is reset to be undefined (see .Xr sigaction 2 for more information). .Pp If the set-user-ID mode bit of the new process image file is set (see .Xr chmod 2 ) , the effective user ID of the new process image is set to the owner ID of the new process image file. If the set-group-ID mode bit of the new process image file is set, the effective group ID of the new process image is set to the group ID of the new process image file. (The effective group ID is the first element of the group list.) The real user ID, real group ID and other group IDs of the new process image remain the same as the calling process image. After any set-user-ID and set-group-ID processing, the effective user ID is recorded as the saved set-user-ID, and the effective group ID is recorded as the saved set-group-ID. These values may be used in changing the effective IDs later (see .Xr setuid 2 ) . .Pp The set-ID bits are not honored if the respective file system has the .Cm nosuid option enabled or if the new process file is an interpreter file. Syscall tracing is disabled if effective IDs are changed. .Pp The new process also inherits the following attributes from the calling process: .Pp .Bl -column parent_process_ID -offset indent -compact .It process ID Ta see Xr getpid 2 .It parent process ID Ta see Xr getppid 2 .It process group ID Ta see Xr getpgrp 2 .It access groups Ta see Xr getgroups 2 .It working directory Ta see Xr chdir 2 .It root directory Ta see Xr chroot 2 .It control terminal Ta see Xr termios 4 .It resource usages Ta see Xr getrusage 2 .It interval timers Ta see Xr getitimer 2 .It resource limits Ta see Xr getrlimit 2 .It file mode mask Ta see Xr umask 2 .It signal mask Ta see Xr sigaction 2 , .Xr sigprocmask 2 .El .Pp When a program is executed as a result of an .Fn execve system call, it is entered as follows: .Bd -literal -offset indent main(argc, argv, envp) int argc; char **argv, **envp; .Ed .Pp where .Fa argc is the number of elements in .Fa argv (the ``arg count'') and .Fa argv points to the array of character pointers to the arguments themselves. .Pp The .Fn fexecve ignores the file offset of .Fa fd . Since execute permission is checked by .Fn fexecve , the file descriptor .Fa fd need not have been opened with the .Dv O_EXEC flag. However, if the file to be executed denies read permission for the process preparing to do the exec, the only way to provide the .Fa fd to .Fn fexecve is to use the .Dv O_EXEC flag when opening .Fa fd . Note that the file to be executed can not be open for writing. .Sh RETURN VALUES As the .Fn execve system call overlays the current process image with a new process image the successful call has no process to return to. If .Fn execve does return to the calling process an error has occurred; the return value will be -1 and the global variable .Va errno is set to indicate the error. .Sh ERRORS The .Fn execve system call will fail and return to the calling process if: .Bl -tag -width Er .It Bq Er ENOTDIR A component of the path prefix is not a directory. .It Bq Er ENAMETOOLONG A component of a pathname exceeded 255 characters, or an entire path name exceeded 1023 characters. .It Bq Er ENOEXEC When invoking an interpreted script, the length of the first line, inclusive of the .Sy \&#! prefix and terminating newline, exceeds .Dv MAXSHELLCMDLEN characters. .It Bq Er ENOENT The new process file does not exist. .It Bq Er ELOOP Too many symbolic links were encountered in translating the pathname. .It Bq Er EACCES Search permission is denied for a component of the path prefix. .It Bq Er EACCES The new process file is not an ordinary file. .It Bq Er EACCES The new process file mode denies execute permission. .It Bq Er EINVAL .Fa argv did not contain at least one element. .It Bq Er ENOEXEC The new process file has the appropriate access permission, but has an invalid magic number in its header. .It Bq Er ETXTBSY The new process file is a pure procedure (shared text) file that is currently open for writing by some process. .It Bq Er ENOMEM The new process requires more virtual memory than is allowed by the imposed maximum .Pq Xr getrlimit 2 . .It Bq Er E2BIG The number of bytes in the new process' argument list is larger than the system-imposed limit. This limit is specified by the .Xr sysctl 3 MIB variable .Dv KERN_ARGMAX . .It Bq Er EFAULT The new process file is not as long as indicated by the size values in its header. .It Bq Er EFAULT The .Fa path , .Fa argv , or .Fa envp arguments point to an illegal address. .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. .El .Pp In addition, the .Fn fexecve will fail and return to the calling process if: .Bl -tag -width Er .It Bq Er EBADF The .Fa fd argument is not a valid file descriptor open for executing. .El .Sh SEE ALSO .Xr ktrace 1 , .Xr _exit 2 , .Xr fork 2 , .Xr open 2 , .Xr execl 3 , .Xr exit 3 , .Xr sysctl 3 , +.Xr fdescfs 4 , .Xr a.out 5 , .Xr elf 5 , -.Xr fdescfs 5 , .Xr environ 7 , .Xr mount 8 .Sh STANDARDS The .Fn execve system call conforms to .St -p1003.1-2001 , with the exception of reopening descriptors 0, 1, and/or 2 in certain circumstances. A future update of the Standard is expected to require this behavior, and it may become the default for non-privileged processes as well. .\" NB: update this caveat when TC1 is blessed. The support for executing interpreted programs is an extension. The .Fn fexecve system call conforms to The Open Group Extended API Set 2 specification. .Sh HISTORY The .Fn execve system call appeared in .At v7 . The .Fn fexecve system call appeared in .Fx 8.0 . .Sh CAVEATS If a program is .Em setuid to a non-super-user, but is executed when the real .Em uid is ``root'', then the program has some of the powers of a super-user as well. .Pp When executing an interpreted program through .Fn fexecve , kernel supplies .Pa /dev/fd/n as a second argument to the interpreter, where .Ar n is the file descriptor passed in the .Fa fd argument to .Fn fexecve . For this construction to work correctly, the -.Xr fdescfs 5 +.Xr fdescfs 4 filesystem shall be mounted on .Pa /dev/fd . diff --git a/lib/libsys/i386/i386_set_watch.3 b/lib/libsys/i386/i386_set_watch.3 index 68c46e0ec081..265c21119c53 100644 --- a/lib/libsys/i386/i386_set_watch.3 +++ b/lib/libsys/i386/i386_set_watch.3 @@ -1,116 +1,116 @@ .\" Copyright (c) 2000 Brian S. Dean .\" All rights reserved. .\" .\" This man-page is based on a similar man-page by Jonathan Lemon .\" which is copyrighted under the following conditions: .\" .\" 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 24, 2000 .Dt I386_SET_WATCH 3 .Os .Sh NAME .Nm i386_clr_watch , .Nm i386_set_watch .Nd manage i386 debug register values .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In machine/reg.h .In machine/sysarch.h .Ft int .Fn i386_clr_watch "int watchnum" "struct dbreg *d" .Ft int .Fn i386_set_watch "int watchnum" "unsigned int watchaddr" "int size" "int access" "struct dbreg *d" .Sh DESCRIPTION The .Fn i386_clr_watch function will disable the indicated watch point within the specified debug register set. .Pp The .Fn i386_set_watch function will set up the specified debug registers as indicated by the arguments. The .Fa watchnum argument specifies which watch register is used, 0, 1, 2, 3, or \-1. If .Fa watchnum is \-1, a free watch register is found and used. If there are no free watch registers, an error code of \-1 is returned. The .Fa watchaddr argument specifies the watch address, .Fa size specifies the size in bytes of the area to be watched (1, 2, or 4 bytes), and .Fa access specifies the type of watch point: .Pp .Bd -literal -offset indent -compact DBREG_DR7_EXEC An execution breakpoint. DBREG_DR7_WRONLY Break only when the watch area is written to. DBREG_DR7_RDWR Break when the watch area is read from or written to. .Ed .Pp Note that these functions do not actually set or clear breakpoints; they manipulate the indicated debug register set. You must use .Xr ptrace 2 to retrieve and install the debug register values for a process. .Sh RETURN VALUES On success, the .Fn i386_clr_watch function returns 0. On error, \-1 returned which indicates that .Fa watchnum is invalid (not in the range of 0-3). If the specified watchnum was already disabled, no error is returned. .Pp On success, the .Fn i386_set_watch function returns the .Fa watchnum argument, or the watchnum actually used in the case where the specified .Fa watchnum was \-1. On error, the .Fn i386_set_watch function returns \-1 indicating that the watchpoint could not established because either no more watchpoints are available, or .Fa watchnum , .Fa size , or .Fa access is invalid. .Sh SEE ALSO .Xr ptrace 2 , -.Xr procfs 5 +.Xr procfs 4 .Sh AUTHORS This man page was written by .An Brian S. Dean . diff --git a/lib/libsys/mq_open.2 b/lib/libsys/mq_open.2 index 17e290e541ca..484fe95432da 100644 --- a/lib/libsys/mq_open.2 +++ b/lib/libsys/mq_open.2 @@ -1,344 +1,344 @@ .\" Copyright (c) 2005 David Xu .\" 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(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. .\" .\" 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 September 26, 2023 .Dt MQ_OPEN 2 .Os .Sh NAME .Nm mq_open .Nd "open a message queue (REALTIME)" .Sh LIBRARY .Lb librt .Sh SYNOPSIS .In mqueue.h .Ft mqd_t .Fn mq_open "const char *name" "int oflag" "..." .Sh DESCRIPTION The .Fn mq_open system call establishes the connection between a process and a message queue with a message queue descriptor. It creates an open message queue description that refers to the message queue, and a message queue descriptor that refers to that open message queue description. The message queue descriptor is used by other functions to refer to that message queue. The .Fa name argument points to a string naming a message queue. The .Fa name argument should conform to the construction rules for a pathname. The .Fa name should begin with a slash character. Processes calling .Fn mq_open with the same value of .Fa name refers to the same message queue object, as long as that name has not been removed. If the .Fa name argument is not the name of an existing message queue and creation is not requested, .Fn mq_open will fail and return an error. .Pp The .Fa oflag argument requests the desired receive and/or send access to the message queue. The requested access permission to receive messages or send messages would be granted if the calling process would be granted read or write access, respectively, to an equivalently protected file. .Pp The value of .Fa oflag is the bitwise-inclusive OR of values from the following list. Applications should specify exactly one of the first three values (access modes) below in the value of .Fa oflag : .Bl -tag -width ".Dv O_NONBLOCK" .It Dv O_RDONLY Open the message queue for receiving messages. The process can use the returned message queue descriptor with .Fn mq_receive , but not .Fn mq_send . A message queue may be open multiple times in the same or different processes for receiving messages. .It Dv O_WRONLY Open the queue for sending messages. The process can use the returned message queue descriptor with .Fn mq_send but not .Fn mq_receive . A message queue may be open multiple times in the same or different processes for sending messages. .It Dv O_RDWR Open the queue for both receiving and sending messages. The process can use any of the functions allowed for .Dv O_RDONLY and .Dv O_WRONLY . A message queue may be open multiple times in the same or different processes for sending messages. .El .Pp Any combination of the remaining flags may be specified in the value of .Fa oflag : .Bl -tag -width ".Dv O_NONBLOCK" .It Dv O_CREAT Create a message queue. It requires two additional arguments: .Fa mode , which is of type .Vt mode_t , and .Fa attr , which is a pointer to an .Vt mq_attr structure. If the pathname .Fa name has already been used to create a message queue that still exists, then this flag has no effect, except as noted under .Dv O_EXCL . Otherwise, a message queue will be created without any messages in it. The user ID of the message queue will be set to the effective user ID of the process, and the group ID of the message queue will be set to the effective group ID of the process. The permission bits of the message queue will be set to the value of the .Fa mode argument, except those set in the file mode creation mask of the process. When bits in .Fa mode other than the file permission bits are specified, the effect is unspecified. If .Fa attr is .Dv NULL , the message queue is created with implementation-defined default message queue attributes. If attr is .Pf non- Dv NULL and the calling process has the appropriate privilege on name, the message queue .Va mq_maxmsg and .Va mq_msgsize attributes will be set to the values of the corresponding members in the .Vt mq_attr structure referred to by .Fa attr . If .Fa attr is .Pf non- Dv NULL , but the calling process does not have the appropriate privilege on name, the .Fn mq_open function will fail and return an error without creating the message queue. .It Dv O_EXCL If .Dv O_EXCL and .Dv O_CREAT are set, .Fn mq_open will fail if the message queue name exists. .It Dv O_NONBLOCK Determines whether an .Fn mq_send or .Fn mq_receive waits for resources or messages that are not currently available, or fails with .Va errno set to .Er EAGAIN ; see .Xr mq_send 2 and .Xr mq_receive 2 for details. .El .Pp The .Fn mq_open system call does not add or remove messages from the queue. .Sh NOTES .Fx implements message queue based on file descriptor. The descriptor is inherited by child after .Xr fork 2 . The descriptor is closed in a new image after .Xr exec 3 . The .Xr select 2 and .Xr kevent 2 system calls are supported for message queue descriptor. .Pp Please see the -.Xr mqueuefs 5 +.Xr mqueuefs 4 man page for instructions on loading the module or compiling the service into the kernel. .Pp The number of queues available, the maximum number of messages per queue and the maximum message size are tunable .Xr sysctl 8 parameters. Their defaults are as follows. .Bl -column kern.mqueue.maxmsgsize integerxxx .It Sy "Name Type Default" .It "kern.mqueue.maxmq integer 100" .It "kern.mqueue.maxmsgsize integer 16384" .It "kern.mqueue.maxmsg integer 100" .El .Sh RETURN VALUES Upon successful completion, the function returns a message queue descriptor; otherwise, the function returns .Po Vt mqd_t Pc Ns \-1 and sets the global variable .Va errno to indicate the error. .Sh ERRORS The .Fn mq_open system call will fail if: .Bl -tag -width Er .It Bq Er EACCES The message queue exists and the permissions specified by .Fa oflag are denied, or the message queue does not exist and permission to create the message queue is denied. .It Bq Er EEXIST .Dv O_CREAT and .Dv O_EXCL are set and the named message queue already exists. .It Bq Er EINTR The .Fn mq_open function was interrupted by a signal. .It Bq Er EINVAL The .Fn mq_open function is not supported for the given name. .It Bq Er EINVAL .Dv O_CREAT was specified in .Fa oflag , the value of .Fa attr is not .Dv NULL , and either .Va mq_maxmsg or .Va mq_msgsize was less than or equal to zero. .It Bq Er EMFILE Too many message queue descriptors or file descriptors are currently in use by this process. .It Bq Er ENAMETOOLONG The length of the .Fa name argument exceeds .Brq Dv PATH_MAX or a pathname component is longer than .Brq Dv NAME_MAX . .It Bq Er ENFILE Too many message queues are currently open in the system. .It Bq Er ENOENT .Dv O_CREAT is not set and the named message queue does not exist. .It Bq Er ENOSPC There is insufficient space for the creation of the new message queue. .El .Sh SEE ALSO .Xr mq_close 2 , .Xr mq_getattr 2 , .Xr mq_receive 2 , .Xr mq_send 2 , .Xr mq_setattr 2 , .Xr mq_unlink 2 , .Xr mq_timedreceive 3 , .Xr mq_timedsend 3 , -.Xr mqueuefs 5 +.Xr mqueuefs 4 .Sh STANDARDS The .Fn mq_open system call conforms to .St -p1003.1-2004 . .Sh HISTORY Support for POSIX message queues first appeared in .Fx 7.0 . .Sh BUGS This implementation places strict requirements on the value of .Fa name : it must begin with a slash .Pq Ql / and contain no other slash characters. .Pp The .Fa mode and .Fa attr arguments are variadic and may result in different calling conventions than might otherwise be expected. .Sh COPYRIGHT 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. diff --git a/lib/libsys/mq_unlink.2 b/lib/libsys/mq_unlink.2 index 07f0364abe00..1bc74b85524f 100644 --- a/lib/libsys/mq_unlink.2 +++ b/lib/libsys/mq_unlink.2 @@ -1,119 +1,119 @@ .\" Copyright (c) 2021 Fernando Apesteguia .\" .\" 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. .\" .\" 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 February 15, 2021 .Dt MQ_UNLINK 2 .Os .Sh NAME .Nm mq_unlink .Nd "mq_unlink - remove a message queue (REALTIME)" .Sh LIBRARY .Lb librt .Sh SYNOPSIS .In mqueue.h .Ft int .Fn mq_unlink "const char *name" .Sh DESCRIPTION The .Fn mq_unlink function removes the message queue named by the string .Fa name . If one or more processes have the message queue open when .Fn mq_unlink is called, destruction of the message queue will be postponed until all references to the message queue have been closed. However, the .Fn mq_unlink call need not block until all references have been closed; it may return immediately. .Pp After a successful call to .Fn mq_unlink , reuse of the name will subsequently cause .Xr mq_open 2 to behave as if no message queue of this name exists. .Sh RETURN VALUES .Rv -std .Sh ERRORS The .Fn mq_unlink system call will fail if: .Bl -tag -width Er .It Bq Er EACCESS Permission is denied to unlink the message queue represented by .Fa name . .It Bq Er EINVAL .Fa name is invalid. .It Bq Er ENAMETOOLONG The length of the .Fa name argument exceeds .Brq Dv PATH_MAX or a pathname component is longer than .Brq Dv NAME_MAX . .It Bq Er ENOENT The message queue does not exist. .It Bq Er ENOSYS -.Xr mqueuefs 5 +.Xr mqueuefs 4 module is neither loaded nor included in the kernel. .El .Sh SEE ALSO .Xr mq_open 2 .Sh STANDARDS The .Fn mq_unlink system call conforms to .St -p1003.1-2004 . The .Bq Er EACCESS error code is an extension to the standard. .Sh HISTORY Support for POSIX message queues first appeared in .Fx 7.0 . .Sh COPYRIGHT 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. diff --git a/lib/libsys/open.2 b/lib/libsys/open.2 index aac3ef1318f8..be164aae1834 100644 --- a/lib/libsys/open.2 +++ b/lib/libsys/open.2 @@ -1,702 +1,702 @@ .\" Copyright (c) 1980, 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 29, 2024 .Dt OPEN 2 .Os .Sh NAME .Nm open , openat .Nd open or create a file for reading, writing or executing .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In fcntl.h .Ft int .Fn open "const char *path" "int flags" "..." .Ft int .Fn openat "int fd" "const char *path" "int flags" "..." .Sh DESCRIPTION The file name specified by .Fa path is opened for either execution or reading and/or writing as specified by the argument .Fa flags and the file descriptor returned to the calling process. The .Fa flags argument may indicate the file is to be created if it does not exist (by specifying the .Dv O_CREAT flag). In this case .Fn open and .Fn openat require an additional argument .Fa "mode_t mode" , and the file is created with mode .Fa mode as described in .Xr chmod 2 and modified by the process' umask value (see .Xr umask 2 ) . .Pp The .Fn openat function is equivalent to the .Fn open function except in the case where the .Fa path specifies a relative path. For .Fn openat and relative .Fa path , the file to be opened is determined relative to the directory associated with the file descriptor .Fa fd instead of the current working directory. The .Fa flag parameter and the optional fourth parameter correspond exactly to the parameters of .Fn open . If .Fn openat is passed the special value .Dv AT_FDCWD in the .Fa fd parameter, the current working directory is used and the behavior is identical to a call to .Fn open . .Pp When .Fn openat is called with an absolute .Fa path , it ignores the .Fa fd argument. .Pp In .Xr capsicum 4 capability mode, .Fn open is not permitted. The .Fa path argument to .Fn openat must be strictly relative to a file descriptor .Fa fd . .Fa path must not be an absolute path and must not contain ".." components which cause the path resolution to escape the directory hierarchy starting at .Fa fd . Additionally, no symbolic link in .Fa path may target absolute path or contain escaping ".." components. .Fa fd must not be .Dv AT_FDCWD . .Pp If the .Dv vfs.lookup_cap_dotdot .Xr sysctl 3 MIB is set to zero, ".." components in the paths, used in capability mode, are completely disabled. If the .Dv vfs.lookup_cap_dotdot_nonlocal MIB is set to zero, ".." is not allowed if found on non-local filesystem. .Pp The flags specified are formed by .Em or Ns 'ing the following values .Pp .Bd -literal -offset indent -compact O_RDONLY open for reading only O_WRONLY open for writing only O_RDWR open for reading and writing O_EXEC open for execute only O_SEARCH open for search only, an alias for O_EXEC O_NONBLOCK do not block on open O_APPEND append on each write O_CREAT create file if it does not exist O_TRUNC truncate size to 0 O_EXCL error if create and file exists O_SHLOCK atomically obtain a shared lock O_EXLOCK atomically obtain an exclusive lock O_DIRECT eliminate or reduce cache effects O_FSYNC synchronous writes (historical synonym for O_SYNC) O_SYNC synchronous writes O_DSYNC synchronous data writes O_NOFOLLOW do not follow symlinks O_NOCTTY ignored O_TTY_INIT ignored O_DIRECTORY error if file is not a directory O_CLOEXEC set FD_CLOEXEC upon open O_VERIFY verify the contents of the file O_RESOLVE_BENEATH path resolution must not cross the fd directory O_PATH record only the target path in the opened descriptor O_EMPTY_PATH openat, open file referenced by fd if path is empty .Ed .Pp Opening a file with .Dv O_APPEND set causes each write on the file to be appended to the end. If .Dv O_TRUNC is specified and the file exists, the file is truncated to zero length. If .Dv O_EXCL is set with .Dv O_CREAT and the file already exists, .Fn open returns an error. This may be used to implement a simple exclusive access locking mechanism. If .Dv O_EXCL is set and the last component of the pathname is a symbolic link, .Fn open will fail even if the symbolic link points to a non-existent name. If the .Dv O_NONBLOCK flag is specified and the .Fn open system call would result in the process being blocked for some reason (e.g., waiting for carrier on a dialup line), .Fn open returns immediately. The descriptor remains in non-blocking mode for subsequent operations. .Pp If .Dv O_SYNC is used in the mask, all writes will immediately and synchronously be written to disk. .Dv O_FSYNC is an historical synonym for .Dv O_SYNC . .Pp If .Dv O_DSYNC is used in the mask, all data and metadata required to read the data will be synchronously written to disk, but changes to metadata such as file access and modification timestamps may be written later. .Pp If .Dv O_NOFOLLOW is used in the mask and the target file passed to .Fn open is a symbolic link then the .Fn open will fail. .Pp When opening a file, a lock with .Xr flock 2 semantics can be obtained by setting .Dv O_SHLOCK for a shared lock, or .Dv O_EXLOCK for an exclusive lock. If creating a file with .Dv O_CREAT , the request for the lock will never fail (provided that the underlying file system supports locking). .Pp .Dv O_DIRECT may be used to minimize or eliminate the cache effects of reading and writing. The system will attempt to avoid caching the data you read or write. If it cannot avoid caching the data, it will minimize the impact the data has on the cache. Use of this flag can drastically reduce performance if not used with care. .Pp .Dv O_NOCTTY may be used to ensure the OS does not assign this file as the controlling terminal when it opens a tty device. This is the default on .Fx , but is present for .Tn POSIX compatibility. The .Fn open system call will not assign controlling terminals on .Fx . .Pp .Dv O_TTY_INIT may be used to ensure the OS restores the terminal attributes when initially opening a TTY. This is the default on .Fx , but is present for .Tn POSIX compatibility. The initial call to .Fn open on a TTY will always restore default terminal attributes on .Fx . .Pp .Dv O_DIRECTORY may be used to ensure the resulting file descriptor refers to a directory. This flag can be used to prevent applications with elevated privileges from opening files which are even unsafe to open with .Dv O_RDONLY , such as device nodes. .Pp .Dv O_CLOEXEC may be used to set .Dv FD_CLOEXEC flag for the newly returned file descriptor. .Pp .Dv O_VERIFY may be used to indicate to the kernel that the contents of the file should be verified before allowing the open to proceed. The details of what .Dq verified means is implementation specific. The run-time linker (rtld) uses this flag to ensure shared objects have been verified before operating on them. .Pp .Dv O_RESOLVE_BENEATH returns .Er ENOTCAPABLE if any intermediate component of the specified relative path does not reside in the directory hierarchy beneath the starting directory. Absolute paths or even the temporal escape from beneath of the starting directory is not allowed. .Pp When .Fa fd is opened with .Dv O_SEARCH , execute permissions are checked at open time. The .Fa fd may not be used for any read operations like .Xr getdirentries 2 . The primary use for this descriptor will be as the lookup descriptor for the .Fn *at family of functions. If .Dv O_SEARCH was not requested at open time, then the .Fn *at functions use the current directory permissions for the directory referenced by the descriptor at the time of the call. .Pp .Dv O_PATH returns a file descriptor that can be used as a directory file descriptor for .Fn openat and other system calls taking a file descriptor argument, like .Xr fstatat 2 and others. The other functionality of the returned file descriptor is limited to the descriptor-level operations. It can be used for .Bl -tag -width readlinkat(2) -offset indent -compact .It Xr fcntl 2 but advisory locking is not allowed .It Xr dup 2 .It Xr close 2 .It Xr fstat 2 .It Xr fexecve 2 .It Dv SCM_RIGHTS can be passed over a .Xr unix 4 socket using a .Dv SCM_RIGHTS message .It Xr kqueue 2 using for .Dv EVFILT_VNODE .It Xr readlinkat 2 .It Xr __acl_get_fd 2 , Xr __acl_aclcheck_fd 2 .El But operations like .Xr read 2 , .Xr ftruncate 2 , and any other that operate on file and not on file descriptor (except .Xr fstat 2 ), are not allowed. .Pp A file descriptor created with the .Dv O_PATH flag can be opened into normal (operable) file descriptor by specifying it as the .Fa fd argument to .Fn openat with empty .Fa path and flag .Dv O_EMPTY_PATH . Such an open behaves as if the current path of the file referenced by .Fa fd is passed, except that the path walk permissions are not checked. See also the description of .Dv AT_EMPTY_PATH flag for .Xr fstatat 2 and related syscalls. .Pp If successful, .Fn open returns a non-negative integer, termed a file descriptor. It returns \-1 on failure. The file pointer used to mark the current position within the file is set to the beginning of the file. .Pp If a sleeping open of a device node from -.Xr devfs 5 +.Xr devfs 4 is interrupted by a signal, the call always fails with .Er EINTR , even if the .Dv SA_RESTART flag is set for the signal. A sleeping open of a fifo (see .Xr mkfifo 2 ) is restarted as normal. .Pp When a new file is created it is given the group of the directory which contains it. .Pp Unless .Dv O_CLOEXEC flag was specified, the new descriptor is set to remain open across .Xr execve 2 system calls; see .Xr close 2 , .Xr fcntl 2 and .Dv O_CLOEXEC description. .Pp The system imposes a limit on the number of file descriptors open simultaneously by one process. The .Xr getdtablesize 2 system call returns the current system limit. .Sh RETURN VALUES If successful, .Fn open and .Fn openat return a non-negative integer, termed a file descriptor. They return \-1 on failure, and set .Va errno to indicate the error. .Sh ERRORS The named file is opened unless: .Bl -tag -width Er .It Bq Er ENOTDIR A component of the path prefix is not a directory. .It Bq Er ENAMETOOLONG A component of a pathname exceeded 255 characters, or an entire path name exceeded 1023 characters. .It Bq Er ENOENT .Dv O_CREAT is not set and the named file does not exist. .It Bq Er ENOENT A component of the path name that must exist does not exist. .It Bq Er EACCES Search permission is denied for a component of the path prefix. .It Bq Er EACCES The required permissions (for reading and/or writing) are denied for the given flags. .It Bq Er EACCES .Dv O_TRUNC is specified and write permission is denied. .It Bq Er EACCES .Dv O_CREAT is specified, the file does not exist, and the directory in which it is to be created does not permit writing. .It Bq Er EPERM .Dv O_CREAT is specified, the file does not exist, and the directory in which it is to be created has its immutable flag set, see the .Xr chflags 2 manual page for more information. .It Bq Er EPERM The named file has its immutable flag set and the file is to be modified. .It Bq Er EPERM The named file has its append-only flag set, the file is to be modified, and .Dv O_TRUNC is specified or .Dv O_APPEND is not specified. .It Bq Er ELOOP Too many symbolic links were encountered in translating the pathname. .It Bq Er EISDIR The named file is a directory, and the arguments specify it is to be modified. .It Bq Er EISDIR The named file is a directory, and the flags specified .Dv O_CREAT without .Dv O_DIRECTORY . .It Bq Er EROFS The named file resides on a read-only file system, and the file is to be modified. .It Bq Er EROFS .Dv O_CREAT is specified and the named file would reside on a read-only file system. .It Bq Er EMFILE The process has already reached its limit for open file descriptors. .It Bq Er ENFILE The system file table is full. .It Bq Er EMLINK .Dv O_NOFOLLOW was specified and the target is a symbolic link. .Tn POSIX specifies a different error for this case; see the note in .Sx STANDARDS below. .It Bq Er ENXIO The named file is a character special or block special file, and the device associated with this special file does not exist. .It Bq Er ENXIO .Dv O_NONBLOCK is set, the named file is a fifo, .Dv O_WRONLY is set, and no process has the file open for reading. .It Bq Er EINTR The .Fn open operation was interrupted by a signal. .It Bq Er EOPNOTSUPP .Dv O_SHLOCK or .Dv O_EXLOCK is specified but the underlying file system does not support locking. .It Bq Er EOPNOTSUPP The named file is a special file mounted through a file system that does not support access to it (e.g.\& NFS). .It Bq Er EWOULDBLOCK .Dv O_NONBLOCK and one of .Dv O_SHLOCK or .Dv O_EXLOCK is specified and the file is locked. .It Bq Er ENOSPC .Dv O_CREAT is specified, the file does not exist, and the directory in which the entry for the new file is being placed cannot be extended because there is no space left on the file system containing the directory. .It Bq Er ENOSPC .Dv O_CREAT is specified, the file does not exist, and there are no free inodes on the file system on which the file is being created. .It Bq Er EDQUOT .Dv O_CREAT is specified, the file does not exist, and the directory in which the entry for the new file is being placed cannot be extended because the user's quota of disk blocks on the file system containing the directory has been exhausted. .It Bq Er EDQUOT .Dv O_CREAT is specified, the file does not exist, and the user's quota of inodes on the file system on which the file is being created has been exhausted. .It Bq Er EIO An I/O error occurred while making the directory entry or allocating the inode for .Dv O_CREAT . .It Bq Er EINTEGRITY Corrupted data was detected while reading from the file system. .It Bq Er ETXTBSY The file is a pure procedure (shared text) file that is being executed and the .Fn open system call requests write access. .It Bq Er EFAULT The .Fa path argument points outside the process's allocated address space. .It Bq Er EEXIST .Dv O_CREAT and .Dv O_EXCL were specified and the file exists. .It Bq Er EOPNOTSUPP An attempt was made to open a socket (not currently implemented). .It Bq Er EINVAL An attempt was made to open a descriptor with an illegal combination of .Dv O_RDONLY , .Dv O_WRONLY , or .Dv O_RDWR , and .Dv O_EXEC or .Dv O_SEARCH . .It Bq Er EBADF The .Fa path argument does not specify an absolute path and the .Fa fd argument is neither .Dv AT_FDCWD nor a valid file descriptor open for searching. .It Bq Er ENOTDIR The .Fa path argument is not an absolute path and .Fa fd is neither .Dv AT_FDCWD nor a file descriptor associated with a directory. .It Bq Er ENOTDIR .Dv O_DIRECTORY is specified and the file is not a directory. .It Bq Er ECAPMODE .Dv AT_FDCWD is specified and the process is in capability mode. .It Bq Er ECAPMODE .Fn open was called and the process is in capability mode. .It Bq Er ENOTCAPABLE .Fa path is an absolute path and the process is in capability mode. .It Bq Er ENOTCAPABLE .Fa path is an absolute path and .Dv O_RESOLVE_BENEATH is specified. .It Bq Er ENOTCAPABLE .Fa path contains a ".." component leading to a directory outside of the directory hierarchy specified by .Fa fd and the process is in capability mode. .It Bq Er ENOTCAPABLE .Fa path contains a ".." component leading to a directory outside of the directory hierarchy specified by .Fa fd and .Dv O_RESOLVE_BENEATH is specified. .It Bq Er ENOTCAPABLE .Fa path contains a ".." component, the .Dv vfs.lookup_cap_dotdot .Xr sysctl 3 is set, and the process is in capability mode. .El .Sh SEE ALSO .Xr chmod 2 , .Xr close 2 , .Xr dup 2 , .Xr fexecve 2 , .Xr fhopen 2 , .Xr getdtablesize 2 , .Xr getfh 2 , .Xr lgetfh 2 , .Xr lseek 2 , .Xr read 2 , .Xr umask 2 , .Xr write 2 , .Xr fopen 3 , .Xr capsicum 4 .Sh STANDARDS These functions are specified by .St -p1003.1-2008 . .Pp .Fx sets .Va errno to .Er EMLINK instead of .Er ELOOP as specified by .Tn POSIX when .Dv O_NOFOLLOW is set in flags and the final component of pathname is a symbolic link to distinguish it from the case of too many symbolic link traversals in one of its non-final components. .Pp The Open Group Extended API Set 2 specification, that introduced the .Fn *at API, required that the test for whether .Fa fd is searchable is based on whether .Fa fd is open for searching, not whether the underlying directory currently permits searches. The present implementation of the .Fa openat system call is believed to be compatible with .St -p1003.1-2017 , which specifies that behavior for .Dv O_SEARCH , in the absence of the flag the implementation checks the current permissions of a directory. .Sh HISTORY The .Fn open function appeared in .At v1 . The .Fn openat function was introduced in .Fx 8.0 . .Dv O_DSYNC appeared in 13.0. .Sh BUGS The .Fa mode argument is variadic and may result in different calling conventions than might otherwise be expected. diff --git a/lib/libsys/sendfile.2 b/lib/libsys/sendfile.2 index 3ffbd733494d..07a563d5ef82 100644 --- a/lib/libsys/sendfile.2 +++ b/lib/libsys/sendfile.2 @@ -1,443 +1,443 @@ .\" Copyright (c) 2003, David G. Lawrence .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice unmodified, this list of conditions, and the following .\" disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd March 30, 2020 .Dt SENDFILE 2 .Os .Sh NAME .Nm sendfile .Nd send a file to a socket .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .In sys/uio.h .Ft int .Fo sendfile .Fa "int fd" "int s" "off_t offset" "size_t nbytes" .Fa "struct sf_hdtr *hdtr" "off_t *sbytes" "int flags" .Fc .Sh DESCRIPTION The .Fn sendfile system call sends a regular file or shared memory object specified by descriptor .Fa fd out a stream socket specified by descriptor .Fa s . .Pp The .Fa offset argument specifies where to begin in the file. Should .Fa offset fall beyond the end of file, the system will return success and report 0 bytes sent as described below. The .Fa nbytes argument specifies how many bytes of the file should be sent, with 0 having the special meaning of send until the end of file has been reached. .Pp An optional header and/or trailer can be sent before and after the file data by specifying a pointer to a .Vt "struct sf_hdtr" , which has the following structure: .Pp .Bd -literal -offset indent -compact struct sf_hdtr { struct iovec *headers; /* pointer to header iovecs */ int hdr_cnt; /* number of header iovecs */ struct iovec *trailers; /* pointer to trailer iovecs */ int trl_cnt; /* number of trailer iovecs */ }; .Ed .Pp The .Fa headers and .Fa trailers pointers, if .Pf non- Dv NULL , point to arrays of .Vt "struct iovec" structures. See the .Fn writev system call for information on the iovec structure. The number of iovecs in these arrays is specified by .Fa hdr_cnt and .Fa trl_cnt . .Pp If .Pf non- Dv NULL , the system will write the total number of bytes sent on the socket to the variable pointed to by .Fa sbytes . .Pp The least significant 16 bits of .Fa flags argument is a bitmap of these values: .Bl -tag -offset indent -width "SF_USER_READAHEAD" .It Dv SF_NODISKIO This flag causes .Nm to return .Er EBUSY instead of blocking when a busy page is encountered. This rare situation can happen if some other process is now working with the same region of the file. It is advised to retry the operation after a short period. .Pp Note that in older .Fx versions the .Dv SF_NODISKIO had slightly different notion. The flag prevented .Nm to run I/O operations in case if an invalid (not cached) page is encountered, thus avoiding blocking on I/O. Starting with .Fx 11 .Nm sending files off the -.Xr ffs 7 +.Xr ffs 4 filesystem does not block on I/O (see .Sx IMPLEMENTATION NOTES ), so the condition no longer applies. However, it is safe if an application utilizes .Dv SF_NODISKIO and on .Er EBUSY performs the same action as it did in older .Fx versions, e.g., .Xr aio_read 2 , .Xr read 2 or .Nm in a different context. .It Dv SF_NOCACHE The data sent to socket will not be cached by the virtual memory system, and will be freed directly to the pool of free pages. .It Dv SF_SYNC .Nm sleeps until the network stack no longer references the VM pages of the file, making subsequent modifications to it safe. Please note that this is not a guarantee that the data has actually been sent. .It Dv SF_USER_READAHEAD .Nm has some internal heuristics to do readahead when sending data. This flag forces .Nm to override any heuristically calculated readahead and use exactly the application specified readahead. See .Sx SETTING READAHEAD for more details on readahead. .El .Pp When using a socket marked for non-blocking I/O, .Fn sendfile may send fewer bytes than requested. In this case, the number of bytes successfully written is returned in .Fa *sbytes (if specified), and the error .Er EAGAIN is returned. .Sh SETTING READAHEAD .Nm uses internal heuristics based on request size and file system layout to do readahead. Additionally application may request extra readahead. The most significant 16 bits of .Fa flags specify amount of pages that .Nm may read ahead when reading the file. A macro .Fn SF_FLAGS is provided to combine readahead amount and flags. An example showing specifying readahead of 16 pages and .Dv SF_NOCACHE flag: .Pp .Bd -literal -offset indent -compact SF_FLAGS(16, SF_NOCACHE) .Ed .Pp .Nm will use either application specified readahead or internally calculated, whichever is bigger. Setting flag .Dv SF_USER_READAHEAD would turn off any heuristics and set maximum possible readahead length to the number of pages specified via flags. .Sh IMPLEMENTATION NOTES The .Fx implementation of .Fn sendfile does not block on disk I/O when it sends a file off the -.Xr ffs 7 +.Xr ffs 4 filesystem. The syscall returns success before the actual I/O completes, and data is put into the socket later unattended. However, the order of data in the socket is preserved, so it is safe to do further writes to the socket. .Pp The .Fx implementation of .Fn sendfile is "zero-copy", meaning that it has been optimized so that copying of the file data is avoided. .Sh TUNING .Ss physical paging buffers .Fn sendfile uses vnode pager to read file pages into memory. The pager uses a pool of physical buffers to run its I/O operations. When system runs out of pbufs, sendfile will block and report state .Dq Li zonelimit . Size of the pool can be tuned with .Va vm.vnode_pbufs .Xr loader.conf 5 tunable and can be checked with .Xr sysctl 8 OID of the same name at runtime. .Ss sendfile(2) buffers On some architectures, this system call internally uses a special .Fn sendfile buffer .Pq Vt "struct sf_buf" to handle sending file data to the client. If the sending socket is blocking, and there are not enough .Fn sendfile buffers available, .Fn sendfile will block and report a state of .Dq Li sfbufa . If the sending socket is non-blocking and there are not enough .Fn sendfile buffers available, the call will block and wait for the necessary buffers to become available before finishing the call. .Pp The number of .Vt sf_buf Ns 's allocated should be proportional to the number of nmbclusters used to send data to a client via .Fn sendfile . Tune accordingly to avoid blocking! Busy installations that make extensive use of .Fn sendfile may want to increase these values to be inline with their .Va kern.ipc.nmbclusters (see .Xr tuning 7 for details). .Pp The number of .Fn sendfile buffers available is determined at boot time by either the .Va kern.ipc.nsfbufs .Xr loader.conf 5 variable or the .Dv NSFBUFS kernel configuration tunable. The number of .Fn sendfile buffers scales with .Va kern.maxusers . The .Va kern.ipc.nsfbufsused and .Va kern.ipc.nsfbufspeak read-only .Xr sysctl 8 variables show current and peak .Fn sendfile buffers usage respectively. These values may also be viewed through .Nm netstat Fl m . .Pp If .Xr sysctl 8 OID .Va kern.ipc.nsfbufs doesn't exist, your architecture does not need to use .Fn sendfile buffers because their task can be efficiently performed by the generic virtual memory structures. .Sh RETURN VALUES .Rv -std sendfile .Sh ERRORS .Bl -tag -width Er .It Bq Er EAGAIN The socket is marked for non-blocking I/O and not all data was sent due to the socket buffer being filled. If specified, the number of bytes successfully sent will be returned in .Fa *sbytes . .It Bq Er EBADF The .Fa fd argument is not a valid file descriptor. .It Bq Er EBADF The .Fa s argument is not a valid socket descriptor. .It Bq Er EBUSY A busy page was encountered and .Dv SF_NODISKIO had been specified. Partial data may have been sent. .It Bq Er EFAULT An invalid address was specified for an argument. .It Bq Er EINTR A signal interrupted .Fn sendfile before it could be completed. If specified, the number of bytes successfully sent will be returned in .Fa *sbytes . .It Bq Er EINVAL The .Fa fd argument is not a regular file. .It Bq Er EINVAL The .Fa s argument is not a SOCK_STREAM type socket. .It Bq Er EINVAL The .Fa offset argument is negative. .It Bq Er EIO An error occurred while reading from .Fa fd . .It Bq Er EINTEGRITY Corrupted data was detected while reading from .Fa fd . .It Bq Er ENOTCAPABLE The .Fa fd or the .Fa s argument has insufficient rights. .It Bq Er ENOBUFS The system was unable to allocate an internal buffer. .It Bq Er ENOTCONN The .Fa s argument points to an unconnected socket. .It Bq Er ENOTSOCK The .Fa s argument is not a socket. .It Bq Er EOPNOTSUPP The file system for descriptor .Fa fd does not support .Fn sendfile . .It Bq Er EPIPE The socket peer has closed the connection. .El .Sh SEE ALSO .Xr netstat 1 , .Xr open 2 , .Xr send 2 , .Xr socket 2 , .Xr writev 2 , .Xr loader.conf 5 , .Xr tuning 7 , .Xr sysctl 8 .Rs .%A K. Elmeleegy .%A A. Chanda .%A A. L. Cox .%A W. Zwaenepoel .%T A Portable Kernel Abstraction for Low-Overhead Ephemeral Mapping Management .%J The Proceedings of the 2005 USENIX Annual Technical Conference .%P pp 223-236 .%D 2005 .Re .Sh HISTORY The .Fn sendfile system call first appeared in .Fx 3.0 . This manual page first appeared in .Fx 3.1 . In .Fx 10 support for sending shared memory descriptors had been introduced. In .Fx 11 a non-blocking implementation had been introduced. .Sh AUTHORS The initial implementation of .Fn sendfile system call and this manual page were written by .An David G. Lawrence Aq Mt dg@dglawrence.com . The .Fx 11 implementation was written by .An Gleb Smirnoff Aq Mt glebius@FreeBSD.org . .Sh BUGS The .Fn sendfile system call will not fail, i.e., return .Dv -1 and set .Va errno to .Er EFAULT , if provided an invalid address for .Fa sbytes . The .Fn sendfile system call does not support SCTP sockets, it will return .Dv -1 and set .Va errno to .Er EINVAL . diff --git a/lib/libsys/statfs.2 b/lib/libsys/statfs.2 index 561774f686d8..50809869a022 100644 --- a/lib/libsys/statfs.2 +++ b/lib/libsys/statfs.2 @@ -1,253 +1,253 @@ .\" Copyright (c) 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 March 29, 2023 .Dt STATFS 2 .Os .Sh NAME .Nm statfs .Nd get file system statistics .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/param.h .In sys/mount.h .Ft int .Fn statfs "const char *path" "struct statfs *buf" .Ft int .Fn fstatfs "int fd" "struct statfs *buf" .Sh DESCRIPTION The .Fn statfs system call returns information about a mounted file system. The .Fa path argument is the path name of any file within the mounted file system. The .Fa buf argument is a pointer to a .Vt statfs structure defined as follows: .Bd -literal typedef struct fsid { int32_t val[2]; } fsid_t; /* file system id type */ /* * filesystem statistics */ #define MFSNAMELEN 16 /* length of type name including null */ #define MNAMELEN 1024 /* size of on/from name bufs */ #define STATFS_VERSION 0x20140518 /* current version number */ struct statfs { uint32_t f_version; /* structure version number */ uint32_t f_type; /* type of filesystem */ uint64_t f_flags; /* copy of mount exported flags */ uint64_t f_bsize; /* filesystem fragment size */ uint64_t f_iosize; /* optimal transfer block size */ uint64_t f_blocks; /* total data blocks in filesystem */ uint64_t f_bfree; /* free blocks in filesystem */ int64_t f_bavail; /* free blocks avail to non-superuser */ uint64_t f_files; /* total file nodes in filesystem */ int64_t f_ffree; /* free nodes avail to non-superuser */ uint64_t f_syncwrites; /* count of sync writes since mount */ uint64_t f_asyncwrites; /* count of async writes since mount */ uint64_t f_syncreads; /* count of sync reads since mount */ uint64_t f_asyncreads; /* count of async reads since mount */ uint64_t f_spare[10]; /* unused spare */ uint32_t f_namemax; /* maximum filename length */ uid_t f_owner; /* user that mounted the filesystem */ fsid_t f_fsid; /* filesystem id */ char f_charspare[80]; /* spare string space */ char f_fstypename[MFSNAMELEN]; /* filesystem type name */ char f_mntfromname[MNAMELEN]; /* mounted filesystem */ char f_mntonname[MNAMELEN]; /* directory on which mounted */ }; .Ed .Pp The flags that may be returned include: .Bl -tag -width MNT_SYNCHRONOUS .It Dv MNT_RDONLY The file system is mounted read-only; Even the super-user may not write on it. .It Dv MNT_NOEXEC Files may not be executed from the file system. .It Dv MNT_NOSUID Setuid and setgid bits on files are not honored when they are executed. .It Dv MNT_SYNCHRONOUS All I/O to the file system is done synchronously. .It Dv MNT_ASYNC No file system I/O is done synchronously. .It Dv MNT_SOFTDEP Soft updates being done (see -.Xr ffs 7 ) . +.Xr ffs 4 ) . .It Dv MNT_GJOURNAL Journaling with gjournal is enabled (see .Xr gjournal 8 ) . .It Dv MNT_SUIDDIR Special handling of SUID bit on directories. .It Dv MNT_UNION Union with underlying file system. .It Dv MNT_NOSYMFOLLOW Symbolic links are not followed. .It Dv MNT_NOCLUSTERR Read clustering is disabled. .It Dv MNT_NOCLUSTERW Write clustering is disabled. .\".It Dv MNT_JAILDEVFS .\"XXX .It Dv MNT_MULTILABEL Mandatory Access Control (MAC) support for individual objects (see .Xr mac 4 ) . .It Dv MNT_ACLS Access Control List (ACL) support enabled. .It Dv MNT_LOCAL The file system resides locally. .It Dv MNT_QUOTA The file system has quotas enabled on it. .It Dv MNT_ROOTFS Identifies the root file system. .It Dv MNT_EXRDONLY The file system is exported read-only. .It Dv MNT_NOATIME Updating of file access times is disabled. .It Dv MNT_USER The file system has been mounted by a user. .\".It Dv MNT_IGNORE .\"XXX .It Dv MNT_EXPORTED The file system is exported for both reading and writing. .It Dv MNT_DEFEXPORTED The file system is exported for both reading and writing to any Internet host. .It Dv MNT_EXPORTANON The file system maps all remote accesses to the anonymous user. .It Dv MNT_EXKERB The file system is exported with Kerberos uid mapping. .It Dv MNT_EXPUBLIC The file system is exported publicly (WebNFS). .El .Pp Fields that are undefined for a particular file system are set to -1. The .Fn fstatfs system call returns the same information about an open file referenced by descriptor .Fa fd . .Sh RETURN VALUES .Rv -std .Sh ERRORS The .Fn statfs system call fails if one or more of the following are true: .Bl -tag -width Er .It Bq Er ENOTDIR A component of the path prefix of .Fa path is not a directory. .It Bq Er ENAMETOOLONG The length of a component of .Fa path exceeds 255 characters, or the length of .Fa path exceeds 1023 characters. .It Bq Er ENOENT The file referred to by .Fa path does not exist. .It Bq Er EACCES Search permission is denied for a component of the path prefix of .Fa path . .It Bq Er ELOOP Too many symbolic links were encountered in translating .Fa path . .It Bq Er EFAULT The .Fa buf or .Fa path argument points to an invalid address. .It Bq Er EIO An .Tn I/O error occurred while reading from or writing to the file system. .It Bq Er EINTEGRITY Corrupted data was detected while reading from the file system. .El .Pp The .Fn fstatfs system call fails if one or more of the following are true: .Bl -tag -width Er .It Bq Er EBADF The .Fa fd argument is not a valid open file descriptor. .It Bq Er EFAULT The .Fa buf argument points to an invalid address. .It Bq Er EIO An .Tn I/O error occurred while reading from or writing to the file system. .It Bq Er EINTEGRITY Corrupted data was detected while reading from the file system. .El .Sh NOTES The fields in the .Vt statfs structure have been defined to provide the parameters relevant for traditional .Tm UNIX file systems. For some other file systems, values that have similar, but not identical, semantics to those described above may be returned. An example is msdosfs, which in case of FAT12 or FAT16 file systems reports the number of available and of free root directory entries instead of inodes .Po where 1 to 21 such directory entries are required to store each file or directory name or disk label .Pc . .Sh SEE ALSO .Xr fhstatfs 2 , .Xr getfsstat 2 .Sh HISTORY The .Fn statfs system call first appeared in .Bx 4.4 . diff --git a/lib/libufs/libufs.3 b/lib/libufs/libufs.3 index 9547396249de..aa3386ad9771 100644 --- a/lib/libufs/libufs.3 +++ b/lib/libufs/libufs.3 @@ -1,85 +1,85 @@ .\" Author: Juli Mallett .\" Date: June 04, 2003 .\" Description: .\" Manual page for libufs. .\" .\" This file is in the public domain. .\" .Dd September 2, 2020 .Dt LIBUFS 3 .Os .Sh NAME .Nm libufs .Nd operate on UFS file systems from userland .Sh LIBRARY .Lb libufs .Sh SYNOPSIS .In sys/param.h .In sys/mount.h .In ufs/ufs/ufsmount.h .In ufs/ufs/dinode.h .In ufs/ffs/fs.h .In libufs.h .Sh DESCRIPTION The .Nm library and the functions it provides are used for implementing utilities which need to access a UFS file system at a low level from userland. Facilities provided are used to implement utilities such as .Xr newfs 8 and .Xr dumpfs 8 . The .Nm library is designed to be simple, and to provide functions that are traditionally useful to have. .Pp A disk is represented as the type .Vt "struct uufsd" as defined in .In libufs.h . The structure is filled out, operations are performed, and the disk is closed. .Sh ERRORS Functions provided by .Nm return \-1 in every functional error situation. They also set the .Va d_error field of .Vt "struct uufsd" to a string describing the error. .Sh SEE ALSO .Xr berase 3 , .Xr bread 3 , .Xr bwrite 3 , .Xr cgget 3 , .Xr cgput 3 , .Xr cgread 3 , .Xr cgread1 3 , .Xr cgwrite 3 , .Xr cgwrite1 3 , .Xr getinode 3 , .Xr putinode 3 , .Xr sbget 3 , .Xr sbput 3 , .Xr sbread 3 , .Xr sbwrite 3 , .Xr ufs_disk_close 3 , .Xr ufs_disk_fillout 3 , .Xr ufs_disk_fillout_blank 3 , .Xr ufs_disk_write 3 , -.Xr ffs 7 +.Xr ffs 4 .Sh HISTORY The .Xr libufs 3 library first appeared in .Fx 5.0 . .Sh AUTHORS .An Juli Mallett Aq Mt jmallett@FreeBSD.org .An Marshall Kirk McKusick Aq Mt mckusick@FreeBSD.org .Pp .An -nosplit Additional design, feedback, and ideas were provided by .An Poul-Henning Kamp Aq Mt phk@FreeBSD.org . diff --git a/sbin/devfs/devfs.8 b/sbin/devfs/devfs.8 index 598f2303a605..bbe4825b8bb2 100644 --- a/sbin/devfs/devfs.8 +++ b/sbin/devfs/devfs.8 @@ -1,388 +1,388 @@ .\" .\" Copyright (c) 2002 Dima Dorfman. .\" 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 October 18, 2023 .Dt DEVFS 8 .Os .Sh NAME .Nm devfs .Nd "DEVFS control" .Sh SYNOPSIS .Nm .Op Fl m Ar mount-point .Ar keyword .Ar argument ... .Sh DESCRIPTION The .Nm utility provides an interface to manipulate properties of -.Xr devfs 5 +.Xr devfs 4 mounts. .Pp The rules, by default as configured by .Pa /etc/rc.conf , are loaded at boot via the devfs .Xr service 8 . The rules can be reloaded by running the command: .Bd -literal -offset indent service devfs restart .Ed .Pp The .Ar keyword argument determines the context for the rest of the arguments. For example, most of the commands related to the rule subsystem must be preceded by the .Cm rule keyword. The following flags are common to all keywords: .Bl -tag -width 15n .It Fl m Ar mount-point Operate on .Ar mount-point , which is expected to be a -.Xr devfs 5 +.Xr devfs 4 mount. If this option is not specified, .Nm operates on .Pa /dev . .El .Ss Rule Subsystem The -.Xr devfs 5 +.Xr devfs 4 rule subsystem provides a way for the administrator of a system to control the attributes of DEVFS nodes. .\" XXX devfs node? entry? what? Each DEVFS mount-point has a .Dq ruleset , or a list of rules, associated with it. When a device driver creates a new node, all the rules in the ruleset associated with each mount-point are applied (see below) before the node becomes visible to the userland. This permits the administrator to change the properties, including the visibility, of certain nodes. For example, one might want to hide all disk nodes in a .Xr jail 2 Ns 's .Pa /dev . .Ss Rule Manipulation Rule manipulation commands follow the .Cm rule keyword. The following flags are common to all of the rule manipulation commands: .Bl -tag -width 15n .It Fl s Ar ruleset Operate on the ruleset with the number .Ar ruleset . If this is not specified, the commands operate on the ruleset currently associated with the specified mount-point. .El .Pp The following commands are recognized: .Bl -tag -width 15n .It Cm rule add Oo Ar rulenum Oc Ar rulespec Add the rule described by .Ar rulespec (defined below) to the ruleset. The rule has the number .Ar rulenum if it is explicitly specified; otherwise, the rule number is automatically determined by the kernel. .It Cm rule apply Ar rulenum | rulespec Apply rule number .Ar rulenum or the rule described by .Ar rulespec to the mount-point. Rules that are .Dq applied have their conditions checked against all nodes in the mount-point and the actions taken if they match. .It Cm rule applyset Apply all the rules in the ruleset to the mount-point (see above for the definition of .Dq apply ) . .It Cm rule del Ar rulenum Delete rule number .Ar rulenum from the ruleset. .It Cm rule delset Delete all rules from the ruleset. .It Cm rule show Op Ar rulenum Display the rule number .Ar rulenum , or all the rules in the ruleset. The output lines (one line per rule) are expected to be valid .Ar rulespec Ns s . .It Cm rule showsets Report the numbers of existing rulesets. .It Cm ruleset Ar ruleset Set ruleset number .Ar ruleset as the current ruleset for the mount-point. .El .Ss Rule Specification Rules have two parts: the conditions and the actions. The conditions determine which DEVFS nodes the rule matches and the actions determine what should be done when a rule matches a node. For example, a rule can be written that sets the GID to .Dq Li operator for all devices of type tape. If the first token of a rule specification is a single dash .Pq Sq Fl , rules are read from the standard input and the rest of the specification is ignored. .Pp The following conditions are recognized. Conditions are ANDed together when matching a device; if OR is desired, multiple rules can be written. .Bl -tag -width 15n .It Cm path Ar pattern Matches any node with a path that matches .Ar pattern , which is interpreted as a .Xr glob 3 Ns -style pattern. .It Cm type Ar devtype Matches any node that is of type .Ar devtype . Valid types are .Cm disk , mem , tape and .Cm tty . .El .Pp The following actions are recognized. Although there is no explicit delimiter between conditions and actions, they may not be intermixed. .Bl -tag -width 15n .It Cm group Ar gid Set the GID of the node to .Ar gid , which may be a group name (looked up in .Pa /etc/group ) or number. .It Cm hide Hide the node. Nodes may later be revived manually with .Xr mknod 8 or with the .Cm unhide action. Hiding a directory node effectively hides all of its child nodes. .It Cm include Ar ruleset Apply all the rules in ruleset number .Ar ruleset to the node. This does not necessarily result in any changes to the node (e.g., if none of the rules in the included ruleset match). Include commands in the referenced .Ar ruleset are not resolved. .It Cm mode Ar filemode Set the file mode to .Ar filemode , which is interpreted as in .Xr chmod 1 . .It Cm user Ar uid Set the UID to .Ar uid , which may be a user name (looked up in .Pa /etc/passwd ) or number. .It Cm unhide Unhide the node. If the node resides in a subdirectory, all parent directory nodes must be visible to be able to access the node. .El .Sh IMPLEMENTATION NOTES Rulesets are created by the kernel at the first reference and destroyed when the last reference disappears. E.g., a ruleset is created when a rule is added to it or when it is set as the current ruleset for a mount-point, and a ruleset is destroyed when the last rule in it is deleted and no other references to it exist (i.e., it is not included by any rules and it is not the current ruleset for any mount-point). .Pp Ruleset number 0 is the default ruleset for all new mount-points. It is always empty, cannot be modified or deleted, and does not show up in the output of .Cm showsets . .Pp Rules and rulesets are unique to the entire system, not a particular mount-point. I.e., a .Cm showsets will return the same information regardless of the mount-point specified with .Fl m . The mount-point is only relevant when changing what its current ruleset is or when using one of the apply commands. .Sh FILES .Bl -tag -width "Pa /etc/defaults/devfs.rules" -compact .It Pa /etc/defaults/devfs.rules Default .Nm configuration file. .It Pa /etc/devfs.rules Local .Nm configuration file. Rulesets in here override those in .Pa /etc/defaults/devfs.rules with the same ruleset number, otherwise the two files are effectively merged. .It Pa /etc/devfs.conf Boot-time .Nm configuration file. .El .Sh EXAMPLES When the system boots, the only ruleset that exists is ruleset number 0; since the latter may not be modified, we have to create another ruleset before adding rules. Note that since most of the following examples do not specify .Fl m , the operations are performed on .Pa /dev (this only matters for things that might change the properties of nodes). .Pp Specify that ruleset 10 should be the current ruleset for .Pa /dev (if it does not already exist, it is created): .Pp .Dl "devfs ruleset 10" .Pp Add a rule that causes all nodes that have a path that matches .Dq Li speaker (this is only .Pa /dev/speaker ) to have the file mode 666 (read and write for all). Note that if any such nodes already exist, their mode will not be changed unless this rule (or ruleset) is explicitly applied (see below). The mode .Em will be changed if the node is created .Em after the rule is added (e.g., the .Pa atspeaker module is loaded after the above rule is added): .Pp .Dl "devfs rule add path speaker mode 666" .Pp Apply all the rules in the current ruleset to all the existing nodes. E.g., if the below rule was added after .Pa /dev/speaker was created, this command will cause its file mode to be changed to 666 as prescribed by the rule: .Pp .Dl "devfs rule applyset" .Pp For all devices with a path that matches .Dq Li snp* , set the file mode to 660 and the GID to .Dq Li snoopers . This permits users in the .Dq Li snoopers group to use the .Xr snp 4 devices (quoting the argument to .Cm path is often necessary to disable the shell's globbing features): .Pp .Dl devfs rule add path "snp*" mode 660 group snoopers .Pp Add a rule to ruleset number 20. Since this ruleset is not the current ruleset for any mount-points, this rule is never applied automatically (unless ruleset 20 becomes a current ruleset for some mount-point at a later time): .Pp .Dl "devfs rule -s 20 add type disk group wheel" .Pp Explicitly apply all rules in ruleset number 20 to the DEVFS mount on .Pa /my/jail/dev . It does not matter that ruleset 20 is not the current ruleset for that mount-point; the rules are still applied: .Pp .Dl "devfs -m /my/jail/dev rule -s 20 applyset" .Pp Since the following rule has no conditions, the action .Pq Cm hide will be applied to all nodes: .Pp .Dl "devfs rule apply hide" .Pp Since hiding all nodes is not very useful, we can undo it. The following applies .Cm unhide to all the nodes, causing them to reappear: .Pp .Dl "devfs rule apply unhide" .Pp Add all the rules from the file .Pa my_rules to ruleset 10: .Pp .Dl "devfs rule -s 10 add - < my_rules" .Pp The below copies all the rules from ruleset 20 into ruleset 10. The rule numbers are preserved, but ruleset 10 may already have rules with non-conflicting numbers (these will be preserved). Since .Cm show outputs valid rules, this feature can be used to copy rulesets: .Pp .Dl "devfs rule -s 20 show | devfs rule -s 10 add -" .Sh SEE ALSO .Xr chmod 1 , .Xr jail 2 , .Xr glob 3 , -.Xr devfs 5 , +.Xr devfs 4 , .Xr devfs.conf 5 , .Xr devfs.rules 5 , .Xr chown 8 , .Xr jail 8 , .Xr mknod 8 , .Xr service 8 .Sh HISTORY The .Nm utility first appeared in .Fx 5.0 . .Sh AUTHORS .An Dima Dorfman diff --git a/sbin/fsck_ffs/fsck_ffs.8 b/sbin/fsck_ffs/fsck_ffs.8 index 1eb9ebeb3b9b..8df5e684b963 100644 --- a/sbin/fsck_ffs/fsck_ffs.8 +++ b/sbin/fsck_ffs/fsck_ffs.8 @@ -1,441 +1,441 @@ .\" .\" 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 November 17, 2023 .Dt FSCK_FFS 8 .Os .Sh NAME .Nm fsck_ffs , .Nm fsck_ufs .Nd file system consistency check and interactive repair .Sh SYNOPSIS .Nm .Op Fl BCdEFfnpRrSyZz .Op Fl b Ar block .Op Fl c Ar level .Op Fl m Ar mode .Ar filesystem .Ar ... .Sh DESCRIPTION The specified disk partitions and/or file systems are checked. In "preen" or "check clean" mode the clean flag of each file system's superblock is examined and only those file systems that are not marked clean are checked. File systems are marked clean when they are unmounted, when they have been mounted read-only, or when .Nm runs on them successfully. If the .Fl f option is specified, the file systems will be checked regardless of the state of their clean flag. .Pp The kernel takes care that only a restricted class of innocuous file system inconsistencies can happen unless hardware or software failures intervene. These are limited to the following: .Pp .Bl -item -compact -offset indent .It Unreferenced inodes .It Link counts in inodes too large .It Missing blocks in the free map .It Blocks in the free map also in files .It Counts in the super-block wrong .El .Pp These are the only inconsistencies that .Nm with the .Fl p option will correct; if it encounters other inconsistencies, it exits with an abnormal return status and an automatic reboot will then fail. For each corrected inconsistency one or more lines will be printed identifying the file system on which the correction will take place, and the nature of the correction. After successfully correcting a file system, .Nm will print the number of files on that file system, the number of used and free blocks, and the percentage of fragmentation. .Pp If sent a .Dv QUIT signal, .Nm will finish the file system checks, then exit with an abnormal return status that causes an automatic reboot to fail. This is useful when you want to finish the file system checks during an automatic reboot, but do not want the machine to come up multiuser after the checks complete. .Pp If .Nm receives a .Dv SIGINFO (see the .Dq status argument for .Xr stty 1 ) signal, a line will be written to the standard output indicating the name of the device currently being checked, the current phase number and phase-specific progress information. .Pp Without the .Fl p option, .Nm audits and interactively repairs inconsistent conditions for file systems. If the file system is inconsistent the operator is prompted for concurrence before each correction is attempted. It should be noted that some of the corrective actions which are not correctable under the .Fl p option will result in some loss of data. The amount and severity of data lost may be determined from the diagnostic output. The default action for each consistency correction is to wait for the operator to respond .Li yes or .Li no . If the operator does not have write permission on the file system .Nm will default to a .Fl n action. .Pp The following flags are interpreted by .Nm : .Bl -tag -width indent .It Fl B A check is done on the specified and possibly active file system. The set of corrections that can be done is limited to those done when running in preen mode (see the .Fl p flag). If unexpected errors are found, the file system is marked as needing a foreground check and .Nm exits without attempting any further cleaning. .It Fl b Use the block specified immediately after the flag as the super block for the file system. An alternate super block is usually located at block 32 for UFS1, and block 192 for UFS2. .Pp See the .Fl N flag of .Xr newfs 8 . .It Fl C Check if file system was dismounted cleanly. If so, skip file system checks (like "preen"). However, if the file system was not cleanly dismounted, do full checks, as if .Nm was invoked without .Fl C . .It Fl c Convert the file system to the specified level. Note that the level of a file system can only be raised. There are currently four levels defined: .Bl -tag -width indent .It 0 The file system is in the old (static table) format. .It 1 The file system is in the new (dynamic table) format. .It 2 The file system supports 32-bit uid's and gid's, short symbolic links are stored in the inode, and directories have an added field showing the file type. .It 3 If maxcontig is greater than one, build the free segment maps to aid in finding contiguous sets of blocks. If maxcontig is equal to one, delete any existing segment maps. .El .Pp In interactive mode, .Nm will list the conversion to be made and ask whether the conversion should be done. If a negative answer is given, no further operations are done on the file system. In preen mode, the conversion is listed and done if possible without user interaction. Conversion in preen mode is best used when all the file systems are being converted at once. The format of a file system can be determined from the first line of output from .Xr dumpfs 8 . .Pp This option implies the .Fl f flag. .It Fl d Enable debugging messages. .It Fl E Clear unallocated blocks, notifying the underlying device that they are not used and that their contents may be discarded. This is useful for filesystems which have been mounted on systems without TRIM support, or with TRIM support disabled, as well as filesystems which have been copied from one device to another. .Pp See the .Fl E and .Fl t flags of .Xr newfs 8 , and the .Fl t flag of .Xr tunefs 8 . .It Fl F Determine whether the file system needs to be cleaned immediately in foreground, or if its cleaning can be deferred to background. To be eligible for background cleaning it must have been running with soft updates, not have been marked as needing a foreground check, and be mounted and writable when the background check is to be done. If these conditions are met, then .Nm exits with a zero exit status. Otherwise it exits with a non-zero exit status. If the file system is clean, it will exit with a non-zero exit status so that the clean status of the file system can be verified and reported during the foreground checks. Note that when invoked with the .Fl F flag, no cleanups are done. The only thing that .Nm does is to determine whether a foreground or background check is needed and exit with an appropriate status code. .It Fl f Force .Nm to check .Sq clean file systems when preening. .It Fl m Use the mode specified in octal immediately after the flag as the permission bits to use when creating the .Pa lost+found directory rather than the default 1777. In particular, systems that do not wish to have lost files accessible by all users on the system should use a more restrictive set of permissions such as 700. .It Fl n Assume a no response to all questions asked by .Nm except for .Ql CONTINUE? , which is assumed to be affirmative; do not open the file system for writing. .It Fl p Preen file systems (see above). .It Fl R Instruct fsck_ffs to restart itself if it encounters certain errors that warrant another run. It will limit itself to a maximum of 10 restarts in a given run in order to avoid an endless loop with extremely corrupted filesystems. .It Fl r Free up excess unused inodes. Decreasing the number of preallocated inodes reduces the running time of future runs of .Nm and frees up space that can allocated to files. The .Fl r option is ignored when running in preen mode. .It Fl S Surrender on error. With this flag enabled, a hard error returned on disk i/o will cause .Nm to abort instead of continuing on and possibly tripping over more i/o errors. .It Fl y Assume a yes response to all questions asked by .Nm ; this should be used with great caution as this is a free license to continue after essentially unlimited trouble has been encountered. .It Fl Z Similar to .Fl E , but overwrites unused blocks with zeroes. If both .Fl E and .Fl Z are specified, blocks are first zeroed and then erased. .It Fl z Clear unused directory space. The cleared space includes deleted file names and name padding. .El .Pp Inconsistencies checked are as follows: .Pp .Bl -enum -compact .It Blocks claimed by more than one inode or the free map. .It Blocks claimed by an inode outside the range of the file system. .It Incorrect link counts. .It Size checks: .Bl -item -offset indent -compact .It Directory size not a multiple of DIRBLKSIZ. .It Partially truncated file. .El .It Bad inode format. .It Blocks not accounted for anywhere. .It Directory checks: .Bl -item -offset indent -compact .It File pointing to unallocated inode. .It Inode number out of range. .It Directories with unallocated blocks (holes). .It Dot or dot-dot not the first two entries of a directory or having the wrong inode number. .El .It Super Block checks: .Bl -item -offset indent -compact .It More blocks for inodes than there are in the file system. .It Bad free block map format. .It Total free block and/or free inode count incorrect. .El .El .Pp Orphaned files and directories (allocated but unreferenced) are, with the operator's concurrence, reconnected by placing them in the .Pa lost+found directory. The name assigned is the inode number. If the .Pa lost+found directory does not exist, it is created. If there is insufficient space its size is increased. .Pp The full foreground .Nm checks for many more problems that may occur after an unrecoverable disk write error. Thus, it is recommended that you perform foreground .Nm on your systems periodically and whenever you encounter unrecoverable disk write errors or file-system\-related panics. .Sh FILES .Bl -tag -width /etc/fstab -compact .It Pa /etc/fstab contains default list of file systems to check. .El .Sh EXIT STATUS .Ex -std .Pp Specific non-zero exit status values used are: .Bl -tag -width indent .It 1 Usage error (missing or invalid command arguments). .It 2 The .Fl p option was used and a .Dv SIGQUIT was received, indicating that the system should be returned to single user mode after the file system check. .It 3 The file system superblock cannot be read. This could indicate that the file system device does not exist or is not yet ready. .It 4 A mounted file system was modified; the system should be rebooted. .It 5 The .Fl B option was used and soft updates are not enabled on the file system. .It 6 The .Fl B option was used and the kernel lacks needed support. .It 7 The .Fl F option was used and the file system is clean. .It 8 General error exit. .It 16 The file system could not be completely repaired. The file system may be able to be repaired by running .Nm on the file system again. .El .Sh DIAGNOSTICS The diagnostics produced by .Nm are fully enumerated and explained in Appendix A of .Rs .%T "Fsck \- The UNIX File System Check Program" .Re .Sh SEE ALSO +.Xr ffs 4 , .Xr fs 5 , .Xr fstab 5 , -.Xr ffs 7 , .Xr fsck 8 , .Xr fsdb 8 , .Xr newfs 8 , .Xr reboot 8 .Sh HISTORY A .Nm fsck utility appeared in .Bx 4.0 . It became .Nm in .Fx 5.0 with the introduction of the filesystem independent wrapper as .Nm fsck . diff --git a/sbin/mdconfig/mdconfig.8 b/sbin/mdconfig/mdconfig.8 index 938d6ddf12b0..73d4b30aac35 100644 --- a/sbin/mdconfig/mdconfig.8 +++ b/sbin/mdconfig/mdconfig.8 @@ -1,386 +1,386 @@ .\" Copyright (c) 1993 University of Utah. .\" Copyright (c) 1980, 1989, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" Copyright (c) 2000 .\" Poul-Henning Kamp All rights reserved. .\" .\" This code is derived from software contributed to Berkeley by .\" the Systems Programming Group of the University of Utah Computer .\" Science Department. .\" .\" 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: src/usr.sbin/vnconfig/vnconfig.8,v 1.19 2000/12/27 15:30:29 .\" .Dd August 27, 2021 .Dt MDCONFIG 8 .Os .Sh NAME .Nm mdconfig .Nd create and control memory disks .Sh SYNOPSIS .Nm .Fl a .Fl t Ar type .Op Fl n .Oo Fl o Oo Cm no Oc Ns Ar option Oc ... .Op Fl f Ar file .Op Fl s Ar size .Op Fl S Ar sectorsize .Op Fl u Ar unit .Op Fl x Ar sectors/track .Op Fl y Ar heads/cylinder .Op Fl L Ar label .Nm .Fl d .Fl u Ar unit .Op Fl o Oo Cm no Oc Ns Ar force .Nm .Fl r .Fl u Ar unit .Fl s Ar size .Op Fl o Oo Cm no Oc Ns Ar force .Nm .Fl l .Op Fl n .Op Fl v .Op Fl f Ar file .Op Fl u Ar unit .Nm .Ar file .Sh DESCRIPTION The .Nm utility creates and controls .Xr md 4 devices. .Pp Options indicate an action to be performed: .Bl -tag -width indent .It Fl a Attach a memory disk. This will configure and attach a memory disk with the parameters specified and attach it to the system. If the .Fl u Ar unit option is not provided, the newly created device name will be printed on stdout. .It Fl d Detach a memory disk from the system and release all resources. .It Fl r Resize a memory disk. .It Fl t Ar type Select the type of the memory disk. .Bl -tag -width "malloc" .It Cm malloc Storage for this type of memory disk is allocated with .Xr malloc 9 . This limits the size to the malloc bucket limit in the kernel. If the .Fl o Cm reserve option is not set, creating and filling a large malloc-backed memory disk is a very easy way to panic the system. .It Cm vnode A file specified with .Fl f Ar file becomes the backing store for this memory disk. .It Cm swap Storage for this type of memory disk is allocated from buffer memory. Pages get pushed out to swap when the system is under memory pressure, otherwise they stay in the operating memory. Using .Cm swap backing is generally preferred instead of using .Cm malloc backing. .It Cm null Bitsink; all writes do nothing, all reads return zeroes. .El .It Fl f Ar file Filename to use for the vnode type memory disk. The .Fl a and .Fl t Cm vnode options are implied if not specified. .It Fl l List configured devices. If given with .Fl u , display details about that particular device. If given with .Fl f Ar file , display .Xr md 4 device names of which .Ar file is used as the backing store. If both of .Fl u and .Fl f options are specified, display devices which match the two conditions. If the .Fl v option is specified, show all details. .It Fl n When printing .Xr md 4 device names, print only the unit number without the .Xr md 4 prefix. .It Fl s Ar size Size of the memory disk. .Ar Size is the number of 512 byte sectors unless suffixed with a .Cm b , k , m , g , t , or .Cm p which denotes byte, kilobyte, megabyte, gigabyte, terabyte and petabyte respectively. When used without the .Fl r option, the .Fl a and .Fl t Cm swap options are implied if not specified. .It Fl S Ar sectorsize Sectorsize to use for the memory disk, in bytes. .It Fl x Ar sectors/track See the description of the .Fl y option below. .It Fl y Ar heads/cylinder For .Cm malloc or .Cm vnode backed devices, the .Fl x and .Fl y options can be used to specify a synthetic geometry. This is useful for constructing bootable images for later download to other devices. .It Fl L Ar label Associate a label (arbitrary string) with the new memory disk. The label can then be inspected with .Bd -literal -offset indent .Nm Fl l v .Ed .It Fl o Oo Cm no Oc Ns Ar option Set or reset options. .Bl -tag -width indent .It Oo Cm no Oc Ns Cm async For .Cm vnode backed devices: avoid .Dv IO_SYNC for increased performance but at the risk of deadlocking the entire kernel. .It Oo Cm no Oc Ns Cm cache For .Cm vnode backed devices: enable/disable caching of data in system caches. The default is to not cache. .Pp Accesses via the device are converted to accesses via the vnode. The caching policy for the vnode is used initially. This is normally to cache. This caching policy is retained if the .Cm cache option is used. Otherwise, caching is limited by releasing data from caches soon after each access. The release has the same semantics as the .Dv POSIX_FADV_DONTNEED feature of .Xr posix_fadvise 2 . The result is that with normal (non-zfs) caching, buffers are released from the buffer cache soon after they are constructed, but their data is kept in the page cache at lower priority. .Pp The .Cm cache option tends to waste memory by giving unwanted double caching, but it saves time if there is memory to spare. .It Oo Cm no Oc Ns Cm reserve Allocate and reserve all needed storage from the start, rather than as needed. .It Oo Cm no Oc Ns Cm cluster Enable clustering on this disk. .It Oo Cm no Oc Ns Cm compress Enable/disable compression features to reduce memory usage. .It Oo Cm no Oc Ns Cm force Disable/enable extra sanity checks to prevent the user from doing something that might adversely affect the system. This can be used with the .Fl d flag to forcibly destroy an .Xr md 4 disk that is still in use. .It Oo Cm no Oc Ns Cm mustdealloc For .Cm vnode backed devices: detect whether hole-punching is supported by the underlying file system. If the file system supports hole-punching, then to handle a .Dv BIO_DELETE request, some or all of the request's operation range may be turned into a hole in the file used for backing store. Any parts which are not turned into holes are zero-filled in the file. If the file system does not support hole-punching, .Dv BIO_DELETE requests to the device are not handled and will fail with .Er EOPNOTSUPP . .Pp When .Cm mustdealloc is not specified or .Oo Cm no Oc Ns Cm mustdealloc is specified, for a .Dv BIO_DELETE request, if the file system supports hole-punching, some or all of the request's operation range may be turned into a hole in the file used for backing store. Any parts which are not turned into holes are zero-filled in the file. If the file system of the vnode type memory disk does not support hole-punching, the request's operation range is zero-filled in the file. .It Oo Cm no Oc Ns Cm readonly Enable/disable readonly mode. .It Oo Cm no Oc Ns Cm verify For .Cm vnode backed devices: enable/disable requesting verification of the file used for backing store. The type of verification depends on which security features are available. One example of verification is testing file integrity with checksums or cryptographic signatures. .El .It Fl u Ar unit Request a specific unit number or device name for the .Xr md 4 device instead of automatic allocation. If a device name is specified, it must start with .Dq md followed by the unit number. .El .Pp The last form, .Nm .Ar file , is provided for convenience as an abbreviation of .Nm .Fl a .Fl t Cm vnode .Fl f Ar file . .Sh EXAMPLES Create a disk with .Pa /tmp/boot.flp as backing storage. The name of the allocated unit will be printed on stdout, such as .Dq Li md0 : .Bd -literal -offset indent mdconfig /tmp/boot.flp .Ed .Pp Create a 1 gigabyte swap backed memory disk named .Dq Li md3 : .Bd -literal -offset indent mdconfig -s 1g -u md3 .Ed .Pp Detach and free all resources used by .Pa /dev/md3 : .Bd -literal -offset indent mdconfig -du md3 .Ed .Pp Show detailed information on current memory disks: .Bd -literal -offset indent mdconfig -lv .Ed .Pp Resize the .Dq Li md3 memory disk to 2 gigabytes: .Bd -literal -offset indent mdconfig -rs 2g -u md3 .Ed .Pp Create a 1 gigabyte swap backed disk, initialize an -.Xr ffs 7 +.Xr ffs 4 file system on it, and mount it on .Pa /tmp : .Bd -literal -offset indent mdconfig -s 1g -u md10 newfs -U /dev/md10 mount /dev/md10 /tmp chmod 1777 /tmp .Ed .Pp Create a memory disk out of an ISO 9660 CD image file, using the first available .Xr md 4 device, and then mount it: .Bd -literal -offset indent mount -t cd9660 /dev/`mdconfig -f cdimage.iso` /mnt .Ed .Pp Create a file-backed device from a hard disk image that begins with 512K of raw header information. .Xr gnop 8 is used to skip over the header information, positioning .Pa md1.nop to the start of the filesystem in the image. .Bd -literal -offset indent mdconfig -u md1 -f diskimage.img gnop create -o 512K md1 mount /dev/md1.nop /mnt .Ed .Sh SEE ALSO .Xr fpathconf 2 , .Xr fspacectl 2 , .Xr open 2 , +.Xr ffs 4 , .Xr md 4 , -.Xr ffs 7 , .Xr gpart 8 , .Xr mdmfs 8 , .Xr malloc 9 , .Xr vn_deallocate 9 .Sh HISTORY The .Nm utility first appeared in .Fx 5.0 as a cleaner replacement for the vn kernel module and the vnconfig utility combo. .Sh AUTHORS The .Nm utility was written by .An Poul-Henning Kamp Aq Mt phk@FreeBSD.org . diff --git a/sbin/mdmfs/mdmfs.8 b/sbin/mdmfs/mdmfs.8 index 50819bfee0c6..ff5b78068299 100644 --- a/sbin/mdmfs/mdmfs.8 +++ b/sbin/mdmfs/mdmfs.8 @@ -1,449 +1,449 @@ .\" .\" Copyright (c) 2001 Dima Dorfman. .\" 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 October 31, 2019 .Dt MDMFS 8 .Os .Sh NAME .Nm mdmfs , .Nm mount_mfs .Nd configure and mount an in-memory file system using the .Xr md 4 driver or the -.Xr tmpfs 5 +.Xr tmpfs 4 filesystem .Sh SYNOPSIS .Nm .Op Fl DLlMNnPStTUX .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 path-mdconfig .Op Fl e Ar maxbpg .Op Fl F Ar file .Op Fl f Ar frag-size .Op Fl i Ar bytes .Op Fl k Ar skel .Op Fl m Ar percent-free .Op Fl O Ar optimization .Op Fl o Ar mount-options .Op Fl p Ar permissions .Op Fl s Ar size .Op Fl T Ar fstype .Op Fl v Ar version .Op Fl w Ar user : Ns Ar group .Ar md-device .Ar mount-point .Sh DESCRIPTION The .Nm utility is designed to be a work-alike and look-alike of the deprecated .Nm mount_mfs . The end result is essentially the same, but is accomplished in a completely different way. Based on .Ar md-device , the .Nm utility either creates a -.Xr tmpfs 5 +.Xr tmpfs 4 filesystem, or it configures an .Xr md 4 disk using .Xr mdconfig 8 , puts a UFS file system on it (unless .Fl P was specified) using .Xr newfs 8 , and mounts it using .Xr mount 8 . It can handle .Xr geom_uzip 4 compressed disk images, as long as the kernel supports this GEOM class. All the command line options are passed to the appropriate program at the appropriate stage in order to achieve the desired effect. .Pp When .Ar md-device is `auto', .Nm uses -.Xr tmpfs 5 +.Xr tmpfs 4 if it is present in the kernel or can be loaded as a module, otherwise it falls back to using .Xr md 4 auto-unit as if `md' had been specified. .Pp When .Ar md-device is `tmpfs', .Nm mounts a -.Xr tmpfs 5 +.Xr tmpfs 4 filesystem, translating the .Fl s size option, if present, into a `-o size=' mount option. Any .Fl o options on the command line are passed through to the -.Xr tmpfs 5 +.Xr tmpfs 4 mount. Options specific to .Xr mdconfig 8 or .Xr newfs 8 are ignored. .Pp When .Ar md-device does not result in -.Xr tmpfs 5 +.Xr tmpfs 4 being used, then an .Xr md 4 device is configured instead. By default, .Nm creates a swap-based .Pq Dv MD_SWAP disk with soft-updates enabled and mounts it on .Ar mount-point . It uses the .Xr md 4 device specified by .Ar md-device . If .Ar md-device is .Ql md (no unit number), it will use .Xr md 4 Ns 's auto-unit feature to automatically select an unused device. Unless otherwise specified with one of the options below, it uses the default arguments to all the helper programs. .Pp The following options are available. Where possible, the option letter matches the one used by .Nm mount_mfs for the same thing. .Bl -tag -width indent .It Fl a Ar maxcontig Specify the maximum number of contiguous blocks that will be laid out before forcing a rotational delay (see the .Fl d option). .It Fl b Ar block-size The block size of the file system, in bytes. .It Fl c Ar blocks-per-cylinder-group The number of blocks per cylinder group in the file system. .It Fl D If not using auto-unit, do not run .Xr mdconfig 8 to try to detach the unit before attaching it. .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. It is presently limited to its default value which is 16 times the file system blocksize. .It Fl E Ar path-mdconfig Use .Ar path-mdconfig as a location of the .Xr mdconfig 8 utility. .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. .It Fl F Ar file Create a vnode-backed .Pq Dv MD_VNODE memory disk backed by .Ar file . .It Fl f Ar frag-size The fragment size of the file system in bytes. .It Fl i Ar bytes Number of bytes per inode. .It Fl k Ar skel Copy the content of directory .Ar skel into .Ar mount-point . .It Fl l Enable multilabel MAC on the new file system. .It Fl L Show the output of the helper programs. By default, it is sent to .Pa /dev/null . .It Fl M Create a .Xr malloc 9 backed disk .Pq Dv MD_MALLOC instead of a swap-backed disk. .It Fl m Ar percent-free The percentage of space reserved for the superuser. .It Fl N Do not actually run the helper programs. This is most useful in conjunction with .Fl X . .It Fl n Do not create a .Pa .snap directory on the new file system. .It Fl O Ar optimization Select the optimization preference; valid choices are .Cm space and .Cm time , which will optimize for minimum space fragmentation and minimum time spent allocating blocks, respectively. .It Fl o Ar mount-options Specify the mount options with which to mount the file system. See .Xr mount 8 for more information. .It Fl P Preserve the existing file system; do not run .Xr newfs 8 . This only makes sense if .Fl F is specified to create a vnode-backed disk. .It Fl p Ar permissions Set the file (directory) permissions of the mount point .Ar mount-point to .Ar permissions . The .Ar permissions argument can be in any of the mode formats recognized by .Xr chmod 1 . If symbolic permissions are specified, the operation characters .Dq + and .Dq - are interpreted relative to the initial permissions of .Dq a=rwx . .It Fl S Do not enable soft-updates on the file system. .It Fl s Ar size Specify the size of the disk to create. This only makes sense if .Fl F is .Em not specified. That is, this will work when the backing storage is some form of memory, as opposed to a fixed-size file. The size may include the usual SI suffixes (k, m, g, t, p). A number without a suffix is interpreted as a count of 512-byte sectors. .It Fl t Turn on the TRIM enable flag for .Xr newfs 8 . When used with a file system that issue BIO_DELETE bio requests, .Xr md 4 returns deleted blocks to the system memory pool. .It Fl T Ar fstype Specify a file system type for a vnode-backed memory disk. Any file system supported by .Xr mount 8 command can be specified. This option only makes sense when .Fl F and .Fl P are used. .It Fl U Enable soft-updates on the file system. This is the default, and is accepted only for compatibility. It is only really useful to negate the .Fl S flag, should such a need occur. .It Fl v Ar version Specify the UFS version number for use on the file system; it may be either .Dv 1 or .Dv 2 . The default is derived from the default of the .Xr newfs 8 command. .It Fl w Ar user : Ns Ar group Set the owner and group to .Ar user and .Ar group , respectively. The arguments have the same semantics as with .Xr chown 8 , but specifying just a .Ar user or just a .Ar group is not supported. .It Fl X Print what command will be run before running it, and other assorted debugging information. .El .Pp The .Fl F and .Fl s options are passed to .Xr mdconfig 8 as .Fl f and .Fl s , respectively. The .Fl a , b , c , d , e , f , i , m and .Fl n options are passed to .Xr newfs 8 with the same letter. The .Fl O option is passed to .Xr newfs 8 as .Fl o . The .Fl o option is passed to .Xr mount 8 with the same letter. The .Fl T option is passed to .Xr mount 8 as .Fl t . For information on semantics, refer to the documentation of the programs that the options are passed to. .Sh EXAMPLES Create and mount a 32 megabyte swap-backed file system on .Pa /tmp : .Pp .Dl "mdmfs -s 32m md /tmp" .Pp The same file system created as an entry in .Pa /etc/fstab : .Pp .Dl "md /tmp mfs rw,-s32m 2 0" .Pp Create and mount a 16 megabyte malloc-backed file system on .Pa /tmp using the .Pa /dev/md1 device; furthermore, do not use soft-updates on it and mount it .Cm async : .Pp .Dl "mdmfs -M -S -o async -s 16m md1 /tmp" .Pp Create and mount a .Xr geom_uzip 4 based compressed disk image: .Pp .Dl "mdmfs -P -F foo.uzip -oro md.uzip /tmp/" .Pp Mount the same image, specifying the .Pa /dev/md1 device: .Pp .Dl "mdmfs -P -F foo.uzip -oro md1.uzip /tmp/" .Pp Configure a vnode-backed file system and mount its first partition, using automatic device numbering: .Pp .Dl "mdmfs -P -F foo.img mds1a /tmp/" .Pp Mount a vnode-backed cd9660 file system using automatic device numbering: .Pp .Dl "mdmfs -T cd9660 -P -F foo.iso md /tmp" .Sh COMPATIBILITY The .Nm utility, while designed to be compatible with .Nm mount_mfs , can be useful by itself. Since .Nm mount_mfs had some silly defaults, a .Dq compatibility mode is provided for the case where bug-to-bug compatibility is desired. .Pp Compatibility is enabled by starting .Nm with the name .Li mount_mfs or .Li mfs (as returned by .Xr getprogname 3 ) . In this mode, the following behavior, as done by .Nm mount_mfs , is duplicated: .Bl -bullet -offset indent .It The file mode of .Ar mount-point is set by default to .Li 01777 as if .Fl p Ar 1777 was given on the command line. .El .Sh SEE ALSO .Xr md 4 , +.Xr tmpfs 4 , .Xr fstab 5 , -.Xr tmpfs 5 , .Xr mdconfig 8 , .Xr mount 8 , .Xr newfs 8 .Sh HISTORY The .Nm utility appeared in .Fx 5.0 . .Sh AUTHORS .An Dima Dorfman diff --git a/sbin/mknod/mknod.8 b/sbin/mknod/mknod.8 index 99337bd34767..fc562e76f0db 100644 --- a/sbin/mknod/mknod.8 +++ b/sbin/mknod/mknod.8 @@ -1,149 +1,149 @@ .\" Copyright (c) 1980, 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 October 3, 2016 .Dt MKNOD 8 .Os .Sh NAME .Nm mknod .Nd build special file .Sh SYNOPSIS .Nm .Ar name .Nm .Ar name .Op Cm b | c .Ar major minor .Op Ar owner : Ns Ar group .Sh DESCRIPTION .Bf -symbolic The .Nm utility is deprecated on modern .Fx systems. .Ef .Pp The .Nm utility creates device special files. To make nodes manually, the arguments are: .Bl -tag -width indent .It Ar name Device name, for example .Pa /dev/da0 for a SCSI disk or .Pa /dev/pts/0 for pseudo-terminals. .It Cm b | c Type of device. If the device is a block type device such as a tape or disk drive which needs both cooked and raw special files, the type is .Cm b . All other devices are character type devices, such as terminal and pseudo devices, and are type .Cm c . .It Ar major The major device number is an integer number which tells the kernel which device driver entry point to use. .It Ar minor The minor device number tells the kernel which subunit the node corresponds to on the device; for example, a subunit may be a file system partition or a tty line. .It Ar owner : Ns Ar group The .Ar owner .Ar group operand pair is optional, however, if one is specified, they both must be specified. The .Ar owner may be either a numeric user ID or a user name. If a user name is also a numeric user ID, the operand is used as a user name. The .Ar group may be either a numeric group ID or a group name. Similar to the user name, if a group name is also a numeric group ID, the operand is used as a group name. .El .Pp Major and minor device numbers can be given in any format acceptable to .Xr strtoul 3 , so that a leading .Ql 0x indicates a hexadecimal number, and a leading .Ql 0 will cause the number to be interpreted as octal. .Pp The .Nm utility can be used to recreate deleted device nodes under a -.Xr devfs 5 +.Xr devfs 4 mount point by invoking it with only a filename as an argument. Example: .Pp .Dl "mknod /dev/cd0" .Pp where .Pa /dev/cd0 is the name of the deleted device node. .Sh COMPATIBILITY The .Xr chown 8 Ns - Ns like functionality is specific to .Fx . .Pp As of .Fx 4.0 , block devices were deprecated in favour of character devices. As of .Fx 5.0 , device nodes are managed by the device file system -.Xr devfs 5 , +.Xr devfs 4 , making the .Nm utility superfluous. As of .Fx 6.0 device nodes may be created in regular file systems but such nodes cannot be used to access devices. .Sh SEE ALSO .Xr mkfifo 1 , .Xr mknod 2 , -.Xr devfs 5 , +.Xr devfs 4 , .Xr chown 8 .Sh HISTORY A .Nm utility appeared in .At v4 . diff --git a/sbin/mount/mount.8 b/sbin/mount/mount.8 index e8e604ba4088..ac04ba409ec6 100644 --- a/sbin/mount/mount.8 +++ b/sbin/mount/mount.8 @@ -1,632 +1,632 @@ .\" 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 24, 2024 .Dt MOUNT 8 .Os .Sh NAME .Nm mount .Nd mount file systems .Sh SYNOPSIS .Nm .Op Fl -libxo .Op Fl adflpruvw .Op Fl F Ar fstab .Op Fl o Ar options .Op Fl t Oo Cm no Oc Ns Cm Ar type Ns Op Cm , Ns Ar type ... .Nm .Op Fl -libxo .Op Fl dfpruvw .Ar special | node .Nm .Op Fl -libxo .Op Fl dfpruvw .Op Fl o Ar options .Op Fl t Oo Cm no Oc Ns Cm Ar type Ns Op Cm , Ns Ar type ... .Ar special node .Sh DESCRIPTION The .Nm utility calls the .Xr nmount 2 system call to prepare and graft a .Ar special device or the remote node (rhost:path) on to the file system tree at the point .Ar node . If either .Ar special or .Ar node are not provided, the appropriate information is taken from the .Xr fstab 5 file. .Pp The system maintains a list of currently mounted file systems. If no arguments are given to .Nm , this list is printed. .Pp The options are as follows: .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 a All the file systems described in .Xr fstab 5 are mounted. Exceptions are those marked as .Dq Li noauto , those marked as .Dq Li late (unless the .Fl l option was specified), those excluded by the .Fl t flag (see below), or if they are already mounted (except the root file system which is always remounted to preserve traditional single user mode behavior). .It Fl d Causes everything to be done except for the actual system call. This option is useful in conjunction with the .Fl v flag to determine what the .Nm command is trying to do. .It Fl F Ar fstab Specify the .Pa fstab file to use. .It Fl f Forces the revocation of write access when trying to downgrade a file system mount status from read-write to read-only. Also forces the R/W mount of an unclean file system (dangerous; use with caution). .It Fl L When used in conjunction with the .Fl a option, mount .Em only those file systems which are marked as .Dq Li late . .It Fl l When used in conjunction with the .Fl a option, also mount those file systems which are marked as .Dq Li late . .It Fl n For compatibility with some other implementations, this flag is currently a no-op. .It Fl o Options are specified with a .Fl o flag followed by a comma separated string of options. In case of conflicting options being specified, the rightmost option takes effect. The following options are available: .Bl -tag -width indent .It Cm acls Enable POSIX.1e Access Control Lists, or ACLs, which can be customized via the .Xr setfacl 1 and .Xr getfacl 1 commands. This flag is mutually exclusive with .Cm nfsv4acls flag. .It Cm async All I/O to the file system should be done asynchronously. This is a .Em dangerous flag to set, since it does not guarantee that the file system structure on the disk will remain consistent. For this reason, the .Cm async flag should be used sparingly, and only when some data recovery mechanism is present. .It Cm atime Update the file access time when reading from a file. This is the default. .It Cm automounted This flag indicates that the file system was mounted by .Xr automountd 8 . Automounted file systems are automatically unmounted by .Xr autounmountd 8 . .It Cm autoro Mount the file system read-write. If that fails with an error that suggests that the media could be read-only, then automatically try to mount the file system read-only. .It Cm current When used with the .Fl u flag, this is the same as specifying the options currently in effect for the mounted file system. .It Cm emptydir Require that the mount point directory be empty. .It Cm force The same as .Fl f ; forces the revocation of write access when trying to downgrade a file system mount status from read-write to read-only. Also forces the R/W mount of an unclean file system (dangerous; use with caution). .It Cm fstab When used with the .Fl u flag, this is the same as specifying all the options listed in the .Xr fstab 5 file for the file system. .It Cm late This file system should be skipped when .Nm is run with the .Fl a flag but without the .Fl l flag. .It Cm mountprog Ns = Ns Aq Ar program Force .Nm to use the specified program to mount the file system, instead of calling .Xr nmount 2 directly. For example: .Bd -literal mount -t foofs -o mountprog=/mydir/fooprog /dev/cd0 /mnt .Ed .It Cm multilabel Enable multi-label Mandatory Access Control, or MAC, on the specified file system. If the file system supports multilabel operation, individual labels will be maintained for each object in the file system, rather than using a single label for all objects. An alternative to the .Fl l flag in .Xr tunefs 8 . See .Xr mac 4 for more information, which cause the multilabel mount flag to be set automatically at mount-time. .It Cm nfsv4acls Enable NFSv4 ACLs, which can be customized via the .Xr setfacl 1 and .Xr getfacl 1 commands. This flag is mutually exclusive with .Cm acls flag. .It Cm noasync Metadata I/O should be done synchronously, while data I/O should be done asynchronously. This is the default. .It Cm noatime Do not update the file access time when reading from a file. This option is useful on file systems where there are large numbers of files and performance is more critical than updating the file access time (which is rarely ever important). This option is currently only supported on local file systems. .It Cm noauto This file system should be skipped when .Nm is run with the .Fl a flag. .It Cm noclusterr Disable read clustering. .It Cm noclusterw Disable write clustering. .It Cm nocover Do not mount if the requested mount point is already the root of a mount point. .It Cm noexec Do not allow execution of any binaries on the mounted file system. This option is useful for a server that has file systems containing binaries for architectures other than its own. Note: This option was not designed as a security feature and no guarantee is made that it will prevent malicious code execution; for example, it is still possible to execute scripts which reside on a .Cm noexec mounted partition. .It Cm nosuid Do not allow set-user-identifier or set-group-identifier bits to take effect. Note: this option is worthless if a public available suid or sgid wrapper is installed on your system. It is set automatically when the user does not have super-user privileges. .It Cm nosymfollow Do not follow symlinks on the mounted file system. .It Cm ro The same as .Fl r ; mount the file system read-only (even the super-user may not write it). .It Cm snapshot Take a snapshot of the specified filesystem. When this option is used, all other options are ignored. The .Fl u flag is required with this option. .Pp Snapshot files must be created in the file system that is being snapshotted. You may create up to 20 snapshots per file system. Active snapshots are recorded in the superblock, so they persist across unmount and remount operations and across system reboots. When you are done with a snapshot, it can be removed with the .Xr rm 1 command. Snapshots may be removed in any order, however you may not get back all the space contained in the snapshot as another snapshot may claim some of the blocks that it is releasing. Note that the schg flag is set on snapshots to ensure that not even the root user can write to them. The unlink command makes an exception for snapshot files in that it allows them to be removed even though they have the schg flag set, so it is not necessary to clear the schg flag before removing a snapshot file. .Pp Once you have taken a snapshot, there are three interesting things that you can do with it: .Pp .Bl -enum -compact .It Run .Xr fsck 8 on the snapshot file. Assuming that the file system was clean when it was mounted, you should always get a clean (and unchanging) result from running fsck on the snapshot. This is essentially what the background fsck process does. .Pp .It Run .Xr dump 8 on the snapshot. You will get a dump that is consistent with the file system as of the timestamp of the snapshot. .Pp .It Mount the snapshot as a frozen image of the file system. To mount the snapshot .Pa /var/snapshot/snap1 : .Bd -literal mdconfig -a -t vnode -f /var/snapshot/snap1 -u 4 mount -r /dev/md4 /mnt .Ed .Pp You can now cruise around your frozen .Pa /var file system at .Pa /mnt . Everything will be in the same state that it was at the time the snapshot was taken. The one exception is that any earlier snapshots will appear as zero length files. When you are done with the mounted snapshot: .Bd -literal umount /mnt mdconfig -d -u 4 .Ed .El .It Cm suiddir A directory on the mounted file system will respond to the SUID bit being set, by setting the owner of any new files to be the same as the owner of the directory. New directories will inherit the bit from their parents. Execute bits are removed from the file, and it will not be given to root. .Pp This feature is designed for use on fileservers serving PC users via ftp, SAMBA, or netatalk. It provides security holes for shell users and as such should not be used on shell machines, especially on home directories. This option requires the SUIDDIR option in the kernel to work. Only UFS file systems support this option. See .Xr chmod 2 for more information. .It Cm sync All I/O to the file system should be done synchronously. .It Cm update The same as .Fl u ; indicate that the status of an already mounted file system should be changed. .It Cm union Causes the namespace at the mount point to appear as the union of the mounted file system root and the existing directory. Lookups will be done in the mounted file system first. If those operations fail due to a non-existent file the underlying directory is then accessed. All creates are done in the mounted file system. .It Cm untrusted The file system is untrusted and the kernel should use more extensive checks on the file-system's metadata before using it. This option is intended to be used when mounting file systems from untrusted media such as USB memory sticks or other externally-provided media. .El .Pp Any additional options specific to a file system type that is not one of the internally known types (see the .Fl t option) may be passed as a comma separated list; these options are distinguished by a leading .Dq \&- (dash). For example, the .Nm command: .Bd -literal -offset indent mount -t cd9660 -o -e /dev/cd0 /cdrom .Ed .Pp causes .Nm to execute the equivalent of: .Bd -literal -offset indent /sbin/mount_cd9660 -e /dev/cd0 /cdrom .Ed .Pp Options that take a value are specified using the -option=value syntax: .Bd -literal -offset indent mount -t msdosfs -o -u=fred,-g=wheel /dev/da0s1 /mnt .Ed .Pp is equivalent to .Bd -literal -offset indent /sbin/mount_msdosfs -u fred -g wheel /dev/da0s1 /mnt .Ed .Pp Additional options specific to file system types which are not internally known (see the description of the .Fl t option below) may be described in the manual pages for the associated .Pa /sbin/mount_ Ns Sy XXX utilities. .It Fl p Print mount information in .Xr fstab 5 format. Implies also the .Fl v option. .It Fl r The file system is to be mounted read-only. Mount the file system read-only (even the super-user may not write it). The same as the .Cm ro argument to the .Fl o option. .It Fl t Oo Cm no Oc Ns Cm Ar type Ns Op Cm , Ns Ar type ... The argument following the .Fl t is used to indicate the file system type. The type .Cm ufs is the default. The .Fl t option can be used to indicate that 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 .Cm no to specify the file system types for which action should .Em not be taken. For example, the .Nm command: .Bd -literal -offset indent mount -a -t nonfs,nullfs .Ed .Pp mounts all file systems except those of type NFS and NULLFS. .Pp The default behavior of .Nm is to pass the .Fl t option directly to the .Xr nmount 2 system call in the .Li fstype option. .Pp However, for the following file system types: .Cm cd9660 , .Cm mfs , .Cm msdosfs , .Cm nfs , .Cm nullfs , .Cm smbfs , .Cm udf , and .Cm unionfs .Nm will not call .Xr nmount 2 directly and will instead attempt to execute a program in .Pa /sbin/mount_ Ns Ar type where .Ar type is replaced by the file system type name. For example, .Cm nfs file systems are mounted by the program .Pa /sbin/mount_nfs . .Pp Most file systems will be dynamically loaded by the kernel if not already present, and if the kernel module is available. .It Fl u The .Fl u flag indicates that the status of an already mounted file system should be changed. Any of the options discussed above (the .Fl o option) may be changed; also a file system can be changed from read-only to read-write or vice versa. An attempt to change from read-write to read-only will fail if any files on the file system are currently open for writing unless the .Fl f flag is also specified. The set of options is determined by applying the options specified in the argument to .Fl o and finally applying the .Fl r or .Fl w option. .It Fl v Verbose mode. If the .Fl v is used alone, show all file systems, including those that were mounted with the .Dv MNT_IGNORE flag and show additional information about each file system (including fsid when run by root). .It Fl w The file system object is to be read and write. .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 DIAGNOSTICS Various, most of them are self-explanatory. .Pp .Dl XXXXX file system is not available .Pp The kernel does not support the respective file system type. Note that support for a particular file system might be provided either on a static (kernel compile-time), or dynamic basis (loaded as a kernel module by .Xr kldload 8 ) . .Sh SEE ALSO .Xr getfacl 1 , .Xr setfacl 1 , .Xr nmount 2 , .Xr acl 3 , .Xr getmntinfo 3 , .Xr libxo 3 , .Xr xo_parse_args 3 , +.Xr cd9660 4 , +.Xr devfs 4 , +.Xr ext2fs 4 , .Xr mac 4 , -.Xr cd9660 5 , -.Xr devfs 5 , -.Xr ext2fs 5 , +.Xr procfs 4 , +.Xr tarfs 4 , +.Xr tmpfs 4 , .Xr fstab 5 , -.Xr procfs 5 , -.Xr tarfs 5 , -.Xr tmpfs 5 , .Xr automount 8 , .Xr fstyp 8 , .Xr kldload 8 , .Xr mount_cd9660 8 , .Xr mount_msdosfs 8 , .Xr mount_nfs 8 , .Xr mount_nullfs 8 , .Xr mount_smbfs 8 , .Xr mount_udf 8 , .Xr mount_unionfs 8 , .Xr quotacheck 8 , .Xr umount 8 , .Xr zfs 8 , .Xr zpool 8 .Sh HISTORY A .Nm utility appeared in .At v1 . .Sh CAVEATS After a successful .Nm , the permissions on the original mount point determine if .Pa ..\& is accessible from the mounted file system. The minimum permissions for the mount point for traversal across the mount point in both directions to be possible for all users is 0111 (execute for all). .Pp Use of the .Nm is preferred over the use of the file system specific .Pa mount_ Ns Sy XXX commands. In particular, .Xr mountd 8 gets a .Dv SIGHUP signal (that causes an update of the export list) only when the file system is mounted via .Nm . .Sh BUGS It is possible for a corrupted file system to cause a crash. .Pp The .Fl p option will not list .Cm userquota or .Cm groupquota items from .Xr fstab 5 because they are not true mount options and are not information returned by .Xr getmntinfo 3 . At boot .Xr quotacheck 8 , processes these items. diff --git a/sbin/mount_cd9660/mount_cd9660.8 b/sbin/mount_cd9660/mount_cd9660.8 index d2cdd2f3ef20..017ad7ee9a11 100644 --- a/sbin/mount_cd9660/mount_cd9660.8 +++ b/sbin/mount_cd9660/mount_cd9660.8 @@ -1,194 +1,194 @@ .\" Copyright (c) 1993, 1994 .\" The Regents of the University of California. All rights reserved. .\" All rights reserved. .\" .\" This code is derived from software donated to Berkeley by .\" Christopher G. Demetriou. .\" .\" 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 2, 2024 .Dt MOUNT_CD9660 8 .Os .Sh NAME .Nm mount_cd9660 .Nd mount an ISO-9660 file system .Sh SYNOPSIS .Nm .Op Fl begjrv .Op Fl C Ar charset .Op Fl G Ar gid .Op Fl m Ar mask .Op Fl M Ar mask .Op Fl o Ar options .Op Fl s Ar startsector .Op Fl U Ar uid .Ar special node .Sh DESCRIPTION The .Nm utility attaches the ISO-9660 file system residing on the device .Pa special to the global file system namespace at the location indicated by .Pa node . This command is normally executed by .Xr mount 8 at boot time. .Pp The options are as follows: .Bl -tag -width indent .It Fl b Relax checking for Supplementary Volume Descriptor Flags field which is set to a wrong value on some Joliet formatted disks. .It Fl e Enable the use of extended attributes. .It Fl g Do not strip version numbers on files. (By default, if there are files with different version numbers on the disk, only the last one will be listed.) In either case, files may be opened without explicitly stating a version number. .It Fl G Ar group Set the group of the files in the file system to .Ar group . The default gid on non-Rockridge volumes is zero. .It Fl U Ar user Set the owner of the files in the file system to .Ar user . The default uid on non-Rockridge volumes is zero. .It Fl m Ar mask Specify the maximum file permissions for files in the file system. (For example, a .Ar mask of .Li 755 specifies that, by default, the owner should have read, write, and execute permissions for files, but others should only have read and execute permissions). See .Xr chmod 1 for more information about octal file modes. Only the nine low-order bits of .Ar mask are used. The default .Ar mask on non-Rockridge volumes is 755. .It Fl M Ar mask Specify the maximum file permissions for directories in the file system. See the previous option's description for details. .It Fl j Do not use any Joliet extensions included in the file system. .It Fl o Options are specified with a .Fl o flag followed by a comma separated string of options. See the .Xr mount 8 man page for possible options and their meanings. The following cd9660 specific options are available: .Pp .Bl -tag -width "brokenjoliet" -compact .It Cm extatt Same as .Fl e . .It Cm gens Same as .Fl g . .It Cm nojoliet Same as .Fl j . .It Cm norrip Same as .Fl r . .It Cm brokenjoliet Same as .Fl b . .El .It Fl r Do not use any Rockridge extensions included in the file system. .It Fl s Ar startsector Start the file system at .Ar startsector . Normally, if the underlying device is a CD-ROM drive, .Nm will try to figure out the last track from the CD-ROM containing data, and start the file system there. If the device is not a CD-ROM, or the table of contents cannot be examined, the file system will be started at sector 0. This option can be used to override the behaviour. Note that .Ar startsector is measured in CD-ROM blocks, with 2048 bytes each. This is the same as for example the .Cm info command of .Xr cdcontrol 1 is printing. It is possible to mount an arbitrary session of a multi-session CD by specifying the correct .Ar startsector here. .It Fl C Ar charset Specify local .Ar charset to convert Unicode file names when using Joliet extensions. .It Fl v Be verbose about the starting sector decisions made. .El .Sh EXAMPLES The following command can be used to mount a Kodak Photo-CD: .Pp .Dl "mount_cd9660 -o rw -v -s 0 /dev/cd0 /cdrom" .Sh SEE ALSO .Xr cdcontrol 1 , .Xr mount 2 , .Xr unmount 2 , -.Xr cd9660 5 , +.Xr cd9660 4 , .Xr fstab 5 , .Xr mdconfig 8 , .Xr mount 8 .Sh HISTORY The .Nm utility first appeared in .Bx 4.4 . .Pp The Unicode conversion routine was added by .An Ryuichiro Imura Aq Mt imura@ryu16.org in 2003. .Sh BUGS POSIX device node mapping is currently not supported. .Pp Version numbers are not stripped if Rockridge extensions are in use. In this case, accessing files that do not have Rockridge names without version numbers gets the one with the lowest version number and not the one with the highest. .Pp There is no ECMA support. diff --git a/sbin/mount_msdosfs/mount_msdosfs.8 b/sbin/mount_msdosfs/mount_msdosfs.8 index 94532cafb543..3a97089e220c 100644 --- a/sbin/mount_msdosfs/mount_msdosfs.8 +++ b/sbin/mount_msdosfs/mount_msdosfs.8 @@ -1,220 +1,220 @@ .\" $NetBSD: mount_msdos.8,v 1.13 1998/02/06 05:57:00 perry Exp $ .\" .\" Copyright (c) 1993,1994 Christopher G. Demetriou .\" 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 by Christopher G. Demetriou. .\" 3. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .Dd May 28, 2017 .Dt MOUNT_MSDOSFS 8 .Os .Sh NAME .Nm mount_msdosfs .Nd mount an MS-DOS file system .Sh SYNOPSIS .Nm .Op Fl 9ls .Op Fl D Ar DOS_codepage .Op Fl g Ar gid .Op Fl L Ar locale .Op Fl M Ar mask .Op Fl m Ar mask .Op Fl o Ar options .Op Fl u Ar uid .Op Fl W Ar table .Ar special node .Sh DESCRIPTION The .Nm utility attaches the MS-DOS file system residing on the device .Pa special to the global file system namespace at the location indicated by .Pa node . This command is normally executed by .Xr mount 8 at boot time, but can be used by any user to mount an MS-DOS file system on any directory that they own (provided, of course, that they have appropriate access to the device that contains the file system). .Pp The options are as follows: .Bl -tag -width Ds .It Fl o Ar options Use the specified mount .Ar options , as described in .Xr mount 8 . The following MSDOS file system-specific options are available: .Bl -tag -width indent .It Cm longnames Force Windows 95 long filenames to be visible. .It Cm shortnames Force only the old MS-DOS 8.3 style filenames to be visible. .It Cm nowin95 Completely ignore Windows 95 extended file information. .El .It Fl u Ar uid Set the owner of the files in the file system to .Ar uid . The default owner is the owner of the directory on which the file system is being mounted. .It Fl g Ar gid Set the group of the files in the file system to .Ar gid . The default group is the group of the directory on which the file system is being mounted. .It Fl m Ar mask Specify the maximum file permissions for files in the file system. (For example, a .Ar mask of .Li 755 specifies that, by default, the owner should have read, write, and execute permissions for files, but others should only have read and execute permissions. See .Xr chmod 1 for more information about octal file modes. Only the nine low-order bits of .Ar mask are used. The value of .Ar -M is used if it is supplied and .Ar -m is omitted. The default .Ar mask is taken from the directory on which the file system is being mounted. .It Fl M Ar mask Specify the maximum file permissions for directories in the file system. The value of .Ar -m is used if it is supplied and .Ar -M is omitted. See the previous option's description for details. .It Fl s Force behaviour to ignore and not generate Win'95 long filenames. .It Fl l Force listing and generation of Win'95 long filenames and separate creation/modification/access dates. .Pp If neither .Fl s nor .Fl l are given, .Fl l is the default. .It Fl 9 Ignore the special Win'95 directory entries even if deleting or renaming a file. This forces .Fl s . .\".It Fl G .\"This option causes the file system to be interpreted as an Atari-Gemdos .\"file system. .\"The differences to the MS-DOS file system are minimal and .\"limited to the boot block. .\"This option enforces .\".Fl s . .It Fl L Ar locale Specify locale name used for file name conversions for DOS and Win'95 names. By default ISO 8859-1 assumed as local character set. .It Fl D Ar DOS_codepage Specify the MS-DOS code page (aka IBM/OEM code page) name used for file name conversions for DOS names. .It Fl W Ar table .Bf Em This option is preserved for backward compatibility purpose only, and will be removed in the future. Please avoid using this option. .Ef .Pp Specify text file name with conversion table: .Pa iso22dos , iso72dos , koi2dos , koi8u2dos . .El .Sh EXAMPLES To mount a Russian MS-DOS file system located in .Pa /dev/ada1s1 : .Pp .Dl "mount_msdosfs -L ru_RU.KOI8-R -D CP866 /dev/ada1s1 /mnt" .Pp To mount a Japanese MS-DOS file system located in .Pa /dev/ada1s1 : .Pp .Dl "mount_msdosfs -L ja_JP.eucJP -D CP932 /dev/ada1s1 /mnt" .Sh SEE ALSO .Xr mount 2 , .Xr unmount 2 , +.Xr msdosfs 4 , .Xr fstab 5 , -.Xr msdosfs 5 , .Xr mount 8 .Pp List of Localized MS Operating Systems: .Pa http://www.microsoft.com/globaldev/reference/oslocversion.mspx . .Sh HISTORY The predecessor to .Nm mount_msdos utility named .Nm mount_pcfs appeared in .Nx 0.8 . It was rewritten in .Nx 1.0 and first appeared in .Fx 2.0 . .Nm mount_msdos was renamed to the more aptly-named .Nm in .Fx 5.0 . The character code conversion routine was added in 2003. .Sh AUTHORS Initial implementation as .Nm mount_pcfs was written by .An -nosplit .An Paul Popelka Aq Mt paulp@uts.amdahl.com . It was rewritten by .An Christopher G. Demetriou Aq Mt cgd@NetBSD.org . The character code conversion routine was added by .An Ryuichiro Imura Aq Mt imura@ryu16.org . .Sh CAVEATS The use of the .Fl 9 flag could result in damaged file systems, albeit the damage is in part taken care of by procedures similar to the ones used in Win'95. diff --git a/sbin/mount_nfs/mount_nfs.8 b/sbin/mount_nfs/mount_nfs.8 index 3ef622a96dc0..13f0608ccad9 100644 --- a/sbin/mount_nfs/mount_nfs.8 +++ b/sbin/mount_nfs/mount_nfs.8 @@ -1,704 +1,704 @@ .\" Copyright (c) 1992, 1993, 1994, 1995 .\" 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 October 8, 2023 .Dt MOUNT_NFS 8 .Os .Sh NAME .Nm mount_nfs .Nd mount NFS file systems .Sh SYNOPSIS .Nm .Op Fl 23bcdiLlNPsTU .Op Fl a Ar maxreadahead .Op Fl D Ar deadthresh .Op Fl g Ar maxgroups .Op Fl I Ar readdirsize .Op Fl o Ar options .Op Fl R Ar retrycnt .Op Fl r Ar readsize .Op Fl t Ar timeout .Op Fl w Ar writesize .Op Fl x Ar retrans .Ar rhost : Ns Ar path node .Sh DESCRIPTION The .Nm utility calls the .Xr nmount 2 system call to prepare and graft a remote NFS file system .Pq Ar rhost : Ns Ar path on to the file system tree at the point .Ar node . This command is normally executed by .Xr mount 8 . For NFSv2 and NFSv3, it implements the mount protocol as described in RFC 1094, Appendix A and RFC 1813, Appendix I. For NFSv4, it uses the NFSv4 protocol as described in RFC 7530, RFC 5661 and RFC 7862. .Pp By default, .Nm keeps retrying until the mount succeeds. This behaviour is intended for file systems listed in .Xr fstab 5 that are critical to the boot process. For non-critical file systems, the .Cm bg and .Cm retrycnt options provide mechanisms to prevent the boot process from hanging if the server is unavailable. .Pp If the server becomes unresponsive while an NFS file system is mounted, any new or outstanding file operations on that file system will hang uninterruptibly until the server comes back. To modify this default behaviour, see the .Cm intr and .Cm soft options. .Pp The options are: .Bl -tag -width indent .It Fl o Options are specified with a .Fl o flag followed by a comma separated string of options. See the .Xr mount 8 man page for possible options and their meanings. The following NFS specific options are also available: .Bl -tag -width indent .It Cm acregmin Ns = Ns Aq Ar seconds .It Cm acregmax Ns = Ns Aq Ar seconds .It Cm acdirmin Ns = Ns Aq Ar seconds .It Cm acdirmax Ns = Ns Aq Ar seconds When attributes of files are cached, a timeout calculated to determine whether a given cache entry has expired. These four values determine the upper and lower bounds of the timeouts for .Dq directory attributes and .Dq regular (ie: everything else). The default values are 3 -> 60 seconds for regular files, and 30 -> 60 seconds for directories. The algorithm to calculate the timeout is based on the age of the file. The older the file, the longer the cache is considered valid, subject to the limits above. .It Cm actimeo Ns = Ns Aq Ar seconds Set four cache timeouts above to specified value. .It Cm allgssname This option can be used along with .Fl o Cm gssname to specify that all operations should use the host-based initiator credential. This may be used for clients that run system daemons that need to access files on the NFSv4 mounted volume. .It Cm bg If an initial attempt to contact the server fails, fork off a child to keep trying the mount in the background. Useful for .Xr fstab 5 , where the file system mount is not critical to multiuser operation. .It Cm bgnow Like .Cm bg , fork off a child to keep trying the mount in the background, but do not attempt to mount in the foreground first. This eliminates a 60+ second timeout when the server is not responding. Useful for speeding up the boot process of a client when the server is likely to be unavailable. This is often the case for interdependent servers such as cross-mounted servers (each of two servers is an NFS client of the other) and for cluster nodes that must boot before the file servers. .It Cm deadthresh Ns = Ns Aq Ar value Set the .Dq "dead server threshold" to the specified number of round trip timeout intervals before a .Dq "server not responding" message is displayed. .It Cm dumbtimer Turn off the dynamic retransmit timeout estimator. This may be useful for UDP mounts that exhibit high retry rates, since it is possible that the dynamically estimated timeout interval is too short. .It Cm fg Same as not specifying .Cm bg . .It Cm gssname Ns = Ns Aq Ar service-principal-name This option can be used with the KerberosV security flavors for NFSv4 mounts to specify the .Dq "service-principal-name" of a host-based entry in the default keytab file that is used for system operations. It allows the mount to be performed by .Dq "root" and avoids problems with cached credentials for the system operations expiring. The .Dq "service-principal-name" should be specified without instance or domain and is typically .Dq "host" , .Dq "nfs" or .Dq "root" , although the form .Sm off .Aq Ar service @ .Aq Ar fqdn .Sm on can also be used if the local system's .Xr gethostname 3 value does not match the host-based principal in the keytab. .It Cm hard Same as not specifying .Cm soft . .It Cm intr Make the mount interruptible, which implies that file system calls that are delayed due to an unresponsive server will fail with EINTR when a termination signal is posted for the process. To avoid leaving file locks in an indeterminate state on the NFS server, it is recommended that the .Cm nolockd option be used with this option. .It Cm maxgroups Ns = Ns Aq Ar value Set the maximum size of the group list for the credentials to the specified value. This should be used for mounts on old servers that cannot handle a group list size of 16, as specified in RFC 1057. Try 8, if users in a lot of groups cannot get response from the mount point. .It Cm mntudp Force the mount protocol to use UDP transport, even for TCP NFS mounts. (Necessary for some old .Bx servers.) .It Cm nametimeo Ns = Ns Aq Ar value Override the default of NFS_DEFAULT_NAMETIMEO for the timeout (in seconds) for positive name cache entries. If this is set to 0 it disables positive name caching for the mount point. .It Cm negnametimeo Ns = Ns Aq Ar value Override the default of NFS_DEFAULT_NEGNAMETIMEO for the timeout (in seconds) for negative name cache entries. If this is set to 0 it disables negative name caching for the mount point. .It Cm nconnect Ns = Ns Aq Ar value Specify the number of TCP connections (1-16) to be used for an NFS Version 4, minor version 1 or 2 mount. Multiple TCP connections can provide more client to server network bandwidth for certain network configurations such as: .Bd -literal - Multiple network interfaces that are aggregated together. - A fast network interface that uses multiple queues. .Ed .sp The first TCP connection will be used for all RPCs that consist entirely of small RPC messages. The RPCs that can have large RPC messages (Read/Readdir/Write) are distributed over the additional TCP connections in a round robin fashion. This option will result in more IP port#s being used. This option requires the .Cm nfsv4 option. Note that for NFS servers such as AmazonEFS, where each new TCP connection can connect to a different cluster that maintains lock state separately, this option cannot be used. .It Cm nfsv2 Use the NFS Version 2 protocol (the default is to try version 3 first then version 2). Note that NFS version 2 has a file size limit of 2 gigabytes. .It Cm nfsv3 Use the NFS Version 3 protocol. .It Cm nfsv4 Use the NFS Version 4 protocol. This option will force the mount to use TCP transport. By default, the highest minor version of NFS Version 4 that is supported by the NFS Version 4 server will be used. See the .Cm minorversion option. Make sure that all your NFS Version 4 clients have unique values in .Pa /etc/hostid . .It Cm minorversion Ns = Ns Aq Ar value Use the specified minor version for a NFS Version 4 mount, overriding the default. The minor versions supported are 0, 1, and 2. This option is only meaningful when used with the .Cm nfsv4 option. .It Cm oneopenown Make a minor version 1 or 2 of the NFS Version 4 protocol mount use a single OpenOwner for all Opens. This may be useful for a server with a very low limit on OpenOwners, such as AmazonEFS. It may be required when an accumulation of NFS version 4 Opens occurs, as indicated by the .Dq Opens count displayed by .Xr nfsstat 1 with the .Fl c and .Fl E command-line options. A common case for an accumulation of Opens is a shared library within the NFS mount that is used by several processes, where at least one of these processes is always running. This option cannot be used for an NFS Version 4, minor version 0 mount. It may not work correctly when Delegations are being issued by a server, but note that the AmazonEFS server does not issued delegations at this time. This option is only meaningful when used with the .Cm nfsv4 option. .It Cm pnfs Enable support for parallel NFS (pNFS) for minor version 1 or 2 of the NFS Version 4 protocol. This option is only meaningful when used with the .Cm nfsv4 option. .It Cm noac Disable attribute caching. .It Cm noconn For UDP mount points, do not do a .Xr connect 2 . This must be used if the server does not reply to requests from the standard NFS port number 2049 or replies to requests using a different IP address (which can occur if the server is multi-homed). Setting the .Va vfs.nfs.nfs_ip_paranoia sysctl to 0 will make this option the default. .It Cm nocto Normally, NFS clients maintain the close-to-open cache coherency. This works by flushing at close time and checking at open time. Checking at open time is implemented by getting attributes from the server and purging the data cache if they do not match attributes cached by the client. .Pp This option disables checking at open time. It may improve performance for read-only mounts, but should only be used if the data on the server changes rarely. Be sure to understand the consequences before enabling this option. .It Cm noinet4 , noinet6 Disables .Dv AF_INET or .Dv AF_INET6 connections. Useful for hosts that have both an A record and an AAAA record for the same name. .It Cm nolockd Do .Em not forward .Xr fcntl 2 locks over the wire via the NLM protocol for NFSv3 mounts or via the NFSv4 protocol for NFSv4 mounts. All locks will be local and not seen by the server and likewise not seen by other NFS clients for NFSv3 or NFSv4 mounts. This removes the need to run the .Xr rpcbind 8 service and the .Xr rpc.statd 8 and .Xr rpc.lockd 8 servers on the client for NFSv3 mounts. Note that this option will only be honored when performing the initial mount, it will be silently ignored if used while updating the mount options. Also, note that NFSv4 mounts do not use these daemons. The NFSv4 protocol handles locks, unless this option is specified. .It Cm noncontigwr This mount option allows the NFS client to combine non-contiguous byte ranges being written such that the dirty byte range becomes a superset of the bytes that are dirty. This reduces the number of writes significantly for software builds. The merging of byte ranges is not done if the file has been file locked, since most applications modifying a file from multiple clients will use file locking. As such, this option could result in a corrupted file for the rare case of an application modifying the file from multiple clients concurrently without using file locking. .It Cm principal For the RPCSEC_GSS security flavors, such as krb5, krb5i and krb5p, this option sets the name of the host based principal name expected by the server. This option overrides the default, which will be ``nfs@'' and should normally be sufficient. .It Cm noresvport Do .Em not use a reserved socket port number (see below). .It Cm port Ns = Ns Aq Ar port_number Use specified port number for NFS requests. The default is to query the portmapper for the NFS port. .It Cm proto Ns = Ns Aq Ar protocol Specify transport protocol version to use. Currently, they are: .Bd -literal udp - Use UDP over IPv4 tcp - Use TCP over IPv4 udp6 - Use UDP over IPv6 tcp6 - Use TCP over IPv6 .Ed .It Cm rdirplus Used with NFSV3 to specify that the \fBReaddirPlus\fR RPC should be used. For NFSV4, setting this option has a similar effect, in that it will make the Readdir Operation get more attributes. This option reduces RPC traffic for cases such as .Dq "ls -l" , but tends to flood the attribute and name caches with prefetched entries. Try this option and see whether performance improves or degrades. Probably most useful for client to server network interconnects with a large bandwidth times delay product. .It Cm readahead Ns = Ns Aq Ar value Set the read-ahead count to the specified value. This may be in the range of 0 - 4, and determines how many blocks will be read ahead when a large file is being read sequentially. Trying a value greater than 1 for this is suggested for mounts with a large bandwidth * delay product. .It Cm readdirsize Ns = Ns Aq Ar value Set the readdir read size to the specified value. The value should normally be a multiple of .Dv DIRBLKSIZ that is <= the read size for the mount. .It Cm resvport Use a reserved socket port number. This flag is obsolete, and only retained for compatibility reasons. Reserved port numbers are used by default now. (For the rare case where the client has a trusted root account but untrustworthy users and the network cables are in secure areas this does help, but for normal desktop clients this does not apply.) .It Cm retrans Ns = Ns Aq Ar value Set the retransmit timeout count for soft mounts to the specified value. .It Cm retrycnt Ns = Ns Aq Ar count Set the mount retry count to the specified value. The default is a retry count of zero, which means to keep retrying forever. There is a 60 second delay between each attempt. .It Cm rsize Ns = Ns Aq Ar value Set the read data size to the specified value. It should normally be a power of 2 greater than or equal to 1024. This should be used for UDP mounts when the .Dq "fragments dropped due to timeout" value is getting large while actively using a mount point. (Use .Xr netstat 1 with the .Fl s option to see what the .Dq "fragments dropped due to timeout" value is.) .It Cm sec Ns = Ns Aq Ar flavor This option specifies what security flavor should be used for the mount. Currently, they are: .Bd -literal krb5 - Use KerberosV authentication krb5i - Use KerberosV authentication and apply integrity checksums to RPCs krb5p - Use KerberosV authentication and encrypt the RPC data sys - The default AUTH_SYS, which uses a uid + gid list authenticator .Ed .It Cm soft A soft mount, which implies that file system calls will fail after .Ar retrycnt round trip timeout intervals. .It Cm syskrb5 This option specifies that a KerberosV NFSv4 minor version 1 or 2 mount uses AUTH_SYS for system operations. Using this option avoids the need for a KerberosV mount to have a host-based principal entry in the default keytab file (no .Cm gssname option) or a requirement for the user doing the mount to have a valid KerberosV ticket granting ticket (TGT) when the mount is done. This option is intended to be used with the .Cm sec Ns = Ns krb5 and .Cm tls options and can only be used for NFSv4 mounts with minor version 1 or 2. .It Cm tcp Use TCP transport. This is the default option, as it provides for increased reliability on both LAN and WAN configurations compared to UDP. Some old NFS servers do not support this method; UDP mounts may be required for interoperability. .It Cm timeout Ns = Ns Aq Ar value Set the initial retransmit timeout to the specified value, expressed in tenths of a second. May be useful for fine tuning UDP mounts over internetworks with high packet loss rates or an overloaded server. Try increasing the interval if .Xr nfsstat 1 shows high retransmit rates while the file system is active or reducing the value if there is a low retransmit rate but long response delay observed. (Normally, the .Cm dumbtimer option should be specified when using this option to manually tune the timeout interval.) .It Cm timeo Ns = Ns Aq Ar value Alias for .Cm timeout . .It Cm tls This option specifies that the connection to the server must use TLS per RFC 9289. TLS is only supported for TCP connections and the .Xr rpc.tlsclntd 8 daemon must be running for an NFS over TCP connection to use TLS. .It Cm tlscertname Ns = Ns Aq Ar name This option specifies the name of an alternate certificate to be presented to the NFS server during TLS handshake. The default certificate file names are .Dq cert.pem and .Dq certkey.pem . When this option is specified, .Ar name replaces .Dq cert in the above file names. For example, if the value of .Ar name is specified as .Dq other the certificate file names to be used will be .Dq other.pem and .Dq otherkey.pem . These files are stored in .Pa /etc/rpc.tlsclntd by default. This option is only meaningful when used with the .Cm tls option and the .Xr rpc.tlsclntd 8 is running with the .Fl m command line flag set. .It Cm udp Use UDP transport. .It Cm vers Ns = Ns Aq Ar vers_number Use the specified version number for NFS requests. See the .Cm nfsv2 , .Cm nfsv3 , and .Cm nfsv4 options for details. .It Cm wcommitsize Ns = Ns Aq Ar value Set the maximum pending write commit size to the specified value. This determines the maximum amount of pending write data that the NFS client is willing to cache for each file. .It Cm wsize Ns = Ns Aq Ar value Set the write data size to the specified value. Ditto the comments w.r.t.\& the .Cm rsize option, but using the .Dq "fragments dropped due to timeout" value on the server instead of the client. Note that both the .Cm rsize and .Cm wsize options should only be used as a last ditch effort at improving performance when mounting servers that do not support TCP mounts. .El .El .Sh IMPLEMENTATION NOTES When neither the .Cm rsize nor .Cm wsize options are specified, the I/O size will be set to the largest value supported by both the NFS client and server. The largest value supported by the NFS client is defined by the tunable .Cd vfs.maxbcachebuf which can be set to a power of two up to .Cd kern.maxphys . .Pp The .Xr nfsstat 1 command with the .Ic -m command line option will show what .Nm option settings are actually in use for the mount. .Sh COMPATIBILITY The following command line flags are equivalent to .Fl o named options and are supported for compatibility with older installations. .Bl -tag -width indent .It Fl 2 Same as .Fl o Cm nfsv2 .It Fl 3 Same as .Fl o Cm nfsv3 .It Fl D Same as .Fl o Cm deadthresh .It Fl I Same as .Fl o Cm readdirsize Ns = Ns Aq Ar value .It Fl L Same as .Fl o Cm nolockd .It Fl N Same as .Fl o Cm noresvport .It Fl P Use a reserved socket port number. This flag is obsolete, and only retained for compatibility reasons. (For the rare case where the client has a trusted root account but untrustworthy users and the network cables are in secure areas this does help, but for normal desktop clients this does not apply.) .It Fl R Same as .Fl o Cm retrycnt Ns = Ns Aq Ar value .It Fl T Same as .Fl o Cm tcp .It Fl U Same as .Fl o Cm mntudp .It Fl a Same as .Fl o Cm readahead Ns = Ns Aq Ar value .It Fl b Same as .Fl o Cm bg .It Fl c Same as .Fl o Cm noconn .It Fl d Same as .Fl o Cm dumbtimer .It Fl g Same as .Fl o Cm maxgroups .It Fl i Same as .Fl o Cm intr .It Fl l Same as .Fl o Cm rdirplus .It Fl r Same as .Fl o Cm rsize Ns = Ns Aq Ar value .It Fl s Same as .Fl o Cm soft .It Fl t Same as .Fl o Cm retransmit Ns = Ns Aq Ar value (deprecated) .It Fl w Same as .Fl o Cm wsize Ns = Ns Aq Ar value .It Fl x Same as .Fl o Cm retrans Ns = Ns Aq Ar value .El .Pp The following .Fl o named options are equivalent to other .Fl o named options and are supported for compatibility with other operating systems (e.g., Linux, Solaris, and OSX) to ease usage of -.Xr autofs 5 +.Xr autofs 4 support. .Bl -tag -width indent .It Fl o Cm vers Ns = Ns 2 Same as .Fl o Cm nfsv2 .It Fl o Cm vers Ns = Ns 3 Same as .Fl o Cm nfsv3 .It Fl o Cm vers Ns = Ns 4 Same as .Fl o Cm nfsv4 .El .Sh SEE ALSO .Xr nfsstat 1 , .Xr nmount 2 , .Xr unmount 2 , .Xr lagg 4 , .Xr nfsv4 4 , .Xr fstab 5 , .Xr gssd 8 , .Xr mount 8 , .Xr nfsd 8 , .Xr nfsiod 8 , .Xr rpc.tlsclntd 8 , .Xr showmount 8 .Sh HISTORY A version of the .Nm utility appeared in .Bx 4.4 . .Sh BUGS Since NFSv4 performs open/lock operations that have their ordering strictly enforced by the server, the options .Cm intr and .Cm soft cannot be safely used. For NFSv4 minor version 1 or 2 mounts, the ordering is done via session slots and the NFSv4 client now handles broken session slots fairly well. As such, if the .Cm nolockd option is used along with .Cm intr and/or .Cm soft , an NFSv4 minor version 1 or 2 mount should work fairly well, although still not completely correctly. For NFSv4 minor version 0 mounts, .Cm hard mounts without the .Cm intr mount option is strongly recommended. diff --git a/sbin/mount_nullfs/mount_nullfs.8 b/sbin/mount_nullfs/mount_nullfs.8 index 8638c25c0610..17b1f45f5e42 100644 --- a/sbin/mount_nullfs/mount_nullfs.8 +++ b/sbin/mount_nullfs/mount_nullfs.8 @@ -1,273 +1,273 @@ .\" .\" Copyright (c) 1992, 1993, 1994 .\" The Regents of the University of California. All rights reserved. .\" .\" This code is derived from software donated to Berkeley by .\" John Heidemann of the UCLA Ficus project. .\" .\" .\" 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 March 24, 2024 .Dt MOUNT_NULLFS 8 .Os .Sh NAME .Nm mount_nullfs .Nd "mount a loopback file system sub-tree; demonstrate the use of a null file system layer" .Sh SYNOPSIS .Nm .Op Fl o Ar options .Ar target .Ar mount-point .Sh DESCRIPTION The .Nm utility creates a -.Xr nullfs 5 +.Xr nullfs 4 layer, duplicating a sub-tree of the file system name space under another part of the global file system namespace. This allows existing files and directories to be accessed using a different pathname. .Pp The primary differences between a virtual copy of the file system and a symbolic link are that the .Xr getcwd 3 functions work correctly in the virtual copy, and that other file systems may be mounted on the virtual copy without affecting the original. A different device number for the virtual copy is returned by .Xr stat 2 , but in other respects it is indistinguishable from the original. .Pp The .Nm utility supports mounting both directories and single files. Both .Ar target and .Ar mount_point must be the same type. Mounting directories to files or files to directories is not supported. .Pp The .Nm file system differs from a traditional loopback file system in two respects: it is implemented using a stackable layers techniques, and its .Do null-node Dc Ns s stack above all lower-layer vnodes, not just over directory vnodes. .Pp The options are as follows: .Bl -tag -width indent .It Fl o Options are specified with a .Fl o flag followed by a comma separated string of options. See the .Xr mount 8 man page for possible options and their meanings. Additionally the following option is supported: .Bl -tag -width nocache .It Cm nocache Disable metadata caching in the null layer. Some lower-layer file systems may force this option. Depending on the access pattern, this may result in increased lock contention. .It Cm cache Force enable metadata caching. .El .El .Pp The .Dv vfs.nullfs.cache_vnodes sysctl specifies global default for mount-specific cache/nocache option. .Pp The null layer has two purposes. First, it serves as a demonstration of layering by providing a layer which does nothing. (It actually does everything the loopback file system does, which is slightly more than nothing.) Second, the null layer can serve as a prototype layer. Since it provides all necessary layer framework, new file system layers can be created very easily by starting with a null layer. .Pp The remainder of this man page examines the null layer as a basis for constructing new layers. .\" .\" .Sh INSTANTIATING NEW NULL LAYERS New null layers are created with .Nm . The .Nm utility takes two arguments, the pathname of the lower vfs (target-pn) and the pathname where the null layer will appear in the namespace (mount-point-pn). After the null layer is put into place, the contents of target-pn subtree will be aliased under mount-point-pn. .\" .\" .Sh OPERATION OF A NULL LAYER The null layer is the minimum file system layer, simply bypassing all possible operations to the lower layer for processing there. The majority of its activity centers on the bypass routine, through which nearly all vnode operations pass. .Pp The bypass routine accepts arbitrary vnode operations for handling by the lower layer. It begins by examining vnode operation arguments and replacing any null-nodes by their lower-layer equivalents. It then invokes the operation on the lower layer. Finally, it replaces the null-nodes in the arguments and, if a vnode is returned by the operation, stacks a null-node on top of the returned vnode. .Pp Although bypass handles most operations, .Em vop_getattr , .Em vop_inactive , .Em vop_reclaim , and .Em vop_print are not bypassed. .Em Vop_getattr must change the fsid being returned. .Em Vop_inactive and .Em vop_reclaim are not bypassed so that they can handle freeing null-layer specific data. .Em Vop_print is not bypassed to avoid excessive debugging information. .\" .\" .Sh INSTANTIATING VNODE STACKS Mounting associates the null layer with a lower layer, in effect stacking two VFSes. Vnode stacks are instead created on demand as files are accessed. .Pp The initial mount creates a single vnode stack for the root of the new null layer. All other vnode stacks are created as a result of vnode operations on this or other null vnode stacks. .Pp New vnode stacks come into existence as a result of an operation which returns a vnode. The bypass routine stacks a null-node above the new vnode before returning it to the caller. .Pp For example, imagine mounting a null layer with .Bd -literal -offset indent mount_nullfs /usr/include /dev/layer/null .Ed .Pp Changing directory to .Pa /dev/layer/null will assign the root null-node (which was created when the null layer was mounted). Now consider opening .Pa sys . A vop_lookup would be done on the root null-node. This operation would bypass through to the lower layer which would return a vnode representing the UFS .Pa sys . Null_bypass then builds a null-node aliasing the UFS .Pa sys and returns this to the caller. Later operations on the null-node .Pa sys will repeat this process when constructing other vnode stacks. .\" .\" .Sh CREATING OTHER FILE SYSTEM LAYERS One of the easiest ways to construct new file system layers is to make a copy of the null layer, rename all files and variables, and then begin modifying the copy. The .Xr sed 1 utility can be used to easily rename all variables. .Pp The umap layer is an example of a layer descended from the null layer. .\" .\" .Sh INVOKING OPERATIONS ON LOWER LAYERS There are two techniques to invoke operations on a lower layer when the operation cannot be completely bypassed. Each method is appropriate in different situations. In both cases, it is the responsibility of the aliasing layer to make the operation arguments "correct" for the lower layer by mapping a vnode argument to the lower layer. .Pp The first approach is to call the aliasing layer's bypass routine. This method is most suitable when you wish to invoke the operation currently being handled on the lower layer. It has the advantage that the bypass routine already must do argument mapping. An example of this is .Em null_getattrs in the null layer. .Pp A second approach is to directly invoke vnode operations on the lower layer with the .Em VOP_OPERATIONNAME interface. The advantage of this method is that it is easy to invoke arbitrary operations on the lower layer. The disadvantage is that vnode arguments must be manually mapped. .\" .\" .Sh SEE ALSO -.Xr nullfs 5 , +.Xr nullfs 4 , .Xr mount 8 .Pp UCLA Technical Report CSD-910056, .Em "Stackable Layers: an Architecture for File System Development" . .Sh HISTORY The .Nm mount_null utility first appeared in .Bx 4.4 . It was renamed to .Nm in .Fx 5.0 . diff --git a/sbin/reboot/reboot.8 b/sbin/reboot/reboot.8 index ed055327b36a..59cbd9de7519 100644 --- a/sbin/reboot/reboot.8 +++ b/sbin/reboot/reboot.8 @@ -1,228 +1,228 @@ .\" Copyright (c) 1990, 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 February 8, 2024 .Dt REBOOT 8 .Os .Sh NAME .Nm reboot , .Nm halt , .Nm fastboot , .Nm fasthalt .Nd stopping and restarting the system .Sh SYNOPSIS .Nm halt .Op Fl DflNnpq .Op Fl e Ar variable=value .Op Fl k Ar kernel .Op Fl o Ar options .Nm .Op Fl cDdflNnpqr .Op Fl e Ar variable=value .Op Fl k Ar kernel .Op Fl o Ar options .Nm fasthalt .Op Fl DflNnpq .Op Fl e Ar variable=value .Op Fl k Ar kernel .Op Fl o Ar options .Nm fastboot .Op Fl dDflNnpq .Op Fl e Ar variable=value .Op Fl k Ar kernel .Op Fl o Ar options .Sh DESCRIPTION The .Nm halt and .Nm utilities flush the file system cache to disk, send all running processes a .Dv SIGTERM (and subsequently a .Dv SIGKILL ) and, respectively, halt or restart the system. The action is logged, including entering a shutdown record into the user accounting database. .Pp The options are as follows: .Bl -tag -width indent .It Fl c The system will turn off the power and then turn it back on if it can. If the power down action fails, the system will halt or reboot normally, depending on whether .Nm halt or .Nm was called. At the present time, only the .Xr ipmi 4 driver implements the power cycle functionality and only on hardware with a BMC that supports power cycling. Unlike power off, the amount of hardware that supports power cycling is small. .It Fl D Delete existing .Nm nextboot configuration and exit. .It Fl d The system is requested to create a crash dump. This option is supported only when rebooting, and it has no effect unless a dump device has previously been specified with .Xr dumpon 8 . .It Fl e Ar variable=value Sets .Va variable to .Va value in the loader's and kernel's environment. If .Va value is not already enclosed in double quotes, they will be added before writing to the .Nm nextboot configuration. Care should be taken if .Va value contains any characters that are special to the shell or loader's configuration parsing code. .It Fl k Ar kname Boot the specified kernel .Ar kname on the next system boot. This is a one-shot option, the .Em default kernel will be booted on successive boots. No .Nm reboot or .Nm halt will be performed if .Em /boot/kname/kernel does not exist unless the .Fl f flag is specified. .It Fl l The halt or reboot is .Em not logged to the system log. This option is intended for applications such as .Xr shutdown 8 , that call .Nm or .Nm halt and log this themselves. .It Fl N The file system cache is not flushed during the initial process clean-up, however the kernel level .Xr reboot 2 is still processed with a sync. This option can be useful for performing a .Dq best-effort reboot when devices might be unavailable. This can happen when devices have been disconnected, such as with .Xr iscsi 4 . .It Fl n The file system cache is not flushed. This option should probably not be used. .It Fl o Ar options This option allows the passing of kernel flags for the next boot. .It Fl p The system will turn off the power if it can. If the power down action fails, the system will halt or reboot normally, depending on whether .Nm halt or .Nm was called. .It Fl q The system is halted or restarted quickly and ungracefully, and only the flushing of the file system cache is performed (if the .Fl n option is not specified). This option should probably not be used. .It Fl r The system kills all processes, unmounts all filesystems, mounts the new root filesystem, and begins the usual startup sequence. After changing vfs.root.mountfrom with .Xr kenv 1 , .Nm Fl r can be used to change the root filesystem while preserving kernel state. This requires the -.Xr tmpfs 5 +.Xr tmpfs 4 kernel module to be loaded because .Xr init 8 needs a place to store itself after the old root is unmounted, but before the new root is in place. .El .Pp The .Nm fasthalt and .Nm fastboot utilities are nothing more than aliases for the .Nm halt and .Nm utilities. .Pp Normally, the .Xr shutdown 8 utility is used when the system needs to be halted or restarted, giving users advance warning of their impending doom and cleanly terminating specific programs. .Sh EXAMPLES Replace current root filesystem with UFS mounted from .Pa /dev/ada0s1a : .Bd -literal -offset indent kenv vfs.root.mountfrom=ufs:/dev/ada0s1a reboot -r .Ed .Pp This mechanism can also be used with NFS, with a caveat that it only works with NFSv4, and requires a numeric IPv4 address: .Bd -literal -offset indent kenv vfs.root.mountfrom=nfs:192.168.1.1:/share/name reboot -r .Ed .Sh SEE ALSO .Xr kenv 1 , .Xr getutxent 3 , .Xr ipmi 4 , .Xr boot 8 , .Xr dumpon 8 , .Xr nextboot 8 , .Xr savecore 8 , .Xr shutdown 8 , .Xr sync 8 .Sh HISTORY A .Nm utility appeared in .Bx 4.0 . diff --git a/sbin/tunefs/tunefs.8 b/sbin/tunefs/tunefs.8 index 97de1abf33c0..0fb11041d97d 100644 --- a/sbin/tunefs/tunefs.8 +++ b/sbin/tunefs/tunefs.8 @@ -1,249 +1,249 @@ .\" 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. .\" .Dd November 17, 2023 .Dt TUNEFS 8 .Os .Sh NAME .Nm tunefs .Nd tune up an existing UFS file system .Sh SYNOPSIS .Nm .Op Fl A .Op Fl a Cm enable | disable .Op Fl e Ar maxbpg .Op Fl f Ar avgfilesize .Op Fl j Cm enable | disable .Op Fl J Cm enable | disable .Op Fl k Ar held-for-metadata-blocks .Op Fl L Ar volname .Op Fl l Cm enable | disable .Op Fl m Ar minfree .Op Fl N Cm enable | disable .Op Fl n Cm enable | disable .Op Fl o Cm space | time .Op Fl p .Op Fl s Ar avgfpdir .Op Fl S Ar size .Op Fl t Cm enable | disable .Ar special | filesystem .Sh DESCRIPTION The .Nm utility is designed to change the dynamic parameters of a UFS file system which affect the layout policies. The .Nm utility cannot be run on an active file system. To change an active file system, it must be downgraded to read-only or unmounted. .Pp The parameters which are to be changed are indicated by the flags given below: .Bl -tag -width indent .It Fl A The file system has several backups of the super-block. Specifying this option will cause all backups to be modified as well as the primary super-block. This is potentially dangerous - use with caution. .It Fl a Cm enable | disable Turn on/off the administrative POSIX.1e ACL enable flag. .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. Typically this value is set to about one quarter of the total blocks in a cylinder group. The intent is to prevent any single file from using up all the blocks in a single cylinder group, thus degrading access times for all files subsequently allocated in that cylinder group. The effect of this limit is to cause big files to do long seeks more frequently than if they were allowed to allocate all the blocks in a cylinder group before seeking elsewhere. For file systems with exclusively large files, this parameter should be set higher. .It Fl f Ar avgfilesize Specify the expected average file size. .It Fl j Cm enable | disable Turn on/off soft updates journaling. .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 J Cm enable | disable Turn on/off gjournal flag. .It Fl k Ar held-for-metadata-blocks Set the amount of space to be held for metadata blocks. 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 . While this option can be set at any time, it is most effective if set before any data is loaded into the file system. By default .Xr newfs 8 sets it to half of the space reserved to minfree. .It Fl L Ar volname Add/modify an optional file system volume label. Legal characters are alphanumerics, dashes, and underscores. .It Fl l Cm enable | disable Turn on/off MAC multilabel flag. .It Fl m Ar minfree Specify the percentage of space held back from normal users; the minimum free space threshold. The default value used is 8%. Note that lowering the threshold can adversely affect performance: .Bl -bullet .It Settings of 5% and less force space optimization to always be used which will greatly increase the overhead for file writes. .It The file system's ability to avoid fragmentation will be reduced when the total free space, including the reserve, drops below 15%. As free space approaches zero, throughput can degrade by up to a factor of three over the performance obtained at a 10% threshold. .El .Pp If the value is raised above the current usage level, users will be unable to allocate files until enough files have been deleted to get under the higher threshold. .It Fl N Cm enable | disable Turn on/off the administrative NFSv4 ACL enable flag. .It Fl n Cm enable | disable Turn on/off soft updates. .It Fl o Cm space | time The file system can either try to minimize the time spent allocating blocks, or it can attempt to minimize the space fragmentation on the disk. Optimization for space has much higher overhead for file writes. The kernel normally changes the preference automatically as the percent fragmentation changes on the file system. .It Fl p Show a summary of what the current tunable settings are on the selected file system. More detailed information can be obtained from the .Xr dumpfs 8 utility. .It Fl s Ar avgfpdir Specify the expected number of files per directory. .It Fl S Ar size Specify the softdep journal size in bytes. The minimum is 4M. .It Fl t Cm enable | disable Turn on/off 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 when the underlying device uses flash-memory as the device can use the delete command to pre-zero or at least avoid copying blocks that have been deleted. .Pp Note that this does not trim blocks that are already free. See the .Xr fsck_ffs 8 .Fl E flag. .El .Pp At least one of these flags is required. .Sh FILES .Bl -tag -width ".Pa /etc/fstab" .It Pa /etc/fstab read this to determine the device file for a specified mount point. .El .Sh SEE ALSO +.Xr ffs 4 , .Xr fs 5 , -.Xr ffs 7 , .Xr tuning 7 , .Xr dumpfs 8 , .Xr gjournal 8 , .Xr growfs 8 , .Xr newfs 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" .%N 3 .%P pp 181-197 .%D August 1984 .%O "(reprinted in the BSD System Manager's Manual, SMM:5)" .Re .Sh HISTORY The .Nm utility appeared in .Bx 4.2 . .Sh BUGS This utility does not work on active file systems. To change the root file system, the system must be rebooted after the file system is tuned. .\" Take this out and a Unix Daemon will dog your steps from now until .\" the time_t's wrap around. .Pp You can tune a file system, but you cannot tune a fish. diff --git a/share/man/man3/makedev.3 b/share/man/man3/makedev.3 index 4cf851f87508..3c0e176a0621 100644 --- a/share/man/man3/makedev.3 +++ b/share/man/man3/makedev.3 @@ -1,100 +1,100 @@ .\" 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. .\" .Dd August 3, 2017 .Dt MAKEDEV 3 .Os .Sh NAME .Nm makedev , .Nm major , .Nm minor .Nd device number conversion .Sh SYNOPSIS .In sys/types.h .Ft dev_t .Fn makedev "int major" "int minor" .Ft int .Fn major "dev_t dev" .Ft int .Fn minor "dev_t dev" .Sh DESCRIPTION The .Fn makedev macro returns a device number created from the provided .Fa major and .Fa minor number. The .Fn major and .Fn minor macros return the original numbers from the device number .Fa dev . In other words, for a value .Va dev of the type .Vt dev_t , and values .Va ma , mi of the type .Vt int , the assertions .Dl dev == makedev(major(dev), minor(dev)) .Dl ma == major(makedev(ma, mi)) .Dl mi == minor(makedev(ma, mi)) are valid. .Pp In previous implementations of .Fx all block and character devices were uniquely identified by a pair of stable major and minor numbers. The major number referred to a certain device class (e.g. disks, TTYs) while the minor number identified an instance within the device class. Later versions of .Fx automatically generate a unique device number for each character device visible in .Pa /dev/ . These numbers are not divided in device classes and are not guaranteed to be stable upon reboot or driver reload. .Pp On .Fx these macros are only used by utilities that need to exchange numbers with other operating systems that may use different encodings for .Vt dev_t , but also applications that present these numbers to the user in a more conventional way. .Sh RETURN VALUES The .Fn major and .Fn minor macros return numbers whose value can span the complete range of an .Vt int . .Sh SEE ALSO .Xr mknod 2 , .Xr devname 3 , -.Xr devfs 5 +.Xr devfs 4 diff --git a/share/man/man4/cd.4 b/share/man/man4/cd.4 index 7c3fa6ed9850..b05e486af6b6 100644 --- a/share/man/man4/cd.4 +++ b/share/man/man4/cd.4 @@ -1,361 +1,361 @@ .\" 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 cd9660 4 , .Xr cam 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/devfs.4 b/share/man/man4/devfs.4 index c90835570127..3022a23dfe9a 100644 --- a/share/man/man4/devfs.4 +++ b/share/man/man4/devfs.4 @@ -1,147 +1,147 @@ .\" Copyright (c) 1996 .\" Mike Pritchard . All rights reserved. .\" .\" Copyright (c) 1992, 1993, 1994 .\" The Regents of the University of California. All rights reserved. .\" 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 June 30, 2022 .Dt DEVFS 4 .Os .Sh NAME .Nm devfs .Nd device file system .Sh SYNOPSIS .Bd -literal devfs /dev devfs rw 0 0 .Ed .Sh DESCRIPTION The device file system, or .Nm , provides access to kernel's device namespace in the global file system namespace. The conventional mount point is .Pa /dev . .Pp The file system includes several directories, links, symbolic links and devices, some of which can also be written. In a chroot'ed environment, .Xr devfs 8 can be used to create a new .Pa /dev mount point. .Pp The .Xr mknod 8 tool can be used to recover deleted device entries under .Nm . .Pp The -.Xr fdescfs 5 +.Xr fdescfs 4 filesystem is an alternate means for populating .Pa /dev/fd . The character devices that both .Nm and -.Xr fdescfs 5 +.Xr fdescfs 4 present in .Pa /dev/fd correspond to the open file descriptors of the process accessing the directory. .Nm only creates files for the standard file descriptors .Pa 0 , .Pa 1 and .Pa 2 . -.Xr fdescfs 5 +.Xr fdescfs 4 creates files for all open descriptors. .Pp The options are as follows: .Bl -tag -width indent .It Fl o Ar options Use the specified mount .Ar options , as described in .Xr mount 8 . The following devfs file system-specific options are available: .Bl -tag -width indent .It Cm ruleset Ns No = Ns Ar ruleset Set ruleset number .Ar ruleset as the current ruleset for the mount-point and apply all its rules. If the ruleset number .Ar ruleset does not exist, an empty ruleset with the number .Ar ruleset is created. See .Xr devfs 8 for more information on working with devfs rulesets. .El .El .Sh FILES .Bl -tag -width /dev/XXXX -compact .It Pa /dev The normal .Nm mount point. .El .Sh EXAMPLES To mount a .Nm volume located on .Pa /mychroot/dev : .Pp .Dl "mount -t devfs devfs /mychroot/dev" .Sh SEE ALSO -.Xr fdescfs 5 , +.Xr fdescfs 4 , .Xr devfs 8 , .Xr mount 8 , .Xr make_dev 9 .Sh HISTORY The .Nm file system first appeared in .Fx 2.0 . It became the preferred method for accessing devices in .Fx 5.0 and the only method in .Fx 6.0 . The .Nm manual page first appeared in .Fx 2.2 . .Sh AUTHORS The .Nm manual page was written by .An Mike Pritchard Aq Mt mpp@FreeBSD.org . diff --git a/share/man/man4/fd.4 b/share/man/man4/fd.4 index f91c0e0501fb..06cc12d25696 100644 --- a/share/man/man4/fd.4 +++ b/share/man/man4/fd.4 @@ -1,98 +1,98 @@ .\" Copyright (c) 1990, 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 June 9, 1993 .Dt FD 4 .Os .Sh NAME .Nm fd , .Nm stdin , .Nm stdout , .Nm stderr .Nd file descriptor files .Sh DESCRIPTION The files .Pa /dev/fd/0 through .Pa /dev/fd/# refer to file descriptors which can be accessed through the file system. If the file descriptor is open and the mode the file is being opened with is a subset of the mode of the existing descriptor, the call: .Bd -literal -offset indent fd = open("/dev/fd/0", mode); .Ed .Pp and the call: .Bd -literal -offset indent fd = fcntl(0, F_DUPFD, 0); .Ed .Pp are equivalent. .Pp Opening the files .Pa /dev/stdin , .Pa /dev/stdout and .Pa /dev/stderr is equivalent to the following calls: .Bd -literal -offset indent fd = fcntl(STDIN_FILENO, F_DUPFD, 0); fd = fcntl(STDOUT_FILENO, F_DUPFD, 0); fd = fcntl(STDERR_FILENO, F_DUPFD, 0); .Ed .Pp Flags to the .Xr open 2 call other than .Dv O_RDONLY , .Dv O_WRONLY and .Dv O_RDWR are ignored. .Sh IMPLEMENTATION NOTES By default, .Pa /dev/fd is provided by -.Xr devfs 5 , +.Xr devfs 4 , which provides nodes for the first three file descriptors. Some sites may require nodes for additional file descriptors; these can be made available by mounting -.Xr fdescfs 5 +.Xr fdescfs 4 on .Pa /dev/fd . .Sh FILES .Bl -tag -width /dev/stderr -compact .It Pa /dev/fd/# .It Pa /dev/stdin .It Pa /dev/stdout .It Pa /dev/stderr .El .Sh SEE ALSO -.Xr tty 4 , -.Xr devfs 5 , -.Xr fdescfs 5 +.Xr devfs 4 , +.Xr fdescfs 4 , +.Xr tty 4 diff --git a/share/man/man4/fdescfs.4 b/share/man/man4/fdescfs.4 index 4b51c2bad369..b050f024ac40 100644 --- a/share/man/man4/fdescfs.4 +++ b/share/man/man4/fdescfs.4 @@ -1,218 +1,218 @@ .\" Copyright (c) 2021 The FreeBSD Foundation, Inc. .\" .\" Copyright (c) 1996 .\" Mike Pritchard . All rights reserved. .\" .\" Copyright (c) 1992, 1993, 1994 .\" The Regents of the University of California. All rights reserved. .\" All rights reserved. .\" .\" This code is derived from software donated to Berkeley by .\" Jan-Simon Pendry. .\" .\" Parts 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. .\" 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 Jul 11, 2023 .Dt FDESCFS 4 .Os .Sh NAME .Nm fdescfs .Nd file-descriptor file system .Sh SYNOPSIS .Bd -literal fdescfs /dev/fd fdescfs rw 0 0 .Ed .Sh DESCRIPTION The file-descriptor file system, or .Nm , provides access to the per-process file descriptor namespace in the global file system namespace. The conventional mount point is .Pa /dev/fd . .Pp The file system's contents appear as a list of numbered files which correspond to the open files of the process reading the directory. The files .Pa /dev/fd/0 through .Pa /dev/fd/# refer to file descriptors which can be accessed through the file system. .Pp The following mount options can be used when mounting .Nm filesystem: .Bl -tag -width linrdlnk .It Cm nodup For file descriptors referencing vnodes, instead of the .Xr dup 2 semantic described above, implement re-opening of the referenced vnode. See below for more details. .It Cm linrdlnk Report the type of the .Nm vnode as .Dv VLNK instead of .Fx traditional .Dv VCHR . For .Xr linux 4 ABI compatibility mount .Nm volume with the .Cm linrdlnk option. .It Cm rdlnk Treat .Nm vnodes as symbolic links consistently, in particular, follow the resolved name for the name lookups. This option is strictly stronger than the .Cm linrdlnk option, it changes not only the type returned by .Xr stat 2 , but also causes the .Nm files to behave as symlinks. .El .Pp For .Nm mounted without the .Cm nodup mount option, if the file descriptor is open and the mode the file is being opened with is a subset of the mode of the existing descriptor, the call: .Bd -literal -offset indent fd = open("/dev/fd/0", mode); .Ed .Pp and the call: .Bd -literal -offset indent fd = fcntl(0, F_DUPFD, 0); .Ed .Pp are equivalent. Flags to the .Xr open 2 call other than .Dv O_RDONLY , .Dv O_WRONLY and .Dv O_RDWR are ignored. .Pp For .Nm mounted with the .Cm nodup option, and file descriptor referencing a vnode, the call: .Bd -literal -offset indent fd = open("/dev/fd/0", mode); .Ed .Pp reopens the referenced vnode with the specified .Fa mode . In other words, the .Fn open call above is equivalent to .Bd -literal -offset indent fd = openat(0, "", O_EMPTY_PATH, mode); .Ed .Pp In particular, if the file descriptor was opened with the .Dv O_PATH flag, then either .Dv O_EMPTY_PATH or .Fn open over .Nm mount with .Cm nodup option allows one to convert it to a regularly opened file, assuming that the current permissions allow the requested .Fa mode . .Pp .Em "Note:" .Pa /dev/fd/0 , .Pa /dev/fd/1 and .Pa /dev/fd/2 files are created by default when devfs alone is mounted. .Nm creates entries for all file descriptors opened by the process. .Sh FILES .Bl -tag -width /dev/stderr -compact .It Pa /dev/fd/# .El .Sh EXAMPLES To mount a .Nm volume located on .Pa /dev/fd : .Pp .Dl "mount -t fdescfs none /dev/fd" .Pp For .Xr linux 4 ABI compatibility: .Pp .Dl "mount -t fdescfs -o linrdlnk none /compat/linux/dev/fd" .Pp For substitute of .Dv O_EMPTY_PATH flag use: .Pp .Dl "mount -t fdescfs -o nodup none /dev/fdpath" .Sh SEE ALSO -.Xr devfs 5 , +.Xr devfs 4 , .Xr mount 8 .Sh HISTORY The .Nm file system first appeared in .Bx 4.4 . The .Nm manual page first appeared in .Fx 2.2 . .Sh AUTHORS .An -nosplit The .Nm manual page was written by .An Mike Pritchard Aq Mt mpp@FreeBSD.org , and was based on the manual page written by .An Jan-Simon Pendry . diff --git a/share/man/man4/intro.4 b/share/man/man4/intro.4 index 9b22e89ff6c3..e4caf6690efb 100644 --- a/share/man/man4/intro.4 +++ b/share/man/man4/intro.4 @@ -1,216 +1,216 @@ .\" .\" Copyright (c) 1996 David E. O'Brien, Joerg Wunsch .\" Copyright (c) 2019 Andrew Gierth .\" .\" 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 April 3, 2019 .Dt INTRO 4 .Os .Sh NAME .Nm intro .Nd introduction to devices and device drivers .Sh DESCRIPTION This section contains information related to devices, device drivers and miscellaneous hardware. .Ss The device abstraction Device is a term used mostly for hardware-related stuff that belongs to the system, like disks, printers, or a graphics display with its keyboard. There are also so-called .Em pseudo-devices where a device driver emulates the behaviour of a device in software without any particular underlying hardware. A typical example for the latter class is .Pa /dev/mem , a mechanism whereby the physical memory can be accessed using file access semantics. .Pp The device abstraction generally provides a common set of system calls, which are dispatched to the corresponding device driver by the upper layers of the kernel. The set of system calls available for devices is chosen from .Xr open 2 , .Xr close 2 , .Xr read 2 , .Xr write 2 , .Xr ioctl 2 , .Xr select 2 , and .Xr mmap 2 . Not all drivers implement all system calls; for example, calling .Xr mmap 2 on a keyboard device is not likely to be useful. .Pp Aspects of the device abstraction have changed significantly in .Fx over the past two decades. The section .Sx Historical Notes describes some of the more important differences. .Ss Accessing Devices Most of the devices in .Fx are accessed through .Em device nodes , sometimes also called .Em special files . They are located within instances of the -.Xr devfs 5 +.Xr devfs 4 filesystem, which is conventionally mounted on the directory .Pa /dev in the file system hierarchy (see also .Xr hier 7 ) . .Pp The -.Xr devfs 5 +.Xr devfs 4 filesystem creates or removes device nodes automatically according to the physical hardware recognized as present at any given time. For pseudo-devices, device nodes may be created and removed dynamically as required, depending on the nature of the device. .Pp Access restrictions to device nodes are usually subject to the regular file permissions of the device node entry, instead of being enforced directly by the drivers in the kernel. But since device nodes are not stored persistently between reboots, those file permissions are set at boot time from rules specified in .Xr devfs.conf 5 , or dynamically according to rules defined in .Xr devfs.rules 5 or set using the .Xr devfs 8 command. In the latter case, different rules may be used to make different sets of devices visible within different instances of the -.Xr devfs 5 +.Xr devfs 4 filesystem, which may be used, for example, to prevent jailed subsystems from accessing unsafe devices. Manual changes to device node permissions may still be made, but will not persist. .Ss Drivers without device nodes Drivers for network devices do not use device nodes in order to be accessed. Their selection is based on other decisions inside the kernel, and instead of calling .Xr open 2 , use of a network device is generally introduced by using the system call .Xr socket 2 . .Ss Configuring a driver into the kernel For each kernel, there is a configuration file that is used as a base to select the facilities and drivers for that kernel, and to tune several options. See .Xr config 8 for a detailed description of the files involved. The individual manual pages in this section provide a sample line for the configuration file in their synopsis portions. See also the files .Pa /usr/src/sys/conf/NOTES and .Pa /usr/src/sys/${ARCH}/conf/NOTES . .Pp Drivers need not be statically compiled into the kernel; they may also be loaded as modules, in which case any device nodes they provide will appear only after the module is loaded (and has attached to suitable hardware, if applicable). .Ss Historical Notes Prior to .Fx 6.0 , device nodes could be created in the traditional way as persistent entries in the file system. While such entries can still be created, they no longer function to access devices. .Pp Prior to .Fx 5.0 , devices for disk and tape drives existed in two variants, known as .Em block and .Em character devices, or to use better terms, buffered and unbuffered (raw) devices. The traditional names are reflected by the letters .Dq Li b and .Dq Li c as the file type identification in the output of .Dq Li ls -l . Raw devices were traditionally named with a prefix of .Dq Li r , for example .Pa /dev/rda0 would denote the raw version of the disk whose buffered device was .Pa /dev/da0 . .Em This is no longer the case ; all disk devices are now .Dq raw in the traditional sense, even though they are not given .Dq Li r prefixes, and .Dq buffered devices no longer exist at all. .Pp Buffered devices were accessed through a buffer cache maintained by the operating system; historically this was the system's primary disk cache, but in .Fx this was rendered obsolete by the introduction of unified virtual memory management. Buffered devices could be read or written at any byte position, with the buffer mechanism handling the reading and writing of disk blocks. In contrast, raw disk devices can be read or written only at positions and lengths that are multiples of the underlying device block size, and .Xr write 2 calls are .Em synchronous , not returning to the caller until the data has been handed off to the device. .Sh SEE ALSO .Xr close 2 , .Xr ioctl 2 , .Xr mmap 2 , .Xr open 2 , .Xr read 2 , .Xr select 2 , .Xr socket 2 , .Xr write 2 , -.Xr devfs 5 , +.Xr devfs 4 , .Xr hier 7 , .Xr config 8 .Sh HISTORY This manual page first appeared in .Fx 2.1 . .Sh AUTHORS .An -nosplit This man page has been rewritten by .An Andrew Gierth from an earlier version written by .An J\(:org Wunsch with initial input by .An David E. O'Brien . diff --git a/share/man/man4/kld.4 b/share/man/man4/kld.4 index bba32f02e677..e0186dec9ccc 100644 --- a/share/man/man4/kld.4 +++ b/share/man/man4/kld.4 @@ -1,171 +1,171 @@ .\" Copyright (c) 1993 Christopher G. Demetriou .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .Dd January 13, 2014 .Dt KLD 4 .Os .Sh NAME .Nm kld .Nd dynamic kernel linker facility .Sh DESCRIPTION The LKM (Loadable Kernel Modules) facility has been deprecated in .Fx 3.0 and above in favor of the .Nm interface. This interface, like its predecessor, allows the system administrator to dynamically add and remove functionality from a running system. This ability also helps software developers to develop new parts of the kernel without constantly rebooting to test their changes. .Pp Various types of modules can be loaded into the system. There are several defined module types, listed below, which can be added to the system in a predefined way. In addition, there is a generic type, for which the module itself handles loading and unloading. .Pp The .Fx system makes extensive use of loadable kernel modules, and provides loadable versions of most file systems, the .Tn NFS client and server, all the screen-savers, and the .Tn Linux emulator. .Nm modules are placed by default in the .Pa /boot/kernel directory along with their matching kernel. .Pp The .Nm interface is used through the .Xr kldload 8 , .Xr kldunload 8 and .Xr kldstat 8 programs. .Pp The .Xr kldload 8 program can load either .Xr a.out 5 or ELF formatted loadable modules. The .Xr kldunload 8 program unloads any given loaded module, if no other module is dependent upon the given module. The .Xr kldstat 8 program is used to check the status of the modules currently loaded into the system. .Pp Kernel modules may only be loaded or unloaded if the system security level .Va kern.securelevel is less than one. .Sh "MODULE TYPES" .Bl -ohang .It Em "Device Driver modules" New block and character device drivers may be loaded into the system with .Nm . Device nodes for the loaded drivers are automatically created when a module is loaded and destroyed when it is unloaded by -.Xr devfs 5 . +.Xr devfs 4 . You can specify userland programs that will run when new devices become available as a result of loading modules, or existing devices go away when modules are unloaded, by configuring .Xr devd 8 . .El .Sh FILES .Bl -tag -width /usr/include/sys/module.h -compact .It Pa /boot/kernel directory containing module binaries built for the kernel also residing in the directory. .It Pa /usr/include/sys/module.h file containing definitions required to compile a .Nm module .It Pa /usr/share/examples/kld example source code implementing a sample kld module .El .Sh SEE ALSO .Xr kldfind 2 , .Xr kldfirstmod 2 , .Xr kldload 2 , .Xr kldnext 2 , .Xr kldstat 2 , .Xr kldunload 2 , -.Xr devfs 5 , +.Xr devfs 4 , .Xr devd 8 , .Xr kldload 8 , .Xr kldstat 8 , .Xr kldunload 8 , .Xr sysctl 8 .Sh HISTORY The .Nm facility appeared in .Fx 3.0 and was designed as a replacement for the .Nm lkm facility, which was similar in functionality to the loadable kernel modules facility provided by .Tn SunOS 4.1.3. .Sh AUTHORS The .Nm facility was originally implemented by .An Doug Rabson Aq Mt dfr@FreeBSD.org . .Sh BUGS If a module B, is dependent on another module A, but is not compiled with module A as a dependency, then .Xr kldload 8 fails to load module B, even if module A is already present in the system. .Pp If multiple modules are dependent on module A, and are compiled with module A as a dependency, then .Xr kldload 8 loads an instance of module A when any of the modules are loaded. .Pp If a custom entry point is used for a module, and the module is compiled as an .Sq ELF binary, then .Xr kldload 8 fails to execute the entry point. .Pp .Xr kldload 8 points the user to read .Xr dmesg 8 for any error encountered while loading a module. .Pp When system internal interfaces change, old modules often cannot detect this, and such modules when loaded will often cause crashes or mysterious failures. diff --git a/share/man/man4/lindebugfs.4 b/share/man/man4/lindebugfs.4 index d78a12c44714..25a398a93f22 100644 --- a/share/man/man4/lindebugfs.4 +++ b/share/man/man4/lindebugfs.4 @@ -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 4 .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 linprocfs 4 , +.Xr linsysfs 4 , .Xr pseudofs 9 , .Xr linux 4 , .Xr mount 1 .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/man4/linsysfs.4 b/share/man/man4/linsysfs.4 index 64270fe753d4..12729a814085 100644 --- a/share/man/man4/linsysfs.4 +++ b/share/man/man4/linsysfs.4 @@ -1,98 +1,98 @@ .\" Written by Garrett Wollman .\" This file is in the public domain. .\" .Dd November 13, 2019 .Dt LINSYSFS 4 .Os .Sh NAME .Nm linsysfs .Nd Linux kernel objects file system .Sh SYNOPSIS .Bd -literal linsys /compat/linux/sys linsysfs rw 0 0 .Ed .Sh DESCRIPTION The .Tn Linux system file system, or .Nm , emulates a subset of the .Tn Linux sys file system and is required for the complete operation of some .Tn Linux binaries. .Pp The .Nm provides a two-level view of devices. At the highest level, PCI devices themselves are named, according to their bus, slot and function in the system hierarchy. PCI storage devices are listed in the .Pa scsi_host class with a device symlink to the PCI directories of the devices. .Pp Each device node is a directory containing some files and directories: .Bl -tag -width ".Pa status" .It Pa host A place holder for storage host information. .It Pa pci_id A directory for the .Pa pci_id that contains either the device information or another directory structure for a PCI bridge. .El .Pp Each host node of scsi_host is a directory containing some files and directories: .Bl -tag -width ".Pa proc_name" .It Pa proc_name The .Tn Linux registered driver name for these devices. .It Pa device A symlink to the PCI device directory. .El .Sh FILES .Bl -tag -width ".Pa /compat/linux/sys/devices/pci0000:00" -compact .It Pa /compat/linux/sys The normal mount point for .Nm . .It Pa /compat/linux/sys/class/scsi_host The storage host node. .It Pa /compat/linux/sys/devices/pci0000:00 The PCI device hierarchy node. .El .Sh EXAMPLES The most common usage follows: .Pp .Dl "mount -t linsysfs linsys /compat/linux/sys" .Pp where .Pa /compat/linux/sys is a mount point. .Sh SEE ALSO .Xr nmount 2 , .Xr unmount 2 , +.Xr linprocfs 4 , .Xr linux 4 , -.Xr linprocfs 5 , .Xr pseudofs 9 .Sh HISTORY The .Nm driver first appeared in .Fx 6.2 . .Sh AUTHORS .An -nosplit The .Nm driver was derived from .Nm linprocfs by .An Doug Ambrisko . This manual page was edited by .An Doug Ambrisko , based on the -.Xr linprocfs 5 +.Xr linprocfs 4 manual page by .An Garrett Wollman . diff --git a/share/man/man4/linux.4 b/share/man/man4/linux.4 index 0efc469985f9..a50e1513ba43 100644 --- a/share/man/man4/linux.4 +++ b/share/man/man4/linux.4 @@ -1,192 +1,192 @@ .\" Copyright (c) 2000 Sheldon Hearn .\" 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 9, 2022 .Dt LINUX 4 .Os .Sh NAME .Nm linux .Nd Linux ABI support .Sh SYNOPSIS To enable the Linux ABI at boot time, place the following line in .Xr rc.conf 5 : .Bd -literal -offset indent linux_enable="YES" .Ed .Sh DESCRIPTION The .Nm kernel module provides limited Linux ABI (application binary interface) compatibility, making it possible to run many unmodified Linux applications without the need for virtualization or emulation. Some of the facilities provided are: .Bl -bullet .It Linux to native system call translation .It Linux-specific system calls .It Special signal handling for Linux processes .It Path translation mechanism .It Linux-specific virtual file systems .El .Pp The path translation mechanism makes Linux processes look up file paths under .Va emul_path (defaulting to .Pa /compat/linux ) before .Pa / . For example, when Linux process attempts to open .Pa /etc/passwd , it will really access .Pa /compat/linux/etc/passwd , unless the latter does not exist. This is used to make sure Linux processes load Linux shared libraries instead of their similarly-named FreeBSD counterparts, and also to provide alternative versions of certain other files and virtual file systems. .Pp To install Linux shared libraries and system files into .Pa /compat/linux , either use the .Pa emulators/linux_base-c7 port or package, or .Xr debootstrap 8 installed from .Pa sysutils/debootstrap . .Pp To avoid mounting Linux-specific filesystems at startup, add the following line to the .Xr rc.conf 5 file: .Pp .Dl linux_mounts_enable="NO" .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 compat.linux.debug Enable debugging messages. Set to 0 to silence them. Defaults to 3. A setting of 1 prints debug messages, tells about unimplemented stuff (only once). Set to 2 is like 1, but also prints messages about implemented but not tested stuff (only once). Setting it to 3 or higher is like 2, but no rate limiting of messages. .It Va compat.linux.default_openfiles Default soft openfiles resource limit for Linux applications. Set to -1 to disable the limit. Defaults to 1024. .It Va compat.linux.emul_path Path to the Linux run-time environment. Defaults to .Pa /compat/linux . .It Va compat.linux.osname Linux kernel operating system name. Defaults to "Linux". .It Va compat.linux.osrelease Linux kernel operating system release. Changing this to something else is discouraged on non-development systems, because it may change the way Linux programs work. Some versions of GNU libc are known to use different syscalls depending on the value of this sysctl. .It Va compat.linux.oss_version Linux Open Sound System version. Defaults to 198144. .It Va compat.linux.preserve_vstatus When set to 1, it prevents Linux applications from resetting the .Xr termios 4 VSTATUS setting. From a user perspective, this makes .Va SIGINFO work for Linux executables. Defaults to 1. .It Va compat.linux.setid_allowed Enable handling of set-user-ID and set-group-ID mode bits for the new process image file when image is to be executed under Linux ABI. When set to 0, new Linux images always use credentials of the program that issued the .Xr execve 2 call, regardless of the image file mode. This might be reasonable or even required, because .Fx does not emulate the Linux environment completely, and missed features may result in security vulnerabilities. Defaults to 1. .It Va compat.linux32.emulate_i386 In the x86_64 (amd64) world enable the real i386 Linuxulator behavior. For example, when set to 0, Linux uname -m will return "x86_64" even if uname itself is a i386 Linux executable. When set to 1, Linux i386 uname -m will return "i686". Defaults to 0. .El .Sh FILES .Bl -tag -width /compat/linux/dev/shm -compact .It Pa /compat/linux Linux run-time environment .It Pa /compat/linux/dev device file system, see -.Xr devfs 5 +.Xr devfs 4 .It Pa /compat/linux/dev/fd file descriptor file system mounted with the .Cm linrdlnk option, see -.Xr fdescfs 5 +.Xr fdescfs 4 .It Pa /compat/linux/dev/shm in-memory file system, see -.Xr tmpfs 5 +.Xr tmpfs 4 .It Pa /compat/linux/proc Linux process file system, see -.Xr linprocfs 5 +.Xr linprocfs 4 .It Pa /compat/linux/sys Linux kernel objects file system, see -.Xr linsysfs 5 +.Xr linsysfs 4 .El .Sh SEE ALSO .Xr brandelf 1 , +.Xr fdescfs 4 , +.Xr linprocfs 4 , +.Xr linsysfs 4 , .Xr pty 4 , -.Xr elf 5 , -.Xr fdescfs 5 , -.Xr linprocfs 5 , -.Xr linsysfs 5 , -.Xr tmpfs 5 +.Xr tmpfs 4 , +.Xr elf 5 .Sh HISTORY Linux ABI support first appeared for i386 in .Fx 2.1 . Support for amd64 binaries first appeared in .Fx 10.3 . Support for arm64 binaries first appeared in .Fx 12.0 . .Sh BUGS Support for some of the Linux-specific system calls and system call arguments is missing. diff --git a/share/man/man4/mlx5io.4 b/share/man/man4/mlx5io.4 index 66a767d97d31..ebfbb41a0823 100644 --- a/share/man/man4/mlx5io.4 +++ b/share/man/man4/mlx5io.4 @@ -1,189 +1,189 @@ .\" .\" Copyright (c) 2018, 2019 Mellanox Technologies .\" 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 October 2, 2019 .Dt mlx5io 4 .Os .Sh NAME .Nm mlx5io .Nd IOCTL interface to manage Connect-X 4/5/6 Mellanox network adapters .Sh SYNOPSIS .In dev/mlx5/mlx5io.h .Sh DESCRIPTION The .Nm interface is provided for management of the Connect-X4, 5 and 6 network adapters in the aspects not covered by the generic network configuration, mostly related to the PCIe attachment and internal card working. Interface consists of the commands, which are passed by means of .Xr ioctl 2 on the file descriptor, opened from the .Pa /dev/mlx5ctl device node. .Pp The following commands are implemented: .Bl -tag -width indent .It Dv MLX5_FWDUMP_FORCE Take the snapshot of the firmware registers state and store it in the kernel buffer. The buffer must be empty, in other words, no dumps should be written so far, or existing dump cleared with the .Dv MLX5_FWDUMP_RESET command for the specified device. The argument for the command should point to the .Vt struct mlx5_tool_addr structure, containing the PCIe bus address of the device. .Bd -literal struct mlx5_tool_addr { uint32_t domain; uint8_t bus; uint8_t slot; uint8_t func; }; .Ed .It Dv MLX5_FWDUMP_RESET Clear the stored firmware dump, preparing the kernel buffer for the next dump. The argument for the command should point to the .Vt struct mlx5_tool_addr structure, containing the PCIe bus address of the device. .It Dv MLX5_FWDUMP_GET Fetch the stored firmware dump into the user memory. The argument to the command should point to the input/output .Vt struct mlx5_fwdump_get structure. Its .Dv devaddr field specifies the address of the device, the .Dv buf fields points to the array of .Vt struct mlx5_fwdump_reg of records of the registers values, the size of the array is specified in the .Dv reg_cnt field. .Bd -literal struct mlx5_fwdump_get { struct mlx5_tool_addr devaddr; struct mlx5_fwdump_reg *buf; size_t reg_cnt; size_t reg_filled; /* out */ }; .Ed .Pp On successful return, the .Dv reg_filled field reports the number of the .Dv buf array elements actually filled with the registers values. If .Dv buf contains the .Dv NULL pointer, no registers are filled, but .Dv reg_filled still contains the number of registers that should be passed for the complete dump. .Pp The .Vt struct mlx5_fwdump_reg element contains the address of the register in the field .Dv addr , and its value in the field .Dv val . .Bd -literal struct mlx5_fwdump_reg { uint32_t addr; uint32_t val; }; .Ed .It Dv MLX5_FW_UPDATE Requests firmware update (flash) on the adapter specified by the .Dv devaddr using the firmware image in .Dv MFA2 format. The argument for the ioctl command is the .Vt struct mlx5_fw_update with the following definition. .Bd -literal struct mlx5_fw_update { struct mlx5_tool_addr devaddr; void *img_fw_data; size_t img_fw_data_len; }; .Ed Image address in memory is passed in .Dv img_fw_data , the length of the image is specified in .Dv img_fw_data_len field. .It Dv MLX5_FW_RESET Requests PCIe link-level reset on the device. The address of the device is specified by the .Vt struct mlx5_tool_addr structure, which should be passed as an argument. .It Dv MLX5_EEPROM_GET Fetch EEPROM information. The argument to the command should point to the input/output .Vt struct mlx5_eeprom_get structure where, the .Dv devaddr field specifies the address of the device. .Bd -literal struct mlx5_eeprom_get { struct mlx5_tool_addr devaddr; size_t eeprom_info_page_valid; uint32_t *eeprom_info_buf; size_t eeprom_info_out_len; }; .Ed .Pp On successful return, the .Dv eeprom_info_out_len field reports the length of the EEPROM information. .Dv eeprom_info_buf field contains the actual EEPROM information. .Dv eeprom_info_page_valid field reports the third page validity. .El .Sh FILES The .Pa /dev/mlx5ctl -.Xr devfs 5 +.Xr devfs 4 node is used to pass commands to the driver. .Sh RETURN VALUES If successful, the IOCTL returns zero. Otherwise, -1 is returned and the global variable .Va errno is set to indicate the error. .Sh SEE ALSO .Xr errno 2 , .Xr ioctl 2 , .Xr mlx5en 4 , .Xr mlx5ib 4 , .Xr mlx5tool 8 and .Xr pci 9 . diff --git a/share/man/man4/pcm.4 b/share/man/man4/pcm.4 index 5fcaca7220b9..769f562fe91e 100644 --- a/share/man/man4/pcm.4 +++ b/share/man/man4/pcm.4 @@ -1,680 +1,680 @@ .\" .\" Copyright (c) 2009-2011 Joel Dahl .\" 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 March 24, 2024 .Dt SOUND 4 .Os .Sh NAME .Nm sound , .Nm pcm , .Nm snd .Nd .Fx PCM audio device infrastructure .Sh SYNOPSIS To compile this driver into the kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "device sound" .Ed .Sh DESCRIPTION The .Nm driver is the main component of the .Fx sound system. It works in conjunction with a bridge device driver on supported devices and provides PCM audio record and playback once it attaches. Each bridge device driver supports a specific set of audio chipsets and needs to be enabled together with the .Nm driver. PCI and ISA PnP audio devices identify themselves so users are usually not required to add anything to .Pa /boot/device.hints . .Pp Some of the main features of the .Nm driver are: multichannel audio, per-application volume control, dynamic mixing through virtual sound channels, true full duplex operation, bit perfect audio, rate conversion and low latency modes. .Pp The .Nm driver is enabled by default, along with several bridge device drivers. Those not enabled by default can be loaded during runtime with .Xr kldload 8 or during boot via .Xr loader.conf 5 . The following bridge device drivers are available: .Pp .Bl -bullet -compact .It .Xr snd_ai2s 4 (enabled by default on powerpc) .It .Xr snd_als4000 4 .It .Xr snd_atiixp 4 .It .Xr snd_cmi 4 (enabled by default on amd64, i386) .It .Xr snd_cs4281 4 .It .Xr snd_csa 4 (enabled by default on amd64, i386) .It .Xr snd_davbus 4 (enabled by default on powerpc) .It .Xr snd_emu10k1 4 .It .Xr snd_emu10kx 4 (enabled by default on amd64, i386) .It .Xr snd_envy24 4 .It .Xr snd_envy24ht 4 .It .Xr snd_es137x 4 (enabled by default on amd64, i386) .It .Xr snd_fm801 4 .It .Xr snd_hda 4 (enabled by default on amd64, i386) .It .Xr snd_hdsp 4 .It .Xr snd_hdspe 4 .It .Xr snd_ich 4 (enabled by default on amd64, i386) .It .Xr snd_maestro3 4 .It .Xr snd_neomagic 4 .It .Xr snd_solo 4 .It .Xr snd_spicds 4 .It .Xr snd_uaudio 4 (auto-loaded on device plug) .It .Xr snd_via8233 4 (enabled by default on amd64, i386) .It .Xr snd_via82c686 4 .It .Xr snd_vibes 4 .El .Pp Refer to the manual page for each bridge device driver for driver specific settings and information. .Ss Boot Variables In general, the module .Pa snd_foo corresponds to .Cd "device snd_foo" and can be loaded by the boot .Xr loader 8 via .Xr loader.conf 5 or from the command line using the .Xr kldload 8 utility. Options which can be specified in .Pa /boot/loader.conf include: .Bl -tag -width ".Va snd_driver_load" -offset indent .It Va snd_driver_load .Pq Dq Li NO If set to .Dq Li YES , this option loads all available drivers. .It Va snd_hda_load .Pq Dq Li NO If set to .Dq Li YES , only the Intel High Definition Audio bridge device driver and dependent modules will be loaded. .It Va snd_foo_load .Pq Dq Li NO If set to .Dq Li YES , load driver for card/chipset foo. .El .Pp To define default values for the different mixer channels, set the channel to the preferred value using hints, e.g.: .Va hint.pcm.0.line Ns = Ns Qq Li 0 . This will mute the input channel per default. .Ss Multichannel Audio Multichannel audio, popularly referred to as .Dq surround sound is supported and enabled by default. The .Fx multichannel matrix processor supports up to 18 interleaved channels, but the limit is currently set to 8 channels (as commonly used for 7.1 surround sound). The internal matrix mapping can handle reduction, expansion or re-routing of channels. This provides a base interface for related multichannel .Fn ioctl support. Multichannel audio works both with and without VCHANs. .Pp Most bridge device drivers are still missing multichannel matrixing support, but in most cases this should be trivial to implement. Use the .Va dev.pcm.%d.[play|rec].vchanformat .Xr sysctl 8 to adjust the number of channels used. The current multichannel interleaved structure and arrangement was implemented by inspecting various popular UNIX applications. There were no single standard, so much care has been taken to try to satisfy each possible scenario, despite the fact that each application has its own conflicting standard. .Ss EQ The Parametric Software Equalizer (EQ) enables the use of .Dq tone controls (bass and treble). Commonly used for ear-candy or frequency compensation due to the vast difference in hardware quality. EQ is disabled by default, but can be enabled with the .Va hint.pcm.%d.eq tunable. .Ss VCHANs Each device can optionally support more playback and recording channels than physical hardware provides by using .Dq virtual channels or VCHANs. VCHAN options can be configured via the .Xr sysctl 8 interface but can only be manipulated while the device is inactive. .Ss VPC .Fx supports independent and individual volume controls for each active application, without touching the master .Nm volume. This is sometimes referred to as Volume Per Channel (VPC). The VPC feature is enabled by default. .Ss Loader Tunables The following loader tunables are used to set driver configuration at the .Xr loader 8 prompt before booting the kernel, or they can be stored in .Pa /boot/loader.conf in order to automatically set them before booting the kernel. It is also possible to use .Xr kenv 1 to change these tunables before loading the .Nm driver. The following tunables can not be changed during runtime using .Xr sysctl 8 . .Bl -tag -width indent .It Va hint.pcm.%d.eq Set to 1 or 0 to explicitly enable (1) or disable (0) the equalizer. Requires a driver reload if changed. Enabling this will make bass and treble controls appear in mixer applications. This tunable is undefined by default. Equalizing is disabled by default. .It Va hint.pcm.%d.vpc Set to 1 or 0 to explicitly enable (1) or disable (0) the VPC feature. This tunable is undefined by default. VPC is however enabled by default. .El .Ss Runtime Configuration There are a number of .Xr sysctl 8 variables available which can be modified during runtime. These values can also be stored in .Pa /etc/sysctl.conf in order to automatically set them during the boot process. .Va hw.snd.* are global settings and .Va dev.pcm.* are device specific. .Bl -tag -width indent .It Va hw.snd.compat_linux_mmap Linux .Xr mmap 2 compatibility. The following values are supported (default is 0): .Bl -tag -width 2n .It -1 Force disabling/denying PROT_EXEC .Xr mmap 2 requests. .It 0 Auto detect proc/ABI type, allow .Xr mmap 2 for Linux applications, and deny for everything else. .It 1 Always allow PROT_EXEC page mappings. .El .It Va hw.snd.default_auto Automatically assign the default sound unit. The following values are supported (default is 1): .Bl -tag -width 2n .It 0 Do not assign the default sound unit automatically. .It 1 Use the best available sound device based on playing and recording capabilities of the device. .It 2 Use the most recently attached device. .El .It Va hw.snd.default_unit Default sound card for systems with multiple sound cards. When using -.Xr devfs 5 , +.Xr devfs 4 , the default device for .Pa /dev/dsp . Equivalent to a symlink from .Pa /dev/dsp to .Pa /dev/dsp Ns Va ${hw.snd.default_unit} . .It Va hw.snd.feeder_eq_exact_rate Only certain rates are allowed for precise processing. The default behavior is however to allow sloppy processing for all rates, even the unsupported ones. Enable to toggle this requirement and only allow processing for supported rates. .It Va hw.snd.feeder_rate_max Maximum allowable sample rate. .It Va hw.snd.feeder_rate_min Minimum allowable sample rate. .It Va hw.snd.feeder_rate_polyphase_max Adjust to set the maximum number of allowed polyphase entries during the process of building resampling filters. Disabling polyphase resampling has the benefit of reducing memory usage, at the expense of slower and lower quality conversion. Only applicable when the SINC interpolator is used. Default value is 183040. Set to 0 to disable polyphase resampling. .It Va hw.snd.feeder_rate_quality Sample rate converter quality. Default value is 1, linear interpolation. Available options include: .Bl -tag -width 2n .It 0 Zero Order Hold, ZOH. Very fast, but with poor quality. .It 1 Linear interpolation. Fast, quality is subject to personal preference. Technically the quality is poor however, due to the lack of anti-aliasing filtering. .It 2 Bandlimited SINC interpolator. Implements polyphase banking to boost the conversion speed, at the cost of memory usage, with multiple high quality polynomial interpolators to improve the conversion accuracy. 100% fixed point, 64bit accumulator with 32bit coefficients and high precision sample buffering. Quality values are 100dB stopband, 8 taps and 85% bandwidth. .It 3 Continuation of the bandlimited SINC interpolator, with 100dB stopband, 36 taps and 90% bandwidth as quality values. .It 4 Continuation of the bandlimited SINC interprolator, with 100dB stopband, 164 taps and 97% bandwidth as quality values. .El .It Va hw.snd.feeder_rate_round Sample rate rounding threshold, to avoid large prime division at the cost of accuracy. All requested sample rates will be rounded to the nearest threshold value. Possible values range between 0 (disabled) and 500. Default is 25. .It Va hw.snd.latency Configure the buffering latency. Only affects applications that do not explicitly request blocksize / fragments. This tunable provides finer granularity than the .Va hw.snd.latency_profile tunable. Possible values range between 0 (lowest latency) and 10 (highest latency). .It Va hw.snd.latency_profile Define sets of buffering latency conversion tables for the .Va hw.snd.latency tunable. A value of 0 will use a low and aggressive latency profile which can result in possible underruns if the application cannot keep up with a rapid irq rate, especially during high workload. The default value is 1, which is considered a moderate/safe latency profile. .It Va hw.snd.maxautovchans Global VCHAN setting that only affects devices with at least one playback or recording channel available. The sound system will dynamically create up to this many VCHANs. Set to .Dq 0 if no VCHANs are desired. Maximum value is 256. .It Va hw.snd.report_soft_formats Controls the internal format conversion if it is available transparently to the application software. When disabled or not available, the application will only be able to select formats the device natively supports. .It Va hw.snd.report_soft_matrix Enable seamless channel matrixing even if the hardware does not support it. Makes it possible to play multichannel streams even with a simple stereo sound card. .It Va hw.snd.verbose Level of verbosity for the .Pa /dev/sndstat device. Higher values include more output and the highest level, four, should be used when reporting problems. Other options include: .Bl -tag -width 2n .It 0 Installed devices and their allocated bus resources. .It 1 The number of playback, record, virtual channels, and flags per device. .It 2 Channel information per device including the channel's current format, speed, and pseudo device statistics such as buffer overruns and buffer underruns. .It 3 File names and versions of the currently loaded sound modules. .It 4 Various messages intended for debugging. .El .It Va hw.snd.vpc_0db Default value for .Nm volume. Increase to give more room for attenuation control. Decrease for more amplification, with the possible cost of sound clipping. .It Va hw.snd.vpc_autoreset When a channel is closed the channel volume will be reset to 0db. This means that any changes to the volume will be lost. Enabling this will preserve the volume, at the cost of possible confusion when applications tries to re-open the same device. .It Va hw.snd.vpc_mixer_bypass The recommended way to use the VPC feature is to teach applications to use the correct .Fn ioctl : .Dv SNDCTL_DSP_GETPLAYVOL , SNDCTL_DSP_SETPLAYVOL , .Dv SNDCTL_DSP_SETRECVOL , SNDCTL_DSP_SETRECVOL . This is however not always possible. Enable this to allow applications to use their own existing mixer logic to control their own channel volume. .It Va hw.snd.vpc_reset Enable to restore all channel volumes back to the default value of 0db. .It Va dev.pcm.%d.bitperfect Enable or disable bitperfect mode. When enabled, channels will skip all dsp processing, such as channel matrixing, rate converting and equalizing. The pure .Nm stream will be fed directly to the hardware. If VCHANs are enabled, the bitperfect mode will use the VCHAN format/rate as the definitive format/rate target. The recommended way to use bitperfect mode is to disable VCHANs and enable this sysctl. Default is disabled. .It Va dev.pcm.%d.[play|rec].vchans The current number of VCHANs allocated per device. This can be set to preallocate a certain number of VCHANs. Setting this value to .Dq 0 will disable VCHANs for this device. .It Va dev.pcm.%d.[play|rec].vchanformat Format for VCHAN mixing. All playback paths will be converted to this format before the mixing process begins. By default only 2 channels are enabled. Available options include: .Bl -tag -width 2n .It s16le:1.0 Mono. .It s16le:2.0 Stereo, 2 channels (left, right). .It s16le:2.1 3 channels (left, right, LFE). .It s16le:3.0 3 channels (left, right, rear center). .It s16le:4.0 Quadraphonic, 4 channels (front/rear left and right). .It s16le:4.1 5 channels (4.0 + LFE). .It s16le:5.0 5 channels (4.0 + center). .It s16le:5.1 6 channels (4.0 + center + LFE). .It s16le:6.0 6 channels (4.0 + front/rear center). .It s16le:6.1 7 channels (6.0 + LFE). .It s16le:7.1 8 channels (4.0 + center + LFE + left and right side). .El .It Va dev.pcm.%d.[play|rec].vchanmode VCHAN format/rate selection. Available options include: .Bl -tag -width 2n .It fixed Channel mixing is done using fixed format/rate. Advanced operations such as digital passthrough will not work. Can be considered as a .Dq legacy mode. This is the default mode for hardware channels which lack support for digital formats. .It passthrough Channel mixing is done using fixed format/rate, but advanced operations such as digital passthrough also work. All channels will produce sound as usual until a digital format playback is requested. When this happens all other channels will be muted and the latest incoming digital format will be allowed to pass through undisturbed. Multiple concurrent digital streams are supported, but the latest stream will take precedence and mute all other streams. .It adaptive Works like the .Dq passthrough mode, but is a bit smarter, especially for multiple .Nm channels with different format/rate. When a new channel is about to start, the entire list of virtual channels will be scanned, and the channel with the best format/rate (usually the highest/biggest) will be selected. This ensures that mixing quality depends on the best channel. The downside is that the hardware DMA mode needs to be restarted, which may cause annoying pops or clicks. .El .It Va dev.pcm.%d.[play|rec].vchanrate Sample rate speed for VCHAN mixing. All playback paths will be converted to this sample rate before the mixing process begins. .It Va dev.pcm.%d.polling Experimental polling mode support where the driver operates by querying the device state on each tick using a .Xr callout 9 mechanism. Disabled by default and currently only available for a few device drivers. .El .Ss Statistics Channel statistics are only kept while the device is open. So with situations involving overruns and underruns, consider the output while the errant application is open and running. .Ss IOCTL Support The driver supports most of the OSS .Fn ioctl functions, and most applications work unmodified. A few differences exist, while memory mapped playback is supported natively and in Linux emulation, memory mapped recording is not due to VM system design. As a consequence, some applications may need to be recompiled with a slightly modified audio module. See .In sys/soundcard.h for a complete list of the supported .Fn ioctl functions. .Sh FILES The .Nm drivers may create the following device nodes: .Pp .Bl -tag -width ".Pa /dev/sndstat" -compact .It Pa /dev/dsp%d Audio device. The number represents the unit number of the device. .It Pa /dev/dsp Alias of .Pa /dev/dsp${hw.snd.default_unit} . Available only if .Pa hw.snd.basename_clone is set. .It Pa /dev/sndstat Current .Nm status, including all channels and drivers. .El .Pp All .Nm devices are listed in .Pa /dev/sndstat . Additional messages are sometimes recorded when the device is probed and attached, these messages can be viewed with the .Xr dmesg 8 utility. .Sh EXAMPLES Use the sound metadriver to load all .Nm bridge device drivers at once (for example if it is unclear which the correct driver to use is): .Pp .Dl kldload snd_driver .Pp Load a specific bridge device driver, in this case the Intel High Definition Audio driver: .Pp .Dl kldload snd_hda .Pp Check the status of all detected .Nm devices: .Pp .Dl cat /dev/sndstat .Pp Change the default sound device, in this case to the second device. This is handy if there are multiple .Nm devices available: .Pp .Dl mixer -d pcm1 .Sh DIAGNOSTICS .Bl -diag .It pcm%d:play:%d:dsp%d.p%d: play interrupt timeout, channel dead The hardware does not generate interrupts to serve incoming (play) or outgoing (record) data. .It unsupported subdevice XX A device node is not created properly. .El .Sh SEE ALSO +.Xr devfs 4 , .Xr snd_ai2s 4 , .Xr snd_als4000 4 , .Xr snd_atiixp 4 , .Xr snd_cmi 4 , .Xr snd_cs4281 4 , .Xr snd_csa 4 , .Xr snd_davbus 4 , .Xr snd_emu10k1 4 , .Xr snd_emu10kx 4 , .Xr snd_envy24 4 , .Xr snd_envy24ht 4 , .Xr snd_es137x 4 , .Xr snd_fm801 4 , .Xr snd_hda 4 , .Xr snd_hdsp 4 , .Xr snd_hdspe 4 , .Xr snd_ich 4 , .Xr snd_maestro3 4 , .Xr snd_neomagic 4 , .Xr snd_solo 4 , .Xr snd_spicds 4 , .Xr snd_t4dwave 4 , .Xr snd_uaudio 4 , .Xr snd_via8233 4 , .Xr snd_via82c686 4 , .Xr snd_vibes 4 , -.Xr devfs 5 , .Xr device.hints 5 , .Xr loader.conf 5 , .Xr dmesg 8 , .Xr kldload 8 , .Xr mixer 8 , .Xr sysctl 8 .Rs .%T "Cookbook formulae for audio EQ biquad filter coefficients (Audio-EQ-Cookbook.txt), by Robert Bristow-Johnson" .%U "https://www.musicdsp.org/en/latest/Filters/197-rbj-audio-eq-cookbook.html" .Re .Rs .%T "Julius O'Smith's Digital Audio Resampling" .%U "http://ccrma.stanford.edu/~jos/resample/" .Re .Rs .%T "Polynomial Interpolators for High-Quality Resampling of Oversampled Audio, by Olli Niemitalo" .%U "http://yehar.com/blog/wp-content/uploads/2009/08/deip.pdf" .Re .Rs .%T "The OSS API" .%U "http://www.opensound.com/pguide/oss.pdf" .Re .Sh HISTORY The .Nm device driver first appeared in .Fx 2.2.6 as .Nm pcm , written by .An Luigi Rizzo . It was later rewritten in .Fx 4.0 by .An Cameron Grant . The API evolved from the VOXWARE standard which later became OSS standard. .Sh AUTHORS .An -nosplit .An Luigi Rizzo Aq Mt luigi@iet.unipi.it initially wrote the .Nm pcm device driver and this manual page. .An Cameron Grant Aq Mt gandalf@vilnya.demon.co.uk later revised the device driver for .Fx 4.0 . .An Seigo Tanimura Aq Mt tanimura@r.dl.itc.u-tokyo.ac.jp revised this manual page. It was then rewritten for .Fx 5.2 . .Sh BUGS Some features of your sound card (e.g., global volume control) might not be supported on all devices. diff --git a/share/man/man5/devfs.conf.5 b/share/man/man5/devfs.conf.5 index e95c7b578bf5..f7141b76c3f6 100644 --- a/share/man/man5/devfs.conf.5 +++ b/share/man/man5/devfs.conf.5 @@ -1,127 +1,127 @@ .\" Copyright (c) 2004 Roland Smith .\" 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 May 25, 2019 .Dt DEVFS.CONF 5 .Os .Sh NAME .Nm devfs.conf .Nd boot-time devfs configuration information .Sh DESCRIPTION The .Nm file provides an easy way to set ownership and permissions, or create links for devices available at boot. .Pp It does not work for devices plugged in and out after the system is up and running, e.g.\& USB devices. See .Xr devfs.rules 5 for setting ownership and permissions for all device nodes, and .Xr devd.conf 5 for actions to be taken when devices are attached or detached. .Pp Lines starting with a hash sign .Pq Ql # and empty lines are ignored. The lines that specify .Nm rules consist of three parameters separated by whitespace: .Bl -tag -width indent .It Ar action The action to take for the device. The action names are only significant to the first unique character. .It Ar devname The name of the device created by -.Xr devfs 5 . +.Xr devfs 4 . .It Ar arg The argument of the .Ar action . .El .Pp The actions currently supported are: .Bl -tag -width indent .It Ic link This action creates a symbolic link named .Ar arg that points to .Ar devname , the name of the device created by -.Xr devfs 5 . +.Xr devfs 4 . .It Ic own This action changes the ownership of .Ar devname . The .Ar arg parameter must be in the form of an .Ar owner Ns : Ns Ar group pair, in the same format used by .Xr chown 8 . .It Ic perm This action changes the permissions of .Ar devname . The .Ar arg parameter must be a .Ar mode as explained in .Xr chmod 1 . .El .Sh FILES .Bl -tag -compact -width Pa .It Pa /etc/devfs.conf .It Pa /usr/share/examples/etc/devfs.conf .El .Sh EXAMPLES To create a .Pa /dev/cdrom link that points to the first CD-ROM, the following may be added to .Nm : .Bd -literal -offset indent link cd0 cdrom .Ed .Pp To set the owner of a device, the .Ic own action may be specified: .Bd -literal -offset indent own cd0 root:cdrom .Ed .Pp To set the permissions of a device, a .Ic perm action should be used: .Bd -literal -offset indent perm cd0 0660 .Ed .Sh SEE ALSO .Xr chmod 1 , +.Xr devfs 4 , .Xr devd.conf 5 , -.Xr devfs 5 , .Xr devfs.rules 5 , .Xr chown 8 .Sh AUTHORS This manual page was written by .An Roland Smith Aq Mt rsmith@xs4all.nl . diff --git a/share/man/man5/devfs.rules.5 b/share/man/man5/devfs.rules.5 index 368a7696b5cd..e878c2a97738 100644 --- a/share/man/man5/devfs.rules.5 +++ b/share/man/man5/devfs.rules.5 @@ -1,133 +1,133 @@ .\" Copyright (c) 2004 Roland Smith .\" 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 1, 2020 .Dt DEVFS.RULES 5 .Os .Sh NAME .Nm devfs.rules .Nd devfs configuration information .Sh DESCRIPTION The .Nm file provides an easy way to create and apply .Xr devfs 8 rules, even for devices that are not available at boot. .Pp For devices available at boot, see .Xr devfs.conf 5 . .Pp The format of this file is simple. Empty lines and lines beginning with a hash sign .Pq Ql # are ignored. A line between brackets denotes the start of a ruleset. In the brackets should be the name of the ruleset and its number, separated by an equal sign. .Pp Other lines are rule specifications as documented in .Xr devfs 8 , in the section .Sx "Rule Specification" . These lines are prepended with .Dq Li rule and are passed to .Xr devfs 8 by the startup scripts of the system. It is important to put path elements that contain .Xr glob 3 special characters between quotes. .Pp Rulesets should have a unique name and number. .Pp All rules that follow a ruleset declaration belong to that ruleset, until a new ruleset is started. .Pp One custom ruleset has to be enabled in .Pa /etc/rc.conf , otherwise it will not be applied to the .Pa /dev file system by the default system startup process. For example, to enable a .Dq Li localrules ruleset for the .Pa /dev file system, you would have to use something like this in your .Pa rc.conf file: .Bd -literal -offset indent devfs_system_ruleset="localrules" .Ed .Pp The rules are loaded at boot via the devfs service. To load modified rules after the system has booted, run the command: .Bd -literal -offset indent service devfs restart .Ed .Sh FILES .Bl -tag -compact -width Pa .It Pa /etc/defaults/devfs.rules Default .Nm configuration file. .It Pa /etc/devfs.rules Local .Nm configuration file. Rulesets in here override those in .Pa /etc/defaults/devfs.rules with the same ruleset number, otherwise the two files are effectively merged. .El .Sh EXAMPLES To make all the partitions of .Xr da 4 devices readable and writable by their owner and the .Dq Li usb group, the following rule may be used: .Pp .Dl "[localrules=10]" .Dl "add path 'da*s*' mode 0660 group usb" .Pp The first line declares and starts a new ruleset, with the name .Va localrules and the number 10. .Pp To give .Xr usbconfig 8 and .Xr libusb 3 enabled applications permission to all usb devices for their owner and the .Dq Li usb group, a similar rule may be used: .Pp .Dl "add path 'usb/*' mode 0660 group usb" .Sh SEE ALSO .Xr glob 3 , -.Xr devfs 5 , +.Xr devfs 4 , .Xr devfs.conf 5 , .Xr devfs 8 , .Xr service 8 .Sh AUTHORS This manual page was written by .An Roland Smith Aq Mt rsmith@xs4all.nl . diff --git a/share/man/man5/fstab.5 b/share/man/man5/fstab.5 index 9cdcf818cf32..787fe3933aca 100644 --- a/share/man/man5/fstab.5 +++ b/share/man/man5/fstab.5 @@ -1,467 +1,467 @@ .\" 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 April 14, 2014 .Dt FSTAB 5 .Os .Sh NAME .Nm fstab .Nd static information about the file systems .Sh SYNOPSIS .In fstab.h .Sh DESCRIPTION The file .Nm contains descriptive information about the various file systems. .Nm is only read by programs, and not written; it is the duty of the system administrator to properly create and maintain this file. Each file system is described on a separate line; fields on each line are separated by tabs or spaces. The order of records in .Nm is important because .Xr fsck 8 , .Xr mount 8 , and .Xr umount 8 sequentially iterate through .Nm doing their thing. .Pp The first field, .Pq Fa fs_spec , describes the special device or remote file system to be mounted. The contents are decoded by the .Xr strunvis 3 function. This allows using spaces or tabs in the device name which would be interpreted as field separators otherwise. .Pp The second field, .Pq Fa fs_file , describes the mount point for the file system. For swap partitions, this field should be specified as .Dq none . The contents are decoded by the .Xr strunvis 3 function, as above. .Pp The third field, .Pq Fa fs_vfstype , describes the type of the file system. The system can support various file system types. Only the root, /usr, and /tmp file systems need be statically compiled into the kernel; everything else will be automatically loaded at mount time. (Exception: the FFS cannot currently be demand-loaded.) Some people still prefer to statically compile other file systems as well. .Pp The fourth field, .Pq Fa fs_mntops , describes the mount options associated with the file system. It is formatted as a comma separated list of options. It contains at least the type of mount (see .Fa fs_type below) plus any additional options appropriate to the file system type. See the options flag .Pq Fl o in the .Xr mount 8 page and the file system specific page, such as .Xr mount_nfs 8 , for additional options that may be specified. All options that can be given to the file system specific mount commands can be used in .Nm as well. They just need to be formatted a bit differently. The arguments of the .Fl o option can be used without the preceding .Fl o flag. Other options need both the file system specific flag and its argument, separated by an equal sign. For example, mounting an -.Xr msdosfs 5 +.Xr msdosfs 4 filesystem, the options .Bd -literal -offset indent -o sync -o noatime -m 644 -M 755 -u foo -g bar .Ed .Pp should be written as .Bd -literal -offset indent sync,noatime,-m=644,-M=755,-u=foo,-g=bar .Ed .Pp in the option field of .Nm . .Pp If the options .Dq userquota and/or .Dq groupquota are specified, the file system is automatically processed by the .Xr quotacheck 8 command, and user and/or group disk quotas are enabled with .Xr quotaon 8 . By default, file system quotas are maintained in files named .Pa quota.user and .Pa quota.group which are located at the root of the associated file system. These defaults may be overridden by putting an equal sign and an alternative absolute pathname following the quota option. Thus, if the user quota file for .Pa /tmp is stored in .Pa /var/quotas/tmp.user , this location can be specified as: .Bd -literal -offset indent userquota=/var/quotas/tmp.user .Ed .Pp If the option .Dq failok is specified, the system will ignore any error which happens during the mount of that filesystem, which would otherwise cause the system to drop into single user mode. This option is implemented by the .Xr mount 8 command and will not be passed to the kernel. .Pp If the option .Dq noauto is specified, the file system will not be automatically mounted at system startup. Note that, for network file systems of third party types (i.e., types supported by additional software not included in the base system) to be automatically mounted at system startup, the .Va extra_netfs_types .Xr rc.conf 5 variable must be used to extend the .Xr rc 8 startup script's list of network file system types. .Pp If the option .Dq late is specified, the file system will be automatically mounted at a stage of system startup after remote mount points are mounted. For more detail about this option, see the .Xr mount 8 manual page. .Pp If the option .Dq update is specified, it indicates that the status of an already mounted file system should be changed accordingly. This allows, for example, file systems mounted read-only to be upgraded read-write and vice-versa. By default, an entry corresponding to a file systems that is already mounted is going to be skipped over when processing .Nm , unless it's a root file system, in which case logic similar to .Dq update is applied automatically. .Pp The .Dq update option is typically used in conjunction with two .Nm files. The first .Nm file is used to set up the initial set of file systems. The second .Nm file is then run to update the initial set of file systems and to add additional file systems. .Pp The type of the mount is extracted from the .Fa fs_mntops field and stored separately in the .Fa fs_type field (it is not deleted from the .Fa fs_mntops field). If .Fa fs_type is .Dq rw or .Dq ro then the file system whose name is given in the .Fa fs_file field is normally mounted read-write or read-only on the specified special file. .Pp If .Fa fs_type is .Dq sw then the special file is made available as a piece of swap space by the .Xr swapon 8 command at the end of the system reboot procedure. For swap devices, the keyword .Dq trimonce triggers the delivery of a .Dv BIO_DELETE command to the device. This command marks the device's blocks as unused, except those that might store a disk label. This marking can erase a crash dump. To delay .Nm swapon for a device until after .Nm savecore has copied the crash dump to another location, use the .Dq late option. For vnode-backed swap spaces, .Dq file is supported in the .Fa fs_mntops field. When .Fa fs_spec is an .Xr md 4 device file .Pq Do md Dc or Do md[0-9]* Dc and .Dq file is specified in .Fa fs_mntopts , an .Xr md 4 device is created with the specified file used as backing store, and then the new device is used as swap space. Swap entries on .Pa .eli devices will cause automatic creation of encrypted devices. The .Dq ealgo , .Dq aalgo , .Dq keylen , .Dq notrim , and .Dq sectorsize options may be passed to control those .Xr geli 8 parameters. The fields other than .Fa fs_spec and .Fa fs_type are unused. If .Fa fs_type is specified as .Dq xx the entry is ignored. This is useful to show disk partitions which are currently unused. .Pp The fifth field, .Pq Fa fs_freq , is used for these file systems by the .Xr dump 8 command to determine which file systems need to be dumped. If the fifth field is not present, a value of zero is returned and .Nm dump will assume that the file system does not need to be dumped. If the fifth field is greater than 0, then it specifies the number of days between dumps for this file system. .Pp The sixth field, .Pq Fa fs_passno , is used by the .Xr fsck 8 and .Xr quotacheck 8 programs to determine the order in which file system and quota checks are done at reboot time. The .Fa fs_passno field can be any value between 0 and .Ql INT_MAX Ns -1 . .Pp The root file system should be specified with a .Fa fs_passno of 1, and other file systems should have a .Fa fs_passno of 2 or greater. A file system with a .Fa fs_passno value of 1 is always checked sequentially and be completed before another file system is processed, and it will be processed before all file systems with a larger .Fa fs_passno . .Pp For any given value of .Fa fs_passno , file systems within a drive will be checked sequentially, but file systems on different drives will be checked at the same time to utilize parallelism available in the hardware. Once all file system checks are complete for the current .Fa fs_passno , the same process will start over for the next .Fa fs_passno . .Pp If the sixth field is not present or is zero, a value of zero is returned and .Xr fsck 8 and .Xr quotacheck 8 will assume that the file system does not need to be checked. .Pp The .Fa fs_passno field can be used to implement finer control when the system utilities may determine that the file system resides on a different physical device, when it actually does not, as with a .Xr ccd 4 device. All file systems with a lower .Fa fs_passno value will be completed before starting on file systems with a higher .Fa fs_passno value. E.g. all file systems with a .Fa fs_passno of 2 will be completed before any file systems with a .Fa fs_passno of 3 or greater are started. Gaps are allowed between the different .Fa fs_passno values. E.g. file systems listed in .Pa /etc/fstab may have .Fa fs_passno values such as 0, 1, 2, 15, 100, 200, 300, and may appear in any order within .Pa /etc/fstab . .Bd -literal #define FSTAB_RW "rw" /* read/write device */ #define FSTAB_RQ "rq" /* read/write with quotas */ #define FSTAB_RO "ro" /* read-only device */ #define FSTAB_SW "sw" /* swap device */ #define FSTAB_XX "xx" /* ignore totally */ struct fstab { char *fs_spec; /* block special device name */ char *fs_file; /* file system path prefix */ char *fs_vfstype; /* File system type, ufs, nfs */ char *fs_mntops; /* Mount options ala -o */ char *fs_type; /* FSTAB_* from fs_mntops */ int fs_freq; /* dump frequency, in days */ int fs_passno; /* pass number on parallel fsck */ }; .Ed .Pp The proper way to read records from .Pa fstab is to use the routines .Xr getfsent 3 , .Xr getfsspec 3 , .Xr getfstype 3 , and .Xr getfsfile 3 . .Sh FILES .Bl -tag -width /etc/fstab -compact .It Pa /etc/fstab The file .Nm resides in .Pa /etc . .El .Sh EXAMPLES .Bd -literal # Device Mountpoint FStype Options Dump Pass# # # UFS file system. /dev/da0p2 / ufs rw 1 1 # # Swap space on a block device. /dev/da0p1 none swap sw 0 0 # # Swap space using a block device with GELI encryption. # aalgo, ealgo, keylen, sectorsize options are available # for .eli devices. /dev/da1p2.eli none swap sw 0 0 # # tmpfs. tmpfs /tmp tmpfs rw,size=1g,mode=1777 0 0 # # UFS file system on a swap-backed md(4). /dev/md10 is # automatically created. If it is "md", a unit number # will be automatically selected. md10 /scratch mfs rw,-s1g 0 0 # # Swap space on a vnode-backed md(4). md11 none swap sw,file=/swapfile 0 0 # # CDROM. "noauto" option is typically used because the # media is removable. /dev/cd0 /cdrom cd9660 ro,noauto 0 0 # # NFS-exported file system. "serv" is an NFS server name # or IP address. serv:/export /nfs nfs rw,noinet6 0 0 .Ed .Sh SEE ALSO .Xr getfsent 3 , .Xr getvfsbyname 3 , .Xr strunvis 3 , .Xr ccd 4 , .Xr dump 8 , .Xr fsck 8 , .Xr geli 8 , .Xr mount 8 , .Xr quotacheck 8 , .Xr quotaon 8 , .Xr swapon 8 , .Xr umount 8 .Sh HISTORY The .Nm file format appeared in .Bx 4.0 . diff --git a/share/man/man5/mount.conf.5 b/share/man/man5/mount.conf.5 index 633a642e37be..4b5c272ef601 100644 --- a/share/man/man5/mount.conf.5 +++ b/share/man/man5/mount.conf.5 @@ -1,249 +1,249 @@ .\" Copyright (c) 2013 Marcel Moolenaar .\" Copyright (c) 2013 Craig Rodrigues .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" .Dd October 17, 2013 .Dt MOUNT.CONF 5 .Os .Sh NAME .Nm mount.conf .Nd root file system mount configuration file .Sh SYNOPSIS .Pa /.mount.conf .Sh DESCRIPTION During the bootup process, the .Fx kernel will try to mount the root file system using the logic in the .Fn vfs_mountroot function in .Pa src/sys/kern/vfs_mountroot.c . The root mount logic can be described as follows: .Bl -enum .It The kernel will synthesize in memory a config file with default directives for mounting the root file system. The logic for this is in .Fn vfs_mountroot_conf0 . .It The kernel will first mount -.Xr devfs 5 +.Xr devfs 4 as the root file system. .It Next, the kernel will parse the in-memory config file created in step 1 and try to mount the actual root file system. See .Sx FILE FORMAT for the format of the config file. .It When the actual root file system is mounted, -.Xr devfs 5 +.Xr devfs 4 will be re-mounted on the .Pa /dev directory. .It If a .Pa /.mount.conf file does not exist in the root file system which was just mounted, the root mount logic stops here. .It If a .Pa /.mount.conf file exists in the root file system which was just mounted, this file will be parsed, and the kernel will use this new config file to try to re-mount the root file system. See .Sx FILE FORMAT for the format of the config file. .It If the new root file system has a .Pa /.mount directory, the old root file system will be re-mounted on .Pa /.mount . .It The root mount logic will go back to step 4. .El .Pp The root mount logic is recursive, and step 8 will be repeated as long as each new root file system which is mounted has a .Pa /.mount.conf file. .Sh FILE FORMAT The kernel parses each line in .Pa .mount.conf and then tries to perform the action specified on that line as soon as it is parsed. .Bl -tag -width "XXXXXXXXXX" .It Ic # A line beginning with a # is a comment and is ignored. .It Ic {FS}:{MOUNTPOINT} {OPTIONS} The kernel will try to mount this in an operation equivalent to: .Bd -literal -offset indent mount -t {FS} -o {OPTIONS} {MOUNTPOINT} / .Ed .Pp If this is successfully mounted, further lines in .Pa .mount.conf are ignored. If all lines in .Pa .mount.conf have been processed and no root file system has been successfully mounted, then the action specified by .Ic .onfail is performed. .It Ic .ask When the kernel processes this line, a .Li mountroot> command-line prompt is displayed. At this prompt, the operator can enter the root mount. .It Ic .md Ar file Create a memory backed .Xr md 4 virtual disk, using .Ar file as the backing store. .It Ic .onfail Ar [panic|reboot|retry|continue] If after parsing all the lines in .Pa .mount.conf the kernel is unable to mount a root file system, the .Ic .onfail directive tells the kernel what action to perform. .It Ic .timeout Ar N Before trying to mount a root file system, if the root mount device does not exist, wait at most .Ar N seconds for the device to appear before trying to mount it. If .Ic .timeout is not specified, the default timeout is 3 seconds. .El .Sh EXAMPLES The following example .Pa .mount.conf will direct the kernel to try mounting the root file system first as an ISO CD9660 file system on .Pa /dev/cd0 , then if that does not work, as an ISO CD9660 file system on .Pa /dev/cd1 , and then if that does not work, as a UFS file system on .Pa /dev/ada0s1a . If that does not work, a .Li mountroot> command-line prompt will be displayed where the operator can manually enter the root file system to mount. Finally if that does not work, the kernel will panic. .Bd -literal -offset indent .Li .onfail panic .Li .timeout 3 cd9660:/dev/cd0 ro .Li .timeout 0 cd9660:/dev/cd1 ro .Li .timeout 3 ufs:/dev/ada0s1a .Li .ask .Ed .Pp The following example .Pa .mount.conf will direct the kernel to create a .Xr md 4 memory disk attached to the file .Pa /data/OS-1.0.iso and then mount the ISO CD9660 file system on the md device which was just created. The last line is a comment which is ignored. .Bd -literal -offset indent .Li .timeout 3 .Li .md /data/OS-1.0.iso .Li cd9600:/dev/md# ro .Li # Can also use cd9660:/dev/md0 ro .Ed .Pp The following example .Pa .mount.conf will direct the kernel to create a .Xr md 4 memory disk attached to the file .Pa /data/base.ufs.uzip and then mount the UFS file system on the md uzip device which was just created by the .Xr geom_uzip 4 driver. .Bd -literal -offset indent .Li .md /data/base.ufs.uzip .Li ufs:/dev/md#.uzip ro .Li # Can also use ufs:/dev/md0.uzip ro .Ed .Pp The following example .Pa .mount.conf will direct the kernel to do a unionfs mount on a directory .Pa /jail/freebsd-8-stable which has a .Xr chroot 2 environment. .Bd -literal -offset indent .Li .timeout 3 .Li unionfs:/jail/freebsd-8-stable .Ed .Sh NOTES For each root file system which is mounted, a .Pa /dev directory .Em must exist so that the root mount logic can properly re-mount -.Xr devfs 5 . +.Xr devfs 4 . If this directory does not exist, the system may hang during the bootup process. .Sh SEE ALSO .Xr nmount 2 , .Xr md 4 , .Xr boot.config 5 , .Xr fstab 5 , .Xr boot 8 , .Xr loader 8 , .Xr mount 8 .Sh HISTORY The .Nm file first appeared in .Fx 9.0 . .Sh AUTHORS .An -nosplit The root mount logic in the .Fx kernel which parses .Pa /.mount.conf was written by .An Marcel Moolenaar Aq Mt marcel@FreeBSD.org . This man page was written by .An Craig Rodrigues Aq Mt rodrigc@FreeBSD.org . diff --git a/share/man/man7/hier.7 b/share/man/man7/hier.7 index 7d164b5683d6..e0a6ff3dfefc 100644 --- a/share/man/man7/hier.7 +++ b/share/man/man7/hier.7 @@ -1,985 +1,985 @@ .\"- .\" SPDX-License-Identifier: BSD-3-Clause .\" .\" Copyright (c) 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. .\" .Dd April 18, 2024 .Dt HIER 7 .Os .Sh NAME .Nm hier .Nd index of .Fx file system hierarchy .Sh DESCRIPTION .Bl -tag -width "/libexec/" .It Pa / root directory of the file system .It Pa /COPYRIGHT .Fx copyright information .It Pa /bin/ fundamental .Bx user utilities; see .Xr intro 1 .It Pa /boot/ programs and configurations used during .Fx .Xr boot 8 .Pp .Bl -tag -width "loader.conf.d/" -compact .It Pa defaults/ default boot configuration files; see .Xr loader.conf 5 .It Pa device.hints kernel variables for controlling drivers; see .Xr device.hints 5 .It Pa dtb/ compiled flattened device tree (FDT) files; see .Xr fdt 4 and .Xr dtc 1 .Pp .Bl -tag -width "overlays/" -compact .It Pa overlays/ compiled .Xr fdt 4 overlays; see .Va fdt_overlays in .Xr loader.conf 5 .El .Pp .It Pa efi/ the .Xr uefi 8 EFI System Partition (ESP) mount point .It Pa firmware/ loadable binary firmware kernel modules .It Pa fonts/ binary bitmap console fonts; see .Xr loader.conf 5 and .Xr vtfontcvt 8 .It Pa images/ beastie boot menu images; see .Xr loader_lua 8 .It Pa kernel/ .Fx kernel and modules; see .Xr kldstat 8 .It Pa kernel.old/ alternative kernel and modules .It Pa loader.conf boot loader configuration; see .Xr loader.conf 5 .It Pa loader.conf.d/ .Xr loader.conf 5 configuration files .It Pa lua/ scripts for the Lua boot loader; see .Xr loader_lua 8 .It Pa modules/ third-party loadable kernel modules, such as those installed with .Xr pkg 8 or from .Xr ports 7 .It Pa zfs/ ZFS .Xr zpool 8 cache files .El .It Pa /compat/ files supporting binary compatibility with other operating systems .Pp .Bl -tag -width "loader.conf.d" -compact .It Pa linux/ default location for .Xr linux 4 compatibility run-time .El .It Pa /dev/ device nodes and special files; see .Xr intro 4 and -.Xr devfs 5 +.Xr devfs 4 .Pp .Bl -tag -width "loader.conf.d" -compact .It Pa ada0 first ATA storage device .It Pa ada0p1 first partition on ada0 .It Pa cd0 first optical drive .It Pa cuaU0 first USB serial port; see .Xr cu 1 .It Pa da0 first SCSI storage device .It Pa da0s1 first partition on da0 .It Pa dri/ GPU character device nodes; see .Xr drm 7 .It Pa drm/ GPU .Xr drm 7 special files .It Pa fd/ file descriptor files; see .Xr fd 4 .It Pa fd0 first floppy drive .It Pa mmcsd0 first SD storage device .It Pa mmcsd0s1 first partition on mmcsd0 .It Pa nda0 first NVMe storage device attached via .Xr cam 3 .It Pa null infinite loop that accepts anything and contains nothing .It Pa nvd0 first NVMe storage device using NVMe namespaces .It Pa pts/ pseduo-terminals; see .Xr pts 4 .It Pa random source of weak randomness; see .Xr random 4 .It Pa sa0 first tape drive .It Pa usb/ USB busses .It Pa vmm/ active .Xr bhyve 8 virtual machines .It Pa zvol/ .Xr zfs 8 volumes .El .It Pa /entropy provides initial state to RNG; see .Xr save-entropy 8 .It Pa /etc/ base system configuration files and scripts; see .Xr intro 5 .Pp .Bl -tag -width "freebsd-update.conf" -compact .It Pa auto_master autofs .Xr automount 8 configuration .It Pa bluetooth/ bluetooth configuration files .It Pa cron.d/ tables for driving scheduled tasks; see .Xr crontab 5 .It Pa crontab root's cron table .It Pa defaults/ default system configuration files; see .Xr rc 8 .It Pa devd/ configuration for .Xr devd 8 , the device state change daemon .It Pa devfs.conf boot time device configuration .It Pa dma/ configuration for .Xr dma 8 .It Pa freebsd-update.conf configuration for the base system updater; see .Xr freebsd-update 8 .It Pa fstab static filesystem configuration; see .Xr fstab 5 .It Pa hosts database of local hosts if no network name server is running .It Pa inetd.conf configuration for .Bx heritage internet servers; see .Xr inetd 8 .It Pa localtime local timezone information; see .Xr ctime 3 .It Pa jail.conf.d/ .Xr jail 8 startup scripts .It Pa login.conf login class capability database; see .Xr login.conf 5 .It Pa machine-id defines the UUID for the local system, required for dbus .It Pa mail/ .Xr sendmail 8 control files .Pp .Bl -tag -width "mailer.conf" -compact .It Pa aliases addresses to deliver system mail .It Pa mailer.conf .Xr mailwrapper 8 configuration .El .Pp .It Pa motd.template message displayed upon tty login; see .Xr motd 5 .It Pa mtree/ system mapper specification; see .Xr mtree 8 .It Pa newsyslog.conf.d/ log rotation configuration files. .It Pa ntp/ stored time for the Network Time Protocol .It Pa ntp.conf configuration for the NTP client, .Xr ntpd 8 .It Pa pam.d/ configuration files for the Pluggable Authentication Modules (PAM) library; see .Xr pam 3 .It Pa periodic/ scripts that are run daily, weekly, or monthly by .Xr cron 8 ; see .Xr periodic 8 .It Pa pf.conf configuration for the Packet Filter firewall; see .Xr pf 4 .It Pa pkg/ default configuration for the package manager, .Xr pkg 8 .It Pa ppp/ PPP configuration files; see .Xr ppp 8 .It Pa rc.conf system and daemon configuration; see .Xr rc.conf 5 .It Pa rc.d/ system and daemon startup/control scripts; see .Xr rc 8 .It Pa resolv.conf DNS configuration; see .Xr resolv.conf 5 .It Pa resolvconf.conf DNS configuration manager configuration, often generated by local-unbound; see .Xr local-unbound 8 or .Xr resolvconf 8 .It Pa security/ OpenBSM audit configuration files; see .Xr audit 8 .It Pa ssh/ OpenSSH configuration files; see .Xr ssh 1 .It Pa ssl/ OpenSSL configuration files .It Pa sysctl.conf kernel state defaults; see .Xr sysctl.conf 5 .It Pa syslog.conf system log configuration .It Pa ttys tty creation configuration; see .Xr getty 8 .It Pa wpa_supplicant.conf client wifi configuration; see .Xr wpa_supplicant.conf 5 .El .It Pa /home/ home directories for users; the typical home for an interactive user .Va beastie would be .Pa /home/beastie/ .It Pa /lib/ system libraries critical to binaries in .Pa /bin and .Pa /sbin .Pp .Bl -tag -width "nvmecontrol/" -compact .It Pa geom/ class-specific libraries for the .Xr geom 8 utility .It Pa nvmecontrol/ vendor-specific libraries to extend the .Xr nvmecontrol 8 utility .El .It Pa /libexec/ system utilities critical to binaries in .Pa /bin and .Pa /sbin .It Pa /media/ mount points for removable storage media such as CDs, DVDs, and USB drives; see .Xr automount 8 , or .Xr bsdisks 8 if a using a desktop environment from .Xr ports 7 .It Pa /mnt/ empty directory commonly used by system administrators as a temporary mount point .It Pa /net/ automounted NFS shares; see .Xr auto_master 5 .It Pa /nonexistent/ a non-existent directory; by convention, it serves as a home directory for user accounts that need no home directory; see also .Pa /var/empty/ .It Pa /proc/ process file system; see -.Xr procfs 5 +.Xr procfs 4 .It Pa /rescue/ statically linked programs for emergency recovery; see .Xr rescue 8 .It Pa /root/ home directory of the root user .It Pa /sbin/ fundamental .Bx system administration utilities; see .Xr intro 8 .It Pa /tmp/ temporary files commonly removed between system reboots; see .Va clear_tmp_enable in .Xr rc.conf 5 .It Pa /usr/ contains the majority of user utilities and applications .Pp .Bl -tag -width "freebsd-dist/" -compact .It Pa bin/ common utilities, programming tools, and applications; see .Xr intro 1 .It Pa freebsd-dist/ distribution files .Pq like base.txz ; see .Xr release 7 and .Xr bsdinstall 8 .It Pa include/ standard C include header files .It Pa lib/ shared and .Xr ar 1 Ns -type libraries; see .Xr intro 3 .Pp .Bl -tag -width Fl -compact .It Pa clang/ shared libraries for the system compiler, .Xr clang 1 .It Pa compat/ shared libraries for compatibility .It Pa debug/ standalone debug data for the kernel and base system libraries and binaries .It Pa dtrace/ .Xr dtrace 1 library scripts .It Pa engines/ OpenSSL .Pq Cryptography/SSL toolkit dynamically loadable engines .It Pa flua/ .Fx Lua shared libraries .It Pa i18n/ shared libraries for internationalization .El .Pp .It Pa lib32/ 32-bit compatibility libraries .It Pa libdata/ miscellaneous utility data files .Pp .Bl -tag -width Fl -compact .It Pa ldscripts/ linker scripts; see .Xr ld 1 .It Pa pkgconfig/ collections of compiler and linker flags for the .Xr pkgconf 1 development tool .El .Pp .It Pa libexec/ system daemons and utilities executed by programs .Pp .Bl -tag -width "bsdinstall/" -compact .It Pa bsdconfig/ utilities called by the ncurses .Fx configuration wizard .It Pa bsdinstall/ utilities for .Xr bsdinstall 8 .It Pa dwatch/ profiles for .Xr dwatch 1 .It Pa fwget/ utilities called by .Xr fwget 8 .It Pa hyperv/ scripts for communicating with the Hyper-V hypervisor .It Pa lpr/ utilities and filters for the line printer system; see .Xr lpr 1 .It Pa sendmail/ the .Xr sendmail 8 binary; see .Xr mailwrapper 8 .It Pa sm.bin/ restricted shell for .Xr sendmail 8 ; see .Xr smrsh 8 .It Pa zfs/ Z file system utilities .El .Pp .It Pa local/ local executables, libraries, etc, installed by .Xr pkg 7 or .Xr ports 7 .Pp .Bl -tag -width Fl -compact .It Pa bin/ local user utilities, see .Xr intro 1 .It Pa etc/ local program configurations .It Pa include/ local library headers .It Pa lib/ local libraries .It Pa lib32/ local 32-bit compatability libraries .It Pa libdata/ local utility data files .It Pa libexec/ utilities executed by local utilities .It Pa man/ local manual pages; see .Xr man 1 .It Pa sbin/ local administration utilities .It Pa share/ local architecture-independent files .It Pa share/doc/ local documentation .It Pa share/doc/freebsd/ articles, books, FAQ, and handbooks available from the .Fx project .El .Pp .It Pa obj/ architecture-specific target tree produced by building .Fx from source; see .Xr build 7 .It Pa ports/ .Fx ports collection; see .Xr ports 7 .It Pa sbin/ system daemons and utilities meant for user execution; see .Xr intro 8 .It Pa share/ architecture-independent files .Pp .Bl -tag -width Fl -compact .It Pa atf/ scripts for the Automated Testing Framework; see .Xr ATF 7 .It Pa bhyve/ .Xr bhyve 8 keyboard mappings .It Pa calendar/ system-wide calendar files; see .Xr calendar 1 .It Pa certs/ TLS certificates for .Xr openssl 1 .It Pa dict/ word lists; see .Xr look 1 .Pp .Bl -tag -width Fl -compact .It Pa freebsd .Fx Ns -specific terms, proper names, and jargon .It Pa web2 words from Webster's Second International .El .Pp .It Pa doc/ miscellaneous documentation .It Pa dtrace/ scripts for the Dynamic Tracing Compiler; see .Xr dtrace 1 .It Pa examples/ various examples for users and programmers .It Pa firmware/ firmware images loaded by userland programs .It Pa games/ ASCII text files used by .Bx heritage games, see .Xr intro 6 .It Pa keys/ known trusted and revoked keys .Pp .Bl -tag -width Fl -compact .It Pa pkg/ fingerprints for .Xr pkg 7 and .Xr pkg 8 .El .Pp .It Pa locale/ localization files; see .Xr setlocale 3 .It Pa man/ system manual pages; see .Xr man 1 .It Pa misc/ miscellaneous system-wide files .Pp .Bl -tag -width Fl -compact .It Pa ascii chart of the ASCII codepoints .It Pa flowers the meanings of flowers .It Pa magic magic numbers used by .Xr file 1 .It Pa termcap terminal characteristics database; see .Xr termcap 5 .El .Pp .It Pa mk/ templates for make; see .Xr make 1 .It Pa nls/ national language support files .It Pa security/ data files for security policies such as .Xr mac_lomac 4 .It Pa sendmail/ .Xr sendmail 8 configuration files .It Pa skel/ example .Pa .\& (dot) files for new accounts .It Pa snmp/ MIBs, example files and tree definitions for the SNMP daemon .Pp .Bl -tag -width Fl -compact .It Pa defs/ tree definition files for use with .Xr gensnmptree 1 .It Pa mibs/ management Information Base .Pq MIB files .El .Pp .It Pa syscons/ .Xr syscons 4 files .Pp .Bl -tag -width Fl -compact .It Pa fonts/ console fonts; see .Xr vidcontrol 1 and .Xr vidfont 1 .It Pa keymaps/ console keyboard maps; see .Xr kbdcontrol 1 and .Xr kbdmap 1 .It Pa scrnmaps/ console screen maps .El .Pp .It Pa sysroot/ files necessary for the -sysroot compiler/linker argument to build non-native binaries .Pp .Bl -tag -width "VERSION/" -compact .It Pa VERSION/ files for .Fx release VERSION; by convention, .Dq VERSION matches .Xr uname 1 .Fl r .It Pa VERSION/MACHINE.MACHINE_ARCH/ represent the binary ABI for these files; .Dq MACHINE matches .Xr uname 1 .Fl m ; .Dq MACHINE_ARCH matches .Xr uname 1 .Fl p .El .Pp .It Pa tabset/ tab description files for a variety of terminals; used in the termcap file; see .Xr termcap 5 .It Pa vi/ localization support and utilities for the .Xr vi 1 editor .It Pa vt/ files used by the system console; see .Xr vt 4 .Pp .Bl -tag -width Fl -compact .It Pa fonts/ console fonts; see .Xr vidcontrol 1 , .Xr vidfont 1 , and .Xr vtfontcvt 8 .It Pa keymaps/ console keyboard maps; see .Xr kbdcontrol 1 and .Xr kbdmap 1 .El .Pp .It Pa zoneinfo/ timezone configuration information; see .Xr tzfile 5 .El .Pp .It Pa src/ .Fx source code; see .Xr development 7 ; the layout of the source tree is described by the top-level .Pa README.md file .Pp .It Pa tests/ the .Fx test suite; see .Xr tests 7 .El .It Pa /var/ log, temporary, transient, and spool files .Pp .Bl -tag -width "preserve/" -compact .It Pa account/ system accounting files .Pp .Bl -tag -width Ds -compact .It Pa acct execution accounting file; see .Xr acct 5 .El .Pp .It Pa at/ timed command scheduling files; see .Xr at 1 .Pp .Bl -tag -width Ds -compact .It Pa jobs/ job files .It Pa spool/ output spool files .El .Pp .It Pa audit/ security event audit trail files; see .Xr audit 8 .It Pa authpf/ user shell sessions for authenticating gateways; see .Xr authpf 8 .It Pa backups/ critical system configuration backups .It Pa cache/ miscellaneous cache files .Pp .Bl -tag -width Ds -compact .It Pa pkg/ cached packages for .Xr pkg 8 .It Pa cups/ cached printers for the Common Unix Prinitng system; see .Xr cups 1 .El .Pp .It Pa crash/ default directory to store kernel crash dumps; see .Xr crash 8 and .Xr savecore 8 .It Pa cron/ files used by cron; see .Xr cron 8 .Pp .Bl -tag -width Ds -compact .It Pa tabs/ crontab files; see .Xr crontab 5 .El .Pp .It Pa db/ autogenerated system-specific database files .Pp .Bl -tag -width "freebsd-update/" -compact .It Pa etcupdate/ temporary files and log for .Xr etcupdate 8 .It Pa freebsd-update/ downloads and temporary files for .Xr freebsd-update 8 .It Pa pkg/ package database .El .Pp .It Pa empty/ for use by programs that require an empty directory, used for instance by .Xr sshd 8 for privilege separation .It Pa games/ status and score files for .Bx heritage games .It Pa heimdal/ Kerberos server databases; see .Xr kdc 8 .It Pa lib/ state information for ported Linux applications .It Pa log/ system log files .Pp .Bl -tag -width "bsdinstall_log" -compact .It Pa Xorg.0.log .Xr Xserver 1 log, if .Xr X 7 is installed rotates to .Pa Xorg.0.log.old .It Pa aculog serial line access log; see .Xr cu 1 .It Pa auth.log system authentication log .It Pa bsdinstall_log system installation log .It Pa cron scheduled task log; see .Xr cron 8 .It Pa cups/ logs for .Xr cups 1 .It Pa daemon.log default log for system daemons .It Pa devd.log default log for device state change daemon .It Pa dmesg.today system message buffer log, rotates to .Pa dmesg.yesterday .It Pa debug.log undiscarded debug syslog messages .It Pa lpd-errs logs for the line printer spooler daemon; see .Xr lpd 8 .It Pa maillog .Xr sendmail 8 log, rotates and compresses to maillog.0.bz2 .It Pa messages general system log; see .Xr syslogd 8 .It Pa mount.today currently loaded .Xr fstab 5 , rotates to .Pa mount.yesterday .It Pa pf.today packet filter firewall log; see .Xr pf 4 .It Pa pflog saved packets caught by .Xr pflogd 8 .It Pa ppp.log see .Xr ppp 8 .It Pa security transcript of events marked with the security flag .It Pa setuid.today listing of executable files which run with elevated permissions, rotates to .Pa setuid.yesterday .It Pa userlog logs changes in users or groups .It Pa utx.lastlogin last login log; see .Xr getutxent 3 .It Pa utx.log login/logout log; see .Xr getutxent 3 .It Pa xferlog default log for .Xr ftpd 8 .El .Pp .It Pa mail/ user mailbox files .It Pa msgs/ system messages database; see .Xr msgs 1 .It Pa preserve/ unused, present for historical reasons .It Pa quotas/ UFS quota information files .It Pa run/ files containing information about the operating system since it was booted .Pp .Bl -tag -width "wpa_supplicant/" -compact .It Pa bhyve/ .Xr bhyve 8 virtual machine .Xr unix 4 Ns -domain sockets .It Pa ppp/ writable by the .Dq network group for command connection sockets; see .Xr ppp 8 .It Pa utx.active database of current users; see .Xr getutxent 3 .It Pa wpa_supplicant/ IEEE Std. 802.11 wifi run time files .El .Pp .It Pa rwho/ information about other systems on the local network; see .Xr rwhod 8 , .Xr rwho 1 , and .Xr ruptime 1 .It Pa spool/ printer and mail system spooling directories .Pp .Bl -tag -width "clientmqueue/" -compact .It Pa clientmqueue/ undelivered submission mail queue; see .Xr sendmail 8 .It Pa cups/ print jobs and temporary files for .Xr cups 1 .It Pa dma/ undelivered mail queue for .Dx Mail Agent; see .Xr dma 8 .It Pa lock/ serial device locks; see .Xr uucplock 3 .It Pa lpd/ line printer spooler daemon spool .It Pa ftp/ ftp root directory; see .Xr ftpd 8 .It Pa mqueue/ undelivered mail queue for .Xr sendmail 8 .It Pa output/ line printer spooling directories .El .Pp .It Pa tmp/ temporary files not removed between system reboots .Pp .Bl -tag -width "vi.recover/" -compact .It Pa vi.recover/ recovery files for the .Xr vi 1 editor .El .Pp .It Pa unbound/ files and configuration for .Xr unbound 8 .It Pa yp/ the NIS maps; see .Xr yp 8 .El .El .Sh NOTES This manual page documents the default .Fx file system layout. The actual hierarchy on a given system is defined at the system administrator's discretion. A well-maintained installation will include a customized version of this document. .Sh SEE ALSO .Xr apropos 1 , .Xr find 1 , .Xr grep 1 , .Xr ls 1 , .Xr whereis 1 , .Xr which 1 .Sh HISTORY A .Nm manual page first appeared in 1979 with .At v7 . diff --git a/share/man/man7/tuning.7 b/share/man/man7/tuning.7 index f04500d0f0dc..caa1efb7d450 100644 --- a/share/man/man7/tuning.7 +++ b/share/man/man7/tuning.7 @@ -1,732 +1,732 @@ .\" Copyright (C) 2001 Matthew Dillon. All rights reserved. .\" Copyright (C) 2012 Eitan Adler. .\" .\" 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 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 November 17, 2023 .Dt TUNING 7 .Os .Sh NAME .Nm tuning .Nd performance tuning under FreeBSD .Sh SYSTEM SETUP - DISKLABEL, NEWFS, TUNEFS, SWAP The swap partition should typically be approximately 2x the size of main memory for systems with less than 4GB of RAM, or approximately equal to the size of main memory if you have more. Keep in mind future memory expansion when sizing the swap partition. Configuring too little swap can lead to inefficiencies in the VM page scanning code as well as create issues later on if you add more memory to your machine. On larger systems with multiple disks, configure swap on each drive. The swap partitions on the drives should be approximately the same size. The kernel can handle arbitrary sizes but internal data structures scale to 4 times the largest swap partition. Keeping the swap partitions near the same size will allow the kernel to optimally stripe swap space across the N disks. Do not worry about overdoing it a little, swap space is the saving grace of .Ux and even if you do not normally use much swap, it can give you more time to recover from a runaway program before being forced to reboot. .Pp It is not a good idea to make one large partition. First, each partition has different operational characteristics and separating them allows the file system to tune itself to those characteristics. For example, the root and .Pa /usr partitions are read-mostly, with very little writing, while a lot of reading and writing could occur in .Pa /var/tmp . By properly partitioning your system fragmentation introduced in the smaller more heavily write-loaded partitions will not bleed over into the mostly-read partitions. .Pp Properly partitioning your system also allows you to tune .Xr newfs 8 , and .Xr tunefs 8 parameters. The only .Xr tunefs 8 option worthwhile turning on is .Em softupdates with .Dq Li "tunefs -n enable /filesystem" . Softupdates drastically improves meta-data performance, mainly file creation and deletion. We recommend enabling softupdates on most file systems; however, there are two limitations to softupdates that you should be aware of when determining whether to use it on a file system. First, softupdates guarantees file system consistency in the case of a crash but could very easily be several seconds (even a minute!\&) behind on pending write to the physical disk. If you crash you may lose more work than otherwise. Secondly, softupdates delays the freeing of file system blocks. If you have a file system (such as the root file system) which is close to full, doing a major update of it, e.g.,\& .Dq Li "make installworld" , can run it out of space and cause the update to fail. For this reason, softupdates will not be enabled on the root file system during a typical install. There is no loss of performance since the root file system is rarely written to. .Pp A number of run-time .Xr mount 8 options exist that can help you tune the system. The most obvious and most dangerous one is .Cm async . Only use this option in conjunction with .Xr gjournal 8 , as it is far too dangerous on a normal file system. A less dangerous and more useful .Xr mount 8 option is called .Cm noatime . .Ux file systems normally update the last-accessed time of a file or directory whenever it is accessed. This operation is handled in .Fx with a delayed write and normally does not create a burden on the system. However, if your system is accessing a huge number of files on a continuing basis the buffer cache can wind up getting polluted with atime updates, creating a burden on the system. For example, if you are running a heavily loaded web site, or a news server with lots of readers, you might want to consider turning off atime updates on your larger partitions with this .Xr mount 8 option. However, you should not gratuitously turn off atime updates everywhere. For example, the .Pa /var file system customarily holds mailboxes, and atime (in combination with mtime) is used to determine whether a mailbox has new mail. You might as well leave atime turned on for mostly read-only partitions such as .Pa / and .Pa /usr as well. This is especially useful for .Pa / since some system utilities use the atime field for reporting. .Sh STRIPING DISKS In larger systems you can stripe partitions from several drives together to create a much larger overall partition. Striping can also improve the performance of a file system by splitting I/O operations across two or more disks. The .Xr gstripe 8 , .Xr gvinum 8 , and .Xr ccdconfig 8 utilities may be used to create simple striped file systems. Generally speaking, striping smaller partitions such as the root and .Pa /var/tmp , or essentially read-only partitions such as .Pa /usr is a complete waste of time. You should only stripe partitions that require serious I/O performance, typically .Pa /var , /home , or custom partitions used to hold databases and web pages. Choosing the proper stripe size is also important. File systems tend to store meta-data on power-of-2 boundaries and you usually want to reduce seeking rather than increase seeking. This means you want to use a large off-center stripe size such as 1152 sectors so sequential I/O does not seek both disks and so meta-data is distributed across both disks rather than concentrated on a single disk. .Sh SYSCTL TUNING .Xr sysctl 8 variables permit system behavior to be monitored and controlled at run-time. Some sysctls simply report on the behavior of the system; others allow the system behavior to be modified; some may be set at boot time using .Xr rc.conf 5 , but most will be set via .Xr sysctl.conf 5 . There are several hundred sysctls in the system, including many that appear to be candidates for tuning but actually are not. In this document we will only cover the ones that have the greatest effect on the system. .Pp The .Va vm.overcommit sysctl defines the overcommit behaviour of the vm subsystem. The virtual memory system always does accounting of the swap space reservation, both total for system and per-user. Corresponding values are available through sysctl .Va vm.swap_total , that gives the total bytes available for swapping, and .Va vm.swap_reserved , that gives number of bytes that may be needed to back all currently allocated anonymous memory. .Pp Setting bit 0 of the .Va vm.overcommit sysctl causes the virtual memory system to return failure to the process when allocation of memory causes .Va vm.swap_reserved to exceed .Va vm.swap_total . Bit 1 of the sysctl enforces .Dv RLIMIT_SWAP limit (see .Xr getrlimit 2 ) . Root is exempt from this limit. Bit 2 allows to count most of the physical memory as allocatable, except wired and free reserved pages (accounted by .Va vm.stats.vm.v_free_target and .Va vm.stats.vm.v_wire_count sysctls, respectively). .Pp The .Va kern.ipc.maxpipekva loader tunable is used to set a hard limit on the amount of kernel address space allocated to mapping of pipe buffers. Use of the mapping allows the kernel to eliminate a copy of the data from writer address space into the kernel, directly copying the content of mapped buffer to the reader. Increasing this value to a higher setting, such as `25165824' might improve performance on systems where space for mapping pipe buffers is quickly exhausted. This exhaustion is not fatal; however, and it will only cause pipes to fall back to using double-copy. .Pp The .Va kern.ipc.shm_use_phys sysctl defaults to 0 (off) and may be set to 0 (off) or 1 (on). Setting this parameter to 1 will cause all System V shared memory segments to be mapped to unpageable physical RAM. This feature only has an effect if you are either (A) mapping small amounts of shared memory across many (hundreds) of processes, or (B) mapping large amounts of shared memory across any number of processes. This feature allows the kernel to remove a great deal of internal memory management page-tracking overhead at the cost of wiring the shared memory into core, making it unswappable. .Pp The .Va vfs.vmiodirenable sysctl defaults to 1 (on). This parameter controls how directories are cached by the system. Most directories are small and use but a single fragment (typically 2K) in the file system and even less (typically 512 bytes) in the buffer cache. However, when operating in the default mode the buffer cache will only cache a fixed number of directories even if you have a huge amount of memory. Turning on this sysctl allows the buffer cache to use the VM Page Cache to cache the directories. The advantage is that all of memory is now available for caching directories. The disadvantage is that the minimum in-core memory used to cache a directory is the physical page size (typically 4K) rather than 512 bytes. We recommend turning this option off in memory-constrained environments; however, when on, it will substantially improve the performance of services that manipulate a large number of files. Such services can include web caches, large mail systems, and news systems. Turning on this option will generally not reduce performance even with the wasted memory but you should experiment to find out. .Pp The .Va vfs.write_behind sysctl defaults to 1 (on). This tells the file system to issue media writes as full clusters are collected, which typically occurs when writing large sequential files. The idea is to avoid saturating the buffer cache with dirty buffers when it would not benefit I/O performance. However, this may stall processes and under certain circumstances you may wish to turn it off. .Pp The .Va vfs.hirunningspace sysctl determines how much outstanding write I/O may be queued to disk controllers system-wide at any given time. It is used by the UFS file system. The default is self-tuned and usually sufficient but on machines with advanced controllers and lots of disks this may be tuned up to match what the controllers buffer. Configuring this setting to match tagged queuing capabilities of controllers or drives with average IO size used in production works best (for example: 16 MiB will use 128 tags with IO requests of 128 KiB). Note that setting too high a value (exceeding the buffer cache's write threshold) can lead to extremely bad clustering performance. Do not set this value arbitrarily high! Higher write queuing values may also add latency to reads occurring at the same time. .Pp The .Va vfs.read_max sysctl governs VFS read-ahead and is expressed as the number of blocks to pre-read if the heuristics algorithm decides that the reads are issued sequentially. It is used by the UFS, ext2fs and msdosfs file systems. With the default UFS block size of 32 KiB, a setting of 64 will allow speculatively reading up to 2 MiB. This setting may be increased to get around disk I/O latencies, especially where these latencies are large such as in virtual machine emulated environments. It may be tuned down in specific cases where the I/O load is such that read-ahead adversely affects performance or where system memory is really low. .Pp The .Va vfs.ncsizefactor sysctl defines how large VFS namecache may grow. The number of currently allocated entries in namecache is provided by .Va debug.numcache sysctl and the condition debug.numcache < kern.maxvnodes * vfs.ncsizefactor is adhered to. .Pp The .Va vfs.ncnegfactor sysctl defines how many negative entries VFS namecache is allowed to create. The number of currently allocated negative entries is provided by .Va debug.numneg sysctl and the condition vfs.ncnegfactor * debug.numneg < debug.numcache is adhered to. .Pp There are various other buffer-cache and VM page cache related sysctls. We do not recommend modifying these values. .Pp The .Va net.inet.tcp.sendspace and .Va net.inet.tcp.recvspace sysctls are of particular interest if you are running network intensive applications. They control the amount of send and receive buffer space allowed for any given TCP connection. The default sending buffer is 32K; the default receiving buffer is 64K. You can often improve bandwidth utilization by increasing the default at the cost of eating up more kernel memory for each connection. We do not recommend increasing the defaults if you are serving hundreds or thousands of simultaneous connections because it is possible to quickly run the system out of memory due to stalled connections building up. But if you need high bandwidth over a fewer number of connections, especially if you have gigabit Ethernet, increasing these defaults can make a huge difference. You can adjust the buffer size for incoming and outgoing data separately. For example, if your machine is primarily doing web serving you may want to decrease the recvspace in order to be able to increase the sendspace without eating too much kernel memory. Note that the routing table (see .Xr route 8 ) can be used to introduce route-specific send and receive buffer size defaults. .Pp As an additional management tool you can use pipes in your firewall rules (see .Xr ipfw 8 ) to limit the bandwidth going to or from particular IP blocks or ports. For example, if you have a T1 you might want to limit your web traffic to 70% of the T1's bandwidth in order to leave the remainder available for mail and interactive use. Normally a heavily loaded web server will not introduce significant latencies into other services even if the network link is maxed out, but enforcing a limit can smooth things out and lead to longer term stability. Many people also enforce artificial bandwidth limitations in order to ensure that they are not charged for using too much bandwidth. .Pp Setting the send or receive TCP buffer to values larger than 65535 will result in a marginal performance improvement unless both hosts support the window scaling extension of the TCP protocol, which is controlled by the .Va net.inet.tcp.rfc1323 sysctl. These extensions should be enabled and the TCP buffer size should be set to a value larger than 65536 in order to obtain good performance from certain types of network links; specifically, gigabit WAN links and high-latency satellite links. RFC1323 support is enabled by default. .Pp The .Va net.inet.tcp.always_keepalive sysctl determines whether or not the TCP implementation should attempt to detect dead TCP connections by intermittently delivering .Dq keepalives on the connection. By default, this is enabled for all applications; by setting this sysctl to 0, only applications that specifically request keepalives will use them. In most environments, TCP keepalives will improve the management of system state by expiring dead TCP connections, particularly for systems serving dialup users who may not always terminate individual TCP connections before disconnecting from the network. However, in some environments, temporary network outages may be incorrectly identified as dead sessions, resulting in unexpectedly terminated TCP connections. In such environments, setting the sysctl to 0 may reduce the occurrence of TCP session disconnections. .Pp The .Va net.inet.tcp.delayed_ack TCP feature is largely misunderstood. Historically speaking, this feature was designed to allow the acknowledgement to transmitted data to be returned along with the response. For example, when you type over a remote shell, the acknowledgement to the character you send can be returned along with the data representing the echo of the character. With delayed acks turned off, the acknowledgement may be sent in its own packet, before the remote service has a chance to echo the data it just received. This same concept also applies to any interactive protocol (e.g.,\& SMTP, WWW, POP3), and can cut the number of tiny packets flowing across the network in half. The .Fx delayed ACK implementation also follows the TCP protocol rule that at least every other packet be acknowledged even if the standard 40ms timeout has not yet passed. Normally the worst a delayed ACK can do is slightly delay the teardown of a connection, or slightly delay the ramp-up of a slow-start TCP connection. While we are not sure we believe that the several FAQs related to packages such as SAMBA and SQUID which advise turning off delayed acks may be referring to the slow-start issue. .Pp The .Va net.inet.ip.portrange.* sysctls control the port number ranges automatically bound to TCP and UDP sockets. There are three ranges: a low range, a default range, and a high range, selectable via the .Dv IP_PORTRANGE .Xr setsockopt 2 call. Most network programs use the default range which is controlled by .Va net.inet.ip.portrange.first and .Va net.inet.ip.portrange.last , which default to 49152 and 65535, respectively. Bound port ranges are used for outgoing connections, and it is possible to run the system out of ports under certain circumstances. This most commonly occurs when you are running a heavily loaded web proxy. The port range is not an issue when running a server which handles mainly incoming connections, such as a normal web server, or has a limited number of outgoing connections, such as a mail relay. For situations where you may run out of ports, we recommend decreasing .Va net.inet.ip.portrange.first modestly. A range of 10000 to 30000 ports may be reasonable. You should also consider firewall effects when changing the port range. Some firewalls may block large ranges of ports (usually low-numbered ports) and expect systems to use higher ranges of ports for outgoing connections. By default .Va net.inet.ip.portrange.last is set at the maximum allowable port number. .Pp The .Va kern.ipc.soacceptqueue sysctl limits the size of the listen queue for accepting new TCP connections. The default value of 128 is typically too low for robust handling of new connections in a heavily loaded web server environment. For such environments, we recommend increasing this value to 1024 or higher. The service daemon may itself limit the listen queue size (e.g.,\& .Xr sendmail 8 , apache) but will often have a directive in its configuration file to adjust the queue size up. Larger listen queues also do a better job of fending off denial of service attacks. .Pp The .Va kern.maxfiles sysctl determines how many open files the system supports. The default is typically a few thousand but you may need to bump this up to ten or twenty thousand if you are running databases or large descriptor-heavy daemons. The read-only .Va kern.openfiles sysctl may be interrogated to determine the current number of open files on the system. .Pp The .Va vm.swap_idle_enabled sysctl is useful in large multi-user systems where you have lots of users entering and leaving the system and lots of idle processes. Such systems tend to generate a great deal of continuous pressure on free memory reserves. Turning this feature on and adjusting the swapout hysteresis (in idle seconds) via .Va vm.swap_idle_threshold1 and .Va vm.swap_idle_threshold2 allows you to depress the priority of pages associated with idle processes more quickly then the normal pageout algorithm. This gives a helping hand to the pageout daemon. Do not turn this option on unless you need it, because the tradeoff you are making is to essentially pre-page memory sooner rather than later, eating more swap and disk bandwidth. In a small system this option will have a detrimental effect but in a large system that is already doing moderate paging this option allows the VM system to stage whole processes into and out of memory more easily. .Sh LOADER TUNABLES Some aspects of the system behavior may not be tunable at runtime because memory allocations they perform must occur early in the boot process. To change loader tunables, you must set their values in .Xr loader.conf 5 and reboot the system. .Pp .Va kern.maxusers controls the scaling of a number of static system tables, including defaults for the maximum number of open files, sizing of network memory resources, etc. .Va kern.maxusers is automatically sized at boot based on the amount of memory available in the system, and may be determined at run-time by inspecting the value of the read-only .Va kern.maxusers sysctl. .Pp The .Va kern.dfldsiz and .Va kern.dflssiz tunables set the default soft limits for process data and stack size respectively. Processes may increase these up to the hard limits by calling .Xr setrlimit 2 . The .Va kern.maxdsiz , .Va kern.maxssiz , and .Va kern.maxtsiz tunables set the hard limits for process data, stack, and text size respectively; processes may not exceed these limits. The .Va kern.sgrowsiz tunable controls how much the stack segment will grow when a process needs to allocate more stack. .Pp .Va kern.ipc.nmbclusters may be adjusted to increase the number of network mbufs the system is willing to allocate. Each cluster represents approximately 2K of memory, so a value of 1024 represents 2M of kernel memory reserved for network buffers. You can do a simple calculation to figure out how many you need. If you have a web server which maxes out at 1000 simultaneous connections, and each connection eats a 16K receive and 16K send buffer, you need approximately 32MB worth of network buffers to deal with it. A good rule of thumb is to multiply by 2, so 32MBx2 = 64MB/2K = 32768. So for this case you would want to set .Va kern.ipc.nmbclusters to 32768. We recommend values between 1024 and 4096 for machines with moderates amount of memory, and between 4096 and 32768 for machines with greater amounts of memory. Under no circumstances should you specify an arbitrarily high value for this parameter, it could lead to a boot-time crash. The .Fl m option to .Xr netstat 1 may be used to observe network cluster use. .Pp More and more programs are using the .Xr sendfile 2 system call to transmit files over the network. The .Va kern.ipc.nsfbufs sysctl controls the number of file system buffers .Xr sendfile 2 is allowed to use to perform its work. This parameter nominally scales with .Va kern.maxusers so you should not need to modify this parameter except under extreme circumstances. See the .Sx TUNING section in the .Xr sendfile 2 manual page for details. .Sh KERNEL CONFIG TUNING There are a number of kernel options that you may have to fiddle with in a large-scale system. In order to change these options you need to be able to compile a new kernel from source. The .Xr config 8 manual page and the handbook are good starting points for learning how to do this. Generally the first thing you do when creating your own custom kernel is to strip out all the drivers and services you do not use. Removing things like .Dv INET6 and drivers you do not have will reduce the size of your kernel, sometimes by a megabyte or more, leaving more memory available for applications. .Pp .Dv SCSI_DELAY may be used to reduce system boot times. The defaults are fairly high and can be responsible for 5+ seconds of delay in the boot process. Reducing .Dv SCSI_DELAY to something below 5 seconds could work (especially with modern drives). .Pp There are a number of .Dv *_CPU options that can be commented out. If you only want the kernel to run on a Pentium class CPU, you can easily remove .Dv I486_CPU , but only remove .Dv I586_CPU if you are sure your CPU is being recognized as a Pentium II or better. Some clones may be recognized as a Pentium or even a 486 and not be able to boot without those options. If it works, great! The operating system will be able to better use higher-end CPU features for MMU, task switching, timebase, and even device operations. Additionally, higher-end CPUs support 4MB MMU pages, which the kernel uses to map the kernel itself into memory, increasing its efficiency under heavy syscall loads. .Sh CPU, MEMORY, DISK, NETWORK The type of tuning you do depends heavily on where your system begins to bottleneck as load increases. If your system runs out of CPU (idle times are perpetually 0%) then you need to consider upgrading the CPU or perhaps you need to revisit the programs that are causing the load and try to optimize them. If your system is paging to swap a lot you need to consider adding more memory. If your system is saturating the disk you typically see high CPU idle times and total disk saturation. .Xr systat 1 can be used to monitor this. There are many solutions to saturated disks: increasing memory for caching, mirroring disks, distributing operations across several machines, and so forth. .Pp Finally, you might run out of network suds. Optimize the network path as much as possible. For example, in .Xr firewall 7 we describe a firewall protecting internal hosts with a topology where the externally visible hosts are not routed through it. Most bottlenecks occur at the WAN link. If expanding the link is not an option it may be possible to use the .Xr dummynet 4 feature to implement peak shaving or other forms of traffic shaping to prevent the overloaded service (such as web services) from affecting other services (such as email), or vice versa. In home installations this could be used to give interactive traffic (your browser, .Xr ssh 1 logins) priority over services you export from your box (web services, email). .Sh SEE ALSO .Xr netstat 1 , .Xr systat 1 , .Xr sendfile 2 , .Xr ata 4 , .Xr dummynet 4 , .Xr eventtimers 4 , +.Xr ffs 4 , .Xr login.conf 5 , .Xr rc.conf 5 , .Xr sysctl.conf 5 , -.Xr ffs 7 , .Xr firewall 7 , .Xr hier 7 , .Xr ports 7 , .Xr boot 8 , .Xr bsdinstall 8 , .Xr ccdconfig 8 , .Xr config 8 , .Xr fsck 8 , .Xr gjournal 8 , .Xr gpart 8 , .Xr gstripe 8 , .Xr gvinum 8 , .Xr ifconfig 8 , .Xr ipfw 8 , .Xr loader 8 , .Xr mount 8 , .Xr newfs 8 , .Xr route 8 , .Xr sysctl 8 , .Xr tunefs 8 .Sh HISTORY The .Nm manual page was originally written by .An Matthew Dillon and first appeared in .Fx 4.3 , May 2001. The manual page was greatly modified by .An Eitan Adler Aq Mt eadler@FreeBSD.org . diff --git a/share/man/man8/uefi.8 b/share/man/man8/uefi.8 index 42642bb48260..7a684f6b092b 100644 --- a/share/man/man8/uefi.8 +++ b/share/man/man8/uefi.8 @@ -1,134 +1,134 @@ .\" Copyright (c) 2014 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 August 31, 2023 .Dt UEFI 8 .Os .Sh NAME .Nm UEFI .Nd Unified Extensible Firmware Interface bootstrapping procedures .Sh DESCRIPTION The .Nm Unified Extensible Firmware Interface provides boot- and run-time services to operating systems. .Nm is a replacement for the legacy BIOS on the i386 and amd64 CPU architectures, and is also used on arm, arm64 and riscv architectures. .Pp The UEFI specification is the successor to the Extensible Firmware Interface (EFI) specification. The terms UEFI and EFI are often used interchangeably. .Pp The .Nm boot process loads system bootstrap code located in an EFI System Partition (ESP). The ESP is a GPT or MBR partition with a specific identifier that contains an -.Xr msdosfs 5 +.Xr msdosfs 4 FAT file system with a specified file hierarchy. .Bl -column -offset indent "Partition Scheme" "ESP Identifier" .It Sy "Partition Scheme" Ta Sy "ESP Identifier" .It GPT Ta C12A7328-F81F-11D2-BA4B-00A0C93EC93B .It MBR Ta 0xEF .El .Pp The .Nm boot process proceeds as follows: .Bl -enum -offset indent -compact .It .Nm firmware runs at power up and searches for an OS loader in the EFI system partition. The path to the loader may be set by an EFI environment variable managed by .Xr efibootmgr 8 . If not set, an architecture-specific default is used. .Bl -column -offset indent "Architecture" "Default Path" .It Sy Architecture Ta Sy Default Path .It amd64 Ta Pa /EFI/BOOT/BOOTX64.EFI .It arm Ta Pa /EFI/BOOT/BOOTARM.EFI .It arm64 Ta Pa /EFI/BOOT/BOOTAA64.EFI .It i386 Ta Pa /EFI/BOOT/BOOTIA32.EFI .It riscv Ta Pa /EFI/BOOT/BOOTRISCV64.EFI .El .Pp The default .Nm boot configuration for .Fx installs .Pa loader.efi in the default path. .It .Pa loader.efi reads boot configuration from .Pa /boot.config or .Pa /boot/config . .It .Pa loader.efi loads and boots the kernel, as described in .Xr loader.efi 8 . .El .Pp The .Xr vt 4 system console is automatically selected when booting via .Nm . .Sh FILES .Bl -tag -width /boot/loader -compact .Nm bootstrap .It Pa /boot/loader.efi Final stage bootstrap .It Pa /boot/kernel/kernel Default kernel .It Pa /boot/kernel.old/kernel Typical non-default kernel (optional) .El .Sh SEE ALSO .Xr vt 4 , .Xr boot.config 5 , -.Xr msdosfs 5 , +.Xr msdosfs 4 , .Xr boot 8 , .Xr efibootmgr 8 , .Xr efidp 8 , .Xr efivar 8 , .Xr gpart 8 , .Xr loader.efi 8 , .Xr uefisign 8 .Sh HISTORY EFI boot support for the ia64 architecture first appeared in .Fx 5.0 . .Nm boot support for amd64 first appeared in .Fx 10.1 ; for arm64 in .Fx 11.0 ; for armv6 and armv7 in .Fx 12.0 ; and for riscv in .Fx 13.0 . .Sh BUGS There is no support for 32-bit i386 booting via UEFI. diff --git a/share/man/man9/DEVICE_ATTACH.9 b/share/man/man9/DEVICE_ATTACH.9 index 0946e1f13b7c..083a0e86f0bc 100644 --- a/share/man/man9/DEVICE_ATTACH.9 +++ b/share/man/man9/DEVICE_ATTACH.9 @@ -1,69 +1,69 @@ .\" -*- nroff -*- .\" .\" Copyright (c) 1998 Doug Rabson .\" .\" 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 January 15, 2017 .Dt DEVICE_ATTACH 9 .Os .Sh NAME .Nm DEVICE_ATTACH .Nd attach a device .Sh SYNOPSIS .In sys/param.h .In sys/bus.h .Ft int .Fn DEVICE_ATTACH "device_t dev" .Sh DESCRIPTION Attach a device to the system after the .Fn DEVICE_PROBE method has been called and has indicated that the device exists. The .Fn DEVICE_ATTACH method should initialize the hardware and allocate other system resources (such as -.Xr devfs 5 +.Xr devfs 4 entries). .Pp Devices which implement buses should use this method to probe for the existence of devices attached to the bus and add them as children. If this is combined with the use of .Xr bus_generic_attach 9 the child devices will be automatically probed and attached. .Sh RETURN VALUES Zero is returned on success, otherwise an appropriate error is returned. .Sh SEE ALSO -.Xr devfs 5 , +.Xr devfs 4 , .Xr device 9 , .Xr DEVICE_DETACH 9 , .Xr DEVICE_IDENTIFY 9 , .Xr DEVICE_PROBE 9 , .Xr DEVICE_SHUTDOWN 9 .Sh AUTHORS This manual page was written by .An Doug Rabson Aq Mt dfr@FreeBSD.org . diff --git a/share/man/man9/dev_clone.9 b/share/man/man9/dev_clone.9 index f5f59e3c6666..56bdd1a9a248 100644 --- a/share/man/man9/dev_clone.9 +++ b/share/man/man9/dev_clone.9 @@ -1,76 +1,76 @@ .\" Copyright (c) 2008 Konstantin Belousov .\" 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 3, 2009 .Dt DEV_CLONE 9 .Os .Sh NAME .Nm dev_clone , .Nm drain_dev_clone_events .Nd eventhandler for name-based device cloning in devfs .Sh SYNOPSIS .In sys/param.h .In sys/conf.h .Ft void .Fn clone_handler "void *arg" "struct ucred *cr" "char *name" "int namelen" "struct cdev **dev" .Bd -literal EVENTHANDLER_REGISTER(dev_clone, clone_handler, arg, priority); .Ed .Ft void .Fn drain_dev_clone_events .Sh DESCRIPTION A device driver may register a listener that will be notified each time a name lookup on the -.Xr devfs 5 +.Xr devfs 4 mount point fails to find the vnode. A listener shall be registered for the .Va dev_clone event. When called, it is supplied with the first argument .Va arg that was specified at handler registration time, appropriate credentials .Va cr , and a name .Va name of length .Va namelen that we look for. If the handler decides that the name is appropriate and wants to create the device that will be associated with the name, it should return it to devfs in the .Va dev argument. .Pp The .Fn drain_dev_clone_events function is a barrier. It is guaranteed that all calls to eventhandlers for .Nm dev_clone that were started before .Fn drain_dev_clone_events call, are finished before it returns control. .Sh SEE ALSO -.Xr devfs 5 , +.Xr devfs 4 , .Xr namei 9 diff --git a/share/man/man9/dev_refthread.9 b/share/man/man9/dev_refthread.9 index e12b5f49a0e5..f615725b0a47 100644 --- a/share/man/man9/dev_refthread.9 +++ b/share/man/man9/dev_refthread.9 @@ -1,151 +1,151 @@ .\" Copyright (c) 2018 Conrad Meyer .\" 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 29, 2018 .Dt DEV_REFTHREAD 9 .Os .Sh NAME .Nm dev_refthread , .Nm devvn_refthread , .Nm dev_relthread .Nd safely access device methods .Sh SYNOPSIS .In sys/param.h .In sys/conf.h .Ft "struct cdevsw *" .Fn dev_refthread "struct cdev *dev" "int *ref" .Ft "struct cdevsw *" .Fn devvn_refthread "struct vnode *vp" "struct cdev **devp" "int *ref" .Ft void .Fn dev_relthread "struct cdev *dev" "int ref" .Sh DESCRIPTION The .Fn dev_refthread (or .Fn devvn_refthread ) and .Fn dev_relthread routines provide a safe way to access -.Xr devfs 5 +.Xr devfs 4 devices that may be concurrently destroyed by .Fn destroy_dev (e.g., removable media). .Pp If successful, .Fn dev_refthread and .Fn devvn_refthread acquire a "thread reference" to the associated .Vt "struct cdev" and return a non-NULL pointer to the cdev's .Vt "struct cdevsw" method table. For the duration of that reference, the cdev's associated private data and method table object are valid. Destruction of the cdev sleeps until the thread reference is released. .Pp A reference cannot prevent media removal. It is an implementation detail of individual drivers how method calls from callers with .Fn dev_refthread references are handled when the device is pending destruction. A common behavior for disk devices is to return the .Er ENXIO status, but that is not required by this KPI. .Pp The .Fn devvn_refthread variant of .Fn dev_refthread extracts the .Vt "struct cdev" pointer out of the .Dv VCHR .Xr vnode 9 automatically before performing the same actions as .Fn dev_refthread . Additionally, a pointer to the .Vt "struct cdev" is returned to the caller via .Fa "*devp" . .Fn devvn_refthread correctly handles possible parallel reclamation of the vnode. .Pp .Fn dev_relthread is used to release a reference to a .Vt "struct cdev" . .Fn dev_relthread .Sy must only be invoked when the associated invocation of .Fn dev_refthread or .Fn devvn_refthread returned a non-NULL .Vt "struct cdevsw *" . .Sh CONTEXT .Vt struct cdev objects have two reference counts, .Va si_refcount and .Va si_threadcount . The .Fn dev_refthread , .Fn devvn_refthread , and .Fn dev_relthread functions manipulate the .Va si_threadcount . The .Va si_threadcount reference guarantees the liveness of the .Vt struct cdev object. The other .Va si_refcount reference provides only the weaker guarantee that the memory backing the .Vt struct cdev has not been freed. .Sh RETURN VALUES If .Fn dev_refthread or .Fn devvn_refthread are unsuccessful, they return .Dv NULL . .Bf Em If these routines are unsuccessful, they do not increment the .Vt "struct cdev" .Va si_threadcount and do not initialize the value pointed to by the .Fa "*ref" parameter in any way. .Ef .Sh SEE ALSO -.Xr devfs 5 , +.Xr devfs 4 , .Xr destroy_dev 9 .Sh CAVEATS Do not invoke .Fn dev_relthread unless the matching refthread routine succeeded! diff --git a/share/man/man9/devfs_set_cdevpriv.9 b/share/man/man9/devfs_set_cdevpriv.9 index 3258ca082e5f..0cbfd3eebeb7 100644 --- a/share/man/man9/devfs_set_cdevpriv.9 +++ b/share/man/man9/devfs_set_cdevpriv.9 @@ -1,159 +1,159 @@ .\" Copyright (c) 2008 Konstantin Belousov .\" 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 March 23, 2024 .Dt DEVFS_CDEVPRIV 9 .Os .Sh NAME .Nm devfs_set_cdevpriv , .Nm devfs_get_cdevpriv , .Nm devfs_clear_cdevpriv , .Nm devfs_foreach_cdevpriv .Nd manage per-open filedescriptor data for devices .Sh SYNOPSIS .In sys/param.h .In sys/conf.h .Bd -literal typedef void d_priv_dtor_t(void *data); .Ed .Ft int .Fn devfs_get_cdevpriv "void **datap" .Ft int .Fn devfs_set_cdevpriv "void *priv" "d_priv_dtor_t *dtr" .Ft void .Fn devfs_clear_cdevpriv "void" .Ft int .Fo devfs_foreach_cdevpriv .Fa "struct cdev *dev" .Fa "int (*cb)(void *data, void *arg)" .Fa "void *arg" .Fc .Sh DESCRIPTION The .Fn devfs_xxx_cdevpriv family of functions allows the .Fa cdev driver methods to associate some driver-specific data with each user process .Xr open 2 of the device special file. Currently, functioning of these functions is restricted to the context of the .Fa cdevsw switch method calls performed as -.Xr devfs 5 +.Xr devfs 4 operations in response to system calls that use filedescriptors. .Pp The .Fn devfs_set_cdevpriv function associates a data pointed by .Va priv with current calling context (filedescriptor). The data may be retrieved later, possibly from another call performed on this filedescriptor, by the .Fn devfs_get_cdevpriv function. The .Fn devfs_clear_cdevpriv disassociates previously attached data from context. Immediately after .Fn devfs_clear_cdevpriv finished operating, the .Va dtr callback is called, with private data supplied .Va data argument. The .Fn devfs_clear_cdevpriv function will be also be called if the open callback function returns an error code. .Pp On the last filedescriptor close, system automatically arranges .Fn devfs_clear_cdevpriv call. .Pp If successful, the functions return 0. .Pp The function .Fn devfs_set_cdevpriv returns the following values on error: .Bl -tag -width Er .It Bq Er ENOENT The current call is not associated with some filedescriptor. .It Bq Er EBUSY The private driver data is already associated with current filedescriptor. .El .Pp The function .Fn devfs_get_cdevpriv returns the following values on error: .Bl -tag -width Er .It Bq Er EBADF The current call is not associated with some filedescriptor. .It Bq Er ENOENT The private driver data was not associated with current filedescriptor, or .Fn devfs_clear_cdevpriv was called. .El .Pp The function .Fn devfs_foreach_cdevpriv sequentially calls the function .Fa cb for each .Nm cdevpriv structure, currently associated with the .Fa cdev device. The iterated .Nm cdevpriv data pointer and the user-supplied context .Fa arg are passed to the function .Fa cb . If .Fa cb returns non-zero value, the iteration stops on that element. The .Fn devfs_foreach_cdevpriv returns the return value from the last call to .Fa cb , or zero if no .Nm cdevpriv data is currently associated with the device. .Pp Current implementation of the iterator makes it impossible to use any blockable locking inside the callback .Fa cb . .Sh SEE ALSO .Xr close 2 , .Xr open 2 , -.Xr devfs 5 +.Xr devfs 4 .Sh HISTORY The .Fn devfs_cdevpriv family of functions first appeared in .Fx 7.1 . diff --git a/share/man/man9/disk.9 b/share/man/man9/disk.9 index 047abb96c619..41436427cbc2 100644 --- a/share/man/man9/disk.9 +++ b/share/man/man9/disk.9 @@ -1,259 +1,259 @@ .\" .\" Copyright (c) 2003 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(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 April 30, 2020 .Dt DISK 9 .Os .Sh NAME .Nm disk .Nd kernel disk storage API .Sh SYNOPSIS .In geom/geom_disk.h .Ft struct disk * .Fn disk_alloc void .Ft void .Fn disk_create "struct disk *disk" "int version" .Ft void .Fn disk_gone "struct disk *disk" .Ft void .Fn disk_destroy "struct disk *disk" .Ft int .Fn disk_resize "struct disk *disk" "int flags" .Ft void .Fn disk_add_alias "struct disk *disk" "const char *alias" .Sh DESCRIPTION The disk storage API permits kernel device drivers providing access to disk-like storage devices to advertise the device to other kernel components, including .Xr GEOM 4 and -.Xr devfs 5 . +.Xr devfs 4 . .Pp Each disk device is described by a .Vt "struct disk" structure, which contains a variety of parameters for the disk device, function pointers for various methods that may be performed on the device, as well as private data storage for the device driver. In addition, some fields are reserved for use by GEOM in managing access to the device and its statistics. .Pp GEOM has the ownership of .Vt "struct disk" , and drivers must allocate storage for it with the .Fn disk_alloc function, fill in the fields and call .Fn disk_create when the device is ready to service requests. .Fn disk_add_alias adds an alias for the disk and must be called before .Fn disk_create , but may be called multiple times. For each alias added, a device node will be created with .Xr make_dev_alias 9 in the same way primary device nodes are created with .Xr make_dev 9 for .Va d_name and .Va d_unit . Care should be taken to ensure that only one driver creates aliases for any given name. .Fn disk_resize can be called by the driver after modifying .Va d_mediasize to notify GEOM about the disk capacity change. The .Fa flags field should be set to either M_WAITOK, or M_NOWAIT. .Fn disk_gone orphans all of the providers associated with the drive, setting an error condition of ENXIO in each one. In addition, it prevents a re-taste on last close for writing if an error condition has been set in the provider. After calling .Fn disk_destroy , the device driver is not allowed to access the contents of .Vt "struct disk" anymore. .Pp The .Fn disk_create function takes a second parameter, .Fa version , which must always be passed .Dv DISK_VERSION . If GEOM detects that the driver is compiled against an unsupported version, it will ignore the device and print a warning on the console. .Ss Descriptive Fields The following fields identify the disk device described by the structure instance, and must be filled in prior to submitting the structure to .Fn disk_create and may not be subsequently changed: .Bl -tag -width indent .It Vt u_int Va d_flags Optional flags indicating to the storage framework what optional features or descriptions the storage device driver supports. Currently supported flags are .Dv DISKFLAG_OPEN (maintained by storage framework), .Dv DISKFLAG_CANDELETE (maintained by device driver), and .Dv DISKFLAG_CANFLUSHCACHE (maintained by device driver). .It Vt "const char *" Va d_name Holds the name of the storage device class, e.g., .Dq Li ahd . This value typically uniquely identifies a particular driver device, and must not conflict with devices serviced by other device drivers. .It Vt u_int Va d_unit Holds the instance of the storage device class, e.g., .Dq Li 4 . This namespace is managed by the device driver, and assignment of unit numbers might be a property of probe order, or in some cases topology. Together, the .Va d_name and .Va d_unit values will uniquely identify a disk storage device. .El .Ss Disk Device Methods The following fields identify various disk device methods, if implemented: .Bl -tag -width indent .It Vt "disk_open_t *" Va d_open Optional: invoked when the disk device is opened. If no method is provided, open will always succeed. .It Vt "disk_close_t *" Va d_close Optional: invoked when the disk device is closed. Although an error code may be returned, the call should always terminate any state setup by the corresponding open method call. .It Vt "disk_strategy_t *" Va d_strategy Mandatory: invoked when a new .Vt "struct bio" is to be initiated on the disk device. .It Vt "disk_ioctl_t *" Va d_ioctl Optional: invoked when an I/O control operation is initiated on the disk device. Please note that for security reasons these operations should not be able to affect other devices than the one on which they are performed. .It Vt "dumper_t *" Va d_dump Optional: if configured with .Xr dumpon 8 , this function is invoked from a very restricted system state after a kernel panic to record a copy of the system RAM to the disk. .It Vt "disk_getattr_t *" Va d_getattr Optional: if this method is provided, it gives the disk driver the opportunity to override the default GEOM response to BIO_GETATTR requests. This function should return -1 if the attribute is not handled, 0 if the attribute is handled, or an errno to be passed to .Fn g_io_deliver . .It Vt "disk_gone_t *" Va d_gone Optional: if this method is provided, it will be called after .Fn disk_gone is called, once GEOM has finished its cleanup process. Once this callback is called, it is safe for the disk driver to free all of its resources, as it will not be receiving further calls from GEOM. .El .Ss Mandatory Media Properties The following fields identify the size and granularity of the disk device. These fields must stay stable from return of the drivers open method until the close method is called, but it is perfectly legal to modify them in the open method before returning. .Bl -tag -width indent .It Vt u_int Va d_sectorsize The sector size of the disk device in bytes. .It Vt off_t Va d_mediasize The size of the disk device in bytes. .It Vt u_int Va d_maxsize The maximum supported size in bytes of an I/O request. Requests larger than this size will be chopped up by GEOM. .El .Ss Optional Media Properties These optional fields can provide extra information about the disk device. Do not initialize these fields if the field/concept does not apply. These fields must stay stable from return of the drivers open method until the close method is called, but it is perfectly legal to modify them in the open method before returning. .Bl -tag -width indent .It Vt u_int Va d_fwsectors , Vt u_int Va d_fwheads The number of sectors and heads advertised on the disk device by the firmware or BIOS. These values are almost universally bogus, but on some architectures necessary for the correct calculation of disk partitioning. .It Vt u_int Va d_stripeoffset , Vt u_int Va d_stripesize These two fields can be used to describe the width and location of natural performance boundaries for most disk technologies. Please see .Pa src/sys/geom/notes for details. .It Vt char Va d_ident[DISK_IDENT_SIZE] This field can and should be used to store disk's serial number if the d_getattr method described above isn't implemented, or if it does not support the GEOM::ident attribute. .It Vt char Va d_descr[DISK_IDENT_SIZE] This field can be used to store the disk vendor and product description. .It Vt uint16_t Va d_hba_vendor This field can be used to store the PCI vendor ID for the HBA connected to the disk. .It Vt uint16_t Va d_hba_device This field can be used to store the PCI device ID for the HBA connected to the disk. .It Vt uint16_t Va d_hba_subvendor This field can be used to store the PCI subvendor ID for the HBA connected to the disk. .It Vt uint16_t Va d_hba_subdevice This field can be used to store the PCI subdevice ID for the HBA connected to the disk. .El .Ss Driver Private Data This field may be used by the device driver to store a pointer to private data to implement the disk service. .Bl -tag -width indent .It Vt "void *" Va d_drv1 Private data pointer. Typically used to store a pointer to the drivers .Vt softc structure for this disk device. .El .Sh SEE ALSO -.Xr GEOM 4 , -.Xr devfs 5 +.Xr devfs 4 , +.Xr GEOM 4 .Sh HISTORY The .Nm kernel disk storage API first appeared in .Fx 4.9 . .Sh AUTHORS This manual page was written by .An Robert Watson . .Sh BUGS Disk aliases are not a general purpose aliasing mechanism, but are intended only to ease the transition from one name to another. They can be used to ensure that nvd0 and nda0 are the same thing. They cannot be used to implement the diskX concept from macOS. diff --git a/share/man/man9/g_provider.9 b/share/man/man9/g_provider.9 index d421af3b1264..940772b26fa5 100644 --- a/share/man/man9/g_provider.9 +++ b/share/man/man9/g_provider.9 @@ -1,143 +1,143 @@ .\" .\" Copyright (c) 2004 Pawel Jakub Dawidek .\" 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 January 16, 2004 .Dt G_PROVIDER 9 .Os .Sh NAME .Nm g_new_providerf , .Nm g_destroy_provider , .Nm g_error_provider .Nd "GEOM providers management" .Sh SYNOPSIS .In geom/geom.h .Ft "struct g_provider *" .Fn g_new_providerf "struct g_geom *gp" "const char *fmt" ... .Ft void .Fn g_destroy_provider "struct g_provider *pp" .Ft void .Fn g_error_provider "struct g_provider *pp" "int error" .Sh DESCRIPTION A GEOM provider is the front gate at which a geom offers service. A provider is .Dq a disk-like thing which appears in Pa /dev \[en] a logical disk in other words. All providers have three main properties: name, sectorsize and size. .Pp The .Fn g_new_providerf function creates a new provider on given geom .Fa gp . The name of the provider, which will appear as device in -.Xr devfs 5 , +.Xr devfs 4 , is created in a .Xr printf 3 Ns -like way from the rest of the arguments. After creation, the caller has to set the provider's .Va mediasize and .Va sectorsize , as well as other desired initializations, and then call .Fn g_error_provider to reset the provider's error, which is initially set to .Er ENXIO . .Pp The .Fn g_destroy_provider function destroys the given provider, cancels all related pending events and removes the corresponding devfs entry. .Pp The .Fn g_error_provider function is used to set the provider's error value. If set to a nonzero, all I/O requests will be denied, as well as increasing its access count will not be possible (error .Fa error will be returned). .Sh RESTRICTIONS/CONDITIONS .Fn g_new_provider : .Bl -item -offset indent .It The provider name should be unique, but this is not enforced by GEOM. If the name is not unique, one will end up with two (or more) files with the same name, which is a programmer error. .It The geom .Fa gp has to have a .Fa start method defined. .It The topology lock has to be held. .El .Pp .Fn g_destroy_provider : .Bl -item -offset indent .It The provider must not have consumers attached. .It The access count has to be 0. .It The topology lock has to be held. .El .Sh RETURN VALUES The .Fn g_new_providerf function returns a pointer to the newly created provider. .Sh EXAMPLES Create an example provider, set its parameters and make it usable. .Bd -literal -offset indent struct g_provider * create_example_provider(struct g_geom *gp) { struct g_provider *pp; g_topology_lock(); pp = g_new_providerf(gp, "example_provider"); g_topology_unlock(); pp->mediasize = 65536; pp->sectorsize = 512; g_error_provider(pp, 0); return (pp); } .Ed .Sh SEE ALSO .Xr geom 4 , .Xr DECLARE_GEOM_CLASS 9 , .Xr g_access 9 , .Xr g_attach 9 , .Xr g_bio 9 , .Xr g_consumer 9 , .Xr g_data 9 , .Xr g_event 9 , .Xr g_geom 9 , .Xr g_provider_by_name 9 , .Xr g_wither_geom 9 .Sh AUTHORS .An -nosplit This manual page was written by .An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org . diff --git a/share/man/man9/make_dev.9 b/share/man/man9/make_dev.9 index 2beb38586593..5428b4c7a74e 100644 --- a/share/man/man9/make_dev.9 +++ b/share/man/man9/make_dev.9 @@ -1,490 +1,490 @@ .\" Copyright (c) 1999 Chris Costello .\" 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 March 2, 2016 .Dt MAKE_DEV 9 .Os .Sh NAME .Nm make_dev , .Nm make_dev_cred , .Nm make_dev_credf , .Nm make_dev_p , .Nm make_dev_s , .Nm make_dev_alias , .Nm make_dev_alias_p , .Nm destroy_dev , .Nm destroy_dev_sched , .Nm destroy_dev_sched_cb , .Nm destroy_dev_drain , .Nm dev_depends .Nd manage .Vt cdev Ns 's and DEVFS registration for devices .Sh SYNOPSIS .In sys/param.h .In sys/conf.h .Ft void .Fn make_dev_args_init "struct make_dev_args *args" .Ft int .Fn make_dev_s "struct make_dev_args *args" "struct cdev **cdev" "const char *fmt" ... .Ft int .Fn make_dev_alias_p "int flags" "struct cdev **cdev" "struct cdev *pdev" "const char *fmt" ... .Ft void .Fn destroy_dev "struct cdev *dev" .Ft void .Fn destroy_dev_sched "struct cdev *dev" .Ft void .Fn destroy_dev_sched_cb "struct cdev *dev" "void (*cb)(void *)" "void *arg" .Ft void .Fn destroy_dev_drain "struct cdevsw *csw" .Ft void .Fn dev_depends "struct cdev *pdev" "struct cdev *cdev" .Pp LEGACY INTERFACES .Ft struct cdev * .Fn make_dev "struct cdevsw *cdevsw" "int unit" "uid_t uid" "gid_t gid" "int perms" "const char *fmt" ... .Ft struct cdev * .Fn make_dev_cred "struct cdevsw *cdevsw" "int unit" "struct ucred *cr" "uid_t uid" "gid_t gid" "int perms" "const char *fmt" ... .Ft struct cdev * .Fn make_dev_credf "int flags" "struct cdevsw *cdevsw" "int unit" "struct ucred *cr" "uid_t uid" "gid_t gid" "int perms" "const char *fmt" ... .Ft int .Fn make_dev_p "int flags" "struct cdev **cdev" "struct cdevsw *devsw" "struct ucred *cr" "uid_t uid" "gid_t gid" "int mode" "const char *fmt" ... .Ft struct cdev * .Fn make_dev_alias "struct cdev *pdev" "const char *fmt" ... .Sh DESCRIPTION The .Fn make_dev_s function creates a .Fa cdev structure for a new device, which is returned into the .Fa cdev argument. It also notifies -.Xr devfs 5 +.Xr devfs 4 of the presence of the new device, that causes corresponding nodes to be created. Besides this, a .Xr devctl 4 notification is sent. The function takes the structure .Va struct make_dev_args args , which specifies the parameters for the device creation: .Pp .Bd -literal -offset indent -compact struct make_dev_args { size_t mda_size; int mda_flags; struct cdevsw *mda_devsw; struct ucred *mda_cr; uid_t mda_uid; gid_t mda_gid; int mda_mode; int mda_unit; void *mda_si_drv1; void *mda_si_drv2; }; .Ed Before use and filling with the desired values, the structure must be initialized by the .Fn make_dev_args_init function, which ensures that future kernel interface expansion does not affect driver source code or binary interface. .Pp The created device will be owned by .Va args.mda_uid , with the group ownership as .Va args.mda_gid . The name is the expansion of .Va fmt and following arguments as .Xr printf 9 would print it. The name determines its path under .Pa /dev or other -.Xr devfs 5 +.Xr devfs 4 mount point and may contain slash .Ql / characters to denote subdirectories. The permissions of the file specified in .Va args.mda_mode are defined in .In sys/stat.h : .Pp .Bd -literal -offset indent -compact #define S_IRWXU 0000700 /* RWX mask for owner */ #define S_IRUSR 0000400 /* R for owner */ #define S_IWUSR 0000200 /* W for owner */ #define S_IXUSR 0000100 /* X for owner */ #define S_IRWXG 0000070 /* RWX mask for group */ #define S_IRGRP 0000040 /* R for group */ #define S_IWGRP 0000020 /* W for group */ #define S_IXGRP 0000010 /* X for group */ #define S_IRWXO 0000007 /* RWX mask for other */ #define S_IROTH 0000004 /* R for other */ #define S_IWOTH 0000002 /* W for other */ #define S_IXOTH 0000001 /* X for other */ #define S_ISUID 0004000 /* set user id on execution */ #define S_ISGID 0002000 /* set group id on execution */ #define S_ISVTX 0001000 /* sticky bit */ #ifndef _POSIX_SOURCE #define S_ISTXT 0001000 #endif .Ed .Pp The .Va args.mda_cr argument specifies credentials that will be stored in the .Fa si_cred member of the initialized .Fa struct cdev . .Pp The .Va args.mda_flags argument alters the operation of .Fn make_dev_s. The following values are currently accepted: .Pp .Bl -tag -width "It Dv MAKEDEV_CHECKNAME" -compact -offset indent .It Dv MAKEDEV_REF reference the created device .It Dv MAKEDEV_NOWAIT do not sleep, the call may fail .It Dv MAKEDEV_WAITOK allow the function to sleep to satisfy malloc .It Dv MAKEDEV_ETERNAL created device will be never destroyed .It Dv MAKEDEV_CHECKNAME return an error if the device name is invalid or already exists .El .Pp Only .Dv MAKEDEV_NOWAIT , .Dv MAKEDEV_WAITOK and .Dv MAKEDEV_CHECKNAME values are accepted for the .Fn make_dev_alias_p function. .Pp The .Dv MAKEDEV_WAITOK flag is assumed if none of .Dv MAKEDEV_WAITOK , .Dv MAKEDEV_NOWAIT is specified. .Pp The .Xr dev_clone 9 event handler shall specify .Dv MAKEDEV_REF flag when creating a device in response to lookup, to avoid race where the device created is destroyed immediately after .Xr devfs_lookup 9 drops his reference to cdev. .Pp The .Dv MAKEDEV_ETERNAL flag allows the kernel to not acquire some locks when translating system calls into the cdevsw methods calls. It is responsibility of the driver author to make sure that .Fn destroy_dev is never called on the returned cdev. For the convenience, use the .Dv MAKEDEV_ETERNAL_KLD flag for the code that can be compiled into kernel or loaded (and unloaded) as loadable module. .Pp A panic will occur if the .Dv MAKEDEV_CHECKNAME flag is not specified and the device name is invalid or already exists. .Pp The .Fn make_dev_p use of the form .Bd -literal -offset indent struct cdev *dev; int res; res = make_dev_p(flags, &dev, cdevsw, cred, uid, gid, perms, name); .Ed is equivalent to the code .Bd -literal -offset indent struct cdev *dev; struct make_dev_args args; int res; make_dev_args_init(&args); args.mda_flags = flags; args.mda_devsw = cdevsw; args.mda_cred = cred; args.mda_uid = uid; args.mda_gid = gid; args.mda_mode = perms; res = make_dev_s(&args, &dev, name); .Ed .Pp Similarly, the .Fn make_dev_credf function call is equivalent to .Bd -literal -offset indent (void) make_dev_s(&args, &dev, name); .Ed In other words, .Fn make_dev_credf does not allow the caller to obtain the return value, and in kernels compiled with the .Va INVARIANTS options, the function asserts that the device creation succeeded. .Pp The .Fn make_dev_cred function is equivalent to the call .Bd -literal -offset indent make_dev_credf(0, cdevsw, unit, cr, uid, gid, perms, fmt, ...); .Ed .Pp The .Fn make_dev function call is the same as .Bd -literal -offset indent make_dev_credf(0, cdevsw, unit, NULL, uid, gid, perms, fmt, ...); .Ed .Pp The .Fn make_dev_alias_p function takes the returned .Ft cdev from .Fn make_dev and makes another (aliased) name for this device. It is an error to call .Fn make_dev_alias_p prior to calling .Fn make_dev . .Pp The .Fn make_dev_alias function is similar to .Fn make_dev_alias_p but it returns the resulting aliasing .Ft *cdev and may not return an error. .Pp The .Fa cdev returned by .Fn make_dev_s and .Fn make_dev_alias_p has two fields, .Fa si_drv1 and .Fa si_drv2 , that are available to store state. Both fields are of type .Ft void * , and can be initialized simultaneously with the .Va cdev allocation by filling .Va args.mda_si_drv1 and .Va args.mda_si_drv2 members of the .Fn make_dev_s argument structure, or filled after the .Va cdev is allocated, if using legacy interfaces. In the latter case, the driver should handle the race of accessing uninitialized .Va si_drv1 and .Va si_drv2 itself. These are designed to replace the .Fa unit argument to .Fn make_dev , which can be obtained with .Fn dev2unit . .Pp The .Fn destroy_dev function takes the returned .Fa cdev from .Fn make_dev and destroys the registration for that device. The notification is sent to .Xr devctl 4 about the destruction event. Do not call .Fn destroy_dev on devices that were created with .Fn make_dev_alias . .Pp The .Fn dev_depends function establishes a parent-child relationship between two devices. The net effect is that a .Fn destroy_dev of the parent device will also result in the destruction of the child device(s), if any exist. A device may simultaneously be a parent and a child, so it is possible to build a complete hierarchy. .Pp The .Fn destroy_dev_sched_cb function schedules execution of the .Fn destroy_dev for the specified .Fa cdev in the safe context. After .Fn destroy_dev is finished, and if the supplied .Fa cb is not .Dv NULL , the callback .Fa cb is called, with argument .Fa arg . The .Fn destroy_dev_sched function is the same as .Bd -literal -offset indent destroy_dev_sched_cb(cdev, NULL, NULL); .Ed .Pp The .Fn d_close driver method cannot call .Fn destroy_dev directly. Doing so causes deadlock when .Fn destroy_dev waits for all threads to leave the driver methods. Also, because .Fn destroy_dev sleeps, no non-sleepable locks may be held over the call. The .Fn destroy_dev_sched family of functions overcome these issues. .Pp The device driver may call the .Fn destroy_dev_drain function to wait until all devices that have supplied .Fa csw as cdevsw, are destroyed. This is useful when driver knows that .Fn destroy_dev_sched is called for all instantiated devices, but need to postpone module unload until .Fn destroy_dev is actually finished for all of them. .Sh RETURN VALUES If successful, .Fn make_dev_s and .Fn make_dev_p will return 0, otherwise they will return an error. If successful, .Fn make_dev_credf will return a valid .Fa cdev pointer, otherwise it will return .Dv NULL . .Sh ERRORS The .Fn make_dev_s , .Fn make_dev_p and .Fn make_dev_alias_p calls will fail and the device will be not registered if: .Bl -tag -width Er .It Bq Er ENOMEM The .Dv MAKEDEV_NOWAIT flag was specified and a memory allocation request could not be satisfied. .It Bq Er ENAMETOOLONG The .Dv MAKEDEV_CHECKNAME flag was specified and the provided device name is longer than .Dv SPECNAMELEN . .It Bq Er EINVAL The .Dv MAKEDEV_CHECKNAME flag was specified and the provided device name is empty, contains a .Qq \&. or .Qq .. path component or ends with .Ql / . .It Bq Er EINVAL The .Dv MAKEDEV_CHECKNAME flag was specified and the provided device name contains invalid characters. .It Bq Er EEXIST The .Dv MAKEDEV_CHECKNAME flag was specified and the provided device name already exists. .El .Sh SEE ALSO .Xr devctl 4 , -.Xr devfs 5 , +.Xr devfs 4 , .Xr dev_clone 9 .Sh HISTORY The .Fn make_dev and .Fn destroy_dev functions first appeared in .Fx 4.0 . The function .Fn make_dev_alias first appeared in .Fx 4.1 . The function .Fn dev_depends first appeared in .Fx 5.0 . The functions .Fn make_dev_credf , .Fn destroy_dev_sched , .Fn destroy_dev_sched_cb first appeared in .Fx 7.0 . The function .Fn make_dev_p first appeared in .Fx 8.2 . The function .Fn make_dev_s first appeared in .Fx 11.0 . diff --git a/share/man/man9/pseudofs.9 b/share/man/man9/pseudofs.9 index e076c398c711..d87bbb0030c7 100644 --- a/share/man/man9/pseudofs.9 +++ b/share/man/man9/pseudofs.9 @@ -1,68 +1,68 @@ .\"- .\" Copyright (c) 2001 Dag-Erling Smørgrav .\" 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 20, 2007 .Dt PSEUDOFS 9 .Os .Sh NAME .Nm pseudofs .Nd pseudo file system construction kit .Sh SYNOPSIS .In fs/pseudofs/pseudofs.h .\" Insert usage example here .Sh DESCRIPTION The .Nm module offers an abstract API for pseudo-file systems such as -.Xr procfs 5 +.Xr procfs 4 and -.Xr linprocfs 5 . +.Xr linprocfs 4 . It takes care of all the hairy bits like interfacing with the VFS system, enforcing access control, keeping track of file numbers, and cloning files and directories that are process-specific. The consumer module, i.e., the module that implements the actual guts of the file system, needs only provide the directory structure (represented by a collection of structures declared and initialized by macros provided by .Nm ) and callbacks that report file attributes or write the actual file contents into sbufs. .\" Insert more info here .Sh SEE ALSO -.Xr linprocfs 5 , -.Xr linsysfs 5 , -.Xr procfs 5 , +.Xr linprocfs 4 , +.Xr linsysfs 4 , +.Xr procfs 4 , .Xr sbuf 9 , .Xr vnode 9 .Sh HISTORY The .Nm module appeared in .Fx 5.0 . .Sh AUTHORS The .Nm module and this manual page were written by .An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org . diff --git a/tools/build/options/WITHOUT_AUTOFS b/tools/build/options/WITHOUT_AUTOFS index fa8ff52d13e3..4e4047dda97f 100644 --- a/tools/build/options/WITHOUT_AUTOFS +++ b/tools/build/options/WITHOUT_AUTOFS @@ -1,3 +1,3 @@ Do not build -.Xr autofs 5 +.Xr autofs 4 related programs, libraries, and kernel modules. diff --git a/usr.bin/lsvfs/lsvfs.1 b/usr.bin/lsvfs/lsvfs.1 index 082023f00857..9871df32fa96 100644 --- a/usr.bin/lsvfs/lsvfs.1 +++ b/usr.bin/lsvfs/lsvfs.1 @@ -1,70 +1,70 @@ .\" Garrett A. Wollman, September 1994 .\" This file is in the public domain. .\" .Dd December 28, 2020 .Dt LSVFS 1 .Os .Sh NAME .Nm lsvfs .Nd list installed virtual file systems .Sh SYNOPSIS .Nm .Op Ar vfsname Ar ... .Sh DESCRIPTION The .Nm command lists information about the currently loaded virtual file system modules. When .Ar vfsname arguments are given, .Nm lists information about the specified VFS modules. Otherwise, .Nm lists all currently loaded modules. The information is as follows: .Pp .Bl -tag -compact -width Filesystem .It Filesystem the name of the file system, as would be used in the .Ar type parameter to .Xr mount 2 and the .Fl t option to .Xr mount 8 .It Num the filesystem type number. .It Refs the number of references to this VFS; i.e., the number of currently mounted file systems of this type .It Flags flag bits. .El .Sh EXAMPLES Show information about the .Ql ufs and -.Xr devfs 5 +.Xr devfs 4 filesystems and check the number of mounts for the former: .Bd -literal -offset indent $ lsvfs ufs devfs Filesystem Num Refs Flags -------------------------------- ---------- ----- --------------- ufs 0x00000035 2 devfs 0x00000071 1 synthetic, jail $ mount -t ufs | wc -l 2 .Ed .Sh SEE ALSO .Xr mount 2 , .Xr getvfsbyname 3 , .Xr mount 8 .Sh HISTORY A .Nm command appeared in .Fx 2.0 . diff --git a/usr.bin/posixmqcontrol/posixmqcontrol.1 b/usr.bin/posixmqcontrol/posixmqcontrol.1 index ec60230aac6e..67ddbfd5eaf0 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_receive 2 , .Xr mq_send 2 , .Xr mq_setattr 2 , .Xr mq_unlink 2 , -.Xr mqueuefs 5 +.Xr mqueuefs 4 .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/autofs/auto_master.5 b/usr.sbin/autofs/auto_master.5 index e826176f9f3f..30c78cc26766 100644 --- a/usr.sbin/autofs/auto_master.5 +++ b/usr.sbin/autofs/auto_master.5 @@ -1,373 +1,373 @@ .\" Copyright (c) 2014 The FreeBSD Foundation .\" .\" This software was developed by Edward Tomasz Napierala 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 December 27, 2023 .Dt AUTO_MASTER 5 .Os .Sh NAME .Nm auto_master .Nd autofs automounter configuration and map file format .Sh DESCRIPTION The automounter configuration consists of the .Nm configuration file, which assigns filesystem paths to map names, and maps, which contain actual mount information. The .Nm configuration file is used by the .Xr automount 8 command. Map files are read by the .Xr automountd 8 daemon. .Sh AUTO_MASTER SYNTAX The .Nm file consists of lines with two or three entries separated by whitespace and terminated by newline character: .Bd -literal -offset indent .Pa mountpoint Pa map_name Op Ar -options .Ed .Pp .Pa mountpoint is either a fully specified path, or .Li /- . When .Pa mountpoint is a full path, .Pa map_name must reference an indirect map. Otherwise, .Pa map_name must reference a direct map. See .Sx "MAP SYNTAX" below. .Pp .Pa map_name specifies map to use. If .Pa map_name begins with .Li - , it specifies a special map. See .Sx "MAP SYNTAX" below. If .Pa map_name is not a fully specified path .Pq it does not start with Li / , .Xr automountd 8 will search for that name in .Li /etc . Otherwise it will use the path as given. If the file indicated by .Pa map_name is executable, .Xr automountd 8 will assume it is an executable map. See .Sx "MAP SYNTAX" below. Otherwise, the file is opened and the contents parsed. .Pp .Pa -options is an optional field that starts with .Li - and can contain generic filesystem mount options. .Pp The following example specifies that the /etc/auto_example indirect map will be mounted on /example. .Bd -literal -offset indent /example auto_example .Ed .Sh MAP SYNTAX Map files consist of lines with a number of entries separated by whitespace and terminated by newline character: .Bd -literal -offset indent .Pa key Oo Ar -options Oc Oo Ar mountpoint Oo -options Oc Oc Ar location Op ... .Ed .Pp In most cases, it can be simplified to: .Bd -literal -offset indent .Pa key Oo Ar -options Oc Ar location .Ed .Pp .Pa key is the path component used by .Xr automountd 8 to find the right map entry to use. It is also used to form the final mountpoint. A wildcard .Pq Ql * can be used for the key. It matches every directory that does not match other keys. Those directories will not be visible to the user until accessed. .Pp The .Ar options field, if present, must begin with .Li - . When mounting the filesystem, options supplied to .Nm and options specified in the map entry are concatenated together. The special option .Li fstype is used to specify filesystem type. It is not passed to the mount program as an option. Instead, it is passed as an argument to .Cm "mount -t". The default .Li fstype is .Ql nfs . The special option .Li nobrowse is used to disable creation of top-level directories for special and executable maps. .Pp The optional .Pa mountpoint field is used to specify multiple mount points for a single key. .Pp The .Ar location field specifies the filesystem to be mounted. Ampersands .Pq Ql & in the .Ar location field are replaced with the value of .Ar key . This is typically used with wildcards, like: .Bd -literal -offset indent .Li * 192.168.1.1:/share/& .Ed .Pp The .Ar location field may contain references to variables, like: .Bd -literal -offset indent .Li sys 192.168.1.1:/sys/${OSNAME} .Ed .Pp Defined variables are: .Pp .Bl -tag -width "-OSNAME" -compact .It Li ARCH Expands to the output of .Li "uname -p" . .It Li CPU Same as ARCH. .It Li DOLLAR A literal $ sign. .It Li HOST Expands to the output of .Li "uname -n" . .It Li OSNAME Expands to the output of .Li "uname -s" . .It Li OSREL Expands to the output of .Li "uname -r" . .It Li OSVERS Expands to the output of .Li "uname -v" . .El .Pp Additional variables can be defined with the .Fl D option of .Xr automount 8 and .Xr automountd 8 . .Pp To pass a location that begins with .Li / , prefix it with a colon. For example, .Li :/dev/cd0 . .Pp This example, when put into .Pa /etc/auto_example , and with .Nm referring to the map as described above, specifies that the NFS share .Li 192.168.1.1:/share/example/x will be mounted on .Pa /example/x/ when any process attempts to access that mountpoint, with .Li intr and .Li nfsv4 mount options, described in .Xr mount_nfs 8 : .Bd -literal -offset indent .Li x -intr,nfsv4 192.168.1.1:/share/example/x .Ed .Pp Automatically mount an SMB share on access, as a guest user, without prompting for a password: .Bd -literal -offset indent .Li share -fstype=smbfs,-N ://@server/share .Ed .Pp Automatically mount the CD drive on access: .Bd -literal -offset indent .Li cd -fstype=cd9660 :/dev/cd0 .Ed .Sh SPECIAL MAPS Special maps have names beginning with .Li - . Supported special maps are: .Pp .Bl -tag -width "-hosts" -compact .It Li -hosts Query the remote NFS server and map exported shares. This map is traditionally mounted on .Pa /net . Access to files on a remote NFS server is provided through the .Pf /net/ Ar nfs-server-ip Ns / Ns Ar share-name Ns / directory without any additional configuration. Directories for individual NFS servers are not present until the first access, when they are automatically created. .It Li -media Query devices that are not yet mounted, but contain valid filesystems. Generally used to access files on removable media. .It Li -noauto Mount filesystems configured in .Xr fstab 5 as "noauto". This needs to be set up as a direct map. .It Li -null Prevent .Xr automountd 8 from mounting anything on the mountpoint. .El .Pp It is possible to add custom special maps by adding them, as executable maps named .Pa special_foo , to the .Pa /etc/autofs/ directory. .Sh EXECUTABLE MAPS If the map file specified in .Nm has the execute bit set, .Xr automountd 8 will execute it and parse the standard output instead of parsing the file contents. When called without command line arguments, the executable is expected to output a list of available map keys separated by newline characters. Otherwise, the executable will be called with a key name as a command line argument. Output from the executable is expected to be the entry for that key, not including the key itself. .Sh INDIRECT VERSUS DIRECT MAPS Indirect maps are referred to in .Nm by entries with a fully qualified path as a mount point, and must contain only relative paths as keys. Direct maps are referred to in .Nm by entries with .Li /- as the mountpoint, and must contain only fully qualified paths as keys. For indirect maps, the final mount point is determined by concatenating the .Nm mountpoint with the map entry key and optional map entry mountpoint. For direct maps, the final mount point is determined by concatenating the map entry key with the optional map entry mountpoint. .Pp The example above could be rewritten using direct map, by placing this in .Nm : .Bd -literal -offset indent .Li /- auto_example .Ed .Pp and this in .Li /etc/auto_example map file: .Bd -literal -offset indent .Li /example/x -intr,nfsv4 192.168.1.1:/share/example/x .Li /example/share -fstype=smbfs,-N ://@server/share .Li /example/cd -fstype=cd9660 :/dev/cd0 .Ed .Sh DIRECTORY SERVICES Both .Nm and maps may contain entries consisting of a plus sign and map name: .Bd -literal -offset indent .Li +auto_master .Ed .Pp Those entries cause .Xr automountd 8 daemon to retrieve the named map from directory services (like LDAP) and include it where the entry was. .Pp If the file containing the map referenced in .Nm is not found, the map will be retrieved from directory services instead. .Pp To retrieve entries from directory services, .Xr automountd 8 daemon runs .Pa /etc/autofs/include , which is usually a shell script, with map name as the only command line parameter. The script should output entries formatted according to .Nm or automounter map syntax to standard output. An example script to use LDAP is included in .Pa /etc/autofs/include_ldap . It can be symlinked to .Pa /etc/autofs/include . .Sh FILES .Bl -tag -width ".Pa /etc/auto_master" -compact .It Pa /etc/auto_master The default location of the .Pa auto_master file. .It Pa /etc/autofs/ Directory containing shell scripts to implement special maps and directory services. .El .Sh SEE ALSO -.Xr autofs 5 , +.Xr autofs 4 , .Xr automount 8 , .Xr automountd 8 , .Xr autounmountd 8 .Sh AUTHORS The .Nm configuration file functionality was developed by .An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org under sponsorship from the FreeBSD Foundation. diff --git a/usr.sbin/autofs/automount.8 b/usr.sbin/autofs/automount.8 index 3dc423c3054f..953b3c265178 100644 --- a/usr.sbin/autofs/automount.8 +++ b/usr.sbin/autofs/automount.8 @@ -1,108 +1,108 @@ .\" Copyright (c) 2014 The FreeBSD Foundation .\" .\" This software was developed by Edward Tomasz Napierala 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 November 22, 2014 .Dt AUTOMOUNT 8 .Os .Sh NAME .Nm automount .Nd update autofs mounts .Sh SYNOPSIS .Nm .Op Fl D Ar name=value .Op Fl L .Op Fl c .Op Fl f .Op Fl o Ar options .Op Fl v .Op Fl u .Sh DESCRIPTION When called without options, the .Nm command parses the .Xr auto_master 5 configuration file and any direct maps that it references, and mounts or unmounts -.Xr autofs 5 +.Xr autofs 4 filesystems to match. These options are available: .Bl -tag -width ".Fl v" .It Fl D Define a variable. It is only useful with .Fl L . .It Fl L Do not mount or unmount anything. Instead parse .Xr auto_master 5 and any direct maps, then print them to standard output. When specified more than once, all the maps, including indirect ones, will be parsed and shown. This is useful when debugging configuration problems. .It Fl c Flush caches, discarding possibly stale information obtained from maps and directory services. .It Fl f Force unmount, to be used with .Fl u . .It Fl o Specify mount options to be used along with the ones specified in the maps. It is only useful with .Fl L . .It Fl u Try to unmount filesystems mounted by .Xr automountd 8 . -.Xr autofs 5 +.Xr autofs 4 mounts are not unmounted. To unmount all -.Xr autofs +.Xr autofs 4 mounts, use .Cm "umount -At autofs". .It Fl v Increase verbosity. .El .Sh EXIT STATUS .Ex -std .Sh EXAMPLES Unmount all filesystems mounted by .Xr automountd 8 : .Dl Nm Fl u .Sh SEE ALSO +.Xr autofs 4 , .Xr auto_master 5 , -.Xr autofs 5 , .Xr automountd 8 , .Xr autounmountd 8 .Sh HISTORY The .Nm command appeared in .Fx 10.1 . .Sh AUTHORS The .Nm was developed by .An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org under sponsorship from the FreeBSD Foundation. diff --git a/usr.sbin/autofs/automountd.8 b/usr.sbin/autofs/automountd.8 index 4b2cf7d56336..0384fe2e7ed2 100644 --- a/usr.sbin/autofs/automountd.8 +++ b/usr.sbin/autofs/automountd.8 @@ -1,100 +1,100 @@ .\" Copyright (c) 2014 The FreeBSD Foundation .\" .\" This software was developed by Edward Tomasz Napierala 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 March 10, 2015 .Dt AUTOMOUNTD 8 .Os .Sh NAME .Nm automountd .Nd daemon handling autofs mount requests .Sh SYNOPSIS .Nm .Op Fl D Ar name=value .Op Fl i .Op Fl m Ar maxproc .Op Fl o Ar options .Op Fl d .Op Fl v .Sh DESCRIPTION The .Nm daemon is responsible for handling -.Xr autofs 5 +.Xr autofs 4 mount requests, parsing maps, and mounting filesystems they specify. On startup, .Nm forks into background and waits for kernel requests. When a request is received, .Nm forks a child process. The child process parses the appropriate map and mounts filesystems accordingly. Then it signals the kernel to release blocked processes that were waiting for the mount. .Bl -tag -width ".Fl v" .It Fl D Define a variable. .It Fl i For indirect mounts, only create subdirectories if there are no wildcard entries. Without .Fl i , .Nm creates all the subdirectories it can. Users may not realize that the wildcard map entry makes it possible to access directories that have not yet been created. .It Fl m Ar maxproc Limit the number of forked .Nm processes, and thus the number of mount requests being handled in parallel. The default is 30. .It Fl d Debug mode: increase verbosity and do not daemonize. .It Fl o Ar options Specify mount options. Options specified here will be overridden by options entered in maps or .Xr auto_master 5 . .It Fl v Increase verbosity. .El .Sh EXIT STATUS .Ex -std .Sh SEE ALSO +.Xr autofs 4 , .Xr auto_master 5 , -.Xr autofs 5 , .Xr automount 8 , .Xr autounmountd 8 .Sh HISTORY The .Nm daemon appeared in .Fx 10.1 . .Sh AUTHORS The .Nm was developed by .An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org under sponsorship from the FreeBSD Foundation. diff --git a/usr.sbin/extattrctl/extattrctl.8 b/usr.sbin/extattrctl/extattrctl.8 index 845929ac9ed2..ea5f69c61126 100644 --- a/usr.sbin/extattrctl/extattrctl.8 +++ b/usr.sbin/extattrctl/extattrctl.8 @@ -1,179 +1,179 @@ .\"- .\" Copyright (c) 2000-2001 Robert N. M. Watson .\" All rights reserved. .\" .\" This software was developed by Robert Watson for the TrustedBSD Project. .\" .\" 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. .\" .\" Developed by the TrustedBSD Project. .\" Support for file system extended attribute. .\" .Dd March 30, 2000 .Dt EXTATTRCTL 8 .Os .Sh NAME .Nm extattrctl .Nd manage UFS1 extended attributes .Sh SYNOPSIS .Nm .Cm start .Ar path .Nm .Cm stop .Ar path .Nm .Cm initattr .Op Fl f .Op Fl p Ar path .Ar attrsize .Ar attrfile .Nm .Cm showattr .Ar attrfile .Nm .Cm enable .Ar path .Ar attrnamespace .Ar attrname .Ar attrfile .Nm .Cm disable .Ar path .Ar attrnamespace .Ar attrname .Sh DESCRIPTION The .Nm utility is the management utility for extended attributes over the UFS1 file system. It allows the starting and stopping of extended attributes on a file system, as well as initialization of attribute backing files, and enabling and disabling of specific extended attributes on a file system. .Pp The first argument on the command line indicates the operation to be performed. Operation must be one of the following: .Bl -tag -width indent .It Cm start Ar path Start extended attribute support on the file system named using .Ar path . The file system must be an UFS1 file system, and the UFS_EXTATTR kernel option must have been enabled. .It Cm stop Ar path Stop extended attribute support on the file system named using .Ar path . Extended attribute support must previously have been started. .It Xo .Cm initattr .Op Fl f .Op Fl p Ar path .Ar attrsize attrfile .Xc Create and initialize a file to use as an attribute backing file. You must specify a maximum per-inode size for the attribute in bytes in .Ar attrsize , as well as the file where the attribute will be stored, using .Ar attrfile . .Pp The .Fl f argument may be used to indicate that it is alright to overwrite an existing attribute backing file; otherwise, if the target file exists, an error will be returned. .Pp The .Fl p Ar path argument may be used to preallocate space for all attributes rather than relying on sparse files to conserve space. This has the advantage of guaranteeing that space will be available for attributes when they are written, preventing low disk space conditions from denying attribute service. .Pp This file should not exist before running .Cm initattr . .It Cm showattr Ar attrfile Show the attribute header values in the attribute file named by .Ar attrfile . .It Cm enable Ar path attrnamespace attrname attrfile Enable an attribute named .Ar attrname in the namespace .Ar attrnamespace on the file system identified using .Ar path , and backed by initialized attribute file .Ar attrfile . Available namespaces are "user" and "system". The backing file must have been initialized using .Cm initattr before its first use. Attributes must have been started on the file system prior to the enabling of any attributes. .It Cm disable Ar path attrnamespace attrname Disable the attributed named .Ar attrname in namespace .Ar attrnamespace on the file system identified by .Ar path . Available namespaces are "user" and "system". The file system must have attributes started on it, and the attribute most have been enabled using .Cm enable . .El .Sh EXAMPLES .Dl extattrctl start / .Pp Start extended attributes on the root file system. .Pp .Dl extattrctl initattr 17 /.attribute/system/md5 .Pp Create an attribute backing file in /.attribute/system/md5, and set the maximum size of each attribute to 17 bytes, with a sparse file used for storing the attributes. .Pp .Dl extattrctl enable / system md5 /.attribute/system/md5 .Pp Enable an attribute named md5 on the root file system, backed from the file /.attribute/system/md5. .Pp .Dl extattrctl disable / md5 .Pp Disable the attribute named md5 on the root file system. .Pp .Dl extattrctl stop / .Pp Stop extended attributes on the root file system. .Sh SEE ALSO -.Xr ffs 7 , +.Xr ffs 4 , .Xr getextattr 8 , .Xr setextattr 8 , .Xr extattr 9 .Sh HISTORY Extended attribute support was developed as part of the TrustedBSD Project, and introduced in .Fx 5.0 . It was developed to support security extensions requiring additional labels to be associated with each file or directory. .Sh AUTHORS .An Robert N M Watson diff --git a/usr.sbin/fstyp/fstyp.8 b/usr.sbin/fstyp/fstyp.8 index 8471bc207e3c..9ab920073867 100644 --- a/usr.sbin/fstyp/fstyp.8 +++ b/usr.sbin/fstyp/fstyp.8 @@ -1,134 +1,134 @@ .\" Copyright (c) 2014 The FreeBSD Foundation .\" .\" This software was developed by Edward Tomasz Napierala 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 December 24, 2019 .Dt FSTYP 8 .Os .Sh NAME .Nm fstyp .Nd determine filesystem type .Sh SYNOPSIS .Nm .Op Fl l .Op Fl s .Op Fl u .Ar special .Sh DESCRIPTION The .Nm utility is used to determine the filesystem type on a given device. It can recognize BeFS (BeOS), ISO-9660, exFAT, Ext2, FAT, NTFS, and UFS filesystems. When the .Fl u flag is specified, .Nm also recognizes certain additional metadata formats that cannot be handled using .Xr mount 8 , such as .Xr geli 8 providers, and ZFS pools. .Pp The filesystem name is printed to the standard output as, respectively: .Bl -item -offset indent -compact .It befs .It cd9660 .It exfat .It ext2fs .It geli .It hammer .It hammer2 .It msdosfs .It ntfs .It ufs .It zfs .El .Pp Because .Nm is built specifically to detect filesystem types, it differs from .Xr file 1 in several ways. The output is machine-parsable, filesystem labels are supported, the utility runs sandboxed using .Xr capsicum 4 , and does not try to recognize any file format other than filesystems. .Pp These options are available: .Bl -tag -width ".Fl l" .It Fl l In addition to filesystem type, print filesystem label if available. .It Fl s Ignore file type. By default, .Nm only works on regular files and disk-like device nodes. Trying to read other file types might have unexpected consequences or hang indefinitely. .It Fl u Include filesystems and devices that cannot be mounted directly by .Xr mount 8 . .El .Sh EXIT STATUS The .Nm utility exits 0 on success, and >0 if an error occurs or the filesystem type is not recognized. .Sh SEE ALSO .Xr file 1 , +.Xr autofs 4 , .Xr capsicum 4 , -.Xr autofs 5 , .Xr geli 8 , .Xr glabel 8 , .Xr mount 8 , .Xr zpool 8 .Sh HISTORY The .Nm command appeared in .Fx 10.2 . .Sh AUTHORS .An -nosplit The .Nm utility was developed by .An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org under sponsorship from the FreeBSD Foundation. ZFS and GELI support was added by .An Allan Jude Aq Mt allanjude@FreeBSD.org . diff --git a/usr.sbin/jail/jail.8 b/usr.sbin/jail/jail.8 index d58192623952..407b26df818b 100644 --- a/usr.sbin/jail/jail.8 +++ b/usr.sbin/jail/jail.8 @@ -1,1503 +1,1503 @@ .\" Copyright (c) 2000, 2003 Robert N. M. Watson .\" Copyright (c) 2008-2012 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 March 16, 2024 .Dt JAIL 8 .Os .Sh NAME .Nm jail .Nd "manage system jails" .Sh SYNOPSIS .Ss From Configuration File .Nm .Op Fl cm .Op Fl Cdqv .Op Fl f Ar conf_file .Op Fl p Ar limit .Op Ar jail .Nm .Op Fl r .Op Fl Cqv .Op Fl f Ar conf_file .Op Fl p Ar limit .Op Cm * | Ar jail ... .Ss Without Configuration File .Nm .Op Fl cm .Op Fl dhilqv .Op Fl J Ar jid_file .Op Fl u Ar username .Op Fl U Ar username .Ar param Ns = Ns Ar value ... .Op Cm command Ns = Ns Ar command ... .Nm .Op Fl rR .Op Fl qv .Op Cm * | Ar jail ... .Ss Show Parameters .Nm .Op Fl f Ar conf_file .Fl e .Ar separator .Ss Backward Compatibility .Nm .Op Fl dhilqv .Op Fl J Ar jid_file .Op Fl u Ar username .Op Fl U Ar username .Op Fl n Ar jailname .Op Fl s Ar securelevel .Ar path hostname ip Ns Op Cm \&, Ns Ar ... .Ar command ... .Sh DESCRIPTION The .Nm utility creates new jails, or modifies or removes existing jails. It can also print a list of configured jails and their parameters. A jail .Pq or Dq prison is specified via parameters on the command line, or in the .Xr jail.conf 5 file. .Pp At least one of the options .Fl c , .Fl e , .Fl m or .Fl r must be specified. These options are used alone or in combination to describe the operation to perform: .Bl -tag -width indent .It Fl c Create a new jail. The jail .Va jid and .Va name parameters (if specified on the command line) must not refer to an existing jail. .It Fl e Ar separator Exhibit a list of all configured non-wildcard jails and their parameters. No jail creation, modification or removal performed if this option is used. The .Ar separator string is used to separate parameters. Use .Xr jls 8 utility to list running jails. .It Fl m Modify an existing jail. One of the .Va jid or .Va name parameters must exist and refer to an existing jail. Some parameters may not be changed on a running jail. .It Fl r Remove the .Ar jail specified by jid or name. All jailed processes are killed, and all jails that are children of this jail are also removed. .It Fl rc Restart an existing jail. The jail is first removed and then re-created, as if .Dq Nm Fl r and .Dq Nm Fl c were run in succession. .It Fl cm Create a jail if it does not exist, or modify the jail if it does exist. .It Fl mr Modify an existing jail. The jail may be restarted if necessary to modify parameters than could not otherwise be changed. .It Fl cmr Create a jail if it doesn't exist, or modify (and possibly restart) the jail if it does exist. .El .Pp Other available options are: .Bl -tag -width indent .It Fl C Clean up after an already-removed jail, running commands and operations that are typically run following jail removal. .It Fl f Ar conf_file Use configuration file .Ar conf_file instead of the default .Pa /etc/jail.conf . .It Fl h Resolve the .Va host.hostname parameter (or .Va hostname ) and add all IP addresses returned by the resolver to the list of addresses for this jail. This is equivalent to the .Va ip_hostname parameter. .It Fl i Output (only) the jail identifier of the newly created jail(s). This implies the .Fl q option. .It Fl J Ar jid_file Write a .Ar jid_file file, containing the parameters used to start the jail. .It Fl l Run commands in a clean environment. This is deprecated and is equivalent to the exec.clean parameter. .It Fl n Ar jailname Set the jail's name. This is deprecated and is equivalent to the .Va name parameter. .It Fl p Ar limit Limit the number of commands from .Va exec.* that can run simultaneously. .It Fl q Suppress the message printed whenever a jail is created, modified or removed. Only error messages will be printed. .It Fl R A variation of the .Fl r option that removes an existing jail without using the configuration file. No removal-related parameters for this jail will be used \(em the jail will simply be removed. .It Fl s Ar securelevel Set the .Va kern.securelevel MIB entry to the specified value inside the newly created jail. This is deprecated and is equivalent to the .Va securelevel parameter. .It Fl u Ar username The user name from host environment as whom jailed commands should run. This is deprecated and is equivalent to the .Va exec.jail_user and .Va exec.system_jail_user parameters. .It Fl U Ar username The user name from the jailed environment as whom jailed commands should run. This is deprecated and is equivalent to the .Va exec.jail_user parameter. .It Fl v Print a message on every operation, such as running commands and mounting filesystems. .It Fl d This is deprecated and is equivalent to the .Va allow.dying parameter, which is also deprecated. It used to allow making changes to a .Va dying jail. Now such jails are always replaced when a new jail is created with the same .Va jid or .Va name . .El .Pp If no arguments are given after the options, the operation (except remove) will be performed on all jails specified in the .Xr jail.conf 5 file. A single argument of a jail name will operate only on the specified jail. The .Fl r and .Fl R options can also remove running jails that aren't in the .Xr jail.conf 5 file, specified by name or jid. .Pp An argument of .Dq * is a wildcard that will operate on all jails, regardless of whether they appear in .Xr jail.conf 5 ; this is the surest way for .Fl r to remove all jails. If hierarchical jails exist, a partial-matching wildcard definition may be specified. For example, an argument of .Dq foo.* would apply to jails with names like .Dq foo.bar and .Dq foo.bar.baz . .Pp A jail may also be specified via parameters directly on the command line in .Dq name=value form, ignoring the contents of .Xr jail.conf 5 . For backward compatibility, the command line may also have four fixed parameters, without names: .Ar path , .Ar hostname , .Ar ip , and .Ar command . .Ss Jail Parameters Parameters in the .Xr jail.conf 5 file, or on the command line, are generally of the form .Dq name=value . Some parameters are boolean, and do not have a value but are set by the name alone with or without a .Dq no prefix, e.g. .Va persist or .Va nopersist . They can also be given the values .Dq true and .Dq false . Other parameters may have more than one value, specified as a comma-separated list or with .Dq += in the configuration file (see .Xr jail.conf 5 for details). .Pp The .Nm utility recognizes two classes of parameters. There are the true jail parameters that are passed to the kernel when the jail is created, which can be seen with .Xr jls 8 , and can (usually) be changed with .Dq Nm Fl m . Then there are pseudo-parameters that are only used by .Nm itself. .Pp Jails have a set of core parameters, and kernel modules can add their own jail parameters. The current set of available parameters can be retrieved via .Dq Nm sysctl Fl d Va security.jail.param . Any parameters not set will be given default values, often based on the current environment. The core parameters are: .Bl -tag -width indent .It Va jid The jail identifier. This will be assigned automatically to a new jail (or can be explicitly set), and can be used to identify the jail for later modification, or for such commands as .Xr jls 8 or .Xr jexec 8 . .It Va name The jail name. This is an arbitrary string that identifies a jail (except it may not contain a .Sq \&. ) . Like the .Va jid , it can be passed to later .Nm commands, or to .Xr jls 8 or .Xr jexec 8 . If no .Va name is supplied, a default is assumed that is the same as the .Va jid . The .Va name parameter is implied by the .Xr jail.conf 5 file format, and need not be explicitly set when using the configuration file. .It Va path The directory which is to be the root of the jail. Any commands run inside the jail, either by .Nm or from .Xr jexec 8 , are run from this directory. .It Va ip4.addr A list of IPv4 addresses assigned to the jail. If this is set, the jail is restricted to using only these addresses. Any attempts to use other addresses fail, and attempts to use wildcard addresses silently use the jailed address instead. For IPv4 the first address given will be used as the source address when source address selection on unbound sockets cannot find a better match. It is only possible to start multiple jails with the same IP address if none of the jails has more than this single overlapping IP address assigned to itself. .It Va ip4.saddrsel A boolean option to change the formerly mentioned behaviour and disable IPv4 source address selection for the jail in favour of the primary IPv4 address of the jail. Source address selection is enabled by default for all jails and the .Va ip4.nosaddrsel setting of a parent jail is not inherited for any child jails. .It Va ip4 Control the availability of IPv4 addresses. Possible values are .Dq inherit to allow unrestricted access to all system addresses, .Dq new to restrict addresses via .Va ip4.addr , and .Dq disable to stop the jail from using IPv4 entirely. Setting the .Va ip4.addr parameter implies a value of .Dq new . .It Va ip6.addr , Va ip6.saddrsel , Va ip6 A set of IPv6 options for the jail, the counterparts to .Va ip4.addr , .Va ip4.saddrsel and .Va ip4 above. .It Va vnet Create the jail with its own virtual network stack, with its own network interfaces, addresses, routing table, etc. The kernel must have been compiled with the .Sy VIMAGE option for this to be available. Possible values are .Dq inherit to use the system network stack, possibly with restricted IP addresses, and .Dq new to create a new network stack. .It Va host.hostname The hostname of the jail. Other similar parameters are .Va host.domainname , .Va host.hostuuid and .Va host.hostid . .It Va host Set the origin of hostname and related information. Possible values are .Dq inherit to use the system information and .Dq new for the jail to use the information from the above fields. Setting any of the above fields implies a value of .Dq new . .It Va securelevel The value of the jail's .Va kern.securelevel sysctl. A jail never has a lower securelevel than its parent system, but by setting this parameter it may have a higher one. If the system securelevel is changed, any jail securelevels will be at least as secure. .It Va devfs_ruleset The number of the devfs ruleset that is enforced for mounting devfs in this jail. A value of zero (default) means no ruleset is enforced. Descendant jails inherit the parent jail's devfs ruleset enforcement. Mounting devfs inside a jail is possible only if the .Va allow.mount and .Va allow.mount.devfs permissions are effective and .Va enforce_statfs is set to a value lower than 2. Devfs rules and rulesets cannot be viewed or modified from inside a jail. .Pp NOTE: It is important that only appropriate device nodes in devfs be exposed to a jail; access to disk devices in the jail may permit processes in the jail to bypass the jail sandboxing by modifying files outside of the jail. See .Xr devfs 8 for information on how to use devfs rules to limit access to entries in the per-jail devfs. A simple devfs ruleset for jails is available as ruleset #4 in .Pa /etc/defaults/devfs.rules . .It Va children.max The number of child jails allowed to be created by this jail (or by other jails under this jail). This limit is zero by default, indicating the jail is not allowed to create child jails. See the .Sx "Hierarchical Jails" section for more information. .It Va children.cur The number of descendants of this jail, including its own child jails and any jails created under them. .It Va enforce_statfs This determines what information processes in a jail are able to get about mount points. It affects the behaviour of the following syscalls: .Xr statfs 2 , .Xr fstatfs 2 , .Xr getfsstat 2 , and .Xr fhstatfs 2 (as well as similar compatibility syscalls). When set to 0, all mount points are available without any restrictions. When set to 1, only mount points below the jail's chroot directory are visible. In addition to that, the path to the jail's chroot directory is removed from the front of their pathnames. When set to 2 (default), above syscalls can operate only on a mount-point where the jail's chroot directory is located. .It Va persist Setting this boolean parameter allows a jail to exist without any processes. Normally, a command is run as part of jail creation, and then the jail is destroyed as its last process exits. A new jail must have either the .Va persist parameter or .Va exec.start or .Va command pseudo-parameter set. .It Va cpuset.id The ID of the cpuset associated with this jail (read-only). .It Va dying This is true if the jail is in the process of shutting down (read-only). .It Va parent The .Va jid of the parent of this jail, or zero if this is a top-level jail (read-only). .It Va osrelease The string for the jail's .Va kern.osrelease sysctl and uname -r. .It Va osreldate The number for the jail's .Va kern.osreldate and uname -K. .It Va allow.* Some restrictions of the jail environment may be set on a per-jail basis. With the exception of .Va allow.set_hostname and .Va allow.reserved_ports , these boolean parameters are off by default. .Bl -tag -width indent .It Va allow.set_hostname The jail's hostname may be changed via .Xr hostname 1 or .Xr sethostname 3 . .It Va allow.sysvipc A process within the jail has access to System V IPC primitives. This is deprecated in favor of the per-module parameters (see below). When this parameter is set, it is equivalent to setting .Va sysvmsg , .Va sysvsem , and .Va sysvshm all to .Dq inherit . .It Va allow.raw_sockets The jail root is allowed to create raw sockets. Setting this parameter allows utilities like .Xr ping 8 and .Xr traceroute 8 to operate inside the jail. If this is set, the source IP addresses are enforced to comply with the IP address bound to the jail, regardless of whether or not the .Dv IP_HDRINCL flag has been set on the socket. Since raw sockets can be used to configure and interact with various network subsystems, extra caution should be used where privileged access to jails is given out to untrusted parties. .It Va allow.chflags Normally, privileged users inside a jail are treated as unprivileged by .Xr chflags 2 . When this parameter is set, such users are treated as privileged, and may manipulate system file flags subject to the usual constraints on .Va kern.securelevel . .It Va allow.mount privileged users inside the jail will be able to mount and unmount file system types marked as jail-friendly. The .Xr lsvfs 1 command can be used to find file system types available for mount from within a jail. This permission is effective only if .Va enforce_statfs is set to a value lower than 2. .It Va allow.mount.devfs privileged users inside the jail will be able to mount and unmount the devfs file system. This permission is effective only together with .Va allow.mount and only when .Va enforce_statfs is set to a value lower than 2. The devfs ruleset should be restricted from the default by using the .Va devfs_ruleset option. .It Va allow.quotas The jail root may administer quotas on the jail's filesystem(s). This includes filesystems that the jail may share with other jails or with non-jailed parts of the system. .It Va allow.read_msgbuf Jailed users may read the kernel message buffer. If the .Va security.bsd.unprivileged_read_msgbuf MIB entry is zero, this will be restricted to the root user. .It Va allow.socket_af Sockets within a jail are normally restricted to IPv4, IPv6, local (UNIX), and route. This allows access to other protocol stacks that have not had jail functionality added to them. .It Va allow.mlock Locking or unlocking physical pages in memory are normally not available within a jail. When this parameter is set, users may .Xr mlock 2 or .Xr munlock 2 memory subject to .Va security.bsd.unprivileged_mlock and resource limits. .It Va allow.nfsd The .Xr mountd 8 , .Xr nfsd 8 , .Xr nfsuserd 8 , .Xr gssd 8 and .Xr rpc.tlsservd 8 daemons are permitted to run inside a properly configured vnet-enabled jail. The jail's root must be a file system mount point and .Va enforce_statfs must not be set to 0, so that .Xr mountd 8 can export file systems visible within the jail. .Va enforce_statfs must be set to 1 if file systems mounted under the jail's file system need to be exported by .Xr mount 8 . For exporting only the jail's file system, a setting of 2 is sufficient. If the kernel configuration does not include the .Sy NFSD option, .Pa nfsd.ko must be loaded outside of the jails. This is normally done by adding .Dq nfsd to .Va kld_list in the .Xr rc.conf 5 file outside of the jails. Similarily, if the .Xr gssd 8 is to be run in a jail, either the kernel .Sy KGSSAPI option needs to be specified or .Dq kgssapi and .Dq kgssapi_krb5 need to be in .Va kld_list in the .Xr rc.conf 5 file outside of the jails. .It Va allow.reserved_ports The jail root may bind to ports lower than 1024. .It Va allow.unprivileged_proc_debug Unprivileged processes in the jail may use debugging facilities. .It Va allow.suser The value of the jail's .Va security.bsd.suser_enabled sysctl. The super-user will be disabled automatically if its parent system has it disabled. The super-user is enabled by default. .It Va allow.extattr Allow privileged process in the jail to manipulate filesystem extended attributes in the system namespace. .El .El .Pp Kernel modules may add their own parameters, which only exist when the module is loaded. These are typically headed under a parameter named after the module, with values of .Dq inherit to give the jail full use of the module, .Dq new to encapsulate the jail in some module-specific way, and .Dq disable to make the module unavailable to the jail. There also may be other parameters to define jail behavior within the module. Module-specific parameters include: .Bl -tag -width indent .It Va allow.mount.fdescfs privileged users inside the jail will be able to mount and unmount the fdescfs file system. This permission is effective only together with .Va allow.mount and only when .Va enforce_statfs is set to a value lower than 2. .It Va allow.mount.fusefs privileged users inside the jail will be able to mount and unmount fuse-based file systems. This permission is effective only together with .Va allow.mount and only when .Va enforce_statfs is set to a value lower than 2. .It Va allow.mount.nullfs privileged users inside the jail will be able to mount and unmount the nullfs file system. This permission is effective only together with .Va allow.mount and only when .Va enforce_statfs is set to a value lower than 2. .It Va allow.mount.procfs privileged users inside the jail will be able to mount and unmount the procfs file system. This permission is effective only together with .Va allow.mount and only when .Va enforce_statfs is set to a value lower than 2. .It Va allow.mount.linprocfs privileged users inside the jail will be able to mount and unmount the linprocfs file system. This permission is effective only together with .Va allow.mount and only when .Va enforce_statfs is set to a value lower than 2. .It Va allow.mount.linsysfs privileged users inside the jail will be able to mount and unmount the linsysfs file system. This permission is effective only together with .Va allow.mount and only when .Va enforce_statfs is set to a value lower than 2. .It Va allow.mount.tmpfs privileged users inside the jail will be able to mount and unmount the tmpfs file system. This permission is effective only together with .Va allow.mount and only when .Va enforce_statfs is set to a value lower than 2. .It Va allow.mount.zfs privileged users inside the jail will be able to mount and unmount the ZFS file system. This permission is effective only together with .Va allow.mount and only when .Va enforce_statfs is set to a value lower than 2. See .Xr zfs 8 for information on how to configure the ZFS filesystem to operate from within a jail. .It Va allow.vmm The jail may access .Xr vmm 4 . This flag is only available when the .Xr vmm 4 kernel module is loaded. .It Va linux Determine how a jail's Linux emulation environment appears. A value of .Dq inherit will keep the same environment, and .Dq new will give the jail its own environment (still originally inherited when the jail is created). .It Va linux.osname , linux.osrelease , linux.oss_version The Linux OS name, OS release, and OSS version associated with this jail. .It Va sysvmsg Allow access to SYSV IPC message primitives. If set to .Dq inherit , all IPC objects on the system are visible to this jail, whether they were created by the jail itself, the base system, or other jails. If set to .Dq new , the jail will have its own key namespace, and can only see the objects that it has created; the system (or parent jail) has access to the jail's objects, but not to its keys. If set to .Dq disable , the jail cannot perform any sysvmsg-related system calls. .It Va sysvsem, sysvshm Allow access to SYSV IPC semaphore and shared memory primitives, in the same manner as .Va sysvmsg . .El .Pp There are pseudo-parameters that are not passed to the kernel, but are used by .Nm to set up the jail environment, often by running specified commands when jails are created or removed. The .Va exec.* command parameters are .Xr sh 1 command lines that are run in either the system or jail environment. They may be given multiple values, which would run the specified commands in sequence. All commands must succeed (return a zero exit status), or the jail will not be created or removed, as appropriate. .Pp The pseudo-parameters are: .Bl -tag -width indent .It Va exec.prepare Command(s) to run in the system environment to prepare a jail for creation. These commands are executed before assigning IP addresses and mounting filesystems, so they may be used to create a new jail filesystem if it does not already exist. .It Va exec.prestart Command(s) to run in the system environment before a jail is created. .It Va exec.created Command(s) to run in the system environment right after a jail has been created, but before commands (or services) get executed in the jail. .It Va exec.start Command(s) to run in the jail environment when a jail is created. A typical command to run is .Dq sh /etc/rc . .It Va command A synonym for .Va exec.start for use when specifying a jail directly on the command line. Unlike other parameters whose value is a single string, .Va command uses the remainder of the .Nm command line as its own arguments. .It Va exec.poststart Command(s) to run in the system environment after a jail is created, and after any .Va exec.start commands have completed. .It Va exec.prestop Command(s) to run in the system environment before a jail is removed. .It Va exec.stop Command(s) to run in the jail environment before a jail is removed, and after any .Va exec.prestop commands have completed. A typical command to run is .Dq sh /etc/rc.shutdown jail . .It Va exec.poststop Command(s) to run in the system environment after a jail is removed. .It Va exec.release Command(s) to run in the system environment after all other actions are done. These commands are executed after unmounting filesystems and removing IP addresses, so they may be used to remove a jail filesystem if it is no longer needed. .It Va exec.clean Run commands in a clean environment. The environment is discarded except for .Ev HOME , SHELL , TERM and .Ev USER . .Ev HOME and .Ev SHELL are set to the target login's default values. .Ev USER is set to the target login. .Ev TERM is imported from the current environment. The environment variables from the login class capability database for the target login are also set. .It Va exec.jail_user The user to run commands as, when running in the jail environment. The default is to run the commands as the current user. .It Va exec.system_jail_user This boolean option looks for the .Va exec.jail_user in the system .Xr passwd 5 file, instead of in the jail's file. .It Va exec.system_user The user to run commands as, when running in the system environment. The default is to run the commands as the current user. .It Va exec.timeout The maximum amount of time to wait for a command to complete, in seconds. If a command is still running after this timeout has passed, the jail will not be created or removed, as appropriate. .It Va exec.consolelog A file to direct command output (stdout and stderr) to. .It Va exec.fib The FIB (routing table) to set when running commands inside the jail. .It Va stop.timeout The maximum amount of time to wait for a jail's processes to exit after sending them a .Dv SIGTERM signal (which happens after the .Va exec.stop commands have completed). After this many seconds have passed, the jail will be removed, which will kill any remaining processes. If this is set to zero, no .Dv SIGTERM is sent and the jail is immediately removed. The default is 10 seconds. .It Va interface A network interface to add the jail's IP addresses .Va ( ip4.addr and .Va ip6.addr ) to. An alias for each address will be added to the interface before the jail is created, and will be removed from the interface after the jail is removed. .It Va ip4.addr In addition to the IP addresses that are passed to the kernel, an interface, netmask and additional parameters (as supported by .Xr ifconfig 8 Ns ) may also be specified, in the form .Dq Ar interface Ns | Ns Ar ip-address Ns / Ns Ar netmask param ... . If an interface is given before the IP address, an alias for the address will be added to that interface, as it is with the .Va interface parameter. If a netmask in either dotted-quad or CIDR form is given after an IP address, it will be used when adding the IP alias. If additional parameters are specified then they will also be used when adding the IP alias. .It Va ip6.addr In addition to the IP addresses that are passed to the kernel, an interface, prefix and additional parameters (as supported by .Xr ifconfig 8 Ns ) may also be specified, in the form .Dq Ar interface Ns | Ns Ar ip-address Ns / Ns Ar prefix param ... . .It Va vnet.interface A network interface to give to a vnet-enabled jail after is it created. The interface will automatically be released when the jail is removed. .It Va zfs.dataset A list of ZFS datasets to be attached to the jail. This requires .Va allow.mount.zfs to be set. See .Xr zfs-jail 8 for information on how to configure a ZFS dataset to be operated from within a jail. .It Va ip_hostname Resolve the .Va host.hostname parameter and add all IP addresses returned by the resolver to the list of addresses .Po Va ip4.addr or .Va ip6.addr Pc for this jail. This may affect default address selection for outgoing IPv4 connections from jails. The address first returned by the resolver for each address family will be used as the primary address. .It Va mount A filesystem to mount before creating the jail (and to unmount after removing it), given as a single .Xr fstab 5 line. .It Va mount.fstab An .Xr fstab 5 format file containing filesystems to mount before creating a jail. .It Va mount.devfs Mount a -.Xr devfs 5 +.Xr devfs 4 filesystem on the chrooted .Pa /dev directory, and apply the ruleset in the .Va devfs_ruleset parameter (or a default of ruleset 4: devfsrules_jail) to restrict the devices visible inside the jail. .It Va mount.fdescfs Mount a -.Xr fdescfs 5 +.Xr fdescfs 4 filesystem on the chrooted .Pa /dev/fd directory. .It Va mount.procfs Mount a -.Xr procfs 5 +.Xr procfs 4 filesystem on the chrooted .Pa /proc directory. .It Va allow.dying This is deprecated and has no effect. It used to allow making changes to a .Va dying jail. Now such jails are always replaced when a new jail is created with the same .Va jid or .Va name . .It Va depend Specify a jail (or jails) that this jail depends on. When this jail is to be created, any jail(s) it depends on must already exist. If not, they will be created automatically, up to the completion of the last .Va exec.poststart command, before any action will taken to create this jail. When jails are removed the opposite is true: this jail will be removed, up to the last .Va exec.poststop command, before any jail(s) it depends on are stopped. .El .Sh EXAMPLES Jails are typically set up using one of two philosophies: either to constrain a specific application (possibly running with privilege), or to create a .Dq "virtual system image" running a variety of daemons and services. In both cases, a fairly complete file system install of .Fx is required, so as to provide the necessary command line tools, daemons, libraries, application configuration files, etc. However, for a virtual server configuration, a fair amount of additional work is required so as to replace the .Dq boot process. This manual page documents the configuration steps necessary to support either of these steps, although the configuration steps may need to be refined based on local requirements. .Ss "Setting up a Jail Directory Tree" To set up a jail directory tree containing an entire .Fx distribution, the following .Xr sh 1 command script can be used: .Bd -literal -offset indent D=/here/is/the/jail cd /usr/src mkdir -p $D make world DESTDIR=$D make distribution DESTDIR=$D .Ed .Pp In many cases this example would put far more in the jail than needed. In the other extreme case a jail might contain only one file: the executable to be run in the jail. .Pp We recommend experimentation, and caution that it is a lot easier to start with a .Dq fat jail and remove things until it stops working, than it is to start with a .Dq thin jail and add things until it works. .Ss "Setting Up a Jail" Do what was described in .Sx "Setting Up a Jail Directory Tree" to build the jail directory tree. For the sake of this example, we will assume you built it in .Pa /data/jail/testjail , for a jail named .Dq testjail . Substitute below as needed with your own directory, IP address, and hostname. .Ss "Setting up the Host Environment" First, set up the real system's environment to be .Dq jail-friendly . For consistency, we will refer to the parent box as the .Dq "host environment" , and to the jailed virtual machine as the .Dq "jail environment" . Since jails are implemented using IP aliases, one of the first things to do is to disable IP services on the host system that listen on all local IP addresses for a service. If a network service is present in the host environment that binds all available IP addresses rather than specific IP addresses, it may service requests sent to jail IP addresses if the jail did not bind the port. This means changing .Xr inetd 8 to only listen on the appropriate IP address, and so forth. Add the following to .Pa /etc/rc.conf in the host environment: .Bd -literal -offset indent sendmail_enable="NO" inetd_flags="-wW -a 192.0.2.23" rpcbind_enable="NO" .Ed .Pp .Li 192.0.2.23 is the native IP address for the host system, in this example. Daemons that run out of .Xr inetd 8 can be easily configured to use only the specified host IP address. Other daemons will need to be manually configured \(em for some this is possible through .Xr rc.conf 5 flags entries; for others it is necessary to modify per-application configuration files, or to recompile the application. The following frequently deployed services must have their individual configuration files modified to limit the application to listening to a specific IP address: .Pp To configure .Xr sshd 8 , it is necessary to modify .Pa /etc/ssh/sshd_config . .Pp To configure .Xr sendmail 8 , it is necessary to modify .Pa /etc/mail/sendmail.cf . .Pp In addition, a number of services must be recompiled in order to run them in the host environment. This includes most applications providing services using .Xr rpc 3 , such as .Xr rpcbind 8 , .Xr nfsd 8 , and .Xr mountd 8 . In general, applications for which it is not possible to specify which IP address to bind should not be run in the host environment unless they should also service requests sent to jail IP addresses. Attempting to serve NFS from the host environment may also cause confusion, and cannot be easily reconfigured to use only specific IPs, as some NFS services are hosted directly from the kernel. Any third-party network software running in the host environment should also be checked and configured so that it does not bind all IP addresses, which would result in those services also appearing to be offered by the jail environments. .Pp Once these daemons have been disabled or fixed in the host environment, it is best to reboot so that all daemons are in a known state, to reduce the potential for confusion later (such as finding that when you send mail to a jail, and its sendmail is down, the mail is delivered to the host, etc.). .Ss "Configuring the Jail" Start any jail for the first time without configuring the network interface so that you can clean it up a little and set up accounts. As with any machine (virtual or not), you will need to set a root password, time zone, etc. Some of these steps apply only if you intend to run a full virtual server inside the jail; others apply both for constraining a particular application or for running a virtual server. .Pp Start a shell in the jail: .Bd -literal -offset indent jail -c path=/data/jail/testjail mount.devfs \\ host.hostname=testhostname ip4.addr=192.0.2.100 \\ command=/bin/sh .Ed .Pp Assuming no errors, you will end up with a shell prompt within the jail. You can now run .Xr bsdconfig 8 and do the post-install configuration to set various configuration options, or perform these actions manually by editing .Pa /etc/rc.conf , etc. .Pp .Bl -bullet -offset indent -compact .It Configure .Pa /etc/resolv.conf so that name resolution within the jail will work correctly. .It Run .Xr newaliases 1 to quell .Xr sendmail 8 warnings. .It Set a root password, probably different from the real host system. .It Set the timezone. .It Add accounts for users in the jail environment. .It Install any packages the environment requires. .El .Pp You may also want to perform any package-specific configuration (web servers, SSH servers, etc), patch up .Pa /etc/syslog.conf so it logs as you would like, etc. If you are not using a virtual server, you may wish to modify .Xr syslogd 8 in the host environment to listen on the syslog socket in the jail environment; in this example, the syslog socket would be stored in .Pa /data/jail/testjail/var/run/log . .Pp Exit from the shell, and the jail will be shut down. .Ss "Starting the Jail" You are now ready to restart the jail and bring up the environment with all of its daemons and other programs. Create an entry for the jail in .Pa /etc/jail.conf : .Bd -literal -offset indent testjail { path = /tmp/jail/testjail; mount.devfs; host.hostname = testhostname; ip4.addr = 192.0.2.100; interface = em0; exec.start = "/bin/sh /etc/rc"; exec.stop = "/bin/sh /etc/rc.shutdown jail"; } .Ed .Pp To start a virtual server environment, .Pa /etc/rc is run to launch various daemons and services, and .Pa /etc/rc.shutdown is run to shut them down when the jail is removed. If you are running a single application in the jail, substitute the command used to start the application for .Dq /bin/sh /etc/rc ; there may be some script available to cleanly shut down the application, or it may be sufficient to go without a stop command, and have .Nm send .Dv SIGTERM to the application. .Pp Start the jail by running: .Bd -literal -offset indent jail -c testjail .Ed .Pp A few warnings may be produced; however, it should all work properly. You should be able to see .Xr inetd 8 , .Xr syslogd 8 , and other processes running within the jail using .Xr ps 1 , with the .Ql J flag appearing beside jailed processes. To see an active list of jails, use .Xr jls 8 . If .Xr sshd 8 is enabled in the jail environment, you should be able to .Xr ssh 1 to the hostname or IP address of the jailed environment, and log in using the accounts you created previously. .Pp It is possible to have jails started at boot time. Please refer to the .Dq jail_* variables in .Xr rc.conf 5 for more information. .Ss "Managing the Jail" Normal machine shutdown commands, such as .Xr halt 8 , .Xr reboot 8 , and .Xr shutdown 8 , cannot be used successfully within the jail. To kill all processes from within a jail, you may use one of the following commands, depending on what you want to accomplish: .Bd -literal -offset indent kill -TERM -1 kill -KILL -1 .Ed .Pp This will send the .Dv SIGTERM or .Dv SIGKILL signals to all processes in the jail \(em be careful not to run this from the host environment! Once all of the jail's processes have died, unless the jail was created with the .Va persist parameter, the jail will be removed. Depending on the intended use of the jail, you may also want to run .Pa /etc/rc.shutdown from within the jail. .Pp To shut down the jail from the outside, simply remove it with: .Bd -literal -offset indent jail -r .Ed .Pp which will run any commands specified by .Va exec.stop , and then send .Dv SIGTERM and eventually .Dv SIGKILL to any remaining jailed processes. .Pp The .Pa /proc/ Ns Ar pid Ns Pa /status file contains, as its last field, the name of the jail in which the process runs, or .Dq Li - to indicate that the process is not running within a jail. The .Xr ps 1 command also shows a .Ql J flag for processes in a jail. .Pp You can also list/kill processes based on their jail ID. To show processes and their jail ID, use the following command: .Pp .Dl "ps ax -o pid,jid,args" .Pp To show and then kill processes in jail number 3 use the following commands: .Bd -literal -offset indent pgrep -lfj 3 pkill -j 3 .Ed or: .Pp .Dl "killall -j 3" .Ss "Jails and File Systems" It is not possible to .Xr mount 8 or .Xr umount 8 any file system inside a jail unless the file system is marked jail-friendly, the jail's .Va allow.mount parameter is set, and the jail's .Va enforce_statfs parameter is lower than 2. .Pp Multiple jails sharing the same file system can influence each other. For example, a user in one jail can fill the file system, leaving no space for processes in the other jail. Trying to use .Xr quota 1 to prevent this will not work either, as the file system quotas are not aware of jails but only look at the user and group IDs. This means the same user ID in two jails share a single file system quota. One would need to use one file system per jail to make this work. .Ss "Sysctl MIB Entries" The read-only entry .Va security.jail.jailed can be used to determine if a process is running inside a jail (value is one) or not (value is zero). .Pp The variable .Va security.jail.jail_max_af_ips determines how may address per address family a jail may have. The default is 255. .Pp Some MIB variables have per-jail settings. Changes to these variables by a jailed process do not affect the host environment, only the jail environment. These variables are .Va kern.securelevel , .Va security.bsd.suser_enabled , .Va kern.hostname , .Va kern.domainname , .Va kern.hostid , and .Va kern.hostuuid . .Ss "Hierarchical Jails" By setting a jail's .Va children.max parameter, processes within a jail may be able to create jails of their own. These child jails are kept in a hierarchy, with jails only able to see and/or modify the jails they created (or those jails' children). Each jail has a read-only .Va parent parameter, containing the .Va jid of the jail that created it; a .Va jid of 0 indicates the jail is a child of the current jail (or is a top-level jail if the current process isn't jailed). .Pp Jailed processes are not allowed to confer greater permissions than they themselves are given, e.g., if a jail is created with .Va allow.nomount , it is not able to create a jail with .Va allow.mount set. Similarly, such restrictions as .Va ip4.addr and .Va securelevel may not be bypassed in child jails. .Pp A child jail may in turn create its own child jails if its own .Va children.max parameter is set (remember it is zero by default). These jails are visible to and can be modified by their parent and all ancestors. .Pp Jail names reflect this hierarchy, with a full name being an MIB-type string separated by dots. For example, if a base system process creates a jail .Dq foo , and a process under that jail creates another jail .Dq bar , then the second jail will be seen as .Dq foo.bar in the base system (though it is only seen as .Dq bar to any processes inside jail .Dq foo ) . Jids on the other hand exist in a single space, and each jail must have a unique jid. .Pp Like the names, a child jail's .Va path appears relative to its creator's own .Va path . This is by virtue of the child jail being created in the chrooted environment of the first jail. .Sh SEE ALSO .Xr killall 1 , .Xr lsvfs 1 , .Xr newaliases 1 , .Xr pgrep 1 , .Xr pkill 1 , .Xr ps 1 , .Xr quota 1 , .Xr jail_set 2 , +.Xr devfs 4 , +.Xr fdescfs 4 , +.Xr linprocfs 4 , +.Xr linsysfs 4 , +.Xr procfs 4 , .Xr vmm 4 , -.Xr devfs 5 , -.Xr fdescfs 5 , .Xr jail.conf 5 , -.Xr linprocfs 5 , -.Xr linsysfs 5 , -.Xr procfs 5 , .Xr rc.conf 5 , .Xr sysctl.conf 5 , .Xr bsdconfig 8 , .Xr chroot 8 , .Xr devfs 8 , .Xr halt 8 , .Xr ifconfig 8 , .Xr inetd 8 , .Xr jexec 8 , .Xr jls 8 , .Xr mount 8 , .Xr mountd 8 , .Xr nfsd 8 , .Xr reboot 8 , .Xr rpcbind 8 , .Xr sendmail 8 , .Xr shutdown 8 , .Xr sysctl 8 , .Xr syslogd 8 , .Xr umount 8 , .Xr zfs-jail 8 , .Xr extattr 9 .Sh HISTORY The .Nm utility appeared in .Fx 4.0 . Hierarchical/extensible jails were introduced in .Fx 8.0 . The configuration file was introduced in .Fx 9.1 . .Sh AUTHORS .An -nosplit The jail feature was written by .An Poul-Henning Kamp for R&D Associates who contributed it to .Fx . .Pp .An Robert Watson wrote the extended documentation, found a few bugs, added a few new features, and cleaned up the userland jail environment. .Pp .An Bjoern A. Zeeb added multi-IP jail support for IPv4 and IPv6 based on a patch originally done by .An Pawel Jakub Dawidek for IPv4. .Pp .An James Gritton added the extensible jail parameters, hierarchical jails, and the configuration file. .Sh BUGS It might be a good idea to add an address alias flag such that daemons listening on all IPs .Pq Dv INADDR_ANY will not bind on that address, which would facilitate building a safe host environment such that host daemons do not impose on services offered from within jails. Currently, the simplest answer is to minimize services offered on the host, possibly limiting it to services offered from .Xr inetd 8 which is easily configurable. .Sh NOTES Great care should be taken when managing directories visible within the jail. For example, if a jailed process has its current working directory set to a directory that is moved out of the jail's chroot, then the process may gain access to the file space outside of the jail. It is recommended that directories always be copied, rather than moved, out of a jail. .Pp In addition, there are several ways in which an unprivileged user outside the jail can cooperate with a privileged user inside the jail and thereby obtain elevated privileges in the host environment. Most of these attacks can be mitigated by ensuring that the jail root is not accessible to unprivileged users in the host environment. Regardless, as a general rule, untrusted users with privileged access to a jail should not be given access to the host environment. diff --git a/usr.sbin/mlx5tool/mlx5tool.8 b/usr.sbin/mlx5tool/mlx5tool.8 index 17f0fd515a50..13c19d2d032b 100644 --- a/usr.sbin/mlx5tool/mlx5tool.8 +++ b/usr.sbin/mlx5tool/mlx5tool.8 @@ -1,120 +1,120 @@ .\" .\" Copyright (c) 2018, 2019 Mellanox Technologies .\" 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 May 7, 2019 .Dt mlx5tool 8 .Os .Sh NAME .Nm mlx5tool .Nd Utility for managing Connect-X 4/5/6 Mellanox network adapters .Sh SYNOPSIS .Nm .Fl d Ar domain:bus:slot:func .Fl E .Nm .Fl d Ar domain:bus:slot:func .Fl e .Nm .Fl d Ar domain:bus:slot:func .Fl f Ar file.mfa2 .Nm .Fl d Ar domain:bus:slot:func .Fl o Ar file .Fl w .Nm .Fl d Ar domain:bus:slot:func .Fl r .Nm .Fl d Ar domain:bus:slot:func .Fl z .Sh DESCRIPTION The .Nm utility is provided for management of the Connect-X4, 5 and 6 network adapters in the aspects not covered by the generic .Xr ifconfig 8 command, mostly related to the PCIe attachment and internal card working. The utility executes commands on specific adapter, which is addressed using .Em device:bus:slot:function conventions of the PCIe buses. You can match adapters ethernet name and addresses using the .X pciconf 8 utility. The address is passed as an argument of the .Fl d option, which must be specified for each invocation. .Pp When the driver detects the malfunctioning of the hardware, or by user request, it is possible to create .Em firmware dump , which contains debugging information about internal device state, for analysis of the failure by the Mellanox support team. .Pp The following commands are currently implemented: .Bl -tag -width indent .It Fl E Print EEPROM information .It Fl e Take the snapshot of the firmware registers state and store it in the kernel buffer. The buffer must be empty, in other words, no dumps should be written so far, or existing dump cleared with the .It Fl f Flashes the firmware image .Fa file.mfa2 to the specified adapter. Image must be in MFA2 pack format and contain a component suitable for the adapter hardware. .Pp Typically, PCIe link-level reset is required to activate the newly flashed image, which can be performed by the system reboot or using the .Fl z option. .Fl r command for the specified device. .It Fl r Clear the stored firmware dump, preparing the kernel buffer for the next dump. .It Fl w Fetches the stored firmware dump and writes it into the file specified by the .Fl o option argument. .It Fl z Performs PCIe link-level reset on the specified device. .El .Sh FILES The .Pa /dev/mlx5ctl -.Xr devfs 5 +.Xr devfs 4 node is used to pass commands to the driver. .Sh SEE ALSO .Xr mlx5en 4 , .Xr mlx5ib 4 , .Xr mlx5io 4 , .Xr ifconfig 8 and .Xr pciconf 8 . diff --git a/usr.sbin/snapinfo/snapinfo.8 b/usr.sbin/snapinfo/snapinfo.8 index 07e6bf2b4d4a..13c257f74ec5 100644 --- a/usr.sbin/snapinfo/snapinfo.8 +++ b/usr.sbin/snapinfo/snapinfo.8 @@ -1,64 +1,64 @@ .\" .\" Copyright (c) 2005 Mark Santcroos .\" 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 July 20, 2005 .Dt SNAPINFO 8 .Os .Sh NAME .Nm snapinfo .Nd "show snapshot location on UFS file systems" .Sh SYNOPSIS .Nm .Op Fl v .Fl a .Nm .Op Fl v .Ar mountpoint .Sh DESCRIPTION The .Nm utility searches and displays the location of snapshots on UFS file systems. .Pp Currently it works only on mounted file systems. It can either search one file system or all of them. .Pp The following options are available: .Bl -tag -width indent .It Fl a Search for snapshots on all mounted UFS file systems. .It Fl v Verbose mode. .It Ar mountpoint Search the file system mounted on this mountpoint. .El .Sh SEE ALSO -.Xr ffs 7 , +.Xr ffs 4 , .Xr mksnap_ffs 8 .Sh HISTORY The .Nm utility first appeared in .Fx 6.1 . .Sh AUTHORS .An Mark Santcroos Aq Mt marks@FreeBSD.org