Operators running the popular open-source Bitcoin payment processor BTCPay Server through standard Docker deployments must explicitly select Tor during their next setup or update cycle if they wish to retain onion network access. The architectural change, introduced alongside version 2.4.5, effectively removes Tor from the suite of automatically included components, transforming what was previously a bundled service into a deliberate configuration choice for system administrators.
The development team detailed the deployment modification in an official announcement published on Oct. 5, accompanying the release of BTCPay Server version 2.4.5. The official GitHub release records the software milestone on Oct. 6. For existing production environments and test setups alike, the transition is triggered the moment an administrator initiates their next Docker setup routine or software update.
This adjustment carries significant implications for Docker-based operators who depend on Tor for enhanced privacy and censorship resistance, including seamless access through their server’s dedicated onion address. In previous iterations of the software stack, these capabilities were provisioned automatically as part of the core BTCPay Server fragment. Within the architecture of the platform, fragments function as modular configuration components utilized by administrators to assemble and customize their local Docker container stacks.
To help mitigate potential disruptions, BTCPay has strongly advised system administrators to carefully review all deployment changes prior to executing updates. For operators who rely on onion routing and wish to maintain their existing workflows after upgrading to version 2.4.5, the software requires the manual application of the specific command sudo btcpay-fragments add opt-add-tor to re-enable the functionality.
Despite the shift from automatic inclusion to manual opt-in, the underlying Tor infrastructure remains fully supported by the project. BTCPay has clarified that existing Tor data will be preserved within current Tor volumes during the transition. While this ensures that stored cryptographic and network data remains intact, administrators must understand that uninterrupted onion access is no longer guaranteed by default and strictly depends on explicitly including and running the Tor fragment within their deployment manifest.
Documentation maintained by the BTCPay Server project describes the optional Tor fragment, designated as opt-add-tor, as a modular addition that introduces hidden services and selected onion connectivity to the server environment. Operators seeking to verify their current system setup can inspect their active configurations using the command btcpay-fragments show. This diagnostic tool operates safely without altering the underlying configuration, generating a report that displays saved additional and excluded fragments alongside the effective fragments derived from the most recently generated deployment manifest.
Administrators should note that commands altering configuration fragments require root privileges on the host machine and trigger an immediate reapplication of the Docker setup routine. This ensures that changes take effect immediately, but it also underscores the importance of careful pre-update planning for production nodes handling live merchant payments.
Private Services Need Separate Exceptions
Alongside the changes to Tor deployment, the release notes for version 2.4.5 highlight another critical security adjustment affecting outbound HTTP requests across the platform. Private-network destinations are now blocked by default for a variety of core operations, including Lightning network connections, Lightning Network Uniform Resource Locator (LNURL) requests, invoice notification URLs, and automated webhooks.
This strict network restriction is designed to mitigate the risks associated with server-side request forgery, commonly referred to as SSRF, a vulnerability class that allows external entities to trick a server into making unintended requests to internal or private network resources. While this security enhancement hardens the default posture of newly deployed and updated servers, it introduces a breaking change for advanced users who rely on local or private-network routing for their payment infrastructure.
With the new protection enabled out of the box, operators who intentionally utilize private services or internal network endpoints must explicitly allow the necessary destinations through the ssrfexceptions configuration parameter. According to guidance outlined in the official BTCPay operator manual, administrators modifying these exceptions must subsequently restart the application and actively test the affected integrations to ensure uninterrupted transaction processing and communication flow.
