Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

Installation

Prerequisites: Linux with a kernel of 5.19 or later (or RHEL / Rocky / Alma 9, see Linux kernel), Python 3.7+, sudo access. The full lists of dependencies and licenses are in Reference.

Yunetas has two installation methods. Your task decides which method you use:

ℹ️ The PyPI package yunetas (pipx install yunetas) is the CLI for management and builds. Its current version is 1.0.7. It is not the C framework runtime, which is at 7.x. The .deb contains the two of them. A build from source uses the CLI to drive the build.


Linux kernel

Yuneta needs Linux 5.19 or later. Its event loop (yev_loop) does all its work with io_uring, and it uses these operations of it:

io_uringSinceUsed for
NOP, POLL_ADD5.1wake-ups, readiness
SENDMSG, RECVMSG5.3UDP
ACCEPT, CONNECT, ASYNC_CANCEL5.5TCP, stopping events
READ, WRITE, IORING_SETUP_CLAMP, the opcode probe5.6sockets, files, timers, signals, inotify
ASYNC_CANCEL with IORING_ASYNC_CANCEL_ALL | ANY5.19stopping the loop: every event still in flight is canceled
SENDMSG_ZC6.1zero-copy UDP send, optional: probed at start, plain SENDMSG without it

5.19 is the floor because of the stop: a loop cannot cancel what it has in flight on an older kernel. Below 5.6 a yuno cannot run at all.

DistributionKernelYuneta
Debian 13 (trixie)6.12✅ (staging and production nodes)
Debian 12 (bookworm)6.1✅ (production nodes)
Ubuntu 24.04 and later6.8+✅ by its kernel (the development machine runs Ubuntu 26.04, kernel 7.0). No package install is tested there
RHEL / Rocky / Alma 95.14✅ — Red Hat backports io_uring into its 5.14: on Rocky 9.7 (5.14.0-611) every operation above is there, CANCEL_ALL | ANY and SENDMSG_ZC included. It is disabled by default: enable it
RHEL / Rocky / Alma 84.18❌ no io_uring at all: Yuneta does not run
Any other kernel below 5.19❌ not supported

A yuno checks this when its loop is created, and on a kernel that does not have it, it says so and stops at its start (a CRITICAL, then an abort): “Linux kernel without io_uring, cannot run yunetas” when there is no io_uring at all (or it is disabled), and “Linux kernel too old for yunetas: it needs Linux 5.19 or later (or RHEL/Rocky/Alma 9)”, with lacks (the operation missing) and kernel (uname -r), when io_uring is there but lacks one of the operations above. Up to 7.25.21 a yuno started on 5.6 to 5.18 and failed only when it stopped. To check a node before installing:

uname -r                                 # 5.19 or later (or an EL9 5.14)
sysctl kernel.io_uring_disabled          # must be 0 (RHEL family: see below)

Quick install

Not on a node that builds from source

The installer refuses a node that keeps the sources in /yuneta/development/yunetas. It looks for kernel/ and .git. The package makes the same refusal when you install it by hand.

The package contains libraries, headers and binaries from a different machine. It puts them in outputs/ and outputs_ext/, the tree that yunetas build owns. After that, the tree is not consistent. New objects link against archives that a different glibc built.

A dynamic link fails with a clear error. A static link is worse, because it resolves the archives with no message. The binary then corrupts its heap at run time. You get a SIGABRT inside malloc some seconds after the start. There is no framework error before it, and the stack shows unrelated code. This is the same fault that libc_guard.cmake catches at configure time.

You can install the package on such a node. But it must be a decision:

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

Put the variable after sudo. The sudo command resets the environment, so VAR=1 sudo … does not reach the scripts of the package. Some nodes are deliberately a build machine and a package node. For those nodes, make the permission permanent with a marker file:

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

Which version a build node shows

On a node that builds from source, read the version from the binary. Do not read it from the package database.

dpkg -l or rpm -q can show an older release than <binary> --version. On a build node, this is the correct state. It is not an upgrade that you must do.

The node builds its own SDK, and it already has that code. The package adds only a version string to the package database.

Tested on

The command above gets a complete test on a new installation of the OS:

DistroPackageTested
Rocky Linux 9 (Blue Onyx).rpm (EL9, x86_64)7.9.11-3 · 2026-08-06
Debian 13 (trixie).deb (amd64)7.9.11-3 · 2026-08-06

The test of Debian 13 uses a VM and a dedicated server. This is deliberate. The faster machine loses a start-up race that the slower machine wins. A snapd bug in the certbot step stayed hidden for this reason. The test of Rocky also includes a reboot. At that moment firewalld starts for the first time, and the agent must start without help.

Other releases of the same families can also work, because the script selects apt or dnf and does not read the version. There is no test for them.

The test at 7.9.11-3 installed the OS again on the two nodes and did a complete test. Only for this reason it found two defects. First, the installer took the oldest package of a release, not the newest. Second, the fail2ban filter matched nothing on a node whose vhost is a single-page app. A node that is already configured shows neither defect.

