2010-05-31 23:31:50 +02:00
|
|
|
|
.TH logkeys 8 2010-05-25
|
2009-12-13 11:56:57 +01:00
|
|
|
|
.SH NAME
|
|
|
|
|
logkeys \- a GNU/Linux keylogger that works!
|
|
|
|
|
.SH SYNOPSIS
|
2010-06-04 14:11:53 +02:00
|
|
|
|
.B logkeys \fB-s\fR [\fB-m \fIkeymap\fR | \fB-u\fR] [\fB-o \fIlogfile\fR] [\fB-d \fIdevice\fR]
|
2009-12-13 11:56:57 +01:00
|
|
|
|
.br
|
2010-05-31 23:31:50 +02:00
|
|
|
|
[\fB--no-func-keys\fR] [\fB--no-timestamps\fR]
|
2009-12-13 11:56:57 +01:00
|
|
|
|
.br
|
2010-06-04 14:11:53 +02:00
|
|
|
|
[\fB--post-http=\fIURL\fR] [\fB--post-size=\fISIZE\fR]
|
2010-05-31 23:31:50 +02:00
|
|
|
|
.br
|
|
|
|
|
.B logkeys \fB-k\fR
|
|
|
|
|
.br
|
|
|
|
|
.B logkeys [\fB--export-keymap=\fIkeymap\fR]
|
|
|
|
|
|
|
|
|
|
|
2009-12-13 11:56:57 +01:00
|
|
|
|
.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
|
2010-04-22 21:36:22 +02:00
|
|
|
|
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).
|
2010-05-31 23:31:50 +02:00
|
|
|
|
|
|
|
|
|
|
2009-12-13 11:56:57 +01:00
|
|
|
|
.SH OPTIONS
|
|
|
|
|
Non-optional arguments are required for short options too.
|
2010-05-31 23:31:50 +02:00
|
|
|
|
|
2009-12-13 11:56:57 +01:00
|
|
|
|
.TP
|
|
|
|
|
\fB-s\fR, \fB-\-start\fR
|
|
|
|
|
Starts the keylogging daemon process.
|
2010-05-31 23:31:50 +02:00
|
|
|
|
|
2009-12-13 11:56:57 +01:00
|
|
|
|
.TP
|
|
|
|
|
\fB-k\fR, \fB-\-kill\fR
|
|
|
|
|
Terminates the running logkeys process.
|
2010-05-31 23:31:50 +02:00
|
|
|
|
|
2009-12-13 11:56:57 +01:00
|
|
|
|
.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.
|
2010-05-31 23:31:50 +02:00
|
|
|
|
|
2009-12-13 11:56:57 +01:00
|
|
|
|
.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.
|
2010-05-31 23:31:50 +02:00
|
|
|
|
|
2009-12-13 11:56:57 +01:00
|
|
|
|
.TP
|
2010-01-05 17:15:28 +01:00
|
|
|
|
\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.
|
2010-05-31 23:31:50 +02:00
|
|
|
|
|
2010-01-05 17:15:28 +01:00
|
|
|
|
.TP
|
2009-12-13 11:56:57 +01:00
|
|
|
|
\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.
|
2010-05-31 23:31:50 +02:00
|
|
|
|
|
2009-12-13 11:56:57 +01:00
|
|
|
|
.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.
|
2010-05-31 23:31:50 +02:00
|
|
|
|
|
2009-12-13 11:56:57 +01:00
|
|
|
|
.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.
|
2010-05-31 23:31:50 +02:00
|
|
|
|
|
|
|
|
|
.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
|
2010-06-04 17:14:59 +02:00
|
|
|
|
If \fB--post-size\fR is set, but no post method is set, 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
|
|
|
|
|
If \fB--post-size\fR is not set, but post method is, then the default \fISIZE\fR of
|
|
|
|
|
500 KB (500.000 B) is used.
|
|
|
|
|
.IP
|
|
|
|
|
If \fB--post-size\fR is not set, and neither is any post method, then logkeys appends
|
|
|
|
|
to the single specified log file.
|
2010-05-31 23:31:50 +02:00
|
|
|
|
.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
|
2010-12-23 02:57:24 +01:00
|
|
|
|
is accessible in PHP via $_FILES['file'] variable.
|
2010-05-31 23:31:50 +02:00
|
|
|
|
|
2009-12-13 11:56:57 +01:00
|
|
|
|
.SH FILES
|
|
|
|
|
.TP
|
|
|
|
|
\fB/var/log/logkeys.log\fR
|
2010-06-04 14:11:53 +02:00
|
|
|
|
When \fB-o\fR option is not used, logkeys appends to this default log file.
|
|
|
|
|
.TP
|
|
|
|
|
\fBetc/logkeys-start.sh\fR
|
|
|
|
|
Setuid root program \fIllk\fR runs this script. Edit the contents to suit your needs.
|
|
|
|
|
.TP
|
|
|
|
|
\fBetc/logkeys-stop.sh\fR
|
|
|
|
|
Setuid root program \fIllkk\fR runs this script. Default value should work well.
|
2010-05-31 23:31:50 +02:00
|
|
|
|
|
|
|
|
|
|
2009-12-13 11:56:57 +01:00
|
|
|
|
.SH "LOGFILE FORMAT"
|
|
|
|
|
Log files are \fBUTF-8 encoded\fR.
|
|
|
|
|
.PP
|
2010-06-04 14:11:53 +02:00
|
|
|
|
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
|
|
|
|
|
\fB--no-timestamps\fR is not in effect).
|
2009-12-13 11:56:57 +01:00
|
|
|
|
.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
|
2010-06-04 14:11:53 +02:00
|
|
|
|
"<#+DD>" is appended, which hints the key was repeated DD more times. The DD decimal
|
|
|
|
|
figure is not to be relied on.
|
2009-12-13 11:56:57 +01:00
|
|
|
|
.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",
|
2010-06-04 14:11:53 +02:00
|
|
|
|
"Help", etc. keys will result in such error strings.
|
2009-12-13 11:56:57 +01:00
|
|
|
|
.PP
|
|
|
|
|
Using US keyboard layout, one example log file could look like:
|
|
|
|
|
.IP
|
|
|
|
|
Logging started ...
|
|
|
|
|
.IP
|
2010-04-22 21:36:22 +02:00
|
|
|
|
2009-12-11 09:58:17+0100 > llk
|
2009-12-13 11:56:57 +01:00
|
|
|
|
.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-14 12:59:07 +01:00
|
|
|
|
2009-12-11 09:58:44+0100 > c<#+53><BckSp><#+34><LCtrl>c
|
|
|
|
|
.br
|
2010-04-22 21:36:22 +02:00
|
|
|
|
2009-12-11 09:58:54+0100 > llkk
|
2009-12-13 11:56:57 +01:00
|
|
|
|
.IP
|
2009-12-14 12:59:07 +01:00
|
|
|
|
Logging stopped at 2009-12-11 09:58:54+0100
|
2009-12-13 11:56:57 +01:00
|
|
|
|
.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
|
2010-04-22 21:36:22 +02:00
|
|
|
|
2009-12-11 09:58:17+0100 > llk
|
2009-12-13 11:56:57 +01:00
|
|
|
|
.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-14 12:59:07 +01:00
|
|
|
|
2009-12-11 09:58:44+0100 > c<#+53>c
|
|
|
|
|
.br
|
2010-04-22 21:36:22 +02:00
|
|
|
|
2009-12-11 09:58:54+0100 > llkk
|
2009-12-13 11:56:57 +01:00
|
|
|
|
.IP
|
2009-12-14 12:59:07 +01:00
|
|
|
|
Logging stopped at 2009-12-11 09:58:54+0100
|
2009-12-13 11:56:57 +01:00
|
|
|
|
.PP
|
|
|
|
|
Even when \fB-\-no-func-keys\fR is in effect, Space and Tab key presses are logged as
|
|
|
|
|
a single space character.
|
2010-05-31 23:31:50 +02:00
|
|
|
|
|
|
|
|
|
|
2009-12-13 11:56:57 +01:00
|
|
|
|
.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.
|
2010-06-04 14:11:53 +02:00
|
|
|
|
The format specifies \fBat least one\fR and \fBup to three\fR space-delimited
|
|
|
|
|
characters on character key lines (first without modifiers, optional second with Shift in
|
2009-12-13 11:56:57 +01:00
|
|
|
|
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
|
2010-04-13 14:37:58 +02:00
|
|
|
|
Basically, \fB-\-export-keymap\fR ouputs 106 lines for 106 keys, even if some of
|
2009-12-13 11:56:57 +01:00
|
|
|
|
those keys aren't located on your keyboard. Lines 1, 14, 15, 28, 29, 42, 54-83,
|
2010-04-13 14:37:58 +02:00
|
|
|
|
85-106 belong to function keys, all other lines (2-13, 16-27, 30-41, 43-53, 84)
|
2009-12-13 11:56:57 +01:00
|
|
|
|
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.
|
2010-06-04 14:11:53 +02:00
|
|
|
|
The keys generally follow the order of their appearance on the keyboard, top-to-bottom
|
2009-12-13 11:56:57 +01:00
|
|
|
|
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.
|
2010-05-31 23:31:50 +02:00
|
|
|
|
|
|
|
|
|
|
2009-12-13 11:56:57 +01:00
|
|
|
|
.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
|
2010-04-22 21:36:22 +02:00
|
|
|
|
To use a custom event device (e.g. /dev/input/event4):
|
|
|
|
|
.IP
|
|
|
|
|
$ logkeys --start --device event4
|
|
|
|
|
.PP
|
2009-12-13 11:56:57 +01:00
|
|
|
|
To end running logkeys process:
|
|
|
|
|
.IP
|
|
|
|
|
$ logkeys --kill
|
|
|
|
|
.PP
|
2010-04-22 21:36:22 +02:00
|
|
|
|
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.
|
2010-05-31 23:31:50 +02:00
|
|
|
|
|
|
|
|
|
|
2009-12-13 11:56:57 +01:00
|
|
|
|
.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
|
2016-02-10 18:36:52 +01:00
|
|
|
|
https://github.com/kernc/logkeys/issues/
|
2009-12-13 11:56:57 +01:00
|
|
|
|
.SH AUTHOR
|
|
|
|
|
.PP
|
2010-05-31 23:31:50 +02:00
|
|
|
|
logkeys was written by Kernc <kerncece+logkeys@gmail.com> with much help from the community.
|
2009-12-13 11:56:57 +01:00
|
|
|
|
.PP
|
|
|
|
|
You can always obtain the latest version and information at project website:
|
2016-02-10 18:36:52 +01:00
|
|
|
|
<https://github.com/kernc/logkeys/issues/>.
|