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.

Files outside /yuneta

Yuneta keeps its files in /yuneta. The binaries, the configurations, the stores and the logs of the yunos are all there. The yuneta-agent package (.deb or .rpm) also puts a small set of files in the system directories, and its install scripts change some system files. This page lists all of them.

The set must stay small. Some sites do not let the user yuneta use sudo. On such a site, the operator can install the package as root and do nothing more. Each file outside /yuneta is a dependency on the administrator of the machine, and each feature that needs root fails on such a site.

To see the list on a node, run one of these commands on that node:

# Debian / Ubuntu
dpkg -L yuneta-agent | grep -v '^/yuneta'
dpkg-query -W -f='${Conffiles}\n' yuneta-agent

# RHEL / Rocky / Alma
rpm -ql yuneta-agent | grep -v '^/yuneta'
rpm -qc yuneta-agent

The first command of each pair lists the files and the directories. The second command lists the configuration files that an upgrade does not replace.

Files in the package

The package contains no compiled binary outside /yuneta. The files below are configuration files, systemd units, shell scripts, and two files of license text.

File.deb.rpmPurpose
/etc/profile.d/yuneta.shconffileconfigPuts /yuneta/bin on the PATH of a login shell.
/etc/sudoers.d/90-yunetaconffileconfigGives the user yuneta NOPASSWD: ALL.
/etc/init.d/yuneta_agentconffileconfigThe SysV script. Under systemd, it drives the two agent units.
/etc/letsencrypt/renewal-hooks/deploy/reload-certsconffileconfigThe certbot hook. It copies the new certificates into /yuneta/store/certs and tells the agent.
/etc/logrotate.d/yunetaconffileconfigRotates the logs of the web server and /var/log/yuneta/*.log.
/etc/fail2ban/filter.d/yuneta-nginx-probe.confconffileconfigThe fail2ban filter for clients that probe the web server.
/etc/fail2ban/jail.d/yuneta-nginx.confconffileconfigTwo fail2ban jails, with enabled = false.
/etc/sysctl.d/99-yuneta-core.confconffileconfigkernel.core_pattern = /var/crash/core.%e and the kernel limits.
/etc/security/limits.d/99-yuneta-core.confconffileconfigThe limits of the user yuneta: core, nofile and memlock.
/etc/yuneta/authorized_keysconffileconfigOnly in a package built with SSH keys.
/usr/lib/systemd/system/yuneta_agent.servicefilefileThe unit of the main agent.
/usr/lib/systemd/system/yuneta_agent22.servicefilefileThe unit of yuneta_agent22, the second agent.
/usr/lib/systemd/system/yuneta-webserver.servicefilefileThe unit of the web server (nginx or openresty).
/usr/lib/systemd/system/yuneta-core-pattern.servicefilenoSets core_pattern again after apport (Ubuntu).
/usr/lib/tmpfiles.d/yuneta-crash.conffilefileMakes /var/crash writable by the group yuneta at each boot.
/usr/libexec/yuneta/yuneta-node-uuidfilefileScript, run as root. It makes the node uuid from the hardware.
/usr/libexec/yuneta/yuneta-agent-certfilefileScript, run as root. It makes the certificate of the agent.
/usr/libexec/yuneta/yuneta-node-labelfilefileScript, run by hand. It prints the label of the box.
/usr/libexec/yuneta/install-packagefilefileScript, run as root by install-package of yuneta_agent22. It downloads, checks and installs a yuneta-agent package.
/usr/share/doc/yuneta-agent/copyrightfilenoThe license. The .rpm puts it in /usr/share/licenses/yuneta-agent/LICENSE.txt.
/usr/share/doc/yuneta-agent/THIRD-PARTY-NOTICESfilenoThe licenses of the third-party code. The .rpm puts it in /usr/share/licenses/yuneta-agent/.

The package also makes two directories: /etc/yuneta and /var/crash.

In the .deb, a “conffile” is a configuration file that dpkg does not replace when the operator changed it. In the .rpm, “config” is a file marked %config(noreplace). When the operator changed such a file, rpm writes the new version next to it as .rpmnew. Every file that the package puts in /etc is in one of these two groups. Up to 7.31.28, the .deb did not mark sysctl.d/99-yuneta-core.conf and limits.d/99-yuneta-core.conf. Each upgrade replaced them and removed the changes of the operator.

The scripts in /usr/libexec/yuneta run as root, so they are not in /yuneta. The user yuneta owns /yuneta, and it must not be able to change a script that root runs.

Changes that the install scripts make

The postinst (.deb) and %post (.rpm) scripts change these system files and objects. These files are not in the package, so the package manager does not remove them.

What.deb.rpm
The user and the group yuneta, with /home/yuneta.yesyes
The user yuneta in a list of groups. The list contains sudo (.deb) or wheel (.rpm).yesyes
/home/yuneta/.ssh/authorized_keys, from /etc/yuneta/authorized_keys.if presentif present
/etc/yuneta/webserver: nginx or openresty. Written once, and kept on an upgrade.yesyes
session required pam_limits.so added to /etc/pam.d/common-session and common-session-noninteractive.yesno
pam_limits.so added to /etc/pam.d/system-auth and password-auth.noyes
en_US.UTF-8 and es_ES.UTF-8 enabled in /etc/locale.gen.yesno
LANG=en_US.UTF-8 in /etc/locale.conf, if that file is empty.noyes
enabled=0 in /etc/default/apport, if that file exists.yesno
/var/crash owned by root:yuneta, mode 0775.yesyes
The kernel settings of 99-yuneta-core.conf, applied at once with sysctl.yesyes
rsyslog enabled and started.yesyes
The units enabled: links in /etc/systemd/system/.yesyes
/run/reboot-required, a hint only. The install never reboots.yesyes
SELinux local policy: a file-context rule bin_t for four files of /yuneta (see below), when SELinux is on. %postun removes the rules at a full uninstall.noyes

/yuneta is outside the policy of SELinux, so SELinux labels its files default_t, and systemd cannot start a default_t file (the unit fails with 203/EXEC). So the %post of the .rpm adds a local rule bin_t (semanage fcontext) for each file of /yuneta that systemd starts, and applies it (restorecon):

On an upgrade, the %post first asks matchpathcon for the label that the policy gives these four files. If it is bin_t for all four, the rules are in place, and the %post runs no semanage (each semanage loads the whole policy). It runs restorecon in every case.

To see the rules and the labels on a node:

semanage fcontext -l -C | grep /yuneta
matchpathcon -n /yuneta/bin/yuneta-webserver /yuneta/agent/yuneta_agent \
    /yuneta/agent/yuneta_agent22 /yuneta/bin/restart-yuneta
ls -Z /yuneta/bin/yuneta-webserver /yuneta/agent/yuneta_agent \
    /yuneta/agent/yuneta_agent22 /yuneta/bin/restart-yuneta

Before an upgrade, the install scripts copy /etc/yuneta/webserver to /etc/yuneta/webserver.pkgsave, and put it back after the upgrade. The .deb preinst also moves a /etc/logrotate.d/yuneta that dpkg does not own to /etc/logrotate.d/yuneta.dpkg-bak. An operator can give a different list of groups with the variable YUNETA_GROUPS at install time.

Two helpers in /yuneta/bin change the system, but only when an operator runs them as root:

What needs root at run time

The agents and the yunos run as the user yuneta. These features use sudo -n. On a node where yuneta cannot use sudo, they fail, and the rest of Yuneta works.

FeatureCommandWithout sudo
Certificate sync of the agent, every 15 minutescert_sync_copy_cmd: /usr/bin/sudo -n /yuneta/store/certs/copy-certs.shThe copy fails and the agent logs a WARNING at each sync. The certbot hook runs as root and copies the certificates. To stop the sync, set cert_sync_enabled to 0.
install-package of yuneta_agent22sudo -n /usr/libexec/yuneta/install-package startThe node cannot install a package through the agent. Root must install it.
install-package-status of yuneta_agent22sudo -n /usr/libexec/yuneta/install-package journal <lines>The answer shows the error of sudo in place of the journal.
upgrade-agent of yuneta_agent22 (source nodes only)sudo -n systemctl restart yuneta_agent.serviceThe new binary is on disk, but the agent does not restart.
restart-yuneta, and the restart action of logcentersudo -n systemctl restart yuneta_agent.serviceThe script refuses and says so.

The package gives sudo to yuneta with the file /etc/sudoers.d/90-yuneta (NOPASSWD: ALL). The package also puts yuneta in the group sudo (or wheel), but yuneta has no password, so the group alone does not give sudo. The standard package keeps this design. A site that does not let yuneta use sudo has two choices:

On such a site, the features of the table above fail as the table says.

Such a site can give sudo for one feature only. For install-package and install-package-status, grant exactly the program and its two subcommands:

# /etc/sudoers.d/91-yuneta-install-package (edit it with visudo -f)
yuneta ALL=(root) NOPASSWD: /usr/libexec/yuneta/install-package start, /usr/libexec/yuneta/install-package journal *

The program checks every value that yuneta wrote, and it reads its own data only from a directory of root. Do not grant systemd-run: its options can run any command. This grant is still equivalent to root, because the operator chooses the package, and the scripts of the package run as root.

Files of /yuneta that root runs

Removing sudo from yuneta does not make yuneta a privilege boundary today. The user yuneta owns /yuneta (the install scripts run chown -R yuneta:yuneta /yuneta), and root runs these files of /yuneta:

FileRun as root byWhen
/yuneta/bin/yuneta-webserver, and the nginx or openresty under /yuneta/bin/nginx/ or /yuneta/bin/openresty/yuneta-webserver.service (it has no User=)At each boot, and at each start of the unit.
/yuneta/bin/nginx/sbin/nginx -s reload (or /yuneta/bin/openresty/bin/openresty -s reload)The certbot deploy hookAfter each renewal of a certificate.
/yuneta/store/certs/copy-certs.shThe certbot deploy hook, and sudo from the agent’s cert syncAfter each renewal of a certificate, and every 15 minutes.
/yuneta/bin/yuneta-webserver type/etc/init.d/yuneta_agent statusEach time root asks for the status.
/yuneta/bin/yuneta-webserver quit and stopThe postinst (.deb) and the %post (.rpm)At each install and upgrade of the package.

Root also works in two places of yuneta without running a file there:

So yuneta can change a file that root runs later, and it gets the rights of root. This breaks rule 5 below. To find these places on a node, run:

systemctl cat yuneta-webserver.service | grep -E '^(User|ExecStart)='
grep -n '/yuneta/' /etc/letsencrypt/renewal-hooks/deploy/reload-certs \
    /etc/init.d/yuneta_agent /etc/logrotate.d/yuneta
# The install scripts of the package
grep -n '/yuneta/bin/' /var/lib/dpkg/info/yuneta-agent.postinst   # Debian
rpm -q --scripts yuneta-agent | grep -n '/yuneta/bin/'             # RHEL

These files no longer run as root (after 7.31.29):

copy-certs.sh opens the keys of /etc/letsencrypt/live/ as root, and yuneta compares them with its copies and writes only the files that changed, in /yuneta/store/certs/. No key is written anywhere else. The script checks the names of certs.list and the paths of the keys, and it refuses a symbolic link in place of a destination directory.

The full fix is a task for a package without sudo, and it is designed:

Files that the software uses at run time

The yunos are static binaries. Static glibc has no NSS and no system resolver, so Yuneta reads these files itself:

The yunos also read these files. They do not write them:

These files are written at run time:

Rules for a change

These rules keep the list short and keep this page correct:

  1. Put a new file in /yuneta when you can. A file outside /yuneta needs a reason that /yuneta cannot meet, for example a path that the system reads (/etc/sysctl.d) or a script that root runs.

  2. If you add, remove or move a file outside /yuneta, update this page in the same commit. Do the same for a system change in an install script.

  3. Mark every file that the package puts in /etc: list it in DEBIAN/conffiles (packages/deb/make-yuneta-agent-deb.sh) and mark it %config(noreplace) (packages/rpm/make-yuneta-agent-rpm.sh).

  4. Do not add a feature that needs sudo when a feature without root can do the work. If a feature needs sudo, add it to the table of root features, with what happens without sudo.

  5. Do not let yuneta write a file that root runs.