Hotplug

Procd (the init system and process management daemon) executes scripts located in /etc/hotplug.d/ when certain events happen, like for example when an interface goes up or down, when a new storage drive is detected, or when a button is pressed. It can be very useful with PPPoE connection or in an unstable network, or to use hardware buttons.

This functionality emulates/extends what was done by the long retired Hotplug2 package.

In the /etc/hotplug.d directory you will find some directories block, iface, net and ntp.

When the trigger event fires, Procd will execute all scripts in that trigger's directory, in alphabetical order. Which is why most scripts in there use a numeric prefix.

See also:

• DHCP client scripts
• Buttons, sound devices, serial and USB serial dongles
• DHCP, NDP, TFTP

Simply place your script(s) into the right hotplug.d directory, if there is none just create the right one.

Procd exposes a wealth of info when executes your scripts in /etc/hotplug.d, usually as environmental variables.

If you want to see what environmental variables it is providing, make a script like this:

cat << "EOF" > /etc/hotplug.d/iface/00-logger
logger -t hotplug $(env)
EOF

Then trigger the event connected to that directory, and then you can see what envs were passed by reading the output:

logread -e hotplug

For scripts in block directory, these are the (relevant) environmental variables

For scripts in dsl directory, these are the (relevant) environment variables

When DSL_NOTIFICATION_TYPE is DSL_STATUS, the following environment variables are set

When DSL_NOTIFICATION_TYPE is DSL_INTERFACE_STATUS, the following environment variables are set

When DSL_NOTIFICATION_TYPE is DSL_DATARATE_STATUS_US, the following environment variables are set

When DSL_NOTIFICATION_TYPE is DSL_DATARATE_STATUS_DS, the following environment variables are set

NOTE: environment variables marked with an * are only available when channel bonding support is compiled in.

For scripts in iface directory, these are the (relevant) environmental variables

The meaning of most actions should be straightforward, the maybe-not-obvious ones are:

When ACTION is ifupdate, the following environment variables may be set

Variables based on busybox ntpd:

Even without NTP sync, you will receive a “periodic” hotplug event, with stratum=16, about every 11 minutes out of the box.

cat << "EOF" > /etc/hotplug.d/iface/99-my-action
[ "${ACTION}" = "ifup" ] && {
    logger -t hotplug "Device: ${DEVICE} / Action: ${ACTION}"
} 
EOF

Every time an interface goes up then the if/fi statement will be executed.

Niii has posted this quick example for a USB WiFi device hotplug event to trigger an init.d network restart wlan0 script.

To determine RTL8188SU_PRODID variable:

# lsusb -v
  idVendor           0x0bda Realtek Semiconductor Corp.
  idProduct          0x8171 RTL8188SU 802.11n WLAN Adapter
  bcdDevice            2.00

mkdir -p /etc/hotplug.d/usb
cat << "EOF" > /etc/hotplug.d/usb/20-rtl8188su
BINARY="/sbin/wifi up"
RTL8188SU_PRODID="bda/8171/200"
 
if [ "${PRODUCT}" = "${RTL8188SU_PRODID}" ]; then
    if [ "${ACTION}" = "add" ]; then
        ${BINARY}
    fi
fi
EOF

An other script to create a symlink instead of renaming the device. I test if DEVICE_NAME is empty because when I plug usb device I retrieve two add event, and the first come before created device, so symlink fails.

cat << "EOF" > /etc/hotplug.d/usb/20-cp210x
CP210_PRODID="10c4/ea60/100"
SYMLINK="my_link"
 
if [ "${PRODUCT}" = "${CP210_PRODID}" ]; then
    if [ "${ACTION}" = "add" ]; then
          DEVICE_NAME=$(ls /sys/${DEVPATH} | grep tty)
          if [ -z ${DEVICE_NAME} ]; then
              logger -t hotplug "Warning DEVICE_NAME is empty"
              exit 0
          fi
          logger -t hotplug "Device name of cp210 is ${DEVICE_NAME}"
          ln -s /dev/${DEVICE_NAME} /dev/${SYMLINK}
          logger -t hotplug "Symlink from /dev/${DEVICE_NAME} to /dev/${SYMLINK} created"
    fi
fi
 
