freebsd-nq/usr.sbin/usbd/usbd.conf.5

.\"
.\" Copyright (c) 1999 Nick Hibma.  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.
.\" 3. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 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$
.\"
.\" Many parts of this manual have been snarfed from the pccard.conf (5) man
.\" page, copyright by Andrew McRae.
.\"
.Dd November 19, 1999
.Dt USBD.CONF 5
.Os
.Sh NAME
.Nm usbd.conf
.Nd
.Xr usbd 8
configuration file
.Sh DESCRIPTION
The
.Nm
file is the configuration file for the
.Xr usbd 8
daemon.
It provides information to allow execution of userland commands
on events reported by the
.Xr usb 4
subsystem in the kernel.
Currently the only events are device attach and
detach, but could in the future be extended to include power management
functions.
.Pp
The configuration file consists of a sorted list of entries.
Each entry
describes a set of criteria commands.
When an event occurs, the criteria
are checked and if met, the commands for that event are executed through
a shell.
The list is sorted and scanned from top to bottom.
The first
matching entry is used for an event.
.Pp
Each entry contains a number of fields.
There are 3 types of fields:
descriptive fields, selection criteria and commands to execute on
events.
The field name is case sensitive and should be all lower case.
Each field can have one or more arguments.
.Pp
The following fields are available:
.Bl -tag -width devicename\ <Id>
.It device Ar string
Start a new entry.
.Ar string
is an arbitrary string used for pretty printing.
.It product Ar id
Product Id
.It vendor Ar id
Vendor Id
.It release Ar id
Release Id, also called revision Id sometimes.
.It class Ar id
Device Class
.It subclass Ar id
Device Subclass
.It protocol Ar id
Device Protocol
.It devname Ar string
Device name, for example umass2, or ums0. These device names can contain
regular expressions.
See
.Xr regex 3
and
.Xr re_format 7 .
The device name that is matched can be used in the commands below
through adding ${DEVNAME} somewhere in that string.
.El
.Pp
String arguments may be quoted.
If a string argument contains a space or
tab character it needs to be enclosed in single or double quotes.
If an
argument contains a single or double quote, that quote needs to be
enclosed in double or single quotes respectively.
See below for
examples.
.Pp
Numeric arguments can either be specified in decimal (42), octal (052) or
hexadeximal (0x2a).
.Pp
The values for the fields
.Li product , vendor , release, class , subclass
and
.Li protocol
can be retrieved by killing the
.Nm usbd
daemon and running it with the
.Fl d
and
.Fl v
flags.
.Pp
Commands to be executed when the action is matched:
.Bl -tag -width devicename\ <Id>
.It attach Ar string
Shell command to execute when a device is attached.
.It detach Ar string
Shell command to execute when a device is detached.
.El
.Sh EXAMPLES
A sample entry to rescan the SCSI bus on connection of a
.Tn "Iomega USB Zip Drive" :
.Bd -literal
   device "USB Zip drive"
      product 0x0001
      vendor  0x059b
      release 0x0100
      attach "/usr/bin/camcontrol rescan bus 0"
.Ed
.Pp
To start up moused for a newly attached mouse:
.Bd -literal
   device "Mouse"
      devname "ums[0-9]+"
      attach "/usr/sbin/moused -p /dev/${DEVNAME} -I /var/run/moused.${DEVNAME}.pid"
.Ed
.Sh FILES
.Bl -tag -width /etc/pccard.conf -compact
.It Pa /etc/usbd.conf
The
.Nm usbd
configuration file.
.El
.Sh SEE ALSO
.Xr usb 4 ,
.Xr usbd 8 ,
.Xr usbdevs 8
.Sh BUGS
It is currently not possible to use a selection criterium more than once. For
example it is not possible to specify more than one vendor Id.
.Sh AUTHORS
The man page for the usbd configuration file was written by
.An Nick Hibma Aq n_hibma@FreeBSD.org .