Getting started

This section tells you what you need to know to start working with KasperskyOS Community Edition.

Using a Docker container

To install and use KasperskyOS Community Edition, you can use a Docker container in which an image of one of the supported operating systems is deployed.

To use a Docker container for installing KasperskyOS Community Edition:

1. Make sure that the Docker software is installed and running.
2. To download the official Docker image of the Debian "Buster" 10.12 operating system from the public Docker Hub repository, run the following command:

   docker pull debian:10.12

3. To run the image, run the following command:

   docker run --net=host --user root --privileged -it --rm debian:10.12 bash

4. Copy the DEB package for installation of KasperskyOS Community Edition into the container.
5. Install KasperskyOS Community Edition.
6. To ensure correct operation of certain examples:
   1. Add the /usr/sbin directory to the PATH environment variable within the container by running the following command:

      export PATH=/usr/sbin:$PATH

   2. Install the parted program within the container. To do so, add the following string to /etc/apt/sources.list:

      deb http://deb.debian.org/debian bullseye main

      After this, run the following command:

      sudo apt update && sudo apt install parted

Installation and removal

Installation

KasperskyOS Community Edition is distributed as a DEB package. It is recommended to use the apt package installer to install KasperskyOS Community Edition.

To deploy the package using apt, run the following command with root privileges:

The package will be installed in /opt/KasperskyOS-Community-Edition-<version>.

For convenient operation, you can add the path to the KasperskyOS Community Edition tools binaries to the PATH variable. This will allow you to use the tools via the terminal from any folder:

Removal

To remove KasperskyOS Community Edition, run the following command with root privileges:

All installed files in the /opt/KasperskyOS-Community-Edition-<version> directory will be deleted.

Configuring the development environment

This section provides brief instructions on configuring the development environment and adding the header files included in KasperskyOS Community Edition to a development project.

Configuring the code editor

Before getting started, you should do the following to simplify your development of solutions based on KasperskyOS:

• Install code editor extensions and plugins for your programming language (C and/or C++).
• Add the header files included in KasperskyOS Community Edition to the development project.

  The header files are located in the directory: /opt/KasperskyOS-Community-Edition-<version>/sysroot-aarch64-kos/include.

Example of how to configure Visual Studio Code

For example, during KasperskyOS development, you can work with source code in Visual Studio Code.

To more conveniently navigate the project code, including the system API:

1. Create a new workspace or open an existing workspace in Visual Studio Code.

   A workspace can be opened implicitly by using the File > Open folder menu options.

2. Make sure the C/C++ for Visual Studio Code extension is installed.
3. In the View menu, select the Command Palette item.
4. Select the C/C++: Edit Configurations (UI) item.
5. In the Include path field, enter /opt/KasperskyOS-Community-Edition-<version>/sysroot-aarch64-kos/include.
6. Close the C/C++ Configurations window.

Building and running examples

Building the examples

The examples are built using the CMake build system that is included in KasperskyOS Community Edition.

The code of the examples and build scripts are available at the following path:

/opt/KasperskyOS-Community-Edition-<version>/examples

Building the examples to run on QEMU

To build an example, go to the directory with the example and run this command:

Running cross-build.sh creates a KasperskyOS-based solution image that includes the example. The kos-qemu-image solution image is located in the <name of example>/build/einit directory.

Building the examples to run on Raspberry Pi 4 B

To build an example:

1. Go to the directory with the example.
2. Open the cross-build.sh script file in a text editor.
3. In the last line of the script file, replace the make sim command with make kos-image.
4. Save the script file and then run the command:

   $ ./cross-build.sh

Running cross-build.sh creates a KasperskyOS-based solution image that includes the example. The kos-image solution image is located in the <name of example>/build/einit directory.

Running examples on QEMU

Running examples on QEMU on Linux with a graphical shell

An example is run on QEMU on Linux with a graphical shell using the cross-build.sh script, which also builds the example. To run the script, go to the folder with the example and run the command:

Additional QEMU parameters must be used to run certain examples. The commands used to run these examples are provided in the descriptions of these examples.

Running examples on QEMU on Linux without a graphical shell

To run an example on QEMU on Linux without a graphical shell, go to the directory with the example, build the example and run the following commands:

Preparing Raspberry Pi 4 B to run examples

Connecting a computer and Raspberry Pi 4 B

To see the output of the examples on the computer:

