release/src/router/hotplug2/docs/hotplug2.rules.doc

   1  INTRO
   2  -----
   3
   4 This document describes the format of /etc/hotplug2.rules file.
   5
   6 The general syntax is:
   7
   8 <key> <condition type> <value> [, <key> <condition type> <value> [,...]] {
   9         action [parameter]
  10         [action [parameter]]
  11         [... [...]]
  12 }
  13
  14 Comments are allowed, they are prefixed with '#', treating the whole rest of
  15 the line as comment. Please note that comments in place of action parameters
  16 are not supported.
  17
  18 The <key> is one of the environmental variables that have been obtained by
  19 the uevent netlink.
  20
  21  COMMON KEYS
  22  -----------
  23
  24 The most common keys available are:
  25  * ACTION
  26
  27  * SUBSYSTEM
  28
  29  * DEVPATH
  30
  31  * MODALIAS
  32
  33  * MAJOR
  34
  35  * MINOR
  36
  37 These values are also substituted by "%variable%", eg. "%MODALIAS". There is
  38 a variable not sent by kernel, but exported nonetheless: DEVICENAME. This
  39 variable is set if DEVPATH is set, and is result of basename(DEVPATH).
  40
  41
  42  CONDITION TYPES
  43  ---------------
  44
  45 Conditiom types specify the realtionship between <key> and <value>.
  46 Available condition types are:
  47  * ==
  48         Values are equal, case sensitive
  49
  50  * !=
  51         Values are not equal, case sensitive
  52
  53  * ~~
  54         The content of <key> matches regex pattern in <value>
  55
  56  * !~
  57         The content of <key> does not match regex pattern in <value>
  58
  59  * is
  60         This is a special condition type. Valid values for it are 'set' and
  61         'unset', specifying the key has any value at all or not. Any other
  62         value implies the condition fails.
  63
  64
  65   ACTIONS
  66   -------
  67
  68  * run <...>
  69         Execute an application using system();, takes one parameter. Note
  70         that the application has set all environmental variables read by
  71         uevent netlink.
  72
  73  * break
  74         Break the processing of the current block of actions.
  75
  76  * break_if_failed
  77         Break if return value from the last action was non-zero.
  78
  79  * next
  80         Continue to the next event, do not process any more rules for the
  81         current one.
  82
  83  * next_if_failed
  84         Continue to the next event if return value from the last action was
  85         non-zero.
  86
  87  * exec <application [parameter [parameter [...]]]> ;
  88         Execute an application. Takes variable number of parameters, but the
  89         last parameter must be terminated with semicolon. Again, all
  90         variables are set as environmental.
  91
  92         If you need to escape the ';', use '\\;'. Only applies for actions
  93         with variable number of parameters.
  94
  95  * makedev <path> <mode>
  96         Create a device with given mode. Mode is interpreted as octal.
  97
  98         Major, minor and devpath must be set for makedev to be able to work.
  99         Tests for these variables are also performed internally in makedev
 100         function.
 101
 102  * symlink <target> <linkname>
 103         Create a symbolic link (symlink, also known as soft link) pointing
 104         at target with name linkname.
 105
 106  * chown <path> <owner name>
 107         Change owner of path to owner name.
 108
 109  * chgrp <path> <group name>
 110         Change group of path to group name.
 111
 112  * chmod <path> <mode>
 113         Change mode of path to given mode. Mode is interpreted as octal.
 114
 115  * setenv <key> <value>
 116         Sets environmental variable key to the given value. If an env var
 117         of the given name already exists, it gets overwritten.
 118
 119  * printdebug
 120         Prints all variables read from kernel.
 121
 122  FLAGS
 123  -----
 124
 125 Flags are, syntactically, just like actions; their semantical value is different however.
 126 Instead of doing something, they instead change the general behavior of the processing
 127 of the given rule.
 128
 129 Note that for flags to work, you also have to invoke it with --override.
 130
 131 Currently, only one flag is implemented:
 132
 133  * nothrottle
 134         Forcibly overrides hotplug2 throttling mechanism. If _all_ rules that match
 135         the given kernel event have 'nothrottle' set, hotplug2 will not wait for
 136         children count to get under max-children limit. That allows to throttle
 137         eg. helper application execution or modprobes, but yet keep node devices
 138         fast.
 139
 140  ESCAPING
 141  --------
 142
 143 There are several items you may like to escape:
 144  * variable substitution
 145         You can escape variable substituion by "%\\variable%\\".
 146
 147  * action block terminator '}'
 148         Similarly, to escape action block terminator, use '\\}'
 149
 150  * variable parameter terminator ';' (semicolon)
 151         Likewise, you can use '\\;' to escape variable parameter terminator.
 152         Note that this only works for actions that take variable number of
 153         paramteres, such as 'exec'.
 154
 155  SAMPLE CONFIG
 156  -------------
 157
 158 Below is a sample hotplug2.rules file. It loads modules to all available
 159 devices quietly and creates device nodes for block devices. Note that this
 160 sample is not very viable for real life usage.
 161 ---------------------------------------------------------------------------------
 162 MODALIAS is set {
 163         exec modprobe -q %MODALIAS% ;
 164 }
 165
 166 SUBSYSTEM == block, DEVPATH is set, MAJOR is set, MINOR is set {
 167         makedev /dev/%DEVICENAME% 0644
 168 }
 169
 170
 171 Please find also the more complex set of rules, dedicated to handling most
 172 common needs.
 173 ---------------------------------------------------------------------------------
 174 #For debugging
 175 #ACTION is set {
 176 #       printdebug
 177 #}
 178
 179 # Load modules (what old hotplug did)
 180 MODALIAS is set {
 181         exec modprobe -q %MODALIAS% ;
 182 }
 183
 184 # Create device nodes
 185 DEVPATH is set, MAJOR is set, MINOR is set {
 186         makedev /dev/%DEVICENAME% 0644
 187 }
 188
 189 # Mount a USB flashdisk
 190 ACTION == add, PHYSDEVPATH ~~ "/usb[0-9]*/", DEVICENAME ~~ "^sd[a-z][0-9]+$", DEVPATH is set, MAJOR is set, MINOR is set {
 191         makedev /dev/%DEVICENAME% 0644
 192         exec mount /dev/%DEVICENAME% /mnt/%DEVICENAME%
 193 }
 194
 195 # Unmount a USB flashdisk
 196 ACTION == remove, PHYSDEVPATH ~~ "/usb[0-9]*/", DEVICENAME ~~ "^sd[a-z][0-9]+$", MAJOR is set, MINOR is set {
 197         exec umount /mnt/%DEVICENAME%
 198 }