2 .\" Copyright (c) 2002 Dima Dorfman.
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
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
36 .Op Fl m Ar mount-point
42 utility provides an interface to manipulate properties of
48 argument determines the context for
49 the rest of the arguments.
51 most of the commands related to the rule subsystem must be preceded by the
54 The following flags are common to all keywords:
55 .Bl -tag -offset indent
56 .It Fl m Ar mount-point
59 which is expected to be a
62 If this option is not specified,
70 rule subsystem provides a way for the administrator of a system to control
71 the attributes of DEVFS nodes.
72 .\" XXX devfs node? entry? what?
73 Each DEVFS mount-point has a
77 When a device driver creates a new node,
78 all the rules in the ruleset associated with each mount-point are applied
79 (see below) before the node becomes visible to the userland.
80 This permits the administrator to change the properties,
81 including the visibility,
83 For example, one might want to hide all disk nodes in a
87 Rule manipulation commands follow the
90 The following flags are common to all of the rule manipulation commands:
91 .Bl -tag -offset indent
93 Operate on the ruleset with the number
95 If this is not specified,
96 the commands operate on the ruleset currently associated with the
97 specified mount-point.
100 The following commands are recognized:
101 .Bl -tag -offset indent
102 .It Cm rule add Oo Ar rulenum Oc Ar rulespec
103 Add the rule described by
107 The rule has the number
109 if it is explicitly specified;
110 otherwise, the rule number is automatically determined by the kernel.
111 .It Cm rule apply Ar rulenum | rulespec
114 or the rule described by
119 have their conditions checked against all nodes
120 in the mount-point and the actions taken if they match.
122 Apply all the rules in the ruleset to the mount-point
123 (see above for the definition of
125 .It Cm rule del Ar rulenum
130 Delete all rules from the ruleset.
131 .It Cm rule show Op Ar rulenum
132 Display the rule number
134 or all the rules in the ruleset.
135 The output lines (one line per rule) are expected to be valid
138 Report the numbers of existing rulesets.
139 .It Cm ruleset Ar ruleset
142 as the current ruleset for the mount-point.
144 .Ss Rule Specification
145 Rules have two parts: the conditions and the actions.
146 The conditions determine which DEVFS nodes the rule matches
147 and the actions determine what should be done when a rule matches a node.
148 For example, a rule can be written that sets the GID to
150 for all devices of type tape.
151 If the first token of a rule specification is a single dash
153 rules are read from the standard input and the rest of the specification
156 The following conditions are recognized.
157 Conditions are ANDed together when matching a device;
158 if OR is desired, multiple rules can be written.
159 .Bl -tag -offset indent
160 .It Cm path Ar pattern
161 Matches any node with a path that matches
163 which is interpreted as a
166 .It Cm type Ar devtype
167 Matches any node that is of type
170 .Cm disk , mem , tape
175 The following actions are recognized.
176 Although there is no explicit delimiter between conditions and actions,
177 they may not be intermixed.
178 .Bl -tag -offset indent
180 Set the GID of the node to
182 which may be a group name
188 Nodes may later be revived manually with
193 .It Cm include Ar ruleset
194 Apply all the rules in ruleset number
197 This does not necessarily result in any changes to the node
198 (e.g., if none of the rules in the included ruleset match).
199 .It Cm mode Ar filemode
202 which is interpreted as in
207 which may be a user name
214 .Sh IMPLEMENTATION NOTES
215 Rulesets are created by the kernel at the first reference
216 and destroyed when the last reference disappears.
217 E.g., a ruleset is created when a rule is added to it or when it is set
218 as the current ruleset for a mount-point, and
219 a ruleset is destroyed when the last rule in it is deleted
220 and no other references to it exist
221 (i.e., it is not included by any rules and it is not the current ruleset
222 for any mount-point).
224 Ruleset number 0 is the default ruleset for all new mount-points.
225 It is always empty, cannot be modified or deleted, and does not show up
229 Rules and rulesets are unique to the entire system,
230 not a particular mount-point.
233 will return the same information regardless of the mount-point specified with
235 The mount-point is only relevant when changing what its current ruleset is
236 or when using one of the apply commands.
239 .It Pa /etc/defaults/devfs.rules
243 .It Pa /etc/devfs.rules
247 .It Pa /etc/devfs.conf
251 .It Pa /usr/share/examples/etc/devfs.conf
257 When the system boots,
258 the only ruleset that exists is ruleset number 0;
259 since the latter may not be modified, we have to create another ruleset
261 Note that since most of the following examples do not specify
263 the operations are performed on
265 (this only matters for things that might change the properties of nodes).
267 .Dl "devfs ruleset 10"
269 Specify that ruleset 10 should be the current ruleset for
271 (if it does not already exist, it is created).
273 .Dl "devfs rule add path speaker mode 666"
275 Add a rule that causes all nodes that have a path that matches
279 to have the file mode 666 (read and write for all).
280 Note that if any such nodes already exist, their mode will not be changed
281 unless this rule (or ruleset) is explicitly applied (see below).
284 be changed if the node is created
289 module is loaded after the above rule is added).
291 .Dl "devfs rule applyset"
293 Apply all the rules in the current ruleset to all the existing nodes.
294 E.g., if the above rule was added after
297 this command will cause its file mode to be changed to 666
298 as prescribed by the rule.
300 .Dl devfs rule add path "snp*" mode 660 group snoopers
302 (Quoting the argument to
304 is often necessary to disable the shell's globbing features.)
305 For all devices with a path that matches
307 set the file mode to 660 and the GID to
309 This permits users in the
315 .Dl "devfs rule -s 20 add type disk group wheel"
317 Add a rule to ruleset number 20.
318 Since this ruleset is not the current ruleset for any mount-points,
319 this rule is never applied automatically (unless ruleset 20 becomes
320 a current ruleset for some mount-point at a later time).
321 However, it can be applied explicitly, as such:
323 .Dl "devfs -m /my/jail/dev rule -s 20 applyset"
325 This will apply all rules in ruleset number 20 to the DEVFS mount on
327 It does not matter that ruleset 20 is not the current ruleset for that
328 mount-point; the rules are still applied.
330 .Dl "devfs rule apply hide"
332 Since this rule has no conditions, the action
334 will be applied to all nodes.
335 Since hiding all nodes is not very useful, we can undo it:
337 .Dl "devfs rule apply unhide"
342 causing them to reappear.
344 .Dl "devfs rule -s 10 add - < my_rules"
346 Add all the rules from the file
350 .Dl "devfs rule -s 20 show | devfs rule -s 10 add -"
355 this feature can be used to copy rulesets.
356 The above copies all the rules from ruleset 20 into ruleset 10.
357 The rule numbers are preserved,
358 but ruleset 10 may already have rules with non-conflicting numbers
359 (these will be preserved).
projects / FreeBSD / releng / 7.2.git / blob