1. Connect the pins of the FT232 USB-UART converter to the corresponding GPIO pins of the Raspberry Pi 4 B (see the figure below).

   

   Diagram for connecting the USB-UART converter and Raspberry Pi 4 B

2. Connect the computer's USB port to the USB-UART converter.
3. Install PuTTY or a similar program for reading data from a COM port. Configure the settings as follows: bps = 115200, data bits = 8, stop bits = 1, parity = none, flow control = none.

To allow a computer and Raspberry Pi 4 B to interact through Ethernet:

1. Connect the network cards of the computer and Raspberry Pi 4 B to a switch or to each other.
2. Configure the computer's network card so that its IP address is in the same subnet as the IP address of the Raspberry Pi 4 B network card (the settings of the Raspberry Pi 4 B network card are defined in the dhcpcd.conf file, which is found at the path <example name>/resources/...).

Preparing a bootable SD card for Raspberry Pi 4 B

A bootable SD card for Raspberry Pi 4 B can be prepared automatically or manually.

To automatically prepare the bootable SD card, connect the SD card to the computer and run the following commands:

To manually prepare the bootable SD card:

1. Build the U-Boot bootloader for ARMv8, which will automatically run the example. To do this, run the following commands:

   $ sudo apt install git build-essential libssl-dev bison flex unzip parted gcc-aarch64-linux-gnu xz-utils device-tree-compiler

   $ git clone https://github.com/u-boot/u-boot.git u-boot-armv8

   # For Raspberry Pi 4 B revisions 1.1 and 1.2 only:

   $ cd u-boot-armv8 && git checkout tags/v2020.10

   # For Raspberry Pi 4 B revisions 1.4 and 1.5 only:

   $ cd u-boot-armv8 && git checkout tags/v2022.01

   # For all Raspberry Pi revisions:

   $ make ARCH=arm CROSS_COMPILE=aarch64-linux-gnu- rpi_4_defconfig

   # In the menu that appears when you run the following command,

   # in the 'Boot options' section, change the value in the 'bootcmd value' field to the following:

   # fatload mmc 0 ${loadaddr} kos-image; bootelf ${loadaddr},

   # and delete the value "usb start;" in the 'preboot default value' field.

   # Exit the menu after saving the settings.

   $ make ARCH=arm CROSS_COMPILE=aarch64-linux-gnu- menuconfig

   $ make ARCH=arm CROSS_COMPILE=aarch64-linux-gnu- u-boot.bin

2. Prepare the image containing the file system for the SD card. To do this, connect the SD card to the computer and run the following commands:

   # For Raspberry Pi 4 B revisions 1.1 and 1.2 only:

   $ wget https://downloads.raspberrypi.org/raspbian_lite/images/raspbian_lite-2020-02-14/2020-02-13-raspbian-buster-lite.zip

   $ unzip 2020-02-13-raspbian-buster-lite.zip

   $ loop_device=$(sudo losetup --find --show --partscan 2020-02-13-raspbian-buster-lite.img)

   # For Raspberry Pi 4 B revision 1.4 only:

   $ wget https://downloads.raspberrypi.org/raspios_lite_arm64/images/raspios_lite_arm64-2022-04-07/2022-04-04-raspios-bullseye-arm64-lite.img.xz

   $ unxz 2022-04-04-raspios-bullseye-arm64-lite.img.xz

   $ loop_device=$(sudo losetup --find --show --partscan 2022-04-04-raspios-bullseye-arm64-lite.img)

   # For Raspberry Pi 4 B revision 1.5 only:

   $ wget https://downloads.raspberrypi.org/raspios_lite_arm64/images/raspios_lite_arm64-2022-09-07/2022-09-06-raspios-bullseye-arm64-lite.img.xz

   $ unxz 2022-09-06-raspios-bullseye-arm64-lite.img.xz

   $ loop_device=$(sudo losetup --find --show --partscan 2022-09-06-raspios-bullseye-arm64-lite.img)

   # For all Raspberry Pi revisions:

   # Image will contain a boot partition of 1 GB in fat32 and 3 partitions of 256 MB each in ext2, ext3 and ext4, respectively:

   $ sudo parted ${loop_device} rm 2

   $ sudo parted ${loop_device} resizepart 1 1G

   $ sudo parted ${loop_device} mkpart primary ext2 1000 1256M

   $ sudo parted ${loop_device} mkpart primary ext3 1256 1512M

   $ sudo parted ${loop_device} mkpart primary ext4 1512 1768M

   $ sudo mkfs.ext2 ${loop_device}p2

   $ sudo mkfs.ext3 ${loop_device}p3

   $ sudo mkfs.ext4 -O ^64bit,^extent ${loop_device}p4

   $ sudo losetup -d ${loop_device}

   # In the following command, [X] is the last symbol in the name of the block device

   # for the SD card.

   $ sudo dd bs=64k if=$(ls *rasp*lite.img) of=/dev/sd[X] conv=fsync

