udevadm - Man Page

Query the udev database for device information​.

Positional arguments should be used to specify one or more devices​. Each one may be a device name (in which case it must start with /dev/), a sys path (in which case it must start with /sys/), a device ID (such as "n1", "c5:1", or "b259:1", see sd_device_get_device_id(3))​. or a systemd device unit name (in which case it must end with "​.device", see systemd.device(5))​.

-q, --query=TYPE

Query the database for the specified type of device data​. Valid TYPEs are: name, symlink, path, property, all​.

--property=NAME

When showing device properties using the --query=property option, limit display to properties specified in the argument​. The argument should be a comma-separated list of property names​. If not specified, all known properties are shown​.

Added in version 250​.

--value

When showing device properties using the --query=property option, print only their values, and skip the property name and "="​.

When showing device symlinks using the --query=symlink option, print one path per line instead of separating paths with spaces​. An empty line is printed after each device, including the last one​.

Cannot be used together with -x/--export or -P/--export-prefix​.

Added in version 250​.

-p, --path=DEVPATH

The /sys/ path of the device to query, e​.g​. [/sys/]/class/block/sda​. This option is an alternative to the positional argument with a /sys/ prefix​. udevadm info --path=/class/block/sda is equivalent to udevadm info /sys/class/block/sda​.

-n, --name=FILE

The name of the device node or a symlink to query, e​.g​. [/dev/]/sda​. This option is an alternative to the positional argument with a /dev/ prefix​. udevadm info --name=sda is equivalent to udevadm info /dev/sda​.

-r, --root

Print absolute paths in name or symlink query​.

-a, --attribute-walk

Print all sysfs properties of the specified device that can be used in udev rules to match the specified device​. It prints all devices along the chain, up to the root of sysfs that can be used in udev rules​.

This switch supports JSON output mode (see --json= below)​. Note that because this switch generates multiple JSON objects, JSON-SEQ mode is automatically enabled (RFC7464)​. (Note: tools such as jq​^[1] natively support JSON-SEQ via the --seq switch​.)

-t, --tree

Display a sysfs tree​. This recursively iterates through the sysfs hierarchy and displays it in a tree structure​. If a path is specified only the subtree below and its parent directories are shown​. This will show both device and subsystem items​.

Added in version 251​.

-x, --export

Print output as key/value pairs​. Values are enclosed in single quotes​. This takes effects only when --query=property or --device-id-of-file=FILE is specified​.

-P, --export-prefix=NAME

Add a prefix to the key name of exported values​. This implies --export​.

-d, --device-id-of-file=FILE

Print major/minor numbers of the underlying device, where the file lives on​. If this is specified, no positional arguments are accepted​.

-e, --export-db

Export the content of the udev database​.

-c, --cleanup-db

Cleanup the udev database​.

-w[SECONDS], --wait-for-initialization[=SECONDS]

Wait for device to be initialized​. If argument SECONDS is not specified, the default is to wait forever​.

Added in version 243​.

--subsystem-match[=SUBSYSTEM], --subsystem-nomatch[=SUBSYSTEM]

When used with --export-db, only show devices of or not of the given subsystem respectively​.

Added in version 255​.

--attr-match[=FILE[=VALUE]], --attr-nomatch[=FILE[=VALUE]]

When used with --export-db, only show devices matching or not matching the given attribute respectively​.

Added in version 255​.

--property-match[=KEY=VALUE]

When used with --export-db, only show devices matching the given property and value​.

Added in version 255​.

--tag-match[=TAG]

When used with --export-db, only show devices with the given tag​.

Added in version 255​.

--sysname-match[=NAME]

When used with --export-db, only show devices with the given "/sys" path​.

Added in version 255​.

--name-match[=NAME]

When used with --export-db, only show devices with the given name in "/dev"​.

Added in version 255​.

--parent-match[=NAME]

When used with --export-db, only show devices with the given parent device​.

Added in version 255​.

--initialized-match, --initialized-nomatch

When used with --export-db, only show devices that are initialized or not initialized respectively​.

Added in version 255​.

--json=MODE

Shows output formatted as JSON​. Expects one of "short" (for the shortest possible output without any redundant whitespace or line breaks), "pretty" (for a pretty version of the same, with indentation and line breaks) or "off" (to turn off JSON output, the default)​.

--no-pager

Do not pipe output into a pager​.

