Installation

Prerequisites: Linux, Python 3.7+, sudo access. Full dependency lists and licenses are in Reference below.

There are two ways to install Yunetas, depending on what you want to do:

• Quick install — pre-built package (.deb on Debian/Ubuntu, .rpm on RHEL/Rocky/Alma), via a single cross-distro installer. Installs the runtime (agent, CLI tools, bundled web server) and the Yuneta libraries, headers and CMake toolchain under /yuneta/development/yunetas/, plus (by default) the developer toolchain — so you can both run yunos and compile your own projects against the published runtime. What it does not include is Yuneta’s own source tree.

• Build from source — the full source tree. Use this to develop the framework itself, or to produce a customised runtime with different build options (TLS backend, modules, static/dynamic, build type — see menuconfig).

ℹ️ The PyPI package yunetas (pipx install yunetas) is the management/build CLI (currently 0.19.1), not the C framework runtime (currently 7.x). The .deb bundles both. A build from source uses the CLI to drive the build.

Quick install¶

Not on a node that builds from source¶

The install refuses a node whose /yuneta/development/yunetas holds the sources (kernel/ and .git), and so does the package itself if you install it by hand.

The package carries libraries, headers and binaries built on another machine, and it lays them into the very tree yunetas build owns — outputs/ and outputs_ext/. From then on the tree is no longer self-consistent: fresh objects link against archives built for a different glibc. A dynamic link fails loudly, which would be a mercy; a static link resolves them silently and the binary corrupts its heap at run time — SIGABRT deep inside malloc, seconds after start, with no framework error first and a stack that blames unrelated code. That is the same trap libc_guard.cmake catches at configure time.

To install anyway — it is supported, it just has to be a decision:

curl -fsSL https://raw.githubusercontent.com/artgins/yunetas/main/install.sh \
    | sudo YUNETAS_FORCE_OVER_SOURCE=1 sh

The variable goes after sudo: sudo resets the environment, so VAR=1 sudo … never reaches the package scripts. To make it stick for a node that is deliberately both — a build machine that also tracks the packages — drop the marker instead:

sudo touch /etc/yuneta/allow-package-over-source

Tested on¶

The command above is exercised end-to-end, on a freshly installed OS, on:

Debian 13 was exercised on both a VM and a dedicated server, deliberately: the faster machine loses a start-up race the slower one wins, which is exactly how a snapd bug in the certbot step stayed hidden. Rocky was also verified across a reboot — the moment firewalld first starts and the agent has to come up on its own.

Other releases of the same families are expected to work — the script branches on apt vs dnf, not on the version — but they are not exercised.

The 7.9.11-3 pass reimaged both nodes and probed them end to end, which is the only reason two defects were found at all: the installer was fetching the oldest package of a release rather than the newest, and the fail2ban filter could not match anything on a node whose vhost is a single-page app. Neither shows up on a node that is already configured.

Each package is built in a container of its own target distro: debian:13 (.deb, glibc 2.41) and rockylinux:9 (.rpm, glibc 2.34). That build base decides whether a node can compile against the shipped SDK — see the glibc warning below. It does not affect running the shipped binaries.

The script does everything in one run, no second step to remember:

• detects the distro (apt vs dnf) and the architecture.

• on RHEL/Rocky/Alma, enables EPEL + CRB first (mercurial, ninja-build, pipx and the -devel/-static packages live there, and dnf cannot pull from a repo that it enables in the same transaction).

• pulls the matching package (.deb / .rpm) from the latest GitHub Release and installs it so that the dependencies resolve cleanly.

• then installs the full developer toolchain (git, mercurial, clang, gcc, cmake, ninja, wget, pipx, …) so the box can build yunos right away. No prompts and no stops. It runs from start to end. Pass --runtime-only (… | sudo sh -s -- --runtime-only) to skip the toolchain on a pure deployment box.

Pin a version (must exist as a published Release):

curl -fsSL https://raw.githubusercontent.com/artgins/yunetas/main/install.sh | sudo sh -s -- 7.5.7

⚠️ RHEL/Rocky/Alma need io_uring enabled. The .rpm ships kernel.io_uring_disabled=0 and applies it in %post, but if SELinux (Enforcing) or a host policy keeps io_uring disabled the agent will not start — see the io_uring requirement below. The %post is honest about it: if the agent is not running after install it prints a warning naming the cause (io_uring or SELinux) with the systemctl status / journalctl commands to diagnose it.