A container of the target distro builds each package: debian:13 for the .deb (glibc 2.41) and rockylinux:9 for the .rpm (glibc 2.34). This build base decides if a node can compile against the SDK of the package. See the glibc warning below. It has no effect on the binaries of the package, which run on any node.

The script does all the work in one run. There is no second step:

Select a version. It 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 and Alma must have io_uring enabled. The .rpm contains kernel.io_uring_disabled=0 and applies it in %post. If SELinux (Enforcing) or a host policy keeps io_uring disabled, the agent does not start. See the io_uring requirement below. If the agent does not run after the installation, %post prints a warning. The warning names the cause, io_uring or SELinux. It also gives the systemctl status and journalctl commands for the diagnosis.

You can also download the package from the Releases page and install it. This installs the runtime and its declared dependencies only. To add the developer toolchain after that, run sudo /yuneta/bin/install-yuneta-dev-deps.sh, or use the one-line command 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

You can also build the package yourself, for a different architecture or with different options. First build from source. Then run packages/deb/<ARCH>.sh or packages/rpm/<arch>.sh. See packages/README.md.

The package installs the agent, the CLI tools and the bundled openresty under /yuneta/. It creates the yuneta system user. It applies the kernel tuning and the PAM limits. Then it starts the two agents, each in its systemd unit.

The package also installs a sparse SDK under /yuneta/development/yunetas/. This sparse SDK holds the Yuneta libraries, the headers, the CMake toolchain and the build .config (outputs/, outputs_ext/, tools/ and .config, with no sources). This base path is the SAME path as a full source checkout. Your projects thus compile against the published runtime with no source tree and with no difference of layout. The full inventory is in packages/README.md.

