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