New advanced.block-broadcast-fallback union:
* enabled (default: false)
* grace-seconds (default: 30, range 10-600)
* backup-rpcs: list of full bitcoind RPC URLs, with inline
credentials supported (https://user:pass@host:port/). Up to 10.
docker_entrypoint reads the list with yq, joins with newlines, and
exports BACKUP_RPC_URLS plus PENDING_BLOCKS_DIR=<logdir>/pending-blocks
and PENDING_BLOCKS_GRACE so kamado-api's blocksubmit watcher activates.
If the user enables the fallback but provides no URLs, we log a
warning and disable rather than spam pending-block warnings.
The companion ckpool patch (KamadoPool repo, 0004-dump-pending-block-
for-fallback) writes raw block hex to PENDING_BLOCKS_DIR before each
submit attempt and unlinks on success. The watcher only fires if
ckpool's primary submit fails AND the operator configured backup RPCs.
Two related polish items:
1. Optional custom block explorer. New union under Advanced config
("Block Explorer") defaulting to "mempool.space". Picking
"Custom URL" reveals a single text field where the user can
point Kamado at their own mempool instance — useful for users
running mempool as a sibling StartOS service or on the same LAN.
The entrypoint reads .advanced.mempool-explorer.{type,url} and
exports MEMPOOL_BASE_URL when type=custom; otherwise leaves it
empty and the UI keeps its mempool.space defaults.
2. stunnel debug level 4 (warning) was hiding successful TLS
handshakes — only failures showed up in the service logs, which
made it hard to confirm "yes, my miner did connect over TLS"
without going looking at netstat. Bump to level 5 (notice) so
each successful handshake produces an "accepted connection from
<ip>" / "connected from <ip>" line. Errors stay visible at level
3, so the only thing this changes is making the happy path
observable.
ckpool exposes the serverurl[] index a client connected on as
client.server in its runtime JSON. By binding a second
loopback-only stratum socket and pointing stunnel at it, every TLS
miner arrives with server == 1 and the dashboard can render a
TLS pill cleanly — no source-IP heuristics.
Add TLS_INTERNAL_PORT=3437 to the entrypoint, render it into the
ckpool.conf.template's serverurl array (in the matching commit on
the KamadoPool repo), and update the stunnel config so TLS traffic
forwards to 127.0.0.1:${TLS_INTERNAL_PORT} instead of the public
plaintext port. Even when TLS is disabled the second bind is
harmless — nothing connects to it.
Miner firmware typically verifies the TLS server cert against the
hostname it was pointed at. Bitaxe (AxeOS) uses mbedtls and the
logs showed mbedtls_ssl_handshake returning -0x2700
(MBEDTLS_ERR_X509_CERT_VERIFY_FAILED) when connecting to
obese-admirer.local:3338 — our cert's SAN only had
kamado-pool.embassy / kamado-pool / localhost / 127.0.0.1, none of
which match an arbitrary mDNS host.
Add leftmost-label wildcards for the TLDs miners typically reach
the pool through:
*.local (mDNS / Bonjour, e.g. obese-admirer.local)
*.embassy (StartOS inter-service hostnames)
*.onion (Tor hidden services)
*.home.arpa (RFC 8375 home network namespace)
*.lan (common consumer router default)
*.internal (some corporate / LAN setups)
OpenSSL's own X509_check_host refuses these 2-label wildcards as a
public-suffix safeguard, but mbedtls accepts them (its wildcard
check is RFC 2818 verbatim — just requires *.X where X is any
non-empty label), so miners using mbedtls-based stacks (ESP-IDF,
most embedded firmwares) will now match.
Bump TLS_CERT_VERSION to 4 so existing installs self-regenerate.
The previous fix relied on inspecting the existing cert for a
subjectAltName extension to decide whether to regenerate. That
works but is brittle — it depends on openssl text output format
and on the assumption that SAN is the only thing that could go
wrong. If a future client rejects us for some *other* missing
extension, we'd be stuck on a bad cert again.
Switch to an explicit cert version marker (TLS_CERT_VERSION). Any
time we change the cert shape, we bump the version; the startup
check regenerates whenever the marker file is absent or out of
date. Upgrades self-heal on next boot with no introspection.
Write the full extension set via an openssl config file instead of
-addext flags. -addext is subtly different across openssl versions
(in some builds the extension lands in the CSR rather than the
cert). The config-file path is the documented, portable way to pin
basicConstraints, keyUsage, extendedKeyUsage, subjectKeyIdentifier,
and subjectAltName together.
Also log the resulting extensions at startup so operators can
verify cert sanity from the service logs without exec'ing into the
container, and pin a modern TLS floor in stunnel.conf (no SSL3,
no TLSv1, no TLSv1.1).
Old cert was /CN=kamado-pool-stratum with no SAN extension. Strict
TLS clients (Go, Rust, mbedtls, most modern miner firmwares) treat
missing SAN as a hard validation failure and send TLS alert 42
(bad_certificate), which is exactly what we saw in the stunnel
logs: "SSL_accept: ... error:0A000412: ... sslv3 alert bad
certificate".
Generate the cert with subjectAltName covering kamado-pool.embassy,
localhost, and 127.0.0.1, and an explicit
extendedKeyUsage=serverAuth. Swap the combined PEM so the cert
comes before the key (convention). Upgrades auto-heal: if an
existing cert lacks SAN, the entrypoint regenerates it on next
start — the fingerprint changes and the user needs to re-pin on
their miner, but the previous cert couldn't complete a handshake
anyway so there's nothing to lose.
Also make stunnel's intent explicit with verify=0 so anyone reading
the config knows we're doing opportunistic TLS, not client-cert
auth; miner auth is the stratum layer's job.
With BITCOIN_NOTIFY=true, ckpool's generator_getbest short-circuits
to GETBEST_NOTIFY (generator.c:902) and the blockupdate loop sleeps
5s doing nothing (stratifier.c:4695). It then expects ZMQ to push
new-tip events — but our ZMQ_BLOCK was empty and ckpool defaults to
tcp://127.0.0.1:28332 (ckpool.c:1795), which has nothing listening
inside this container. Net effect: ckpool was blind to tip changes,
so miners kept hashing the stale work until the next 30s
update_interval finally pulled a new template. Observed was a
16-second gap between bitcoind's UpdateTip log line and ckpool's
subsequent CreateNewBlock call — that's pure wasted hashrate.
Fix both paths:
- BITCOIN_NOTIFY=false so the blockpoll thread actually polls
getbestblockhash every BLOCKPOLL_MS (100ms).
- ZMQ_BLOCK=tcp://${BITCOIN_RPC_HOST}:28332 so the zmqnotify thread
subscribes to bitcoind's real hashblock publisher. Whichever path
sees the new tip first triggers update_base(); both are safe to
run concurrently.
- Drop the sed line that was stripping zmqblock from the rendered
conf — we now want it in there.
The default LOGDIR and DB_PATH both pointed at ephemeral container
paths, so a service restart wiped the pool's users/workers state,
its block history, and kamado-api's hashrate chart.
- LOGDIR: /var/log/ckpool -> /root/.ckpool/logs (ckpool volume).
Persists pool/pool.status, users/, workers/, and daily logs.
- DB_PATH: default /var/lib/kamado/kamado.db
-> /root/.kamado/data/kamado.db (main volume).
Persists blocks, hashrate_samples, and the kv table that holds
cumulative pool work.
CKPOOL_LOGFILE follows LOGDIR so kamado-api's log-tailer keeps
picking up ckpool's block-solve lines.
Entrypoint persists the generated TLS cert fingerprint so the
properties script can read it from the main volume. The screen
shows the active network, plaintext and TLS stratum ports, the
SHA-256 fingerprint for miner pinning, and the worker username
format (BTC address plus optional worker label).
ckpool-solo validates conf btcaddress once at startup to prime the
coinbase-builder, then pays solves to the worker's stratum address.
The conf value never sees a satoshi, so use the active network's
genesis coinbase address instead of a burn placeholder.
Worker stratum username is the payout address in ckpool-solo, so the
separate field was redundant. Niche vardiff/logging/zmq knobs now
live under an Advanced group with sensible defaults.
New 'tls' union config (disabled by default) spins up an
stunnel4 process inside the container that terminates TLS on
a configurable port (3334 by default) and forwards decrypted
stratum traffic to 127.0.0.1:${STRATUM_PORT}.
Cert is self-signed, generated once on first start with a
10-year validity and persisted at /root/.kamado/tls/ so the
fingerprint stays stable across restarts. SHA-256 fingerprint
is printed to container logs on each startup so users can
pin it on their miners. Miners must connect with
verification disabled (no CA trust chain for a private pool).
Runtime image grows by ~3MB for stunnel4 + openssl. The
supervisor loop now waits on three PIDs and tears all of them
down together if any one exits.
New 'zmq-enabled' boolean (default true) makes the entrypoint
export BITCOIN_ZMQ_BLOCK=tcp://<bitcoind-host>:28332, which
kamado-api's zmqmon subscribes to for sub-second chain refresh
on the dashboard. Disable it if your bitcoind doesn't have
zmqpubhashblock exposed.
Previous scaffold referenced a non-existent 'make ckpool-src'
target. Rewritten to inline the real build steps from the
upstream KamadoPool repo: clone ckpool at CKPOOL_COMMIT, apply
patches/*.patch, build with the same portable CFLAGS the
ckpool Dockerfile uses. The ui and api stages now match
api/Dockerfile exactly.
Entrypoint now uses the same env-var interface as the upstream
ckpool entrypoint (POOL_BTCADDRESS, BITCOIN_RPC_*, STRATUM_PORT,
etc.) and renders ckpool.conf from the bundled template via
sed. kamado-api env vars corrected to match config.FromEnv
(BITCOIN_RPC_URL, CKPOOL_SOCKDIR, CKPOOL_LOGFILE, LISTEN_ADDR).
Exposes stratum-port in the StartOS config UI so users running
simpleproxy or another TCP forwarder can point Kamado at a
non-default port. Entrypoint substitutes the value into
ckpool.conf serverurl.
Also pins placeholder KAMADO_SHA in the Dockerfile — swap to a
real pushed commit before the first build.
Multi-stage Dockerfile clones KamadoPool at a pinned SHA, builds
ckpool and kamado-api (with embedded Svelte UI), runtime image
supervises both processes via tini + wait -n. Config covers
bitcoind mainnet/testnet4 variant, payout address, coinbase tag,
vardiff knobs, and log level. Web UI interface only — stratum
:3333 requires a router port-forward or simpleproxy workaround
because StartOS 0.3.x does not forward raw TCP on LAN.
TODO before first build: pin KAMADO_REPO + KAMADO_SHA in the
Dockerfile to a pushed commit.
satoshi