Key Highlights:
- BTCPay Server administrators must manually add the Tor fragment after updating to version 2.4.5 to maintain onion routing services.
- Version 2.4.5 introduces a security-focused breaking change that blocks outbound HTTP traffic to private networks by default to mitigate SSRF vulnerabilities.
- Operators relying on private-network endpoints for Lightning, LNURL, webhooks, or invoice notifications must explicitly whitelist them using SSRF exceptions.
The developers of the open-source payment processor BTCPay Server are advising server administrators to carefully review significant deployment adjustments before applying the update to version 2.4.5. The latest release introduces major updates regarding Tor hidden service deployments and imposes default restrictions on outbound network traffic, requiring administrative action to prevent service interruptions across merchant nodes.
Tor Deployment Shifts to an Optional Fragment
While Tor remains fully supported across BTCPay deployments, administrators updating to version 2.4.5 must take direct steps to retain or restore onion-routing capabilities. According to the release guidance, the specific instruction for enabling Tor after updating to version 2.4.5 is:
sudo btcpay-fragments add opt-add-torBTCPay reassures node runners that all existing data remains stored within current Tor volumes during this process. While this ensures that no historical data is destroyed, uninterrupted onion network access requires that the Tor service is actively included and running in the updated deployment structure. As detailed in the official BTCPay Server documentation, the optional opt-add-tor fragment operates by adding hidden services and enabling selected onion connectivity across the system.
Managing Fragments and Server Configurations
Administrators wishing to verify their deployment parameters can evaluate their configuration state directly from the command line. Operators can inspect their current environment by running btcpay-fragments show. This diagnostic command does not alter any existing system settings; instead, it outputs saved additional and excluded fragments alongside the effective fragments derived from the last generated manifest.
Because modifying the deployment architecture impacts operational services, any fragment-changing commands require root privileges and immediately trigger the reapplication of the server setup.
SSRF Security Measures Restrict Outbound Private Requests
In addition to Tor configuration changes, the version 2.4.5 release notes highlight a critical breaking change concerning outbound HTTP requests. To proactively guard against Server-Side Request Forgery (SSRF) attacks, the payment engine now blocks outbound destinations directed toward private networks by default. This restriction directly applies to outbound traffic tied to Lightning Network connections, LNURL requests, invoice notification URLs, and merchant webhooks.
For operations that legitimately rely on internal network communications or private microservices, operators must explicitly register permitted destinations via ssrfexceptions. BTCPay’s operator documentation states that once these security exception settings are configured, administrators must restart the application and thoroughly exercise the affected integration to ensure payments and outbound notifications proceed as expected.
Why This Matters
Securing cryptocurrency infrastructure against SSRF vulnerabilities is critical for self-hosted payment gateways, where malicious actors might otherwise attempt to exploit internal APIs or expose sensitive services hosted on private subnets. At the same time, shifting components such as Tor into explicit fragments streamlines the core architecture for operators who run BTCPay entirely over standard internet routing. For enterprises, merchants, and node operators, these structural refinements enhance baseline server hardening, but they mandate administrative intervention during upgrades to prevent sudden disconnections in Lightning operations, automated webhook handlers, and private onion routing.
Frequently Asked Questions
Will updating to BTCPay Server 2.4.5 erase my existing Tor data?
No. BTCPay has confirmed that existing data stays intact within the current Tor volumes. However, to maintain functional onion routing and hidden services, administrators must manually add the opt-add-tor fragment and run the service after updating.
Why are my internal webhooks or Lightning connections failing after the 2.4.5 update?
Version 2.4.5 blocks outbound HTTP requests to private networks by default to prevent SSRF vulnerabilities. If your integrations, Lightning nodes, LNURL services, or webhooks use private IP ranges or internal hostnames, you must define them under ssrfexceptions and restart the application.
How can I view my active configuration fragments without modifying the server?
You can execute the btcpay-fragments show command. This command provides a report of both additional and excluded fragments, as well as the active manifest, without making any modifications to your setup.
