
BUILDING / INSTALLING LKRG:
---------------------------

Before LKRG can be installed, first it needs to be gathered and built
(compiled). The following document describes build process which should work
on any Linux distribution.


GETTING THE SOURCES:
--------------------

LKRG is being hosted on the bitbucket git repository, which can be cloned to
the local directory via following command:

    $ git clone https://bitbucket.org/Adam_pi3/lkrg-main.git

There is also separate version of the project kept under "experimental" branch
and you can read about it more here:

    https://openwall.info/wiki/p_lkrg/Protected_Features

If you do not want to use Git, you can also obtain tarballs from the Openwall
website and verify the signature of the packages:

    $ wget https://www.openwall.com/signatures/openwall-offline-signatures.asc
    $ gpg --import openwall-offline-signatures.asc
    $ wget https://www.openwall.com/lkrg/lkrg-0.6.tar.gz.sign
    $ wget https://www.openwall.com/lkrg/lkrg-0.6.tar.gz
    $ gpg --verify lkrg-0.6.tar.gz.sign lkrg-0.6.tar.gz


BUILD REQUIREMENTS:
-------------------

To be able to compile any Linux kernel module you will need the following
software:

- GNU make
- A C compiler (the best will be the same which was used to compile kernel
  itself)
- A kernel build directory corresponding to the Linux kernel image the module
  is to run on. Under Debian and Ubuntu, for example, each linux-image package
  containing a kernel binary has a corresponding linux-headers package with the
  required build infrastructure. E.g.
  -> Red Hat'ish (e.g. RHEL, CentOS, Fedora) distribution requires linux-devel
     package:
        $ sudo yum install kernel-devel
  -> Debian-based (e.g. Ubuntu) distribution requires linux-headers package:
        $ sudo apt-get install linux-headers-$(uname -r)


COMPILING:
----------

If you have correctly set-up kernel build directory then you can easily compile
LKRG via running 'make' command. It can be done from the normal user (non-root)
account:

     pi3@pi3-VM:~/lkrg-main$ make -j8


INSTALLATION:
-------------

Installation of LKRG is exactly the same as loading normal kernel module. As
soon as system is installed it starts the work. If default logging level is
used, LKRG produces one short sentence saying that system is clean unless
corruptions are detected.

    pi3@pi3-VM:~/lkrg-main$ modinfo output/p_lkrg.ko
    filename:       /home/pi3/lkrg-main/output/p_lkrg.ko
    license:        GPL
    description:    pi3's Linux kernel Runtime Guard
    author:         Adam 'pi3' Zabrocki (http://pi3.com.pl)
    srcversion:     0732EECE0E4A7E4C51A09B3
    depends:
    name:           p_lkrg
    vermagic:       4.13.0-31-generic SMP mod_unload
    parm:           p_init_log_level:Logging level init value [1 (alive) is default] (uint)
    pi3@pi3-VM:~/lkrg-main$ sudo insmod output/p_lkrg.ko p_init_log_level=3
    [sudo] password for pi3:
    pi3@pi3-VM:~/lkrg-main$ sudo tail /var/log/kern.log
    Jan 29 17:33:58 pi3-VM kernel: [201258.270920] p_lkrg: loading out-of-tree module taints kernel.
    Jan 29 17:33:58 pi3-VM kernel: [201258.270964] p_lkrg: module verification failed: signature and/or required key missing - tainting kernel
    Jan 29 17:33:58 pi3-VM kernel: [201258.273105] [p_lkrg] Loading LKRG...
    Jan 29 17:33:59 pi3-VM kernel: [201258.590589] [p_lkrg] LKRG initialized successfully!
    Jan 29 17:34:14 pi3-VM kernel: [201273.828062] [p_lkrg] System is clean!
    pi3@pi3-VM:~/lkrg-main$

We have also prepared early boot systemd unit file. Similar optional
functionality for other init systems may be added later. You can install LKRG
using Makefile:

    root@pi3-ubuntu:~/lkrg-main# make install
    make -C /lib/modules/4.8.0-53-generic/build M=/root/lkrg-main modules_install
    make[1]: Entering directory '/usr/src/linux-headers-4.8.0-53-generic'
      DEPMOD  4.8.0-53-generic
    make[1]: Leaving directory '/usr/src/linux-headers-4.8.0-53-generic'
    depmod -a
    /root/lkrg-main/scripts/bootup/lkrg-bootup.sh install
     [*] Executing LKRG's bootup installation script
      [+] Systemd detected
           Installing lkrg.service file under /lib/systemd/system folder
           Enabling lkrg.service on bootup
    Created symlink from /etc/systemd/system/multi-user.target.wants/lkrg.service to /lib/systemd/system/lkrg.service.
           To start lkrg.service please use: systemctl start lkrg
      [+] Done!

Please do not forget to run the following command to start LKRG service:

    systemctl start lkrg

You can uninstall LKRG using Makefile as well:

    root@pi3-ubuntu:~/lkrg-main# make uninstall
    /root/lkrg-main/scripts/bootup/lkrg-bootup.sh uninstall
     [*] Executing LKRG's bootup installation script
      [+] Systemd detected
           Stopping lkrg.service
           Disabling lkrg.service on bootup
    Removed symlink /etc/systemd/system/multi-user.target.wants/lkrg.service.
           Deleting lkrg.service file from the /lib/systemd/system folder
      [+] Done!

You can also use the following command to temporarily stop LKRG service without
uninstalling it:

    systemctl stop lkrg


COMMUNICATION CHANNEL:
----------------------

The project has a built-in sysctl interface, which enables the interaction
between the administrator and LKRG. The following options are available:

    root@pi3-ubuntu:~/p_lkrg-main# sysctl -a | grep lkrg
    lkrg.block_modules = 0
    lkrg.ci_panic = 0
    lkrg.clean_message = 1
    lkrg.force_run = 0
    lkrg.log_level = 1
    lkrg.random_events = 1
    lkrg.timestamp = 15

 -> Blocking module functionality (lkrg.block_modules) - only two options are
    available:
        0 - do NOT lock the kernel and allow to load kernel module
        1 - lock the kernel and do NOT allow to load kernel module
 -> Kernel panic on CI failure (lkrg.ci_panic) - only two options are
    available:
        0 - do NOT crash the kernel on CI failure (default)
        1 - crash the kernel (call panic()) on CI failure
 -> Printing "System is clean!" message (lkrg.clean_message) - only two options
    are available:
        0 - do NOT print "System is clean!" message regardless of log_level
            value
        1 - if log_level value allows it, print "System is clean!" message
 -> Force (lkrg.force_run) - forces LKRG to run integrity function right now.
    It is always visible as 0 number. Nevertheless, if you set it to 1, the
    integrity checking function will be immediately fired and value restored to
    0 again
 -> log level (lkrg.log_level) - it might be a number between 0-4 or 0-6 (if
    debugging compilation was used). A strong debug provides very useful data
    to identify where could be a specific problem with LKRG (if it ever
    appears). Unfortunately, it produces tons of logs per execution and must be
    used only for debugging purpose, not as a normal run.
 -> Random events (lkrg.random_events) - only two options are available:
        0 - do NOT perform integrity checking on the random events (perform it
            only at regular intervals configured by lkrg.timestamp)
        1 - perform integrity checking on the random events (as well as at the
            regular intervals)
 -> timestamp (lkrg.timestamp) - changes how often kernel timer will be
    launched (kernel timer periodically calls integrity function). It can't be
    less than 5 seconds (not to eat too much system resources) and not more
    than 1800 seconds (half an hour) - not to be silent for too long
