VDEVD-ACTIONS(8)

NAME
vdevd-actions - action definitions for the vdevd device-file manager daemon

DESCRIPTION
vdevd is a portable userspace device-file manager daemon. Its main task is to manage the "/dev" file structue in response to kernel events, to add, remove and configure device nodes and symbolic links so to make devices available through the traditional well defined naming scheme. The details of operation are programmed by a combination of action declarations and helper scripts. The action declarations are used for recognising the types of devices, and mapping these to appropriate initialization actions. The helper scripts implement these actions.

ACTION SYNTAX
An action file consists of a single declaration block headed by a line saying "[vdev-action]". This is followed by a number of assignment patterns to be matched on the event, as well as result assignments for the helperfwhich identifies the assoicated helper script, and the daemonlet variable, which signals whether or not to invoke the helper script via the daemonlet wrapper script.

For example, the 001-sysfs-block.act action looks as follows:
[vdev-action]
event=add
type=block
OS_DEVPATH=
helper=sysfs.sh
daemonlet=true

The action matches for add events of block devices where OS_DEVPATH is empty, and as a result, the helper script sysfs.sh is invoked via the daemonlet wrapper script.

Specifically: unless stated otherwise, all action fields are optional, and all fields must match the device event for the action's command to be executed.

event
    The event field is *required. Use "add" to match a device-add event, "remove" to match a device-remove event, "change" to match a device-change event (such as a battery level changing), or "any" to match any device event.

path
    The path field is optional. This is an extended POSIX regular expression that matches the kernel-given device path (such as sda or input/mice) to the action.

type
    The type field is optional. This is either "block" or "char", which will match the event only if it it is for a block or character device, respectively. Not all devices are representable by block or character device files, however, which is why this field is optional.

OS_*
    OS_* fields are optional. Any field prefixed with OS_ matches an OS-specific device attribute. On Linux, these include the names of uevent fields. For example, an action can match a device's subsystem using the OS_SUBSYSTEM field. If an empty value is given (e.g. "OS_SUBSYSTEM="), then the action will match any value as long as the device attribute is present in the device event (for example, a Linux uevent packet that does not have SUBSYSTEM defined will not match an action with "OS_SUBSYSTEM=").

Once a device event is encountered that matches all of an action's fields, vdevd runs the commands specified by the action's ini file. The fields that describe the commands are:

rename_command
    This is a shell command to run to generate the path to the device file to create. It will be evaluated after the device event matches the action, but before the device file is created. The command must write the desired path to stdout. Its output will be truncated at 4,096 characters (which is PATH_MAX on most filesystems). Note that not all devices have paths given by the kernel.

command
    This is the shell command to run once the device file has been successfully created. Unless specified otherwise, vdevd will run this as a synchronous subprocess; i.e., it will wait until the command has completed before processing the next action.

async
    If set to "true", this tells vdevd to start and run the action command asynchronously with its continued processing, i.e., to not wait until the commmand has completed. This is useful for long-running device setup tasks.

if_exists
    Commands are executed optimistically; even if one fails, the other subsequent ones will be attempted, unless the device already exists and vdevdfIif_exists=error in one of the matching actions. If the device already exists (given by the exists flag), then only run commands with if_exists=run.

daemonlet
    If set to "true", this tells vdevd to run the command with a daemonlet wrapping. See "Advanced Device Handling" below for a description of what this means.

NOTE: vdevd matches a device event against actions according to their files' lexographic order. Moreover, it processes device events sequentially, in the order in which they arrive. This is also true for the Linux port; the kernel's SEQNUM field is passed on to actions, but not used for sequencing the event handling. vdevd communicates device information to action commands using environment variables. When a command or rename_command runs, the following environment variables will be set:

$VDEV_ACTION
    This is the event field of the action, i.e. "add", "remove", "change", or "any".

