94 lines
8.1 KiB
Markdown
94 lines
8.1 KiB
Markdown
# Kamado Pool
|
|
|
|
Kamado is a solo Bitcoin mining pool built on a patched fork of CKPool-solo, with a Go middleware API and a real-time Svelte dashboard. When a miner connected to your Kamado instance solves a block, **the full block reward goes to the payout address that miner connected with** — no pool fees, no splits, no share accounting.
|
|
|
|
## What you get on StartOS
|
|
|
|
- **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.
|
|
|
|
## Setup
|
|
|
|
1. Install and start **Bitcoin Core**. Kamado requires it running and synced; mining on an unsynced node produces invalid work.
|
|
2. Accept the suggested task to enable **ZMQ** on Bitcoin Core (recommended — it gives sub-second new-block detection; without it Kamado falls back to RPC polling).
|
|
3. Start Kamado Pool and open the **Web Dashboard** from the interface list.
|
|
|
|
There is no payout address to configure. CKPool-solo pays the full block reward directly to whichever Bitcoin address the miner connects with as its stratum username — see **Connecting miners** below. Kamado validates worker usernames against Bitcoin Core and **refuses to authenticate any worker whose username is not a valid address on the active network**, so misconfigured miners fail loudly instead of silently mining to the wrong place.
|
|
|
|
## Connecting miners
|
|
|
|
The stratum port defaults to **3333** and can be changed in the *Configure* action — that setting is the network port your miners connect to. Check the **Stratum** interface after saving to see the port actually in use, since the OS assigns a different one if your choice is already claimed by another service. Point each miner at:
|
|
|
|
```text
|
|
stratum+tcp://<your-server-lan-address>:<stratum-port>
|
|
```
|
|
|
|
- **Username**: the Bitcoin address that should receive the block reward, optionally followed by `.workername` for labelling in the dashboard (e.g. `bc1q....myBitaxe`).
|
|
- **Password**: ignored — anything works.
|
|
|
|
### 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:
|
|
|
|
| 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)** |
|
|
|
|
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:
|
|
|
|
- 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.
|
|
|
|
#### How the two share one port
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
## 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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
## Actions
|
|
|
|
- **Pool Status** — full text snapshot: Bitcoin Core sync, ckpool health, miners, hashrate, found blocks, submit-gap diagnostics.
|
|
- **Stratum TLS Certificate** — fingerprint + PEM for miner setup.
|
|
- **Regenerate TLS Certificate** — clears the cert; a fresh one is generated on next start.
|
|
- **Reset Block Latency** — zeroes the block-update latency counters after tuning.
|
|
|
|
## Troubleshooting
|
|
|
|
- **No miners appear after connecting**: check the Stratum interface for the right port, and confirm the miner reaches it (`telnet <server> <port>`). Check the Kamado logs.
|
|
- **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.
|
|
- **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.
|
|
|
|
## Upstream
|
|
|
|
CKPool-solo by Con Kolivas: <https://bitbucket.org/ckolivas/ckpool>
|