aboutsummaryrefslogtreecommitdiff
path: root/sbin/devfs/devfs.8
blob: 7a744d437e07b7c34d5b0032417c9ee73750ffc1 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
.\"
.\" Copyright (c) 2002 Dima Dorfman.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd February 21, 2010
.Dt DEVFS 8
.Os
.Sh NAME
.Nm devfs
.Nd "DEVFS control"
.Sh SYNOPSIS
.Nm
.Op Fl m Ar mount-point
.Ar keyword
.Ar argument ...
.Sh DESCRIPTION
The
.Nm
utility provides an interface to manipulate properties of
.Xr devfs 5
mounts.
.Pp
The
.Ar keyword
argument determines the context for
the rest of the arguments.
For example,
most of the commands related to the rule subsystem must be preceded by the
.Cm rule
keyword.
The following flags are common to all keywords:
.Bl -tag -offset indent
.It Fl m Ar mount-point
Operate on
.Ar mount-point ,
which is expected to be a
.Xr devfs 5
mount.
If this option is not specified,
.Nm
operates on
.Pa /dev .
.El
.Ss Rule Subsystem
The
.Xr devfs 5
rule subsystem provides a way for the administrator of a system to control
the attributes of DEVFS nodes.
.\" XXX devfs node?  entry?  what?
Each DEVFS mount-point has a
.Dq ruleset ,
or a list of rules,
associated with it.
When a device driver creates a new node,
all the rules in the ruleset associated with each mount-point are applied
(see below) before the node becomes visible to the userland.
This permits the administrator to change the properties,
including the visibility,
of certain nodes.
For example, one might want to hide all disk nodes in a
.Xr jail 2 Ns 's
.Pa /dev .
.Ss Rule Manipulation
Rule manipulation commands follow the
.Cm rule
keyword.
The following flags are common to all of the rule manipulation commands:
.Bl -tag -offset indent
.It Fl s Ar ruleset
Operate on the ruleset with the number
.Ar ruleset .
If this is not specified,
the commands operate on the ruleset currently associated with the
specified mount-point.
.El
.Pp
The following commands are recognized:
.Bl -tag -offset indent
.It Cm rule add Oo Ar rulenum Oc Ar rulespec
Add the rule described by
.Ar rulespec
(defined below)
to the ruleset.
The rule has the number
.Ar rulenum
if it is explicitly specified;
otherwise, the rule number is automatically determined by the kernel.
.It Cm rule apply Ar rulenum | rulespec
Apply rule number
.Ar rulenum
or the rule described by
.Ar rulespec
to the mount-point.
Rules that are
.Dq applied
have their conditions checked against all nodes
in the mount-point and the actions taken if they match.
.It Cm rule applyset
Apply all the rules in the ruleset to the mount-point
(see above for the definition of
.Dq apply ) .
.It Cm rule del Ar rulenum
Delete rule number
.Ar rulenum
from the ruleset.
.It Cm rule delset
Delete all rules from the ruleset.
.It Cm rule show Op Ar rulenum
Display the rule number
.Ar rulenum ,
or all the rules in the ruleset.
The output lines (one line per rule) are expected to be valid
.Ar rulespec Ns s .
.It Cm rule showsets
Report the numbers of existing rulesets.
.It Cm ruleset Ar ruleset
Set ruleset number
.Ar ruleset
as the current ruleset for the mount-point.
.El
.Ss Rule Specification
Rules have two parts: the conditions and the actions.
The conditions determine which DEVFS nodes the rule matches
and the actions determine what should be done when a rule matches a node.
For example, a rule can be written that sets the GID to
.Dq Li operator
for all devices of type tape.
If the first token of a rule specification is a single dash
.Pq Sq Fl ,
rules are read from the standard input and the rest of the specification
is ignored.
.Pp
The following conditions are recognized.
Conditions are ANDed together when matching a device;
if OR is desired, multiple rules can be written.
.Bl -tag -offset indent
.It Cm path Ar pattern
Matches any node with a path that matches
.Ar pattern ,
which is interpreted as a
.Xr glob 3 Ns -style
pattern.
.It Cm type Ar devtype
Matches any node that is of type
.Ar devtype .
Valid types are
.Cm disk , mem , tape
and
.Cm tty .
.El
.Pp
The following actions are recognized.
Although there is no explicit delimiter between conditions and actions,
they may not be intermixed.
.Bl -tag -offset indent
.It Cm group Ar gid
Set the GID of the node to
.Ar gid ,
which may be a group name
(looked up in
.Pa /etc/group )
or number.
.It Cm hide
Hide the node.
Nodes may later be revived manually with
.Xr mknod 8
or with the
.Cm unhide
action.
.It Cm include Ar ruleset
Apply all the rules in ruleset number
.Ar ruleset
to the node.
This does not necessarily result in any changes to the node
(e.g., if none of the rules in the included ruleset match).
Include commands in the referenced
.Ar ruleset
are not resolved.
.It Cm mode Ar filemode
Set the file mode to
.Ar filemode ,
which is interpreted as in
.Xr chmod 1 .
.It Cm user Ar uid
Set the UID to
.Ar uid ,
which may be a user name
(looked up in
.Pa /etc/passwd )
or number.
.It Cm unhide
Unhide the node.
.El
.Sh IMPLEMENTATION NOTES
Rulesets are created by the kernel at the first reference
and destroyed when the last reference disappears.
E.g., a ruleset is created when a rule is added to it or when it is set
as the current ruleset for a mount-point, and
a ruleset is destroyed when the last rule in it is deleted
and no other references to it exist
(i.e., it is not included by any rules and it is not the current ruleset
for any mount-point).
.Pp
Ruleset number 0 is the default ruleset for all new mount-points.
It is always empty, cannot be modified or deleted, and does not show up
in the output of
.Cm showsets .
.Pp
Rules and rulesets are unique to the entire system,
not a particular mount-point.
I.e., a
.Cm showsets
will return the same information regardless of the mount-point specified with
.Fl m .
The mount-point is only relevant when changing what its current ruleset is
or when using one of the apply commands.
.Sh FILES
.Bl -tag -compact
.It Pa /etc/defaults/devfs.rules
Default
.Nm
configuration file.
.It Pa /etc/devfs.rules
Local
.Nm
configuration file.  Rulesets in here override those in
.Pa /etc/defaults/devfs.rules 
with the same ruleset number, otherwise the two files are effectively merged. 
.It Pa /etc/devfs.conf
Boot-time
.Nm
configuration file.
.It Pa /usr/share/examples/etc/devfs.conf
Example boot-time
.Nm
configuration file.
.El
.Sh EXAMPLES
When the system boots,
the only ruleset that exists is ruleset number 0;
since the latter may not be modified, we have to create another ruleset
before adding rules.
Note that since most of the following examples do not specify
.Fl m ,
the operations are performed on
.Pa /dev
(this only matters for things that might change the properties of nodes).
.Pp
.Dl "devfs ruleset 10"
.Pp
Specify that ruleset 10 should be the current ruleset for
.Pa /dev
(if it does not already exist, it is created).
.Pp
.Dl "devfs rule add path speaker mode 666"
.Pp
Add a rule that causes all nodes that have a path that matches
.Dq Li speaker
(this is only
.Pa /dev/speaker )
to have the file mode 666 (read and write for all).
Note that if any such nodes already exist, their mode will not be changed
unless this rule (or ruleset) is explicitly applied (see below).
The mode
.Em will
be changed if the node is created
.Em after
the rule is added
(e.g., the
.Pa atspeaker
module is loaded after the above rule is added).
.Pp
.Dl "devfs rule applyset"
.Pp
Apply all the rules in the current ruleset to all the existing nodes.
E.g., if the above rule was added after
.Pa /dev/speaker
was created,
this command will cause its file mode to be changed to 666
as prescribed by the rule.
.Pp
.Dl devfs rule add path "snp*" mode 660 group snoopers
.Pp
(Quoting the argument to
.Cm path
is often necessary to disable the shell's globbing features.)
For all devices with a path that matches
.Dq Li snp* ,
set the file mode to 660 and the GID to
.Dq Li snoopers .
This permits users in the
.Dq Li snoopers
group to use the
.Xr snp 4
devices.
.Pp
.Dl "devfs rule -s 20 add type disk group wheel"
.Pp
Add a rule to ruleset number 20.
Since this ruleset is not the current ruleset for any mount-points,
this rule is never applied automatically (unless ruleset 20 becomes
a current ruleset for some mount-point at a later time).
However, it can be applied explicitly, as such:
.Pp
.Dl "devfs -m /my/jail/dev rule -s 20 applyset"
.Pp
This will apply all rules in ruleset number 20 to the DEVFS mount on
.Pa /my/jail/dev .
It does not matter that ruleset 20 is not the current ruleset for that
mount-point; the rules are still applied.
.Pp
.Dl "devfs rule apply hide"
.Pp
Since this rule has no conditions, the action
.Pq Cm hide
will be applied to all nodes.
Since hiding all nodes is not very useful, we can undo it:
.Pp
.Dl "devfs rule apply unhide"
.Pp
which applies
.Cm unhide
to all the nodes,
causing them to reappear.
.Pp
.Dl "devfs rule -s 10 add - < my_rules"
.Pp
Add all the rules from the file
.Pa my_rules
to ruleset 10.
.Pp
.Dl "devfs rule -s 20 show | devfs rule -s 10 add -"
.Pp
Since
.Cm show
outputs valid rules,
this feature can be used to copy rulesets.
The above copies all the rules from ruleset 20 into ruleset 10.
The rule numbers are preserved,
but ruleset 10 may already have rules with non-conflicting numbers
(these will be preserved).
.Sh SEE ALSO
.Xr chmod 1 ,
.Xr jail 2 ,
.Xr glob 3 ,
.Xr devfs 5 ,
.Xr devfs.conf 5 ,
.Xr devfs.rules 5 ,
.Xr chown 8 ,
.Xr jail 8 ,
.Xr mknod 8
.Sh AUTHORS
.An Dima Dorfman