$VDEV_DAEMONLET
    If set to 1, then the command is being invoked as a daemonlet (see the "Advanced Device Handling" section below).

$VDEV_CONFIG_FILE
    This is the absolute path to the configuration file vdevd is using.

$VDEV_HELPERS
    This is the absolute path to the directory containing vdevd's helper programs.

$VDEV_INSTANCE
    This is a randomly-generated string that corresponds to this running intance of vdevd. It will be different on each invocation of vdevd.

$VDEV_GLOBAL_METADATA
    The absolute path to the metadata directory into which vdevd writes metadata (e.g. /dev/metadata).

$VDEV_LOGFILE
    If specified, this is the path to vdevd's logfile.

$VDEV_MAJOR
    If the device event corresponds to a block or character device, this is the device file's major number.

$VDEV_METADATA
    If the device is given a path (either by the kernel or the rename_command output), this is the absolute path to the directory to contain the device's metadata.

$VDEV_MINOR
    If the device event corresponds to a block or character device, this is the device file's minor number.

$VDEV_MODE
    If the device event corresponds to a block or character device, this is the string "block" or "char" (respectively).

I$VDEV_MOUNTPOINT
    This is the absolute path to the directory in which the device files will be created. For example, this is usually /dev.

$VDEV_OS_*
    Any OS-specific device attributes will be encoded by name, prefixed with VDEV_OS_. For example, on Linux, the SUBSYSTEM field in the device's uevent packet will be exported as $VDEV_OS_SUBSYSTEM. Similarly, the DEVPATH field in a device's uevent packet will be exported as $VDEV_OS_DEVPATH.

$VDEV_PATH
    If the device is given a path (either by the kernel or the rename_command output), this is the path to the device file *relative* to $VDEV_MOUNTPOINT. The absolute path to the device file can be found by $VDEV_MOUNTPOINT/$VDEV_PATH. Note that not all devices have device files (such as batteries, PCI buses, etc.).

Advanced Device Handling

By default, vdevd will fork() and exec() the command for each device request in the system shell. However, as an optimization, vdevd can run the command as a *daemonlet*. This means that the command will be expected to stay resident once it proceses a device request, and receive and process subsequent device requests from vdevd instead of simply exiting after each one. Doing so saves vdevd from having to fork() and exec() the same command over and over again for common types of devices, and lets it avoid having to repeatly incur long command start-up times. It also allows the administrator to define stateful or long-running actions that can work on sets of devices.

The programming model for daemonlet commands is as follows:

1.  vdevd will fork() and exec() the command directly. It will *not* invoke the system shell to run it.

2.  vdevd will write a sequence of newline-terminated strings to the command's stdin, followed by an empty newline string. These strings encode the request's environment variables, and are in the form NAME=VALUE\n.

3.  The command is expected to write an ASCII-encoded exit code to stdout to indicate the success/failure of processing the request. 0 indicates success, and non-zero indicates failure. If the command crashes or misbehaves, vdevd will log as such and attempt to restart it.

