unit-redis
==========

The Redis component of Keel Linux, as a fab unit: a directory carrying a
``plan``, an ``overlay/`` and an executable ``conf``, which fab resolves and
applies when the recipe being built has it under ``unit.d/`` (``UNIT_DIRS``
in ``share/product.mk``). Compatible with TurnKey Linux appliances.

Unlike ``unit-mariadb`` and ``unit-postgresql``, nothing here was extracted
from the shared tree, because there was nothing to extract:
``turnkeylinux/common`` has no ``conf/redis``, no ``overlays/redis`` and no
``plans/turnkey/redis``. The upstream ``redis`` appliance named its packages
in its own ``plan/main`` and configured the server from its own recipe and
two first boot hooks. So this component is new code, written to the rules the
project arrived at with the other two engines.

Why a repository, and why this name
-----------------------------------

Decision 0006 gives appliances the ``keel-`` prefix and leaves
infrastructure unprefixed. A component is neither: not an appliance, and not
a fork of an upstream repository. ``unit-`` names the artefact in the
vocabulary of the build system that consumes it, and the name after the dash
is the directory under ``unit.d``, which is the name the layer manifest
carries::

    keel-linux/unit-redis   ->   unit.d/redis   ->   units redis@1.0.0

What it carries
---------------

========================================  ===================================
File                                      What it is
========================================  ===================================
``plan``                                  ``redis-server``, which pulls
                                          ``redis-tools`` at its own version
``overlay/etc/redis/redis.conf.d/``       the bind addresses, and who may do
                                          what before any secret exists
``overlay/usr/lib/inithooks/``            the first boot hook, its library
                                          and its dialog
``conf``                                  the include line, and the running
                                          server asked what it is doing
``version``                               the pin ``bt-layer`` records in the
                                          layer manifest
========================================  ===================================

There is no ``conf-vars``: fab lets a unit name the build time variables its
conf script reads, and this one reads none. There is no ``removelist``: this
component takes nothing out of the image.

The bind addresses
------------------

::

    bind ::1 127.0.0.1

Debian ships ``bind 127.0.0.1 -::1``. The dash is Redis's mark for an
optional address: if ``::1`` cannot be bound the server starts anyway and
says nothing, which is a server that answers one family and looks right.
Both are named here without it.

