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