path: root/upstream/fedora-rawhide/man8/udevadm.8

'\" t
.TH "UDEVADM" "8" "" "systemd 256~rc3" "udevadm"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
udevadm \- udev management tool
.SH "SYNOPSIS"
.HP \w'\fBudevadm\fR\ 'u
\fBudevadm\fR [\fB\-\-debug\fR] [\fB\-\-version\fR] [\fB\-\-help\fR]
.HP \w'\fBudevadm\ info\ \fR\fB[options]\fR\fB\ \fR\fB[devpath]\fR\ 'u
\fBudevadm info \fR\fB[options]\fR\fB \fR\fB[devpath]\fR
.HP \w'\fBudevadm\ trigger\ \fR\fB[options]\fR\fB\ \fR\fB[devpath]\fR\ 'u
\fBudevadm trigger \fR\fB[options]\fR\fB \fR\fB[devpath]\fR
.HP \w'\fBudevadm\ settle\ \fR\fB[options]\fR\ 'u
\fBudevadm settle \fR\fB[options]\fR
.HP \w'\fBudevadm\ control\ \fR\fB\fIoption\fR\fR\ 'u
\fBudevadm control \fR\fB\fIoption\fR\fR
.HP \w'\fBudevadm\ monitor\ \fR\fB[options]\fR\ 'u
\fBudevadm monitor \fR\fB[options]\fR
.HP \w'\fBudevadm\ test\ \fR\fB[options]\fR\fB\ \fR\fB\fIdevpath\fR\fR\ 'u
\fBudevadm test \fR\fB[options]\fR\fB \fR\fB\fIdevpath\fR\fR
.HP \w'\fBudevadm\ test\-builtin\ \fR\fB[options]\fR\fB\ \fR\fB\fIcommand\fR\fR\fB\ \fR\fB\fIdevpath\fR\fR\ 'u
\fBudevadm test\-builtin \fR\fB[options]\fR\fB \fR\fB\fIcommand\fR\fR\fB \fR\fB\fIdevpath\fR\fR
.HP \w'\fBudevadm\ verify\fR\ 'u
\fBudevadm verify\fR [options...] [\fIfile\fR...]
.HP \w'\fBudevadm\ wait\ \fR\fB[options]\fR\fB\ \fR\fB\fIdevice|syspath\fR\fR\ 'u
\fBudevadm wait \fR\fB[options]\fR\fB \fR\fB\fIdevice|syspath\fR\fR
.HP \w'\fBudevadm\ lock\ \fR\fB[options]\fR\fB\ \fR\fB\fIcommand\fR\fR\ 'u
\fBudevadm lock \fR\fB[options]\fR\fB \fR\fB\fIcommand\fR\fR
.SH "DESCRIPTION"
.PP
\fBudevadm\fR
expects a command and command specific options\&. It controls the runtime behavior of
\fBsystemd\-udevd\fR, requests kernel events, manages the event queue, and provides simple debugging mechanisms\&.
.SH "OPTIONS"
.PP
\fB\-d\fR, \fB\-\-debug\fR
.RS 4
Print debug messages to standard error\&. This option is implied in
\fBudevadm test\fR
and
\fBudevadm test\-builtin\fR
commands\&.
.RE
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Print a short help text and exit\&.
.RE
.SS "udevadm info [\fIoptions\fR] [\fIdevpath\fR|\fIfile\fR|\fIunit\fR]"
.PP
Query the udev database for device information\&.
.PP
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/), or a systemd device unit name (in which case it must end with
"\&.device", see
\fBsystemd.device\fR(5))\&.
.PP
\fB\-q\fR, \fB\-\-query=\fR\fB\fITYPE\fR\fR
.RS 4
Query the database for the specified type of device data\&. Valid
\fITYPE\fRs are:
\fBname\fR,
\fBsymlink\fR,
\fBpath\fR,
\fBproperty\fR,
\fBall\fR\&.
.RE
.PP
\fB\-\-property=\fR\fB\fINAME\fR\fR
.RS 4
When showing device properties using the
\fB\-\-query=property\fR
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\&.
.sp
Added in version 250\&.
.RE
.PP
\fB\-\-value\fR
.RS 4
When showing device properties using the
\fB\-\-query=property\fR
option, print only their values, and skip the property name and
"="\&.
.sp
Cannot be used together with
\fB\-x/\-\-export\fR
or
\fB\-P/\-\-export\-prefix\fR\&.
.sp
Added in version 250\&.
.RE
.PP
\fB\-p\fR, \fB\-\-path=\fR\fB\fIDEVPATH\fR\fR
.RS 4
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\&.
\fBudevadm info \-\-path=/class/block/sda\fR
is equivalent to
\fBudevadm info /sys/class/block/sda\fR\&.
.RE
.PP
\fB\-n\fR, \fB\-\-name=\fR\fB\fIFILE\fR\fR
.RS 4
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\&.
\fBudevadm info \-\-name=sda\fR
is equivalent to
\fBudevadm info /dev/sda\fR\&.
.RE
.PP
\fB\-r\fR, \fB\-\-root\fR
.RS 4
Print absolute paths in
\fBname\fR
or
\fBsymlink\fR
query\&.
.RE
.PP
\fB\-a\fR, \fB\-\-attribute\-walk\fR
.RS 4
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\&.
.RE
.PP
\fB\-t\fR, \fB\-\-tree\fR
.RS 4
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\&.
.sp
Added in version 251\&.
.RE
.PP
\fB\-x\fR, \fB\-\-export\fR
.RS 4
Print output as key/value pairs\&. Values are enclosed in single quotes\&. This takes effects only when
\fB\-\-query=property\fR
or
\fB\-\-device\-id\-of\-file=\fR\fB\fIFILE\fR\fR
is specified\&.
.RE
.PP
\fB\-P\fR, \fB\-\-export\-prefix=\fR\fB\fINAME\fR\fR
.RS 4
Add a prefix to the key name of exported values\&. This implies
\fB\-\-export\fR\&.
.RE
.PP
\fB\-d\fR, \fB\-\-device\-id\-of\-file=\fR\fB\fIFILE\fR\fR
.RS 4
Print major/minor numbers of the underlying device, where the file lives on\&. If this is specified, all positional arguments are ignored\&.
.RE
.PP
\fB\-e\fR, \fB\-\-export\-db\fR
.RS 4
Export the content of the udev database\&.
.RE
.PP
\fB\-c\fR, \fB\-\-cleanup\-db\fR
.RS 4
Cleanup the udev database\&.
.RE
.PP
\fB\-w\fR\fB[SECONDS]\fR, \fB\-\-wait\-for\-initialization\fR\fB[=SECONDS]\fR
.RS 4
Wait for device to be initialized\&. If argument
\fISECONDS\fR
is not specified, the default is to wait forever\&.
.sp
Added in version 243\&.
.RE
.PP
\fB\-\-subsystem\-match\fR\fB[=SUBSYSTEM]\fR, \fB\-\-subsystem\-nomatch\fR\fB[=SUBSYSTEM]\fR
.RS 4
When used with
\fB\-\-export\-db\fR, only show devices of or not of the given subsystem respectively\&.
.sp
Added in version 255\&.
.RE
.PP
\fB\-\-attr\-match\fR\fB[=FILE[=VALUE]]\fR, \fB\-\-attr\-nomatch\fR\fB[=FILE[=VALUE]]\fR
.RS 4
When used with
\fB\-\-export\-db\fR, only show devices matching or not matching the given attribute respectively\&.
.sp
Added in version 255\&.
.RE
.PP
\fB\-\-property\-match\fR\fB[=KEY=VALUE]\fR
.RS 4
When used with
\fB\-\-export\-db\fR, only show devices matching the given property and value\&.
.sp
Added in version 255\&.
.RE
.PP
\fB\-\-tag\-match\fR\fB[=TAG]\fR
.RS 4
When used with
\fB\-\-export\-db\fR, only show devices with the given tag\&.
.sp
Added in version 255\&.
.RE
.PP
\fB\-\-sysname\-match\fR\fB[=NAME]\fR
.RS 4
When used with
\fB\-\-export\-db\fR, only show devices with the given
"/sys"
path\&.
.sp
Added in version 255\&.
.RE
.PP
\fB\-\-name\-match\fR\fB[=NAME]\fR
.RS 4
When used with
\fB\-\-export\-db\fR, only show devices with the given name in
"/dev"\&.
.sp
Added in version 255\&.
.RE
.PP
\fB\-\-parent\-match\fR\fB[=NAME]\fR
.RS 4
When used with
\fB\-\-export\-db\fR, only show devices with the given parent device\&.
.sp
Added in version 255\&.
.RE
.PP
\fB\-\-initialized\-match\fR, \fB\-\-initialized\-nomatch\fR
.RS 4
When used with
\fB\-\-export\-db\fR, only show devices that are initialized or not initialized respectively\&.
.sp
Added in version 255\&.
.RE
.PP
\fB\-\-json=\fR\fB\fIMODE\fR\fR
.RS 4
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)\&.
.RE
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Print a short help text and exit\&.
.RE
.PP
\fB\-\-no\-pager\fR
.RS 4
Do not pipe output into a pager\&.
.RE
.PP
The generated output shows the current device database entry in a terse format\&. Each line shown is prefixed with one of the following characters:
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.B Table\ \&1.\ \&udevadm info output prefixes
.TS
allbox tab(:);
lB lB.
T{
Prefix
T}:T{
Meaning
T}
.T&
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l.
T{
"P:"
T}:T{
Device path in /sys/
T}
T{
"M:"
T}:T{
Device name in /sys/ (i\&.e\&. the last component of "P:")
T}
T{
"R:"
T}:T{
Device number in /sys/ (i\&.e\&. the numeric suffix of the last component of "P:")
T}
T{
"U:"
T}:T{
Kernel subsystem
T}
T{
"T:"
T}:T{
Kernel device type within subsystem
T}
T{
"D:"
T}:T{
Kernel device node major/minor
T}
T{
"I:"
T}:T{
Network interface index
T}
T{
"N:"
T}:T{
Kernel device node name
T}
T{
"L:"
T}:T{
Device node symlink priority
T}
T{
"S:"
T}:T{
Device node symlink
T}
T{
"Q:"
T}:T{
Block device sequence number (DISKSEQ)
T}
T{
"V:"
T}:T{
Attached driver
T}
T{
"E:"
T}:T{
Device property
T}
.TE
.sp 1
.SS "udevadm trigger [\fIoptions\fR] [\fIdevpath\fR|\fIfile\fR|\fIunit\fR]"
.PP
Request device events from the kernel\&. Primarily used to replay events at system coldplug time\&.
.PP
Takes device specifications as positional arguments\&. See the description of
\fBinfo\fR
above\&.
.PP
\fB\-v\fR, \fB\-\-verbose\fR
.RS 4
Print the list of devices which will be triggered\&.
.RE
.PP
\fB\-n\fR, \fB\-\-dry\-run\fR
.RS 4
Do not actually trigger the event\&.
.RE
.PP
\fB\-q\fR, \fB\-\-quiet\fR
.RS 4
Suppress error logging in triggering events\&.
.sp
Added in version 248\&.
.RE
.PP
\fB\-t\fR, \fB\-\-type=\fR\fB\fITYPE\fR\fR
.RS 4
Trigger a specific type of devices\&. Valid types are
"all",
"devices", and
"subsystems"\&. The default value is
"devices"\&.
.RE
.PP
\fB\-c\fR, \fB\-\-action=\fR\fB\fIACTION\fR\fR
.RS 4
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"\&.
.RE
.PP
\fB\-\-prioritized\-subsystem=\fR\fB\fISUBSYSTEM\fR\fI[,\fISUBSYSTEM\fR\&...]\fR\fR
.RS 4
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
\fB\-\-prioritized\-subsystem=block,net\fR, 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,
\fB\-\-prioritized\-subsystem=block \-\-prioritized\-subsystem=net\fR
is equivalent to
\fB\-\-prioritized\-subsystem=block,net\fR\&.
.sp
Added in version 251\&.
.RE
.PP
\fB\-s\fR, \fB\-\-subsystem\-match=\fR\fB\fISUBSYSTEM\fR\fR
.RS 4
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\&.
.RE
.PP
\fB\-S\fR, \fB\-\-subsystem\-nomatch=\fR\fB\fISUBSYSTEM\fR\fR
.RS 4
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\&.
.RE
.PP
\fB\-a\fR, \fB\-\-attr\-match=\fR\fB\fIATTRIBUTE\fR\fR\fB=\fR\fB\fIVALUE\fR\fR
.RS 4
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\&.
.RE
.PP
\fB\-A\fR, \fB\-\-attr\-nomatch=\fR\fB\fIATTRIBUTE\fR\fR\fB=\fR\fB\fIVALUE\fR\fR
.RS 4
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\&.
.RE
.PP
\fB\-p\fR, \fB\-\-property\-match=\fR\fB\fIPROPERTY\fR\fR\fB=\fR\fB\fIVALUE\fR\fR
.RS 4
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\&.
.RE
.PP
\fB\-g\fR, \fB\-\-tag\-match=\fR\fB\fITAG\fR\fR
.RS 4
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\&.
.RE
.PP
\fB\-y\fR, \fB\-\-sysname\-match=\fR\fB\fINAME\fR\fR
.RS 4
Trigger events for devices for which the last component (i\&.e\&. the filename) of the
/sys/
path matches the specified
\fIPATH\fR\&. 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
\fINAME\fR
are triggered\&.
.RE
.PP
\fB\-\-name\-match=\fR\fB\fINAME\fR\fR
.RS 4
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\&.
.sp
Added in version 218\&.
.RE
.PP
\fB\-b\fR, \fB\-\-parent\-match=\fR\fB\fISYSPATH\fR\fR
.RS 4
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\&.
.RE
.PP
\fB\-\-initialized\-match\fR, \fB\-\-initialized\-nomatch\fR
.RS 4
When
\fB\-\-initialized\-match\fR
is specified, trigger events for devices that are already initialized by
\fBsystemd\-udevd\fR, and skip devices that are not initialized yet\&.
.sp
When
\fB\-\-initialized\-nomatch\fR
is specified, trigger events for devices that are not initialized by
\fBsystemd\-udevd\fR
yet, and skip devices that are already initialized\&.
.sp
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\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBWarning\fR
.ps -1
.br
\fB\-\-initialized\-nomatch\fR
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
\fBudev\fR(7)
for more details), the final state of the device becomes easily unstable with this option\&.
.sp .5v
.RE
Added in version 251\&.
.RE
.PP
\fB\-w\fR, \fB\-\-settle\fR
.RS 4
Apart from triggering events, also waits for those events to finish\&. Note that this is different from calling
\fBudevadm settle\fR\&.
\fBudevadm settle\fR
waits for all events to finish\&. This option only waits for events triggered by the same command to finish\&.
.sp
Added in version 238\&.
.RE
.PP
\fB\-\-uuid\fR
.RS 4
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\&.
.sp
Added in version 249\&.
.RE
.PP
\fB\-\-wait\-daemon[=\fR\fB\fISECONDS\fR\fR\fB]\fR
.RS 4
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
\fBudevadm control \-\-ping\fR
before
\fBudevadm trigger\fR\&.
.sp
Added in version 241\&.
.RE
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Print a short help text and exit\&.
.RE
.PP
In addition, optional positional arguments can be used to specify device names or sys paths\&. They must start with
/dev/
or
/sys/
respectively\&.
.SS "udevadm settle [\fIoptions\fR]"
.PP
Watches the udev event queue, and exits if all current events are handled\&.
.PP
\fB\-t\fR, \fB\-\-timeout=\fR\fB\fISECONDS\fR\fR
.RS 4
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\&.
.RE
.PP
\fB\-E\fR, \fB\-\-exit\-if\-exists=\fR\fB\fIFILE\fR\fR
.RS 4
Stop waiting if file exists\&.
.RE
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Print a short help text and exit\&.
.RE
.PP
See
\fBsystemd-udev-settle.service\fR(8)
for more information\&.
.SS "udevadm control \fIoption\fR"
.PP
Modify the internal state of the running udev daemon\&.
.PP
\fB\-e\fR, \fB\-\-exit\fR
.RS 4
Signal and wait for systemd\-udevd to exit\&. No option except for
\fB\-\-timeout\fR
can be specified after this option\&. Note that
systemd\-udevd\&.service
contains
\fBRestart=always\fR
and so as a result, this option restarts systemd\-udevd\&. If you want to stop
systemd\-udevd\&.service, please use the following:
.sp
.if n \{\
.RS 4
.\}
.nf
systemctl stop systemd\-udevd\-control\&.socket systemd\-udevd\-kernel\&.socket systemd\-udevd\&.service
.fi
.if n \{\
.RE
.\}
.sp
.RE
.PP
\fB\-l\fR, \fB\-\-log\-level=\fR\fB\fIvalue\fR\fR
.RS 4
Set the internal log level of
systemd\-udevd\&. Valid values are the numerical syslog priorities or their textual representations:
\fBemerg\fR,
\fBalert\fR,
\fBcrit\fR,
\fBerr\fR,
\fBwarning\fR,
\fBnotice\fR,
\fBinfo\fR, and
\fBdebug\fR\&.
.RE
.PP
\fB\-s\fR, \fB\-\-stop\-exec\-queue\fR
.RS 4
Signal systemd\-udevd to stop executing new events\&. Incoming events will be queued\&.
.RE
.PP
\fB\-S\fR, \fB\-\-start\-exec\-queue\fR
.RS 4
Signal systemd\-udevd to enable the execution of events\&.
.RE
.PP
\fB\-R\fR, \fB\-\-reload\fR
.RS 4
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\&.
.RE
.PP
\fB\-p\fR, \fB\-\-property=\fR\fB\fIKEY\fR\fR\fB=\fR\fB\fIvalue\fR\fR
.RS 4
Set a global property for all events\&.
.RE
.PP
\fB\-m\fR, \fB\-\-children\-max=\fR\fB\fIvalue\fR\fR
.RS 4
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\&.
.RE
.PP
\fB\-\-ping\fR
.RS 4
Send a ping message to systemd\-udevd and wait for the reply\&. This may be useful to check that systemd\-udevd daemon is running\&.
.sp
Added in version 241\&.
.RE
.PP
\fB\-t\fR, \fB\-\-timeout=\fR\fB\fIseconds\fR\fR
.RS 4
The maximum number of seconds to wait for a reply from systemd\-udevd\&.
.RE
.PP
\fB\-\-load\-credentials\fR
.RS 4
When specified, the following credentials are used when passed in:
.PP
\fIudev\&.conf\&.*\fR
.RS 4
These credentials should contain valid
\fBudev.conf\fR(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\&.
.sp
Added in version 256\&.
.RE
.PP
\fIudev\&.rules\&.*\fR
.RS 4
These credentials should contain valid
\fBudev\fR(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\&.
.sp
Added in version 256\&.
.RE
.sp
Note, this
\fIdoes not\fR
imply
\fB\-\-reload\fR
option\&. So, if
\fBsystemd\-udevd\fR
is already running, please consider to also specify
\fB\-reload\fR
to make the copied udev rules files used by
\fBsystemd\-udevd\fR\&.
.sp
Added in version 256\&.
.RE
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Print a short help text and exit\&.
.RE
.SS "udevadm monitor [\fIoptions\fR]"
.PP
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\&.
.PP
\fB\-k\fR, \fB\-\-kernel\fR
.RS 4
Print the kernel uevents\&.
.RE
.PP
\fB\-u\fR, \fB\-\-udev\fR
.RS 4
Print the udev event after the rule processing\&.
.RE
.PP
\fB\-p\fR, \fB\-\-property\fR
.RS 4
Also print the properties of the event\&.
.RE
.PP
\fB\-s\fR, \fB\-\-subsystem\-match=\fR\fB\fIstring[/string]\fR\fR
.RS 4
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\&.
.RE
.PP
\fB\-t\fR, \fB\-\-tag\-match=\fR\fB\fIstring\fR\fR
.RS 4
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\&.
.RE
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Print a short help text and exit\&.
.RE
.SS "udevadm test [\fIoptions\fR] [\fIdevpath\fR|\fIfile\fR|\fIunit\fR]"
.PP
Simulate a udev event run for the given device, and print debug output\&.
.PP
\fB\-a\fR, \fB\-\-action=\fR\fB\fIACTION\fR\fR
.RS 4
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"\&.
.RE
.PP
\fB\-N\fR, \fB\-\-resolve\-names=\fR\fB\fBearly\fR\fR\fB|\fR\fB\fBlate\fR\fR\fB|\fR\fB\fBnever\fR\fR
.RS 4
Specify when udevadm should resolve names of users and groups\&. When set to
\fBearly\fR
(the default), names will be resolved when the rules are parsed\&. When set to
\fBlate\fR, names will be resolved for every event\&. When set to
\fBnever\fR, names will never be resolved and all devices will be owned by root\&.
.sp
Added in version 209\&.
.RE
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Print a short help text and exit\&.
.RE
.SS "udevadm test\-builtin [\fIoptions\fR] \fIcommand\fR [\fIdevpath\fR|\fIfile\fR|\fIunit\fR]"
.PP
Run a built\-in command
\fICOMMAND\fR
for device
\fIDEVPATH\fR, and print debug output\&.
.PP
\fB\-a\fR, \fB\-\-action=\fR\fB\fIACTION\fR\fR
.RS 4
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"\&.
.sp
Added in version 250\&.
.RE
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Print a short help text and exit\&.
.RE
.PP
\fB\-\-version\fR
.RS 4
Print a short version string and exit\&.
.RE
.SS "udevadm verify [\fIoptions\fR] [\fIfile\fR] \&..."
.PP
Verify syntactic, semantic, and stylistic correctness of udev rules files\&.
.PP
Positional arguments could be used to specify one or more files to check\&. 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 the udev daemon\&.
.PP
The exit status is
\fB0\fR
if all specified udev rules files are syntactically, semantically, and stylistically correct, and a non\-zero error code otherwise\&.
.PP
\fB\-N\fR, \fB\-\-resolve\-names=\fR\fB\fBearly\fR\fR\fB|\fR\fB\fBnever\fR\fR
.RS 4
Specify when udevadm should resolve names of users and groups\&. When set to
\fBearly\fR
(the default), names will be resolved when the rules are parsed\&. When set to
\fBnever\fR, names will never be resolved\&.
.sp
Added in version 254\&.
.RE
.PP
\fB\-\-root=\fR\fB\fIPATH\fR\fR
.RS 4
When looking for udev rules files located in udev/rules\&.d directories, operate on files underneath the specified root path
\fIPATH\fR\&.
.sp
Added in version 254\&.
.RE
.PP
\fB\-\-no\-summary\fR
.RS 4
Do not show summary\&.
.sp
Added in version 254\&.
.RE
.PP
\fB\-\-no\-style\fR
.RS 4
Ignore style issues\&. When specified, even if style issues are found in udev rules files, the exit status is
\fB0\fR
if no syntactic or semantic errors are found\&.
.sp
Added in version 254\&.
.RE
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Print a short help text and exit\&.
.RE
.SS "udevadm wait [\fIoptions\fR] [\fIdevice|syspath\fR] \&..."
.PP
Wait for devices or device symlinks being created and initialized by
\fBsystemd\-udevd\fR\&. 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
\fBsystemd\-udevd\fR
after e\&.g\&. partitioning or formatting the devices\&.
.PP
\fB\-t\fR, \fB\-\-timeout=\fR\fB\fISECONDS\fR\fR
.RS 4
Maximum number of seconds to wait for the specified devices or device symlinks being created, initialized, or removed\&. The default value is
"infinity"\&.
.sp
Added in version 251\&.
.RE
.PP
\fB\-\-initialized=\fR\fB\fIBOOL\fR\fR
.RS 4
Check if
\fBsystemd\-udevd\fR
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\&.
.sp
Added in version 251\&.
.RE
.PP
\fB\-\-removed\fR
.RS 4
When specified, the command wait for devices being removed instead of created or initialized\&. If this is specified,
\fB\-\-initialized=\fR
will be ignored\&.
.sp
Added in version 251\&.
.RE
.PP
\fB\-\-settle\fR
.RS 4
When specified, also watches the udev event queue, and wait for all queued events being processed by
\fBsystemd\-udevd\fR\&.
.sp
Added in version 251\&.
.RE
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Print a short help text and exit\&.
.RE
.SS "udevadm lock [\fIoptions\fR] [\fIcommand\fR] \&..."
.PP
\fBudevadm lock\fR
takes an (advisory) exclusive lock on a block device (or all specified devices), as per
\m[blue]\fBLocking Block Device Access\fR\m[]\&\s-2\u[1]\d\s+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
\fBudevadm lock\fR\&.
.PP
This tool is in particular useful to ensure that
\fBsystemd-udevd.service\fR(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
\fBsfdisk\fR(8)\*(Aqs
\fB\-\-lock\fR
switch\&.
.PP
The command expects at least one block device specified via
\fB\-\-device=\fR
or
\fB\-\-backing=\fR, and a command line to execute as arguments\&.
.PP
\fB\-\-device=\fR\fB\fIDEVICE\fR\fR, \fB\-d \fR\fB\fIDEVICE\fR\fR
.RS 4
Takes a path to a device node of the device to lock\&. This switch may be used multiple times (and in combination with
\fB\-\-backing=\fR) 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\&.
.sp
This switch must be used at least once, to specify at least one device to lock\&. (Alternatively, use
\fB\-\-backing=\fR, see below\&.)
.sp
Added in version 251\&.
.RE
.PP
\fB\-\-backing=\fR\fB\fIPATH\fR\fR, \fB\-b \fR\fB\fIPATH\fR\fR
.RS 4
If a path to a device node is specified, identical to
\fB\-\-device=\fR\&. 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
\fB\-\-device=\fR\&.
.sp
Added in version 251\&.
.RE
.PP
\fB\-\-timeout=\fR\fB\fISECS\fR\fR, \fB\-t \fR\fB\fISECS\fR\fR
.RS 4
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
\fBsystemd.time\fR(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\&.
.sp
Added in version 251\&.
.RE
.PP
\fB\-\-print\fR, \fB\-p\fR
.RS 4
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\*(Aqd be locked)\&. Note that the number of lines printed here can be less than the number of
\fB\-\-device=\fR
and
\fB\-\-backing=\fR
switches specified in case these resolve to the same "whole" devices\&.
.sp
Added in version 251\&.
.RE
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Print a short help text and exit\&.
.RE
.SH "INITIALIZED DEVICES"
.PP
Initialized devices are those for which at least one udev rule already completed execution \(en for any action but
"remove"
\(em that set a property or other device setting (and thus has an entry in the udev device database)\&. Devices are no longer considered initialized if a
"remove"
action is seen for them (which removes their entry in the udev device database)\&. Note that devices that have no udev rules are never considered initialized, but might still be announced via the sd\-device API (or similar)\&.
.SH "EXAMPLE"
.PP
\fBExample\ \&1.\ \&Format a File System\fR
.PP
Take a lock on the backing block device while creating a file system, to ensure that
\fBsystemd\-udevd\fR
doesn\*(Aqt probe or announce the new superblock before it is comprehensively written:
.sp
.if n \{\
.RS 4
.\}
.nf
# udevadm lock \-\-device=/dev/sda1 mkfs\&.ext4 /dev/sda1
.fi
.if n \{\
.RE
.\}
.PP
\fBExample\ \&2.\ \&Format a RAID File System\fR
.PP
Similar, but take locks on multiple devices at once:
.sp
.if n \{\
.RS 4
.\}
.nf
# udevadm lock \-\-device=/dev/sda1 \-\-device=/dev/sdb1 mkfs\&.btrfs /dev/sda1 /dev/sdb1
.fi
.if n \{\
.RE
.\}
.PP
\fBExample\ \&3.\ \&Copy in a File System\fR
.PP
Take a lock on the backing block device while copying in a prepared file system image, to ensure that
\fBsystemd\-udevd\fR
doesn\*(Aqt probe or announce the new superblock before it is fully written:
.sp
.if n \{\
.RS 4
.\}
.nf
# udevadm lock \-d /dev/sda1 dd if=fs\&.raw of=/dev/sda1
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.PP
\fBudev\fR(7), \fBsystemd-udevd.service\fR(8)
.SH "NOTES"
.IP " 1." 4
Locking Block Device Access
.RS 4
\%https://systemd.io/BLOCK_DEVICE_LOCKING
.RE