A name is never used, and that is the trap this project has already paid
for. Debian's ``/etc/hosts`` maps ``::1`` to ``ip6-localhost`` and
``ip6-loopback`` and never to ``localhost``, so ``bind localhost`` resolves
to ``127.0.0.1`` alone; the PostgreSQL appliance shipped listening on IPv4
only for exactly that reason (docs/traps.md, "On Debian, ``localhost`` is not
an IPv6 name"). Two literal addresses cannot resolve into something else.

The port is not opened to the network. This component is what an appliance
that needs Redis is built on, and those talk to it from the same machine.
Opening it, saying who may reach it and terminating TLS is a decision the
appliance makes, and the console modes of decision 0013 are where it will be
made.

What the declared secret means here
-----------------------------------

``secrets.db_password`` of the instance description renders to ``DB_PASS``,
the same variable every database hook of this project reads. On MariaDB it
is a database account's password and on PostgreSQL a role's. **Redis has
neither.** Its secret is one of two things: ``requirepass``, which is the
password of the built in ``default`` user, or an ACL user with a password of
its own.

This component uses **an ACL user**, and the account is ``admin``
(``app.options.db_user`` of the description renames it). So the declared
secret is the password of that ACL user, and a client authenticates with a
user name and that password::

    REDISCLI_AUTH=$(cat /etc/keel/secrets/db_password) \
        redis-cli -h ::1 -p 6379 --user admin PING

Two reasons for the ACL user rather than ``requirepass``, and both are
properties an operator can check:

1. **``requirepass`` would also lock ``INFO``.** ``keel inspect`` reads
   ``database.server.role`` from ``INFO replication`` and ``INFO cluster``,
   it never reads a secret to get past a refusal, and a Redis it cannot ask
   is reported as a role it could not infer. An appliance that cannot say it
   is ``standalone`` cannot say it is a ``primary`` or a ``replica`` either,
   and that reading is the seam the replication modes of decision 0013 are
   built on. So the ``default`` account is left able to run one command,
   ``INFO``, with no key and no channel: the three questions inspect asks
   are answered without a secret, and ``GET`` on any key is refused with
   ``NOPERM``.
2. **``requirepass`` lives in a world readable file.** The package ships
   ``/etc/redis/redis.conf`` as ``root:root 0644``, so the upstream
   appliance wrote the Redis password into a file every local account could
   read, and shipped ``turnkey-redis-pw get`` to print it back out. An ACL
   rule takes the **SHA-256** of a password instead of the password, and
   this component writes that digest into
   ``/etc/redis/redis.conf.d/50-keel-secret.conf`` as ``root:redis 0640``.
   The password itself exists on the machine only in the file the
   description points at.

Before the first boot **the administrative account does not exist**, and
that is deliberate rather than an omission. ``keel-mariadb`` publishes its
account with a password hash no input produces; the same shape was tried
here, ``user admin off`` at build time and the real rule at first boot, and
Redis refuses it:

    Error in user declaration 'admin': Duplicate user found.
    A user can only be defined once in config files

So the account is declared once, by the first boot, or not at all. The
property that mattered is the same either way: a layer is published once and
reused by every appliance built on it, so a password chosen at build time
would be the same password everywhere, and a random one would make the layer
irreproducible (brief section 5.4).

Three Redis behaviours are worth stating on their own, because the checks in
this component are written around them and each one cost a build or a boot.

**redis-cli exits 0 when the server answers with an error.** A wrong password
prints ``AUTH failed: WRONGPASS ...`` and then the command's own refusal, and
exits 0. So the hook, the conf script and the appliance's boot test all read
the answer and never the exit code.

**Redis speaks CRLF.** Every line of an ``INFO`` reply ends ``\r\n`` and
redis-cli prints the reply as it came, so a grep anchored with ``$`` never
matches a whole line.

**Redis opens every value its ``logfile`` setting is ever given.** A
``--logfile`` on the command line does not stop the packaged path being
created first, so a check that runs the server as root leaves
``/var/log/redis/redis-server.log`` owned by root in a directory the redis
user owns, and the service cannot start at all afterwards. The conf script
takes an empty one away again.

How configuration is added
--------------------------

Not by editing Debian's ``redis.conf``, beyond one appended line::

    include /etc/redis/redis.conf.d/*.conf

Redis keeps the last value it read for a directive, and its own manual says
to put an ``include`` last when the included file is meant to override. So
the fragments win, the 110 kB conffile keeps every other default and every
comment, and a package upgrade has one line to ask about. An include whose
glob matches nothing is read as nothing rather than as an error, which is
why the conf script checks that the fragments the overlay ships are there.

The fragments are read in the order the glob sorts them, so 10 is the bind,
20 is who may do what, and 50 is the account the first boot writes, which
therefore replaces the one 20 published.

How a recipe consumes it
------------------------

::

    git clone --branch v1.0.0 https://github.com/keel-linux/unit-redis.git \
        $FAB_PATH/products/redis/unit.d/redis
    bt-layer redis --parent core

``bt-layer`` reads ``version``, records ``units redis@1.0.0`` in the layer
manifest, and a child layer built on that one subtracts the component
instead of applying it again. Assembling ``unit.d`` from the pins a recipe
declares is the step decision 0010 names as new code of the project and does
not exist yet: today the clone above is the assembly step, and the layer
manifest is the record of what was applied.

Order in the build
------------------

fab applies every unit overlay, then every unit conf script, then every unit
removelist, after the common overlays, conf scripts and patches and before
the common removelists, the product overlay and the product's own
``conf.d``. So this conf script runs before the recipe's, and
``keel-redis``'s own ``conf.d/main`` checks what it did rather than trusting
it.

No Webmin module
----------------

Debian 13 packages ``webmin-mysql`` and ``webmin-postgresql`` and no
equivalent for Redis. An appliance built on this component gets the Webmin
panel ``core`` carries, with no Redis page in it, and its boot test checks
that the panel answers rather than pretending a module exists.

What is deliberately not here
-----------------------------

The upstream ``redis`` appliance also ships Redis Commander on nginx and
pm2, a landing page, ``turnkey-redis-pw`` and a confconsole plugin that
writes the password to ``/root/redis_password.txt``. None of it is here.
Redis Commander is a web application and belongs with a web stack, the same
argument that keeps Adminer out of ``unit-mariadb``; and a tool whose job is
to print the Redis password out of a configuration file has nothing to print
once the configuration holds a digest.

Also not here: ``redis-sentinel``, which Debian packages beside the server,
and Redis Cluster, which needs no package at all. Both are modes, and modes
are decision 0013's later phases in their own issue.

Valkey
------

Debian 13 also ships ``valkey-server 8.1.1``, the fork made after Redis
changed its licence. Everything this component does is Valkey's too: Valkey
8.1 keeps the ACL vocabulary, the ``include`` semantics, the ``bind`` syntax
and the ``INFO`` sections, so serving both would be a choice of package name
and of the four paths and one service name this component already reads from
its environment, not a second recipe. What it is not is a drop in rename:
the paths differ (``/etc/valkey/valkey.conf``, ``valkey-server.service``,
``valkey-cli``), so the honest shape is one variable naming the flavour,
and that is a change with its own issue rather than a line smuggled in here.

Tests
-----

``tests/coverage.sh`` runs the bats suite under kcov and fails below
``COVERAGE_THRESHOLD``. COVERAGE.md records what is measured and what is
not. The acceptance test of a component is the layer that consumes it:
``keel-redis`` builds it, boots it in LXC and proves the declared secret
reaches the server, which is why this repository carries no boot test of its
own.