3. Copy the U-Boot bootloader to the SD card by running the following commands:

   # In the following commands, the path ~/mnt/fat32 is just an example. You

   # can use a different path.

   $ mkdir -p ~/mnt/fat32

   # In the following command, [X] is the last alphabetic character in the name of the block

   # device for the partition on the formatted SD card.

   $ sudo mount /dev/sd[X]1 ~/mnt/fat32/

   $ sudo cp u-boot.bin ~/mnt/fat32/u-boot.bin

   # For Raspberry Pi 4 B revision 1.5 only:

   # In the following commands, the path ~/tmp_dir is just an example. You

   # can use a different path.

   $ mkdir -p ~/tmp_dir

   $ cp ~/mnt/fat32/bcm2711-rpi-4-b.dtb ~/tmp_dir

   $ dtc -I dtb -O dts -o ~/tmp_dir/bcm2711-rpi-4-b.dts ~/tmp_dir/bcm2711-rpi-4-b.dtb && \

   $ sed -i -e "0,/emmc2bus = /s/emmc2bus =.*//" ~/tmp_dir/bcm2711-rpi-4-b.dts && \

   $ sed -i -e "s/dma-ranges = <0x00 0xc0000000 0x00 0x00 0x40000000>;/dma-ranges = <0x00 0x00 0x00 0x00 0xfc000000>;/" ~/tmp_dir/bcm2711-rpi-4-b.dts && \

   $ sed -i -e "s/mmc@7e340000 {/mmc@7e340000 {\n\t\t\tranges = <0x00 0x7e000000 0x00 0xfe000000 0x1800000>;\n dma-ranges = <0x00 0x00 0x00 0x00 0xfc000000>;/" ~/tmp_dir/bcm2711-rpi-4-b.dts && \

   $ dtc -I dts -O dtb -o ~/tmp_dir/bcm2711-rpi-4-b.dtb ~/tmp_dir/bcm2711-rpi-4-b.dts

   $ sudo cp ~/tmp_dir/bcm2711-rpi-4-b.dtb ~/mnt/fat32/bcm2711-rpi-4-b.dtb

   $ sudo rm -rf ~/tmp_dir

4. Fill in the configuration file for the U-Boot bootloader on the SD card by using the following commands:

   $ echo "[all]" > ~/mnt/fat32/config.txt

   $ echo "arm_64bit=1" >> ~/mnt/fat32/config.txt

   $ echo "enable_uart=1" >> ~/mnt/fat32/config.txt

   $ echo "kernel=u-boot.bin" >> ~/mnt/fat32/config.txt

   $ echo "dtparam=i2c_arm=on" >> ~/mnt/fat32/config.txt

   $ echo "dtparam=i2c=on" >> ~/mnt/fat32/config.txt

   $ echo "dtparam=spi=on" >> ~/mnt/fat32/config.txt

   $ sync

   $ sudo umount ~/mnt/fat32

Running examples on Raspberry Pi 4 B

To run an example on a Raspberry Pi 4 B:

1. Go to the directory with the example and build the example.
2. Make sure that Raspberry Pi 4 B and the bootable SD card are prepared to run examples.
3. Copy the KasperskyOS-based solution image to the bootable SD card. To do this, connect the bootable SD card to the computer and run the following commands:

   # In the following command, [X] is the last alphabetic character in the name of the block

   # device for the partition on the bootable SD card.

   # In the following commands, the path ~/mnt/fat32 is just an example. You

   # can use a different path.

   $ sudo mount /dev/sd[X]1 ~/mnt/fat32/

   $ sudo cp build/einit/kos-image ~/mnt/fat32/kos-image

   $ sync

   $ sudo umount ~/mnt/fat32

4. Connect the bootable SD card to the Raspberry Pi 4 B.
5. Supply power to the Raspberry Pi 4 B and wait for the example to run.

   The output displayed on the computer indicates that the example started.