1UDEVADM(8)                          udevadm                         UDEVADM(8)
2
3
4

NAME

6       udevadm - udev management tool
7

SYNOPSIS

9       udevadm [--debug] [--version] [--help]
10
11       udevadm info [options] [devpath]
12
13       udevadm trigger [options] [devpath]
14
15       udevadm settle [options]
16
17       udevadm control option
18
19       udevadm monitor [options]
20
21       udevadm test [options] devpath
22
23       udevadm test-builtin [options] command devpath
24
25       udevadm wait [options] device|syspath
26
27       udevadm lock [options] command
28

DESCRIPTION

30       udevadm expects a command and command specific options. It controls the
31       runtime behavior of systemd-udevd, requests kernel events, manages the
32       event queue, and provides simple debugging mechanisms.
33

OPTIONS

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

INITIALIZED DEVICES

536       Initialized devices are those for which at least one udev rule already
537       completed execution – for any action but "remove" — that set a property
538       or other device setting (and thus has an entry in the udev device
539       database). Devices are no longer considered initialized if a "remove"
540       action is seen for them (which removes their entry in the udev device
541       database). Note that devices that have no udev rules are never
542       considered initialized, but might still be announced via the sd-device
543       API (or similar).
544

EXAMPLE

546       Example 1. Format a File System
547
548       Take a lock on the backing block device while creating a file system,
549       to ensure that systemd-udevd doesn't probe or announce the new
550       superblock before it is comprehensively written:
551
552           # udevadm lock --device=/dev/sda1 mkfs.ext4 /dev/sda1
553
554       Example 2. Format a RAID File System
555
556       Similar, but take locks on multiple devices at once:
557
558           # udevadm lock --device=/dev/sda1 --device=/dev/sdb1 mkfs.btrfs /dev/sda1 /dev/sdb1
559
560       Example 3. Copy in a File System
561
562       Take a lock on the backing block device while copying in a prepared
563       file system image, to ensure that systemd-udevd doesn't probe or
564       announce the new superblock before it is fully written:
565
566           # udevadm lock -d /dev/sda1 dd if=fs.raw of=/dev/sda1
567

SEE ALSO

569       udev(7), systemd-udevd.service(8)
570

NOTES

572        1. Locking Block Device Access
573           https://systemd.io/BLOCK_DEVICE_LOCKING
574
575
576
577systemd 251                                                         UDEVADM(8)
Impressum