Design of a Secure IPC and JSON-RPC Based Administration Framework for FullNode #6497
Description
Background
After a FullNode is started, its runtime status must be continuously monitored in real time . Once an abnormal condition is detected, timely manual intervention should be possible, such as dynamically adjusting startup or runtime parameters. Currently, the system lacks an effective mechanism to interact with the node. In most abnormal scenarios, recovery can only be achieved by restarting the node, which inevitably interrupts the services provided by the FullNode and negatively impacts overall stability and availability.
Although the existing configuration file provides the node.dynamicConfig capability, its functionality is relatively limited, lacks extensibility, and provides no real-time feedback to users. As a result, it does not adequately meet operational and debugging requirements. To address these limitations, we designed and implemented a real-time interaction mechanism for FullNode based on a UNIX Server Socket combined with a JSON-RPC service bound only to the local network interface. This approach significantly improves system flexibility, operability, and issue-handling efficiency while maintaining strong security guarantees.
Rationale
Why should this feature exist?
This solution enables real-time, bidirectional interaction with a FullNode, rather than being limited to passive reading of node status or information. It greatly improves troubleshooting and debugging efficiency, simplifies node management workflows, and supports rapid intervention in abnormal scenarios, ultimately ensuring the overall stability and availability of the service.
What are the use-cases?
- Support dynamic management of node connections, including operations such as AddPeer, RemovePeer, AddTrustedPeer, and RemoveTrustedPeer, enabling flexible runtime adjustment of peers and related policies.
- Support querying all runtime non-sensitive parameters, not limited to the information currently exposed by org.tron.core.services.NodeInfoService, thereby improving observability and operational transparency.
- Support dynamic modification of configuration parameters during runtime for debugging and issue diagnosis without restarting the FullNode, reducing service interruption risks and improving debugging efficiency.
Specification
Users can interact with the FullNode in two ways:
- an HTTP-based JSON-RPC service, and
- a local IPC service based on a UNIX Server Socket.
Both approaches share identical interface definitions, parameter validation, and execution logic, differing only in communication channels and security boundaries.
Assume the following JSON-RPC interface is defined in FullNode:
@Component
public interface AdminJsonRpc {
@JsonRpcMethod("admin_example")
@JsonRpcErrors({
@JsonRpcError(exception = JsonRpcInvalidParamsException.class, code = -32602, data = "{}"),
})
String adminExample(@JsonRpcParam("param1") String param1,
@JsonRpcParam("param2") String param2)
throws JsonRpcInvalidParamsException;
}
Approach 1: HTTP-based JSON-RPC Interaction
In this approach, a dedicated HTTP service and port are started to expose the AdminJsonRpc interface, referred to as AdminRpcHttpService. Users can interact with the node through standard HTTP POST requests, for example:
{"jsonrpc":"2.0","id":1,"method":"admin_example","params":["abc","def"]}
For security reasons, AdminRpcHttpService listens on localhost by default to prevent external exposure of administrative interfaces. If necessary, the listening address can be adjusted via configuration to allow access from LAN nodes or a wider network scope. This approach is suitable for automated operations, remote management, and integration with external systems.
The overall interaction flow is illustrated below:
Approach 2: Inter-Process Communication via UNIX Server Socket
The second approach uses a UNIX Server Socket to enable inter-process communication (IPC). When the FullNode starts, it creates a socket file named after the process ID under the /tmp directory and starts an IpcService bound to this socket. The IpcService listens for incoming socket requests in a dedicated thread.
On the same machine, users can bind to the socket file using FullNode.jar and start an IpcClient process. Interaction with the IpcService is performed using commands such as:
> admin_example abc def
The IpcClient parses and validates the command-line input, resolves the corresponding JSON-RPC method, and converts it into a standard JSON-RPC request. The request is then sent to the IpcService through the UNIX socket, and the execution result is received and displayed.
Upon receiving the request, the IpcService delegates execution to the internal JSON-RPC Server and returns the result to the IpcClient through the same socket, which is then presented to the user. Functionally and in terms of output, this approach is fully equivalent to the HTTP-based approach.
Key Characteristics
- Both interaction methods share the same underlying JSON-RPC Server, ensuring consistent behavior.
- Each method can be independently enabled or disabled via configuration, without mutual dependency or interference.
- The local UNIX Server Socket communication model avoids exposing network ports, significantly enhancing security and reducing the attack surface.
Test Specification
Scope Of Impact
Only the services module of the framework is affected.
Implementation
Do you have ideas regarding the implementation of this feature?
Yes.
Are you willing to implement this feature?
Yes. An example interaction between the IPC Client and IPC Service is shown below:
[use@host]$ java -jar build/libs/FullNode.jar --attach /tmp/java-tron.91257.sock
Connected to server: /tmp/java-tron.91257.sock
You can enter the following commands, case insensitive:
admin_example, help, exit, quit
> help
You can enter the following commands, case insensitive:
admin_example, help, exit, quit
> help admin_example
usage: admin_example param1 param2
> admin_example abc def
{"jsonrpc":"2.0","id":2,"result":"abc:def"}
Backwards Compatibility
This solution does not depend on existing JSON-RPC interface definitions; therefore, it introduces no interface evolution or compatibility risks.
Starting from JDK 16, Java provides native support for Unix Domain Sockets. In JDK 1.8 environments, access to Unix Domain Sockets on Linux / Unix platforms can be achieved via the third-party library junixsocket. Since FullNode must currently support both JDK 1.8 and JDK 17 runtimes, junixsocket is used as the unified underlying communication mechanism to ensure consistent behavior and implementation stability.
In future versions, once compatibility with JDK 1.8 is no longer required, the implementation can be migrated to Java’s native Unix Domain Socket support. This will reduce third-party dependencies, further simplify the system architecture, and lower long-term maintenance costs.