Updated

Mining pools are where your hashrate becomes revenue, so your pool settings need to be correct on every miner and protected from changes you didn't make. Foreman lets you change pools across your whole fleet at once, require approval for pool changes, and automatically reverse any change that doesn't match your approved pools.

What You'll Accomplish

By the end of this module, you will have:

  1. Pushed your pool configuration to your miners in bulk
  2. Set up trusted pools so Foreman flags any miner pointed somewhere it shouldn't be
  3. Created an auto-correct trigger that puts miners back on your pools and alerts your team
  4. Connected pool reporting so you can check your pool's numbers against what your miners report

Pool Basics

Each miner holds up to three pools. It mines to Pool 1, falls back to Pool 2 if Pool 1 is unreachable, and then to Pool 3.

Each pool has three fields:

  • URL: the pool's stratum address and port, for example stratum+tcp://btc.foundryusapool.com:3333. Use the address and port from your pool's documentation.
  • Username (worker name): your pool account or wallet address, a dot, then a worker suffix, for example youraccount.rack05-miner12
  • Password: often just x, unless your pool says otherwise

Plan Your Failover

  • Pool 1: your main pool
  • Pool 2: ideally a different provider, so one provider's outage doesn't stop all your mining
  • Pool 3: another endpoint or region for extra coverage

Plan Your Worker Names

Instead of typing a worker name for each miner, use a variable that Foreman fills in per miner. The safest choices are based on the miner's hardware, because they don't change:

  • ${miner.mac:clean}: MAC address without colons
  • ${miner.serial}: miner serial number

Example: youraccount.${miner.mac:clean}. Avoid IP-based worker names, since they change whenever a miner's IP changes.

Step 1: Change Pools on Your Miners

