Mounting USB filesystems

Updated: April 19, 2023

If you use the USB launcher service for device publishing, you can configure it to mount the filesystems of USB devices. That way, you don't need to use a separate service to do the mounting (unless you also need to mount non-USB devices).

The USB launcher service can mount the filesystems of attached USB devices based on a mount-rules file. The service reads either the default mount-rules file, /etc/usblauncher/rules.mnt, or another file specified with the -M command-line option. The service uses the standard mount() function call to do the actual mounting.

Content detection rules

The mount-rules file specifies one matching rule per line, with each rule containing fields for a device, mountpoint, filesystem type, and options. The service processes the rules starting from the first line and stopping at the first matching rule that either succeeds or tells the service to skip the device (i.e., when the rule has only a global pattern and no mount information). If a rule's execution fails, the service goes to the next rule (line), until it successfully executes a rule or reaches the end of the file. To select the appropriate filesystem, you can define multiple rules for a removable device.

Here's a sample mount-rules file:
# Device                    Mountpoint  FS type Options
/dev/umass[0-9]*            /           enum
/dev/umass[0-9]*t1[1234]    /fs/usb%0   dos
/dev/umass[0-9]*t1[1234].*  /fs/usb%0   dos
/dev/umass[0-9]*t[146]      /fs/usb%0   dos
/dev/umass[0-9]*t[146].*    /fs/usb%0   dos
/dev/umass*t17[789]         /fs/usb%0   qnx6    sync=optional
/dev/umass[0-9]*            /fs/usb%0   dos
The column entries have the following formats:
  • Device — Contains pathnames in the form /dev/umassX[tN], where X is a storage-device number (0, 1, 2, etc.) and N is a partition type (4, 11, 12, etc.). Thus, a path with umassX refers to a device, while a path with umassXtN refers to a partition.
  • Mountpoint — States the full path of the mountpoint, and supports these special sequences:
    Sequence Description
    %#

    Expands to the major device number of the storage device.

    For example, with /fs/usb%#, /dev/umass0 will be mounted at /fs/usb0 and /dev/umass1 will be mounted at /fs/usb1. But %# does not permit multiple partitions, so it's better to use %0.

    %U

    Expands to the filesystem UUID (universally-unique identifier) of the storage device.

    For example, with /fs/%U, the filesystem will be mounted at /fs/filesystem_uuid.

    If no valid filesystem UUID is found, the service replaces %U with uuid%0 to allocate a unique mountpoint name.

    Only supported for FAT and NTFS filesystems.

    %P

    Expands to the partition UUID of the storage device.

    If no valid partition UUID is found, the service replaces %P with uuid%0 to allocate a unique mountpoint name.

    For example, with /fs/%P, the filesystem will be mounted at /fs/partition_uuid.

    Only supported for MBR and GPT partitions.

    %0

    Used principally to support multiple partition rules in the /etc/usblauncher/rules.mnt file, all with mountpoint names of the form /fs/usb%0.

    If you specify %0 in the name, the service tries to allocate /fs/usb0, /fs/usb1, and so on until it finds a unique mountpoint name.

  • FS type — Contains either the filesystem type or an enum command that instructs the service to enumerate any partitions found for the device that matches the rule in the Device column.
  • Options — Contains any options passed to the filesystem driver. The sync=optional parameter in the above example is specific to the filesystem driver DLL; see the driver documentation for more information.

Mounting a filesystem

Given the content-detection rules and example mount-rules file described above, here's what happens when you insert a USB stick that contains one or more filesystems:
  1. The USB launcher service attempts to identify a matching rule for the USB stick and finds the enum rule, which enumerates the partition. At this point, the service has completed processing the mount rules, and the enumeration proceeds.
  2. The enumeration makes /dev/umassXtN pathnames appear. In response, the service resumes processing the mount rules, skipping both the enumeration rule and the rule to mount the whole device as a filesystem. Instead, it tries an fs-dos mount on a partition, resulting in the appearance of an /fs/usb* pathname.
  3. The service publishes a mount object for the raw device and for each partition that has been enumerated. When it subsequently mounts a filesystem on a partition, the service updates the partition's mount object with mountpoint information.

Disabling the auto-mount feature

By default, the USB launcher service automatically attempts to mount filesystems on USB devices. To disable the auto-mounter feature, use the -M option to point to an empty mount-rules file or to /dev/null. If you use this technique, the service won't log mount attempts or publish accurate mnt_status values through the PPS mount object.