logkeys/man/logkeys.8

.TH logkeys 8 2010-05-25
.SH NAME
logkeys \- a GNU/Linux keylogger that works!
.SH SYNOPSIS
.B logkeys \fB-s\fR [\fB-m \fIkeymap\fR|\fB-u\fR] [\fB-o \fIlogfile\fR] [\fB-d \fIdevice\fR]
.br
           [\fB--no-func-keys\fR] [\fB--no-timestamps\fR] 
.br
           [\fB--post-size=\fISIZE\fR] [\fB--post-http=\fIURL\fR]
.br
.B logkeys \fB-k\fR
.br
.B logkeys [\fB--export-keymap=\fIkeymap\fR]


.SH DESCRIPTION
logkeys is a linux keylogger. It is no more advanced than other available linux
keyloggers, notably \fBlkl\fR and \fBuberkey\fR, 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 \fI/dev/input/eventX\fR).
.PP
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.
.PP
Two helper \fBsetuid root\fR programs are shipped with logkeys. \fIllk\fR, which runs 
\fIetc/logkeys-start.sh\fR script, and \fIllkk\fR, which runs \fIetc/logkeys-kill.sh\fR script.
Because llk and llkk are installed setuid root, you can edit the two .sh scripts
(mostly just logkeys-start.sh) to your preference, then issue logkeys via llk whenever 
you have to run it covertly (e.g. when you don't want to su to root or type sudo password).


.SH OPTIONS
Non-optional arguments are required for short options too.

.TP
\fB-s\fR, \fB-\-start\fR
Starts the keylogging daemon process.

.TP
\fB-k\fR, \fB-\-kill\fR
Terminates the running logkeys process.

.TP
\fB-o\fR, \fB-\-output\fR=\fIlogfile\fR
Set ouput log file to \fIlogfile\fR. If no \fB-o\fR option is provided, logkeys
appends to \fI/var/log/logkeys.log\fR file. If \fIlogfile\fR doesn't exist, logkeys
creates the file with 600 permissions.
.IP
See also \fBLOGFILE FORMAT\fR section.

.TP
\fB-m\fR, \fB-\-keymap\fR=\fIkeymap\fR
Use file \fIkeymap\fR as input keymap for processing pressed keys.
.IP
This option works best if \fIkeymap\fR is hand corrected file, which had been
previously exported by \fB--export-keymap\fR.
.IP
See also \fBKEYMAP FORMAT\fR section.
.IP
\fB-m\fR and \fB-u\fR option are mutually exclusive.

.TP
\fB-d\fR, \fB-\-device\fR=\fIdevice\fR
Use \fIdevice\fR as keyboard input event device instead of \fI/dev/input/eventX\fR default.
.IP
You can determine the keyboard device to be used by examining \fI/proc/bus/input/devices\fR.

.TP
\fB-u\fR, \fB-\-us-keymap\fR
This option makes logkeys interpret keys as on standard US keyboard.
.IP
\fB-u\fR and \fB-m\fR option are mutually exclusive.

.TP
\fB-\-export-keymap\fR=\fIkeymap\fR
This option makes logkeys export dynamic keymap as obtained from \fIdumpkeys\fR(1)
to file \fIkeymap\fR and then exit.
.IP
\fIkeymap\fR can later be used with \fB-m\fR option to override automatic keymap 
"calculation", which may be wrong.
.IP
It is advised that you manually edit \fIkeymap\fR and correct any mistakes as well
as complete deficient entries. It is also advised that you use \fB-\-export-keymap\fR
on a virtual terminal outside of X (\fI/dev/ttyX\fR).
.IP
See section \fBKEYMAP FORMAT\fR for exported keymap format.

.TP
\fB-\-no-func-keys\fR
This option makes logkeys log all and only character key presses 
(1, 2, ..., q, w, e, ..., a, s, d, f, ..., ", @, \\, ...).
.IP
This option may be useful when correct \fIkeymap\fR can reliably be 
expected (i.e. by providing it with \fB-m\fR option). Then only character keys are
logged, influenced by Shift and AltGr modifiers.

.TP
\fB-\-no-timestamps\fR
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.

.TP
\fB-\-post-size=\fISIZE\fR
When log size reaches \fISIZE\fR, the current log filename is appended \fI.X\fR, 
where X is ascending number (e.g. \fIlogfile.1\fR).
.IP
When that happens, logkeys starts remote uploading process and all \fIlogfile.X\fR
files are uploaded as specified by \fB--post-http\fR or \fB--post-irc\fR options.
.IP
If \fB--post-size\fR is set, but no post method is set (i.e. neither \fB--post-http\fR
nor \fB--post-irc\fR), then the logfile is only truncated when it reaches 
\fISIZE\fR, renamed to \fIlogfile.X\fR, and a new blank logfile is created for 
active logging.
.IP
\fISIZE\fR can be an integer bytesize, or an intger followed by K or M for kilobytes 
or megabytes, respectively.

.TP
\fB-\-post-http=\fIURL\fR
This option tells logkeys to POST the log file to URL, where it is preferrably greeted 
by a (PHP) script.
.IP
The file is sent with header \fIContent-Type: multipart/form-data\fR as file, so it
is accessible in PHP via $_FILES variable.

.SH FILES
.TP
\fB/var/log/logkeys.log\fR
When \fB-o\fR option is not used, logkeys appends to default log file.


.SH "LOGFILE FORMAT"
Log files are \fBUTF-8 encoded\fR.
.PP
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.
.PP
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.
.PP
All character key presses are logged as they appear. All 
function key presses are replaced with strings as obtained from \fIkeymap\fR file, or
as hardcoded when no \fIkeymap\fR file is provided.
.PP
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.
.PP
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.
.PP
Using US keyboard layout, one example log file could look like:
.IP
Logging started ...
.IP
2009-12-11 09:58:17+0100 > llk
.br
2009-12-11 09:58:20+0100 > sudo cp <RShift>~/foo.<Tab> /usr/bin
.br
2009-12-11 09:58:26+0100 > <LShift>R00<LShift>T_p455\\\\/0rD
.br
2009-12-11 09:58:39+0100 > <Up><Up><Home>sudo
.br
2009-12-11 09:58:44+0100 > c<#+53><BckSp><#+34><LCtrl>c
.br
2009-12-11 09:58:54+0100 > llkk
.IP
Logging stopped at 2009-12-11 09:58:54+0100
.PP
If the same log was obtained by a logkeys process invoked with \fB-\-no-func-keys\fR
option, it would look like:
.IP
Logging started ...
.IP
2009-12-11 09:58:17+0100 > llk
.br
2009-12-11 09:58:20+0100 > sudo cp ~/foo.  /usr/bin
.br
2009-12-11 09:58:26+0100 > R00T_p455\\\\/0rD
.br
2009-12-11 09:58:39+0100 > sudo
.br
2009-12-11 09:58:44+0100 > c<#+53>c
.br
2009-12-11 09:58:54+0100 > llkk
.IP
Logging stopped at 2009-12-11 09:58:54+0100
.PP
Even when \fB-\-no-func-keys\fR is in effect, Space and Tab key presses are logged as
a single space character.


.SH "KEYMAP FORMAT"
The keymap file is expected to be \fBUTF-8 encoded\fR.
.PP
Each line of file represents either one character key or one function key.
The format specifies \fBat least two\fR and \fBup to three\fR space-delimited 
characters on character key lines (first without modifiers, second with Shift in 
action, optional third with AltGr in action), and up to \fB7 characters long\fR
string on function key lines.
.PP
First three lines in a Slovene keymap file look like:
.IP
<Esc>
.br
1 ! ~
.br
2 " ˇ
.br
...
.PP
How does one know which lines belong to character keys and which lines to function
keys?
.PP
Well, the easiest way is to use \fB-\-export-keymap\fR, 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).
.PP
Basically, \fB-\-export-keymap\fR 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.
.PP
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 \fBexported keymap\fR.
The keys generally follow the order of their appearance on keyboard, top-to-bottom 
left-to-right.
.PP
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.


.SH EXAMPLES
To print short help:
.IP
$ logkeys
.PP
To start logging to a custom log file with dynamically generated keymap:
.IP
$ logkeys --start --output /home/user/.secret/log
.PP
To start logging to default log file on a standard US keyboard:
.IP
$ logkeys --start --us-keymap
.PP
To export dynamically generated keymap to file:
.IP
$ logkeys --export-keymap my_keymap
.PP
To start logging to default log file with a custom keymap:
.IP
$ logkeys --start --keymap my_keymap
.PP
To use a custom event device (e.g. /dev/input/event4):
.IP
$ logkeys --start --device event4
.PP
To end running logkeys process:
.IP
$ logkeys --kill
.PP
After \fIetc/logkeys-start.sh\fR is updated to one's liking, helper programs \fIbin/llk\fR (start) and 
\fIbin/llkk\fR (kill) can be used as well.


.SH BUGS
logkeys relies on numeric output of \fIdumpkeys\fR(1), which \fIkeymaps\fR(5)
manual page specifically discourages as unportable.
.PP
Be nice and hope nothing breaks.
.PP
If you come across any bugs, please report them on project website, issues page:
.IP
http://code.google.com/p/logkeys/issues/
.SH AUTHOR
.PP
logkeys was written by Kernc <kerncece+logkeys@gmail.com> with much help from the community.
.PP
You can always obtain the latest version and information at project website:
<http://code.google.com/p/logkeys/>.