Bitcoin Core clearbanned RPC: Network Ban Reset Guide

This guide explains Bitcoin Core clearbanned RPC in plain English. It shows what the command does, what its result means and what it cannot prove.

All-entry scope

The historical call has no filter and removes all banned IPs. Use setban remove for a deliberate single-entry change where supported rather than reaching for a global reset. A wrapper should display the count and broad effect before execution and should not pretend a subnet, reason or expiry argument can constrain clearbanned.

Evidence before reset

Record only the operationally necessary ban-list summary, creation time, expiry distribution and incident reference before clearing. Avoid publishing private IPs or sensitive topology. If a software bug, clock error or attack caused the list, preserve logs and version details so the condition can be reproduced without keeping production connectivity impaired.

Connectivity consequences

Clearing bans permits endpoints to attempt reconnection; it does not actively connect every peer or remove firewall rules. Observe inbound and outbound counts, handshake failures, service bits, chainwork and resource use. Separate improvement caused by expired bans from unrelated DNS, routing, proxy, port or peer-selection failures.

Security trade-off

An attacker that triggered bans may return immediately after reset. Apply rate, firewall and topology controls appropriate to the incident and ensure automatic ban behaviour remains functional. Do not replace a repeatedly growing ban list with scheduled clearing, because that hides the signal and weakens an intended defensive boundary.

RPC access control

Network-ban mutation should be unavailable to public dashboards and ordinary monitoring accounts. Keep RPC on a protected interface, use strong authentication and allow the operation only through an audited incident procedure. Log actor, node, reason and verification outcome, never credentials or full sensitive peer lists.

Selective restoration plan

If the prior list contained known malicious ranges alongside one mistaken entry, capture enough information to recreate justified bans after the reset or use selective removal instead. Reapplying entries must be reviewed and bounded; importing a stale list wholesale can recreate the original outage or block reassigned addresses.

How specialists test it

Operators test the command on a non-production node first. They check a normal reply, an invalid request, a timeout and a restart. This shows what the response means and prevents one local result from being mistaken for a network-wide outcome.

Conclusion

clearbanned is a global ban-list reset, useful only when its broad effect is intentional. A safe incident response preserves evidence, prefers selective repair and watches for the same abusive peers returning after access is reopened.