Provided by: logkeys_0.1.1a+git5ef6b0dcb9e3-2_i386 bug

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)