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 the
15line as comment. Please note that comments in place of action parameters are not
16supported.
17
18The <key> is one of the environmental variables that have been obtained by the
19uevent 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 that
70	the application has set all environmental variables read by uevent
71	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 variables
90	are set as environmental.
91	
92	If you need to escape the ';', use '\\;'. Only applies for actions with
93	variable number of parameters.
94	
95 * makedev <path> <mode>
96	Create a device with given mode. The mode is not in octal unless it
97	starts with '0', eg. "0644" != "644".
98	
99	Major, minor and devpath must be set for makedev to be able to work.
100	Tests for these variables are also performed internally in makedev
101	function.
102
103 * symlink <target> <linkname>
104	Create a symbolic link (symlink, also known as soft link) pointing at
105	target with name linkname.
106	
107 * chown <path> <owner name>
108	Change owner of path to owner name.
109	
110 * chgrp <path> <group name>
111	Change group of path to group name.
112	
113 * chmod <path> <mode>
114	Change mode of path to given mode. Like with makedev, heading '0' is
115	necessary for the mode to be interpreted as octal.
116
117 * setenv <key> <value>
118	Sets environmental variable key to the given value. If an env var
119	of the given name already exists, it gets overwritten.
120	
121 ESCAPING
122 --------
123
124There are several items you may like to escape:
125 * variable substitution
126	You can escape variable substituion by "%\\variable%\\".
127	
128 * action block terminator '}'
129	Similarly, to escape action block terminator, use '\\}'
130
131 * variable parameter terminator ';' (semicolon)
132	Likewise, you can use '\\;' to escape variable parameter terminator.
133	Note that this only works for actions that take variable number of
134	paramteres, such as 'exec'.
135
136 SAMPLE CONFIG
137 -------------
138
139Below is a sample hotplug2.rules file. It loads modules to all available devices
140quietly and creates device nodes for block devices.
141---------------------------------------------------------------------------------
142MODALIAS is set {
143	exec modprobe -q %MODALIAS% ;
144}
145
146SUBSYSTEM == block, DEVPATH is set, MAJOR is set, MINOR is set {
147	makedev /dev/%DEVICENAME% 0644
148}
149