Usage Instructions
This section describes how to use devmaster, covering daemon configuration, client tool, rule usage, and NIC configuration.
Daemon Configuration
After being started, the devmaster daemon reads the configuration file, adjusts the log level, and sets the rule path based on the configuration file. devmaster has a unique configuration file /etc/devmaster/config.toml, which is in TOML format.
Configuration Items
The devmaster configuration file supports the following configuration items:
- rules_d: Rule path. The default value is ["/etc/devmaster/rules.d", "/lib/devmaster/rules.d", "/etc/udev/rules.d", "/run/udev/rules.d", "/lib/udev/rules.d"]. If this item is not explicitly specified, the default value is ["/etc/devmaster/rules.d", "/run/devmaster/rules.d", "/usr/local/lib/devmaster/rules.d", "/usr/lib/devmaster/rules.d"]. Currently, devmaster does not support rule loading priorities. Rule files with the same name in different rule paths will not conflict with each other. Rule files are loaded in the sequence specified by rules_d. Rule files in the same directory are loaded in the lexicographical sequence.
- max_workers: Maximum number of concurrent worker threads. If this item is not specified, the default value 3 is used. The value cannot be greater than the number of CPU cores.
- log_level: Log level. The value can be error, debug or info. If this parameter is not specified, info is used. The default value in the configuration file is error.
- network_d: NIC configuration path. The default value is ["/etc/devmaster/network.d"]. If this parameter is not specified, there is no default path. NIC configurations control the behavior of the
net_setup_link
command of devmaster. For details, see NIC Configuration. - log_targets: Log output target. The value can be file, console, or syslog. The default value is syslog. When file is specified, logs are save to the /var/log/devmaster/devmaster.log file. When console is specified, logs are printed to the terminal. When syslog is specified, logs are output to the /dev/log socket and managed by the log service, such as rsyslog, and will be printed to the terminal if no log service is configured. Multiple log output targets can be specified.
Client Tool
devctl
is the client tool of the devmaster daemon. It is used to control devmaster behaviors, simulate device events, and debug rules. Common devctl
commands are as follows.
Viewingvice Dat
View the sysfs attribute and database information, or clean up the database:
# devctl info [OPTIONS] [DEVICES]...
Monitoring Device Events
Monitor uevent events reported by the kernel and events sent after devmaster processes devices, which are prefixed with KERNEL and USERSPACE, respectively.
# devctl monitor [OPTIONS]
Triggering Device Events
Simulate a device action to trigger a kernel uevent event. This operation is used to replay coldplug device events during kernel initialization.
# devctl trigger [OPTIONS] [DEVICES]...
Testing Built-in Commands
Test the effect of a built-in command on a device. Supported built-in commands include blkid
, input_id
, kmod
, net_id
, net_setup_link
, path_id
, and usb_id
. Event types that can be triggered include add
, change
, remove
, move
, online
, offline
, bind
, and unbind
.
# devctl test-builtin [OPTIONS] <BUILTIN> <SYSPATH>
Rule Usage
devmaster rules consist of a group of rule files. After the devmaster daemon is started, it loads the rule files in lexicographic order based on the rule path specified in the configuration file.
Note:
After adding or deleting a rule, or modifying a rule or configuration file, you need to restart devmaster for the modifictaion to take effect.
devmaster cannot be restarted by running
sctl restart devmaster
. Runsctl stop devmaster
andsctl start devmaster
.
Rule Examples
The following describes several common rule examples. For details about the rule syntax, see the devmaster manual.
Example 1: Creating a Soft Link for a Block Device
Use the blkid
built-in command to read the UUID of a block device and create a soft link for the block device based on the UUID.
After an event of a device that has a file system is triggered, a soft link corresponding to the device is generated in the /dev/test directory.
The following uses the block device of the sda1 partition as an example.
Create the rule file /etc/devmaster/rules.d/00-persist-storage.rules. The file content is as follows:
SUBSYSTEM!="block", GOTO="end" IMPORT{builtin}=="blkid" ENV{ID_FS_UUID_ENC}=="?*", SYMLINK+="test/$env{ID_FS_UUID_ENC}" LABEL="end"
Restart devmaster:
# sctl stop devmaster # sctl start devmaster
Trigger the sda1 device event:
# devctl trigger /dev/sda1
Check if a soft link pointing to sda1 exists in the /dev/test/ directory. If yes, the rule takes effect.
# ll /dev/test/ total 0 lrwxrwxrwx 1 root root 7 Sep 6 15:35 06771fe1-39da-42d7-ad3c-236a10d08a7d -> ../sda1
Example 2: Renaming a NIC
Use the net_id
built-in command to obtain the hardware attributes of the NIC, then run the net_setup_link
built-in command to select a hardware attribute based on the NIC configuration as the NIC name, and rename the NIC through the NAME rule.
The following uses the ens33 NIC as an example to test the effect of the NIC renaming rule:
Create the rule file /etc/devmaster/rules.d/01-netif-rename.rules. The file content is as follows:
SUBSYSTEM!="net", GOTO="end" IMPORT{builtin}=="net_id" IMPORT{builtin}=="net_setup_link" ENV{ID_NET_NAME}=="?*", NAME="$env{ID_NET_NAME}" LABEL="end"
Restart devmaster:
# sctl stop devmaster # sctl start devmaster
Create the NIC configuration file /etc/devmaster/network.d/99-default.link. The content is as follows:
[Match] OriginalName = "*" [Link] NamePolicy = ["database", "onboard", "slot", "path"]
Bring the NIC offline.
# ip link set ens33 down
Temporarily name the NIC tmp:
# ip link set ens33 name tmp
Trigger the add event of the NIC.
# devctl trigger /sys/class/net/tmp --action add
Check the NIC name. If the NIC name is changed to ens33, the rule takes effect.
# ll /sys/class/net/| grep ens33 lrwxrwxrwx 1 root root 0 Sep 6 11:57 ens33 -> ../../devices/pci0000:00/0000:00:11.0/0000:02:01.0/net/ens33
Restore the network connection after activating the NIC.
# ip link set ens33 up
Note:
An activated NIC cannot be renamed. You need to bring it offline first. In addition, the renaming rule of devmaster takes effect only in the add event of the NIC.
Adding net.ifnames=0 or net.ifnames=false to th kernel parameters disables NIC renaming.
Example 3: Modifying the User Permissions on a Device Node
The OPTIONS+="static_node=
Create the rule file /etc/devmaster/rules.d/02-devnode-privilege.rules. The file content is as follows:
OWNER="root", GROUP="root", MODE="777", OPTIONS+="static_node=tty5"
Restart devmaster:
# sctl stop devmaster # sctl start devmaster
After devmaster is restarted, check the user, user group, and permissions of /dev/tty5. If the user, user group, and permissions are changed to root, root, and rwxrwxrwx, the rule takes effect.
# ll /dev/tty5 crwxrwxrwx 1 root root 4, 5 Feb 3 2978748 /dev/tty5
NIC Configuration
The NIC renaming function of devmaster is implemented by the built-in commands net_id
and net_setup_link
and the NIC configuration file. In the rule file, use net_id
to obtain the hardware attributes of a NIC, and then use net_setup_link
to select a NIC attribute as the new NIC name. The net_setup_link
command controls the NIC naming style for a specific NIC based on the NIC configuration file. This section describes how to use the NIC configuration file. For details about how to rename a NIC, see Renaming a NIC.
Default NIC Configurations
devmaster provides the following default NIC configurations:
[Match]
OriginalName = "*"
[Link]
NamePolicy = ["onboard", "slot", "path"]
The NIC configuration file contains the [Match] matching section and [Link] control section. Each section contains several configuration items. The configuration items in the [Match] section are used to match NICs. When a NIC meets all matching conditions, all configuration items in the [Link] section are applied to the NIC, for example, setting the NIC naming style and adjusting NIC parameters.
The preceding default NIC configuration indicates that the configuration takes effect on all NICs and checks the NIC naming styles of the onboard, slot, and path styles in sequence. If an available style is found, the NIC is named in this style.
For details about the NIC configuration, see the devmaster manual.
Note:
Adding net.ifnames=0 or net.ifnames=false to th kernel parameters disables NIC renaming.
If NIC renaming does not take effect, check the kernel parameters.