devfsctl.8: Add a description of the rule syntax.

Submitted-by: alexh

diff --git a/usr.sbin/devfsctl/devfsctl.8 b/usr.sbin/devfsctl/devfsctl.8
index b18e6eb..6905bf0 100644 (file)
--- a/usr.sbin/devfsctl/devfsctl.8
+++ b/usr.sbin/devfsctl/devfsctl.8
@@ -29,7 +29,7 @@
 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd August 12, 2009
+.Dd August 13, 2009
 .Os
 .Dt DEVFSCTL 8
 .Sh NAME
@@ -109,11 +109,146 @@ This does not clear the current ruleset and it is hence recommended
 to use this command together with
 .Fl c .
 .El
+.Sh RULE SYNTAX
+Rules are specified one rule per line, with whitespace separated values.
+Empty lines and lines beginning with a
+.Dq #
+are ignored.
+Once applied, the rules are in effect for existing device nodes as well
+as future ones.
+Rules are applied in the order specified, thus later rules will override
+prior ones.
+.Pp
+Names used in
+.Xr devfs 5
+rules can be either device names (? and * wildcards are allowed), device
+types or existing groups.
+Groups are referenced in rules by prefixing them with
+.Sq @ .
+A device type is one of the following list of special names:
+.Pp
+.Bl -tag -offset indent -width ".Li D_DISK" -compact
+.It Li D_DISK
+disk devices/slices/partitions
+.It Li D_TAPE
+tape devices
+.It Li D_MEM
+(kernel) memory devices
+.It Li D_TTY
+tty devices
+.El
+.Pp
+Rule lines are of the following format:
+.Bd -literal -offset indent
+.Ic action Cm argument ...
+.Ed
+.Pp
+Valid actions are
+.Ic group ,
+.Ic include ,
+.Ic hide ,
+.Ic jail ,
+.Ic link ,
+.Ic perm
+and
+.Ic show :
+.Bl -tag -width indent -offset indent
+.It Ic group Ar group_name Ar name ...
+This will group the specified names into a group of the specified
+.Ar group_name .
+.It Ic include Ar file
+Includes the specified rule file and processes its rules.
+.It Ic hide Ar name
+This will hide the device node(s) specified by
+.Ar name .
+A hidden node will not appear in directory listings and all operations on
+it will fail, except if it is open already.
+By default, everything except
+.Xr pty 4
+nodes is shown.
+.It Ic jail Ar yes|no
+A
+.Sq Ar yes
+argument will cause all following rules to only apply to mounts of
+.Xr devfs
+inside a
+.Xr jail 8 ,
+until a
+.Dq Ic jail Ar no
+is reached.
+.It Ic link Ar device Ar path
+.Ic link
+rules will create a link node at the specified
+.Ar link_path
+to the given
+.Ar device .
+The path is relative to the mountpoint being operated on (see
+.Xr devfsctl 8 Ap s
+.Fl m
+option), which is usually
+.Pa /dev .
+.Pp
+Note that for
+.Ic link
+rules, the
+.Ar device
+has to be a single device node and specifying a device type or group (unless
+it contains only one node) is not possible.
+.It Ic perm Ar name Ar user:group Ar mode
+A
+.Ic perm
+rule will applies the specified mode (octal, see
+.Xr chmod 1 )
+and ownership (see
+.Xr chown 2 )
+to
+.Ar name .
+.It Ic show Ar name
+This will show previously hidden nodes again.
+.El
 .Sh FILES
 .Bl -tag -width ".Pa /etc/devfs" -compact
-.It Pa /etc/devfs
+.It Pa /etc/devfs/*
 devfs ruleset files
 .El
+.Sh EXAMPLES
+Examples of valid names:
+.Bd -literal -offset indent
+bpf*
+tun0
+D_DISK
+serno/*s3
+@groupA
+.Ed
+.Pp
+Examples of valid rules:
+.Bd -literal -offset indent
+group   foo     da*     ri*
+group   foo     ad*
+group   foo     md*
+
+perm    da0     uucp:dialer 0644
+link    foo     bar
+hide    @foo
+show    D_DISK
+group   g1      a b f g
+group   g2      c d
+group   g3      @g1 h @g2 i j k D_MEM
+jail    yes
+hide    @g3
+perm    @g3     root:wheel 0644
+jail    no
+group   cdrom   cd*     acd*
+group   disks   da*
+group   disks   ad*
+group   drives  @disks  @cdrom
+
+group   test    @disks  @g2     y
+show    @drives
+show    @disks
+show    @test
+link    da0     "my drives/my new da0"
+.Ed
 .Sh SEE ALSO
 .Xr devfs 5 ,
 .Xr devfs.conf 5 ,