Merge bitcoin/bitcoin#35037: ipc: support per-address max-connections options on -ipcbind
What changed, and why it matters
This change adds a per-listener connection limit for Bitcoin Core's local inter-process communication (IPC) socket option `-ipcbind`. Previously, IPC listeners had no enforced cap on simultaneous connections. The patch lets users specify `,max-connections=<n>` (default 16, maximum 256) and reserves matching file descriptors at startup. It is a hardening improvement rather than a fix for an active vulnerability, and it includes tests and release notes.
Treat as a routine hardening improvement. Reviewers should verify that `MAX_CONNECTIONS` plus listener count does not exceed the startup FD reservation on typical systems, and that URL decoding of socket paths does not introduce path-traversal issues when combined with custom `-ipcbind` paths.
Security signals we found
Adds resource-limiting controls to a local unauthenticated IPC listener
Enforces per-address max-connections with a hard upper bound
Reserves file descriptors at startup to avoid runtime exhaustion
Includes unit and functional tests covering boundary values and connection limiting behavior
No mention of a CVE, bug report, or external security disclosure
Evidence from the diff
The commit refactors -ipcbind parsing to strip inline options, adds ipc::ListenAddress and ipc::types.h, enforces DEFAULT_MAX_CONNECTIONS=16 and MAX_CONNECTIONS=256, validates per-address limits, caps aggregate IPC file-descriptor reservations, and passes the limit into the Cap’n Proto listener. It also URL-decodes Unix socket paths so commas in paths can be escaped. The change is defensive: it prevents unbounded IPC connection slots from competing with P2P/RPC FD budgets and limits resource exhaustion via the local IPC socket.
Changed components
src/init.cppsrc/interfaces/ipc.hsrc/ipc/capnp/protocol.cppsrc/ipc/interfaces.cppsrc/ipc/listen.cppsrc/ipc/protocol.hsrc/ipc/types.htest/functional/interface_ipc_init.pyInspect captured patch +391 / −17
### doc/release-notes-35037.md
@@ -0,0 +1,8 @@
+Updated settings
+----------------
+
+- IPC listeners configured with `-ipcbind` now reserve and accept
+ up to 16 client connections by default, with a maximum of 256. The limit can
+ be set per listener by appending `,max-connections=<n>` to the bind address,
+ for example `-ipcbind=unix:/path_to_socket_file.sock,max-connections=8`.
+ Unix socket paths in `-ipcbind` are now URL-decoded.
### src/CMakeLists.txt
@@ -120,6 +120,7 @@ add_library(bitcoin_common STATIC EXCLUDE_FROM_ALL
deploymentinfo.cpp
external_signer.cpp
init/common.cpp
+ ipc/listen.cpp
kernel/chainparams.cpp
key.cpp
key_io.cpp
### src/init.cpp
@@ -35,6 +35,7 @@
#include <interfaces/ipc.h>
#include <interfaces/node.h>
#include <ipc/exception.h>
+#include <ipc/types.h>
#include <kernel/blockmanager_opts.h>
#include <kernel/caches.h>
#include <kernel/chainstatemanager_opts.h>
@@ -750,7 +751,7 @@ void SetupServerArgs(ArgsManager& argsman, bool can_listen_ipc)
argsman.AddArg("-rpcworkqueue=<n>", strprintf("Set the maximum depth of the work queue to service RPC calls (default: %d)", DEFAULT_HTTP_WORKQUEUE), ArgsManager::ALLOW_ANY | ArgsManager::DEBUG_ONLY, OptionsCategory::RPC);
argsman.AddArg("-server", "Accept command line and JSON-RPC commands", ArgsManager::ALLOW_ANY, OptionsCategory::RPC);
if (can_listen_ipc) {
- argsman.AddArg("-ipcbind=<address>", "Bind to Unix socket address and listen for incoming connections. Valid address values are \"unix\" to listen on the default path, <datadir>/node.sock, or \"unix:/custom/path\" to specify a custom path. Can be specified multiple times to listen on multiple paths. Default behavior is not to listen on any path. If relative paths are specified, they are interpreted relative to the network data directory. If paths include any parent directory components and the parent directories do not exist, they will be created. Enabling this gives local processes that can access the socket unauthenticated RPC access, so it's important to choose a path with secure permissions if customizing this.", ArgsManager::ALLOW_ANY, OptionsCategory::IPC);
+ argsman.AddArg("-ipcbind=<address>", strprintf("Bind to Unix socket address and listen for incoming connections. Valid address values are \"unix\" to listen on the default path, <datadir>/node.sock, or \"unix:/custom/path\" to specify a custom path. Append \",max-connections=8\", for example \"unix:/custom/path,max-connections=8\", to limit the number of simultaneous connections on that address (default: %d, maximum: %d). Can be specified multiple times to listen on multiple paths. Default behavior is not to listen on any path. If relative paths are specified, they are interpreted relative to the network data directory. If paths include any parent directory components and the parent directories do not exist, they will be created. Enabling this gives local processes that can access the socket unauthenticated RPC access, so it's important to choose a path with secure permissions if customizing this.",ipc::DEFAULT_MAX_CONNECTIONS, ipc::MAX_CONNECTIONS), ArgsManager::ALLOW_ANY, OptionsCategory::IPC);
}
#if HAVE_DECL_FORK
@@ -1058,17 +1059,48 @@ bool AppInitParameterInteraction(const ArgsManager& args)
// Make sure enough file descriptors are available. We need to reserve enough FDs to account for the bare minimum,
// plus all manual connections and all bound interfaces. Any remainder will be available for connection sockets
+ // Keep IPC reservations low enough to leave room for core and P2P file descriptor reservations.
+ constexpr size_t MAX_IPC_FDS{ipc::MAX_CONNECTIONS + 1};
+
// Number of bound interfaces (we have at least one)
int num_p2p_bind = std::max(num_user_p2p_bind, size_t(1));
// Maximum number of connections with other nodes, this accounts for all types of outbounds and inbounds except for manual
int user_p2p_max_connections = args.GetIntArg("-maxconnections", DEFAULT_MAX_PEER_CONNECTIONS);
if (user_p2p_max_connections < 0) {
return InitError(Untranslated("-maxconnections must be greater or equal than zero"));
}
+
+ // Reserve one listening socket per -ipcbind address plus its accepted
+ // connection slots. Unlike P2P, IPC has no default listener.
+ size_t ipc_addresses{0};
+ size_t ipc_max_connections{0};
+ for (const std::string& configured_address : args.GetArgs("-ipcbind")) {
+ auto listen_address{interfaces::Ipc::parseListenAddress(configured_address)};
+ if (!listen_address) {
+ return InitError(Untranslated(strprintf("Invalid -ipcbind address '%s': %s", configured_address, util::ErrorString(listen_address).original)));
+ }
+ // Check the aggregate after adding this listener so multiple
+ // individually valid -ipcbind values cannot exceed the IPC FD cap.
+ ipc_addresses += 1;
+ ipc_max_connections += listen_address->max_connections;
+ }
+ // Actual number of IPC file descriptors to be reserved.
+ const size_t ipc_fds{ipc_max_connections + ipc_addresses};
+
+ if (ipc_fds > MAX_IPC_FDS) {
+ return InitError(Untranslated(strprintf("Too many IPC file descriptors requested: %d -ipcbind listeners and connection slots exceed the limit of %d. Reduce the number of -ipcbind addresses or their max-connections values", static_cast<int>(ipc_fds), static_cast<int>(MAX_IPC_FDS))));
+ }
+
+ if (ipc_addresses > 0) {
+ LogInfo("Reserving %d file descriptors for IPC (%d listening sockets, %d connection slots)",
+ static_cast<int>(ipc_fds),
+ static_cast<int>(ipc_addresses),
+ static_cast<int>(ipc_max_connections));
+ }
+
const size_t max_private{args.GetBoolArg("-privatebroadcast", DEFAULT_PRIVATE_BROADCAST)
? MAX_PRIVATE_BROADCAST_CONNECTIONS
: 0};
-
// HTTP server listen sockets: by default two (IPv4 and IPv6 loopback), or one per -rpcbind entry
int num_rpc_bind = std::max(args.GetArgs("-rpcbind").size(), size_t(2));
// HTTP server connected client sockets
@@ -1090,19 +1122,21 @@ bool AppInitParameterInteraction(const ArgsManager& args)
num_rpc_bind +
user_rpc_max_connections +
user_p2p_max_connections +
+ static_cast<int64_t>(ipc_fds) +
static_cast<int64_t>(max_private);
if (total_fds > std::numeric_limits<int>::max()) {
return InitError(Untranslated("Too many file descriptors requested. Try lower values for -rpcmaxconnections "
"or -maxconnections, or fewer settings of "
- "-rpcbind, -bind and -whitebind"));
+ "-rpcbind, -bind, -whitebind and -ipcbind"));
}
// Subset of total_fds must also be a safe int
int min_required_fds = MIN_CORE_FDS +
MAX_ADDNODE_CONNECTIONS +
num_p2p_bind +
num_rpc_bind +
- user_rpc_max_connections;
+ user_rpc_max_connections +
+ static_cast<int>(ipc_fds);
// Try raising the FD limit to what the user wants (available_fds may be smaller than the requested amount if this fails)
available_fds = RaiseFileDescriptorLimit(static_cast<int>(total_fds));
@@ -1569,13 +1603,15 @@ bool AppInitMain(NodeContext& node, interfaces::BlockAndHeaderTipInfo* tip_info)
uiInterface.InitWallet();
if (interfaces::Ipc* ipc = node.init->ipc()) {
- for (std::string address : gArgs.GetArgs("-ipcbind")) {
+ for (const std::string& configured_address : gArgs.GetArgs("-ipcbind")) {
+ auto listen_address{interfaces::Ipc::parseListenAddress(configured_address)};
+ Assert(listen_address); // Already validated in AppInitParameterInteraction.
try {
- ipc->listenAddress(address);
+ ipc->listenAddress(*listen_address);
} catch (const std::exception& e) {
- return InitError(Untranslated(strprintf("Unable to bind to IPC address '%s'. %s", address, e.what())));
+ return InitError(Untranslated(strprintf("Unable to bind to IPC address '%s'. %s", listen_address->address, e.what())));
}
- LogInfo("Listening for IPC requests on address %s", address);
+ LogInfo("Listening for IPC requests on address %s", listen_address->address);
}
}
### src/interfaces/ipc.h
@@ -5,6 +5,9 @@
#ifndef BITCOIN_INTERFACES_IPC_H
#define BITCOIN_INTERFACES_IPC_H
+#include <ipc/types.h>
+#include <util/result.h>
+
#include <functional>
#include <memory>
#include <string>
@@ -68,9 +71,14 @@ class Ipc
//! an unexpected error.
virtual std::unique_ptr<Init> connectAddress(std::string& address) = 0;
- //! Listen on a socket address exposing this process's init interface to
- //! clients. Throws an exception if there was an error.
- virtual void listenAddress(std::string& address) = 0;
+ //! Parse an IPC listening address and its per-listener options.
+ static util::Result<ipc::ListenAddress> parseListenAddress(std::string address);
+
+ //! Listen on a configured socket address exposing this process's init
+ //! interface and accepting at most listen_address.max_connections simultaneous
+ //! client connections. Updates listen_address.address with the resolved socket
+ //! address. Throws an exception if there was an error.
+ virtual void listenAddress(ipc::ListenAddress& listen_address) = 0;
//! Disconnect any incoming connections that are still connected.
virtual void disconnectIncoming() = 0;
### src/ipc/capnp/protocol.cpp
@@ -83,13 +83,13 @@ class CapnpProtocol : public Protocol
startLoop();
return mp::ConnectStream<messages::Init>(*m_loop, std::move(stream));
}
- void listen(mp::SocketId listen_fd, interfaces::Init& init) override
+ void listen(mp::SocketId listen_fd, interfaces::Init& init, std::optional<size_t> max_connections) override
{
startLoop();
if (::listen(listen_fd, /*backlog=*/5) != 0) {
throw std::system_error(errno, std::system_category());
}
- mp::ListenConnections<messages::Init>(*m_loop, listen_fd, init);
+ mp::ListenConnections<messages::Init>(*m_loop, listen_fd, init, max_connections);
}
void serve(interfaces::Init& init, const std::function<mp::Stream()>& make_stream) override
{
### src/ipc/interfaces.cpp
@@ -9,6 +9,7 @@
#include <ipc/capnp/protocol.h>
#include <ipc/process.h>
#include <ipc/protocol.h>
+#include <ipc/types.h>
#include <tinyformat.h>
#include <util/fs.h>
#include <util/log.h>
@@ -111,10 +112,10 @@ class IpcImpl : public interfaces::Ipc
}
return m_protocol->connect(m_protocol->makeStream(fd));
}
- void listenAddress(std::string& address) override
+ void listenAddress(ListenAddress& listen_address) override
{
- mp::SocketId fd = m_process->bind(gArgs.GetDataDirNet(), m_exe_name, address);
- m_protocol->listen(fd, m_init);
+ mp::SocketId fd = m_process->bind(gArgs.GetDataDirNet(), m_exe_name, listen_address.address);
+ m_protocol->listen(fd, m_init, listen_address.max_connections);
}
void disconnectIncoming() override
{
### src/ipc/listen.cpp
@@ -0,0 +1,75 @@
+// Copyright (c) 2026-present The Bitcoin Core developers
+// Distributed under the MIT software license, see the accompanying
+// file COPYING or http://www.opensource.org/licenses/mit-license.php.
+
+#include <common/url.h>
+#include <interfaces/ipc.h>
+#include <util/strencodings.h>
+#include <util/string.h>
+#include <util/translation.h>
+
+#include <cstdint>
+#include <string>
+#include <string_view>
+#include <utility>
+
+namespace {
+util::Result<int64_t> ParseIntOption(std::string_view name, std::string_view value, int64_t min_val, int64_t max_val)
+{
+ if (value.empty()) return util::Error{Untranslated(strprintf("Missing value for %s option", name))};
+ const auto parsed{ToIntegral<int64_t>(value)};
+ if (!parsed) return util::Error{Untranslated(strprintf("Invalid %s value '%s'", name, value))};
+ if (*parsed < min_val) return util::Error{Untranslated(strprintf("%s must be at least %d", name, min_val))};
+ if (*parsed > max_val) return util::Error{Untranslated(strprintf("%s must be at most %d", name, max_val))};
+ return *parsed;
+}
+} // namespace
+
+namespace interfaces {
+util::Result<ipc::ListenAddress> Ipc::parseListenAddress(std::string address)
+{
+ constexpr std::string_view UNIX_PREFIX{"unix:"};
+
+ // Only Unix socket -ipcbind values support inline socket options. Leave
+ // other address families untouched so ipc::Process can report address
+ // scheme errors consistently with -ipcconnect.
+ if (!address.starts_with(UNIX_PREFIX)) {
+ return ipc::ListenAddress{.address = std::move(address)};
+ }
+
+ // Socket options follow the first comma:
+ // unix:,max-connections=8
+ // unix:/custom/path,max-connections=8
+ // Commas in socket paths must be URL-encoded as %2C.
+ //
+ // Subsequent commas separate individual options.
+ const size_t option_pos{address.find(',')};
+ if (option_pos == std::string::npos) {
+ return ipc::ListenAddress{.address = UrlDecode(address)};
+ }
+
+ const std::string_view address_view{address};
+
+ ipc::ListenAddress listen_address{
+ .address = UrlDecode(address_view.substr(0, option_pos)),
+ };
+
+ for (const std::string& option_str : util::SplitString(address_view.substr(option_pos + 1), ',')) {
+ if (option_str.empty()) {
+ return util::Error{Untranslated("Empty socket option")};
+ }
+ const size_t eq{option_str.find('=')};
+ const std::string_view name{std::string_view{option_str}.substr(0, eq)};
+ const std::string_view value{eq == std::string::npos ? std::string_view{} : std::string_view{option_str}.substr(eq + 1)};
+ if (name == "max-connections") {
+ auto parsed{ParseIntOption(name, value, 1, static_cast<int64_t>(ipc::MAX_CONNECTIONS))};
+ if (!parsed) return util::Error{util::ErrorString(parsed)};
+ listen_address.max_connections = static_cast<size_t>(*parsed);
+ } else {
+ return util::Error{Untranslated(strprintf("Unknown socket option '%s'", name))};
+ }
+ }
+
+ return listen_address;
+}
+} // namespace interfaces
### src/ipc/protocol.h
@@ -8,8 +8,10 @@
#include <interfaces/init.h>
#include <ipc/util.h>
+#include <cstddef>
#include <functional>
#include <memory>
+#include <optional>
#include <typeindex>
namespace ipc {
@@ -38,7 +40,7 @@ class Protocol
//! Listen for connections on provided socket id, accept them, and handle
//! requests on accepted connections. This method doesn't block, and
//! performs I/O on a background thread.
- virtual void listen(mp::SocketId listen_fd, interfaces::Init& init) = 0;
+ virtual void listen(mp::SocketId listen_fd, interfaces::Init& init, std::optional<size_t> max_connections = std::nullopt) = 0;
//! Handle requests from a stream provided by the make_stream callback,
//! forwarding them to the provided Init interface. Socket communication is
### src/ipc/test/ipc_tests.cpp
@@ -5,12 +5,15 @@
#include <interfaces/init.h>
#include <ipc/capnp/mining.capnp.h>
#include <ipc/capnp/protocol.h>
+#include <interfaces/ipc.h>
#include <ipc/process.h>
#include <ipc/protocol.h>
#include <ipc/test/ipc_test.capnp.h>
#include <ipc/test/ipc_test.capnp.proxy.h>
#include <ipc/test/ipc_test.h>
#include <mp/proxy-types.h>
+#include <ipc/types.h>
+
#include <test/util/common.h>
#include <test/util/setup_common.h>
#include <tinyformat.h>
@@ -199,12 +202,56 @@ void IpcSocketTest(const fs::path& datadir)
}
}
+//! Test ipc::Protocol listen() local connection limiting over a unix socket.
+void IpcSocketMaxConnectionsTest(const fs::path& datadir)
+{
+ std::unique_ptr<interfaces::Init> init{std::make_unique<TestInit>()};
+ std::unique_ptr<ipc::Protocol> protocol{ipc::capnp::MakeCapnpProtocol("IpcSocketMaxConnectionsTest")};
+ std::unique_ptr<ipc::Process> process{ipc::MakeProcess()};
+
+ std::string address{strprintf("unix:%s", TempPath("bitcoin_sock_limit_XXXXXX"))};
+ mp::SocketId serve_fd = process->bind(datadir, "test_bitcoin", address);
+ BOOST_CHECK_NE(serve_fd, mp::SocketError);
+ protocol->listen(serve_fd, *init, /*max_connections=*/1);
+
+ auto connect_fd{[&](const std::string& connect_address) {
+ std::string addr{connect_address};
+ mp::SocketId fd{process->connect(datadir, "test_bitcoin", addr)};
+ return std::make_pair(fd, addr);
+ }};
+
+ auto [fd1, addr1] = connect_fd(address);
+ BOOST_CHECK_EQUAL(addr1, address);
+ std::unique_ptr<interfaces::Init> remote_init1{protocol->connect(protocol->makeStream(fd1))};
+ std::unique_ptr<interfaces::Echo> remote_echo1{remote_init1->makeEcho()};
+ BOOST_CHECK_EQUAL(remote_echo1->echo("echo test 1"), "echo test 1");
+
+ auto second_call = std::async(std::launch::async, [&] {
+ std::string addr{address};
+ mp::SocketId fd{process->connect(datadir, "test_bitcoin", addr)};
+ std::unique_ptr<interfaces::Init> remote_init{protocol->connect(protocol->makeStream(fd))};
+ std::unique_ptr<interfaces::Echo> remote_echo{remote_init->makeEcho()};
+ return std::make_pair(remote_echo->echo("echo test 2"), addr);
+ });
+
+ BOOST_CHECK(second_call.wait_for(std::chrono::milliseconds{100}) == std::future_status::timeout);
+
+ remote_echo1.reset();
+ remote_init1.reset();
+
+ BOOST_REQUIRE(second_call.wait_for(std::chrono::seconds{5}) == std::future_status::ready);
+ auto [echo2, addr2] = second_call.get();
+ BOOST_CHECK_EQUAL(addr2, address);
+ BOOST_CHECK_EQUAL(echo2, "echo test 2");
+}
+
BOOST_FIXTURE_TEST_SUITE(ipc_tests, BasicTestingSetup)
BOOST_AUTO_TEST_CASE(ipc_tests)
{
IpcPipeTest();
IpcSocketPairTest();
IpcSocketTest(m_args.GetDataDirNet());
+ IpcSocketMaxConnectionsTest(m_args.GetDataDirNet());
}
// Test address parsing.
@@ -229,6 +276,39 @@ BOOST_AUTO_TEST_CASE(parse_address_test)
"unix:" + prefix + "0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000.sock",
"Unix address path \"" + prefix + "0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000.sock\" exceeded maximum socket path length");
check_address("invalid", "invalid", "Unrecognized address 'invalid'");
+
+ auto check_listen_address{[](const std::string& configured_address, const std::string& expected_address, size_t expected_max_connections, const std::string& expected_error = "") {
+ auto listen_address{interfaces::Ipc::parseListenAddress(configured_address)};
+ if (!expected_error.empty()) {
+ BOOST_CHECK(!listen_address);
+ BOOST_CHECK_EQUAL(util::ErrorString(listen_address).original, expected_error);
+ return;
+ }
+ BOOST_REQUIRE(listen_address);
+ BOOST_CHECK_EQUAL(listen_address->address, expected_address);
+ BOOST_CHECK_EQUAL(listen_address->max_connections, expected_max_connections);
+ }};
+ check_listen_address("unix", "unix", ipc::DEFAULT_MAX_CONNECTIONS);
+ check_listen_address("unix:", "unix:", ipc::DEFAULT_MAX_CONNECTIONS);
+ check_listen_address("unix:,max-connections=8", "unix:", 8);
+ check_listen_address("unix:path.sock,max-connections=8", "unix:path.sock", 8);
+ check_listen_address("unix:,max-connections=1", "unix:", 1);
+ check_listen_address("unix:,max-connections=256", "unix:", ipc::MAX_CONNECTIONS);
+ check_listen_address("unix:path.sock,max-connections=8,unknown=1", "", 0, "Unknown socket option 'unknown'");
+ check_listen_address("unix:,max-connections=8,", "", 0, "Empty socket option");
+ check_listen_address("unix:,,max-connections=8", "", 0, "Empty socket option");
+ check_listen_address("unix:,max-connections=8,,max-connections=8", "", 0, "Empty socket option");
+ check_listen_address("unix:,max-connections=0", "", 0, "max-connections must be at least 1");
+ check_listen_address("unix:,max-connections=-1", "", 0, "max-connections must be at least 1");
+ check_listen_address("unix:,max-connections=-9223372036854775808", "", 0, "max-connections must be at least 1");
+ check_listen_address("unix:,max-connections=257", "", 0, "max-connections must be at most 256");
+ check_listen_address("unix:,max-connections=9223372036854775808", "", 0, "Invalid max-connections value '9223372036854775808'");
+ check_listen_address("unix:,max-connections=", "", 0, "Missing value for max-connections option");
+ check_listen_address("unix:path,backup.sock=1", "", 0, "Unknown socket option 'backup.sock'");
+ check_listen_address("unix:path%2Cbackup.sock=1", "unix:path,backup.sock=1", ipc::DEFAULT_MAX_CONNECTIONS);
+ check_listen_address("unix:path%2Cbackup.sock=1,max-connections=8", "unix:path,backup.sock=1", 8);
+ check_listen_address("unix:,max-connections", "", 0, "Missing value for max-connections option");
+ check_listen_address("unix:,max-connections=2,max-connections=1", "unix:", 1);
}
// Test command line parsing in ipc::Process::checkSpawned().
### src/ipc/types.h
@@ -0,0 +1,40 @@
+// Copyright (c) The Bitcoin Core developers
+// Distributed under the MIT software license, see the accompanying
+// file COPYING or http://www.opensource.org/licenses/mit-license.php.
+
+//! @file ipc/types.h is a home for public enum and struct type definitions
+//! that are used internally by ipc code, but also used externally by wallet,
+//! mining or GUI code.
+//!
+//! This file is intended to define only simple types that do not have external
+//! dependencies. More complicated types should be defined in dedicated header
+//! files.
+
+#ifndef BITCOIN_IPC_TYPES_H
+#define BITCOIN_IPC_TYPES_H
+
+#include <cstddef>
+#include <string>
+
+namespace ipc {
+
+//! Default accepted client connection limit for each IPC listening socket.
+inline constexpr size_t DEFAULT_MAX_CONNECTIONS{16};
+
+//! Maximum accepted client connection limit for an IPC listening socket.
+//! This conservative bound leaves ample room for other file descriptor
+//! reservations.
+inline constexpr size_t MAX_CONNECTIONS{256};
+
+struct ListenAddress {
+ //! Socket address passed to ipc::Process::bind(), with any -ipcbind socket
+ //! options stripped.
+ std::string address;
+
+ //! Maximum simultaneous client connections accepted by this listener.
+ size_t max_connections{DEFAULT_MAX_CONNECTIONS};
+};
+
+} // namespace ipc
+
+#endif // BITCOIN_IPC_TYPES_H
### test/functional/interface_ipc_init.py
@@ -0,0 +1,122 @@
+#!/usr/bin/env python3
+# Copyright (c) 2026 The Bitcoin Core developers
+# Distributed under the MIT software license, see the accompanying
+# file COPYING or http://www.opensource.org/licenses/mit-license.php.
+"""Test IPC initialization behavior."""
+
+import socket
+import tempfile
+import time
+from pathlib import Path
+
+from test_framework.test_framework import BitcoinTestFramework
+from test_framework.util import assert_equal
+
+MAX_IPC_CONNECTIONS = 256
+
+
+class IPCInitTest(BitcoinTestFramework):
+ def set_test_params(self):
+ self.setup_clean_chain = True
+ self.num_nodes = 1
+
+ def skip_test_if_missing_module(self):
+ self.skip_if_no_ipc()
+
+ def setup_nodes(self):
+ self.extra_init = [{"ipcbind": True}]
+ super().setup_nodes()
+ self.nodes[0].args = [arg for arg in self.nodes[0].args if not arg.startswith("-ipcbind=")]
+ self.ipc_tmpdir = tempfile.TemporaryDirectory(prefix="btc-ipc-init-")
+ self.ipcbind_path = Path(self.ipc_tmpdir.name) / "ipcinit.sock"
+ self.ipcbind_path2 = Path(self.ipc_tmpdir.name) / "ipcinit2.sock"
+
+ def test_ipcbind_max_connections(self):
+ self.log.info("Test -ipcbind max-connections initialization behavior")
+ node = self.nodes[0]
+
+ # Test default value (16)
+ with node.assert_debug_log([
+ "Reserving 17 file descriptors for IPC (1 listening sockets, 16 connection slots)",
+ ]):
+ self.restart_node(0, extra_args=[f"-ipcbind=unix:{self.ipcbind_path}"])
+
+ ipcbind_arg = f"-ipcbind=unix:{self.ipcbind_path},max-connections={{}}"
+
+ with node.assert_debug_log([
+ "Reserving 9 file descriptors for IPC (1 listening sockets, 8 connection slots)",
+ ]):
+ self.restart_node(0, extra_args=[ipcbind_arg.format(8)])
+ assert_equal(node.getblockcount(), 0)
+
+ self.stop_node(0)
+ node.assert_start_raises_init_error(
+ extra_args=[ipcbind_arg.format(0)],
+ expected_msg=f"Error: Invalid -ipcbind address 'unix:{self.ipcbind_path},max-connections=0': max-connections must be at least 1",
+ )
+ node.assert_start_raises_init_error(
+ extra_args=[ipcbind_arg.format(MAX_IPC_CONNECTIONS + 1)],
+ expected_msg=f"Error: Invalid -ipcbind address 'unix:{self.ipcbind_path},max-connections={MAX_IPC_CONNECTIONS + 1}': max-connections must be at most {MAX_IPC_CONNECTIONS}",
+ )
+
+ # Individually valid limits must not exceed the aggregate IPC FD cap.
+ half_max = MAX_IPC_CONNECTIONS // 2
+ node.assert_start_raises_init_error(
+ extra_args=[
+ ipcbind_arg.format(half_max),
+ f"-ipcbind=unix:{self.ipcbind_path2},max-connections={half_max}",
+ ],
+ expected_msg=f"Error: Too many IPC file descriptors requested: {MAX_IPC_CONNECTIONS + 2} -ipcbind listeners and connection slots exceed the limit of {MAX_IPC_CONNECTIONS + 1}. Reduce the number of -ipcbind addresses or their max-connections values",
+ )
+
+ def test_ipcbind_connection_limiting(self):
+ self.log.info("Test per-address -ipcbind connection limiting")
+ node = self.nodes[0]
+ self.restart_node(0, extra_args=[
+ f"-ipcbind=unix:{self.ipcbind_path},max-connections=1",
+ f"-ipcbind=unix:{self.ipcbind_path2},max-connections=1",
+ "-debug=ipc",
+ ])
+
+ def ipc_client(path):
+ client = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+ client.connect(str(path))
+ return client
+
+ # Each listener independently accepts its first client.
+ with node.assert_debug_log(["IPC server: socket connected."], timeout=5):
+ first1 = ipc_client(self.ipcbind_path)
+ with node.assert_debug_log(["IPC server: socket connected."], timeout=5):
+ first2 = ipc_client(self.ipcbind_path2)
+
+ # Further clients can connect to the socket backlog but must not be
+ # accepted while their listener's only slot is occupied.
+ with node.assert_debug_log([], unexpected_msgs=["IPC server: socket connected."]):
+ second1 = ipc_client(self.ipcbind_path)
+ second2 = ipc_client(self.ipcbind_path2)
+ time.sleep(0.5)
+
+ # Freeing a slot on either listener immediately admits its waiting client.
+ with node.assert_debug_log([
+ "IPC server: socket disconnected.",
+ "IPC server: socket connected.",
+ ], timeout=5):
+ first1.close()
+ with node.assert_debug_log([
+ "IPC server: socket disconnected.",
+ "IPC server: socket connected.",
+ ], timeout=5):
+ first2.close()
+
+ with node.assert_debug_log(["IPC server: socket disconnected."], timeout=5):
+ second1.close()
+ with node.assert_debug_log(["IPC server: socket disconnected."], timeout=5):
+ second2.close()
+
+ def run_test(self):
+ self.test_ipcbind_max_connections()
+ self.test_ipcbind_connection_limiting()
+
+
+if __name__ == '__main__':
+ IPCInitTest(__file__).main()
### test/functional/test_runner.py
@@ -399,6 +399,7 @@
'p2p_handshake.py',
'p2p_handshake.py --v2transport',
'interface_ipc_cli.py',
+ 'interface_ipc_init.py',
'feature_dirsymlinks.py',
'feature_help.py',
'feature_framework_startup_failures.py',Why this scored 22/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.