diff options
Diffstat (limited to 'usr/src/man/man7')
| -rw-r--r-- | usr/src/man/man7/Makefile | 6 | ||||
| -rw-r--r-- | usr/src/man/man7/inotify.7 | 305 | ||||
| -rw-r--r-- | usr/src/man/man7/lx.7 | 113 | ||||
| -rw-r--r-- | usr/src/man/man7/privileges.7 | 20 | ||||
| -rw-r--r-- | usr/src/man/man7/resource_controls.7 | 74 |
5 files changed, 513 insertions, 5 deletions
diff --git a/usr/src/man/man7/Makefile b/usr/src/man/man7/Makefile index 2527fc1008..6ce3008a0c 100644 --- a/usr/src/man/man7/Makefile +++ b/usr/src/man/man7/Makefile @@ -14,7 +14,7 @@ # Copyright (c) 2012 by Delphix. All rights reserved. # Copyright 2014 Nexenta Systems, Inc. # Copyright 2014 Garrett D'Amore <garrett@damore.org> -# Copyright (c) 2015, Joyent, Inc. All rights reserved. +# Copyright 2017 Joyent, Inc. # Copyright 2018 Gary Mills # Copyright 2019 OmniOS Community Edition (OmniOSce) Association. # Copyright 2019 Peter Tribble @@ -62,6 +62,7 @@ _MANFILES= Intro.7 \ iconv_unicode.7 \ ieee802.3.7 \ ieee802.11.7 \ + inotify.7 \ ipfilter.7 \ isalist.7 \ kerberos.7 \ @@ -72,6 +73,7 @@ _MANFILES= Intro.7 \ lfcompile.7 \ lfcompile64.7 \ locale.7 \ + lx.7 \ man.7 \ mandoc_char.7 \ mandoc_roff.7 \ @@ -135,8 +137,6 @@ _MANFILES= Intro.7 \ zones.7 \ zpool-features.7 -sparc_MANFILES= - i386_MANFILES= beastie.4th.7 \ brand.4th.7 \ check-password.4th.7 \ diff --git a/usr/src/man/man7/inotify.7 b/usr/src/man/man7/inotify.7 new file mode 100644 index 0000000000..13ea10cf2b --- /dev/null +++ b/usr/src/man/man7/inotify.7 @@ -0,0 +1,305 @@ +'\" te +.\" Copyright (c) 2014, Joyent, Inc. All Rights Reserved. +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.TH INOTIFY 7 "Sep 17, 2014" +.SH NAME +inotify \- Linux-compatible file event notification facility +.SH SYNOPSIS + +.LP +.nf +#include <sys/inotify.h> +.fi + +.SH DESCRIPTION +.sp +.LP + +\fBinotify\fR is a facility for receiving file system events on specified +files or directories. When monitoring a directory, \fBinotify\fR can be +used to retrieve events not only on the directory, but also on any files +that the directory contains. \fBinotify\fR originated with Linux, and +this facility is designed to be binary-compatible with the Linux facility, +including the following interfaces: + +.RS +4 +.TP +.ie t \(bu +.el o +\fBinotify_init\fR(3C) creates an \fBinotify\fR instance, returning a file +descriptor associated with the in-kernel event queue. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBinotify_init1\fR(3C) also creates an \fBinotify\fR instance, but allows +for a flags argument that controls some attributes of the returned file +descriptor. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBinotify_add_watch\fR(3C) allows a watch of a particular file or directory +to be added to a watch list associated with the specified \fBinotify\fR +instance. \fBinotify_add_watch\fR(3C) returns a watch descriptor that will +be reflected in the \fIwd\fR member of the \fIinotify_event\fR structure +returned via a \fBread\fR(2) of the instance. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBinotify_rm_watch\fR(3C) removes the watch that corresponds to the specified +watch descriptor. +.RE + +When all file descriptors referring to a particular \fBinotify\fR instance +are closed, the instance and all watches associated with that instance are +freed. + +To consume events on an \fBinotify\fR instance, an application should +issue a \fBread\fR(2) to the instance. If no events are available +(and the \fBinotify\fR instance has not been explicitly made non-blocking +via \fBinotify_init1\fR(3C)) the \fBread\fR(2) will block until a +watched event occurs. If and when events are available, \fBread\fR(2) will +return an array of the following structures: + +.sp +.in +2 +.nf +struct inotify_event { + int wd; /* watch descriptor */ + uint32_t mask; /* mask of event */ + uint32_t cookie; /* cookie for associating renames */ + uint32_t len; /* size of name field */ + char name[]; /* optional name */ +}; +.fi +.in -2 + +\fIwd\fR contains the watch descriptor that corresponds to the event, +as returned by \fBinotify_add_watch\fR(3C). + +\fImask\fR is a bitwise \fBOR\fR of event masks (see below) that +describes the event. + +\fIcookie\fR is an opaque value that can be used to associate different +events into a single logical event. In particular, it allows consumers to +associate \fBIN_MOVED_FROM\fR events with subsequent \fBIN_MOVED_TO\fR +events. + +\fIlen\fR denotes the length of the \fIname\fR field, including any padding +required for trailing null bytes and alignment. The size of the entire +event is therefore the size of the \fIinotify_event\fR structure plus the +value of \fIlen\fR. + +\fIname\fR contains the name of the file associated with the event, if any. +This field is only present when the watched entity is a directory and +the event corresponds to a file that was contained by the watched directory +(though see \fBNOTES\fR and \fBWARNINGS\fR for details and limitations). +When present, \fIname\fR is null terminated, and may contain additional +zero bytes +to pad for alignment. (The length of this field -- including any bytes +for alignment -- is denoted by the \fIlen\fR field.) + +.SS "Events" + +The events that can be generated on a watched entity are as follows: + +.sp +.in +2 +.TS +c c +l l . +\fIEvent\fR \fIDescription\fR +\fBIN_ACCESS\fR File/directory was accessed +\fBIN_ATTRIB\fR File/directory attributes were changed +\fBIN_CLOSE_WRITE\fR File/directory opened for writing was closed +\fBIN_CLOSE_NOWRITE\fR File/directory not opened for writing was closed +\fBIN_CREATE\fR File/directory created in watched directory +\fBIN_DELETE\fR File/directory deleted from watched directory +\fBIN_DELETE_SELF\fR Watched file/directory was deleted +\fBIN_MODIFY\fR File/directory was modified +\fBIN_MODIFY_SELF\fR Watched file/directory was modified +\fBIN_MOVED_FROM\fR File was renamed from entity in watched directory +\fBIN_MOVED_TO\fR File was renamed to entity in watched directory +\fBIN_OPEN\fR File/directory was opened +.TE +.in -2 + +Of these, all events except \fBIN_MOVE_SELF\fR and \fBIN_DELETE_SELF\fR +can refer to either the watched entity or (if the watched entity +is a directory) a file or directory contained by the watched directory. +(See \fBNOTES\fR and \fBWARNINGS\fR, below for details on this +mechanism and its limitations.) +If the event corresponds to a contained entity, +\fIname\fR will be set to the name of the affected +entity. + +In addition to speciyfing events of interest, watched events may +be modified by potentially setting any of the following when adding a +watch via \fBinotify_add_watch\fR(3C): + +.sp +.ne 2 +.na +\fBIN_DONT_FOLLOW\fR +.ad +.RS 12n +Don't follow the specified pathname if it is a symbolic link. +.RE + +.sp +.ne 2 +.na +\fBIN_EXCL_UNLINK\fR +.ad +.RS 12n +If watching a directory and a contained entity becomes unlinked, cease +generating events for that entity. (By default, contained entities will +continue to generate events on their former parent directory.) +.RE + +.sp +.ne 2 +.na +\fBIN_MASK_ADD\fR +.ad +.RS 12n +If the specified pathname is already being watched, the specified events +will be added to the watched events instead of the default behavior of +replacing them. (If one +may forgive the editorializing, this particular interface gewgaw +seems entirely superfluous, and a canonical example of +feasibility trumping wisdom.) +.RE + +.sp +.ne 2 +.na +\fBIN_ONESHOT\fR +.ad +.RS 12n +Once an event has been generated for the watched entity, remove the +watch from the watch list as if \fBinotify_rm_watch\fR(3C) had been called +on it (thereby inducing an \fBIN_IGNORED\fR event). +.RE + +.sp +.ne 2 +.na +\fBIN_ONLYDIR\fR +.ad +.RS 12n +Only watch the specified pathname if it is a directory. +.RE + +In addition to the specified events, the following bits may be specified +in the \fImask\fR field as returned from \fBread\fR(2): + +.sp +.ne 2 +.na +\fBIN_IGNORED\fR +.ad +.RS 12n +A watch was removed explicitly (i.e, via \fBinotify_rm_watch\fR(3C)) or +implicitly (e.g., because \fBIN_ONESHOT\fR was set or because the watched +entity was deleted). +.RE + +.sp +.ne 2 +.na +\fBIN_ISDIR\fR +.ad +.RS 12n +The entity inducing the event is a directory. +.RE + +.sp +.ne 2 +.na +\fBIN_Q_OVERFLOW\fR +.ad +.RS 12n +The event queue exceeded the maximum event queue length per instance. +(By default, this is 16384, but it can be tuned by setting +\fBinotify_maxevents\fR via \fB/etc/system\fR.) +.RE + +.sp +.ne 2 +.na +\fBIN_UNMOUNT\fR +.ad +.RS 12n +The filesystem containing the watched entity was unmounted. +.RE + +.sp +.SH NOTES +.sp +.LP + +\fBinotify\fR instances can be monitored via \fBpoll\fR(2), +\fBport_get\fR(3C), \fBepoll\fR(7), etc. + +The event queue associated with an \fBinotify\fR instance is serialized +and ordered: events will be placed on the tail of the queue in the order +that they occur. + +If at the time an event occurs the tail of the event queue is identical +to the newly received event, the newly received event will be dropped, +effectively coalescing the two events. + +When watching a directory and receieving events on contained elements +(i.e., a contained file or subdirectory), note that the information +received in the \fIname\fR field may be stale: the file may have been +renamed between the event and its processing. If a file has been unlinked +(and if \fBIN_EXCL_UNLINK\fR has not been set), +the \fIname\fR will reflect the last name that resolved to the file. +If a new file is created in the same directory with the old name, events +on the new file and the old (unlinked) file will become undistinguishable. + +The number of bytes that are available to be read on an \fBinotify\fR +instance can be determined via a \fBFIONREAD\fR \fBioctl\fR(2). + +.sp +.SH WARNINGS +.sp +.LP + +While a best effort has been made to mimic the Linux semantics, there +remains a fundamental difference with respect to hard links: on Linux, +if a file has multiple hard links to it, a notification on a watched +directory or file will be received if and only if that event was received +via the watched path. For events that are induced by open files +(such as \fBIN_MODIFY\fR), these semantics seem peculiar: the watched +file is in fact changing, but because it is not changing via the watched +path, no notification is received. By contrast, the implementation here +will always yield an event in this case -- even if the event was induced +by an \fBopen\fR(2) via an unwatched path. If an event occurs within a +watched directory on a file for which there exist multiple hard links within +the same (watched) directory, the event's \fIname\fR will correspond to one +of the links to the file. If multiple hard links exist to the +same file in the same watched directory and one of the links is removed, +notifications may not necessarily continue to be received for the file, +despite the (remaining) link in the watched directory; users of +\fBinotify\fR should exercise extreme caution when watching directories +that contain files with multiple hard links in the same directory. + +.SH SEE ALSO +.sp +.LP +\fBinotify_init\fR(3C), \fBinotify_init1\fR(3C), \fBinotify_add_watch\fR(3C), +\fBinotify_rm_watch\fR(3C), \fBport_get\fR(3C), \fBepoll\fR(7) diff --git a/usr/src/man/man7/lx.7 b/usr/src/man/man7/lx.7 new file mode 100644 index 0000000000..a45ead418c --- /dev/null +++ b/usr/src/man/man7/lx.7 @@ -0,0 +1,113 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016, Joyent, Inc. +.\" +.Dd February 5, 2106 +.Dt LX 7 +.Os +.Sh NAME +.Nm lx +.Nd zone brand for running a GNU/Linux user-level environment +.Sh DESCRIPTION +The +.Em lx +brand +uses the +.Xr brands 7 +framework to provide an environment for running binary applications built +for GNU/Linux. +User-level code, including an entire Linux distribution, can run inside the +zone. +Both 32-bit and 64-bit applications are supported. +The majority of Linux system calls are provided, along with emulation for a +variety of Linux file systems, such as +.Em proc , +.Em cgroup +and +.Em sysfs . +.Pp +The +.Em /proc +file system within the zone is a subset of a full Linux +.Em /proc . +Most kernel-level tuning applied to +.Em /proc +is unavailable or ignored. +Some tuning can be performed, but only to reduce the overall limits that have +been specified on the zone's configuration. +That is, within the zone there is no way to increase the resource limits set on +the zone itself. +.Pp +The zone must be installed using a clone of a +.Xr zfs 8 +dataset which contains an image of the software to be run in the zone. +.Pp +Example: +.Dl zoneadm -z myzone install -x nodataset -t debian7 +.Pp +Applications provided by the base SunOS operating system are also available +within the zone under the +.Em /native +mount point. +This allows the use of various native tools such as +.Xr dtrace 8 , +.Xr mdb 1 , +or the +.Xr proc 1 +tools on GNU/Linux applications. +However, not every native tool will work properly within an +.Em lx +zone. +.Sh CONFIGURATION +The +.Em kernel-version +attribute can be included in the zone's +.Xr zonecfg 8 +settings as a way to specify the Linux version that the zone is emulating. +For example, the value could be +.Em 3.13.0 . +.Sh LIMITATIONS +The brand only supports the exclusive IP stack zone configuration. +.Pp +Most modern GNU/Linux application software runs on +.Em lx , +but because there are some system calls or file systems which are not currently +implemented, it's possible that an application won't run. +This does not preclude the application running in the future as the +.Em lx +brand adds new capabilities. +.Pp +Because there is only the single SunOS kernel running on the system, there +is no support for any Linux kernel-level modules. +That is, there is no support for add-on drivers or any other modules that are +part of the Linux kernel itself. +If that is required, a full virtual machine should be used instead of an +.Em lx +branded zone. +.Pp +Any core files produced within the zone are in the native SunOS format. +.Pp +As with any zone, the normal security mechanisms and privileges apply. +Thus, certain operations (for example, changing the system time), will not be +allowed unless the zone has been configured with the appropriate additional +privileges. +.Sh SEE ALSO +.Xr mdb 1 , +.Xr proc 1 , +.Xr brands 7 , +.Xr privileges 7 , +.Xr resource_controls 7 , +.Xr zones 7 , +.Xr dtrace 8 , +.Xr zfs 8 , +.Xr zoneadm 8 , +.Xr zonecfg 8 diff --git a/usr/src/man/man7/privileges.7 b/usr/src/man/man7/privileges.7 index aade5c020c..b2d51cccf8 100644 --- a/usr/src/man/man7/privileges.7 +++ b/usr/src/man/man7/privileges.7 @@ -307,6 +307,16 @@ Allow a process to perform privileged mappings through a graphics device. .sp .ne 2 .na +\fB\fBPRIV_HYPRLOFS_CONTROL\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to perform hyprlofs name space management. +.RE + +.sp +.ne 2 +.na \fB\fBPRIV_IPC_DAC_READ\fR\fR .ad .sp .6 @@ -697,6 +707,16 @@ Allow a process to configure a system's datalink interfaces. .sp .ne 2 .na +\fB\fBPRIV_SYS_FS_IMPORT\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to import a potentially untrusted file system (e.g. ZFS recv). +.RE + +.sp +.ne 2 +.na \fB\fBPRIV_SYS_IP_CONFIG\fR\fR .ad .sp .6 diff --git a/usr/src/man/man7/resource_controls.7 b/usr/src/man/man7/resource_controls.7 index e9928399aa..34392538bc 100644 --- a/usr/src/man/man7/resource_controls.7 +++ b/usr/src/man/man7/resource_controls.7 @@ -1,12 +1,13 @@ '\" te .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 2017, Joyent, Inc. .\" Copyright 2021 OmniOS Community Edition (OmniOSce) Association. .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] .TH RESOURCE_CONTROLS 7 "Jan 23, 2021" .SH NAME -resource_controls \- resource controls available through project database +resource_controls \- resource controls available through projects and zones .SH DESCRIPTION The resource controls facility is configured through the project database. See \fBproject\fR(5). You can set and modify resource controls through the @@ -35,6 +36,12 @@ following utilities: .el o .BR rctladm (8) .RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBzonecfg\fR(8) +.RE .sp .LP In a program, you use \fBsetrctl\fR(2) to set resource control values. @@ -407,6 +414,33 @@ The following zone-wide resource controls are available: .sp .ne 2 .na +\fBzone.cpu-baseline\fR +.ad +.sp .6 +.RS 4n +Sets a baseline amount of CPU time that a zone can use before it is considered +to be bursting. The unit used is the percentage of a single CPU that is being +used by all user threads in a zone. The value should be less than the +\fBzone.cpu-cap\fR rctl value and is expressed as an integer. +This resource control does not support the \fBsyslog\fR action. +.RE + +.sp +.ne 2 +.na +\fBzone.cpu-burst-time\fR +.ad +.sp .6 +.RS 4n +Sets the number of seconds that a zone can exceed the \fBzone.cpu-baseline\fR +rctl value before being cpu-capped down to the \fBzone.cpu-baseline\fR. +A value of 0 means that \fBzone.cpu-baseline\fR can be exceeded indefinitely. +This resource control does not support the \fBsyslog\fR action. +.RE + +.sp +.ne 2 +.na \fBzone.cpu-cap\fR .ad .sp .6 @@ -425,7 +459,7 @@ not support the \fBsyslog\fR action. .ad .sp .6 .RS 4n -Sets a limit on the number of fair share scheduler (FSS) CPU shares for a zone. +Sets a value on the number of fair share scheduler (FSS) CPU shares for a zone. CPU shares are first allocated to the zone, and then further subdivided among projects within the zone as specified in the \fBproject.cpu-shares\fR entries. Expressed as an integer. This resource control does not support the @@ -445,6 +479,15 @@ Total amount of physical locked memory available to a zone. .sp .ne 2 .na +\fBzone.max-lofi\fR +.ad +.sp .6 +.RS 4n +Sets a limit on the number of \fBLOFI\fR(4D) devices that can be created in a +zone. Expressed as an integer. This resource control does not support the +\fBsyslog\fR action. +.RE + \fBzone.max-lwps\fR .ad .sp .6 @@ -469,6 +512,14 @@ integer. .sp .ne 2 .na +\fBzone.max-physical-memory\fR +.ad +.sp .6 +.RS 4n +Sets a limit on the amount of physical memory (RSS) that can be used by a zone +before resident pages start being forcibly paged out. The unit used is bytes. +Expressed as an integer. This resource control does not support the +\fBsyslog\fR action. \fBzone.max-processes\fR .ad .sp .6 @@ -482,6 +533,11 @@ Expressed as an integer. .sp .ne 2 .na +.RE + +.sp +.ne 2 +.na \fBzone.max-sem-ids\fR .ad .sp .6 @@ -523,6 +579,18 @@ mappings and \fBtmpfs\fR mounts for this zone. .RE .sp +.ne 2 +.na +\fB\fBzone.zfs-io-priority\fR\fR +.ad +.sp .6 +.RS 4n +Sets a value for the \fBzfs\fR(8) I/O priority for a zone. This is used as +one of the inputs to determine if a zone's I/O should be throttled. Expressed +as an integer. This resource control does not support the \fBsyslog\fR action. +.RE + +.sp .LP See \fBzones\fR(7). .SS "Units Used in Resource Controls" @@ -1032,6 +1100,8 @@ Interface Stability Evolving .BR FSS (4), .BR project (5), .BR attributes (7), +.BR privileges (7), +.BR zones (7), .BR pooladm (8), .BR poolcfg (8), .BR projadd (8), |