The generated output shows the current device database entry in a terse format​. Each line shown is prefixed with one of the following characters:

Table ​1. ​udevadm info output prefixes

Request device events from the kernel​. Primarily used to replay events at system coldplug time​.

Takes device specifications as positional arguments​. See the description of udevadm info above​.

-v,  --verbose

Print the list of devices which will be triggered​.

-n,  --dry-run

Do not actually trigger the event​.

-q,  --quiet

Suppress error logging in triggering events​.

Added in version 248​.

-t,  --type=TYPE

Trigger a specific type of devices​. Valid types are "all", "devices", and "subsystems"​. The default value is "devices"​.

-c,  --action=ACTION

Type of event to be triggered​. Possible actions are "add", "remove", "change", "move", "online", "offline", "bind", and "unbind"​. Also, the special value "help" can be used to list the possible actions​. The default value is "change"​.

--prioritized-subsystem=SUBSYSTEM[,SUBSYSTEM​...]

Takes a comma separated list of subsystems​. When triggering events for devices, the devices from the specified subsystems and their parents are triggered first​. For example, if --prioritized-subsystem=block,net, then firstly all block devices and their parents are triggered, in the next all network devices and their parents are triggered, and lastly the other devices are triggered​. This option can be specified multiple times, and in that case the lists of the subsystems will be merged​. That is, --prioritized-subsystem=block --prioritized-subsystem=net is equivalent to --prioritized-subsystem=block,net​.

Added in version 251​.

-s,  --subsystem-match=SUBSYSTEM

Trigger events for devices which belong to a matching subsystem​. This option supports shell style pattern matching​. When this option is specified more than once, then each matching result is ORed, that is, all the devices in each subsystem are triggered​.

-S,  --subsystem-nomatch=SUBSYSTEM

Do not trigger events for devices which belong to a matching subsystem​. This option supports shell style pattern matching​. When this option is specified more than once, then each matching result is ANDed, that is, devices which do not match all specified subsystems are triggered​.

-a,  --attr-match=ATTRIBUTE=VALUE

Trigger events for devices with a matching sysfs attribute​. If a value is specified along with the attribute name, the content of the attribute is matched against the given value using shell style pattern matching​. If no value is specified, the existence of the sysfs attribute is checked​. When this option is specified multiple times, then each matching result is ANDed, that is, only devices which have all specified attributes are triggered​.

-A,  --attr-nomatch=ATTRIBUTE=VALUE

Do not trigger events for devices with a matching sysfs attribute​. If a value is specified along with the attribute name, the content of the attribute is matched against the given value using shell style pattern matching​. If no value is specified, the existence of the sysfs attribute is checked​. When this option is specified multiple times, then each matching result is ANDed, that is, only devices which have none of the specified attributes are triggered​.

-p,  --property-match=PROPERTY=VALUE

Trigger events for devices with a matching property value​. This option supports shell style pattern matching​. When this option is specified more than once, then each matching result is ORed, that is, devices which have one of the specified properties are triggered​.

-g,  --tag-match=TAG

Trigger events for devices with a matching tag​. When this option is specified multiple times, then each matching result is ANDed, that is, devices which have all specified tags are triggered​.

-y,  --sysname-match=NAME

Trigger events for devices for which the last component (i​.e​. the filename) of the /sys/ path matches the specified PATH​. This option supports shell style pattern matching​. When this option is specified more than once, then each matching result is ORed, that is, all devices which have any of the specified NAME are triggered​.

--name-match=NAME

Trigger events for devices with a matching device path​. When this option is specified more than once, then each matching result is ORed, that is, all specified devices are triggered​.

Added in version 218​.

-b,  --parent-match=SYSPATH

Trigger events for all children of a given device​. When this option is specified more than once, then each matching result is ORed, that is, all children of each specified device are triggered​.

--initialized-match,  --initialized-nomatch

When --initialized-match is specified, trigger events for devices that are already initialized by systemd-udevd, and skip devices that are not initialized yet​.

When --initialized-nomatch is specified, trigger events for devices that are not initialized by systemd-udevd yet, and skip devices that are already initialized​.

Typically, it is essential that applications which intend to use such a match, make sure a suitable udev rule is installed that sets at least one property on devices that shall be matched​. See also Initialized Devices section below for more details​.

