Kerberos.io
IntroductionArchitectures
Open Source
First things firstReleasesUpgradeInstallationKiOSRaspbianDockerGenericContributeLicenseMachineryWeb
Enterprise
Cloud

Installation

Kerberos Open Source comes with different installation flavours. So you might think, why? The reason is simple, depending on the use case one option is better than another. A short list of recommendations:

  1. KiOS: You have a Raspberry Pi, and you only want to run a Kerberos agent on it.
  2. Raspbian: You have a Raspberry Pi, but you want other services running next to the Kerberos agent.
  3. Docker: You have a lot of IP cameras, and/or don't want to mess with dependencies.
  4. Generic: You want to develop/extend Kerberos with your own features, or you want to run a Kerberos agent on a not supported OS/architecure.

KiOS

KiOS (Kerberos Operating System) is our custom linux OS, which runs the Kerberos agent out-of-the-box (read plug-and-play). It's an OS designed for the Raspberry Pi (all version are supported), which you can flash to an SD card.

It can be installed using our own installer, which comes with a nice interface that handles the flashing and network configuration for you, or you can handle the flashing yourself by using Etcher.

Github

KiOS is compiled using Buildroot, the project can be found on following Github repo.

Kerberos installer

Installing the Kerberos agent to your Raspberry Pi, has never been so easy. By using our cross-platform installer, you can run a fully configured video surveillance system within 3 minutes. Indeed, we also think that's awesome!

access kerberos installer

Download the correct installer for your OS below:

https://github.com/kerberos-io/etcher/releases

Etcher

If you love Etcher, or the Kerberos installer is not working as expected, you can also flash the Kerberos agent to your SD card manually. It goes as following:

  1. Download the KiOS image,
  2. flash it to your SD card with Etcher,
  3. and edit some configuration files at the boot directory.

use etcher for kios

Once you have download the KiOS image (make sure you downloaded the right image) and flashed it to an SD card, put it back into your working station. Navigate to the SD card and creating following files.

Connecting to WiFi

If you want to connect your Raspberry Pi to a WiFi connection, you will need to create a file wireless.conf on your SD card, with following contents. Change the SSID and password properties to your own WiFi credentials.

update_config=1
ctrl_interface=/var/run/wpa_supplicant
network={
  scan_ssid=1
  ssid=""
  psk=""
}

Setup a static IP-address

If you want to assign a static ip-address to your Raspberry Pi, create a file static_ip.conf on your SD card, with following contents:

#####################################################################
# Enter the IP-address you want to have, followed by the subnet mask
# e.g. 192.168.0.10/24
static_ip=""
#####################################################################
# Enter the Gateway and DNS, this will be your router in most cases
# e.g. 192.168.0.1
static_gw=""
static_dns=""

Power on the Raspberry Pi

Once you've finished the installation using either the KiOS installer or Etcher, you can put the SD card into your Raspberry Pi and turn it on. Please note that the first time you boot KiOS it can take about 2 mins before the system is operational. When KiOS is ready you can open your favorite browser and type in the IP address of your Raspberry Pi. This will open the Kerberos agent's front-end, which you can access with the username: root and password: root.

access kerberos interface

Access the Raspberry Pi

You can access the KiOS system with attaching your Raspberry Pi to a HDMI monitor or by using ssh.

Cedrics-Mac-mini:build cedricverst$ ssh root@192.168.0.12
Welcome to kios-79e30bbb!
[root@kios-79e30bbb ~]#

Note that by default no root password is set, you can define a password in the /data/etc/kios.conf file. Once you added a password, make sure to reboot the OS.

[root@kios-79e30bbb ~]# nano /data/etc/kios.conf
[root@kios-79e30bbb ~]# reboot

Raspbian

If you have already an OS (e.g. Raspbian Buster) flashed to your Raspberry Pi, then it makes sense to install the Kerberos agent on top of your existing OS. There are two ways to achieve this:

  1. Install the Kerberos agent using Docker (more info below),
  2. or you can install the Kerberos agent manually (machinery + web).

This section will focus on option 2, and will show you how to install the Kerberos agent manually.

Update OS

Let's start with updating the OS, and installing a couple of packages.

We have tested the Raspbian installation on Raspbian GNU/Linux 10 (buster). It might be that if you have a different version of Raspbian, you will need to install additional/different packages.

sudo apt-get update && sudo apt-get install -y ffmpeg

Machinery

Download the debian file from the machinery repository.

https://github.com/kerberos-io/machinery/releases

A .deb file is available for every version of the Raspberry Pi. For example if you are using a Raspberry Pi 4 for version 2.8.0, execute following command. You can change the version and Raspberry Pi board to your needs.

Please make sure you pick the right board (rpi, rpi2, rpi3 or rpi4), and choose the version you want (e.g. 2.8.0). Replace below url, with your preferences.

wget https://github.com/kerberos-io/machinery/releases/download/v2.8.0/rpi4-machinery-kerberosio-armhf-2.8.0.deb
sudo dpkg -i rpi4-machinery-kerberosio-armhf-2.8.0.deb

