diff --git a/lib/libc/sys/procctl.2 b/lib/libc/sys/procctl.2 index b040116a8e60..2d9833ab4710 100644 --- a/lib/libc/sys/procctl.2 +++ b/lib/libc/sys/procctl.2 @@ -1,858 +1,858 @@ .\" Copyright (c) 2013 Hudson River Trading LLC .\" Written by: John H. Baldwin .\" All rights reserved. .\" .\" Copyright (c) 2014 The FreeBSD Foundation .\" Portions of this documentation were written by Konstantin Belousov .\" under sponsorship from the FreeBSD Foundation. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE 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 26, 2023 .Dt PROCCTL 2 .Os .Sh NAME .Nm procctl .Nd control processes .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/procctl.h .Ft int .Fn procctl "idtype_t idtype" "id_t id" "int cmd" "void *data" .Sh DESCRIPTION The .Fn procctl system call provides for control over processes. The .Fa idtype and .Fa id arguments specify the set of processes to control. If multiple processes match the identifier, .Nm will make a .Dq best effort to control as many of the selected processes as possible. An error is only returned if no selected processes successfully complete the request. The following identifier types are supported: .Bl -tag -width P_PGID .It Dv P_PID Control the process with the process ID .Fa id . .Fa id zero is a shortcut for the calling process ID. .It Dv P_PGID Control processes belonging to the process group with the ID .Fa id . .El .Pp The control request to perform is specified by the .Fa cmd argument. .Pp All status changing requests .Dv *_CTL require the caller to have the right to debug the target. All status query requests -.DV *_STATUS +.Dv *_STATUS require the caller to have the right to observe the target. .Pp The following commands are supported: .Bl -tag -width PROC_TRAPCAP_STATUS .It Dv PROC_ASLR_CTL Controls the Address Space Layout Randomization (ASLR) in the program images created by .Xr execve 2 in the specified process or its descendants that do not either change the control or modify it by other means. The .Fa data parameter must point to the integer variable holding one of the following values: .Bl -tag -width PROC_ASLR_FORCE_DISABLE .It Dv PROC_ASLR_FORCE_ENABLE Request that ASLR is enabled after execution, even if it is disabled system-wide. The image flag and set-uid might prevent ASLR enablement still. .It Dv PROC_ASLR_FORCE_DISABLE Request that ASLR is disabled after execution. Same notes as for .Dv PROC_ASLR_FORCE_ENABLE apply. .It Dv PROC_ASLR_NOFORCE Use the system-wide configured policy for ASLR. .El .It Dv PROC_ASLR_STATUS Returns the current status of ASLR enablement for the target process. The .Fa data parameter must point to the integer variable, where one of the following values is written: .Bl -tag -width PROC_ASLR_FORCE_DISABLE .It Dv PROC_ASLR_FORCE_ENABLE .It Dv PROC_ASLR_FORCE_DISABLE .It Dv PROC_ASLR_NOFORCE .El .Pp If the currently executed image in the process itself has ASLR enabled, the .Dv PROC_ASLR_ACTIVE flag is or-ed with the value listed above. .It Dv PROC_PROTMAX_CTL Controls implicit application of PROT_MAX protection equal to the .Fa prot argument of the .Xr mmap 2 syscall, in the target process. The .Fa data parameter must point to the integer variable holding one of the following values: .Bl -tag -width PROC_PROTMAX_FORCE_DISABLE .It Dv PROC_PROTMAX_FORCE_ENABLE Enables implicit PROT_MAX application, even if it is disabled system-wide by the sysctl .Va vm.imply_prot_max . The image flag might still prevent the enablement. .It Dv PROC_PROTMAX_FORCE_DISABLE Request that implicit application of PROT_MAX be disabled. Same notes as for .Dv PROC_PROTMAX_FORCE_ENABLE apply. .It Dv PROC_PROTMAX_NOFORCE Use the system-wide configured policy for PROT_MAX. .El .It Dv PROC_PROTMAX_STATUS Returns the current status of implicit PROT_MAX enablement for the target process. The .Fa data parameter must point to the integer variable, where one of the following values is written: .Bl -tag -width PROC_PROTMAX_FORCE_DISABLE .It Dv PROC_PROTMAX_FORCE_ENABLE .It Dv PROC_PROTMAX_FORCE_DISABLE .It Dv PROC_PROTMAX_NOFORCE .El .Pp If the currently executed image in the process itself has implicit PROT_MAX application enabled, the .Dv PROC_PROTMAX_ACTIVE flag is or-ed with the value listed above. .It Dv PROC_SPROTECT Set process protection state. This is used to mark a process as protected from being killed if the system exhausts the available memory and swap. The .Fa data parameter must point to an integer containing an operation and zero or more optional flags. The following operations are supported: .Bl -tag -width PPROT_CLEAR .It Dv PPROT_SET Mark the selected processes as protected. .It Dv PPROT_CLEAR Clear the protected state of selected processes. .El .Pp The following optional flags are supported: .Bl -tag -width PPROT_DESCEND .It Dv PPROT_DESCEND Apply the requested operation to all child processes of each selected process in addition to each selected process. .It Dv PPROT_INHERIT When used with .Dv PPROT_SET , mark all future child processes of each selected process as protected. Future child processes will also mark all of their future child processes. .El .It Dv PROC_REAP_ACQUIRE Acquires the reaper status for the current process. Reaper status means that children orphaned by the reaper's descendants that were forked after the acquisition of reaper status are reparented to the reaper process. After system initialization, .Xr init 8 is the default reaper. .It Dv PROC_REAP_RELEASE Release the reaper state for the current process. The reaper of the current process becomes the new reaper of the current process's descendants. .It Dv PROC_REAP_STATUS Provides information about the reaper of the specified process, or the process itself when it is a reaper. The .Fa data argument must point to a .Vt procctl_reaper_status structure which is filled in by the syscall on successful return. .Bd -literal struct procctl_reaper_status { u_int rs_flags; u_int rs_children; u_int rs_descendants; pid_t rs_reaper; pid_t rs_pid; }; .Ed The .Fa rs_flags may have the following flags returned: .Bl -tag -width REAPER_STATUS_REALINIT .It Dv REAPER_STATUS_OWNED The specified process has acquired reaper status and has not released it. When the flag is returned, the specified process .Fa id , pid, identifies the reaper, otherwise the .Fa rs_reaper field of the structure is set to the pid of the reaper for the specified process id. .It Dv REAPER_STATUS_REALINIT The specified process is the root of the reaper tree, i.e., .Xr init 8 . .El .Pp The .Fa rs_children field returns the number of children of the reaper among the descendants. It is possible to have a child whose reaper is not the specified process, since the reaper for any existing children is not reset on the .Dv PROC_REAP_ACQUIRE operation. The .Fa rs_descendants field returns the total number of descendants of the reaper(s), not counting descendants of the reaper in the subtree. The .Fa rs_reaper field returns the reaper pid. The .Fa rs_pid returns the pid of one reaper child if there are any descendants. .It Dv PROC_REAP_GETPIDS Queries the list of descendants of the reaper of the specified process. The request takes a pointer to a .Vt procctl_reaper_pids structure in the .Fa data parameter. .Bd -literal struct procctl_reaper_pids { u_int rp_count; struct procctl_reaper_pidinfo *rp_pids; }; .Ed When called, the .Fa rp_pids field must point to an array of .Vt procctl_reaper_pidinfo structures, to be filled in on return, and the .Fa rp_count field must specify the size of the array, into which no more than .Fa rp_count elements will be filled in by the kernel. .Pp The .Vt "struct procctl_reaper_pidinfo" structure provides some information about one of the reaper's descendants. Note that for a descendant that is not a child, it may be incorrectly identified because of a race in which the original child process exited and the exited process's pid was reused for an unrelated process. .Bd -literal struct procctl_reaper_pidinfo { pid_t pi_pid; pid_t pi_subtree; u_int pi_flags; }; .Ed The .Fa pi_pid field is the process id of the descendant. The .Fa pi_subtree field provides the pid of the child of the reaper, which is the (grand-)parent of the process. The .Fa pi_flags field returns the following flags, further describing the descendant: .Bl -tag -width REAPER_PIDINFO_EXITING .It Dv REAPER_PIDINFO_VALID Set to indicate that the .Vt procctl_reaper_pidinfo structure was filled in by the kernel. Zero-filling the .Fa rp_pids array and testing the .Dv REAPER_PIDINFO_VALID flag allows the caller to detect the end of the returned array. .It Dv REAPER_PIDINFO_CHILD The .Fa pi_pid field identifies the direct child of the reaper. .It Dv REAPER_PIDINFO_REAPER The reported process is itself a reaper. The descendants of the subordinate reaper are not reported. .It Dv REAPER_PIDINFO_ZOMBIE The reported process is in the zombie state, ready to be reaped. .It Dv REAPER_PIDINFO_STOPPED The reported process is stopped by a SIGSTOP/SIGTSTP signal. .It Dv REAPER_PIDINFO_EXITING The reported process is in the process of exiting (but not yet a zombie). .El .It Dv PROC_REAP_KILL Request to deliver a signal to some subset of the descendants of the reaper. The .Fa data parameter must point to a .Vt procctl_reaper_kill structure, which is used both for parameters and status return. .Bd -literal struct procctl_reaper_kill { int rk_sig; u_int rk_flags; pid_t rk_subtree; u_int rk_killed; pid_t rk_fpid; }; .Ed The .Fa rk_sig field specifies the signal to be delivered. Zero is not a valid signal number, unlike for .Xr kill 2 . The .Fa rk_flags field further directs the operation. It is or-ed from the following flags: .Bl -tag -width REAPER_KILL_CHILDREN .It Dv REAPER_KILL_CHILDREN Deliver the specified signal only to direct children of the reaper. .It Dv REAPER_KILL_SUBTREE Deliver the specified signal only to descendants that were forked by the direct child with pid specified in the .Fa rk_subtree field. .El If neither the .Dv REAPER_KILL_CHILDREN nor the .Dv REAPER_KILL_SUBTREE flags are specified, all current descendants of the reaper are signalled. .Pp If a signal was delivered to any process, the return value from the request is zero. In this case, the .Fa rk_killed field identifies the number of processes signalled. The .Fa rk_fpid field is set to the pid of the first process for which signal delivery failed, e.g., due to permission problems. If no such process exists, the .Fa rk_fpid field is set to -1. .It Dv PROC_TRACE_CTL Enable or disable tracing of the specified process(es), according to the value of the integer argument. Tracing includes attachment to the process using the .Xr ptrace 2 and .Xr ktrace 2 , debugging sysctls, .Xr hwpmc 4 , .Xr dtrace 1 , and core dumping. Possible values for the .Fa data argument are: .Bl -tag -width PROC_TRACE_CTL_DISABLE_EXEC .It Dv PROC_TRACE_CTL_ENABLE Enable tracing, after it was disabled by .Dv PROC_TRACE_CTL_DISABLE . Only allowed for self. .It Dv PROC_TRACE_CTL_DISABLE Disable tracing for the specified process. Tracing is re-enabled when the process changes the executing program with the .Xr execve 2 syscall. A child inherits the trace settings from the parent on .Xr fork 2 . .It Dv PROC_TRACE_CTL_DISABLE_EXEC Same as .Dv PROC_TRACE_CTL_DISABLE , but the setting persists for the process even after .Xr execve 2 . .El .It Dv PROC_TRACE_STATUS Returns the current tracing status for the specified process in the integer variable pointed to by .Fa data . If tracing is disabled, .Fa data is set to -1. If tracing is enabled, but no debugger is attached by the .Xr ptrace 2 syscall, .Fa data is set to 0. If a debugger is attached, .Fa data is set to the pid of the debugger process. .It Dv PROC_TRAPCAP_CTL Controls the capability mode sandbox actions for the specified sandboxed processes, on a return from any syscall which gives either a .Er ENOTCAPABLE or .Er ECAPMODE error. If the control is enabled, such errors from the syscalls cause delivery of the synchronous .Dv SIGTRAP signal to the thread immediately before returning from the syscalls. .Pp Possible values for the .Fa data argument are: .Bl -tag -width PROC_TRAPCAP_CTL_DISABLE .It Dv PROC_TRAPCAP_CTL_ENABLE Enable the .Dv SIGTRAP signal delivery on capability mode access violations. The enabled mode is inherited by the children of the process, and is kept after .Xr fexecve 2 calls. .It Dv PROC_TRAPCAP_CTL_DISABLE Disable the signal delivery on capability mode access violations. Note that the global sysctl .Dv kern.trap_enotcap might still cause the signal to be delivered. See .Xr capsicum 4 . .El .Pp On signal delivery, the .Va si_errno member of the .Fa siginfo signal handler parameter is set to the syscall error value, and the .Va si_code member is set to .Dv TRAP_CAP . The system call number is stored in the .Va si_syscall field of the .Fa siginfo signal handler parameter. The other system call parameters can be read from the .Fa ucontext_t but the system call number is typically stored in the register that also contains the return value and so is unavailable in the signal handler. .Pp See .Xr capsicum 4 for more information about the capability mode. .It Dv PROC_TRAPCAP_STATUS Return the current status of signalling capability mode access violations for the specified process. The integer value pointed to by the .Fa data argument is set to the .Dv PROC_TRAPCAP_CTL_ENABLE value if the process control enables signal delivery, and to .Dv PROC_TRAPCAP_CTL_DISABLE otherwise. .Pp See the note about sysctl .Dv kern.trap_enotcap above, which gives independent global control of signal delivery. .It Dv PROC_PDEATHSIG_CTL Request the delivery of a signal when the parent of the calling process exits. .Fa idtype must be .Dv P_PID and .Fa id must be the either caller's pid or zero, with no difference in effect. The value is cleared for child processes and when executing set-user-ID or set-group-ID binaries. .Fa data must point to a value of type .Vt int indicating the signal that should be delivered to the caller. Use zero to cancel a previously requested signal delivery. .It Dv PROC_PDEATHSIG_STATUS Query the current signal number that will be delivered when the parent of the calling process exits. .Fa idtype must be .Dv P_PID and .Fa id must be the either caller's pid or zero, with no difference in effect. .Fa data must point to a memory location that can hold a value of type .Vt int . If signal delivery has not been requested, it will contain zero on return. .It Dv PROC_STACKGAP_CTL Controls the stack gaps in the specified process. A stack gap is the part of the growth area for a .Dv MAP_STACK mapped region that is reserved and never filled by memory. Instead, the process is guaranteed to receive a .Dv SIGSEGV signal on accessing pages in the gap. Gaps protect against stack overflow corrupting memory adjacent to the stack. .Pp The .Fa data argument must point to an integer variable containing flags. The following flags are allowed: .Bl -tag -width PROC_STACKGAP_DISABLE_EXEC .It Dv PROC_STACKGAP_ENABLE This flag is only accepted for consistency with .Dv PROC_STACKGAP_STATUS . If stack gaps are enabled, the flag is ignored. If disabled, the flag causes an .Ev EINVAL error to be returned. After gaps are disabled in a process, they can only be re-enabled when an .Xr execve 2 is performed. .It Dv PROC_STACKGAP_DISABLE Disable stack gaps for the process. For existing stacks, the gap is no longer a reserved part of the growth area and can be filled by memory on access. .It Dv PROC_STACKGAP_ENABLE_EXEC Enable stack gaps for programs started after an .Xr execve 2 by the specified process. .It Dv PROC_STACKGAP_DISABLE_EXEC Inherit disabled stack gaps state after .Xr execve 2 . In other words, if the currently executing program has stack gaps disabled, they are kept disabled on exec. If gaps were enabled, they are kept enabled after exec. .El .Pp The stack gap state is inherited from the parent on .Xr fork 2 . .It Dv PROC_STACKGAP_STATUS Returns the current stack gap state for the specified process. .Fa data must point to an integer variable, which is used to return a bitmask consisting of the following flags: .Bl -tag -width PROC_STACKGAP_DISABLE_EXEC .It Dv PROC_STACKGAP_ENABLE Stack gaps are enabled. .It Dv PROC_STACKGAP_DISABLE Stack gaps are disabled. .It Dv PROC_STACKGAP_ENABLE_EXEC Stack gaps are enabled in the process after .Xr execve 2 . .It Dv PROC_STACKGAP_DISABLE_EXEC Stack gaps are disabled in the process after .Xr execve 2 . .El .It Dv PROC_NO_NEW_PRIVS_CTL Allows one to ignore the SUID and SGID bits on the program images activated by .Xr execve 2 in the specified process and its future descendants. The .Fa data parameter must point to the integer variable holding the following value: .Bl -tag -width PROC_NO_NEW_PRIVS_ENABLE .It Dv PROC_NO_NEW_PRIVS_ENABLE Request SUID and SGID bits to be ignored. .El .Pp It is not possible to disable it once it has been enabled. .It Dv PROC_NO_NEW_PRIVS_STATUS Returns the current status of SUID/SGID enablement for the target process. The .Fa data parameter must point to the integer variable, where one of the following values is written: .Bl -tag -width PROC_NO_NEW_PRIVS_DISABLE .It Dv PROC_NO_NEW_PRIVS_ENABLE .It Dv PROC_NO_NEW_PRIVS_DISABLE .El .It Dv PROC_WXMAP_CTL Controls the 'write exclusive against execution' permissions for the mappings in the process address space. It overrides the global settings established by the .Dv kern.elf{32/64}.allow_wx sysctl, and the corresponding bit in the ELF control note, see .Xr elfctl 1 . .Pp The .Fa data parameter must point to the integer variable holding one of the following values: .Bl -tag -width PROC_WX_MAPPINGS_DISALLOW_EXEC .It Dv PROC_WX_MAPPINGS_PERMIT Enable creation of mappings that have both write and execute protection attributes, in the specified process' address space. .It Dv PROC_WX_MAPPINGS_DISALLOW_EXEC In the new address space created by .Xr execve 2 , disallow creation of mappings that have both write and execute permissions. .El .Pp Once creation of writeable and executable mappings is allowed, it is impossible (and pointless) to disallow it. The only way to ensure the absence of such mappings after they were enabled in a given process, is to set the .Dv PROC_WX_MAPPINGS_DISALLOW_EXEC flag and .Xr execve 2 an image. .It Dv PROC_WXMAP_STATUS Returns the current status of the 'write exclusive against execution' enforcement for the specified process. The .Dv data parameter must point to the integer variable, where one of the following values is written: .Bl -tag -width PROC_WX_MAPPINGS_DISALLOW_EXEC .It Dv PROC_WX_MAPPINGS_PERMIT Creation of simultaneously writable and executable mapping is permitted, otherwise the process cannot create such mappings. .It Dv PROC_WX_MAPPINGS_DISALLOW_EXEC After .Xr execve 2 , the new address space should disallow creation of simultaneously writable and executable mappings. .El .Pp Additionally, if the address space of the process disallows creation of simultaneously writable and executable mappings and it is guaranteed that no such mapping was created since address space creation, the .Dv PROC_WXORX_ENFORCE flag is set in the returned value. .El .Sh x86 MACHINE-SPECIFIC REQUESTS .Bl -tag -width PROC_KPTI_STATUS .It Dv PROC_KPTI_CTL AMD64 only. Controls the Kernel Page Table Isolation (KPTI) option for the children of the specified process. For the command to work, the .Va vm.pmap.kpti tunable must be enabled on boot. It is not possible to change the KPTI setting for a running process, except at the .Xr execve 2 , where the address space is reinitialized. .Pp The .Fa data parameter must point to an integer variable containing one of the following commands: .Bl -tag -width PROC_KPTI_CTL_DISABLE_ON_EXEC .It Dv PROC_KPTI_CTL_ENABLE_ON_EXEC Enable KPTI after .Xr execve 2 . .It Dv PROC_KPTI_CTL_DISABLE_ON_EXEC Disable KPTI after .Xr execve 2 . Only root or a process having the .Va PRIV_IO privilege might use this option. .El .It Dv PROC_KPTI_STATUS Returns the current KPTI status for the specified process. .Fa data must point to the integer variable, which returns the following statuses: .Bl -tag -width PROC_KPTI_CTL_DISABLE_ON_EXEC .It Dv PROC_KPTI_CTL_ENABLE_ON_EXEC .It Dv PROC_KPTI_CTL_DISABLE_ON_EXEC .El .Pp The status is or-ed with the .Va PROC_KPTI_STATUS_ACTIVE in case KPTI is active for the current address space of the process. .El .Sh NOTES Disabling tracing on a process should not be considered a security feature, as it is bypassable both by the kernel and privileged processes, and via other system mechanisms. As such, it should not be utilized to reliably protect cryptographic keying material or other confidential data. .Pp Note that processes can trivially bypass the 'no simultaneously writable and executable mappings' policy by first marking some mapping as writeable and write code to it, then removing write and adding execute permission. This may be legitimately required by some programs, such as JIT compilers. .Sh RETURN VALUES If an error occurs, a value of -1 is returned and .Va errno is set to indicate the error. .Sh ERRORS The .Fn procctl system call will fail if: .Bl -tag -width Er .It Bq Er EFAULT The .Fa data parameter points outside the process's allocated address space. .It Bq Er EINVAL The .Fa cmd argument specifies an unsupported command. .Pp The .Fa idtype argument specifies an unsupported identifier type. .It Bq Er EPERM The calling process does not have permission to perform the requested operation on any of the selected processes. .It Bq Er ESRCH No processes matched the requested .Fa idtype and .Fa id . .It Bq Er EINVAL An invalid operation or flag was passed in .Fa data for a .Dv PROC_SPROTECT command. .It Bq Er EPERM The .Fa idtype argument is not equal to .Dv P_PID , or .Fa id is not equal to the pid of the calling process, for .Dv PROC_REAP_ACQUIRE or .Dv PROC_REAP_RELEASE requests. .It Bq Er EINVAL Invalid or undefined flags were passed to a .Dv PROC_REAP_KILL request. .It Bq Er EINVAL An invalid or zero signal number was requested for a .Dv PROC_REAP_KILL request. .It Bq Er EINVAL The .Dv PROC_REAP_RELEASE request was issued by the .Xr init 8 process. .It Bq Er EBUSY The .Dv PROC_REAP_ACQUIRE request was issued by a process that had already acquired reaper status and has not yet released it. .It Bq Er EBUSY The .Dv PROC_TRACE_CTL request was issued for a process already being traced. .It Bq Er EPERM The .Dv PROC_TRACE_CTL request to re-enable tracing of the process .Po Dv PROC_TRACE_CTL_ENABLE Pc , or to disable persistence of .Dv PROC_TRACE_CTL_DISABLE on .Xr execve 2 was issued for a non-current process. .It Bq Er EINVAL The value of the integer .Fa data parameter for the .Dv PROC_TRACE_CTL or .Dv PROC_TRAPCAP_CTL request is invalid. .It Bq Er EINVAL The .Dv PROC_PDEATHSIG_CTL or .Dv PROC_PDEATHSIG_STATUS request referenced an unsupported .Fa id , .Fa idtype or invalid signal number. .El .Sh SEE ALSO .Xr dtrace 1 , .Xr proccontrol 1 , .Xr protect 1 , .Xr cap_enter 2 , .Xr kill 2 , .Xr ktrace 2 , .Xr mmap 2 , .Xr mprotect 2 , .Xr ptrace 2 , .Xr wait 2 , .Xr capsicum 4 , .Xr hwpmc 4 , .Xr init 8 .Sh HISTORY The .Fn procctl function appeared in .Fx 10.0 . .Pp The reaper facility is based on a similar feature of Linux and DragonflyBSD, and first appeared in .Fx 10.2 . .Pp The .Dv PROC_PDEATHSIG_CTL facility is based on the prctl(PR_SET_PDEATHSIG, ...) feature of Linux, and first appeared in .Fx 11.2 . .Pp The ASLR support was added to system for the checklists compliance in .Fx 13.0 . diff --git a/lib/libc/sys/statfs.2 b/lib/libc/sys/statfs.2 index 6111b127b8e3..7e41537b359c 100644 --- a/lib/libc/sys/statfs.2 +++ b/lib/libc/sys/statfs.2 @@ -1,255 +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. .\" .\" @(#)statfs.2 8.5 (Berkeley) 5/24/95 .\" .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 ) . .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. +traditional 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/libc/sys/swapon.2 b/lib/libc/sys/swapon.2 index 8cfac8ce1f64..b5adda8df2fd 100644 --- a/lib/libc/sys/swapon.2 +++ b/lib/libc/sys/swapon.2 @@ -1,162 +1,162 @@ .\" 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. .\" .\" @(#)swapon.2 8.1 (Berkeley) 6/4/93 .\" .Dd December 8, 2021 .Dt SWAPON 2 .Os .Sh NAME .Nm swapon , swapoff .Nd control devices for interleaved paging/swapping .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In vm/vm_param.h .In vm/swap_pager.h .Pp .In unistd.h .Ft int .Fn swapon "const char *special" .Ft int .Fn swapoff "const char *special" "u_int flags" .Sh DESCRIPTION The .Fn swapon system call makes the block device .Fa special available to the system for allocation for paging and swapping. The names of potentially available devices are known to the system and defined at system configuration time. The size of the swap area on .Fa special is calculated at the time the device is first made available for swapping. .Pp The .Fn swapoff system call disables paging and swapping on the given device. All associated swap metadata are deallocated, and the device is made available for other purposes. .Pp The .Fa special argument points to the name of the device or file used for swapping. -.The +The .Va flags argument takes the following flags: .Bl -tag -width SWAPOFF_FORCE .It Dv SWAPOFF_FORCE Overrides a very conservative check that prevents swapoff if the total amount of free memory and remaining swap devices space might be unsufficient for the system to continue operating. .El .Sh RETURN VALUES If an error has occurred, a value of -1 is returned and .Va errno is set to indicate the error. .Sh ERRORS Both .Fn swapon and .Fn swapoff can fail 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 ENOENT The named device does not exist. .It Bq Er EACCES Search permission is denied for a component of the path prefix. .It Bq Er ELOOP Too many symbolic links were encountered in translating the pathname. .It Bq Er EPERM The caller is not the super-user. .It Bq Er EFAULT The .Fa special argument points outside the process's allocated address space. .El .Pp Additionally, .Fn swapon can fail for the following reasons: .Bl -tag -width Er .It Bq Er ENOTBLK The .Fa special argument is not a block device. .It Bq Er EBUSY The device specified by .Fa special has already been made available for swapping .It Bq Er ENXIO The major device number of .Fa special is out of range (this indicates no device driver exists for the associated hardware). .It Bq Er EIO An I/O error occurred while opening the swap device. .It Bq Er EINTEGRITY Corrupted data was detected while reading from the file system to open the swap device. .El .Pp Lastly, .Fn swapoff can fail if: .Bl -tag -width Er .It Bq Er EINVAL The system is not currently swapping to .Fa special . .It Bq Er ENOMEM Not enough virtual memory is available to safely disable paging and swapping to the given device. .El .Sh SEE ALSO .Xr config 8 , .Xr swapon 8 , .Xr sysctl 8 .Sh HISTORY The .Fn swapon system call appeared in .Bx 4.0 . The .Fn swapoff system call appeared in .Fx 5.1 . diff --git a/lib/libcasper/services/cap_net/cap_net.3 b/lib/libcasper/services/cap_net/cap_net.3 index 6e525508d3c4..e322222e866f 100644 --- a/lib/libcasper/services/cap_net/cap_net.3 +++ b/lib/libcasper/services/cap_net/cap_net.3 @@ -1,292 +1,292 @@ .\" Copyright (c) 2020 Mariusz Zaborski .\" .\" 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 6, 2023 .Dt CAP_NET 3 .Os .Sh NAME .Nm cap_bind , .Nm cap_connect , .Nm cap_getaddrinfo , .Nm cap_gethostbyaddr , .Nm cap_gethostbyname , .Nm cap_gethostbyname2 , .Nm cap_getnameinfo , .Nm cap_net_free , .Nm cap_net_limit , .Nm cap_net_limit_addr2name , .Nm cap_net_limit_addr2name_family , .Nm cap_net_limit_bind , .Nm cap_net_limit_connect , .Nm cap_net_limit_init , .Nm cap_net_limit_name2addr , .Nm cap_net_limit_name2addr_family , .Nd "library for networking in capability mode" .Sh LIBRARY .Lb libcap_net .Sh SYNOPSIS .In sys/nv.h .In libcasper.h .In casper/cap_net.h .Ft int .Fn cap_bind "cap_channel_t *chan" "int s" "const struct sockaddr *addr" "socklen_t addrlen" .Ft int .Fn cap_connect "cap_channel_t *chan" "int s" "const struct sockaddr *name" "socklen_t namelen" .Ft int .Fn cap_getaddrinfo "cap_channel_t *chan" "const char *hostname" "const char *servname" "const struct addrinfo *hints" "struct addrinfo **res" .Ft int .Fn cap_getnameinfo "cap_channel_t *chan" "const struct sockaddr *sa" "socklen_t salen" "char *host" "size_t hostlen" "char *serv" "size_t servlen" "int flags" .Ft "struct hostent *" .Fn cap_gethostbyname "const cap_channel_t *chan" "const char *name" .Ft "struct hostent *" .Fn cap_gethostbyname2 "const cap_channel_t *chan" "const char *name" "int af" .Ft "struct hostent *" .Fn cap_gethostbyaddr "const cap_channel_t *chan" "const void *addr" "socklen_t len" "int af" .Ft "cap_net_limit_t *" .Fn cap_net_limit_init "cap_channel_t *chan" "uint64_t mode" .Ft int .Fn cap_net_limit "cap_net_limit_t *limit" .Ft void .Fn cap_net_free "cap_net_limit_t *limit" .Ft "cap_net_limit_t *" .Fn cap_net_limit_addr2name_family "cap_net_limit_t *limit" "int *family" "size_t size" .Ft "cap_net_limit_t *" .Fn cap_net_limit_addr2name "cap_net_limit_t *limit" "const struct sockaddr *sa" "socklen_t salen" .Ft "cap_net_limit_t *" .Fn cap_net_limit_name2addr_family "cap_net_limit_t *limit" "int *family" "size_t size" .Ft "cap_net_limit_t *" .Fn cap_net_limit_name2addr "cap_net_limit_t *limit" "const char *name" "const char *serv" .Ft "cap_net_limit_t *" .Fn cap_net_limit_connect "cap_net_limit_t *limit" "const struct sockaddr *sa" "socklen_t salen" .Ft "cap_net_limit_t *" .Fn cap_net_limit_bind "cap_net_limit_t *limit" "const struct sockaddr *sa" "socklen_t salen" .Sh DESCRIPTION The functions .Fn cap_bind , .Fn cap_connect , .Fn cap_getaddrinfo , .Fn cap_getnameinfo , .Fn cap_gethostbyname , .Fn cap_gethostbyname2 , and .Fn cap_gethostbyaddr provide a set of APIs equivalent to .Xr bind 2 , .Xr connect 2 , .Xr getaddrinfo 3 , .Xr getnameinfo 3 , .Xr gethostbyname 3 , .Xr gethostbyname2 3 , and .Xr gethostbyaddr 3 except that a connection to the .Nm system.net service needs to be provided. .Pp These functions, as well as .Fn cap_net_limit , are reentrant but not thread-safe. That is, they may be called from separate threads only with different .Vt cap_channel_t arguments or with synchronization. .Sh LIMITS By default, the cap_net capability provides unrestricted access to the network namespace. Applications typically only require access to a small portion of the network namespace: The .Fn cap_net_limit function can be used to restrict access to the network. The .Fn cap_net_limit_init returns an opaque limit handle used to store a list of capabilities. The -.Fv mode +.Fa mode restricts the functionality of the service. Modes are encoded using the following flags: .Pp .Bd -literal -offset indent -compact CAPNET_ADDR2NAME reverse DNS lookups are allowed with cap_getnameinfo CAPNET_NAME2ADDR name resolution is allowed with cap_getaddrinfo CAPNET_DEPRECATED_ADDR2NAME reverse DNS lookups are allowed with cap_gethostbyaddr CAPNET_DEPRECATED_NAME2ADDR name resolution is allowed with cap_gethostbyname and cap_gethostbyname2 CAPNET_BIND bind syscall is allowed CAPNET_CONNECT connect syscall is allowed CAPNET_CONNECTDNS connect syscall is allowed to the values returned from previous call to the cap_getaddrinfo or cap_gethostbyname .Ed .Pp .Fn cap_net_limit_addr2name_family limits the .Fn cap_getnameinfo and .Fn cap_gethostbyaddr to do reverse DNS lookups to specific family (AF_INET, AF_INET6, etc.) .Pp .Fn cap_net_limit_addr2name limits the .Fn cap_getnameinfo and .Fn cap_gethostbyaddr to do reverse DNS lookups only on those specific structures. .Pp .Fn cap_net_limit_name2addr_family limits the .Fn cap_getaddrinfo , .Fn cap_gethostbyname and .Fn cap_gethostbyname2 to do the name resolution on specific family (AF_INET, AF_INET6, etc.) .Pp .Fn cap_net_limit_addr2name restricts .Fn cap_getaddrinfo , .Fn cap_gethostbyname and .Fn cap_gethostbyname2 to a set of domains. .Pp .Fn cap_net_limit_bind limits .Fn cap_bind to bind only on those specific structures. .Pp .Fn cap_net_limit_connect limits .Fn cap_connect to connect only on those specific structures. If the CAPNET_CONNECTDNS is set the limits are extended to the values returned by .Fn cap_getaddrinfo , .Fn cap_gethostbyname and .Fn cap_gethostbyname2 In case of the .Fn cap_getaddrinfo the restriction is strict. In case of the .Fn cap_gethostbyname and .Fn cap_gethostbyname2 any port will be accepted in the .Fn cap_connect function. .Pp The .Fn cap_net_limit will consume and apply the limits. .Pp Once a set of limits is applied, subsequent calls to .Fn cap_net_limit will fail unless the new set is a subset of the current set. .Pp If the .Fn cap_net_limit was not called the rights may be freed using .Fn cap_net_free . Multiple calls to .Fn cap_net_limit_addr2name_family , .Fn cap_net_limit_addr2name , .Fn cap_net_limit_name2addr_family , .Fn cap_net_limit_name2addr , .Fn cap_net_limit_connect , and .Fn cap_net_limit_bind is supported, each call is extending preview capabilities. .Sh EXAMPLES The following example first opens a capability to casper and then uses this capability to create the .Nm system.net casper service and uses it to resolve a host and connect to it. .Bd -literal cap_channel_t *capcas, *capnet; cap_net_limit_t *limit; int familylimit, error, s; const char *host = "example.com"; struct addrinfo hints, *res; /* Open capability to Casper. */ capcas = cap_init(); if (capcas == NULL) err(1, "Unable to contact Casper"); /* Cache NLA for gai_strerror. */ caph_cache_catpages(); /* Enter capability mode sandbox. */ if (caph_enter_casper() < 0) err(1, "Unable to enter capability mode"); /* Use Casper capability to create capability to the system.net service. */ capnet = cap_service_open(capcas, "system.net"); if (capnet == NULL) err(1, "Unable to open system.net service"); /* Close Casper capability. */ cap_close(capcas); /* Limit system.net to reserve IPv4 addresses, to host example.com . */ limit = cap_net_limit_init(capnet, CAPNET_NAME2ADDR | CAPNET_CONNECTDNS); if (limit == NULL) err(1, "Unable to create limits."); cap_net_limit_name2addr(limit, host, "80"); familylimit = AF_INET; cap_net_limit_name2addr_family(limit, &familylimit, 1); if (cap_net_limit(limit) < 0) err(1, "Unable to apply limits."); /* Find IP addresses for the given host. */ memset(&hints, 0, sizeof(hints)); hints.ai_family = AF_INET; hints.ai_socktype = SOCK_STREAM; error = cap_getaddrinfo(capnet, host, "80", &hints, &res); if (error != 0) errx(1, "cap_getaddrinfo(): %s: %s", host, gai_strerror(error)); s = socket(res->ai_family, res->ai_socktype, res->ai_protocol); if (s < 0) err(1, "Unable to create socket"); if (cap_connect(capnet, s, res->ai_addr, res->ai_addrlen) < 0) err(1, "Unable to connect to host"); .Ed .Sh SEE ALSO .Xr bind 2 , .Xr cap_enter 2 , .Xr connect 2 , .Xr caph_enter 3 , .Xr err 3 , .Xr gethostbyaddr 3 , .Xr gethostbyname 3 , .Xr gethostbyname2 3 , .Xr getnameinfo 3 , .Xr capsicum 4 , .Xr nv 9 .Sh AUTHORS .An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org diff --git a/share/man/man4/qat.4 b/share/man/man4/qat.4 index 03d1e6e956e7..3d8c0cd32664 100644 --- a/share/man/man4/qat.4 +++ b/share/man/man4/qat.4 @@ -1,185 +1,185 @@ .\" SPDX-License-Identifier: BSD-3-Clause .\" Copyright(c) 2007-2022 Intel Corporation .Dd May 4, 2023 .Dt QAT 4 .Os .Sh NAME .Nm qat .Nd Intel (R) QuickAssist Technology (QAT) driver .Sh SYNOPSIS To load the driver call: .Pp .Bl -item -compact .It kldload qat .El .Pp In order to load the driver on boot add these lines to .Xr loader.conf 5 selecting firmware(s) suitable for installed device(s) .Pp .Bl -item -compact .It qat_200xx_fw_load="YES" .It qat_c3xxx_fw_load="YES" .It qat_c4xxx_fw_load="YES" .It qat_c62x_fw_load="YES" .It qat_dh895xcc_fw_load="YES" .It qat_4xxx_fw_load="YES" .It qat_load="YES" .El .Sh DESCRIPTION The .Nm driver supports cryptography and compression acceleration of the Intel (R) QuickAssist Technology (QAT) devices. .Pp The .Nm driver is intended for platforms that contain: .Bl -bullet -compact .It Intel (R) C62x Chipset .It Intel (R) Atom C3000 processor product family .It Intel (R) QuickAssist Adapter 8960/Intel (R) QuickAssist Adapter 8970 (formerly known as "Lewis Hill") .It Intel (R) Communications Chipset 8925 to 8955 Series .It Intel (R) Atom P5300 processor product family .It Intel (R) QAT 4xxx Series .El .Pp The .Nm driver supports cryptography and compression acceleration. A complete API for offloading these operations is exposed in the kernel and may be used by any other entity directly. For details of usage and supported operations and algorithms refer to the following documentation available from Intel Download Center .Lk https://downloadcenter.intel.com : .Bl -bullet -compact .It .Rs .%A Intel (R) .%T QuickAssist Technology API Programmer's Guide .Re .It .Rs .%A Intel (R) .%T QuickAssist Technology Cryptographic API Reference Manual .Re .It .Rs .%A Intel (R) .%T QuickAssist Technology Data Compression API Reference Manual .Re .It .Rs .%A Intel (R) .%T QuickAssist Technology Performance Optimization Guide .Re .El .Pp In addition to exposing complete kernel API for offloading cryptography and compression operations, the .Nm driver also integrates with .Xr crypto 4 , allowing offloading supported cryptography operations to Intel (R) QuickAssist Technology (QAT) devices. For details of usage and supported operations and algorithms refer to the documentation mentioned above and .Sx SEE ALSO section. .Sh SYSCTL_VARIABLES Following variables may be used to reconfigure the QAT device.\& For configuration persistence those variables may be set before loading the driver, either via .Xr kenv 1 or .Xr loader.conf 5 . The device specific configuration options are prefixed with .Va dev.qat.X\&. where X is the device number. The specific device needs to be in "down" state before changing the configuration. .Bl -tag -width indent .It Va state Show current state of the device. Override the device state. Possible values: "down", "up". NOTE: If the symmetric services are used for device the qat_ocf driver needs to be disabled prior the device reconfiguration. Following variable may be used to enable/disable the QAT cryptographic framework connectivity .Va dev.qat_ocf.0.enable\&. Enabled by default. .It Va cfg_services Override the device services enabled: symmetric, asymmetric, data compression. Possible values: "sym", "asym", "dc", "sym;dc", "asym;dc", "sym;asym". Default services configured are "sym;asym" for even and "dc" for odd devices. .It Va cfg_mode Override the device mode configuration for kernel space and user space instances. Possible values: "ks", "us", "ks;us". Default value "ks;us". .It Va num_user_processes Override the number of uio user space processes that can connect to the QAT device. Default: 2 .El .Pp The following .Xr sysctl 8 variables are read-only: .Bl -tag -width indent .It Va frequency QAT device frequency value. .It Va mmp_version QAT MMP Library revision number. .It Va hw_version QAT hardware revision number. .It Va fw_version QAT firmware revision number. .It Va dev_cfg Summary of device specific configuration. .It Va heartbeat QAT device heartbeat status. Value '1' indicates that the device is operational. -'0' value means that the device is not responsive. Device requires restart. +Value '0' means that the device is not responsive. Device requires restart. .It Va heartbeat_failed Number of QAT heartbeat failures received. .It Va heartbeat_sent Number of QAT heartbeat requests sent. .El .Sh COMPATIBILITY The .Nm driver replaced previous implementation introduced in .Fx 13.0 . Current version, in addition to .Xr crypto 4 integration, supports also data compression and exposes a complete API for offloading data compression and cryptography operations. .Sh SEE ALSO .Xr crypto 4 , .Xr ipsec 4 , .Xr pci 4 , .Xr crypto 7 , .Xr crypto 9 .Sh HISTORY This .Nm driver was introduced in .Fx 14.0 . .Fx 13.0 included a different version of .Nm driver. .Sh AUTHORS The .Nm driver was written by .An Intel (R) Corporation . diff --git a/usr.sbin/mfiutil/mfiutil.8 b/usr.sbin/mfiutil/mfiutil.8 index 86dc6b6ee122..9f8cacf7f16d 100644 --- a/usr.sbin/mfiutil/mfiutil.8 +++ b/usr.sbin/mfiutil/mfiutil.8 @@ -1,824 +1,825 @@ .\" Copyright (c) 2008, 2009 Yahoo!, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. The names of the authors may not be used to endorse or promote .\" products derived from this software without specific prior written .\" permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd September 2, 2011 .Dt MFIUTIL 8 .Os .Sh NAME .Nm mfiutil , .Nm mrsasutil .Nd Utility for managing LSI MegaRAID SAS controllers .Sh SYNOPSIS .Nm .Cm version .Nm .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm show adapter .Nm .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm show battery .Nm .Op Fl d .Op Fl e .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm show config .Nm .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm show drives .Nm .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm show events .Op Fl c Ar class .Op Fl l Ar locale .Op Fl n Ar count .Op Fl v .Op Ar start Op Ar stop .Nm .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm show firmware .Nm .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm show foreign Op Ar volume .Nm .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm show logstate .Nm .Op Fl d .Op Fl e .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm show patrol .Nm .Op Fl d .Op Fl e .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm show progress .Nm .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm show volumes .Nm .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm fail Ar drive .Nm .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm good Ar drive .Nm .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm rebuild Ar drive .Nm .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm syspd Ar drive .Nm .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm drive progress Ar drive .Nm .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm drive clear Ar drive Brq "start | stop" .Nm .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm start rebuild Ar drive .Nm .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm abort rebuild Ar drive .Nm .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm locate Ar drive Brq "on | off" .Nm .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm cache Ar volume Op Ar setting Oo Ar value Oc Op ... .Nm .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm name Ar volume Ar name .Nm .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm volume progress Ar volume .Nm .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm clear .Nm .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm create Ar type .Op Fl v .Op Fl s Ar stripe_size .Ar drive Ns Op \&, Ns Ar drive Ns Op ",..." .Op Ar drive Ns Op \&, Ns Ar drive Ns Op ",..." .Nm .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm delete Ar volume .Nm .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm add Ar drive Op Ar volume .Nm .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm remove Ar drive .Nm .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm start patrol .Nm .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm stop patrol .Nm .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm patrol Ar command Op Ar interval Op Ar start .Nm .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm foreign scan .Nm .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm foreign clear Op Ar config .Nm .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm foreign diag Op Ar config .Nm .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm foreign preview Op Ar config .Nm .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm foreign import Op Ar config .Nm .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm flash Ar file .Nm .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm start learn .Nm .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm bbu Ar setting Ar value .Nm .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm ctrlprop Ar rebuild Op Ar rate .Nm .Op Fl D Ar device .Op Fl t Ar type .Op Fl u Ar unit .Cm ctrlprop Ar alarm Op Ar 0/1 .Sh DESCRIPTION The .Nm utility can be used to display or modify various parameters on LSI MegaRAID SAS RAID controllers. Each invocation of .Nm consists of zero or more global options followed by a command. Commands may support additional optional or required arguments after the command. .Pp Currently three global options are supported: .Bl -tag -width indent .It Fl D Ar device .Ar device specifies the device node of the controller to use. -'/dev/' will be added to the device node if needed. +.Pa /dev/ +will be added to the device node if needed. If no device node is specified, then device will be made of the type and device. .It Fl t Ar type .Ar type specifies the type of the controller to work with either .Xr mfi 4 or .Xr mrsas 4 . If no type is specified, then the name of the invoked tool used to derive the type. .It Fl u Ar unit .Ar unit specifies the unit of the controller to work with. If no unit is specified, then unit 0 is used. .El .Pp Various commands accept either or both of the two options: .Bl -tag -width indent .It Fl d Print numeric device IDs as drive identifier. This is the default. Useful in combination with .Fl e to print both, numeric device IDs and enclosure:slot information. .It Fl e Print drive identifiers in enclosure:slot form. See next paragraph on format details in context of input rather than output. .El .Pp Drives may be specified in two forms. First, a drive may be identified by its device ID. The device ID for configured drives can be found in .Cm show config . Second, a drive may be identified by its location as .Sm off .Op E Ar xx Ns \&: .Li S Ns Ar yy .Sm on where .Ar xx is the enclosure and .Ar yy is the slot for each drive as displayed in .Cm show drives . .Pp Volumes may be specified in two forms. First, a volume may be identified by its target ID. Second, on the volume may be specified by the corresponding .Em mfidX device, such as .Em mfid0 . .Pp The .Nm utility supports several different groups of commands. The first group of commands provide information about the controller, the volumes it manages, and the drives it controls. The second group of commands are used to manage the physical drives attached to the controller. The third group of commands are used to manage the logical volumes managed by the controller. The fourth group of commands are used to manage the drive configuration for the controller. The fifth group of commands are used to manage controller-wide operations. .Pp The informational commands include: .Bl -tag -width indent .It Cm version Displays the version of .Nm . .It Cm show adapter Displays information about the RAID controller such as the model number. .It Cm show battery Displays information about the battery from the battery backup unit. .It Cm show config Displays the volume and drive configuration for the controller. Each array is listed along with the physical drives the array is built from. Each volume is listed along with the arrays that the volume spans. If any hot spare drives are configured, then they are listed as well. .It Cm show drives Lists all of the physical drives attached to the controller. .It Xo Cm show events .Op Fl c Ar class .Op Fl l Ar locale .Op Fl n Ar count .Op Fl v .Op Ar start Op Ar stop .Xc Display entries from the controller's event log. The controller maintains a circular buffer of events. Each event is tagged with a class and locale. .Pp The .Ar class parameter limits the output to entries at the specified class or higher. The default class is .Dq warn . The available classes from lowest priority to highest are: .Bl -tag -width indent .It Cm debug Debug messages. .It Cm progress Periodic progress updates for long-running operations such as background initializations, array rebuilds, or patrol reads. .It Cm info Informational messages such as drive insertions and volume creations. .It Cm warn Indicates that some component may be close to failing. .It Cm crit A component has failed, but no data is lost. For example, a volume becoming degraded due to a drive failure. .It Cm fatal A component has failed resulting in data loss. .It Cm dead The controller itself has died. .El .Pp The .Ar locale parameter limits the output to entries for the specified part of the controller. The default locale is .Dq all . The available locales are .Dq volume , .Dq drive , .Dq enclosure , .Dq battery , .Dq sas , .Dq controller , .Dq config , .Dq cluster , and .Dq all . .Pp The .Ar count parameter is a debugging aid that specifies the number of events to fetch from the controller for each low-level request. The default is 15 events. .Pp By default, matching event log entries from the previous shutdown up to the present are displayed. This range can be adjusted via the .Ar start and .Ar stop parameters. Each of these parameters can either be specified as a log entry number or as one of the following aliases: .Bl -tag -width indent .It Cm newest The newest entry in the event log. .It Cm oldest The oldest entry in the event log. .It Cm clear The first entry since the event log was cleared. .It Cm shutdown The entry in the event log corresponding to the last time the controller was cleanly shut down. .It Cm boot The entry in the event log corresponding to the most recent boot. .El .It Cm show firmware Lists all of the firmware images present on the controller. .It Cm show foreign Displays detected foreign configurations on disks for importation or removal. .It Cm show logstate Display the various sequence numbers associated with the event log. .It Cm show patrol Display the status of the controller's patrol read operation. .It Cm show progress Report the current progress and estimated completion time for active operations on all volumes and drives. .It Cm show volumes Lists all of the logical volumes managed by the controller. .El .Pp The physical drive management commands include: .Bl -tag -width indent .It Cm fail Ar drive Mark .Ar drive as failed. .Ar Drive must be an online drive that is part of an array. .It Cm good Ar drive Mark .Ar drive as an unconfigured good drive. .Ar Drive must not be part of an existing array. .It Cm rebuild Ar drive Mark a failed .Ar drive that is still part of an array as a good drive suitable for a rebuild. The firmware should kick off an array rebuild on its own if a failed drive is marked as a rebuild drive. .It Cm syspd Ar drive Present the drive to the host operating system as a disk SYSPD block device in the format /dev/mfisyspdX. Clear this flag with .Cm good .Ar drive .It Cm drive progress Ar drive Report the current progress and estimated completion time of drive operations such as rebuilds or patrol reads. .It Cm drive clear Ar drive Brq "start | stop" Start or stop the writing of all 0x00 characters to a drive. .It Cm start rebuild Ar drive Manually start a rebuild on .Ar drive . .It Cm abort rebuild Ar drive Abort an in-progress rebuild operation on .Ar drive . It can be resumed with the .Cm start rebuild command. .It Cm locate Ar drive Brq "on | off" Change the state of the external LED associated with .Ar drive . .El .Pp The logical volume management commands include: .Bl -tag -width indent .It Cm cache Ar volume Op Ar setting Oo Ar value Oc Op ... If no .Ar setting arguments are supplied, then the current cache policy for .Ar volume is displayed; otherwise, the cache policy for .Ar volume is modified. One or more .Ar setting arguments may be given. Some settings take an additional .Ar value argument as noted below. The valid settings are: .Bl -tag -width indent .It Cm enable Enable caching for both read and write I/O operations. .It Cm disable Disable caching for both read and write I/O operations. .It Cm reads Enable caching only for read I/O operations. .It Cm writes Enable caching only for write I/O operations. .It Cm write-back Use write-back policy for cached writes. .It Cm write-through Use write-through policy for cached writes. .It Cm read-ahead Ar value Set the read ahead policy for cached reads. The .Ar value argument can be set to either .Dq none , .Dq adaptive , or .Dq always . .It Cm bad-bbu-write-cache Ar value Control the behavior of I/O write caching if the battery is dead or missing. The .Ar value argument can be set to either .Dq disable or .Dq enable . In general this setting should be left disabled to avoid data loss when the system loses power. .It Cm write-cache Ar value Control the write caches on the physical drives backing .Ar volume . The .Ar value argument can be set to either .Dq disable , .Dq enable , or .Dq default . .Pp In general this setting should be left disabled to avoid data loss when the physical drives lose power. The battery backup of the RAID controller does not save data in the write caches of the physical drives. .El .It Cm name Ar volume Ar name Sets the name of .Ar volume to .Ar name . .It Cm volume progress Ar volume Report the current progress and estimated completion time of volume operations such as consistency checks and initializations. .El .Pp The configuration commands include: .Bl -tag -width indent .It Cm clear Delete the entire configuration including all volumes, arrays, and spares. .It Xo Cm create Ar type .Op Fl v .Op Fl s Ar stripe_size .Ar drive Ns Op \&, Ns Ar drive Ns Op ",..." .Op Ar drive Ns Op \&, Ns Ar drive Ns Op ",..." .Xc Create a new volume. The .Ar type specifies the type of volume to create. Currently supported types include: .Bl -tag -width indent .It Cm jbod Creates a RAID0 volume for each drive specified. Each drive must be specified as a separate argument. .It Cm raid0 Creates one RAID0 volume spanning the drives listed in the single drive list. .It Cm raid1 Creates one RAID1 volume spanning the drives listed in the single drive list. .It Cm raid5 Creates one RAID5 volume spanning the drives listed in the single drive list. .It Cm raid6 Creates one RAID6 volume spanning the drives listed in the single drive list. .It Cm raid10 Creates one RAID10 volume spanning multiple RAID1 arrays. The drives for each RAID1 array are specified as a single drive list. .It Cm raid50 Creates one RAID50 volume spanning multiple RAID5 arrays. The drives for each RAID5 array are specified as a single drive list. .It Cm raid60 Creates one RAID60 volume spanning multiple RAID6 arrays. The drives for each RAID6 array are specified as a single drive list. .It Cm concat Creates a single volume by concatenating all of the drives in the single drive list. .El .Pp .Sy Note : Not all volume types are supported by all controllers. .Pp If the .Fl v flag is specified after .Ar type , then more verbose output will be enabled. Currently this just provides notification as drives are added to arrays and arrays to volumes when building the configuration. .Pp The .Fl s .Ar stripe_size parameter allows the stripe size of the array to be set. By default a stripe size of 64K is used. Valid values are 512 through 1M, though the MFI firmware may reject some values. .It Cm delete Ar volume Delete the volume .Ar volume . .It Cm add Ar drive Op Ar volume Mark .Ar drive as a hot spare. .Ar Drive must be in the unconfigured good state. If .Ar volume is specified, then the hot spare will be dedicated to arrays backing that volume. Otherwise, .Ar drive will be used as a global hot spare backing all arrays for this controller. Note that .Ar drive must be as large as the smallest drive in all of the arrays it is going to back. .It Cm remove Ar drive Remove the hot spare .Ar drive from service. It will be placed in the unconfigured good state. .El .Pp The controller management commands include: .Bl -tag -width indent .It Cm patrol Ar command Op Ar interval Op Ar start Set the patrol read operation mode. The .Ar command argument can be one of the following values: .Bl -tag -width indent .It Cm disable Disable patrol reads. .It Cm auto Enable periodic patrol reads initiated by the firmware. The optional .Ar interval argument specifies the interval in seconds between patrol reads. If patrol reads should be run continuously, then .Ar interval should consist of the word .Dq continuously . The optional .Ar start argument specifies a non-negative, relative start time for the next patrol read. If an interval or start time is not specified, then the existing setting will be used. .It Cm manual Enable manual patrol reads that are only initiated by the user. .El .It Cm start patrol Start a patrol read operation. .It Cm stop patrol Stop a currently running patrol read operation. .It Cm foreign scan Scan for foreign configurations and display the number found. The .Ar config argument for the commands below takes the form of a number from 0 to the total configurations found. .It Cm foreign clear Op config Clear the specified foreign .Ar config or all if no .Ar config argument is provided. .It Cm foreign diag Op config Display a diagnostic display of the specified foreign .Ar config or all if no .Ar config argument is provided. .It Cm foreign preview Op config Preview the specified foreign .Ar config after import or all if no .Ar config argument is provided. .It Cm foreign import Op config Import the specified foreign .Ar config or all if no .Ar config argument is provided. .It Cm flash Ar file Updates the flash on the controller with the firmware stored in .Ar file . A reboot is required for the new firmware to take effect. .It Cm start learn Start a battery relearn. Note that this seems to always result in the battery being completely drained, regardless of the BBU mode. In particular, the controller write cache will be disabled during the relearn even if transparent learning mode is enabled. .It Cm bbu Ar setting Ar value Update battery backup unit (BBU) properties related to battery relearning. The following settings are configurable: .Bl -tag -width indent .It Cm learn-delay Add a delay to the next scheduled battery relearn event. This setting is given in hours and must lie in the range of 0 to 255. .It Cm autolearn-mode Enable or disable automatic periodic battery relearning. The setting may be set to .Dq enable or .Dq disable to respectively enable or disable the relearn cycle. Alternatively, a mode of 0, 1 or 2 may be given. Mode 0 enables periodic relearning, mode 1 disables it, and mode 2 disables it and logs a warning to the event log when it detects that a battery relearn should be performed. .It Cm bbu-mode Set the BBU's mode of operation. This setting is not supported by all BBUs. Where it is supported, the possible values are the integers between 1 and 5 inclusive. Modes 1, 2 and 3 enable a transparent learn cycle, whereas modes 4 and 5 do not. The BBU's data retention time is greater when transparent learning is not used. .El .It Cm ctrlprop Ar rebuild Op Ar rate With no arguments display the rate of rebuild (percentage)a for volumes. With an integer argument (0-100), set that value as the new rebuild rate for volumes. .It Cm ctrlprop Ar alarm Op Ar 0/1 With no arguments display the current alarm enable/disable status. With a 0, disable alarms. With a 1, enable alarms. .El .Sh EXAMPLES Configure the cache for volume mfid0 to cache only writes: .Pp .Dl Nm Cm cache mfid0 writes .Dl Nm Cm cache mfid0 write-back .Pp Create a RAID5 array spanning the first four disks in the second enclosure: .Pp .Dl Nm Cm create raid5 e1:s0,e1:s1,e1:s2,e1:s4 .Pp Configure the first three disks on a controller as JBOD: .Pp .Dl Nm Cm create jbod 0 1 2 .Pp Create a RAID10 volume that spans two arrays each of which contains two disks from two different enclosures: .Pp .Dl Nm Cm create raid10 e1:s0,e1:s1 e2:s0,e2:s1 .Pp Add drive with the device ID of 4 as a global hot spare: .Pp .Dl Nm Cm add 4 .Pp Add the drive in slot 2 in the main chassis as a hot spare for volume mfid0: .Pp .Dl Nm Cm add s2 mfid0 .Pp Reconfigure a disk as a SYSPD block device with no RAID .Pp .Dl Nm Cm syspd 0 .Pp Configure the adapter to run periodic patrol reads once a week with the first patrol read starting in 5 minutes: .Pp .Dl Nm Cm patrol auto 604800 300 .Pp Display the second detected foreign configuration: .Pp .Dl Nm Cm show foreign 1 .Pp Set the current rebuild rate for volumes to 40%: .Dl Nm Cm ctrlprop rebuild 40 .Sh SEE ALSO .Xr mfi 4 , .Xr mrsas 4 .Sh HISTORY The .Nm utility first appeared in .Fx 8.0 . diff --git a/usr.sbin/mlx5tool/mlx5tool.8 b/usr.sbin/mlx5tool/mlx5tool.8 index 17f0fd515a50..5f4157c4d49c 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 +.Xr 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 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 .