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