Warning
--initialized-nomatch can potentially save a significant amount of time compared to re-triggering all devices in the system and e​.g​. can be used to optimize boot time​. However, this is not safe to be used in a boot sequence in general​. Especially, when udev rules for a device depend on its parent devices (e​.g​. "ATTRS" or "IMPORT{parent}" keys, see udev(7) for more details), the final state of the device becomes easily unstable with this option​.

Added in version 251​.

--include-parents

Trigger parent devices of found devices even if the parents will not match the filter condition​. This is useful if we are interested to limit the coldplug activities to some devices or subsystems​.

Added in version 258​.

-w,  --settle

Apart from triggering events, also waits for those events to finish​. Note that this is different from calling udevadm settle​. udevadm settle waits for all events to finish​. This option only waits for events triggered by the same command to finish​.

Added in version 238​.

--uuid

Trigger the synthetic device events, and associate a randomized UUID with each​. These UUIDs are printed to standard output, one line for each event​. These UUIDs are included in the uevent environment block (in the "SYNTH_UUID=" property) and may be used to track delivery of the generated events​.

Added in version 249​.

--wait-daemon[=SECONDS]

Before triggering uevents, wait for systemd-udevd daemon to be initialized​. Optionally takes timeout value​. Default timeout is 5 seconds​. This is equivalent to invoking udevadm control --ping before udevadm trigger​.

Added in version 241​.

In addition, optional positional arguments can be used to specify device names or sys paths​. They must start with /dev/ or /sys/ respectively​.

Watches the udev event queue, and exits if all current events are handled​.

-t, --timeout=SECONDS

Maximum number of seconds to wait for the event queue to become empty​. The default value is 120 seconds​. A value of 0 will check if the queue is empty and always return immediately​. A non-zero value will return an exit code of 0 if queue became empty before timeout was reached, non-zero otherwise​.

-E, --exit-if-exists=FILE

Stop waiting if file exists​.

See systemd-udev-settle.service(8) for more information​.

Modify the internal state of the running udev daemon​.

-e, --exit

Signal and wait for systemd-udevd to exit​. No option except for --timeout can be specified after this option​. Note that systemd-udevd​.service contains Restart=always and so as a result, this option restarts systemd-udevd​. If you want to stop systemd-udevd​.service, please use the following:

systemctl stop systemd-udevd-kernel​.socket systemd-udevd-varlink​.socket systemd-udevd​.service

-l, --log-level=value

Set the internal log level of systemd-udevd​. Valid values are the numerical syslog priorities or their textual representations: emerg, alert, crit, err, warning, notice, info, and debug​.

-s, --stop-exec-queue

Signal systemd-udevd to stop executing new events​. Incoming events will be queued​.

-S, --start-exec-queue

Signal systemd-udevd to enable the execution of events​.

-R, --reload

Signal systemd-udevd to reload the rules files and other databases like the kernel module index​. Reloading rules and databases does not apply any changes to already existing devices; the new configuration will only be applied to new events​.

-p, --property=KEY=value

Set a global property for all events​.

-m, --children-max=value

Set the maximum number of events, systemd-udevd will handle at the same time​. When 0 is specified, then the maximum is determined based on the system resources​.

--ping

Send a ping message to systemd-udevd and wait for the reply​. This may be useful to check that systemd-udevd daemon is running​.

Added in version 241​.

--trace=BOOL

Enable/disable trace logging in systemd-udevd​.

Added in version 258​.

--revert

Revert settings previously set with udevadm control command​. When specified, settings set with -l/--log-level=, --trace, -m/--children-max=, and -p/--property= will be cleared​.

Added in version 258​.

-t, --timeout=seconds

The maximum number of seconds to wait for a reply from systemd-udevd​.

--load-credentials

When specified, the following credentials are used when passed in:

udev​.conf​.*

These credentials should contain valid udev.conf(5) configuration data​. From each matching credential a separate file is created​. Example: a passed credential udev​.conf​.50-foobar will be copied into a configuration file /run/udev/udev​.conf​.d/50-foobar​.conf​.

Added in version 256​.

udev​.rules​.*

These credentials should contain valid udev(7) rules​. From each matching credential a separate file is created​. Example: a passed credential udev​.rules​.50-foobar will be copied into a configuration file /run/udev/rules​.d/50-foobar​.rules​.

Added in version 256​.

Note, this does not imply --reload option​. So, if systemd-udevd is already running, please consider to also specify -reload to make the copied udev rules files used by systemd-udevd​.

