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