Provided by: logkeys_0.1.1a+git5ef6b0dcb9e3-2_amd64 
NAME
logkeys - a GNU/Linux keylogger that works!
SYNOPSIS
logkeys -s [-m keymap | -u] [-o logfile] [-d device]
[--no-func-keys] [--no-timestamps]
[--post-http=URL] [--post-size=SIZE]
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.
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 output 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.
--no-timestamps
When this option is set, logkeys doesn't prepend timestamp to each line of log
file. Timestamps are only logged when logkeys starts and stops.
--post-size=SIZE
When log size reaches SIZE, the current log filename is appended .X, where X is
ascending number (e.g. logfile.1).
When that happens, logkeys starts remote uploading process and all logfile.X files
are uploaded as specified by --post-http or --post-irc options.
If --post-size is set, but no post method is set, then the logfile is only
truncated when it reaches SIZE, renamed to logfile.X, and a new blank logfile is
created for active logging.
If --post-size is not set, but post method is, then the default SIZE of 500 KB
(500.000 B) is used.
If --post-size is not set, and neither is any post method, then logkeys appends to
the single specified log file.
SIZE can be an integer bytesize, or an intger followed by K or M for kilobytes or
megabytes, respectively.
--post-http=URL
This option tells logkeys to POST the log file to URL, where it is preferrably
greeted by a (PHP) script.
The file is sent with header Content-Type: multipart/form-data as file, so it is
accessible in PHP via $_FILES['file'] variable.
FILES
/var/log/logkeys.log
When -o option is not used, logkeys appends to this default log file.
etc/logkeys-start.sh
Setuid root program llk runs this script. Edit the contents to suit your needs.
etc/logkeys-stop.sh
Setuid root program llkk runs this script. Default value should work well.
LOGFILE FORMAT
Log files are UTF-8 encoded.
Each logging session is enclosed in "Logging started... [<timestamp>]" 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 (provided --no-timestamps is
not in effect).
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 decimal
figure is not to be relied on.
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 such error strings.
Using US keyboard layout, one example log file could look like:
Logging started ...
2009-12-11 09:58:17+0100 > llk
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 > llkk
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 > llk
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 > llkk
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 one and up to three space-delimited characters on character key lines
(first without modifiers, optional 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 106 lines for 106 keys, even if some of those keys
aren't located on your keyboard. Lines 1, 14, 15, 28, 29, 42, 54-83, 85-106 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 the 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 use a custom event device (e.g. /dev/input/event4):
$ logkeys --start --device event4
To end running logkeys process:
$ logkeys --kill
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> with much help from the
community.
You can always obtain the latest version and information at project website:
<http://code.google.com/p/logkeys/>.
2010-05-25 logkeys(8)