Download the x265 library (version 160) from the machinery repository, as Raspbian Buster 10 only ships with version 165. Make sure you select the right board.

v2.8.0/rpi4-libx265.so.160 this will download the libx265 shared library for the Raspberry Pi 4.

wget https://github.com/kerberos-io/machinery/releases/download/v2.8.0/rpi4-libx265.so.160
sudo mv rpi4-libx265.so.160 /usr/lib/arm-linux-gnueabihf/libx265.so.160

Same applies for the libx264 library, download the right shared library.

v2.8.0/rpi4-libx264.so.148 this will download the libx264 shared library for the Raspberry Pi 4.

wget https://github.com/kerberos-io/machinery/releases/download/v2.8.0/rpi4-libx264.so.148
sudo mv rpi4-libx264.so.148 /usr/lib/arm-linux-gnueabihf/libx264.so.148

If you wish to use the Raspberry Pi Camera Module, make sure to enable it using sudo raspi-config.

sudo raspi-config

Enable machinery to start on boot, and start the service.

sudo systemctl enable kerberosio
sudo service kerberosio start

Web

Before you can run the web interface, you'll need to download and configure a webserver. We recommend to use Nginx, as it is a light-weight and fast webserver. The web interface is written in PHP, so we also need to download PHP and some packages. Update the packages and kernel.

Install Nginx and PHP (+extensions).

sudo apt-get install -y nginx php7.1 php7.1-curl php7.1-gd php7.1-fpm php7.1-cli php7.1-opcache php7.1-mbstring php7.1-xml php7.1-zip php7.1-mcrypt php7.1-readline

Creating a Nginx config.

sudo rm -f /etc/nginx/sites-enabled/default
sudo nano /etc/nginx/sites-enabled/kerberosio.conf

Copy and paste following config file; this file tells nginx where the web will be installed and that it requires PHP.

server
{
    listen 80 default_server;
    listen [::]:80 default_server;
    root /var/www/web/public;
    server_name kerberos.rpi;
    index index.php index.html index.htm;
    location /
    {
            autoindex on;
            try_files $uri $uri/ /index.php?$query_string;
    }
    location ~ \.php$
    {
            fastcgi_pass unix:/var/run/php/php7.1-fpm.sock;
            fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
            include fastcgi_params;
    }
}

Restart nginx

sudo service nginx restart

Now we have installed all the dependencies, we can download the web interface source code.

sudo mkdir -p /var/www/web && sudo chown www-data:www-data /var/www/web
cd /var/www/web
sudo -u www-data wget https://github.com/kerberos-io/web/releases/download/v2.8.0/web.tar.gz
sudo -u www-data tar xvf web.tar.gz .
sudo chown www-data -R storage bootstrap/cache config/kerberos.php
sudo chmod -R 775 storage bootstrap/cache
sudo chmod 0600 config/kerberos.php

Once everything is setup correctly, you should be able to browse towards the ip-address of your Raspberry Pi and see the Kerberos web interface.

Auto removal

By default images or videos aren't removed automatically. This means that the Kerberos agent will keep writing to disk, even if there is no more space available on your SD card. When your SD card is full you'll be experiencing strange errors: a corrupt web interface, blank images or corrupt videos.

To resolve this your should install a simple bash script and initiate a cronjob which continuously poll your filesystem, and start removing media when your disk is getting full.

Create a bash script and copy following script.

nano /home/pi/autoremoval.sh

Copy following script (make sure the partition is correct, this is the default one for a Raspberry Pi).

partition=/dev/root
imagedir=/etc/opt/kerberosio/capture/
if [[ $(df -h | grep $partition | head -1 | awk -F' ' '{ print $5/1 }' | tr ['%'] ["0"]) -gt 90 ]];
then
    echo "Cleaning disk"
    find $imagedir -type f | sort | head -n 100 | xargs -r rm -rf;
fi;

Make the script executable.

chmod +x /home/pi/autoremoval.sh

Initiate a cronjob, and select the nano editor.

crontab -e

Append following line, to execute the autoremoval.sh script every 5min.

*/5 * * * * /bin/bash /home/pi/autoremoval.sh

Docker

A Docker image (x86, ARMv7, ARMv8) is available on the Docker Hub, which contains all the necessary software to setup the Kerberos agent in a matter of seconds. Before you can run this image, make sure you have Docker installed. Afterwards you can use docker, to get the Kerberos agent up and running. All docker images can be found on the Docker hub.

Prerequisites

Docker or Docker Desktop (Linux, OS or Windows)

Github

All technical information, such as Dockerfile, can be found on following Github repo.

Download docker image

Before you are able to run the Kerberos agent inside a container, you will need to pull the docker image from the Docker hub.

docker pull kerberos/kerberos

When you pulled succesfully you can run your first Kerberos container as following. This will run Kerberos agent and expose the web interface on port 80, and the livestream on port 8889.

docker run --name camera1 -p 80:80 -p 8889:8889 -d kerberos/kerberos

To add more containers, you can change the name parameter and assign another port to expose the web interface and livestream (ports are unique on a OS).

