Sternum Linux SDK

This repository contains the files of the Sternum Linux SDK, a versatile and flexible tool to add observability and traceability to Linux devices using C/C++.

The SDK package is organized into three main directories:

• linux - Sources for building Sternum Linux SDK library,
• posix_native_sdk - The SDK core files, included into Linux build automatically.
• linux/modules - Third-party libraries: OpenSSL.

Setup

Build OpenSSL

OpenSSL requirements setup

Linux SDK requires OpenSSL for encrypted transmission. OpenSSL is provided as source in the SDK package.

Before building or compiling the OpenSSL module, ensure that you have the necessary development packages installed on your Linux system. The required packages may vary depending on your Linux distribution. Typically, you'll need development tools and libraries. Here's how to install the prerequisites on Debian-based systems (such as Ubuntu):

Update the package index:

sudo apt update

Install the necessary development packages for OpenSSL:

sudo apt install build-essential

This command installs essential development tools including compilers and libraries required for building OpenSSL.

Build OpenSSL library

Change into the OpenSSL submodule directory by running the following command:

cd sternum_linux_sdk/linux/modules/openssl

Configure OpenSSL build:

./config

This command configures OpenSSL build environment based on your system's architecture and installed libraries.

When cross-compiling, ensure to modify the build parameters accordingly. An example is provided in the Cross Compilation section.

Build OpenSSL:

make

This command compiles OpenSSL from the source code.

(Optional) Run tests:

make test

This command runs the OpenSSL test suite to ensure that the build is successful and the library functions correctly.

The compiled libraries will be located in the modules/openssl directory. During the SDK build process, these libraries will be placed into the sternum_linux_sdk/linux/output directory.

OpenSSL Cross Compilation

The following example demonstrates how to cross-compile OpenSSL for AARCH64.

Assuming your cross-compilation toolchain is accessible as aarch64-linux-gnu-, the OpenSSL configuration can be done as follows:

export CROSS_COMPILE=aarch64-linux-gnu-
./Configure linux-aarch64 shared --cross-compile-prefix=${CROSS_COMPILE}
make

Adapt the parameters to your toolchain and architecture as needed.

Build Sternum Linux SDK

Once you have built OpenSSL successfully, you can build Sternum SDK library. Navigate to Linux SDK directory:

cd sternum_linux_sdk/linux

Configure SDK build:

To configure the SDK build for your host environment with default features, use the following command:

cmake .

This command generates the necessary build files based on your environment, including your system architecture and the default SDK feature settings. It prepares the project for compilation, tailored to your specific development environment.

Build SDK:

make

The sternum_linux_sdk/linux/output directory will contain generated SDK library libsternum_linux_sdk.so, OpenSSL libraries libssl.so, libcrypto.so, and include directory encompassing all necessary SDK headers.

After building the SDK, move created libraries (libsternum_linux_sdk.so, libssl.so, libcrypto.so) to target device and ensure that they are accessible for dynamic linker. You have three options to make these libraries accessible:

• Set RPATH in the Target Project:

In your target project's CMakeLists.txt, set the RPATH to include the directory where the SDK's shared libraries are located. This ensures that the dynamic linker can find the libraries at runtime without requiring additional environment variables.

For example, if the shared libraries are in the lib/ directory relative to the executable:

set_target_properties(your_target PROPERTIES
    INSTALL_RPATH "$ORIGIN/../lib"
    BUILD_RPATH "$ORIGIN/../lib"
    INSTALL_RPATH_USE_LINK_PATH TRUE
)

• Update LD_LIBRARY_PATH:

Set the LD_LIBRARY_PATH environment variable on your target device to include the paths to these libraries. This allows the dynamic linker to find the libraries at runtime. For example:

export LD_LIBRARY_PATH=/path/to/libraries:$LD_LIBRARY_PATH

• Move Libraries to a Default Location:

Alternatively, you can move the libraries to a standard system directory where the dynamic linker automatically searches for shared libraries. Common default paths include /usr/lib or /usr/local/lib.

By following these steps, you ensure that your target device can locate and use the SDK and its dependencies correctly.

SDK Cross Compilation

When cross-compiling the SDK, adjust the build parameters to match the target architecture. Detailed instructions are provided in this section.

Create a toolchain file that specifies the necessary variables for cross-compilation. Below is an example for AArch64 (ARM 64-bit architecture) that utilizes a previously defined CROSS_COMPILE environment variable.

Example: aarch64-toolchain.cmake

# Set the cross-compilation environment
set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR aarch64)
 