🔴 The sparse SDK compiles only on the glibc that built the package. The outputs/lib/*.a files of the package are static archives. They reference internals of glibc, and the layout of those internals changes between releases. If you link new objects against them on a node with a different glibc, the binary corrupts its heap at run time. You get a SIGABRT in _int_malloc some seconds after the start, with no framework error before it and a stack that shows unrelated code. The binaries of the package continue to work, because they are self-contained. Only the build fails. Before you build on a node, do this test:

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

If the two values are different, that node is runtime-only. Build on a different machine and push the binaries with yunetas sync-binaries. tools/cmake/libc_guard.cmake applies this rule at configure time. -DYUNETA_ALLOW_LIBC_MISMATCH=ON removes the message only. It does not make the link safe.

A container of the target distro builds each package. Each package thus matches one glibc only:

PackageBuilt inglibcNodes that can build on-node
.rpm (EL9)rockylinux:92.34Rocky/Alma 9
.deb (AMD64)debian:132.41Debian 13 (trixie)

Thus Ubuntu nodes are runtime-only. Ubuntu 24.04 has glibc 2.39 and Ubuntu 26.04 has glibc 2.43, and neither value is 2.41. Debian 12 is runtime-only for the same reason. Build for those nodes on a different machine and push the binaries. Until 7.8.6-3, an ubuntu-22.04 runner (glibc 2.35) built the .deb. If you have an older package, read its stamp and do not use this table.

ℹ️ Build options of the published .deb. The Kconfig defaults (alldefconfig) compile the release asset. These defaults are GCC, RelWithDebInfo, fully static binaries and the OpenSSL TLS backend (mbedTLS is off). All the modules are enabled: console, mqtt, postgres, test and modbus. The installation puts the exact configuration at /yuneta/development/yunetas/.config. Read that file to know the options of a given package. For a different combination, build from source and select your options with menuconfig. Two examples are mbedTLS for smaller binaries, and a smaller set of modules.

⚠️ The two agents are systemd units: yuneta_agent.service and yuneta_agent22.service. Start, stop and restart them with systemctl. Each unit runs the agent’s own daemon (--start), whose watcher relaunches the agent when it crashes, and writes the watcher’s pid for systemd (--pid-file). Stopping or restarting a unit does not stop the yunos (KillMode=process). The units are independent: one agent can be stopped, upgraded or fail while the other keeps the node reachable, so never stop both at once.

sudo systemctl restart yuneta_agent          # the agent, on its new binary
sudo systemctl status yuneta_agent yuneta_agent22

An agent started by hand runs outside its unit, and systemd does not see it: systemctl status says inactive while it runs, and nothing starts it at the next boot. Do not use yuneta_agent --start on a node with the units. --stop is what the unit’s ExecStop runs. A binary cannot be written over while it runs (ETXTBSY): copy the new one beside it, move it into place, then restart the unit.

cp yuneta_agent /yuneta/agent/yuneta_agent.new
mv /yuneta/agent/yuneta_agent.new /yuneta/agent/yuneta_agent
sudo systemctl restart yuneta_agent

On a node that builds from source, yunetas build installs both agents into /yuneta/agent and warns when they still run the old binary. yunetas restart-agents restarts them in order: it keeps the running binary, restarts the main agent, checks that it answers, and only then restarts agent22.

The unit is named like the SysV script (/etc/init.d/yuneta_agent), so systemd uses it instead of the unit it generated from the script, and service yuneta_agent ... reaches it too (the main agent’s unit alone, service yuneta_agent22 ... reaches agent22’s). The script stays, and under systemd it drives the PAIR of units: sudo /etc/init.d/yuneta_agent start starts both (agent22 once the main agent is up), stop stops the main agent alone (agent22, the escape hatch, keeps running, as the SysV stop always did), status reports both. An agent started by hand outside its unit is stopped first and started in it. Up to 7.25.21 there was no native unit: an agent started by hand was invisible to systemd, and yuneta_agent22 had no unit at all. The web server has its own unit (yuneta-webserver.service) and is not started or stopped with the agent.

How an agent outside its unit is recognized. The SysV script, the packages’ install scripts and install-yuneta-service.sh look for a process named yuneta_agent (or yuneta_agent22) whose argv[0] has that base name, the way the agent’s own --stop finds it. The SysV script has the same name, but its argv[0] is its shell, so it is not taken. To see what they see:

for p in $(pgrep -x yuneta_agent); do
    printf '%s: ' "$p"; tr '\0' '\n' < "/proc/$p/cmdline" | head -n 1
done
# 4120: /yuneta/agent/yuneta_agent      <- the agent
# 4377: /bin/sh                         <- the SysV script

Up to 7.30.17 they read /proc/<pid>/exe instead. That fails when /yuneta is a symlink, when the running binary was renamed (yuneta_agent.bak-pre-<version>), and when root has no CAP_SYS_PTRACE (a container by default): the agent was then not found, and an .rpm upgrade left the old agent running.

ℹ️ You can build the .deb yourself and not use the published asset. See packages/README.md for the four wrapper scripts, one for each architecture (AMD64.sh, ARM32.sh, ARMhf.sh, RISCV64.sh). The SDK must be built first (next section). On riscv64 the package has no openresty, because its LuaJIT does not support that architecture. configure-libs.sh skips it with a warning, and the node serves with nginx (the default).

Tests after a fresh install

There are six tests, and they apply to the two distro families. Run them immediately after the one-line command ends. They find all the faults that occurred 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, and systemd sees them running
systemctl is-enabled yuneta_agent yuneta_agent22 yuneta-webserver
systemctl is-active yuneta_agent yuneta_agent22 yuneta-webserver

# 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

# 6. The node uuid comes from the hardware, not from chance
sudo /usr/libexec/yuneta/yuneta-node-uuid show   # source: not "random"

# 7. The agent's certificate is this node's own (7.30.6+)
sudo /usr/libexec/yuneta/yuneta-agent-cert show  # state: own

The node uuid is a function of the machine. A reinstall gives the same uuid, two machines never give the same uuid, and a cloned disk gets its own uuid on its first start. The control center knows a node by it.

The stored file is only the answer written down. When the hardware gives another uuid, ensure replaces the stored uuid, keeps a copy of the old file and logs a warning: a disk in other hardware, a card added with a lower MAC, or a uuid made by an older release. The uuid is kept only when something is missing at one start and nothing new is here: the chip gives no value, or the interface the uuid was made from is missing while the DMI uuid is the same and no new card is present.

sudo /usr/libexec/yuneta/yuneta-node-uuid show
# hardware: machine -> 8eebab45-a352-8300-9516-fe077f8e0995
# status:   the stored uuid is the one this hardware gives

A node installed with 7.29.1 to 7.31.2 gets the uuid of its hardware at its first ensure of 7.31.3 (a new uuid, and its agent key changes too): restart both agents and every yuno, and accept the node again in each control center (see below). A uuid set by hand is never changed. yuneta-node-uuid unset goes back to the uuid of the hardware.

A value that the script knows as a placeholder is not an identity, because all the boxes of the model give it. Example: the devicetree serial-number of an Orange Pi RV2 is 0123456789ABCDEF on every board, so up to 7.30.2 two of these boards got the same uuid. A uuid made from a placeholder is replaced by the uuid of this hardware (here the SoC serial), or by a random uuid when the box has nothing else. ensure keeps a copy of the old file and logs a warning. Restart both agents and every yuno after that (see below).

sudo /usr/libexec/yuneta/yuneta-node-uuid show
# hardware: devicetree-serial gives the stored uuid from a placeholder, no identity: ensure replaces it with soc-serial -> c9936647-...
sudo /usr/libexec/yuneta/yuneta-node-uuid ensure

If the chip gives no value at one start (a driver that did not load), the uuid is kept and ensure logs a warning. If it gives another value, this is other hardware (a cloned card), and the box gets the uuid of its own chip.

In a container random is correct: its /sys is the host’s, so no hardware is read there. The uuid belongs to the container’s hostname, which the file records: a restart of the container keeps it, and a container with another hostname makes its own. A container with no hostname records "": its uuid is kept across its restarts, and a copy of it that has a hostname makes its own. A Docker or Podman container takes its own id as hostname, so a re-created container is a new node. To keep the identity of a re-created container, give it a fixed hostname:

docker run --hostname node-01 -v yuneta-store:/yuneta/store my-yuneta-image

There is a limit. Nothing inside a container tells a copy of it from the same container re-created over its kept store. So two containers that have the same hostname and the same uuid.json share the uuid. This occurs when you commit an image from a container that has a uuid, and then run it twice as --hostname node-01. Before a docker commit or a docker export, delete the uuid file. If copies already share a uuid, set a uuid in each copy (yuneta-node-uuid set <uuid>):

sudo rm -f /yuneta/store/agent/uuid/uuid.json    # in the container, before the commit

A board written from a docker export is not a container: it starts its own init in the initial pid namespace. Thus the /.dockerenv that it keeps does not count. The /run/systemd/container of an Ubuntu image (it contains docker) does not count either, if /run is not a tmpfs. The random uuid of the container is not the uuid of the board, also with the same hostname: on its first start the board gets the uuid of its hardware (or a new random uuid if it has no identifier), keeps a copy of the old file and logs a warning.

The script finds a container from the pid namespace first. A system that starts on its own runs in the initial pid namespace, and a container does not. Thus all processes out of the initial pid namespace are in a container, also without a marker file: a BuildKit RUN step (no /.dockerenv, no container=), and containerd or Kubernetes. The marker files (/.dockerenv, /run/.containerenv) only give the name. In the initial pid namespace, only what this start made counts, because an image can keep files:

In the initial pid namespace, the script also compares / with the root of PID 1 (/proc/1/root), as systemd-detect-virt --chroot does:

Only a root with CAP_SYS_PTRACE in the initial user namespace can look at the root of PID 1, and a security module or the container runtime can refuse it also to that root. The root of Docker has no CAP_SYS_PTRACE, and the root of rootless Podman is in a user namespace. A root that you start without CAP_SYS_PTRACE on the box itself (with setpriv, capsh, a CapabilityBoundingSet= or a hardened provisioning agent) has the mount of PID 1 on /: the script reads the hardware.

The mount does not tell a chroot from a container. If the script cannot look at the root of PID 1 and / is another mount, the script treats it as a container, and the marker files give the name.

If /proc/1/mountinfo cannot be read either (for example, a security module refuses both files to a pod that runs with hostPID), the mount does not tell. Then the script uses the capabilities: a root in a user namespace, or a root without CAP_SYS_PTRACE, is a container, and the script does not read the hardware. Any other user (a root with CAP_SYS_PTRACE, or not root) is the system, and the script reads the hardware.

# As root: the same question that the script asks
sudo systemd-detect-virt --chroot; echo $?   # 0 = a chroot, 1 = not
# The mount on /, of PID 1 and of this shell: the same two fields = no chroot
awk '$5 == "/" {print $3, $4}' /proc/1/mountinfo /proc/self/mountinfo

systemd-detect-virt --chroot also fails where root cannot look at the root of PID 1.

To see what the script finds in a build step, emulate the step without Docker:

# As a normal user: a pid namespace of its own and no /.dockerenv,
# as in a BuildKit RUN step
unshare -Upf --mount-proc /usr/libexec/yuneta/yuneta-node-uuid show
# hardware: none read: this is a container (container-other), ...
readlink /proc/self/ns/pid       # pid:[4026531836] = the initial namespace

The package’s install stores nothing in a container or a chroot (ensure --installing), because the install can be the build of an image (a RUN step of a docker build too). Without systemd, the install also does not start the agents there. Otherwise, their start stores a uuid in the image. Start them in the container (/etc/init.d/yuneta_agent start). Their first start makes the uuid and the agent’s pair. A container that starts the agents without their units or the SysV script runs both scripts first, as root and in this order: the pair is bound to the node uuid (see the agent’s own certificate).

/usr/libexec/yuneta/yuneta-node-uuid ensure
/usr/libexec/yuneta/yuneta-agent-cert ensure
# then the agents, as yuneta

The agents and the yunos read the uuid when they start. If the uuid changes (a disk moved to other hardware, yuneta-node-uuid set <uuid>, a random uuid replaced by the uuid of the hardware, or a uuid made by an older release), restart both agents and then every yuno: the package restarts the agents only.

sudo systemctl restart yuneta_agent; sudo systemctl restart yuneta_agent22
sudo -u yuneta ycommand -c 'kill-yuno'; sudo -u yuneta ycommand -c 'run-yuno'

A changed uuid also changes the node for its control centers, which know it by its uuid and its key. The pair that yuneta-agent-cert made is bound to the old uuid, so the agents’ restart makes a new pair and removes the old key (see the agent’s own certificate). This is true also after set <uuid> with the uuid the node had before. Accept the node again in each control center (1996 and 1997), with its uuid and its new key, both read on the node after the restart:

# on the node
sudo /usr/libexec/yuneta/yuneta-agent-cert show      # node: <its uuid>
openssl x509 -in /yuneta/agent/certs/yuneta_agent.crt -noout -pubkey \
    | openssl pkey -pubin -outform DER | sha256sum
# through each control center
accept-node node_id=<its uuid> spki_sha256=<the sha256 read on the node>

The script’s warning says the same: “... accept the node again in each (accept-node node_id= spki_sha256=)”.

When many nodes must be accepted at once, an operator can open an enrollment in each control center for some minutes instead (7.31.15+, open-enrollment minutes=10 max_nodes=20). It accepts a node with no key accepted, never a node accepted with another key, so a node whose key changed still needs accept-node.

A node that builds from source does not install the package, so it keeps the random uuid until it is given the script by hand, from its checkout:

sudo packages/install-yuneta-node-uuid.sh -n   # what it would do
sudo packages/install-yuneta-node-uuid.sh      # install, and the uuid

It does what the package does (the script, root’s, and the ExecStartPre of both agent units, as a drop-in) and only what differs, so a second run says “Nothing changed” with the same uuid: that is also how to check any node, with the package or without it.

The label of a box

Run this on the box, as root, after the package is installed:

sudo /usr/libexec/yuneta/yuneta-node-label --title CONTROLLER
# title:  CONTROLLER
# uuid:   1a048bb3-e76d-8081-820e-4dea17a518d7
# short:  1a048bb3
# source: soc-serial
# model:  ky x1 orangepi-rv2 board
# port:   end0 c0:74:2b:fa:50:94
# port:   end1 c0:74:2b:fa:50:95
# qr:     1A048BB3-E76D-8081-820E-4DEA17A518D7

# The printable label, from another machine
ssh <box> 'sudo /usr/libexec/yuneta/yuneta-node-label --title CONTROLLER --svg -' > label.svg

Print label.svg from a browser, or give the text fields to the software of a label printer. The SVG needs qrencode on the box. The package recommends it, so apt installs it by default.

A field box is known by its node uuid. A central declares the box with it, and an installer finds the box with it in a list of pending boxes. The uuid is a hash of the hardware, so it exists only after the box starts with the package. The label of the maker does not give it. Thus the box makes its own label, at the time it is installed.

The tool refuses to make a label in two cases:

A uuid from the machine source (an x86 box, a VM) gives a warning. A network card with a lower MAC changes that uuid.

The label carries these items:

The SVG is 62 mm wide, a common size of label roll. Its height grows with the number of ports. Nothing on the label is a secret: the uuid identifies the box, but it does not authenticate it.

The agent’s own certificate

The agent serves /yuneta/agent/certs/yuneta_agent.{crt,key} on its secure port (wss://...:1993). Up to 7.30.5 that pair came with the agent, the same on every node, and its key was published with the source. Since 7.30.6 each node makes its own: yuneta-agent-cert ensure (the package’s install, both agents’ units before each start, after yuneta-node-uuid ensure, and the agent’s build on a node that builds from source) makes a pair when there is none or when it is the published one, keeping a copy of the old files, and keeps any other pair. The new pair is EC P-256, valid from 2000 to 2126, named yuneta_agent.yuneta.io (the name the clients already check) with the host’s name in its SAN.

An agent without its pair keeps running. Its secure port does not listen, and it says why once (the ERROR of the missing file, then “TLS server without its TLS context: not listening, trying again”). 1991 still serves ycommand, and the agent still manages its realms and yunos. The port opens by itself when the pair is there (the next try, 60 s at most), or at once with reload-certs. Up to 7.30.17 the agent exited with code 0, and only a start by hand brought it back:

sudo /usr/libexec/yuneta/yuneta-agent-cert ensure
ycommand -c 'command-agent service=agent_secure_port command=reload-certs'

Since 7.30.10 the same pair is also who the node is to its control center: the agent presents it as the client certificate of its link, and the control center pins the node’s uuid to its key once an operator accepts it (controlcenter, “Each node’s key”). A new pair (another key) is a node the control center has to accept again. Since 7.30.11 that key is also the agent’s login to its control center: a node needs no token in its agent’s json. To read the key the control center will show for a node (spki_sha256):

openssl x509 -in /yuneta/agent/certs/yuneta_agent.crt -noout -pubkey \
    | openssl pkey -pubin -outform DER | sha256sum

So a copy of a node must not keep its key: a disk or SD copied from a box that already started, a VM template, a docker commit of a started container. If it keeps it, every copy presents the same key, and any of them can claim the node of another. Each pair that yuneta-agent-cert makes is bound to the node uuid it was made for, written beside it in /yuneta/agent/certs/yuneta_agent.uuid. A copy whose hardware gives another identifier gets its own node uuid on its first start (yuneta-node-uuid, which runs first), so ensure finds a pair made for another uuid (state: cloned): it makes a new pair and logs a warning. It keeps a copy of the old certificate (it is public), but not of the old key: that key is the other node’s login, so it is overwritten and removed. Both agents’ units run ensure (the two agents serve the same pair, and the script locks, so their runs do not overlap), so neither serves the copied key. Restart both agents if they were already running, and accept the copy’s key in the control center as a new node’s. A pair made by an earlier version has no yuneta_agent.uuid: ensure binds it to the node uuid it finds, so take the image after one ensure of this version. A pair that the script did not make (a certificate of your own CA) is never bound and never replaced.

A copy that keeps the uuid keeps the key, and nothing warns. That is the case when:

Give such a copy its own uuid before its agents start (or restart them after), then make its pair, as root:

cat /proc/sys/kernel/random/uuid                     # a new uuid
/usr/libexec/yuneta/yuneta-node-uuid set 7d3f0a52-9c1e-4b8a-a6d4-2e5f8c1b9a03
/usr/libexec/yuneta/yuneta-agent-cert ensure         # state: cloned -> a new pair

Then accept the copy as a new node, with its uuid and its key (see above). On a node that builds from source, run install-yuneta-node-uuid.sh first.

sudo /usr/libexec/yuneta/yuneta-agent-cert show
# state:   cloned
# node:    16b087c8-46c2-8d38-8928-ea7a11521ec6
# bound:   ab81a85f-a234-8d07-9345-928dbac002e6
#          a pair made for another node uuid (a cloned disk): run 'ensure'
sudo /usr/libexec/yuneta/yuneta-agent-cert ensure
# WARNING: the agent's pair was made for node uuid ab81a85f-..., and this
# node is 16b087c8-... (a cloned disk or image): a new pair (sha256 ...), the
# old certificate kept and its key removed (it is the other node's login) ...
sudo /usr/libexec/yuneta/yuneta-agent-cert show
# state:   public   -- the published pair: 'ensure' replaces it
sudo /usr/libexec/yuneta/yuneta-agent-cert ensure
sudo systemctl restart yuneta_agent; sudo systemctl restart yuneta_agent22   # both serve the new pair

A node that builds from source gets the units’ step by hand, as for the uuid (a drop-in zz-yuneta-agent-cert.conf in both units: systemd runs drop-ins in the order of their names, so it runs after yuneta-node-uuid.conf. The yuneta-agent-cert.conf of up to 7.30.14 ran before it and is removed):

sudo packages/install-yuneta-agent-cert.sh -n   # what it would do
sudo packages/install-yuneta-agent-cert.sh      # install, and the pair

It refuses a node without /usr/libexec/yuneta/yuneta-node-uuid: run install-yuneta-node-uuid.sh first. A git pull does not update the installed scripts or the drop-ins. The agent’s build (yunetas build) warns when they are not the checkout’s, and tells you to run both installers again:

CMake Warning: /usr/libexec/yuneta/yuneta-agent-cert is not this tree's;
  /etc/systemd/system/yuneta_agent.service.d/yuneta-agent-cert.conf is of
  7.30.14 (it runs before the node uuid).  From this checkout, as root, one
  after the other: packages/install-yuneta-node-uuid.sh, then
  packages/install-yuneta-agent-cert.sh

It also warns when only one of the two scripts is installed: the pair is bound to the node uuid, so each one needs the other.

The same build compares /etc/init.d/yuneta_agent with the checkout’s SysV script (yunos/c/yuno_agent/service/yuneta_agent). Without the units, this script starts the agents, and the script of up to 7.30.15 does not run yuneta-node-uuid or yuneta-agent-cert. The warning tells you to run the service helper, which replaces it:

CMake Warning: /etc/init.d/yuneta_agent is not this tree's (without the
  units it starts the agents, and up to 7.30.15 it ran neither
  yuneta-node-uuid nor yuneta-agent-cert).  As root:
  /yuneta/agent/service/install-yuneta-service.sh (it keeps the old one
  beside it, and starts or restarts both agents)
sudo /yuneta/agent/service/install-yuneta-service.sh
# /etc/init.d/yuneta_agent replaced by this agent's, the old one kept as
#   /etc/init.d/yuneta_agent.20261108120000.bak

The old script stays beside the new one, not executable, so no init system runs it. Then the helper restarts the units, but only where yuneta_agent.service exists, as the SysV script decides. On a node without the units it enables and starts the SysV script, also under systemd. Up to 7.30.16 a systemd without the units was enough: the helper stopped the agents that ran outside, failed to restart a unit that does not exist, and left them stopped with exit 0. Now, when a restart fails, the helper says so and exits 1, and it leaves yuneta_agent22 as it is.

A client that trusted the old certificate to reach a node’s port 1993 needs the node’s new one -- it is public, copy it (a node whose agent serves a certificate of a public CA on 1993, set in its json, is not concerned):

scp yuneta@node:/yuneta/agent/certs/yuneta_agent.crt ~/.yuneta/certs/node.crt
yunetas register-node node --url wss://node:1993 \
    --ssl-trusted-certificate ~/.yuneta/certs/node.crt \
    --ssl-server-name yuneta_agent.yuneta.io

If the node must build software, do the glibc-stamp test above too.

One result looks like a fault and is correct: on RHEL, certbot-renew.timer is enabled but inactive until the next boot. And one is a fault even if the agent answers: systemctl is-active yuneta_agent answering inactive while ps shows the agent means it was started by hand, outside its unit (see above). After a restart of a unit, its journal says “Found left-over process ... in control group” for the yunos the agent launched: they are meant to survive the agent, and that is the line saying so.

Logs and banning

The package also configures the logs of the web server. nginx does not rotate its logs, and it does not ban an attacker.

The rotation is automatic. /etc/logrotate.d/yuneta rotates the access log and the error log of the web server of the node, one time each day. It keeps 30 compressed files. Without this rotation, those files increase in size for the full life of the node. nginx has no rotation function. It can only open its files again when it receives a signal.

The ban function is installed, but it is OFF. /etc/fail2ban/jail.d/yuneta-nginx.conf contains two jails. They ban a client that probes the node for .php paths, .env, .git or the WordPress paths. A Yuneta node serves none of these, thus such a request cannot be an error.

The jails are disabled deliberately. If the log path of a jail matches no file, fail2ban does not omit that jail. It refuses to start, and all the other jails stop with it, sshd included. A node that has the package and has not started its web server is in this condition.

When access.log exists, enable the jails:

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 test the firewall, not the jail. If banaction names a command that the node does not have, the jail reports a good condition but bans nothing. On Debian that command is nft. The nftables package supplies it, and a minimal installation does not.

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

⚠️ With SELinux in Enforcing mode, the log paths of the package do not work. The paths are globs, and fail2ban_t cannot list /yuneta/bin. SELinux dontaudits this denial, thus it writes no AVC. fail2ban then reports “Have not found any log file” and stops. No message names SELinux. Give the jails a literal path in the same zz- file. Then label the directory with semanage fcontext -a -t var_log_t "/yuneta/bin/nginx/logs(/.*)?" and restorecon -R /yuneta/bin/nginx/logs.

The full detail is in packages/deb/README.md.


Build from source

The seven steps below install the full SDK at /yuneta/development/yunetas, the same path on every node (see the layout contract in step 5). The SDK holds the sources, the build dependencies and the tools.

1. Create the yuneta user

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

Close the session. Then start a new session as the yuneta user for the other steps.

2. Install OS packages

The repo contains a helper script. It installs all the packages below, the kconfiglib backend for menuconfig, and myst-plain-lint, the plain-English check of the docs. It reads /etc/os-release to find the distro family: Debian and Ubuntu, or RHEL, Rocky, Alma and Fedora. It is in the repo, so clone it first (step 4), then return to this step:

cd /yuneta/development/yunetas
./install-dependencies.sh

To run the package manager yourself, select your distro below.

Debian / Ubuntu
RHEL / Rocky / Alma / Fedora
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 gh \
  build-essential pkg-config ca-certificates linux-libc-dev

pipx install kconfiglib
What each non-obvious package is for
  • libjansson-dev / jansson-devel — required for libjwt

  • libpcre2-dev / pcre2-devel — required by nginx and openresty, which link PCRE2. PCRE1 (libpcre3-dev / pcre-devel) is not needed: Debian 13 and Rocky 10 no longer have it

  • perl dos2unix mercurial wget — required by openresty (wget fetches its tarballs)

  • pipx kconfiglib — yunetas configuration tool

  • pipx myst-plain-lint — plain-English (ASD-STE100) check of the docs, from artgins/myst-plain-english

  • kconfig-frontends — alternative configuration tool (Debian only)

  • telnet — required by tests

  • gh — GitHub CLI, to work with the repositories (releases, issues, pull requests)

3. Install the yunetas CLI

With `pipx`
With `conda`
sudo apt install pipx     # Ubuntu 23.04+
pipx ensurepath
pipx install yunetas
Older Ubuntu (≤22.04)
python3 -m pip install --user pipx
python3 -m pipx ensurepath
Update / uninstall
pipx upgrade yunetas
pipx uninstall yunetas

4. Clone the repo

mkdir -p /yuneta/development
cd /yuneta/development
git clone --recurse-submodules https://github.com/artgins/yunetas.git
Pin a specific version
git clone -b <version> --recurse-submodules https://github.com/artgins/yunetas.git <version>

5. Activate the environment

cd /yuneta/development/yunetas
source yunetas-env.sh

yunetas-env.sh exports four variables. It also puts /yuneta/bin and $YUNETAS_BASE/scripts at the start of PATH:

VariableValue
YUNETAS_BASEThe yunetas repo root (the dir you sourced from).
YUNETAS_OUTPUTS$YUNETAS_BASE/outputs
YUNETAS_OUTPUTS_EXT$YUNETAS_BASE/outputs_ext
YUNETAS_YUNOS$YUNETAS_OUTPUTS/yunos

ℹ️ Layout contract. The build artifacts (outputs/ and outputs_ext/) are INSIDE $YUNETAS_BASE. Git ignores the two directories. The base is the SAME path on every node: /yuneta/development/yunetas/. On a development node it is a full source checkout. On a runtime-only node it is the sparse SDK from the .deb or the .rpm (outputs/, outputs_ext/, tools/ and .config, with no sources). Your own project repos can be at any path. Register them with yunetas register-project (below).

⚠️ Source the file again in each shell. A new SSH session, a cron job and CI must source yunetas-env.sh again. Without it, ybatch, ycommand and yshutdown are not on PATH. The deploy scripts then fail with “command not found”.

To make this permanent, add this line to ~/.bashrc:

source /yuneta/development/yunetas/yunetas-env.sh

If ~/.yunetasrc exists, the script sources it too. Use that file for your own additions.

6. Configure (menuconfig)

cd /yuneta/development/yunetas
menuconfig

Select the compiler, the build type and the modules. Then save. This writes .config, and the build needs that file.

Full menuconfig options
(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 change the compiler, run ./set_compiler.sh again. It builds the external libraries with the correct toolchain.

7. Build and test

First, build the bundled external libraries. You do this one time only:

cd /yuneta/development/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 CLI is the standard build interface, with the commands init, build, clean and test. Use it, and do not call cmake directly. The CLI does the installation to $YUNETAS_OUTPUTS/lib and the relink of each yuno in the correct order:

cd /yuneta/development/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

The artifacts go to $YUNETAS_OUTPUTS/, which is $YUNETAS_BASE/outputs/. The subdirectories are include/, lib/, bin/ and yunos/.

Raise the inotify limits before yunetas test. timeranger2 opens one inotify instance per watched topic (the master’s watch of disks/, and one per rt_disk reader), and all of them count against ONE per-user limit. The Linux default is 128, and some treedb tests open more than that in one process: they fail with “inotify_init1() FAILED”, errno 24, “The user limit on the total number of INOTIFY INSTANCES has been reached”. A node installed from the .deb/.rpm already has the right values (/etc/sysctl.d/99-yuneta-core.conf). A machine that only builds from source needs them set by hand:

sudo tee /etc/sysctl.d/99-yuneta-inotify.conf <<'EOF'
fs.inotify.max_user_instances = 4096
fs.inotify.max_user_watches = 524288
fs.inotify.max_queued_events = 65536
EOF
sudo sysctl --system

Run the tests as the yuneta user (step 1), never as root: a yuno refuses to start for a user that is not yuneta and not in the yuneta group, and a run as root leaves root-owned state under /yuneta and /tmp that makes the next run as yuneta fail with Permission denied.

External projects

The yunetas CLI can also build your own projects. A project is any repo whose yunos/CMakeLists.txt includes tools/cmake/project.cmake. Register a project one time. Then init, build and clean process it immediately 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 user state of the local machine (~/.yuneta/projects.json). It stays outside the source tree.

A deploy has two steps. First push the artifacts. Then promote them. The helpers below run the agent tools that ship inside the CLI package. They forward the shared arguments without a change: -n for a dry run, -a for all, and the OAuth2 options. The yunetas CLI gives the full CLI reference, with the build commands and the project-management commands:

# 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 kinds of artifact with sync. Do not push them one at a time. A new binary must never go to a node without its new configuration.

One example shows the risk. A new fail-closed runtime verifies TLS by default. Against an old configuration with no CA, the OIDC login fails. sync connects the two steps, thus you cannot forget one. If the push of the binaries fails, sync stops before the configurations. There is no half-deploy. (Up to CLI 0.21.2 a failed push did not stop sync: the tool exited with 0.)

The individual helpers stay available. Use them when you need one kind only, or a flag of one tool:

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 reads the registered projects, and the configuration pass of sync does the same. Without --host, it asks the local agent for its realms (*list-realms). It then syncs every batches/<host>/ directory whose name is a realm_id of that agent. A node with several realms thus deploys all of them in one pass. The name of a batches directory is its realm_id, which is the deploy FQDN. If the agent does not answer, the tool matches one hostname only.

upgrade-yunos does four operations:

  1. It makes an optional snapshot for a rollback. The name makes it idempotent, and the default name is pre-upgrade-<YYYYMMDD>. Use --no-snap to omit the snapshot. If a snap is already active, the tool uses that one.

  2. It shows the new yuno rows that find-new-yunos creates, and it asks for a confirmation. Use --yes to omit the question.

  3. It registers those rows with find-new-yunos create=1.

  4. It runs deactivate-snap. This starts restart_nodes() in the agent, which does a SIGKILL and a treedb reload. The agent then promotes the newest release of every yuno.

A hot-patch of the same version has no change of APP_VERSION. For that case you can omit upgrade-yunos. Run sync. Then restart the affected yunos with kill-yuno and run-yuno or play-yuno.

ℹ️ Fully static builds (CONFIG_FULLY_STATIC=y) use the same configure-libs.sh with GCC or with Clang. They need no different toolchain. The build of OpenSSL uses no-dso and no-sock. This keeps the glibc resolver stubs out of the static binary. See kernel/c/linux-ext-libs/HACKS.md for the details.


Troubleshooting

Restore /var/log/syslog
sudo apt-get update
sudo apt-get install rsyslog
sudo systemctl enable --now rsyslog
Correct the “Setting locale failed” warnings
dpkg-reconfigure locales

Reference

License

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

Build dependencies (C / Linux)

Runtime / deploy dependencies