docker run --name camera2 -p 81:80 -p 8890:8889 -d kerberos/kerberos
docker run --name camera3 -p 82:80 -p 8891:8889 -d kerberos/kerberos

When the containers are created, you can open your browser and browse to your different containers.

http://localhost:80
http://localhost:81
http://localhost:82

Volumes

You can assign volumes to the Kerberos container to for example

  • preload configuration,
  • or centralise the images/videos on your working station.

Generic

If you want to install the Kerberos agent from source on your working station or server, either for development or running the software, this is the preferred installation procedure. We are assuming that you use a Linux OS, when using Mac OSX the installation is slightly different.

This was tested on a Ubuntu VM (18.04.3 (LTS) x64).

Machinery

Update the packages and kernel, and install some development tools.

sudo apt-get -y update
sudo apt-get install -y git cmake subversion dh-autoreconf libcurl4-openssl-dev yasm libx264-dev pkg-config libssl-dev

Install the FFmpeg library with x264 support.

It's recommended to install FFmpeg 3.1. Later versions might give issues at compilation or run time.

git clone https://github.com/FFmpeg/FFmpeg ffmpeg
cd ffmpeg && git checkout remotes/origin/release/3.1
./configure --enable-gpl --enable-libx264 --enable-shared --prefix=/usr
make && sudo make install

Go to your home directory, or any place your prefer and pull the machinery from Github. Afterwards create a build directory and start the compilation.

You can change the -j attribute of make -j8to the number of cores of your compilation host.

cd && git clone https://github.com/kerberos-io/machinery
cd machinery && mkdir build && cd build
cmake .. && make -j8 && make check && sudo make install

After the machinery is build and installed succesfully, you can enable kerberosio to start on boot.

sudo systemctl enable kerberosio
sudo systemctl start kerberosio

Web

If you want to install the web, you'll need to have a webserver (e.g. Nginx) and PHP running with some extensions. You'll also need NodeJS and npm installed, to install Bower.

cd ~
curl -sL https://deb.nodesource.com/setup_10.x | sudo bash -
sudo apt-add-repository -y ppa:ondrej/php
sudo apt-get -y update
sudo apt-get install -y git php7.1-cli php7.1-gd php7.1-mcrypt php7.1-curl php7.1-mbstring php7.1-dom php7.1-zip php7.1-fpm nodejs
sudo npm -g install bower

Next we'll need to install Nginx, and create a config file.

sudo apt-get -y install nginx
sudo rm -f /etc/nginx/sites-enabled/default
sudo nano /etc/nginx/sites-enabled/default

Assign Nginx to our web interface (which we will soon create).

server
{
    listen 80 default_server;
    listen [::]:80 default_server;
    root /var/www/web/public;
    server_name kerberos.rpi;
    index index.php index.html index.htm;
    location /
    {
            autoindex on;
            try_files $uri $uri/ /index.php?$query_string;
    }
    location ~ \.php$
    {
            fastcgi_pass unix:/var/run/php/php7.1-fpm.sock;
            fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
            include fastcgi_params;
    }
}

Now we have all the dependencies installed we can clone the web repository to our working station.

mkdir -p /var/www
cd /var/www && sudo git clone https://github.com/kerberos-io/web && cd web

Install the PHP dependency manager, composer, the install all the needed dependencies.

curl -sS https://getcomposer.org/installer | sudo php
sudo mv composer.phar /usr/bin/composer
sudo composer install

Change some permissions, to make sure we can write logging and caching files.

sudo chmod -R 777 storage
sudo chmod -R 777 bootstrap/cache
sudo chmod 777 config/kerberos.php

We will need to install a couple of more JavaScript libraries using bower.

cd public
sudo bower --allow-root install
service nginx restart

Once everything is setup correctly, you should be able to browse towards the ip-address of your Raspberry Pi and see the Kerberos web interface.

Auto removal

By default images or videos aren't removed automatically. This means that the Kerberos agent will keep writing to disk, even if there is no more space available on your SD card. When your SD card is full you'll be experiencing strange errors: a corrupt web interface, blank images or corrupt videos.

To resolve this your should install a simple bash script and initiate a cronjob which continuously poll your filesystem, and start removing media when your disk is getting full.

Create a bash script and copy following script.

nano /home/[user]/autoremoval.sh

Copy following script (make sure the partition is correct, this is the default one for a Raspberry Pi).

partition=/dev/root
imagedir=/etc/opt/kerberosio/capture/
if [[ $(df -h | grep $partition | head -1 | awk -F' ' '{ print $5/1 }' | tr ['%'] ["0"]) -gt 90 ]];
then
    echo "Cleaning disk"
    find $imagedir -type f | sort | head -n 100 | xargs -r rm -rf;
fi;

Make the script executable.

chmod +x /home/[user]/autoremoval.sh

Initiate a cronjob, and select the nano editor.

crontab -e

Append following line, to execute the autoremoval.sh script every 5min.

*/5 * * * * /bin/bash /home/[user]/autoremoval.sh