aboutsummaryrefslogtreecommitdiff
path: root/README
blob: e7fedf49d40250f0c6e27d9705dba9ab86c7f799 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
Inputfwd is a set of Linux tools for creating virtual input devices (using
uinput) that mirror input from source devices. The source devices may be added
and removed dynamically during the virtual device lifetime.

Inputfwd was developed for gaming in unprivileged LXC containers, when input
devices may appear and disappear dynamically. Statically mounting them on
container boot is then too limiting. The solution is then to
- create virtual devices that will exist throughout the containeer's lifetime
- start the container with those virtual devices
- dynamically forward real devices to those virtual devices, as they are added
  and removed

This also solves the problem of the container seeing input it shouldn't (e.g.
passwords entered on the host) - just disconnect the device temporarily.

Inputfwd is written in Python 3 and depends on the evdev package. Due to that
dependency it can only run on Linux. It is licensed under GPL version 3.

The project consists of the following tools:

inputdev_describe
-----------------
Helper tool that creates input device descriptions from an existing input
device and prints them to stdout. Simply run it on a desired /dev/input/event*
node and redirect the output to ~/.local/var/inputfwd/<name>.desc.

uinput_mng
----------
The main tool - it creates and manages a virtual (uinput) device based on a
description created by inputdev_describe. It accepts as argument the <name> of
the device description, i.e. corresponding to a
~/.local/var/inputfwd/<name>.desc file. You may also pass an absolute path to
the description, if you really want the files to live somewhere else.

Binding and unbinding real devices to the virtual device is done through the
control fifo, which is created in ~/.cache/inputfwd/<name> (location may be
customized with the -c option).

Simply write the commands to this FIFO, e.g. by
  echo "command" > ~/.cache/inputfwd/<name>

The commands are:
* add <device path>
  Adds the corresponding device node (e.g.
  /dev/input/eventxx). Input events from that device will be forwarded to the
  virtual device. Force-feedback events sent to the virtual device will be
  forwarded up to the real device.
* remove <device path>
  Removes the previously added device node, i.e. events from it will no longer
  be forwarded. Devices are also automatically removed from uinput_mng if they
  are disconnected.
* list
  Lists all currently bound device paths.
* clear
  Remove all currently bound devices.

dev_add
-------
A helper tool that accepts the name (or full path) of the control FIFO and a
regex pattern. It adds all input devices whose name matches the pattern
(monitoring newly newly added devices using udevadm). On exit it clears all
bound devices (unless the --no-clear option is used).