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 .\"
  28 .\" Many parts of this manual have been snarfed from the pccard.conf (5) man
  29 .\" page, copyright by Andrew McRae.
  30 .\"
  31 .Dd November 19, 1999
  32 .Dt USBD.CONF 5
  33 .Os
  34 .Sh NAME
  35 .Nm usbd.conf
  36 .Nd
  37 .Xr usbd 8
  38 configuration file
  39 .Sh DESCRIPTION
  40 The
  41 .Nm
  42 file is the configuration file for the
  43 .Xr usbd 8
  44 daemon.
  45 It provides information to allow execution of userland commands
  46 on events reported by the
  47 .Xr usb 4
  48 subsystem in the kernel.
  49 Currently the only events are device attach and
  50 detach, but could in the future be extended to include power management
  51 functions.
  52 .Pp
  53 The configuration file consists of a sorted list of entries.
  54 Each entry
  55 describes a set of criteria commands.
  56 When an event occurs, the criteria
  57 are checked and if met, the commands for that event are executed through
  58 a shell.
  59 The list is sorted and scanned from top to bottom.
  60 The first
  61 matching entry is used for an event.
  62 .Pp
  63 Each entry contains a number of fields.
  64 There are 3 types of fields:
  65 descriptive fields, selection criteria and commands to execute on
  66 events.
  67 The field names are case sensitive and should be all lower case.
  68 Each field can have one or more arguments.
  69 .Pp
  70 The following fields are available:
  71 .Bl -tag -width devicename\ <Id>
  72 .It device Ar string
  73 Start a new entry.
  74 .Ar string
  75 is an arbitrary string used for pretty printing.
  76 .It product Ar id
  77 Product Id
  78 .It vendor Ar id
  79 Vendor Id
  80 .It release Ar id
  81 Release Id, also called revision Id sometimes.
  82 .It class Ar id
  83 Device Class
  84 .It subclass Ar id
  85 Device Subclass
  86 .It protocol Ar id
  87 Device Protocol
  88 .It devname Ar string
  89 Device name, for example umass2, or ums0.
  90 These device names can contain regular expressions.
  91 See
  92 .Xr regex 3
  93 and
  94 .Xr re_format 7 .
  95 The device name that is matched can be used in the commands below
  96 through adding ${DEVNAME} somewhere in that string.
  97 .El
  98 .Pp
  99 String arguments may be quoted.
 100 If a string argument contains a space or
 101 tab character it needs to be enclosed in single or double quotes.
 102 If an
 103 argument contains a single or double quote, that quote needs to be
 104 enclosed in double or single quotes respectively.
 105 See below for
 106 examples.
 107 .Pp
 108 Numeric arguments can either be specified in decimal (42), octal (052) or
 109 hexadecimal (0x2a).
 110 .Pp
 111 The values for the fields
 112 .Li product , vendor , release, class , subclass
 113 and
 114 .Li protocol
 115 can be retrieved by killing the
 116 .Nm usbd
 117 daemon and running it with the
 118 .Fl d
 119 and
 120 .Fl v
 121 flags.
 122 .Pp
 123 Commands to be executed when the action is matched:
 124 .Bl -tag -width devicename\ <Id>
 125 .It attach Ar string
 126 Shell command to execute when a device is attached.
 127 .It detach Ar string
 128 Shell command to execute when a device is detached.
 129 .El
 130 .Sh FILES
 131 .Bl -tag -width /etc/usbd.conf -compact
 132 .It Pa /etc/usbd.conf
 133 The
 134 .Nm usbd
 135 configuration file.
 136 .El
 137 .Sh EXAMPLES
 138 A sample entry to rescan the SCSI bus on connection of a
 139 .Tn "Iomega USB Zip Drive" :
 140 .Bd -literal
 141    device "USB Zip drive"
 142       product 0x0001
 143       vendor  0x059b
 144       release 0x0100
 145       attach "/usr/bin/camcontrol rescan bus 0"
 146 .Ed
 147 .Pp
 148 To start up moused for a newly attached mouse:
 149 .Bd -literal
 150    device "Mouse"
 151       devname "ums[0-9]+"
 152       attach "/usr/sbin/moused -p /dev/${DEVNAME} -I /var/run/moused.${DEVNAME}.pid"
 153 .Ed
 154 .Sh SEE ALSO
 155 .Xr usb 4 ,
 156 .Xr usbd 8 ,
 157 .Xr usbdevs 8
 158 .Sh AUTHORS
 159 This manual page was written by
 160 .An Nick Hibma Aq Mt n_hibma@FreeBSD.org .
 161 .Sh BUGS
 162 It is currently not possible to use a selection criterion more than once.
 163 For example, it is not possible to specify more than one vendor ID.