Skip to content

getting-started.md

Latest commit

 

History

History
134 lines (100 loc) · 5.96 KB

getting-started.md

File metadata and controls

134 lines (100 loc) · 5.96 KB
Raw

Getting Started

Install and tune an XMRig worker from a fresh machine. A single script, rigforge.sh, drives the whole process, and most of it is automated.

TL;DR

git clone https://github.com/p2pool-starter-stack/rigforge.git
cd rigforge
chmod +x rigforge.sh
sudo ./rigforge.sh

Answer one prompt (your pool URL), let it build, and on Linux reboot once to apply the kernel tuning. The xmrig service starts automatically after the reboot.

1. Prerequisites

Requirement Recommendation
Operating system Ubuntu Server 22.04+ (or Debian 12) is the officially supported target. macOS works for development and light use; other Linux distros are courtesy.
CPU 64-bit x86 with AVX2 is strongly recommended for RandomX performance. More and faster cores mean more hashrate.
RAM ~2.3 GB free for RandomX fast mode (a 2080 MB dataset + 256 MB cache), plus ~2 MB of L3 cache per mining thread. 4 GB+ recommended.
Privileges root. The script installs packages and tunes the kernel, so run it with sudo.
Network The worker must reach your pool / stack host on its Stratum port (Pithead uses 3333). Workers run on a trusted LAN and do not need Tor.

📐 Full sizing guidance, including minimum vs. recommended specs and the per-CPU tuning profiles, is in Hardware Requirements. The stack host these workers connect to is sized separately in Pithead's hardware guide.

You don't need to install build dependencies yourself. RigForge installs the toolchain (cmake, libuv, hwloc, …) for you on first run. You only need git to clone the repo.

2. Get the code

git clone https://github.com/p2pool-starter-stack/rigforge.git
cd rigforge
chmod +x rigforge.sh

Have your pool URL ready, a host:port. For a Pithead stack that's the stack machine's address and its proxy port 3333 (e.g. stack.lan:3333); with Pithead you do not need a wallet, since the stack handles payouts centrally.

Mining to a public pool (SupportXMR, etc.) instead of Pithead? Public pools pay you, so they expect your Monero wallet address as the login (and usually a TLS port). The first-run prompt only asks for the pool URL, so afterwards set pools[].user to your wallet (and tls) and run sudo ./rigforge.sh apply. There's a copy-paste example in Configuration › Connecting to a public pool. Otherwise your hashes credit the rig's hostname instead of you.

3. Run setup

sudo ./rigforge.sh

setup is the default command and is safe to re-run. On a fresh machine it walks through:

  1. Dependencies. Installs the build toolchain and runtime libraries for your OS.
  2. First-run config. If there's no config.json, it asks for the one thing it needs, your pool URL, and writes a minimal config. (You can also pre-create one; see Configuration.)
  3. Build. Clones and compiles XMRig from source, pinned to a known version/commit and patched to your DONATION level. Build output is captured to a logfile.
  4. Hardware tuning. Detects your CPU and writes a matching XMRig config (NUMA, ASM, thread layout, MSR). See How It Works.
  5. Kernel tuning (Linux only). Configures HugePages (1 GB and 2 MB), MSR access, hugetlbfs mounts, and memlock limits. The GRUB change requires a reboot.
  6. Service. Installs and enables the xmrig systemd service with a cpupower performance governor and log rotation.

Re-running setup is idempotent: it skips the (slow) recompile when the pinned XMRig is already built, and it won't duplicate the kernel/limits edits. Later on, to apply a config.json edit use apply; to rebuild only when the pinned version changed, use upgrade.

Optional: a rigforge command on your PATH. Set "add_to_path": true in config.json and setup installs a rigforge symlink in /usr/local/bin, so you can run it from any directory (sudo rigforge doctor, sudo rigforge tune, …) instead of ./rigforge.sh. It's off by default, so this guide uses ./rigforge.sh throughout. (uninstall removes the symlink.)

4. Reboot (Linux only)

To apply HugePages and the other kernel tuning, a reboot is required on Linux. The script tells you when:

sudo reboot

After the reboot the xmrig service starts automatically. (macOS needs no reboot.)

5. Verify it's mining

sudo systemctl status xmrig      # service should be active (running)
sudo journalctl -u xmrig -f      # live logs — watch for accepted shares

Confirm the optimizations applied:

sudo ./rigforge.sh doctor                       # the one-stop health check (HugePages, MSR, governor, …)
grep Huge /proc/meminfo                         # HugePages_Total should be non-zero
grep -i msr data/worker/xmrig.log               # MSR mod applied (no errors)

<WORKER_ROOT> is data/worker inside the repo by default. If you see MSR errors, you may need to disable Secure Boot in your BIOS/UEFI; see Operations › Troubleshooting.

On macOS the steps above (the systemd service and the HugePages/MSR checks) don't apply: there's no service and no kernel tuning. Start the miner yourself with ./rigforge.sh start (then status / logs / stop); see Operations › Running on macOS.

Next steps