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.5 2006/02/17 19:40:29 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 FILES
 132 .Bl -tag -width /etc/usbd.conf -compact
 133 .It Pa /etc/usbd.conf
 134 The
 135 .Nm usbd
 136 configuration file.
 137 .El
 138 .Sh EXAMPLES
 139 A sample entry to rescan the SCSI bus on connection of a
 140 .Tn "Iomega USB Zip Drive" :
 141 .Bd -literal
 142    device "USB Zip drive"
 143       product 0x0001
 144       vendor  0x059b
 145       release 0x0100
 146       attach "/usr/bin/camcontrol rescan bus 0"
 147 .Ed
 148 .Pp
 149 To start up moused for a newly attached mouse:
 150 .Bd -literal
 151    device "Mouse"
 152       devname "ums[0-9]+"
 153       attach "/usr/sbin/moused -p /dev/${DEVNAME} -I /var/run/moused.${DEVNAME}.pid"
 154 .Ed
 155 .Sh SEE ALSO
 156 .Xr usb 4 ,
 157 .Xr usbd 8 ,
 158 .Xr usbdevs 8
 159 .Sh AUTHORS
 160 This manual page was written by
 161 .An Nick Hibma Aq n_hibma@FreeBSD.org .
 162 .Sh BUGS
 163 It is currently not possible to use a selection criterion more than once.
 164 For example, it is not possible to specify more than one vendor ID.