Added in version 256​.

Listens to the kernel uevents and events sent out by a udev rule and prints the devpath of the event to the console​. It can be used to analyze the event timing, by comparing the timestamps of the kernel uevent and the udev event​.

-k, --kernel

Print the kernel uevents​.

-u, --udev

Print the udev event after the rule processing​.

-p, --property

Also print the properties of the event​.

-s, --subsystem-match=string[/string]

Filter kernel uevents and udev events by subsystem[/devtype]​. Only events with a matching subsystem value will pass​. When this option is specified more than once, then each matching result is ORed, that is, all devices in the specified subsystems are monitored​.

-t, --tag-match=string

Filter udev events by tag​. Only udev events with a given tag attached will pass​. When this option is specified more than once, then each matching result is ORed, that is, devices which have one of the specified tags are monitored​.

Simulate a udev event run for the given device, and print debug output​. The option --json= may be useful for parsing the final result​. See also Example section​.

-a, --action=ACTION

Type of event to be simulated​. Possible actions are "add", "remove", "change", "move", "online", "offline", "bind", and "unbind"​. Also, the special value "help" can be used to list the possible actions​. The default value is "add"​.

-N, --resolve-names=early|late|never

Specify when udevadm should resolve names of users and groups specified in udev rules​. When set to early (the default), names will be resolved when the rules are parsed​. When set to late, names will be resolved during the event being processed​. When set to never, names will never be resolved and relevant udev rules will be ignored​.

Added in version 209​.

-D DIR, --extra-rules-dir=DIR

Also load udev rules files from the specified directory​. This option can be specified multiple times​. It may be useful for debugging udev rules by copying some udev rules files to a temporary directory, editing them, and specifying the directory with this option​. Files found in the specified directories have a higher priority than rules files in the default udev/rules​.d directories used by systemd-udevd​. See udev(7) for more details about the search paths​.

Added in version 258​.

-v, --verbose

Shows verbose logs in processing udev rules​.

Added in version 258​.

--json=MODE

Shows output formatted as JSON​. Expects one of "short" (for the shortest possible output without any redundant whitespace or line breaks), "pretty" (for a pretty version of the same, with indentation and line breaks) or "off" (to turn off JSON output, the default)​.

Run a built-in command COMMAND for device DEVPATH, and print debug output​.

-a, --action=ACTION

Type of event to be simulated​. Possible actions are "add", "remove", "change", "move", "online", "offline", "bind", and "unbind"​. Also, the special value "help" can be used to list the possible actions​. The default value is "add"​.

Added in version 250​.

Verify syntactic, semantic, and stylistic correctness of udev rules files​.

Positional arguments can be used to specify one or more files to check​. Each argument must be an absolute path to a udev rules file or a directory that contains rules files, or a file name of udev rules file (e​.g​. 99-systemd​.rules)​. If a file name is specified, the file will be searched in the udev/rules​.d directories that are processed by systemd-udevd, and searched in the current working directory if not found​. If no files are specified, the udev rules are read from the files located in the same udev/rules​.d directories that are processed by systemd-udevd​. See udev(7) for more details about the search paths​.

The exit status is 0 if all specified udev rules files are syntactically, semantically, and stylistically correct, and a non-zero error code otherwise​.

-N, --resolve-names=early|late|never

Specify when udevadm should resolve names of users and groups specified in udev rules​. When set to early (the default), names will be resolved when the rules are parsed​. When set to late, names will not be verified, as systemd-udevd resolves names during each event being processed​. When set to never, names will never be resolved and relevant rules will be ignored​.

Added in version 254​.

--root=PATH

When looking for udev rules files located in the udev/rules​.d directories, operate on files underneath the specified root path PATH​. When a file name is specified, and it is not found in the udev/rules​.d directories, the file will be searched in the specified root path PATH, rather than the current working directory​.

Added in version 254​.

--no-summary

Do not show summary​.

Added in version 254​.

--no-style

Ignore style issues​. When specified, even if style issues are found in udev rules files, the exit status is 0 if no syntactic or semantic errors are found​.

Added in version 254​.

Show udev rules files or udev​.conf​.