# Specify the cross-compiler
set(CMAKE_C_COMPILER $ENV{CROSS_COMPILE}gcc)
set(CMAKE_CXX_COMPILER $ENV{CROSS_COMPILE}g++)
set(CMAKE_ASM_COMPILER $ENV{CROSS_COMPILE}gcc)

To build the library using the toolchain file, run the following command:

cmake -DCMAKE_TOOLCHAIN_FILE=aarch64-toolchain.cmake .
make

Customizing Features

You can customize various features of the SDK by adding CMake options when configuring the build. Here are the available options:

• -DAPPEND_PROCESS_NAME=ON/OFF: Enable or disable adding the executing process name to each trace (default: ON).
• -DENABLE_CRASH_DETECTION=ON/OFF: Enable or disable crash detection feature (default: ON).
• -DLOG_LEVEL=0..3: Specify the log level (Default: 2).

Log Level

The log level determines the verbosity of logging messages generated by the library. Accepted values are:

ERR   0
WARN  1
INF   2
DBG   3

Crash detection

The Crash Detection feature automatically captures program state information when the program crashes due to certain signals, including SIGSEGV, SIGBUS, SIGILL, SIGABRT, SIGFPE, SIGSYS, and SIGTERM. This information is stored in a crash dump file in the cache. On the next boot of the program, the stored crash dump is automatically transmitted to Sternum Platform within TRACE_CRASH. This allows developers to analyze the crash and diagnose the root cause more effectively.

Append process name

If APPEND_PROCESS_NAME is enabled, executing process name will be included automatically to each transmitted trace.

Integrate Sternum Linux into your project

Your project will need the SDK headers, SDK library libsternum_linux_sdk.so, and its dependencies (libssl.so, libcrypto.so) in order to instrument and build your applications with the SDK.

Copy and paste the contents of sternum_linux_sdk/linux/output to your project or general location on your device. You can create new folder in your project structure for this purpose, for instance sternum_sdk.

Adjust the configuration according to your build system to include the SDK directory and link with SDK library. If you are using CMake, an example of configuration is documented next.

Example of CMake configuration

To build your application with the SDK, update your CMake configuration as follows:

Add sternum_sdk/include directory to the list of include directories for your project:

target_include_directories(app PRIVATE
    # existing include directories...
    sternum_sdk/include
)

Link your application with Sternum SDK library:

target_link_libraries(app PRIVATE sternum_sdk/libsternum_linux_sdk.so)

If you're using a different build system, adjust the configuration accordingly to include the SDK directory and link with SDK library.

Using the API

Include sternum_sdk.h

#include "sternum_sdk.h"

Initialize Sternum SDK

You must initialize Sternum SDK before using it.

Transmission initialization:

• sternum_settings_t::sternum_url - The designated endpoint provided by Sternum, serving as the destination for transmitting traces.
• sternum_settings_t::access_token - Identifier for the product to which traces will be transmitted.

File cache initialization:

Traces are cached in a file cache. If transmission fails, they will remain stored in the file cache until successfully sent. Once transmitted, they are then removed from the cache. The file cache maintains persistence across multiple application executions and must be unique for each application instance.

• sternum_settings_t::cache_file_path - You can specify your preferred file cache location as a full path or filename that will be located in current working directory. Each application instance using the SDK must set its own file cache. Refer to field documentation to understand the accepted path formats and other details.
• sternum_settings_t::max_cache_size_bytes - Sets the maximum cache size. The recommended size is 65kB. If there's no space in the cache to construct a trace, it won't be created even if immediate transmission is possible.

For more information about the initialization structure, refer to the documentation of struct sternum_settings_t .

Below is an example of how to initialize the SDK:

sternum_settings_t settings;
// Ensure clear initial state of settings
init_sternum_settings(&settings);
 
settings.sternum_url = "gateway.sternum.cloud";
settings.access_token = 0x10101010;
settings.device_id = 0x20304050;
settings.relay_override_device_id = NULL;
settings.is_production = false;
settings.max_cache_size_bytes = 65000;
settings.cache_file_path = "sternum_cache.bin";
 
if (sternum_sdk_initialize(&settings) != STERNUM_CODE_SUCCESS) {
    printf("SDK initialization failed");
    return -1;
}

Thread safety

The SDK library is thread-safe.

Sending traces

STERNUM_ADS_TRACE(TRACE_UPDATE_START);

Relaying device data

sternum_sdk_relay_device_data(device_type, data, size);

Flushing traces

Calling the sternum_sdk_flush() method initiates the secure transmission of traces to the cloud via TLS/OpenSSL. If transmission is impossible, traces will be retained in the cache until a successful connection can be established, ensuring no data loss occurs.

sternum_sdk_flush();

Closing the Sternum SDK

sternum_sdk_close();