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
46 The rules, by default as configured by
48 are loaded at boot via the devfs
50 The rules can be reloaded by running the command:
51 .Bd -literal -offset indent
57 argument determines the context for
58 the rest of the arguments.
60 most of the commands related to the rule subsystem must be preceded by the
63 The following flags are common to all keywords:
65 .It Fl m Ar mount-point
68 which is expected to be a
71 If this option is not specified,
79 rule subsystem provides a way for the administrator of a system to control
80 the attributes of DEVFS nodes.
81 .\" XXX devfs node? entry? what?
82 Each DEVFS mount-point has a
86 When a device driver creates a new node,
87 all the rules in the ruleset associated with each mount-point are applied
88 (see below) before the node becomes visible to the userland.
89 This permits the administrator to change the properties,
90 including the visibility,
92 For example, one might want to hide all disk nodes in a
96 Rule manipulation commands follow the
99 The following flags are common to all of the rule manipulation commands:
102 Operate on the ruleset with the number
104 If this is not specified,
105 the commands operate on the ruleset currently associated with the
106 specified mount-point.
109 The following commands are recognized:
111 .It Cm rule add Oo Ar rulenum Oc Ar rulespec
112 Add the rule described by
116 The rule has the number
118 if it is explicitly specified;
119 otherwise, the rule number is automatically determined by the kernel.
120 .It Cm rule apply Ar rulenum | rulespec
123 or the rule described by
128 have their conditions checked against all nodes
129 in the mount-point and the actions taken if they match.
131 Apply all the rules in the ruleset to the mount-point
132 (see above for the definition of
134 .It Cm rule del Ar rulenum
139 Delete all rules from the ruleset.
140 .It Cm rule show Op Ar rulenum
141 Display the rule number
143 or all the rules in the ruleset.
144 The output lines (one line per rule) are expected to be valid
147 Report the numbers of existing rulesets.
148 .It Cm ruleset Ar ruleset
151 as the current ruleset for the mount-point.
153 .Ss Rule Specification
154 Rules have two parts: the conditions and the actions.
155 The conditions determine which DEVFS nodes the rule matches
156 and the actions determine what should be done when a rule matches a node.
157 For example, a rule can be written that sets the GID to
159 for all devices of type tape.
160 If the first token of a rule specification is a single dash
162 rules are read from the standard input and the rest of the specification
165 The following conditions are recognized.
166 Conditions are ANDed together when matching a device;
167 if OR is desired, multiple rules can be written.
169 .It Cm path Ar pattern
170 Matches any node with a path that matches
172 which is interpreted as a
175 .It Cm type Ar devtype
176 Matches any node that is of type
179 .Cm disk , mem , tape
184 The following actions are recognized.
185 Although there is no explicit delimiter between conditions and actions,
186 they may not be intermixed.
189 Set the GID of the node to
191 which may be a group name
197 Nodes may later be revived manually with
202 Hiding a directory node effectively hides all of its child nodes.
203 .It Cm include Ar ruleset
204 Apply all the rules in ruleset number
207 This does not necessarily result in any changes to the node
208 (e.g., if none of the rules in the included ruleset match).
209 Include commands in the referenced
212 .It Cm mode Ar filemode
215 which is interpreted as in
220 which may be a user name
226 If the node resides in a subdirectory,
227 all parent directory nodes must be visible to be able to access the node.
229 .Sh IMPLEMENTATION NOTES
230 Rulesets are created by the kernel at the first reference
231 and destroyed when the last reference disappears.
232 E.g., a ruleset is created when a rule is added to it or when it is set
233 as the current ruleset for a mount-point, and
234 a ruleset is destroyed when the last rule in it is deleted
235 and no other references to it exist
236 (i.e., it is not included by any rules and it is not the current ruleset
237 for any mount-point).
239 Ruleset number 0 is the default ruleset for all new mount-points.
240 It is always empty, cannot be modified or deleted, and does not show up
244 Rules and rulesets are unique to the entire system,
245 not a particular mount-point.
248 will return the same information regardless of the mount-point specified with
250 The mount-point is only relevant when changing what its current ruleset is
251 or when using one of the apply commands.
253 .Bl -tag -width "Pa /usr/share/examples/etc/devfs.conf" -compact
254 .It Pa /etc/defaults/devfs.rules
258 .It Pa /etc/devfs.rules
262 Rulesets in here override those in
263 .Pa /etc/defaults/devfs.rules
264 with the same ruleset number, otherwise the two files are effectively merged.
265 .It Pa /etc/devfs.conf
269 .It Pa /usr/share/examples/etc/devfs.conf
275 When the system boots,
276 the only ruleset that exists is ruleset number 0;
277 since the latter may not be modified, we have to create another ruleset
279 Note that since most of the following examples do not specify
281 the operations are performed on
283 (this only matters for things that might change the properties of nodes).
285 Specify that ruleset 10 should be the current ruleset for
287 (if it does not already exist, it is created):
289 .Dl "devfs ruleset 10"
291 Add a rule that causes all nodes that have a path that matches
295 to have the file mode 666 (read and write for all).
296 Note that if any such nodes already exist, their mode will not be changed
297 unless this rule (or ruleset) is explicitly applied (see below).
300 be changed if the node is created
305 module is loaded after the above rule is added):
307 .Dl "devfs rule add path speaker mode 666"
309 Apply all the rules in the current ruleset to all the existing nodes.
310 E.g., if the below rule was added after
313 this command will cause its file mode to be changed to 666
314 as prescribed by the rule:
316 .Dl "devfs rule applyset"
318 For all devices with a path that matches
320 set the file mode to 660 and the GID to
322 This permits users in the
327 (quoting the argument to
329 is often necessary to disable the shell's globbing features):
331 .Dl devfs rule add path "snp*" mode 660 group snoopers
333 Add a rule to ruleset number 20.
334 Since this ruleset is not the current ruleset for any mount-points,
335 this rule is never applied automatically (unless ruleset 20 becomes
336 a current ruleset for some mount-point at a later time):
338 .Dl "devfs rule -s 20 add type disk group wheel"
340 Explicitly apply all rules in ruleset number 20 to the DEVFS mount on
342 It does not matter that ruleset 20 is not the current ruleset for that
343 mount-point; the rules are still applied:
345 .Dl "devfs -m /my/jail/dev rule -s 20 applyset"
347 Since the following rule has no conditions, the action
349 will be applied to all nodes:
351 .Dl "devfs rule apply hide"
353 Since hiding all nodes is not very useful, we can undo it.
354 The following applies
357 causing them to reappear:
359 .Dl "devfs rule apply unhide"
361 Add all the rules from the file
365 .Dl "devfs rule -s 10 add - < my_rules"
367 The below copies all the rules from ruleset 20 into ruleset 10.
368 The rule numbers are preserved,
369 but ruleset 10 may already have rules with non-conflicting numbers
370 (these will be preserved).
374 this feature can be used to copy rulesets:
376 .Dl "devfs rule -s 20 show | devfs rule -s 10 add -"
391 utility first appeared in
projects / freebsd.git / blob