1UDEVADM(8) udevadm UDEVADM(8)
2
6 udevadm - udev management tool
7
9 udevadm [--debug] [--version] [--help]
10 udevadm info [options] [devpath]
12 udevadm trigger [options] [devpath]
14 udevadm settle [options]
16 udevadm control option
18 udevadm monitor [options]
20 udevadm test [options] devpath
22 udevadm test-builtin [options] command devpath
24 udevadm verify [options...] [file...]
26 udevadm wait [options] device|syspath
28 udevadm lock [options] command
30
32 udevadm expects a command and command specific options. It controls the
33 runtime behavior of systemd-udevd, requests kernel events, manages the
34 event queue, and provides simple debugging mechanisms.
35
37 -d, --debug
38 Print debug messages to standard error. This option is implied in
39 udevadm test and udevadm test-builtin commands.
40 -h, --help
42 Print a short help text and exit.
43 udevadm info [options] [devpath|file|unit...]
45 Query the udev database for device information.
46 Positional arguments should be used to specify one or more devices.
48 Each one may be a device name (in which case it must start with /dev/),
49 a sys path (in which case it must start with /sys/), or a systemd
50 device unit name (in which case it must end with ".device", see
51 systemd.device(5)).
52 -q, --query=TYPE
54 Query the database for the specified type of device data. Valid
55 TYPEs are: name, symlink, path, property, all.
56 --property=NAME
58 When showing device properties using the --query=property option,
59 limit display to properties specified in the argument. The argument
60 should be a comma-separated list of property names. If not
61 specified, all known properties are shown.
62 --value
64 When showing device properties using the --query=property option,
65 print only their values, and skip the property name and "=".
66 Cannot be used together with -x/--export or -P/--export-prefix.
68 -p, --path=DEVPATH
70 The /sys/ path of the device to query, e.g.
71 [/sys/]/class/block/sda. This option is an alternative to the
72 positional argument with a /sys/ prefix. udevadm info
73 --path=/class/block/sda is equivalent to udevadm info
74 /sys/class/block/sda.
75 -n, --name=FILE
77 The name of the device node or a symlink to query, e.g.
78 [/dev/]/sda. This option is an alternative to the positional
79 argument with a /dev/ prefix. udevadm info --name=sda is
80 equivalent to udevadm info /dev/sda.
81 -r, --root
83 Print absolute paths in name or symlink query.
84 -a, --attribute-walk
86 Print all sysfs properties of the specified device that can be used
87 in udev rules to match the specified device. It prints all devices
88 along the chain, up to the root of sysfs that can be used in udev
89 rules.
90 -t, --tree
92 Display a sysfs tree. This recursively iterates through the sysfs
93 hierarchy and displays it in a tree structure. If a path is
94 specified only the subtree below and its parent directories are
95 shown. This will show both device and subsystem items.
96 -x, --export
98 Print output as key/value pairs. Values are enclosed in single
99 quotes. This takes effects only when --query=property or
100 --device-id-of-file=FILE is specified.
101 -P, --export-prefix=NAME
103 Add a prefix to the key name of exported values. This implies
104 --export.
105 -d, --device-id-of-file=FILE
107 Print major/minor numbers of the underlying device, where the file
108 lives on. If this is specified, all positional arguments are
109 ignored.
110 -e, --export-db
112 Export the content of the udev database.
113 -c, --cleanup-db
115 Cleanup the udev database.
116 -w[SECONDS], --wait-for-initialization[=SECONDS]
118 Wait for device to be initialized. If argument SECONDS is not
119 specified, the default is to wait forever.
120 -h, --help
122 Print a short help text and exit.
123 --no-pager
125 Do not pipe output into a pager.
126 The generated output shows the current device database entry in a terse
128 format. Each line shown is prefixed with one of the following
129 characters:
130 Table 1. udevadm info output prefixes
132 ┌───────┬────────────────────────────┐
133 │Prefix │ Meaning │
134 ├───────┼────────────────────────────┤
135 │"P:" │ Device path in /sys/ │
136 ├───────┼────────────────────────────┤
137 │"M:" │ Device name in /sys/ (i.e. │
138 │ │ the last component of │
139 │ │ "P:") │
140 ├───────┼────────────────────────────┤
141 │"R:" │ Device number in /sys/ │
142 │ │ (i.e. the numeric suffix │
143 │ │ of the last component of │
144 │ │ "P:") │
145 ├───────┼────────────────────────────┤
146 │"U:" │ Kernel subsystem │
147 ├───────┼────────────────────────────┤
148 │"T:" │ Kernel device type within │
149 │ │ subsystem │
150 ├───────┼────────────────────────────┤
151 │"D:" │ Kernel device node │
152 │ │ major/minor │
153 ├───────┼────────────────────────────┤
154 │"I:" │ Network interface index │
155 ├───────┼────────────────────────────┤
156 │"N:" │ Kernel device node name │
157 ├───────┼────────────────────────────┤
158 │"L:" │ Device node symlink │
159 │ │ priority │
160 ├───────┼────────────────────────────┤
161 │"S:" │ Device node symlink │
162 ├───────┼────────────────────────────┤
163 │"Q:" │ Block device sequence │
164 │ │ number (DISKSEQ) │
165 ├───────┼────────────────────────────┤
166 │"V:" │ Attached driver │
167 ├───────┼────────────────────────────┤
168 │"E:" │ Device property │
169 └───────┴────────────────────────────┘
170 udevadm trigger [options] [devpath|file|unit]
172 Request device events from the kernel. Primarily used to replay events
173 at system coldplug time.
174 Takes device specifications as positional arguments. See the
176 description of info above.
177 -v, --verbose
179 Print the list of devices which will be triggered.
180 -n, --dry-run
182 Do not actually trigger the event.
183 -q, --quiet
185 Suppress error logging in triggering events.
186 -t, --type=TYPE
188 Trigger a specific type of devices. Valid types are "all",
189 "devices", and "subsystems". The default value is "devices".
190 -c, --action=ACTION
192 Type of event to be triggered. Possible actions are "add",
193 "remove", "change", "move", "online", "offline", "bind", and
194 "unbind". Also, the special value "help" can be used to list the
195 possible actions. The default value is "change".
196 --prioritized-subsystem=SUBSYSTEM[,SUBSYSTEM...]
198 Takes a comma separated list of subsystems. When triggering events
199 for devices, the devices from the specified subsystems and their
200 parents are triggered first. For example, if
201 --prioritized-subsystem=block,net, then firstly all block devices
202 and their parents are triggered, in the next all network devices
203 and their parents are triggered, and lastly the other devices are
204 triggered. This option can be specified multiple times, and in that
205 case the lists of the subsystems will be merged. That is,
206 --prioritized-subsystem=block --prioritized-subsystem=net is
207 equivalent to --prioritized-subsystem=block,net.
208 -s, --subsystem-match=SUBSYSTEM
210 Trigger events for devices which belong to a matching subsystem.
211 This option supports shell style pattern matching. When this option
212 is specified more than once, then each matching result is ORed,
213 that is, all the devices in each subsystem are triggered.
214 -S, --subsystem-nomatch=SUBSYSTEM
216 Do not trigger events for devices which belong to a matching
217 subsystem. This option supports shell style pattern matching. When
218 this option is specified more than once, then each matching result
219 is ANDed, that is, devices which do not match all specified
220 subsystems are triggered.
221 -a, --attr-match=ATTRIBUTE=VALUE
223 Trigger events for devices with a matching sysfs attribute. If a
224 value is specified along with the attribute name, the content of
225 the attribute is matched against the given value using shell style
226 pattern matching. If no value is specified, the existence of the
227 sysfs attribute is checked. When this option is specified multiple
228 times, then each matching result is ANDed, that is, only devices
229 which have all specified attributes are triggered.
230 -A, --attr-nomatch=ATTRIBUTE=VALUE
232 Do not trigger events for devices with a matching sysfs attribute.
233 If a value is specified along with the attribute name, the content
234 of the attribute is matched against the given value using shell
235 style pattern matching. If no value is specified, the existence of
236 the sysfs attribute is checked. When this option is specified
237 multiple times, then each matching result is ANDed, that is, only
238 devices which have none of the specified attributes are triggered.
239 -p, --property-match=PROPERTY=VALUE
241 Trigger events for devices with a matching property value. This
242 option supports shell style pattern matching. When this option is
243 specified more than once, then each matching result is ORed, that
244 is, devices which have one of the specified properties are
245 triggered.
246 -g, --tag-match=TAG
248 Trigger events for devices with a matching tag. When this option is
249 specified multiple times, then each matching result is ANDed, that
250 is, devices which have all specified tags are triggered.
251 -y, --sysname-match=NAME
253 Trigger events for devices for which the last component (i.e. the
254 filename) of the /sys/ path matches the specified PATH. This option
255 supports shell style pattern matching. When this option is
256 specified more than once, then each matching result is ORed, that
257 is, all devices which have any of the specified NAME are triggered.
258 --name-match=NAME
260 Trigger events for devices with a matching device path. When this
261 option is specified more than once, then each matching result is
262 ORed, that is, all specified devices are triggered.
263 -b, --parent-match=SYSPATH
265 Trigger events for all children of a given device. When this option
266 is specified more than once, then each matching result is ORed,
267 that is, all children of each specified device are triggered.
268 --initialized-match, --initialized-nomatch
270 When --initialized-match is specified, trigger events for devices
271 that are already initialized by systemd-udevd, and skip devices
272 that are not initialized yet.
273 When --initialized-nomatch is specified, trigger events for devices
275 that are not initialized by systemd-udevd yet, and skip devices
276 that are already initialized.
277 Typically, it is essential that applications which intend to use
279 such a match, make sure a suitable udev rule is installed that sets
280 at least one property on devices that shall be matched. See also
281 Initialized Devices section below for more details.
282 WARNING: --initialized-nomatch can potentially save a significant
284 amount of time compared to re-triggering all devices in the system
285 and e.g. can be used to optimize boot time. However, this is not
286 safe to be used in a boot sequence in general. Especially, when
287 udev rules for a device depend on its parent devices (e.g. "ATTRS"
288 or "IMPORT{parent}" keys, see udev(7) for more details), the final
289 state of the device becomes easily unstable with this option.
290 -w, --settle
292 Apart from triggering events, also waits for those events to
293 finish. Note that this is different from calling udevadm settle.
294 udevadm settle waits for all events to finish. This option only
295 waits for events triggered by the same command to finish.
296 --uuid
298 Trigger the synthetic device events, and associate a randomized
299 UUID with each. These UUIDs are printed to standard output, one
300 line for each event. These UUIDs are included in the uevent
301 environment block (in the "SYNTH_UUID=" property) and may be used
302 to track delivery of the generated events.
303 --wait-daemon[=SECONDS]
305 Before triggering uevents, wait for systemd-udevd daemon to be
306 initialized. Optionally takes timeout value. Default timeout is 5
307 seconds. This is equivalent to invoking udevadm control --ping
308 before udevadm trigger.
309 -h, --help
311 Print a short help text and exit.
312 In addition, optional positional arguments can be used to specify
314 device names or sys paths. They must start with /dev/ or /sys/
315 respectively.
316 udevadm settle [options]
318 Watches the udev event queue, and exits if all current events are
319 handled.
320 -t, --timeout=SECONDS
322 Maximum number of seconds to wait for the event queue to become
323 empty. The default value is 120 seconds. A value of 0 will check if
324 the queue is empty and always return immediately. A non-zero value
325 will return an exit code of 0 if queue became empty before timeout
326 was reached, non-zero otherwise.
327 -E, --exit-if-exists=FILE
329 Stop waiting if file exists.
330 -h, --help
332 Print a short help text and exit.
333 See systemd-udev-settle.service(8) for more information.
335 udevadm control option
337 Modify the internal state of the running udev daemon.
338 -e, --exit
340 Signal and wait for systemd-udevd to exit. No option except for
341 --timeout can be specified after this option. Note that
342 systemd-udevd.service contains Restart=always and so as a result,
343 this option restarts systemd-udevd. If you want to stop
344 systemd-udevd.service, please use the following:
345 systemctl stop systemd-udevd-control.socket systemd-udevd-kernel.socket systemd-udevd.service
347 -l, --log-level=value
350 Set the internal log level of systemd-udevd. Valid values are the
351 numerical syslog priorities or their textual representations:
352 emerg, alert, crit, err, warning, notice, info, and debug.
353 -s, --stop-exec-queue
355 Signal systemd-udevd to stop executing new events. Incoming events
356 will be queued.
357 -S, --start-exec-queue
359 Signal systemd-udevd to enable the execution of events.
360 -R, --reload
362 Signal systemd-udevd to reload the rules files and other databases
363 like the kernel module index. Reloading rules and databases does
364 not apply any changes to already existing devices; the new
365 configuration will only be applied to new events.
366 -p, --property=KEY=value
368 Set a global property for all events.
369 -m, --children-max=value
371 Set the maximum number of events, systemd-udevd will handle at the
372 same time.
373 --ping
375 Send a ping message to systemd-udevd and wait for the reply. This
376 may be useful to check that systemd-udevd daemon is running.
377 -t, --timeout=seconds
379 The maximum number of seconds to wait for a reply from
380 systemd-udevd.
381 -h, --help
383 Print a short help text and exit.
384 udevadm monitor [options]
386 Listens to the kernel uevents and events sent out by a udev rule and
387 prints the devpath of the event to the console. It can be used to
388 analyze the event timing, by comparing the timestamps of the kernel
389 uevent and the udev event.
390 -k, --kernel
392 Print the kernel uevents.
393 -u, --udev
395 Print the udev event after the rule processing.
396 -p, --property
398 Also print the properties of the event.
399 -s, --subsystem-match=string[/string]
401 Filter kernel uevents and udev events by subsystem[/devtype]. Only
402 events with a matching subsystem value will pass. When this option
403 is specified more than once, then each matching result is ORed,
404 that is, all devices in the specified subsystems are monitored.
405 -t, --tag-match=string
407 Filter udev events by tag. Only udev events with a given tag
408 attached will pass. When this option is specified more than once,
409 then each matching result is ORed, that is, devices which have one
410 of the specified tags are monitored.
411 -h, --help
413 Print a short help text and exit.
414 udevadm test [options] [devpath|file|unit]
416 Simulate a udev event run for the given device, and print debug output.
417 -a, --action=ACTION
419 Type of event to be simulated. Possible actions are "add",
420 "remove", "change", "move", "online", "offline", "bind", and
421 "unbind". Also, the special value "help" can be used to list the
422 possible actions. The default value is "add".
423 -N, --resolve-names=early|late|never
425 Specify when udevadm should resolve names of users and groups. When
426 set to early (the default), names will be resolved when the rules
427 are parsed. When set to late, names will be resolved for every
428 event. When set to never, names will never be resolved and all
429 devices will be owned by root.
430 -h, --help
432 Print a short help text and exit.
433 udevadm test-builtin [options] [command] [devpath|file|unit]
435 Run a built-in command COMMAND for device DEVPATH, and print debug
436 output.
437 -a, --action=ACTION
439 Type of event to be simulated. Possible actions are "add",
440 "remove", "change", "move", "online", "offline", "bind", and
441 "unbind". Also, the special value "help" can be used to list the
442 possible actions. The default value is "add".
443 -h, --help
445 Print a short help text and exit.
446 --version
448 Print a short version string and exit.
449 udevadm verify [options] [file...] ...
451 Verify syntactic, semantic, and stylistic correctness of udev rules
452 files.
453 Positional arguments could be used to specify one or more files to
455 check. If no files are specified, the udev rules are read from the
456 files located in the same udev/rules.d directories that are processed
457 by the udev daemon.
458 The exit status is 0 if all specified udev rules files are
460 syntactically, semantically, and stylistically correct, and a non-zero
461 error code otherwise.
462 -N, --resolve-names=early|never
464 Specify when udevadm should resolve names of users and groups. When
465 set to early (the default), names will be resolved when the rules
466 are parsed. When set to never, names will never be resolved.
467 --root=PATH
469 When looking for udev rules files located in udev/rules.d
470 directories, operate on files underneath the specified root path
471 PATH.
472 --no-summary
474 Do not show summary.
475 --no-style
477 Ignore style issues. When specified, even if style issues are found
478 in udev rules files, the exit status is 0 if no syntactic or
479 semantic errors are found.
480 -h, --help
482 Print a short help text and exit.
483 udevadm wait [options] [device|syspath] ...
485 Wait for devices or device symlinks being created and initialized by
486 systemd-udevd. Each device path must start with "/dev/" or "/sys/",
487 e.g. "/dev/sda", "/dev/disk/by-path/pci-0000:3c:00.0-nvme-1-part1",
488 "/sys/devices/pci0000:00/0000:00:1f.6/net/eth0", or
489 "/sys/class/net/eth0". This can take multiple devices. This may be
490 useful for waiting for devices being processed by systemd-udevd after
491 e.g. partitioning or formatting the devices.
492 -t, --timeout=SECONDS
494 Maximum number of seconds to wait for the specified devices or
495 device symlinks being created, initialized, or removed. The default
496 value is "infinity".
497 --initialized=BOOL
499 Check if systemd-udevd initialized devices. Defaults to true. When
500 false, the command only checks if the specified devices exist. Set
501 false to this setting if there is no udev rules for the specified
502 devices, as the devices will never be considered as initialized in
503 that case. See Initialized Devices section below for more details.
504 --removed
506 When specified, the command wait for devices being removed instead
507 of created or initialized. If this is specified, --initialized=
508 will be ignored.
509 --settle
511 When specified, also watches the udev event queue, and wait for all
512 queued events being processed by systemd-udevd.
513 -h, --help
515 Print a short help text and exit.
516 udevadm lock [options] [command] ...
518 udevadm lock takes an (advisory) exclusive lock on a block device (or
519 all specified devices), as per Locking Block Device Access[1] and
520 invokes a program with the locks taken. When the invoked program exits
521 the locks are automatically released and its return value is propagated
522 as exit code of udevadm lock.
523 This tool is in particular useful to ensure that systemd-
525 udevd.service(8) does not probe a block device while changes are made
526 to it, for example partitions created or file systems formatted. Note
527 that many tools that interface with block devices natively support
528 taking relevant locks, see for example sfdisk(8)'s --lock switch.
529 The command expects at least one block device specified via --device=
531 or --backing=, and a command line to execute as arguments.
532 --device=DEVICE, -d DEVICE
534 Takes a path to a device node of the device to lock. This switch
535 may be used multiple times (and in combination with --backing=) in
536 order to lock multiple devices. If a partition block device node is
537 specified the containing "whole" block device is automatically
538 determined and used for the lock, as per the specification. If
539 multiple devices are specified, they are deduplicated, sorted by
540 the major/minor of their device nodes and then locked in order.
541 This switch must be used at least once, to specify at least one
543 device to lock. (Alternatively, use --backing=, see below.)
544 --backing=PATH, -b PATH
546 If a path to a device node is specified, identical to --device=.
547 However, this switch alternatively accepts a path to a regular file
548 or directory, in which case the block device of the file system the
549 file/directory resides on is automatically determined and used as
550 if it was specified with --device=.
551 --timeout=SECS, -t SECS
553 Specifies how long to wait at most until all locks can be taken.
554 Takes a value in seconds, or in the usual supported time units, see
555 systemd.time(7). If specified as zero the lock is attempted and if
556 not successful the invocation will immediately fail. If passed as
557 "infinity" (the default) the invocation will wait indefinitely
558 until the lock can be acquired. If the lock cannot be taken in the
559 specified time the specified command will not be executed and the
560 invocation will fail.
561 --print, -p
563 Instead of locking the specified devices and executing a command,
564 just print the device paths that would be locked, and execute no
565 command. This command is useful to determine the "whole" block
566 device in case a partition block device is specified. The devices
567 will be sorted by their device node major number as primary
568 ordering key and the minor number as secondary ordering key (i.e.
569 they are shown in the order they'd be locked). Note that the number
570 of lines printed here can be less than the number of --device= and
571 --backing= switches specified in case these resolve to the same
572 "whole" devices.
573 -h, --help
575 Print a short help text and exit.
576
578 Initialized devices are those for which at least one udev rule already
579 completed execution – for any action but "remove" — that set a property
580 or other device setting (and thus has an entry in the udev device
581 database). Devices are no longer considered initialized if a "remove"
582 action is seen for them (which removes their entry in the udev device
583 database). Note that devices that have no udev rules are never
584 considered initialized, but might still be announced via the sd-device
585 API (or similar).
586
588 Example 1. Format a File System
589 Take a lock on the backing block device while creating a file system,
591 to ensure that systemd-udevd doesn't probe or announce the new
592 superblock before it is comprehensively written:
593 # udevadm lock --device=/dev/sda1 mkfs.ext4 /dev/sda1
595 Example 2. Format a RAID File System
597 Similar, but take locks on multiple devices at once:
599 # udevadm lock --device=/dev/sda1 --device=/dev/sdb1 mkfs.btrfs /dev/sda1 /dev/sdb1
601 Example 3. Copy in a File System
603 Take a lock on the backing block device while copying in a prepared
605 file system image, to ensure that systemd-udevd doesn't probe or
606 announce the new superblock before it is fully written:
607 # udevadm lock -d /dev/sda1 dd if=fs.raw of=/dev/sda1
609
611 udev(7), systemd-udevd.service(8)
612
614 1. Locking Block Device Access
615 https://systemd.io/BLOCK_DEVICE_LOCKING
616systemd 254 UDEVADM(8)