NAME
logkeys - a GNU/Linux keylogger that works!
SYNOPSIS
logkeys -s [-m keymap|-u] [-o logfile] [-d device] [--no-func-keys]
logkeys -k
logkeys [--export-keymap=keymap]
DESCRIPTION
logkeys is a linux keylogger. It is no more advanced than other
available linux keyloggers, notably lkl and uberkey, but is a bit
newer, more up to date, it doesn’t unreliably repeat keys and it
shouldn’t crash your X. All in all, it just seems to work. It relies on
the event interface of Linux input subsystem (normally devices
/dev/input/eventX).
Once set, it logs all common character and function keys, while also
being fully aware of Shift and AltGr key modifiers. It tries to
automatically determine the correct input device, and may in some cases
also get the character keys mapping right.
It is installed setuid root and may be invoked by any user anytime,
either directly or using the accompanying lkl and lklk scripts.
OPTIONS
Non-optional arguments are required for short options too.
-s, --start
Starts the keylogging daemon process.
-k, --kill
Terminates the running logkeys process.
-o, --output=logfile
Set ouput log file to logfile. If no -o option is provided,
logkeys appends to /var/log/logkeys.log file. If logfile doesn’t
exist, logkeys creates the file with 600 permissions.
See also LOGFILE FORMAT section.
-m, --keymap=keymap
Use file keymap as input keymap for processing pressed keys.
This option works best if keymap is hand corrected file, which
had been previously exported by --export-keymap.
See also KEYMAP FORMAT section.
-m and -u option are mutually exclusive.
-d, --device=device
Use device as keyboard input event device instead of
/dev/input/eventX default.
You can determine the keyboard device to be used by examining
/proc/bus/input/devices.
-u, --us-keymap
This option makes logkeys interpret keys as on standard US
keyboard.
-u and -m option are mutually exclusive.
--export-keymap=keymap
This option makes logkeys export dynamic keymap as obtained from
dumpkeys(1) to file keymap and then exit.
keymap can later be used with -m option to override automatic
keymap "calculation", which may be wrong.
It is advised that you manually edit keymap and correct any
mistakes as well as complete deficient entries. It is also
advised that you use --export-keymap on a virtual terminal
outside of X (/dev/ttyX).
See section KEYMAP FORMAT for exported keymap format.
--no-func-keys
This option makes logkeys log all and only character key presses
(1, 2, ..., q, w, e, ..., a, s, d, f, ..., ", @, \, ...).
This option may be useful when correct keymap can reliably be
expected (i.e. by providing it with -m option). Then only
character keys are logged, influenced by Shift and AltGr
modifiers.
FILES
/var/log/logkeys.log
When -o option is not used, logkeys appends to default log file.
LOGFILE FORMAT
Log files are UTF-8 encoded.
Each logging session is enclosed in "Logging started..." and "Logging
stopped at <timestamp>" strings. Whenever Enter key (Return key) or
Ctrl+C or Ctrl+D combination is pressed, a timestamp is appended on a
new line.
Timestamp format is "%F %T%z", which results in "YYYY-mm-dd
HH:MM:SS+ZZZZ". Timestamp is separated from the logged keys by one ’>’
symbol.
All character key presses are logged as they appear. All function key
presses are replaced with strings as obtained from keymap file, or as
hardcoded when no keymap file is provided.
If a key is pressed down long enough so it repeats, it is logged only
once and then "<#+DD>" is appended, which hints the key was repeated DD
more times. The DD figure is not to be relied on. DD is in decimal
format.
If a keypress results in keycode, which is not recognized (i.e. key not
found on a standard US or Intl 105-key keyboard), then the string "<E-
XX>" is appended, where XX is the received keycode in hexadecimal
format. All new "WWW", "E-Mail", "Volume+", "Media", "Help", etc. keys
will result in this error string.
Using US keyboard layout, one example log file could look like:
Logging started ...
2009-12-11 09:58:17+0100 > lkl
2009-12-11 09:58:20+0100 > sudo cp <RShift>~/foo.<Tab> /usr/bin
2009-12-11 09:58:26+0100 > <LShift>R00<LShift>T_p455\\/0rD
2009-12-11 09:58:39+0100 > <Up><Up><Home>sudo
2009-12-11 09:58:44+0100 > c<#+53><BckSp><#+34><LCtrl>c
2009-12-11 09:58:54+0100 > lklk
Logging stopped at 2009-12-11 09:58:54+0100
If the same log was obtained by a logkeys process invoked with --no-
func-keys option, it would look like:
Logging started ...
2009-12-11 09:58:17+0100 > lkl
2009-12-11 09:58:20+0100 > sudo cp ~/foo. /usr/bin
2009-12-11 09:58:26+0100 > R00T_p455\\/0rD
2009-12-11 09:58:39+0100 > sudo
2009-12-11 09:58:44+0100 > c<#+53>c
2009-12-11 09:58:54+0100 > lklk
Logging stopped at 2009-12-11 09:58:54+0100
Even when --no-func-keys is in effect, Space and Tab key presses are
logged as a single space character.
KEYMAP FORMAT
The keymap file is expected to be UTF-8 encoded.
Each line of file represents either one character key or one function
key. The format specifies at least two and up to three space-delimited
characters on character key lines (first without modifiers, second with
Shift in action, optional third with AltGr in action), and up to 7
characters long string on function key lines.
First three lines in a Slovene keymap file look like:
<Esc>
1 ! ~
2 " Ë
How does one know which lines belong to character keys and which lines
to function keys?
Well, the easiest way is to use --export-keymap, and examine the
exported keymap. Make sure you export in a virtual terminal (ttyX) and
not in X as this way more keys could get exported correctly (don’t ask
me why).
Basically, --export-keymap ouputs 105 lines for 105 keys, even if some
of those keys aren’t located on your keyboard. Lines 1, 14, 15, 28, 29,
42, 54-83, 85-105 belong to function keys, all other lines (2-13,
16-27, 30-41, 43-53, 84) belong to character keys.
Line 57 is reserved for Space and it should always be ’ ’. Line 84 is
reserved for the key just right to left Shift that is present on some
international layouts. Other lines can be quite reliably determined by
looking at one exported keymap. The keys generally follow the order of
their appearance on keyboard, top-to-bottom left-to-right.
If you create full and completely valid keymap for your particular
language, please upload it to project website or send it to me by e-
mail. Thanks.
EXAMPLES
To print short help:
$ logkeys
To start logging to a custom log file with dynamically generated
keymap:
$ logkeys --start --output /home/user/.secret/log
To start logging to default log file on a standard US keyboard:
$ logkeys --start --us-keymap
To export dynamically generated keymap to file:
$ logkeys --export-keymap my_keymap
To start logging to default log file with a custom keymap:
$ logkeys --start --keymap my_keymap
To end running logkeys process:
$ logkeys --kill
After updated to one’s liking, helper scripts /usr/bin/lkl (start) and
/usr/bin/lklk (kill) can be used as well.
BUGS
logkeys relies on numeric output of dumpkeys(1), which keymaps(5)
manual page specifically discourages as unportable.
Be nice and hope nothing breaks.
If you come across any bugs, please report them on project website,
issues page:
http://code.google.com/p/logkeys/issues
AUTHOR
logkeys was written by Kernc <kerncece+logkeys@gmail.com>.
You can always obtain the latest version and information at project
website: <http://code.google.com/p/logkeys/>.
2009-12-13 logkeys(8)