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