LIST OF ACTIONS
vdevd includes the following list of actions:

    /etc/vdev/actions/001-sysfs-block.act
    /etc/vdev/actions/001-sysfs-char.act
    /etc/vdev/actions/002-modalias.act
    /etc/vdev/actions/003-firmware.act
    /etc/vdev/actions/agpgart.act
    /etc/vdev/actions/block.act
    /etc/vdev/actions/btrfs-control.act
    /etc/vdev/actions/char.act
    /etc/vdev/actions/cpu.act
    /etc/vdev/actions/cpu-msr.act
    /etc/vdev/actions/cuse.act
    /etc/vdev/actions/device-mapper.act
    /etc/vdev/actions/dialout.act
    /etc/vdev/actions/disk.act
    /etc/vdev/actions/disk-part.act
    /etc/vdev/actions/dm-disk.act
    /etc/vdev/actions/dri.act
    /etc/vdev/actions/err.act
    /etc/vdev/actions/fb.act
    /etc/vdev/actions/full.act
    /etc/vdev/actions/fuse.act
    /etc/vdev/actions/fuse-mounts.act
    /etc/vdev/actions/hwdb.act
    /etc/vdev/actions/ifname.act
    /etc/vdev/actions/input.act
    /etc/vdev/actions/irlpt.act
    /etc/vdev/actions/kmsg.act
    /etc/vdev/actions/kvm.act
    /etc/vdev/actions/legousbtower.act
    /etc/vdev/actions/lircN.act
    /etc/vdev/actions/loop.act
    /etc/vdev/actions/loop-control.act
    /etc/vdev/actions/lp.act
    /etc/vdev/actions/mem.act
    /etc/vdev/actions/mISDNtimer.act
    /etc/vdev/actions/mmtimer.act
    /etc/vdev/actions/mwave.act
    /etc/vdev/actions/netdev.act
    /etc/vdev/actions/net-tun.act
    /etc/vdev/actions/null.act
    /etc/vdev/actions/nvram.act
    /etc/vdev/actions/optical.act
    /etc/vdev/actions/parport.act
    /etc/vdev/actions/pktcdvd.act
    /etc/vdev/actions/pktcdvdN.act
    /etc/vdev/actions/port.act
    /etc/vdev/actions/power-switch.act
    /etc/vdev/actions/printer.act
    /etc/vdev/actions/ptmx.act
    /etc/vdev/actions/qftN.act
    /etc/vdev/actions/random.act
    /etc/vdev/actions/raw.act
    /etc/vdev/actions/rawctl.act
    /etc/vdev/actions/rfkill.act
    /etc/vdev/actions/rtc.act
    /etc/vdev/actions/sch.act
    /etc/vdev/actions/sclp_line.act
    /etc/vdev/actions/sgi.act
    /etc/vdev/actions/sonypi.act
    /etc/vdev/actions/sound-alsa-control.act
    /etc/vdev/actions/sound-audio.act
    /etc/vdev/actions/tty3270.act
    /etc/vdev/actions/tty.act
    /etc/vdev/actions/ttyN.act
    /etc/vdev/actions/ttyS.act
    /etc/vdev/actions/ttysclp.act
    /etc/vdev/actions/usb-bus.act
    /etc/vdev/actions/v4l.act
    /etc/vdev/actions/vcs.act
    /etc/vdev/actions/virtio.act
    /etc/vdev/actions/virtualbox-usb.act
    /etc/vdev/actions/virtualbox-usb_device.act
    /etc/vdev/actions/z90crypt.act
    /etc/vdev/actions/zzz-event-push.act
    /etc/vdev/actions/zzz-udev-compat.act

HELPERS
vdevd includes the following helper scripts and binaries:

block.sh
    Helper script to link a block device to /dev/block/$MAJOR:$MINOR.

char.sh
    Helper sript to link a character device to /dev/char/$MAJOR:$MINOR.

daemonlet
    This is a wrapper script around persistent helper scripts. dameonlet provides a loop for successive helper script invocation, in a loop that first reads ASCII-encoded KEY=VALUE environment variables until it receives "done" (indicating the end of a stanza), then invokes the helper script, and then prints the return code.
    If reading an empty string, daemonlet exits the loop.

dev-setup.sh
    This script is not meant to be run manually.

disk.sh
    Helper for setting up symlinks to disks and their partitions.

dm-disk.sh
    Helper script for generating dm block device paths and symlinks.

echo_n
    Helper binary that merely implements "echo -n", i.e. to print to stdout all its arguments separated by space, and no terminating newline.

event-push.sh
    Helper script to push device events to listening processes. The event to push is defined by environment variables: $VDEV_OS_SEQNUM, $VDEV_OS_DEVPATH, $VDEV_OS_SUBSYSTEM, and the optional $VDEV_PATH.
    The event is pushed vie event-put to the socket /dev/events/global.