if [ "${PRODUCT}" = "${CP210_PRODID}" ]; then
    if [ "${ACTION}" = "remove" ]; then
        rm /dev/${SYMLINK}
        logger -t hotplug "Symlink /dev/${SYMLINK} removed"
    fi
fi
EOF

cat << "EOF" > /etc/hotplug.d/usb/20-bt_test
BT_PRODID="a12/1/"
BT_PRODID_HOT=`echo ${PRODUCT} | cut -c 1-6`
 
#logger -t hotplug "PRODUCT ID is ${BT_PRODID_HOT}"
 
if [ "${BT_PRODID_HOT}" = "${BT_PRODID}" ]; then
    if [ "${ACTION}" = "add" ]; then
        logger -t hotplug "bluetooth device has been plugged in!"
        if [ "${BSBTID_NEW}" = "${BSBTID_OLD}" ]; then
            logger -t hotplug "bluetooth device hasn't changed"
        else
            logger -t hotplug "bluetooth device has changed"
        fi
    fi
    if [ "${ACTION}" = "remove" ]; then
        logger -t hotplug "bluetooth device has been removed!"
    fi
else
    logger -t hotplug "USB device is not bluetooth"
fi
EOF

cat << "EOF" > /etc/hotplug.d/usb/20-mjpg_start
case "${ACTION}" in
    add)
            # start process
        /etc/init.d/mjpg-streamer start
            ;;
    remove)
            # stop process
        /etc/init.d/mjpg-streamer stop
            ;;
esac
EOF

cat << "EOF" > /etc/hotplug.d/block/xfs_automount
# if a new block device is connected
if [ "${ACTION}" = "add" ]; then
    # getting device UUID
    detected_uuid="$(xfs_admin -u /dev/${DEVICENAME} | awk '{print $3}')"
    # deciding mountpoint for known UUID
    mountpoint=""
    case "${detected_uuid}" in
        6a5d7c5c-c9d0-41cc-8f19-78d97f839c05)
            mountpoint="/path/to/first/mountpoint"
            ;;
        02880b1f-0c67-46b6-9b05-5535680ccc89)
            mountpoint="/path/to/second/mountpoint"
            ;;
    esac
 
    # if we have a known UUID we have a mountpoint so we can mount it
    if [ "${mountpoint}" != "" ]; then 
        mount /dev/${DEVICENAME} ${mountpoint}
    fi
fi
# unmounting happens automatically at device disconnection anyway so no logic for that
EOF

If you had notice the udev and eudev were removed in the openwrt 18.0.* release, don't be afraid because you still can make the things works. You can use hotplug scripts as coldplug. Pay attention at the ACTION environment variable, at the boot are executed 'bind' actions. So, just add this option to hotplug run accordinly. In my case I used this:

mkdir -p /etc/hotplug.d/usb
cat << "EOF" > /etc/hotplug.d/usb/22-symlinks
# Description: Action executed on boot (bind) and with the system on the fly
if [ "${ACTION}" = "bind" ]; then
  case "${PRODUCT}" in
    1bc7*) # Telit HE910 3g modules product id prefix
      DEVICE_NAME="$(ls /sys/${DEVPATH} | grep tty)"
      DEVICE_TTY="$(ls /sys/${DEVPATH}/tty/)"
      # Module Telit HE910-* connected to minipciexpress slot MAIN
      if [ "${DEVICENAME}" = "1-1.3:1.0" ]; then
        ln -s /dev/${DEVICE_TTY} /dev/ttyMODULO1_DIAL
        logger -t hotplug "Symlink from /dev/${DEVICE_TTY} to /dev/ttyMODULO1_DIAL created"
      elif [ "${DEVICENAME}" = "1-1.3:1.6" ]; then
        ln -s /dev/${DEVICE_TTY} /dev/ttyMODULO1_DATA
        logger -t hotplug "Symlink from /dev/${DEVICE_TTY} to /dev/ttyMODULO1_DATA created"
      # Module Telit HE910-* connected to minipciexpress slot SECONDARY
      elif [ "${DEVICENAME}" = "1-1.2:1.0" ]; then
        ln -s /dev/${DEVICE_TTY} /dev/ttyMODULO2_DIAL
        logger -t hotplug "Symlink from /dev/${DEVICE_TTY} to /dev/ttyMODULO2_DIAL created"
      elif [ "${DEVICENAME}" = "1-1.2:1.6" ]; then
        ln -s /dev/${DEVICE_TTY} /dev/ttyMODULO2_DATA
        logger -t hotplug "Symlink from /dev/${DEVICE_TTY} to /dev/ttyMODULO2_DATA created"
      fi
    ;;
  esac