For many miners at once:

  1. Go to Miners in the left-hand menu.
  2. Click Bulk Edit Miners.
  3. Check the box next to each miner you want to change, or use filters to narrow the list first.
  4. Click Edit (#) to open the modal and choose Change Pools.
  5. Enter the URL, username, and password for Pools 1–3, then apply.

Onboarding: Bulk Edit Miners

Onboarding: Select miners and click Edit

For a single miner: open the miner from the Miners page and use its remote commands to change pool settings.

Before a fleet-wide change:

  • Test on 5–10 miners first and confirm they show up on your pool's dashboard.
  • For large fleets, roll out in batches and watch hashrate as you go.
  • Expect each changed miner to show as rebooted, with its uptime reset. A pool change resets the share counter Foreman uses to detect reboots.

Step 2: Require Approval for Pool Changes

Pool change approval makes bulk pool changes made in Foreman wait for a second person to approve them. This protects you if someone gets into a Foreman account or API key.

  1. Open Settings from the user menu in the top-right corner.
  2. In the Mining Pools section, turn on Pool Change Approval.
  3. Turn on emails for pool change requests. Users with the Mining Pool Manager permission are notified.
  4. Set the number of approvals required, then save.

Onboarding: Mining Pools settings

Step 3: Set Up Trusted Pools

Trusted pools tell Foreman which pool URL and worker name combinations are allowed. On every stats update, Foreman checks each of a miner's three pools. If any pool doesn't match at least one trusted pool, the miner is flagged with Invalid Pools Configured. This works no matter how the change was made, including by another tool outside Foreman.

Choose Where to Enforce

Trusted pools are set on a dashboard and apply to the miners under it:

  • Parent dashboard: everything in your organization
  • Site dashboard: one physical location
  • Client dashboard: one customer, which hosting providers use to give each customer their own allowed pools

Add a Trusted Pool

  1. Open Settings > Mining Pools on the dashboard you chose. Under Trusted Pool Configurations, click Add Config.
  2. Match Type:
    • Exact is the safest choice. An Insert Variables button lets you build worker names from miner details, such as ${miner.mac:clean}.
    • Regular Expression is for worker names that follow a pattern.
  3. Miner Types (optional): leave this blank to apply to all miners, or pick models that mine to a different pool.
  4. Stratum Expression: the pool host and port, without stratum+tcp://.
  5. Worker Expression: the worker name or pattern. It must include your wallet address or account name, not just the part after the dot.
  6. Click Add Config again for every pool you use, including your fallback pools, then click Save.

Onboarding: Add a trusted pool

Examples

Setup Match Type Stratum Expression Worker Expression
One wallet, MAC-based workers Exact mine.ocean.xyz:3334 bc1qYOURWALLET.${miner.mac:clean}
Account-based pool, any worker suffix Regular Expression btc\.global\.luxor\.tech:700 youraccount\..*
One pool, several ports Regular Expression btc\.foundryusapool\.com:(3333|443|25) youraccount\..*

Avoid These Mistakes

  • A worker pattern that matches anything. .* or a blank entry accepts every worker, including an attacker's wallet.
  • Unescaped dots in a regular expression. Write mine\.ocean\.xyz, not mine.ocean.xyz.
  • Forgetting fallback pools. If Pools 2 and 3 aren't trusted, every miner gets flagged.

After saving, check your Miners list. Any miner showing Invalid Pools Configured doesn't match a trusted pool. Fix those miners or adjust your pattern before moving on. Matching miners clear in about five minutes.

Step 4: Create the Auto-Correct Trigger

One trigger can both fix the pools and tell your team.

  1. Go to Alerts & Triggers and click Add Trigger.
  2. Miners to Check: the miners that share these pool settings, such as a site or client. Leave the first box on Any. A Count Of and A Percentage Of only allow Send Alert.
  3. What to Check For: Trips a(n) Invalid Pools Configured. Lower the interval count to 1–5 so you lose as little hashrate as possible. The default is 10.
  4. What to Do: select both Change Pools and Send Alert.
    • Fill in the URL, username, and password for all three pools. All three are required.
    • Type your wallet or account name in full in each username, and use the same worker variable as your trusted pool, for example youraccount.${miner.mac:clean}.
    • Don't use ${miner.account} or ${miner.worker} here. Those copy the pool settings last seen on the miner, which after an attack would be the attacker's wallet.
  5. Choose alert destinations and click Add Trigger.

Onboarding: Invalid Pools Configured condition

Onboarding: Change Pools and Send Alert actions

Test it: change the pool on one miner by hand. After the next stats update and the trigger's interval, you should see the Invalid Pools Configured flag, the correction in the audit log, and the alert.

To also catch miners with no pools at all, see How To: Add A Pool Configuration Management Trigger.

What to Know Before Relying on It

  • It reverses changes. It doesn't block them. Expect a few minutes of lost hashrate per incident.
  • Repeated changes will bounce. If another tool keeps pushing bad settings, remove or disconnect that tool.
  • Dispatches pause the fix. Change Pools is skipped during an active demand response dispatch. You'll still get the alert.
  • Foreman needs access to the miner. If the miner's login or firmware has been changed, the fix can't be pushed, but you'll still be alerted.

Full walkthrough: Quick Guide: Protecting Your Miners from Unauthorized Pool Changes

Step 5: Monitor Pool Performance

In Foreman

  • Dashboard: pool connection status and share acceptance across your fleet
  • Miner details: the Share Dist graph shows pool statistics for a single miner
  • Stale and rejected shares: a small amount is normal, around 0.5% or lower. A spike usually points to network latency between your site and the pool. Some pools report stale and rejected shares together.

Pool Reports

For supported pools (AntPool, BTC.com, Foundry USA, Luxor, Poolin, and ViaBTC), Foreman can email daily, weekly, or monthly reports with pool-side hashrate, earnings, and payouts. For FPPS pools, the report also checks the pool's payout rate against the network rate.

  1. Create an API key in your pool account.
  2. In Foreman, go to Settings > Mining Pools > Mining Pool API Keys, click Add Key, choose the pool, and enter the sub-account and key. Add one key per sub-account.
  3. Go to Reports, click Add Report, and enroll in that pool's report.

Pool-by-pool instructions: How To: Audit Pool Payouts

Best Practices

Security

  • Give pool-change permissions only to the people who need them (see Module 4: Managing User Permissions).
  • Turn on Require Two Factor in Company Settings, and remove users who no longer need access.
  • Limit the other tools that can write to your miners, and keep them on a segmented network.
  • Check the audit log regularly for pool changes you don't recognize.

Regular Reviews

  • Monthly: confirm no miners are flagged with Invalid Pools Configured, and review stale and rejected share rates.
  • Quarterly: review fees and failover pools, and update trusted pools and triggers to match.

Troubleshooting

Miners won't connect to the pool:

  • Check the URL and port for typos.
  • Make sure your firewall allows outbound connections on that port.

Worker doesn't appear on the pool's dashboard:

  • Check that the username format matches what your pool expects.
  • Give it 5–10 minutes. Some pools are slow to show new workers.

Miners show Invalid Pools Configured but the pools look right:

  • Check that the stratum and worker match your trusted pool exactly, including the port.
  • Check that your fallback pools are trusted too.
  • For regular expressions, check that dots are escaped and the pattern covers the whole worker name. You can test patterns at regexr.com.

You can't change pools:

  • Check that your role has pool-change permissions.
  • If Pool Change Approval is on, your change is waiting for approval from a Mining Pool Manager.

More help: Common Troubleshooting: Pools

Setup Checklist

☐ Choose primary and backup pools (different providers)

☐ Decide on a worker naming convention

☐ Test a pool change on 5–10 miners

☐ Roll out to your fleet with Bulk Edit

☐ Turn on Pool Change Approval

☐ Add trusted pools for every pool you use

☐ Clear any miners flagged Invalid Pools Configured

☐ Create and test the auto-correct trigger

☐ Connect Mining Pool API Keys and enroll in pool reports

What's Next?

You've completed Learning Path 2. Your site is mapped, routine issues fix themselves, and your pools are protected.

Next Article: Learning Path 3, Module 1: Power Controls – Control when and how your site uses power.

Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request

Can't find what you're looking for?

Our support team can help with setup, hardware and billing questions.

Contact Support