satoshi/KamadoPool-StartOS-040
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Show domains in pool status

Browse Source
This commit is contained in:
satoshi
2026-08-18 02:53:40 +03:00
parent a1fa90c66a
commit eb5f4cbf5a
12 changed files with 517 additions and 141 deletions
Download Patch File Download Diff File Expand all files Collapse all files
instructions.md
+31 -29
View File
@@ -7,7 +7,7 @@ Kamado is a solo Bitcoin mining pool built on a patched fork of CKPool-solo, wit
- **A running solo pool**: stratum server (ckpool), middleware API, and web dashboard, supervised as separate daemons with individual health checks.
- **A real-time dashboard** with live hashrate, per-miner stats, hardware detection, block history, best-share leaderboards, and a transaction accelerator.
- **Direct LAN stratum access**: StartOS 0.4.0 exposes the stratum TCP port on your network — no router port-forward or proxy needed (this was a 0.3.x limitation).
- **Stratum TLS on both sides of the network**: a publicly trusted certificate for miners connecting over a clearnet domain, and a persisted self-signed certificate for miners on the LAN — on the same port, at the same time.
- **Stratum TLS on both sides of the network**: a Let's Encrypt certificate issued by StartOS for miners connecting over a clearnet domain, and a persisted self-signed certificate for miners on the LAN — each on its own port, both alongside the plaintext endpoint.
## Setup
@@ -30,47 +30,44 @@ stratum+tcp://<your-server-lan-address>:<stratum-port>
### Stratum over TLS
Kamado exposes two stratum interfaces — **Stratum** (plaintext) and **Stratum (TLS)** — and each is reachable both on your local network and, if you attach a domain, over the internet. That gives four working combinations:
Kamado offers two separate TLS endpoints, because they are secured in different ways:
| Path | Endpoint | Certificate | Setup needed |
| ---- | -------- | ----------- | ------------ |
| Plaintext, local network | `stratum+tcp://<lan-address>:3333` | — | none |
| Plaintext, public domain | `stratum+tcp://<your-domain>:3333` | — | attach a domain to **Stratum** |
| TLS, local network | `stratum+ssl://<lan-address>:3334` | self-signed | enable **Stratum TLS (Local Network)** |
| TLS, public domain | `stratum+ssl://<your-domain>:3334` | Let's Encrypt | attach a domain to **Stratum (TLS)** |
**Over the internet — Stratum (TLS, Public Domain).** Attach a domain to this interface in the StartOS UI and choose Let's Encrypt. StartOS obtains and renews the certificate and terminates TLS itself, so miners validate it against their normal root store with nothing pasted in. See *Reaching the pool from the internet* below — attaching the domain is not quite the whole setup.
The dashboard shows a padlock next to every encrypted miner; hover it to see which of the two certificates that miner is actually using.
#### TLS over a public domain (no certificate setup)
Add a clearnet domain to the **Stratum (TLS)** interface in the StartOS interface list. StartOS obtains a Let's Encrypt certificate for it and Kamado starts serving it automatically — there is nothing to enable in *Configure* and nothing to paste into your miners. Any miner whose firmware ships a normal CA root store validates it the same way a browser validates a website.
Certificates renew automatically. Kamado picks up each renewal on its own, which briefly restarts the stratum listener — connected miners reconnect within seconds.
#### TLS on the local network (self-signed)
A Let's Encrypt certificate is only ever valid for the domain name it was issued for, so a miner pointed at a bare LAN IP cannot validate it. For those miners, enable **Stratum TLS (Local Network)** in *Configure*. Kamado generates a self-signed certificate once and persists it, so pinned fingerprints survive restarts and updates.
Run the **Stratum TLS Certificate** action to get:
**On your local network — Stratum (TLS, Local Network).** Enable **Stratum TLS (Local Network)** in *Configure* to serve a self-signed certificate on its own port. Public certificate authorities cannot sign a bare LAN IP or a `.local` name, so this path stays self-signed and miners must be told to trust it. Run the **Stratum TLS Certificate** action to get:
- the **SHA-256 fingerprint** for firmwares that pin fingerprints, and
- the **full PEM** to paste into firmwares that accept a custom root (AxeOS exposes a *Stratum SSL Cert* field for exactly this).
Otherwise connect with `stratum+ssl://` and certificate verification disabled. Use the **Regenerate TLS Certificate** action to rotate the certificate; miners that pin it will need the new fingerprint.
Otherwise connect with `stratum+ssl://` and certificate verification disabled. Use the **Regenerate TLS Certificate** action to rotate it; miners that pin it will need the new fingerprint.
#### How the two share one port
Both TLS endpoints and the plaintext one run at the same time on their own ports, and the dashboard's padlock names which certificate each miner arrived on when you hover it.
Both certificates are served on the same TLS port, selected per connection by the hostname the miner asks for (SNI). A miner that connects by domain name gets the Let's Encrypt certificate for that name; a miner that connects to a bare IP sends no hostname and gets the self-signed one. You do not have to choose, and you do not need a second port.
### Reaching the pool from the internet
If you would rather have your LAN miners use the publicly trusted certificate too, point your local DNS (router, Pi-hole, AdGuard) at the server's LAN address for your domain and connect them by domain name. They then validate against Let's Encrypt while their traffic stays on the LAN — and you can leave **Stratum TLS (Local Network)** off entirely.
Miners outside your network use the **Stratum (TLS, Public Domain)** interface:
1. **Attach a domain** to that interface and choose Let's Encrypt. Point its DNS at whatever address the internet reaches your server on.
2. **Point miners at the domain and its port.** A domain is published on the port set in *Configure* (Preferred Stratum TLS Port (Public Domain)), which can differ from the port shown for IP-based access on the same interface. The **Pool Status** action lists every endpoint and every attached domain with the port it is published on.
```text
stratum+ssl://<your-domain>:<public-tls-port>
```
Set the miner to use its **system/built-in certificates** — a Let's Encrypt chain validates against any normal root store with nothing pasted in.
Two things worth knowing if a certificate never appears:
- **Issuance validates on port 443 of your domain**, using the TLS-ALPN-01 challenge, regardless of which port the pool itself runs on. If your server isn't reachable on 443 for that name, issuance fails and StartOS falls back to a self-signed certificate that public clients reject.
- **A hostname that has failed validation repeatedly gets rate-limited** by Let's Encrypt (5 failures per hostname per hour), and StartOS retries roughly every minute — so a name that failed early can stay stuck long after the original cause is fixed. Check `start-cli server logs | grep -i acme`; if you see `ACME order failed` looping, remove the domain to stop the retries, wait for the hour to clear, then re-add it. Using a fresh hostname sidesteps it entirely.
## Configuration
Everything lives in the **Configure** action: the stratum and stratum-TLS ports, vardiff (starting/min/max difficulty), idle-client disconnect, the coinbase tag embedded in solved blocks, ZMQ, local-network TLS, log level, and an optional self-hosted mempool explorer URL for dashboard links.
Everything lives in the **Configure** action: the three stratum ports (plaintext, local-network TLS, public-domain TLS), vardiff (starting/min/max difficulty), idle-client disconnect, the coinbase tag embedded in solved blocks, ZMQ, local-network TLS, log level, and an optional self-hosted mempool explorer URL for dashboard links.
TLS over a public domain is deliberately *not* a config option — it follows whatever domains you attach to the **Stratum (TLS)** interface, so there is no second copy of that setting to drift out of sync with what the OS actually has.
Which domain is used for public TLS is deliberately *not* a config option — it follows whatever you attach to the **Stratum (TLS, Public Domain)** interface, so there is no second copy of that setting to drift out of sync with what the OS actually has. Only its port lives in *Configure*.
Changing a port rebinds the interface without restarting the pool, so miners already connected on other ports keep hashing — but anything pointed at the old port must be updated. Setting both stratum ports to the same number is rejected when you save.
Changing a port rebinds the interface without restarting the pool, so miners already connected on other ports keep hashing — but anything pointed at the old port must be updated. Setting any two of the three ports to the same number is rejected when you save.
## Actions
@@ -85,8 +82,13 @@ Changing a port rebinds the interface without restarting the pool, so miners alr
- **Bitcoin Core RPC errors**: make sure Bitcoin Core is running and fully synced; Kamado's *Bitcoin Core RPC* health check shows the current state.
- **Best share resets to 0 after a block is found**: upstream CKPool zeroes the "current round" best diff on solve. Kamado ships a patch that also exposes the all-time best, so the dashboard has both columns.
- **Miner rejects the TLS certificate**: re-check that the PEM was pasted completely (including the BEGIN/END lines), or pin the SHA-256 fingerprint, or disable verification in the miner.
- **A miner set to system certificates rejects the public-domain endpoint** (`No matching trusted root certificate found`, mbedTLS `-0x2700`/`-0x3000`): StartOS is serving its own self-signed certificate because Let's Encrypt never issued one. Check `start-cli server logs | grep -i acme` for `ACME order failed`, and confirm your server is reachable on **port 443** for that domain — that is where the TLS-ALPN-01 challenge is performed, whatever port the pool runs on. A hostname that failed repeatedly may also be rate-limited; see *Reaching the pool from the internet* above. Verify what is actually served with:
```sh
openssl s_client -connect <domain>:<port> -servername <domain> </dev/null 2>/dev/null | openssl x509 -noout -issuer
```
- **Miner rejects the certificate on a public domain**: make sure it is connecting by the domain name, not by IP — the certificate is only valid for the name. If it is using the name and still fails, the firmware's CA root store may not include Let's Encrypt's ISRG Root X1; pin the certificate or use the plaintext endpoint for that miner.
- **The public domain's certificate is not being served**: it takes a few minutes after adding a domain for StartOS to complete the ACME challenge. Until it does, Kamado logs `no certificate available for <domain> yet — skipping` and keeps serving the other paths. Check that the domain's DNS points at your server and that the port is reachable from the internet.
- **The public domain's certificate is not being served**: it takes a few minutes after adding a domain for StartOS to complete the ACME challenge, and the certificate is the OS's to issue — check the domain on the **Stratum (TLS, Public Domain)** interface, that its DNS points at your server, and that the port is reachable from the internet. The other endpoints keep serving meanwhile.
## Upstream