1 INTRO 2 ----- 3 4This document describes the format of /etc/hotplug2.rules file. 5 6The general syntax is: 7 8<key> <condition type> <value> [, <key> <condition type> <value> [,...]] { 9 action [parameter] 10 [action [parameter]] 11 [... [...]] 12} 13 14Comments are allowed, they are prefixed with '#', treating the whole rest of 15the line as comment. Please note that comments in place of action parameters 16are not supported. 17 18The <key> is one of the environmental variables that have been obtained by 19the uevent netlink. 20 21 COMMON KEYS 22 ----------- 23 24The most common keys available are: 25 * ACTION 26 27 * SUBSYSTEM 28 29 * DEVPATH 30 31 * MODALIAS 32 33 * MAJOR 34 35 * MINOR 36 37These values are also substituted by "%variable%", eg. "%MODALIAS". There is 38a variable not sent by kernel, but exported nonetheless: DEVICENAME. This 39variable is set if DEVPATH is set, and is result of basename(DEVPATH). 40 41 42 CONDITION TYPES 43 --------------- 44 45Conditiom types specify the realtionship between <key> and <value>. 46Available 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 125Flags are, syntactically, just like actions; their semantical value is different however. 126Instead of doing something, they instead change the general behavior of the processing 127of the given rule. 128 129Note that for flags to work, you also have to invoke it with --override. 130 131Currently, 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 143There 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 158Below is a sample hotplug2.rules file. It loads modules to all available 159devices quietly and creates device nodes for block devices. Note that this 160sample is not very viable for real life usage. 161--------------------------------------------------------------------------------- 162MODALIAS is set { 163 exec modprobe -q %MODALIAS% ; 164} 165 166SUBSYSTEM == block, DEVPATH is set, MAJOR is set, MINOR is set { 167 makedev /dev/%DEVICENAME% 0644 168} 169 170 171Please find also the more complex set of rules, dedicated to handling most 172common needs. 173--------------------------------------------------------------------------------- 174#For debugging 175#ACTION is set { 176# printdebug 177#} 178 179# Load modules (what old hotplug did) 180MODALIAS is set { 181 exec modprobe -q %MODALIAS% ; 182} 183 184# Create device nodes 185DEVPATH is set, MAJOR is set, MINOR is set { 186 makedev /dev/%DEVICENAME% 0644 187} 188 189# Mount a USB flashdisk 190ACTION == 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 196ACTION == remove, PHYSDEVPATH ~~ "/usb[0-9]*/", DEVICENAME ~~ "^sd[a-z][0-9]+$", MAJOR is set, MINOR is set { 197 exec umount /mnt/%DEVICENAME% 198} 199