Positional arguments can be used to specify one or more files to show​. Each argument must be an absolute path to a udev rules file or a directory that contains rules files, or a file name of udev rules file (e​.g​. 99-systemd​.rules)​. If a file name is specified, the file will be searched in the udev/rules​.d directories that are processed by systemd-udevd, and searched in the current working directory if not found​. If no files are specified, the udev rules are read from the files located in the same udev/rules​.d directories that are processed by systemd-udevd​. See udev(7) for more details about the search paths​.

--root=PATH

When looking for udev rules files located in the udev/rules​.d directories, operate on files underneath the specified root path PATH​. When a file name is specified, and it is not found in the udev/rules​.d directories, the file will be searched in the specified root path PATH, rather than the current working directory​.

Added in version 258​.

--tldr

Only print the "interesting" parts of the configuration files, skipping comments and empty lines and section headers followed only by comments and empty lines​.

Added in version 258​.

--config

Shows udev.conf(5) files, rather than udev rules files​. When specified, no udev rules file cannot be specified​.

Added in version 258​.

Wait for devices or device symlinks being created and initialized by systemd-udevd​. Each device path must start with "/dev/" or "/sys/", e​.g​. "/dev/sda", "/dev/disk/by-path/pci-0000:3c:00​.0-nvme-1-part1", "/sys/devices/pci0000:00/0000:00:1f​.6/net/eth0", or "/sys/class/net/eth0"​. This can take multiple devices​. This may be useful for waiting for devices being processed by systemd-udevd after e​.g​. partitioning or formatting the devices​.

-t, --timeout=SECONDS

Maximum number of seconds to wait for the specified devices or device symlinks being created, initialized, or removed​. The default value is "infinity"​.

Added in version 251​.

--initialized=BOOL

Check if systemd-udevd initialized devices​. Defaults to true​. When false, the command only checks if the specified devices exist​. Set false to this setting if there is no udev rules for the specified devices, as the devices will never be considered as initialized in that case​. See Initialized Devices section below for more details​.

Added in version 251​.

--removed

When specified, the command wait for devices being removed instead of created or initialized​. If this is specified, --initialized= will be ignored​.

Added in version 251​.

--settle

When specified, also watches the udev event queue, and wait for all queued events being processed by systemd-udevd​.

Added in version 251​.

udevadm lock takes an (advisory) exclusive lock on a block device (or all specified devices), as per Locking Block Device Access​^[2] and invokes a program with the locks taken​. When the invoked program exits the locks are automatically released and its return value is propagated as exit code of udevadm lock​.

This tool is in particular useful to ensure that systemd-udevd.service(8) does not probe a block device while changes are made to it, for example partitions created or file systems formatted​. Note that many tools that interface with block devices natively support taking relevant locks, see for example sfdisk(8)'s --lock switch​.

The command expects at least one block device specified via --device= or --backing=, and a command line to execute as arguments​.

--device=DEVICE, -d DEVICE

Takes a path to a device node of the device to lock​. This switch may be used multiple times (and in combination with --backing=) in order to lock multiple devices​. If a partition block device node is specified the containing "whole" block device is automatically determined and used for the lock, as per the specification​. If multiple devices are specified, they are deduplicated, sorted by the major/minor of their device nodes and then locked in order​.

This switch must be used at least once, to specify at least one device to lock​. (Alternatively, use --backing=, see below​.)

Added in version 251​.

--backing=PATH, -b PATH

If a path to a device node is specified, identical to --device=​. However, this switch alternatively accepts a path to a regular file or directory, in which case the block device of the file system the file/directory resides on is automatically determined and used as if it was specified with --device=​.

Added in version 251​.

--timeout=SECS, -t SECS

Specifies how long to wait at most until all locks can be taken​. Takes a value in seconds, or in the usual supported time units, see systemd.time(7)​. If specified as zero the lock is attempted and if not successful the invocation will immediately fail​. If passed as "infinity" (the default) the invocation will wait indefinitely until the lock can be acquired​. If the lock cannot be taken in the specified time the specified command will not be executed and the invocation will fail​.

Added in version 251​.

--print, -p

Instead of locking the specified devices and executing a command, just print the device paths that would be locked, and execute no command​. This command is useful to determine the "whole" block device in case a partition block device is specified​. The devices will be sorted by their device node major number as primary ordering key and the minor number as secondary ordering key (i​.e​. they are shown in the order they'd be locked)​. Note that the number of lines printed here can be less than the number of --device= and --backing= switches specified in case these resolve to the same "whole" devices​.

Added in version 251​.