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 October 5, 2016 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 47.Ar keyword 48argument determines the context for 49the rest of the arguments. 50For example, 51most of the commands related to the rule subsystem must be preceded by the 52.Cm rule 53keyword. 54The following flags are common to all keywords: 55.Bl -tag -width 15n 56.It Fl m Ar mount-point 57Operate on 58.Ar mount-point , 59which is expected to be a 60.Xr devfs 5 61mount. 62If this option is not specified, 63.Nm 64operates on 65.Pa /dev . 66.El 67.Ss Rule Subsystem 68The 69.Xr devfs 5 70rule subsystem provides a way for the administrator of a system to control 71the attributes of DEVFS nodes. 72.\" XXX devfs node? entry? what? 73Each DEVFS mount-point has a 74.Dq ruleset , 75or a list of rules, 76associated with it. 77When a device driver creates a new node, 78all the rules in the ruleset associated with each mount-point are applied 79(see below) before the node becomes visible to the userland. 80This permits the administrator to change the properties, 81including the visibility, 82of certain nodes. 83For example, one might want to hide all disk nodes in a 84.Xr jail 2 Ns 's 85.Pa /dev . 86.Ss Rule Manipulation 87Rule manipulation commands follow the 88.Cm rule 89keyword. 90The following flags are common to all of the rule manipulation commands: 91.Bl -tag -width 15n 92.It Fl s Ar ruleset 93Operate on the ruleset with the number 94.Ar ruleset . 95If this is not specified, 96the commands operate on the ruleset currently associated with the 97specified mount-point. 98.El 99.Pp 100The following commands are recognized: 101.Bl -tag -width 15n 102.It Cm rule add Oo Ar rulenum Oc Ar rulespec 103Add the rule described by 104.Ar rulespec 105(defined below) 106to the ruleset. 107The rule has the number 108.Ar rulenum 109if it is explicitly specified; 110otherwise, the rule number is automatically determined by the kernel. 111.It Cm rule apply Ar rulenum | rulespec 112Apply rule number 113.Ar rulenum 114or the rule described by 115.Ar rulespec 116to the mount-point. 117Rules that are 118.Dq applied 119have their conditions checked against all nodes 120in the mount-point and the actions taken if they match. 121.It Cm rule applyset 122Apply all the rules in the ruleset to the mount-point 123(see above for the definition of 124.Dq apply ) . 125.It Cm rule del Ar rulenum 126Delete rule number 127.Ar rulenum 128from the ruleset. 129.It Cm rule delset 130Delete all rules from the ruleset. 131.It Cm rule show Op Ar rulenum 132Display the rule number 133.Ar rulenum , 134or all the rules in the ruleset. 135The output lines (one line per rule) are expected to be valid 136.Ar rulespec Ns s . 137.It Cm rule showsets 138Report the numbers of existing rulesets. 139.It Cm ruleset Ar ruleset 140Set ruleset number 141.Ar ruleset 142as the current ruleset for the mount-point. 143.El 144.Ss Rule Specification 145Rules have two parts: the conditions and the actions. 146The conditions determine which DEVFS nodes the rule matches 147and the actions determine what should be done when a rule matches a node. 148For example, a rule can be written that sets the GID to 149.Dq Li operator 150for all devices of type tape. 151If the first token of a rule specification is a single dash 152.Pq Sq Fl , 153rules are read from the standard input and the rest of the specification 154is ignored. 155.Pp 156The following conditions are recognized. 157Conditions are ANDed together when matching a device; 158if OR is desired, multiple rules can be written. 159.Bl -tag -width 15n 160.It Cm path Ar pattern 161Matches any node with a path that matches 162.Ar pattern , 163which is interpreted as a 164.Xr glob 3 Ns -style 165pattern. 166.It Cm type Ar devtype 167Matches any node that is of type 168.Ar devtype . 169Valid types are 170.Cm disk , mem , tape 171and 172.Cm tty . 173.El 174.Pp 175The following actions are recognized. 176Although there is no explicit delimiter between conditions and actions, 177they may not be intermixed. 178.Bl -tag -width 15n 179.It Cm group Ar gid 180Set the GID of the node to 181.Ar gid , 182which may be a group name 183(looked up in 184.Pa /etc/group ) 185or number. 186.It Cm hide 187Hide the node. 188Nodes may later be revived manually with 189.Xr mknod 8 190or with the 191.Cm unhide 192action. 193Hiding a directory node effectively hides all of its child nodes. 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). 200Include commands in the referenced 201.Ar ruleset 202are not resolved. 203.It Cm mode Ar filemode 204Set the file mode to 205.Ar filemode , 206which is interpreted as in 207.Xr chmod 1 . 208.It Cm user Ar uid 209Set the UID to 210.Ar uid , 211which may be a user name 212(looked up in 213.Pa /etc/passwd ) 214or number. 215.It Cm unhide 216Unhide the node. 217If the node resides in a subdirectory, 218all parent directory nodes must be visible to be able to access the node. 219.El 220.Sh IMPLEMENTATION NOTES 221Rulesets are created by the kernel at the first reference 222and destroyed when the last reference disappears. 223E.g., a ruleset is created when a rule is added to it or when it is set 224as the current ruleset for a mount-point, and 225a ruleset is destroyed when the last rule in it is deleted 226and no other references to it exist 227(i.e., it is not included by any rules and it is not the current ruleset 228for any mount-point). 229.Pp 230Ruleset number 0 is the default ruleset for all new mount-points. 231It is always empty, cannot be modified or deleted, and does not show up 232in the output of 233.Cm showsets . 234.Pp 235Rules and rulesets are unique to the entire system, 236not a particular mount-point. 237I.e., a 238.Cm showsets 239will return the same information regardless of the mount-point specified with 240.Fl m . 241The mount-point is only relevant when changing what its current ruleset is 242or when using one of the apply commands. 243.Sh FILES 244.Bl -tag -width "Pa /usr/share/examples/etc/devfs.conf" -compact 245.It Pa /etc/defaults/devfs.rules 246Default 247.Nm 248configuration file. 249.It Pa /etc/devfs.rules 250Local 251.Nm 252configuration file. 253Rulesets in here override those in 254.Pa /etc/defaults/devfs.rules 255with the same ruleset number, otherwise the two files are effectively merged. 256.It Pa /etc/devfs.conf 257Boot-time 258.Nm 259configuration file. 260.It Pa /usr/share/examples/etc/devfs.conf 261Example boot-time 262.Nm 263configuration file. 264.El 265.Sh EXAMPLES 266When the system boots, 267the only ruleset that exists is ruleset number 0; 268since the latter may not be modified, we have to create another ruleset 269before adding rules. 270Note that since most of the following examples do not specify 271.Fl m , 272the operations are performed on 273.Pa /dev 274(this only matters for things that might change the properties of nodes). 275.Pp 276Specify that ruleset 10 should be the current ruleset for 277.Pa /dev 278(if it does not already exist, it is created): 279.Pp 280.Dl "devfs ruleset 10" 281.Pp 282Add a rule that causes all nodes that have a path that matches 283.Dq Li speaker 284(this is only 285.Pa /dev/speaker ) 286to have the file mode 666 (read and write for all). 287Note that if any such nodes already exist, their mode will not be changed 288unless this rule (or ruleset) is explicitly applied (see below). 289The mode 290.Em will 291be changed if the node is created 292.Em after 293the rule is added 294(e.g., the 295.Pa atspeaker 296module is loaded after the above rule is added): 297.Pp 298.Dl "devfs rule add path speaker mode 666" 299.Pp 300Apply all the rules in the current ruleset to all the existing nodes. 301E.g., if the below rule was added after 302.Pa /dev/speaker 303was created, 304this command will cause its file mode to be changed to 666 305as prescribed by the rule: 306.Pp 307.Dl "devfs rule applyset" 308.Pp 309For all devices with a path that matches 310.Dq Li snp* , 311set the file mode to 660 and the GID to 312.Dq Li snoopers . 313This permits users in the 314.Dq Li snoopers 315group to use the 316.Xr snp 4 317devices 318(quoting the argument to 319.Cm path 320is often necessary to disable the shell's globbing features): 321.Pp 322.Dl devfs rule add path "snp*" mode 660 group snoopers 323.Pp 324Add a rule to ruleset number 20. 325Since this ruleset is not the current ruleset for any mount-points, 326this rule is never applied automatically (unless ruleset 20 becomes 327a current ruleset for some mount-point at a later time): 328.Pp 329.Dl "devfs rule -s 20 add type disk group wheel" 330.Pp 331Explicitly apply all rules in ruleset number 20 to the DEVFS mount on 332.Pa /my/jail/dev . 333It does not matter that ruleset 20 is not the current ruleset for that 334mount-point; the rules are still applied: 335.Pp 336.Dl "devfs -m /my/jail/dev rule -s 20 applyset" 337.Pp 338Since the following rule has no conditions, the action 339.Pq Cm hide 340will be applied to all nodes: 341.Pp 342.Dl "devfs rule apply hide" 343.Pp 344Since hiding all nodes is not very useful, we can undo it. 345The following applies 346.Cm unhide 347to all the nodes, 348causing them to reappear: 349.Pp 350.Dl "devfs rule apply unhide" 351.Pp 352Add all the rules from the file 353.Pa my_rules 354to ruleset 10: 355.Pp 356.Dl "devfs rule -s 10 add - < my_rules" 357.Pp 358The below copies all the rules from ruleset 20 into ruleset 10. 359The rule numbers are preserved, 360but ruleset 10 may already have rules with non-conflicting numbers 361(these will be preserved). 362Since 363.Cm show 364outputs valid rules, 365this feature can be used to copy rulesets: 366.Pp 367.Dl "devfs rule -s 20 show | devfs rule -s 10 add -" 368.Sh SEE ALSO 369.Xr chmod 1 , 370.Xr jail 2 , 371.Xr glob 3 , 372.Xr devfs 5 , 373.Xr devfs.conf 5 , 374.Xr devfs.rules 5 , 375.Xr chown 8 , 376.Xr jail 8 , 377.Xr mknod 8 378.Sh HISTORY 379The 380.Nm 381utility first appeared in 382.Fx 5.0 . 383.Sh AUTHORS 384.An Dima Dorfman 385