The usbemergencybutton daemon allows to use USB keyboards, sometimes very specific ones with a single key like the emergency button below, to trigger a script without being logged. It is a tool targeted to launch actions on a Linux machine in case of emergency.
Example of USB button, defined by Vendor ID 0x2704 & Product ID 0x2018. See tools for more information.
A script is associated to a button press using configuration file and is launched synchronously or in background.
Every keyboards or buttons, considered as such by Linux Kernel and therefore identified as input devices, can be used with usbemergencybutton.
A device usable with usbemergencybutton is listed as keyboard in /proc/bus/input/devices. The Vendor ID and Product ID of such device is used
More information on how to retrieve those ID values with a shell script as well as examples of usable hardware is available in the tools directory.
The iniparser library written by Nicolas Devilla must be installed to run.
Development version of libiniparser needs also to be deployed in order to build usbemergency (linker directive -l iniparser is used during build)
To compile usbemergencybutton, just type
make -f Makefile.written
The resulting executable is in the build directory.
Install in /usr/local/bin using Makefile
sudo make -f Makefile.written install
Launch the daemon at startup (systemd file provided) after having prepared a configuration file.
Default location of configuration file is /etc/usbemergency.conf
This value can be overridden with -f parameters (see below).
In daemon mode only one instance of usbemergencybutton is able to run. It is enforced by use of /var/run/usbemergencybutton.pid file containing the PID value. This rule does not apply when instances are launched in debug mode (with the -d parameter see below) and no PID is created in this case.
If modified, the configuration file can be read again without restarting the service by sending the SIGHUP signal. Warning: when usbemergencybutton is launched as a daemon and the location of the configuration file is specified as relative value, the program won't be able te reload the file since the service is detached from any console and therefore its default path is root (/) directory. It is not a bug but a feature.
Normal termination of usbemergencybutton is expected with SIGTERM signal. In this case, the PID file is removed.
It is also possible to cleanly end usbemergencybutton with SIGINT signal but as the program is idle waiting for input, the device key must be pressed a last time in order to stop. PID file is also cleaned.
Finally, nothing can stop SIGQUIT and therefore the PID file is not cleaned when using this signal.
The daemon can be launched without parameters because default values are defined. However, the following parameters are available
-h: print help and exit-d: debug mode. Launch program in display mode (remain connected to console) without PID file (/var/run/usbemergencybutton.pid) being created.-f FILEset name of configuration file (default is/etc/usbemergencybutton.conf)-g: generate example configuration file and halt
The configuration file follow structure of .INI files
A sample of configuration file is provided: see usbemergency.conf.example
The configuration file is divided into two sections : the [Device] and the [Action] one.
false]
[Device] section contains daemons' settings.
vendor_ID =: vendor ID of USB device, expressed in hexadecimal, as shown in /proc/bus/input/devicesproduct_ID =: product ID of USB device, expressed in hexadecimal, as shown in /proc/bus/input/devicesexpect_specific_key = [true|;: Do we expect a specific key or any key stroke is valid?key_value =: Code of the expected key, expressed in hexadecimal, if detection is activated. See tools directory to know how to find such value.
[Action] section gathers definition of action to execute on button press.
asynchronous_launch = [false|true];Script to be launched in asynchronous mode (i.e. in background)? Default is false.script =: Script launched when the button is pressed. Default/bin/true
In the roadmap for next versions:
- Generate Makefile and compile using Autotools
- Write man page
- Add more automated tests
- Add support for translation
- package as RPM
The following links contain information used to design and code usbemergency and associated script tools .
- "Linux Keylogger: How to Read the Linux Keyboard Buffer". Extensive information on low level, close to the hardware, information available from input devices. Also contains hints used to write
list_event_devices.shdescribed in tools directory. - "Accessing Keys from Linux Input Device". Details how to get keyed values in low level events input method.
- "Is it possible for a daemon (i.e. background) process to look for key-presses from a USB keyboard?". Describes how to get low level events from a keyboard for a non interactive program. Also contains details on how to spot low level input events from a keyboard (hint: event flags array EV == 120013).
- "Get /dev/input/eventX from an attached USB device with PID:VID". Inspiration and hints to get input from a device with known Vendor and Product IDs.
- "Determine Linux keyboard events device". Extensively explains how to get information of event device number both by scripts and with C code.
This software is released under MIT License. See LICENSE for full informations