Or download the package manually from the Releases page and install it (this installs only the runtime + its declared deps — for the developer toolchain, run sudo /yuneta/bin/install-yuneta-dev-deps.sh afterwards, or use the one-liner above):

# Debian / Ubuntu
sudo apt install ./yuneta-agent-<version>-<release>-<arch>.deb

# RHEL / Rocky / Alma  (enable EPEL + CRB first so the deps resolve)
sudo dnf -y install epel-release && sudo crb enable
sudo dnf -y install ./yuneta-agent-<version>-<release>.x86_64.rpm

Prefer to build the package yourself (other arch, custom options)? Build from source, then run packages/deb/<ARCH>.sh or packages/rpm/<arch>.sh — see packages/README.md.

The package installs the agent + CLI tools + bundled openresty under /yuneta/, creates the yuneta system user, applies kernel tuning and PAM limits, and starts the SysV service. It also lays down the Yuneta libraries, headers, CMake toolchain and the build .config as a sparse SDK under /yuneta/development/yunetas/ (outputs/, outputs_ext/, tools/, .config — no sources): the SAME base path as a full source checkout, so projects compile against the published runtime without the source tree and without layout differences. Full inventory in packages/README.md.

🔴 That sparse SDK only compiles on the glibc the package was built against. The shipped outputs/lib/*.a are static archives that reference glibc internals whose layout moves between releases, so linking fresh objects against them on a node with a different glibc produces a binary that corrupts the heap at run time — SIGABRT deep in _int_malloc seconds after start, no framework error first, stack blaming unrelated code. The shipped binaries keep working (they are self-contained). It is the build that breaks. Check before building anything on a node:

cat /yuneta/development/yunetas/outputs/lib/yuneta_libc.stamp   # what built the package
ldd --version | head -1                                          # what the node has

If they differ, that node is runtime-only: build elsewhere and push binaries with yunetas sync-binaries. tools/cmake/libc_guard.cmake enforces this at configure time. -DYUNETA_ALLOW_LIBC_MISMATCH=ON only silences the message, it does not make the link safe.

In practice, each package is built in a container of its own target distro, so each one matches exactly one glibc:

Package	Built in	glibc	Nodes that can build on-node
.rpm (EL9)	rockylinux:9	2.34	Rocky/Alma 9
.deb (AMD64)	debian:13	2.41	Debian 13 (trixie)

So Ubuntu nodes are runtime-only — 24.04 (2.39) and 26.04 (2.43) both differ from 2.41 — as is Debian 12. Build those elsewhere and push binaries. The .deb came from an ubuntu-22.04 runner (glibc 2.35) until 7.8.6-3. if you are on an older package, check its stamp rather than this table.

ℹ️ Build options of the published .deb. The release asset is compiled with the Kconfig defaults (alldefconfig): GCC, RelWithDebInfo, fully static binaries, OpenSSL TLS backend (mbedTLS off), and every module enabled (console, mqtt, postgres, test, modbus). The exact configuration is installed at /yuneta/development/yunetas/.config — inspect it to confirm what a given package was built with. Need a different combination (for example mbedTLS for smaller binaries, or a leaner module set)? Build from source and pick your options with menuconfig.

⚠️ The agent is a SysV service — manage it with the agent binary’s own --start / --stop, NOT systemctl/systemd. Yuneta runs its own daemon + watchdog, so systemctl restart yuneta_agent is effectively a no-op (the process keeps its old PID and binary, so it is not restarted). To start/stop/restart the agent:

/yuneta/agent/yuneta_agent --config-file=/yuneta/agent/yuneta_agent.json --stop
/yuneta/agent/yuneta_agent --config-file=/yuneta/agent/yuneta_agent.json --start

or the init script /etc/init.d/yuneta_agent {start|stop|restart} (which also handles the bundled web server). To roll out a new agent binary: overwrite /yuneta/agent/yuneta_agent, then --stop and --start.

ℹ️ Build the .deb yourself instead of using the published asset: see packages/README.md for the four arch wrapper scripts (AMD64.sh, ARM32.sh, ARMhf.sh, RISCV64.sh). Requires the SDK already built (next section).

Verify a fresh install¶

Five checks, both families. Run them right after the one-liner finishes — they catch everything that went wrong on a new node:

# 1. The three processes are up (agent, agent22, bundled web server)
ps -ef | grep -E 'yuneta_agent|nginx' | grep -v grep

# 2. They come back after a reboot (SysV, enabled — there is no native unit
#    for agent22/nginx, the init script starts all three)
systemctl is-enabled yuneta_agent

# 3. The control channel answers (empty list on a fresh node is correct)
sudo -u yuneta ycommand -c 'list-yunos'

# 4. The CLI runs
sudo -u yuneta yunetas --help

# 5. Core dumps land where the debugger looks for them
cat /proc/sys/kernel/core_pattern      # -> /var/crash/core.%e

Add the glibc-stamp check above if the node is meant to build.

Two things that look wrong and are not: systemctl is-active yuneta_agent22 and nginx report inactive/not-found (neither has a systemd unit — the init script owns them), and on RHEL certbot-renew.timer is enabled but inactive until the next boot.

Logs and banning¶

The package also configures what happens to the web server’s logs, because nginx does neither on its own.

Rotation is automatic. /etc/logrotate.d/yuneta rotates the access and error logs of whichever web server the node runs, daily, keeping 30 compressed. Without it those files grow for the life of the node — nginx has no rotation of its own, it only knows how to reopen its files when it is signalled.

Banning is installed but OFF. /etc/fail2ban/jail.d/yuneta-nginx.conf carries two jails that ban whoever probes the node for .php paths, .env, .git or the WordPress surface — none of which a Yuneta node serves, so a request for them cannot be a mistake. They ship disabled on purpose: if a jail’s log path resolves to nothing, fail2ban does not skip that jail, it refuses to start at all and takes every other jail down with it, sshd included. A node that has the package but has not started its web server yet is exactly that case.

Turn them on once access.log exists:

printf '[yuneta-nginx-probe]\nenabled = true\n[nginx-botsearch]\nenabled = true\n' \
    | sudo tee /etc/fail2ban/jail.d/zz-yuneta-nginx-enabled.conf
sudo systemctl reload fail2ban && sudo fail2ban-client status

Then check the firewall, not the jail. A jail reports itself healthy while banning into thin air if banaction names a command the node does not have — on Debian that is nft, which nftables provides and a minimal install does not:

sudo nft list table inet f2b-table     # or: sudo iptables -L f2b-yuneta-nginx-probe -n

⚠️ On SELinux (Enforcing) the shipped log paths do not work. They are globs, and fail2ban_t cannot list /yuneta/bin — a denial that is dontaudited, so it writes no AVC. fail2ban then reports “Have not found any log file” and exits, with nothing naming SELinux. Give the jails a literal path in the same zz- file and label the directory: semanage fcontext -a -t var_log_t "/yuneta/bin/nginx/logs(/.*)?" followed by restorecon -R /yuneta/bin/nginx/logs.

Full detail, including what the filter deliberately does not match, is in packages/deb/README.md.

Build from source¶

The 7-step flow below installs the full SDK — sources, build deps, tooling — under ~/yunetaprojects/.

1. Create the yuneta user¶

sudo adduser yuneta
sudo mkdir /yuneta
sudo chown yuneta:yuneta /yuneta

Log out and log back in as yuneta for the rest of the steps.

2. Install OS packages¶

The repo ships a distro-aware helper that installs everything below and the kconfiglib menuconfig backend. It auto-detects Debian/Ubuntu vs RHEL/Rocky/Alma/Fedora from /etc/os-release:

cd ~/yunetaprojects/yunetas
./install-dependencies.sh

Prefer to run the package manager yourself? Pick your distro below.

sudo apt -y install --no-install-recommends \
  git mercurial make cmake ninja-build \
  gcc clang g++ \
  python3-dev python3-pip python3-setuptools \
  python3-tk python3-wheel python3-venv \
  libjansson-dev libpcre2-dev liburing-dev \
  zlib1g-dev libssl-dev \
  perl dos2unix tree curl wget \
  postgresql-server-dev-all libpq-dev \
  kconfig-frontends telnet pipx \
  patch gettext fail2ban rsync \
  build-essential pkg-config ca-certificates linux-libc-dev

pipx install kconfiglib

sudo dnf -y install epel-release
sudo crb enable        # or: sudo dnf config-manager --set-enabled crb

sudo dnf -y install \
  git mercurial make cmake ninja-build \
  gcc clang gcc-c++ \
  python3-devel python3-pip python3-setuptools \
  python3-tkinter python3-wheel \
  jansson-devel pcre2-devel liburing-devel \
  pcre-devel zlib-devel openssl-devel \
  perl dos2unix tree wget \
  libpq-devel \
  telnet pipx \
  patch gettext fail2ban rsync \
  pkgconf-pkg-config ca-certificates glibc-devel kernel-headers \
  glibc-static libstdc++-static libxcrypt-static

pipx install kconfiglib

3. Install the yunetas CLI¶

sudo apt install pipx     # Ubuntu 23.04+
pipx ensurepath
pipx install yunetas

python3 -m pip install --user pipx
python3 -m pipx ensurepath

pipx upgrade yunetas
pipx uninstall yunetas

pip install yunetas

mkdir -p ~/miniconda3
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda3/miniconda.sh
bash ~/miniconda3/miniconda.sh -b -u -p ~/miniconda3
rm -rf ~/miniconda3/miniconda.sh
~/miniconda3/bin/conda init bash
exit   # close and re-open the shell

conda config --add channels conda-forge
conda create -y -n conda_yunetas pip
conda config --set auto_activate_base false
echo 'conda activate conda_yunetas' >> ~/.bashrc
source ~/.bashrc

4. Clone the repo¶

mkdir ~/yunetaprojects
cd ~/yunetaprojects
git clone --recurse-submodules https://github.com/artgins/yunetas.git

git clone -b <version> --recurse-submodules https://github.com/artgins/yunetas.git <version>

5. Activate the environment¶

cd ~/yunetaprojects/yunetas
source yunetas-env.sh

yunetas-env.sh exports four variables and prepends /yuneta/bin plus $YUNETAS_BASE/scripts to PATH:

ℹ️ Layout contract. Build artefacts (outputs/, outputs_ext/) live INSIDE $YUNETAS_BASE — both dirs are gitignored. The base is the SAME path on every node: /yuneta/development/yunetas/, as a full source checkout on dev nodes or as the sparse SDK (outputs/, outputs_ext/, tools/, .config — no sources) staged by the .deb/.rpm on runtime-only nodes. Your own project repos can live anywhere. Register them with yunetas register-project (below).

⚠️ Re-source per shell. New SSH sessions, cron jobs and CI need to source yunetas-env.sh again. Without it, ybatch / ycommand / yshutdown are not on PATH and deploy scripts fail with “command not found”.

Make it permanent — add to ~/.bashrc:

cd ~/yunetaprojects/yunetas
source yunetas-env.sh

The script also sources ~/.yunetasrc if it exists — use that file for your own personal additions.

6. Configure (menuconfig)¶

cd ~/yunetaprojects/yunetas
menuconfig

Pick compiler, build type and the modules you need, then save — this writes .config, which the build needs.

(Top) → Compiler Selection
    (X) GCC compiler (default)
    ( ) Clang compiler

(Top) → Build Configuration
    Build Type
        (X) RelWithDebInfo (default)
        ( ) Release
        ( ) Debug
        ( ) MinSizeRel
    [*] Build fully static binaries (default y)
         Produces binaries with no shared library dependencies.
         Copy to any Linux machine of the same architecture and run — nothing to install.

(Top) → TLS Library
    (X) OpenSSL (default)
    ( ) Mbed-TLS

(Top) → Debug Options
    [*] Use backtrace library (default y)
    [ ] Enable track memory
    [ ] Print times of yev_loop

(Top) → Modules
    [*] C_CONSOLE support
    [*] C_MQTT support
    [*] C_MODBUS support
    [*] C_POSTGRES support
    [*] C_TEST support

⚠️ Save .config or the build fails. If you switch compiler, re-run ./set_compiler.sh so the external libs are rebuilt with the matching toolchain.

7. Build and test¶

Build the bundled external libraries first (one-shot):

cd ~/yunetaprojects/yunetas/kernel/c/linux-ext-libs
./extrae.sh         # clone libraries
./configure-libs.sh # configure, build and install

Then build, install and test yunetas with the yunetas CLI — this is the standard build interface (init, build, clean, test). Prefer it over calling cmake directly, so the install to $YUNETAS_OUTPUTS/lib and the per-yuno relinks happen in the right order:

cd ~/yunetaprojects/yunetas
yunetas init     # configure build dirs + compiler/build-type from .config (menuconfig)
yunetas build    # regenerate yuneta_version.h + `make install` everything (kernel + yunos)
yunetas test     # ctest
# yunetas clean  # wipe the build dirs

Artefacts land in $YUNETAS_OUTPUTS/ (= $YUNETAS_BASE/outputs/): include/, lib/, bin/, yunos/.

External projects¶

The yunetas CLI can also drive your own projects (any repo whose yunos/CMakeLists.txt includes tools/cmake/project.cmake). Register them once and init / build / clean process them right after the SDK:

yunetas register-project /yuneta/development/projects/myproject
yunetas list-projects
yunetas build                 # SDK + every registered project
yunetas build myproject       # only that project (SDK skipped)
yunetas build --sdk-only      # only the SDK
yunetas unregister-project myproject

The registry is machine-local user state (~/.yuneta/projects.json), kept outside the source tree.

Deploy is two steps: push the artifacts, then promote them. The helpers below wrap tools/agent/. Shared arguments are forwarded verbatim (-n dry-run, -a all, OAuth2 options…). The full CLI reference, including the build and project-management commands, is on The yunetas CLI:

# 1. Push binaries AND configs together (recommended)
yunetas sync -n               # = sync-binaries + sync-configs, dry-run

# 2. Promote the freshly pushed releases to primary and restart
yunetas upgrade-yunos -n      # preview the agent commands without running them
yunetas upgrade-yunos         # snapshot -> find-new-yunos -> deactivate-snap

Push the two artifact kinds with sync, not one at a time: a binary bump must never ship without its matching config bump. A new fail-closed runtime (TLS verify-by-default) against a stale no-CA config is exactly what breaks OIDC login — sync couples the steps so neither is forgotten, and aborts before configs if the binaries push fails (no half-deploy). The individual helpers remain for when you need only one or a tool-specific flag:

yunetas sync-binaries -n      # outputs/yunos vs the local agent
yunetas sync-configs -n       # each project's yunos/batches/<host>/, auto-matched to local realms
yunetas sync-configs -n --host my.host.com   # or target one batches dir explicitly

sync-configs (and the configs pass of sync) walks the registered projects. Without --host it queries the local agent (*list-realms) and syncs every batches/<host>/ whose name is a realm_id the agent manages — a node running several realms deploys all the relevant ones in one pass (a batches dir is named after its realm_id, the deploy FQDN). If the agent cannot be reached it uses a single hostname match instead.

upgrade-yunos takes an optional rollback snapshot (idempotent by name, default pre-upgrade-<YYYYMMDD>, --no-snap to skip. If a snap is already active it reuses that one instead of shooting another), lists the new yuno rows that find-new-yunos creates and asks for confirmation (--yes to skip), registers them (find-new-yunos create=1), then runs deactivate-snap — which triggers the agent’s restart_nodes() (SIGKILL + treedb reload), promoting the newest release of every yuno. For a same-version hot-patch (no APP_VERSION bump) you can skip upgrade-yunos: sync, then bounce the affected yunos (kill-yuno + run-yuno / play-yuno).

ℹ️ Fully static builds (CONFIG_FULLY_STATIC=y) reuse the same configure-libs.sh with GCC or Clang — no separate toolchain. OpenSSL is built with no-dso and no-sock to avoid glibc resolver stubs in the static binary. See kernel/c/linux-ext-libs/HACKS.md for details.

Troubleshooting¶

sudo apt-get update
sudo apt-get install rsyslog
sudo systemctl enable --now rsyslog

dpkg-reconfigure locales

Reference¶

License¶

MIT, except for kernel/c/libjwt/* which is MPL-2.0.

Build dependencies (C / Linux)¶

• Jansson — MIT

• libjwt — MPL-2.0

• liburing — MIT, LGPL-2.1, GPL-2.0

• mbedtls — Apache-2.0 or GPL-2.0

• openssl — Apache-2.0

• pcre2 — BSD and others

• libbacktrace — BSD 3-Clause

• argp-standalone — LGPL-2.1

• ncurses — MIT

• llhttp — MIT

Runtime / deploy dependencies¶

• nginx — BSD-2-Clause

• openresty — BSD 2-Clause, BSD 3-Clause, MIT, OpenSSL, Zlib, SSLeay