From 9498a983a938cec96851b64642f0b62bba7d1827 Mon Sep 17 00:00:00 2001 From: dd Date: Wed, 17 Jul 2002 01:46:48 +0000 Subject: Introduce the DEVFS "rule" subsystem. DEVFS rules permit the administrator to define certain properties of new devfs nodes before they become visible to the userland. Both static (e.g., /dev/speaker) and dynamic (e.g., /dev/bpf*, some removable devices) nodes are supported. Each DEVFS mount may have a different ruleset assigned to it, permitting different policies to be implemented for things like jails. Approved by: phk --- sbin/devfs/devfs.8 | 326 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 326 insertions(+) create mode 100644 sbin/devfs/devfs.8 (limited to 'sbin/devfs/devfs.8') diff --git a/sbin/devfs/devfs.8 b/sbin/devfs/devfs.8 new file mode 100644 index 0000000..48e63c6 --- /dev/null +++ b/sbin/devfs/devfs.8 @@ -0,0 +1,326 @@ +.\" +.\" Copyright (c) 2002 Dima Dorfman. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dt DEVFS 8 +.Dd July 1, 2002 +.Os +.Sh NAME +.Nm devfs +.Nd "DEVFS control" +.Sh SYNOPSIS +.Nm +.Op Fl m Ar mount-point +.Cm keyword +.Ar argument ... +.Sh DESCRIPTION +The +.Nm +utility provides an interface to manipulate properties of +.Xr devfs 5 +mounts. +.Pp +The first keyword after the program name determines the context for +the rest of the arguments. +For example, +most of the commands related to the rule subsystem must be preceded by the +.Cm rule +keyword. +The following flags are common to all keywords: +.Bl -tag -offset indent +.It Fl m Ar mount-point +Operate on +.Ar mount-point , +which is expected to be a +.Xr devfs 5 +mount. +If this option is not specified, +.Nm +operates on +.Pa /dev . +.El +.Sh RULE SUBSYSTEM +The +.Xr devfs 5 +rule subsystem provides a way for the administrator of a system to control +the attributes of DEVFS nodes. +.\" XXX devfs node? entry? what? +Each DEVFS mount-point has a +.Dq ruleset , +or a list of rules, +associated with it. +When a device driver creates a new node, +all the rules in the ruleset associated with each mount-point are applied +(see below) before the node becomes visible to the userland. +This permits the administrator to change the properties, +including the visibility, +of certain nodes. +For example, one might want to hide all disk nodes in a +.Xr jail 2 Ns 's +.Pa /dev . +.Ss Rule Manipulation +Rule manipulation commands follow the +.Cm rule +keyword. +The following flags are common to all of the rule manipulation commands: +.Bl -tag -offset indent +.It Fl s Ar ruleset +Operate on the ruleset with the number +.Ar ruleset . +If this is not specified, +the commands operate on the ruleset currently associated with the +specified mount-point. +.El +.Pp +The following commands are recognized: +.Bl -tag -offset indent +.It Cm rule add Oo Ar rulenum Oc Ar rulespec +Add the rule described by +.Ar rulespec +(defined below) +to the ruleset. +The rule has the number +.Ar rulenum +if it is explicitly specified; +otherwise, the rule number is automatically determined by the kernel. +.It Cm rule apply Ar rulenum | Ar rulespec +Apply rule number +.Ar rulenum +or the rule described by +.Ar rulespec +to the mount-point. +Rules that are "applied" have their conditions checked against all nodes +in the mount-point, and the actions taken if they match. +.It Cm rule applyset +Apply all the rules in the ruleset to the mount-point +(see above for the definition of "apply"). +.It Cm rule del Ar rulenum +Delete rule number +.Ar rulenum +from the ruleset. +.It Cm rule delset +Delete all rules from the ruleset. +.It Cm rule show Op Ar rulenum +Display the rule number +.Ar rulenum , +or all the rules in the ruleset. +The output lines (one line per rule) are expected to be valid +.Ar rulespec Ns s . +.It Cm rule showsets +Report the numbers of existing rulesets. +.It Cm ruleset Ar ruleset +Set ruleset number +.Ar ruleset +as the current ruleset for the mount-point. +.El +.Ss Rule Specification +Rules have two parts: the conditions and the actions. +The conditions determine which DEVFS nodes the rule matches, +and the actions determine what should be done when a rule matches a node. +For example, a rule can be written that sets the GID to +.Li games +for all devices with major number 53. +.Pp +The following conditions are recognized. +Conditions are ANDed together when matching a device; +if OR is desired, multiple rules can be written. +.Bl -tag -offset indent +.It Cm major Ar majdev +Matches any node with a major number equal to +.Ar majdev . +.It Cm path Ar pattern +Matches any node with a path that matches +.Ar pattern . +The latter is interpreted as a +.Xr glob 3 Ns -style +pattern. +(Note: Pattern matching is currently unimplemented; +the only wildcard recognized is an asterisk at the end of the string. +This will be corrected in the future.) +.It Cm type Ar devtype +Matches any node that is of type +.Ar devtype . +Valid types are +.Li disk , mem , tape +and +.Li tty . +.El +.Pp +The following actions are recognized. +Although there is no explicit delimiter between conditions and actions, +they may not be intermixed. +.Bl -tag -offset indent +.It Cm group Ar gid +Set the GID of the node to +.Ar gid , +which may be a group name +(looked up in +.Pa /etc/group ) +or number. +.It Cm hide +Hide the node. +Nodes may later be revived manually with +.Xr mknod 8 , +or with the +.Cm unhide +action. +.It Cm include Ar ruleset +Apply all the rules in ruleset number +.Ar ruleset +to the node. +This does not necessarily result in any changes to the node +(e.g., if none of the rules in the included ruleset match). +.It Cm mode Ar filemode +Set the file mode to +.Ar filemode , +which is interpreted in octal. +.It Cm user Ar uid +Set the UID to +.Ar uid , +which may be a user name +(looked up in +.Pa /etc/passwd ) +or number. +.It Cm unhide +Unhide the node. +.El +.Ss Notes +.Bl -bullet -offset indent +.It +Rulesets are created by the kernel at the first reference, +and destroyed when the last reference disappears. +E.g., a ruleset is created when a rule is added to it or when it is set +as the current ruleset for a mount-point; +a ruleset is destroyed when the last rule in it is deleted, +and no other references to it exist +(i.e., it is not included by any rules, and it is not the current ruleset +for any mount-point). +.It +Ruleset number 0 is the default ruleset for all new mount-points. +It is always empty, cannot be modified or deleted, and does not show up +in the output of +.Cm showsets . +.It +Rules and rulesets are unique to the entire system, +not a particular mount-point. +I.e., a +.Cm showsets +will return the same information regardless of the mount-point specified with +.Fl m . +The mount-point is only relevant when changing what its current ruleset is, +or when using one of the apply commands. +.El +.Ss Examples +When the system boots, +the only ruleset that exists is ruleset number 0; +since the latter may not be modified, we have to create another ruleset +before adding rules. +Note that since most of the following examples don't specify +.Fl m , +the operations are performed on +.Pa /dev +(this only matters for things that might change the properties of nodes). +.Pp +.Dl devfs ruleset 10 +.Pp +Specify that ruleset 10 should be the current ruleset for +.Pa /dev +(if it does not already exist, it is created). +.Pp +.Dl devfs rule add path speaker mode 666 +.Pp +Add a rule that causes all nodes that have a path that matches +"speaker" +(this is only +.Pa /dev/speaker ) +to have the file mode 666 (read and write for all). +Note that if any such nodes already exist, their mode will not be changed +unless this rule (or ruleset) is explicitly applied (see below). +The mode +.Em will +be changed if the node is created +.Em after +the rule is added +(e.g., the +.Pa atspeaker +module is loaded after the above rule is added). +.Pp +.Dl devfs rule applyset +.Pp +Apply all the rules in the current ruleset to all the existing nodes. +E.g., if the above rule was added after +.Pa /dev/speaker +was created, +this command will cause its file mode to be changed to 666, +as rule rule prescribes. +.Pp +.Dl devfs rule add path "snp*" mode 660 group snoopers +.Pp +(Quoting the argument to +.Cm path +is often necessary to disable the shell's globbing features.) +For all devices with a path that matches "snp*", +set the file more to 660, and the GID to +.Li snoopers . +This permits users in the +.Li snoopers +group to use the +.Xr snp 4 +devices. +.Pp +.Dl devfs rule -s 20 add major 53 group games +.Pp +Add a rule to ruleset number 20. +Since this ruleset is not the current ruleset for any mount-points, +this rule is never applied automatically (unless ruleset 20 becomes +a current ruleset for some mount-point at a later time). +However, it can be applied explicitly, as such: +.Pp +.Dl devfs -m /my/jail/dev rule -s 20 applyset +.Pp +This will apply all rules in ruleset number 20 to the DEVFS mount on +.Pa /my/jail/dev . +It doesn't matter that ruleset 20 is not the current ruleset for that +mount-point; the rules are applied regardless. +.Pp +.Dl devfs rule apply hide +.Pp +Since this rule has no conditions, the action +.Pq Cm hide +will be applied to all nodes. +Since hiding all nodes isn't very useful, we can undo like so: +.Pp +.Dl devfs rule apply unhide +.Sh SEE ALSO +.Xr jail 2 , +.Xr glob 3 , +.Xr devfs 5 , +.Xr chmod 8 , +.Xr chown 8 , +.Xr jail 8 , +.Xr mknod 8 +.Sh AUTHORS +.An Dima Dorfman -- cgit v1.1