event-put
    Helper binary to trigger an event from an stdin event definition. Run it as "event-put -h" to get usage information.

firmware.sh
    This is a helper script for firmware loading.

gen-ifnames.sh
    Helper script that merely filters the output of "ip link show" into a series of "$IFNAME mac $MAC" lines for the available network interfaces.

hwdb-props.sh
    Helper script to insert a device's hardware database files.

hwdb.sh
    Helper script to query the hardware database (if it exists), and extract useful properties from it. NOTE: does not use vdev's subr.sh; this program can run independently.

ifname.sh
    Helper script to rename interfaces to have persistnet names, according to the rules in $VDEV_IFNAMES_PATH The format of this file should be lines of: "$IFNAME $ID_TYPE $ID_ARG" where $IFNAME is the persistent name; $ID_TYPE is either "mac" or "devpath", and $ID_ARG is either the MAC address (formatted xx:xx:xx:xx:xx:xx) if $ID_TYPE is "mac", or $ID_ARG is the device path (starting with /devices)

input.sh
    Helper script to set up /dev/input/by-id and /dev/input/by-path.

modprobe.sh
    Helper script to invoke modprobe with $VDEV_OS_MODALIAS argument.

netdev.sh
    Helper script to collate properties for a network device.

optical.sh
    Helper script to set up symlinks to optical (CD, DVD) devices, based on capability.

permissions.sh
    Helper script to set permissions and ownership. It takes the owner from the VDEV_VAR_PERMISSIONS_OWNER environment variable, the group from the VDEV_VAR_PERMISSIONS_GROUP environment variable and/or the mode from the VDEV_VAR_PERMISSIONS_MODE environment variable.

power-switch.sh
    Helper script to tag "power switch" devices as such in the metadata.

sound.sh
    Helper script to set up /dev/snd/by-path and /dev/snd/by-id.

stat_ata
    Helper binary to read product/serial number for ATA drives.

stat_bus
    Helper binary to set up bus link(s) according to sub system.

stat_input
    Helper binary to read input device properties.

stat_net
    Helper binary to read network device properties, given an interface.

stat_optical
    Helper binary to get drive capabilities from an open device node, using the Linux-specific CDROM_GET_CAPABILITY ioctl.

stat_path
    Helper binary to build a persistent path name from sysfs.

stat_scsi
    Helper binary to read SCSI device properties.

stat_usb
    Helper binary to read USB device properties.

stat_v4l
    Helper binary to read video4linux device properties.

subr-event.sh
    Helper script inclusion file that defines a collection of utility functions for event processing, to be used in helper scripts.

subr-hwdb.sh
    Helper script inclusion file that defines a collection of utility functions for hardware database access, to be used in helper scripts.

subr.sh
    Helper script inclusion file that defines a collection of more generic utility functions, to be used in helper scripts.

sysfs.sh
    Helper script to store device metadata from sysfs to the OS metadata database. In particular, map a device's sysfs path to its metadata directory.

udev-compat.sh
    Helper script to maintain udev compatibility.

usb-name.sh
    Helper script to echo USB device details when known.

v4l.sh
    Helper script for video4linux devices.

VBoxCreateUSBNode.sh
    Helper script for creating and removing device nodes for VirtualBox USB devices.

SEE ALSO
vdevd(8).

CONTRIBUTIONS
This software was primarily developed by Jude Nelson <judecn@gmail.com>.
Various contributions by Didier Kryn <kryn@in2p3.fr>, Kylie McClain <somasis@exherbo.org>, Jack Frost <fbt@fleshless.org, tilt12345678, Suedi, Obarun, Peter Gossner <gossner@internode.on.net>
This man page is maintained by Ralph Ronnquist <ralph.ronnquist@gmail.com>. Most of the detailed content is authored by Jude Nelson, then edited and formatted into this form by Ralph.