8498e7dd58f5f65ce874129e920ddfd6b9af5ef3
[dragonfly.git] / usr.sbin / usbd / usbd.conf.5
1 .\"
2 .\" Copyright (c) 1999 Nick Hibma.  All rights reserved.
3 .\"
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
6 .\" are met:
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\"    notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\"    notice, this list of conditions and the following disclaimer in the
11 .\"    documentation and/or other materials provided with the distribution.
12 .\" 3. The name of the author may not be used to endorse or promote products
13 .\"    derived from this software without specific prior written permission.
14 .\"
15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
16 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
17 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
18 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
19 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
20 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
21 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
22 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
23 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
24 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
25 .\"
26 .\" $FreeBSD: src/usr.sbin/usbd/usbd.conf.5,v 1.13 2003/01/30 22:38:54 trhodes Exp $
27 .\" $DragonFly: src/usr.sbin/usbd/usbd.conf.5,v 1.4 2005/06/17 23:10:11 swildner Exp $
28 .\"
29 .\" Many parts of this manual have been snarfed from the pccard.conf (5) man
30 .\" page, copyright by Andrew McRae.
31 .\"
32 .Dd November 19, 1999
33 .Dt USBD.CONF 5
34 .Os
35 .Sh NAME
36 .Nm usbd.conf
37 .Nd
38 .Xr usbd 8
39 configuration file
40 .Sh DESCRIPTION
41 The
42 .Nm
43 file is the configuration file for the
44 .Xr usbd 8
45 daemon.
46 It provides information to allow execution of userland commands
47 on events reported by the
48 .Xr usb 4
49 subsystem in the kernel.
50 Currently the only events are device attach and
51 detach, but could in the future be extended to include power management
52 functions.
53 .Pp
54 The configuration file consists of a sorted list of entries.
55 Each entry
56 describes a set of criteria commands.
57 When an event occurs, the criteria
58 are checked and if met, the commands for that event are executed through
59 a shell.
60 The list is sorted and scanned from top to bottom.
61 The first
62 matching entry is used for an event.
63 .Pp
64 Each entry contains a number of fields.
65 There are 3 types of fields:
66 descriptive fields, selection criteria and commands to execute on
67 events.
68 The field names are case sensitive and should be all lower case.
69 Each field can have one or more arguments.
70 .Pp
71 The following fields are available:
72 .Bl -tag -width devicename\ <Id>
73 .It device Ar string
74 Start a new entry.
75 .Ar string
76 is an arbitrary string used for pretty printing.
77 .It product Ar id
78 Product Id
79 .It vendor Ar id
80 Vendor Id
81 .It release Ar id
82 Release Id, also called revision Id sometimes.
83 .It class Ar id
84 Device Class
85 .It subclass Ar id
86 Device Subclass
87 .It protocol Ar id
88 Device Protocol
89 .It devname Ar string
90 Device name, for example umass2, or ums0.
91 These device names can contain regular expressions.
92 See
93 .Xr regex 3
94 and
95 .Xr re_format 7 .
96 The device name that is matched can be used in the commands below
97 through adding ${DEVNAME} somewhere in that string.
98 .El
99 .Pp
100 String arguments may be quoted.
101 If a string argument contains a space or
102 tab character it needs to be enclosed in single or double quotes.
103 If an
104 argument contains a single or double quote, that quote needs to be
105 enclosed in double or single quotes respectively.
106 See below for
107 examples.
108 .Pp
109 Numeric arguments can either be specified in decimal (42), octal (052) or
110 hexadecimal (0x2a).
111 .Pp
112 The values for the fields
113 .Li product , vendor , release, class , subclass
114 and
115 .Li protocol
116 can be retrieved by killing the
117 .Nm usbd
118 daemon and running it with the
119 .Fl d
120 and
121 .Fl v
122 flags.
123 .Pp
124 Commands to be executed when the action is matched:
125 .Bl -tag -width devicename\ <Id>
126 .It attach Ar string
127 Shell command to execute when a device is attached.
128 .It detach Ar string
129 Shell command to execute when a device is detached.
130 .El
131 .Sh EXAMPLES
132 A sample entry to rescan the SCSI bus on connection of a
133 .Tn "Iomega USB Zip Drive" :
134 .Bd -literal
135    device "USB Zip drive"
136       product 0x0001
137       vendor  0x059b
138       release 0x0100
139       attach "/usr/bin/camcontrol rescan bus 0"
140 .Ed
141 .Pp
142 To start up moused for a newly attached mouse:
143 .Bd -literal
144    device "Mouse"
145       devname "ums[0-9]+"
146       attach "/usr/sbin/moused -p /dev/${DEVNAME} -I /var/run/moused.${DEVNAME}.pid"
147 .Ed
148 .Sh FILES
149 .Bl -tag -width /etc/usbd.conf -compact
150 .It Pa /etc/usbd.conf
151 The
152 .Nm usbd
153 configuration file.
154 .El
155 .Sh SEE ALSO
156 .Xr usb 4 ,
157 .Xr usbd 8 ,
158 .Xr usbdevs 8
159 .Sh BUGS
160 It is currently not possible to use a selection criterion more than once.
161 For example, it is not possible to specify more than one vendor ID.
162 .Sh AUTHORS
163 This manual page was written by
164 .An Nick Hibma Aq n_hibma@FreeBSD.org .