1.\" 2.\" Copyright (c) 2002 Dima Dorfman. 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd July 1, 2002 29.Dt DEVFS 8 30.Os 31.Sh NAME 32.Nm devfs 33.Nd "DEVFS control" 34.Sh SYNOPSIS 35.Nm 36.Op Fl m Ar mount-point 37.Ar keyword 38.Ar argument ... 39.Sh DESCRIPTION 40The 41.Nm 42utility provides an interface to manipulate properties of 43.Xr devfs 5 44mounts. 45.Pp 46The first keyword after the program name determines the context for 47the rest of the arguments. 48For example, 49most of the commands related to the rule subsystem must be preceded by the 50.Cm rule 51keyword. 52The following flags are common to all keywords: 53.Bl -tag -offset indent 54.It Fl m Ar mount-point 55Operate on 56.Ar mount-point , 57which is expected to be a 58.Xr devfs 5 59mount. 60If this option is not specified, 61.Nm 62operates on 63.Pa /dev . 64.El 65.Ss Rule Subsystem 66The 67.Xr devfs 5 68rule subsystem provides a way for the administrator of a system to control 69the attributes of DEVFS nodes. 70.\" XXX devfs node? entry? what? 71Each DEVFS mount-point has a 72.Dq ruleset , 73or a list of rules, 74associated with it. 75When a device driver creates a new node, 76all the rules in the ruleset associated with each mount-point are applied 77(see below) before the node becomes visible to the userland. 78This permits the administrator to change the properties, 79including the visibility, 80of certain nodes. 81For example, one might want to hide all disk nodes in a 82.Xr jail 2 Ns 's 83.Pa /dev . 84.Ss Rule Manipulation 85Rule manipulation commands follow the 86.Cm rule 87keyword. 88The following flags are common to all of the rule manipulation commands: 89.Bl -tag -offset indent 90.It Fl s Ar ruleset 91Operate on the ruleset with the number 92.Ar ruleset . 93If this is not specified, 94the commands operate on the ruleset currently associated with the 95specified mount-point. 96.El 97.Pp 98The following commands are recognized: 99.Bl -tag -offset indent 100.It Cm rule add Oo Ar rulenum Oc Ar rulespec 101Add the rule described by 102.Ar rulespec 103(defined below) 104to the ruleset. 105The rule has the number 106.Ar rulenum 107if it is explicitly specified; 108otherwise, the rule number is automatically determined by the kernel. 109.It Cm rule apply Ar rulenum | rulespec 110Apply rule number 111.Ar rulenum 112or the rule described by 113.Ar rulespec 114to the mount-point. 115Rules that are 116.Dq applied 117have their conditions checked against all nodes 118in the mount-point, and the actions taken if they match. 119.It Cm rule applyset 120Apply all the rules in the ruleset to the mount-point 121(see above for the definition of 122.Dq apply ) . 123.It Cm rule del Ar rulenum 124Delete rule number 125.Ar rulenum 126from the ruleset. 127.It Cm rule delset 128Delete all rules from the ruleset. 129.It Cm rule show Op Ar rulenum 130Display the rule number 131.Ar rulenum , 132or all the rules in the ruleset. 133The output lines (one line per rule) are expected to be valid 134.Ar rulespec Ns s . 135.It Cm rule showsets 136Report the numbers of existing rulesets. 137.It Cm ruleset Ar ruleset 138Set ruleset number 139.Ar ruleset 140as the current ruleset for the mount-point. 141.El 142.Ss Rule Specification 143Rules have two parts: the conditions and the actions. 144The conditions determine which DEVFS nodes the rule matches, 145and the actions determine what should be done when a rule matches a node. 146For example, a rule can be written that sets the GID to 147.Dq Li games 148for all devices with major number 53. 149If the first token of a rule specification is a single dash 150.Pq Sq Fl , 151rules are read from the standard input and the rest of the specification 152is ignored. 153.Pp 154The following conditions are recognized. 155Conditions are ANDed together when matching a device; 156if OR is desired, multiple rules can be written. 157.Bl -tag -offset indent 158.It Cm major Ar majdev 159Matches any node with a major number equal to 160.Ar majdev . 161.It Cm path Ar pattern 162Matches any node with a path that matches 163.Ar pattern . 164The latter is interpreted as a 165.Xr glob 3 Ns -style 166pattern. 167.It Cm type Ar devtype 168Matches any node that is of type 169.Ar devtype . 170Valid types are 171.Cm disk , mem , tape 172and 173.Cm tty . 174.El 175.Pp 176The following actions are recognized. 177Although there is no explicit delimiter between conditions and actions, 178they may not be intermixed. 179.Bl -tag -offset indent 180.It Cm group Ar gid 181Set the GID of the node to 182.Ar gid , 183which may be a group name 184(looked up in 185.Pa /etc/group ) 186or number. 187.It Cm hide 188Hide the node. 189Nodes may later be revived manually with 190.Xr mknod 8 , 191or with the 192.Cm unhide 193action. 194.It Cm include Ar ruleset 195Apply all the rules in ruleset number 196.Ar ruleset 197to the node. 198This does not necessarily result in any changes to the node 199(e.g., if none of the rules in the included ruleset match). 200.It Cm mode Ar filemode 201Set the file mode to 202.Ar filemode , 203which is interpreted in octal. 204.It Cm user Ar uid 205Set the UID to 206.Ar uid , 207which may be a user name 208(looked up in 209.Pa /etc/passwd ) 210or number. 211.It Cm unhide 212Unhide the node. 213.El 214.Sh IMPLEMENTATION NOTES 215Rulesets are created by the kernel at the first reference, 216and destroyed when the last reference disappears. 217E.g., a ruleset is created when a rule is added to it or when it is set 218as the current ruleset for a mount-point; 219a ruleset is destroyed when the last rule in it is deleted, 220and no other references to it exist 221(i.e., it is not included by any rules, and it is not the current ruleset 222for any mount-point). 223.Pp 224Ruleset number 0 is the default ruleset for all new mount-points. 225It is always empty, cannot be modified or deleted, and does not show up 226in the output of 227.Cm showsets . 228.Pp 229Rules and rulesets are unique to the entire system, 230not a particular mount-point. 231I.e., a 232.Cm showsets 233will return the same information regardless of the mount-point specified with 234.Fl m . 235The mount-point is only relevant when changing what its current ruleset is, 236or when using one of the apply commands. 237.Sh EXAMPLES 238When the system boots, 239the only ruleset that exists is ruleset number 0; 240since the latter may not be modified, we have to create another ruleset 241before adding rules. 242Note that since most of the following examples do not specify 243.Fl m , 244the operations are performed on 245.Pa /dev 246(this only matters for things that might change the properties of nodes). 247.Pp 248.Dl "devfs ruleset 10" 249.Pp 250Specify that ruleset 10 should be the current ruleset for 251.Pa /dev 252(if it does not already exist, it is created). 253.Pp 254.Dl "devfs rule add path speaker mode 666" 255.Pp 256Add a rule that causes all nodes that have a path that matches 257.Dq Li speaker 258(this is only 259.Pa /dev/speaker ) 260to have the file mode 666 (read and write for all). 261Note that if any such nodes already exist, their mode will not be changed 262unless this rule (or ruleset) is explicitly applied (see below). 263The mode 264.Em will 265be changed if the node is created 266.Em after 267the rule is added 268(e.g., the 269.Pa atspeaker 270module is loaded after the above rule is added). 271.Pp 272.Dl "devfs rule applyset" 273.Pp 274Apply all the rules in the current ruleset to all the existing nodes. 275E.g., if the above rule was added after 276.Pa /dev/speaker 277was created, 278this command will cause its file mode to be changed to 666, 279as rule rule prescribes. 280.Pp 281.Dl devfs rule add path "snp*" mode 660 group snoopers 282.Pp 283(Quoting the argument to 284.Cm path 285is often necessary to disable the shell's globbing features.) 286For all devices with a path that matches 287.Dq Li snp* , 288set the file more to 660, and the GID to 289.Dq Li snoopers . 290This permits users in the 291.Dq Li snoopers 292group to use the 293.Xr snp 4 294devices. 295.Pp 296.Dl "devfs rule -s 20 add major 53 group games" 297.Pp 298Add a rule to ruleset number 20. 299Since this ruleset is not the current ruleset for any mount-points, 300this rule is never applied automatically (unless ruleset 20 becomes 301a current ruleset for some mount-point at a later time). 302However, it can be applied explicitly, as such: 303.Pp 304.Dl "devfs -m /my/jail/dev rule -s 20 applyset" 305.Pp 306This will apply all rules in ruleset number 20 to the DEVFS mount on 307.Pa /my/jail/dev . 308It does not matter that ruleset 20 is not the current ruleset for that 309mount-point; the rules are applied regardless. 310.Pp 311.Dl "devfs rule apply hide" 312.Pp 313Since this rule has no conditions, the action 314.Pq Cm hide 315will be applied to all nodes. 316Since hiding all nodes is not very useful, we can undo like so: 317.Pp 318.Dl "devfs rule apply unhide" 319.Pp 320which applies 321.Cm unhide 322to all the nodes, 323causing them to reappear. 324.Pp 325.Dl "cat my_rules | devfs rule -s 10 add -" 326.Pp 327Add all the rules from the file 328.Pa my_rules 329to ruleset 10. 330.Pp 331.Dl "devfs rule -s 20 show | devfs rule -s 10 add -" 332.Pp 333Since 334.Cm show 335outputs valid rules, 336this feature can be used to copy rulesets. 337The above copies all the rules from ruleset 20 into ruleset 10. 338The rule numbers are preserved, 339but ruleset 10 may already have rules with non-conflicting numbers 340(these will be preserved). 341.Sh SEE ALSO 342.Xr jail 2 , 343.Xr glob 3 , 344.Xr devfs 5 , 345.Xr chmod 8 , 346.Xr chown 8 , 347.Xr jail 8 , 348.Xr mknod 8 349.Sh AUTHORS 350.An Dima Dorfman 351