DOCSEARCHbyAlgolia
Submit Docs

NodePass TCP/UDP Network Tunneling

repository·main·Indexed 42 days ago

https://github.com/nodepassproject/nodepass

An open-source, lightweight, enterprise-grade TCP/UDP network tunneling solution featuring an all-in-one architecture with separated control and data channels. It supports NAT traversal, protocol conversion, and connection pooling via TCP, QUIC, WebSocket, and HTTP/2. NodePass operates in three modes: server, client, and master (REST/OpenAPI control interface), and offers three TLS security modes including plaintext, self-signed, and strict validation.

Tokens
42.7K
Snippets
112
Records
167
Agent score
52%

What's inside NodePass

  1. Overview of the NodePass API

    main
    NodePass provides a RESTful API when running in Master Mode. This API is designed to support frontend integration and automation tasks. The API surface includes various endpoints for interacting with the NodePass instance, real-time event streaming via Server-Sent Events (SSE), and structured data exchange using the Instance Data Structure.

  2. Overview of NodePass System Architecture

    main

    NodePass is built on a layered, decoupled architecture designed for cloud-native environments.

    Core Architectural Layers

    1. Transport Layer: Separates control and data channels. This prevents control signaling from interfering with data throughput and allows independent optimization of TCP and UDP.
    2. Security Layer: A pluggable TLS implementation that supports modular security levels, automated certificate management, and key rotation.
    3. Management Layer: An API-first, stateless design that is container-friendly and supports horizontal scaling.

    Key Performance Innovations

    • Connection Pool Warm-up: Instead of "connect-on-demand," NodePass uses a "pre-warm-and-ready" approach to eliminate cold start latency.
    • Fault Isolation: Provides connection-level isolation so that a single point of failure does not impact the entire service. It also features automatic reconnection and graceful degradation strategies.

  3. Operational behaviors and limitations of NodePass MCP

    main

    When automating NodePass via MCP, be aware of the following behaviors:

    • Asynchronous Execution: Tools like create_instance, control_instance, delete_instance, and import_instances return a response once the request is accepted. You must poll get_instance or list_instances to confirm completion.
    • Configuration Updates: When using setter tools, if an instance is currently running, NodePass will stop it, update the configuration, regenerate the config URL, and restart it.
    • Tag Replacement: The tags argument in update_instance replaces the entire existing tag map. It does not perform a merge.
    • Protected Data: The internal ID ******** is used to store the API key and master ID. This ID is hidden from list_instances and cannot be modified by instance mutation tools.
    • Structured Data: MCP returns structured data fields in addition to text. Automation clients should prioritize consuming these structured fields for better reliability.

  4. Configure WebSocket Pool Settings and Security

    main

    When using the WebSocket-based pool (type=2), NodePass establishes connections via standard HTTP upgrade requests, making it highly compatible with proxies and load balancers.

    Security Configuration: TLS is required for all WebSocket pools (WSS). You can select from two TLS modes:

    • Mode 1: WSS with self-signed certificates.
    • Mode 2: WSS with full certificate verification (required for production).

    Key Characteristics:

    • Traversal: Uses standard ports 80 (ws) or 443 (wss) and can be deployed through CDNs.
    • Lifecycle: The server assigns a unique connection ID during the handshake, which is sent to the client via the control channel to allow the client to retrieve the connection as a net.Conn.
    • Validation: Supports Origin validation to prevent cross-site WebSocket hijacking and allows custom authentication headers.

  5. Core Concepts of NodePass Architecture

    main

    NodePass uses an integrated S/C/M (Server/Client/Master) architecture designed with the full decoupling of control and data channels.

    • Server: Handles incoming tunnel connections and manages traffic relay to target destinations.
    • Client: Establishes the tunnel connection to a server to bridge local traffic to a remote target.
    • Master: Provides multi-instance management and coordination.
    • Connection Pooling: Supports TCP, QUIC, WebSocket, and HTTP/2 transport methods to eliminate handshake delays and support 0-RTT.
    • Security Modes: Offers three TLS modes: plaintext, self-signed, and strict validation.

  6. Compare TCP and UDP data exchange

    main

    NodePass supports both TCP and UDP protocols with different handling characteristics:

    • TCP: Provides full bidirectional streaming using persistent connections. It uses conn.DataExchange() for continuous data transfer and supports automatic error handling with reconnection capabilities.
    • UDP: Uses datagram forwarding. It is optimized for low-latency, stateless communication. It uses one-shot datagram forwarding with configurable buffer sizes (UDP_DATA_BUF_SIZE) and supports read timeout control for waiting for responses.

  7. How bidirectional data flow modes work

    main

    NodePass automatically selects an operating mode based on the tunnel and target addresses provided in the connection URL. Understanding these modes helps in configuring different networking scenarios:

    1. Client Single-End Forwarding Mode:

      • Behavior: The client listens on a local tunnel address and uses connection pooling to forward directly to the target address.
      • Key Feature: No server is required for the handshake; it operates independently.
      • Use Case: Local proxies, simple port forwarding, or high-performance forwarding in testing environments.
      • Trigger: Enabled if the client's tunnel address is a local address.

    2. Server Receives Mode:

      • Behavior: The server listens on the target_addr and forwards incoming connections through the tunnel to the client.
      • Use Case: Exposing internal services to external access.
      • Trigger: Enabled if the target address is a local address.

    3. Server Sends Mode:

      • Behavior: The server connects to a remote target_addr to fetch data and sends it through the tunnel to the client.
      • Use Case: Accessing remote services through a tunnel proxy.
      • Trigger: Enabled if the target address is a remote address.

  8. Configure Instance URLs (Server and Client modes)

    main

    NodePass uses two primary URL formats for instance configuration. These URLs define how traffic is routed and which protocols are used.

    Server Mode

    Format: server://<bind_address>:<bind_port>/<target_host>:<target_port>?<parameters> Used to listen on a specific address/port and forward traffic to a target. Example: server://0.0.0.0:8080/localhost:3000 (Listen on 8080, forward to local 3000).

    Client Mode

    Format: client://<server_host>:<server_port>/<local_host>:<local_port>?<parameters> Used to connect to a remote server and listen on a local port. Example: client://example.com:8080/localhost:3000 (Connect to example.com:8080, listen locally on 3000).

  9. Understand NodePass Operating Modes

    main

    NodePass operates using three core modes, specified by the <core> component in the command URI:

    1. server: Acts as the tunnel endpoint. It manages connection pools and can configure TLS and pool types which are then communicated to the client.
    2. client: Connects to a server to establish a tunnel for data exchange.
    3. master: Used for API-driven control, where the <target_addr> acts as an API prefix.

  10. Use the NodePass MCP JSON-RPC 2.0 interface

    main

    NodePass accepts MCP requests via HTTP POST with a JSON-RPC 2.0 body.

    Required Headers:

    • Content-Type: application/json
    • X-API-Key: <api-key>

    Response Formats:

    • Success: Returns HTTP 200 with a result object.
    • JSON-RPC Error: Returns HTTP 200 with an error object containing code, message, and data.
    • HTTP Errors: Errors like 401 (Unauthorized) or 405 (Method Not Allowed) are returned before JSON-RPC processing.
    {
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

  11. Implement High Availability with Target Address Groups

    main

    NodePass supports high availability and load balancing by providing a comma-separated list of target addresses.

    • Load Balancing: When using mode=2 on the server side, NodePass uses a round-robin algorithm to distribute traffic across the provided addresses.
    • Automatic Failover: If one backend fails, NodePass automatically switches to another available server in the group and resumes traffic to recovered servers.
    • Best Practices:
      • Use 2-5 addresses per group; too many can increase failure detection time.
      • Ensure backend services have their own health checks.
      • Maintain port consistency across addresses or specify the port for each.
    # Server side: Round-robin load balancing across 3 backends
nodepass "server://0.0.0.0:10101/web1.internal:8080,web2.internal:8080,web3.internal:8080?mode=2&tls=1"

# Client side: High-performance local proxy with primary/replica failover
nodepass "client://127.0.0.1:3306/db-primary.local:3306,db-secondary.local:3306?mode=1"

  12. Configure and use Tunnel Keys for authentication

    main

    Tunnel keys are used to authenticate the connection between a client and a server. You can specify a key using two different methods in your connection URL:

    1. Explicit Key (Username Method)

    Specify the key as the username part of the URL. This is the most reliable way to set a custom key.

    # Use 'mypassword' as the tunnel key
nodepass server://mypassword@10.1.0.1:10101/10.1.0.1:8080
nodepass client://mypassword@10.1.0.1:10101/127.0.0.1:8080

    2. Port-Derived Key (Automatic Method)

    If no username is provided in the URL, NodePass derives the key from the hexadecimal value of the port number.

    # Port 10101's hexadecimal value '2775' will be used as the tunnel key
nodepass server://10.1.0.1:10101/10.1.0.1:8080

    Handshake Lifecycle

    1. Connection: Client connects to the server's tunnel address.
    2. Authentication: Client sends the encrypted tunnel key.
    3. Verification: Server decrypts and verifies the key.
    4. Sync: Upon success, the server sends configuration (data flow direction, max connection pool capacity, TLS mode).
    5. Establishment: Data transmission begins.
    # Explicit Key Example
nodepass server://mypassword@10.1.0.1:10101/10.1.0.1:8080

# Port-Derived Key Example
nodepass server://10.1.0.1:10101/10.1.0.1:8080