diff options
Diffstat (limited to 'usr/src/man/man5')
| -rw-r--r-- | usr/src/man/man5/Makefile | 6 | ||||
| -rw-r--r-- | usr/src/man/man5/epoll.5 | 113 | ||||
| -rw-r--r-- | usr/src/man/man5/eventfd.5 | 34 | ||||
| -rw-r--r-- | usr/src/man/man5/inotify.5 | 305 | ||||
| -rw-r--r-- | usr/src/man/man5/overlay.5 | 499 | ||||
| -rw-r--r-- | usr/src/man/man5/privileges.5 | 34 | ||||
| -rw-r--r-- | usr/src/man/man5/resource_controls.5 | 114 | ||||
| -rw-r--r-- | usr/src/man/man5/timerfd.5 | 44 |
8 files changed, 1139 insertions, 10 deletions
diff --git a/usr/src/man/man5/Makefile b/usr/src/man/man5/Makefile index 84d3f6aab6..27c549e44d 100644 --- a/usr/src/man/man5/Makefile +++ b/usr/src/man/man5/Makefile @@ -14,6 +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. # include $(SRC)/Makefile.master @@ -41,8 +42,10 @@ MANFILES= Intro.5 \ device_clean.5 \ dhcp.5 \ environ.5 \ + epoll.5 \ eqn.5 \ eqnchar.5 \ + eventfd.5 \ extendedFILE.5 \ filesystem.5 \ fnmatch.5 \ @@ -55,6 +58,7 @@ MANFILES= Intro.5 \ iconv_unicode.5 \ ieee802.3.5 \ ieee802.11.5 \ + inotify.5 \ ipfilter.5 \ isalist.5 \ kerberos.5 \ @@ -75,6 +79,7 @@ MANFILES= Intro.5 \ ms.5 \ mutex.5 \ nfssec.5 \ + overlay.5 \ pam_allow.5 \ pam_authtok_check.5 \ pam_authtok_get.5 \ @@ -119,6 +124,7 @@ MANFILES= Intro.5 \ tecla.5 \ term.5 \ threads.5 \ + timerfd.5 \ trusted_extensions.5 \ vgrindefs.5 \ zones.5 \ diff --git a/usr/src/man/man5/epoll.5 b/usr/src/man/man5/epoll.5 new file mode 100644 index 0000000000..94314861d9 --- /dev/null +++ b/usr/src/man/man5/epoll.5 @@ -0,0 +1,113 @@ +'\" 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 EPOLL 5 "Apr 17, 2014" +.SH NAME +epoll \- Linux-compatible I/O event notification facility +.SH SYNOPSIS + +.LP +.nf +#include <sys/epoll.h> +.fi + +.SH DESCRIPTION +.sp +.LP + +\fBepoll\fR is a facility for efficient event-oriented I/O that has a +similar model to \fBpoll\fR(2), but does not necessitate rescanning a +set of file descriptors to wait for an event. \fBepoll\fR is of Linux +origins, 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 +\fBepoll_create\fR(3C) creates an \fBepoll\fR instance, returning a file +descriptor. It contains a size arugment which is meaningful only in as +much as it cannot be 0. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBepoll_create1\fR(3C) also creates an \fBepoll\fR instance, but eliminates +the meaningless size argument -- replacing it instead with a flags +argument. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBepoll_ctl\fR(3C) allows file descriptors to be added +(via \fBEPOLL_CTL_ADD\fR), deleted (via \fBEPOLL_CTL_DEL\fR) or +modified (via \fBEPOLL_CTL_MOD\fR) with respect to the \fBepoll\fR'd set +of file descriptors. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBepoll_wait\fR(3C) fetches pending events for file descriptors added +via \fBepoll_ctl\fR(3C), blocking the caller if no such events are pending. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBepoll_pwait\fR(3C) opeates in a similar manner to \fBepoll_wait\fR(3C), but +allows the caller to specify a signal mask to be set atomically with respect +to waiting for events. +.RE + +.sp +.SH NOTES +.sp +.LP + +The \fBepoll\fR facility is implemented +for purposes of offering compatibility to and portability of Linux-borne +applications; native applications should continue to prefer using event ports +via the \fBport_create\fR(3C), +\fBport_associate\fR(3C) and \fBport_getn\fR(3C) interfaces. +In particular, use of \fBepoll\fR in a multithreaded environment is fraught +with peril; even when using \fBEPOLLONESHOT\fR for one-shot events, +there are race conditions with respect to \fBclose\fR(2) that are unresolvable. +(For more details, see the aborted effort in Linux to resolve this via the +proposed +\fBEPOLL_CTL_DISABLE\fR operation.) +The event port facility -- like the BSD kqueue facility that inspired it -- +is designed to deal with such issues via explicit event source dissociation. + +While a best effort has been made to mimic the Linux semantics, there +are some semantics that are too peculiar or ill-conceived to merit +accommodation. In particular, the Linux \fBepoll\fR facility will -- by +design -- continue to generate events for closed file descriptors where/when +the underlying file description remains open. For example, if one were +to \fBfork\fR(2) and subsequently close an actively \fBepoll\fR'd file +descriptor in the parent, +any events generated in the child on the implicitly duplicated file descriptor +will continue to be delivered to the parent -- despite the fact that the +parent itself no longer has any notion of the file description! +This \fBepoll\fR facility refuses to honor +these semantics; closing the \fBEPOLL_CTL_ADD\fR'd file descriptor +will always result in no further +events being generated for that event description. + +.SH SEE ALSO +.sp +.LP +\fBepoll_create\fR(3C), \fBepoll_create1\fR(3C), \fBepoll_ctl\fR(3C), +\fBepoll_wait\fR(3C), \fBepoll_pwait\fR(3C), +\fBport_create\fR(3C), \fBport_associate\fR(3C), \fBport_dissociate\fR(3C), +\fBport_get\fR(3C), +\fBpselect\fR(3C) diff --git a/usr/src/man/man5/eventfd.5 b/usr/src/man/man5/eventfd.5 new file mode 100644 index 0000000000..fc30495070 --- /dev/null +++ b/usr/src/man/man5/eventfd.5 @@ -0,0 +1,34 @@ +'\" 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 EVENTFD 5 "Dec 3, 2014" +.SH NAME +eventfd \- Linux-compatible user event notification facility +.SH SYNOPSIS + +.LP +.nf +#include <sys/eventfd.h> +.fi + +.SH DESCRIPTION +.sp +.LP + +\fBeventfd\fR is a Linux-borne facility for sending and receiving user +events via a file descriptor. While the facility itself is somewhat dubious +(it can be mimicked in an entirely portable way with a pipe), it is +small and straightforward and this implementation is entirely compatible +with its Linux antecedent; see \fBeventfd\fR(3C) for details. + +.SH SEE ALSO +.sp +.LP +\fBeventfd\fR(3C) diff --git a/usr/src/man/man5/inotify.5 b/usr/src/man/man5/inotify.5 new file mode 100644 index 0000000000..9b0016101d --- /dev/null +++ b/usr/src/man/man5/inotify.5 @@ -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 5 "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(5), 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(5) diff --git a/usr/src/man/man5/overlay.5 b/usr/src/man/man5/overlay.5 new file mode 100644 index 0000000000..12134ebb82 --- /dev/null +++ b/usr/src/man/man5/overlay.5 @@ -0,0 +1,499 @@ +.\" +.\" 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 2015 Joyent, Inc. +.\" +.Dd Apr 09, 2015 +.Dt OVERLAY 5 +.Os +.Sh NAME +.Nm overlay +.Nd Overlay Devices +.Sh DESCRIPTION +Overlay devices are a GLDv3 device that allows users to create overlay +networks that can be used to form the basis of network virtualization +and software defined networking. Overlay networks allow a single +physical network, often called an +.Sy underlay +network, to provide the means for creating multiple logical, isolated, +and discrete layer two and layer three networks on top of it. +.Pp +Overlay devices are administered through +.Xr dladm 1M . +Overlay devices themselves cannot be plumbed up with +.Sy IP , +.Sy vnd , +or any other protocol. Instead, like an +.Sy etherstub , +they allow for VNICs to be created on top of them. Like an +.Sy etherstub , +an overlay device acts as a local switch; however, when it encounters a +non-local destination address, it instead looks up where it should send +the packet, encapsulates it, and sends it out another interface in the +system. +.Pp +A single overlay device encapsulates the logic to answer two different, +but related, questions: +.Pp +.Bl -enum -offset indent -compact +.It +How should a packet be transformed and put on the wire? +.It +Where should a transformed packet be sent? +.El +.Pp +Each of these questions is answered by a plugin. The first question is +answered by what's called an +.Em encapsulation plugin . +The second question is answered by what's called a +.Em search plugin . +Packets are encapsulated and decapsulated using the encapsulation plugin +by the kernel. The search plugins are all user land plugins that are +consumed by the varpd service whose FMRI is +.Em svc:/network/varpd:default . +This separation allows for the kernel to be responsible for the data +path, while having the search plugins in userland allows the system to +provide a much more expressive interface. +.Ss Overlay Types +Overlay devices come in +two different flavors, one where all packets are always sent to a single +address, the other, where the destination of a packet varies based on +the target MAC address of the packet. This information is maintained in +a +.Em target table , +which is independent and unique to each overlay device. We call the +plugins that send traffic to a single location, for example a single +unicast or multicast IP address, a +.Sy point to point +overlay and the overlay devices that can send traffic to different +locations based on the MAC address of that packet a +.Sy dynamic +overlay. The plugin type is determined based on the type of the +.Sy search plugin . +These are all fully listed in the section +.Sx Plugins and their Properties . +.Ss Overlay Destination +Both encapsulation and search plugins define the kinds of destinations +that they know how to support. An encapsulation plugin always has a +single destination type that's determined based on how the encapsulation +is defined. A search plugin, on the other hand, can support multiple +combinations of destinations. A search plugin must support the +destination type of the encapsulation device. The destination may +require any of the following three pieces of information, depending on +the encapsulation plugin: +.Bl -hang -width Ds +.It Sy MAC Address +.Bd -filled -compact +An Ethernet MAC address is required to determine the destination. +.Ed +.It Sy IP Address +.Bd -filled -compact +An IP address is required. Both IPv4 and IPv6 addresses are supported. +.Ed +.It Sy Port +.Bd -filled -compact +An IP protocol level (TCP, UDP, SCTP, etc.) port is required. +.Ed +.El +.Pp +The list of destination types that are supported by both the search and +encapsulation plugins is listed in the section +.Sx Plugins and their Properties . +.Ss varpd +The varpd service, mentioned above, is responsible for providing the +virtual ARP daemon. Its responsibility is conceptually similar to ARP. +It runs all instances of search plugins in the system and is responsible +for answering the kernel's ARP-like questions for where packets should +be sent. +.Pp +The varpd service, svc:/network/varpd:default, must be enabled for +overlay devices to function. If it is disabled while there are active +devices, then most overlay devices will not function correctly and +likely will end up dropping traffic. +.Sh PLUGINS AND PROPERTIES +Properties fall into three categories in the system: +.Bl -enum -offset indent -compact +.It +Generic properties all overlay devices have +.It +Properties specific to the encapsulation plugin +.It +Properties specific to the search plugin +.El +.Pp +Each property in the system has the following attributes, which mirror +the traditional +.Xr dladm 1M +link properties: +.Bl -hang -width Ds +.It Sy Name +.Bd -filled -compact +The name of a property is namespaced by its module and always structured +and referred to as as module/property. This allows for both an +encapsulation and search plugin to have a property with the same name. +Properties that are valid for all overlay devices and not specific to a +module do not generally use a module prefix. +.Pp +For example, the property +.Sy vxlan/listen_ip +is associated with the +.Sy vxlan +encapsulation module. +.Ed +.It Sy Type +.Bd -filled -compact +Each property in the system has a type. +.Xr dladm 1M +takes care of converting between the internal representation and a +value, but the type influences the acceptable input range. The types +are: +.Bl -hang -width Ds +.It Sy INT +A signed integer that is up to eight bytes long +.Pq Sy int64_t . +.It Sy UINT +An unsigned integer that is up to eight bytes long +.Pq Sy uint64_t . +.It Sy IP +Either an IPv4 or IPv6 address in traditional string form. For example, +192.168.128.23 or 2001:470:8af4::1:1. IPv4 addresses may also be encoded +as IPv4-mapped IPv6 addresses. +.It Sy STRING +A string of ASCII or UTF-8 encoded characters terminated with a +.Sy NUL +byte. The maximum string length, including the terminator, is currently +256 bytes. +.El +.Ed +.It Sy Permissions +.Bd -filled -compact +Each property has permissions associated with it, which indicate whether +the system considers them read-only properties or read-write properties. +A read-only property can never be updated once the device is created. +This generally includes things like the overlay's encapsulation module. +.Ed +.It Sy Required +.Bd -filled -compact +This property indicates whether the property is required for the given +plugin. If it is not specified during a call to +.Sy dladm create-overlay , +then the overlay cannot be successfully created. Properties which have a +.Sy default +will use that value if one is not specified rather than cause the +overlay creation to fail. +.Ed +.It Sy Current Value +.Bd -filled -compact +The current value of a property, if the property has a value set. +Required properties always have a value set. +.Ed +.It Sy Default Value +.Bd -filled -compact +The default value is an optional part of a given property. If a property +does define a default value, then it will be used when an overlay is +created and no other value is given. +.Ed +.It Sy Value ranges +.Bd -filled -compact +Value ranges are an optional part of a given property. They indicate a +range or set of values that are valid and may be set for a property. A +property may not declare such a range as it may be impractical or +unknown. For example, most properties based on IP addresses will not +declare a range. +.Ed +.El +.Pp +The following sections describe both the modules and the properties that +exist for each module, noting their name, type, permissions, whether or +not they are required, and if there is a default value. In addition, the +effects of each property will be described. +.Ss Encapsulation Plugins +.Bl -hang -width Ds +.It Sy vxlan +The +.Sy vxlan +module is a UDP based encapsulation method. It takes a frame that would +be put on the wire, wraps it up in a VXLAN header and places it in a UDP +packet that gets sent out on the underlying network. For more details +about the specific format of the VXLAN header, see +.Xr vxlan 7P . +.Pp +The +.Sy vxlan +module requires both an +.Sy IP address +and +.Sy port +to address it. It has a 24-bit virtual network ID space, allowing for +virtual network identifiers that range from +.Sy 0 +- +.Sy 16777215 . +.Pp +The +.Sy vxlan +module has the following properties: +.Bl -hang -width Ds +.It Sy vxlan/listen_ip +.Bd -filled -compact +Type: +.Sy IP | +Permissions: +.Sy Read/Write | +.Sy Required +.Ed +.Bd -filled +The +.Sy vxlan/listen_ip +property determines the IP address that the system will accept VXLAN +encapsulated packets on for this overlay. +.Ed +.It Sy vxlan/listen_port +.Bd -filled -compact +Type: +.Sy UINT | +Permissions: +.Sy Read/Write | +.Sy Required +.Ed +.Bd -filled -compact +Default Value: +.Sy 4789 | +Range: +.Sy 0 - 65535 +.Ed +.Bd -filled +The +.Sy vxlan/listen_port +property determines the UDP port that the system will listen on for +VXLAN traffic for this overlay. The default value is +.Sy 4789 , +the IANA assigned port for VXLAN. +.Ed +.El +.Pp +The +.Sy vxlan/listen_ip +and +.Sy vxlan/listen_port +properties determine how the system will accept VXLAN encapsulated +packets for this interface. It does not determine the interface that +packets will be sent out over. Multiple overlays that all use VXLAN can +share the same IP and port combination, as the virtual network +identifier can be used to tell the different overlays apart. +.El +.Ss Search Plugins +Because search plugins may support multiple destinations, they may have +more properties listed than necessarily show up for a given overlay. +For example, the +.Sy direct +plugin supports destinations that are identified by both an IP address +and a port, or just an IP address. In cases where the device is created +over an overlay that only uses an IP address for its destination, then +it will not have the +.Sy direct/dest_port +property. +.Bl -hang -width Ds +.It Sy direct +The +.Sy direct +plugin is a point to point module that can be used to create an overlay +that forwards all non-local traffic to a single destination. It supports +destinations that are a combination of an +.Sy IP Address +and a +.Sy port . +.Pp +The +.Sy direct +plugin has the following properties: +.Bl -hang -width Ds +.It Sy direct/dest_ip +.Bd -filled -compact +Type: +.Sy IP | +Permissions: +.Sy Read/Write | +.Sy Required +.Ed +.Bd -filled +The +.Sy direct/dest_ip +property indicates the IP address that all traffic will be sent out. +Traffic will be sent out the corresponding interface based on +traditional IP routing rules and the configuration of the networking +stack of the global zone. +.Ed +.It Sy direct/dest_port +.Bd -filled -compact +Type: +.Sy UINT | +Permissions: +.Sy Read/Write | +.Sy Required +.Ed +.Bd -filled -compact +Default Value: +.Sy - | +Range: +.Sy 0 - 65535 +.Ed +.Bd -filled +The +.Sy direct/dest_port +property indicates the TCP or UDP port that all traffic will be directed +to. +.Ed +.El +.It Sy files +The +.Sy files +plugin implements a +.Sy dynamic +plugin that specifies where traffic should be sent based on a file. It +is a glorified verison of /etc/ethers. The +.Sy dynamic +plugin does not support broadcast or multicast traffic, but it has +support for proxy ARP, NDP, and DHCPv4. For the full details of the file +format, see +.Xr overlay_files 4 . +.Pp +The +.Sy files +plugin has the following property: +.Bl -hang -width Ds +.It Sy files/config +.Bd -filled -compact +Type: +.Sy String | +Permissions: +.Sy Read/Write | +.Sy Required +.Ed +.Bd -filled +The +.Sy files/config +property specifies an absolute path to a file to read. The file is a +JSON file that is formatted according to +.Xr overlay_files 4 . +.Ed +.El +.El +.Ss General Properties +Each overaly has the following properties which are used to give +additional information about the system. None of these properties may be +specified as part of a +.Sy dladm create-overlay , +instead they come from other arguments or from internal parts of the +system. +.Bl -hang -width Ds +.It Sy encap +.Bd -filled -compact +.Sy String | +Permissions: +.Sy Read Only +.Ed +.Bd -filled +The +.Sy encap +property contains the name of the encapsulation module that's in use. +.Ed +.It Sy mtu +.Bd -filled -compact +.Sy UINT | +Permissions: +.Sy Read/Write +.Ed +.Bd -filled -compact +Default Value: +.Sy 1400 | +Range: +.Sy 576 - 9000 +.Ed +.Bd -filled +The +.Sy mtu +property describes the maximum transmission unit of the overlay. The +default value is +.Sy 1400 +bytes, which ensures that in a traditional deployment with an MTU of +1500 bytes, the overhead that is added from encapsulation is all +accounted for. It is the administrator's responsibility to ensure that +the device's MTU and the encapsulation overhead does not exceed that of +the interfaces that the encapsulated traffic will be sent out of. +.Pp +To modify the +.Sy mtu +property, use +.Sy dladm set-linkprop . +.Ed +.It Sy search +.Bd -filled -compact +.Sy String | +Permissions: +.Sy Read Only +.Ed +.Bd -filled +The +.Sy search +property contains the name of the search plugin that's in use. +.Ed +.It Sy varpd/id +.Bd -filled -compact +.Sy String | +Permissions: +.Sy Read Only +.Ed +.Bd -filled +The +.Sy varpd/id +property indicates the identifier which the +.Sy varpd +service uses for this overlay. +.Ed +.It Sy vnetid +.Bd -filled -compact +.Sy UINT | +Permissions: +.Sy Read/Write +.Ed +.Bd -filled +The +.Sy vnetid +property has the virtual network identifier that belongs to this overlay. +The valid range for the virtual network identifier depends on the +encapsulation engine. +.Ed +.El +.Sh FMA INTEGRATION +Overlay devices are wired into FMA, the illumos fault management +architecture, and generates error reports depending on the +.Sy search +plugin in use. Due to limitations in FMA today, when a single overlay +enters a degraded state, meaning that it cannot properly perform look +ups or another error occurred, then it degrades the overall +.Sy overlay +psuedo-device driver. +.Pp +For more fine-grained information about which overlay is actually in a +.Em degraded +state, one should run +.Sy dladm show-overlay -f . +In addition, for each overlay in a degraded state a more useful +diagnostic message is provided which describes the reason that caused +this overlay to enter into a degraded state. +.Pp +The overlay driver is self-healing. If the problem corrects itself on +its own, it will clear the fault on the corresponding device. +.Sh SEE ALSO +.Xr dladm 1M , +.Xr overlay_files 4 , +.Xr vxlan 7P diff --git a/usr/src/man/man5/privileges.5 b/usr/src/man/man5/privileges.5 index 294eb378b4..260a768e81 100644 --- a/usr/src/man/man5/privileges.5 +++ b/usr/src/man/man5/privileges.5 @@ -1,10 +1,10 @@ '\" te .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved. -.\" Copyright 2013, Joyent, Inc. All Rights Reserved. +.\" Copyright 2015, Joyent, Inc. All Rights Reserved. .\" 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 PRIVILEGES 5 "Feb 3, 2015" +.TH PRIVILEGES 5 "Apr 15, 2015" .SH NAME privileges \- process privilege model .SH DESCRIPTION @@ -303,6 +303,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 @@ -517,6 +527,16 @@ Allow a process to lock pages in physical memory. .sp .ne 2 .na +\fB\fBPRIV_PROC_MEMINFO\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to access physical memory information. +.RE + +.sp +.ne 2 +.na \fB\fBPRIV_PROC_OWNER\fR\fR .ad .sp .6 @@ -670,6 +690,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/man5/resource_controls.5 b/usr/src/man/man5/resource_controls.5 index 745d777624..35a78aae6e 100644 --- a/usr/src/man/man5/resource_controls.5 +++ b/usr/src/man/man5/resource_controls.5 @@ -1,16 +1,18 @@ '\" te .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2012, Joyent, Inc. All Rights Reserved. .\" 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 5 "Jul 19, 2013" .SH NAME -resource_controls \- resource controls available through project database +resource_controls \- resource controls available through projects and zones .SH DESCRIPTION .sp .LP -The resource controls facility is configured through the project database. See -\fBproject\fR(4). You can set and modify resource controls through the +For projects the resource controls facility is configured through the project +database. See \fBproject\fR(4). For zones, resource controls are configured +through \fBzonecfg\fR(1M). You can set and modify resource controls through the following utilities: .RS +4 .TP @@ -36,6 +38,12 @@ following utilities: .el o \fBrctladm\fR(1M) .RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBzonecfg\fR(1M) +.RE .sp .LP In a program, you use \fBsetrctl\fR(2) to set resource control values. @@ -283,6 +291,19 @@ Maximum allowable number of event ports, expressed as an integer. .sp .ne 2 .na +\fB\fBproject.max-processes\fR\fR +.ad +.sp .6 +.RS 4n +Maximum number of processes that can be active in a project. This rctl is +similar to \fBproject.max-lwps\fR, except that zombie processes are included. +This rctl prevents process-slot exhaustion which can occur due to an excessive +number of zombies. Expressed as an integer. +.RE + +.sp +.ne 2 +.na \fB\fBproject.max-sem-ids\fR\fR .ad .sp .6 @@ -371,6 +392,33 @@ The following zone-wide resource controls are available: .sp .ne 2 .na +\fB\fBzone.cpu-baseline\fR\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 +\fB\fBzone.cpu-burst-time\fR\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 \fB\fBzone.cpu-cap\fR\fR .ad .sp .6 @@ -389,7 +437,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 @@ -409,14 +457,25 @@ Total amount of physical locked memory available to a zone. .sp .ne 2 .na +\fB\fBzone.max-lofi\fR\fR +.ad +.sp .6 +.RS 4n +Sets a limit on the number of \fBLOFI\fR(7D) devices that can be created in a +zone. Expressed as an integer. This resource control does not support the +\fBsyslog\fR action. +.RE + +.sp +.ne 2 +.na \fB\fBzone.max-lwps\fR\fR .ad .sp .6 .RS 4n -Enhances resource isolation by preventing too many LWPs in one zone from -affecting other zones. A zone's total LWPs can be further subdivided among -projects within the zone within the zone by using \fBproject.max-lwps\fR -entries. Expressed as an integer. +Sets a limit on how many LWPs can be active in a zone. A zone's total LWPs +can be further subdivided among projects within the zone within the zone by +using \fBproject.max-lwps\fR entries. Expressed as an integer. .RE .sp @@ -433,6 +492,33 @@ integer. .sp .ne 2 .na +\fB\fBzone.max-physical-memory\fR\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. +.RE + +.sp +.ne 2 +.na +\fB\fBzone.max-processes\fR\fR +.ad +.sp .6 +.RS 4n +Maximum number of processes that can be active in a zone. This rctl is +similar to \fBzone.max-lwps\fR, except that zombie processes are included. +This rctl prevents process-slot exhaustion which can occur due to an excessive +number of zombies. This rctl can be further subdivided among projects within +the zone using \fBproject.max-processes\fR. Expressed as an integer. +.RE + +.sp +.ne 2 +.na \fB\fBzone.max-sem-ids\fR\fR .ad .sp .6 @@ -474,6 +560,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(1M) 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(5). .SS "Units Used in Resource Controls" diff --git a/usr/src/man/man5/timerfd.5 b/usr/src/man/man5/timerfd.5 new file mode 100644 index 0000000000..a6829901aa --- /dev/null +++ b/usr/src/man/man5/timerfd.5 @@ -0,0 +1,44 @@ +'\" te +.\" Copyright (c) 2015, 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 TIMERFD 5 "Feb 23, 2015" +.SH NAME +timerfd \- Linux-compatible timer notification facility +.SH SYNOPSIS + +.LP +.nf +#include <sys/timerfd.h> +.fi + +.SH DESCRIPTION +.sp +.LP + +\fBtimerfd\fR is a Linux-borne facility for creating POSIX timers and +receiving their subsequent events via a file descriptor. +The facility itself is arguably unnecessary: +portable code can either use the timeout value present in +\fBpoll\fR(2)/\fBport_get\fR(3C)/\fBepoll_wait\fR(3C) or -- if this +is deemed of unacceptably poor resolution -- create a POSIX timer +via \fBtimer_create\fR(3C) and use the resulting signal to induce an +\fBEINTR\fR to polling threads. (For code that need not be +portable, the \fBSIGEV_PORT\fR signal notification allows for explicit, +event-oriented timer notification to be sent to a specified port; +see \fBsignal.h\fR(3HEAD) for details.) +This facility therefore exists only to accommodate Linux-borne +applications and binaries; it is compatible with its Linux antecedent in both +binary interface and in semantics. + +.SH SEE ALSO +.sp +.LP +\fBtimerfd_create\fR(3C), \fBtimerfd_gettime\fR(3C), \fBtimerfd_settime\fR(3C) + |