fi
# Action to remove the symlinks
if [ "${ACTION}" = "remove" ]; then
  case "${PRODUCT}" in
    1bc7*)  # Telit HE910 3g modules product id prefix
     # Module Telit HE910-* connected to minipciexpress slot MAIN
      if [ "${DEVICENAME}" = "1-1.3:1.0" ]; then
        rm /dev/ttyMODULO1_DIAL
        logger -t hotplug "Symlink /dev/ttyMODULO1_DIAL removed"
      elif [ "${DEVICENAME}" = "1-1.3:1.6" ]; then
        rm /dev/ttyMODULO1_DATA
        logger -t hotplug "Symlink /dev/ttyMODULO1_DATA removed"
      # Module Telit HE910-* connected to minipciexpress slot SECONDARY
      elif [ "${DEVICENAME}" = "1-1.2:1.0" ]; then
        rm /dev/ttyMODULO2_DIAL
        logger -t hotplug "Symlink /dev/ttyMODULO2_DIAL removed"
      elif [ "${DEVICENAME}" = "1-1.2:1.6" ]; then
        rm /dev/ttyMODULO2_DATA
        logger -t hotplug "Symlink /dev/ttyMODULO2_DATA removed"
      fi
    ;;
  esac
fi
EOF

A simple method to configure persistent interface names by MAC address.

uci set network.wan1.ifname="wan1"
uci set network.wan2.ifname="wan2"
uci -q delete network.wan1_dev
uci set network.wan1_dev="device"
uci set network.wan1_dev.name="wan1"
uci set network.wan1_dev.mac="11:22:33:44:55:66"
uci -q delete network.wan2_dev
uci set network.wan2_dev="device"
uci set network.wan2_dev.name="wan2"
uci set network.wan2_dev.mac="aa:bb:cc:dd:ee:ff"
uci commit network
 
cat << "EOF" > /etc/rc.local
NET_DEVS="$(ls /sys/class/net/*/device/uevent \
    | awk -F '/' '{print $5}')"
for NET_DEV0 in ${NET_DEVS}
do
    NET_MAC0="$(cat /sys/class/net/"${NET_DEV0}"/address)"
    I="0"
    while uci -q get network.@device["${I}"] > /dev/null
    do
        NET_DEV="$(uci -q get network.@device["${I}"].name)"
        NET_MAC="$(uci -q get network.@device["${I}"].mac)"
        if [ -n "${NET_DEV}" -a -n "${NET_MAC}" ] \
        && [ "${NET_MAC}" = "${NET_MAC0}" ]
        then
            ip link set "${NET_DEV0}" down
            ip link set "${NET_DEV0}" name "${NET_DEV}"
        fi
    done
done
/etc/init.d/network reload
EOF
sh /etc/rc.local

If you have a DSL modem you can add logging of DSL status changes and connection data rates.

This can be helpful if your DSL connection is affected by Seamless Rate Adaptation (SRA) or Dynamic Line Management (DLM) events; for SRA events data rate changes will be logged, while for DLM events connection status changes will be logged as the modem is forced to retrain and then the new data rates will be logged.

cat << "EOF" > /etc/hotplug.d/dsl/20-dsl_status
case "${DSL_NOTIFICATION_TYPE}" in
    "DSL_INTERFACE_STATUS")    logger -p daemon.notice -t "dsl-notify" "${DSL_XTU_STATUS} link status: ${DSL_INTERFACE_STATUS}";;
    "DSL_DATARATE_STATUS_US")  logger -p daemon.notice -t "dsl-notify" "DSL upstream actual data rate: ${DSL_DATARATE_US_BC0}";;
    "DSL_DATARATE_STATUS_DS")  logger -p daemon.notice -t "dsl-notify" "DSL downstream actual data rate: ${DSL_DATARATE_DS_BC0}";;
esac
EOF

Note that this example script assumes that channel bonding is not compiled in to the DSL support.