Usage Instructions

NodePass creates tunnels with an unencrypted TCP control channel and configurable TLS encryption options for data exchange. This guide covers the three operating modes and explains how to use each effectively.

Command Line Syntax

The general syntax for NodePass commands is:

nodepass "<core>://<tunnel_addr>/<target_addr>?log=<level>&tls=<mode>&crt=<cert_file>&key=<key_file>&min=<min_pool>&max=<max_pool>"

Where:

<core>: Specifies the operating mode (server, client, or master)
<tunnel_addr>: The tunnel endpoint address for control channel communications
<target_addr>: The destination address for business data with bidirectional flow support (or API prefix in master mode)

Query Parameters

Common query parameters:

log=<level>: Log verbosity level (none, debug, info, warn, error, or event)
min=<min_pool>: Minimum connection pool capacity (default: 64, client mode only)
max=<max_pool>: Maximum connection pool capacity (default: 1024, client mode only)

TLS-related parameters (server/master modes only):

tls=<mode>: TLS security level for data channels (0, 1, or 2)
crt=<cert_file>: Path to certificate file (when tls=2)
key=<key_file>: Path to private key file (when tls=2)

Operating Modes

NodePass offers three complementary operating modes to suit various deployment scenarios.

Server Mode

Server mode establishes tunnel control channels and supports bidirectional data flow forwarding.

nodepass "server://<tunnel_addr>/<target_addr>?log=<level>&tls=<mode>&crt=<cert_file>&key=<key_file>"

Parameters

tunnel_addr: Address for the TCP tunnel endpoint (control channel) that clients will connect to (e.g., 10.1.0.1:10101)
target_addr: The destination address for business data with bidirectional flow support (e.g., 10.1.0.1:8080)
log: Log level (debug, info, warn, error, event)
tls: TLS encryption mode for the target data channel (0, 1, 2)
- 0: No TLS encryption (plain TCP/UDP)
- 1: Self-signed certificate (automatically generated)
- 2: Custom certificate (requires crt and key parameters)
crt: Path to certificate file (required when tls=2)
key: Path to private key file (required when tls=2)

How Server Mode Works

In server mode, NodePass supports two data flow directions:

Mode 1: Server Receives Traffic (target_addr is local address)

Listens for TCP tunnel connections (control channel) on tunnel_addr
Listens for incoming TCP and UDP traffic on target_addr
When a connection arrives at target_addr, it signals the connected client through the control channel
Creates a data channel for each connection with the specified TLS encryption level

Mode 2: Server Sends Traffic (target_addr is remote address)

Listens for TCP tunnel connections (control channel) on tunnel_addr
Waits for clients to listen locally and receive connections through the tunnel
Establishes connections to remote target_addr and forwards data

Examples

# No TLS encryption for data channel - Server receives mode
nodepass "server://10.1.0.1:10101/10.1.0.1:8080?log=debug&tls=0"

# Self-signed certificate (auto-generated) - Server sends mode
nodepass "server://10.1.0.1:10101/192.168.1.100:8080?log=debug&tls=1"

# Custom domain certificate - Server receives mode
nodepass "server://10.1.0.1:10101/10.1.0.1:8080?log=debug&tls=2&crt=/path/to/cert.pem&key=/path/to/key.pem"

Client Mode

Client mode connects to a NodePass server and supports bidirectional data flow forwarding.

nodepass "client://<tunnel_addr>/<target_addr>?log=<level>&min=<min_pool>&max=<max_pool>"

Parameters

tunnel_addr: Address of the NodePass server's tunnel endpoint to connect to (e.g., 10.1.0.1:10101)
target_addr: The destination address for business data with bidirectional flow support (e.g., 127.0.0.1:8080)
log: Log level (debug, info, warn, error, event)
min: Minimum connection pool capacity (default: 64)
max: Maximum connection pool capacity (default: 1024)

How Client Mode Works

In client mode, NodePass supports three operating modes:

Mode 1: Client Single-End Forwarding (when tunnel address is local)

Listens for TCP and UDP connections on the local tunnel address
Uses connection pooling technology to pre-establish TCP connections to target address, eliminating connection latency
Directly forwards received traffic to the target address with high performance
No handshake with server required, enables point-to-point direct forwarding
Suitable for local proxy and simple forwarding scenarios

Mode 2: Client Receives Traffic (when server sends traffic)

Connects to the server's TCP tunnel endpoint (control channel)
Listens locally and waits for connections through the tunnel
Establishes connections to local target_addr and forwards data

Mode 3: Client Sends Traffic (when server receives traffic)

Connects to the server's TCP tunnel endpoint (control channel)
Listens for signals from the server through this control channel
When a signal is received, establishes a data connection with the TLS security level specified by the server
Creates a connection to target_addr and forwards traffic

Examples

# Client single-end forwarding mode - Local proxy listening on port 1080, forwarding to target server
nodepass client://127.0.0.1:1080/target.example.com:8080?log=debug

# Connect to a NodePass server and adopt its TLS security policy - Client sends mode
nodepass client://server.example.com:10101/127.0.0.1:8080

# Connect with debug logging - Client receives mode
nodepass client://server.example.com:10101/192.168.1.100:8080?log=debug

# Custom connection pool capacity - High performance configuration
nodepass "client://server.example.com:10101/127.0.0.1:8080?min=128&max=4096"

# Resource-constrained configuration - Small connection pool
nodepass "client://server.example.com:10101/127.0.0.1:8080?min=16&max=512&log=info"

Master Mode (API)

Master mode runs a RESTful API server for centralized management of NodePass instances.

nodepass "master://<api_addr>[<prefix>]?log=<level>&tls=<mode>&crt=<cert_file>&key=<key_file>"

Parameters

api_addr: Address where the API service will listen (e.g., 0.0.0.0:9090)
prefix: Optional API prefix path (e.g., /management). Default is /api
log: Log level (debug, info, warn, error, event)
tls: TLS encryption mode for the API service (0, 1, 2)
- 0: No TLS encryption (HTTP)
- 1: Self-signed certificate (HTTPS with auto-generated cert)
- 2: Custom certificate (HTTPS with provided cert)
crt: Path to certificate file (required when tls=2)
key: Path to private key file (required when tls=2)

How Master Mode Works

In master mode, NodePass:

Runs a RESTful API server that allows dynamic management of NodePass instances
Provides endpoints for creating, starting, stopping, and monitoring client and server instances
Includes Swagger UI for easy API exploration at {prefix}/v1/docs
Automatically inherits TLS and logging settings for instances created through the API

API Endpoints

All endpoints are relative to the configured prefix (default: /api):

GET {prefix}/v1/instances - List all instances
POST {prefix}/v1/instances - Create a new instance with JSON body: {"url": "server://0.0.0.0:10101/0.0.0.0:8080"}
GET {prefix}/v1/instances/{id} - Get instance details
PATCH {prefix}/v1/instances/{id} - Update instance with JSON body: {"action": "start|stop|restart"}
DELETE {prefix}/v1/instances/{id} - Delete instance
GET {prefix}/v1/openapi.json - OpenAPI specification
GET {prefix}/v1/docs - Swagger UI documentation

Examples

# Start master with HTTP using default API prefix (/api)
nodepass "master://0.0.0.0:9090?log=info"

# Start master with custom API prefix (/management)
nodepass "master://0.0.0.0:9090/management?log=info"

# Start master with HTTPS (self-signed certificate)
nodepass "master://0.0.0.0:9090/admin?log=info&tls=1"

# Start master with HTTPS (custom certificate)
nodepass "master://0.0.0.0:9090?log=info&tls=2&crt=/path/to/cert.pem&key=/path/to/key.pem"

Managing NodePass Instances

Creating and Managing via API

You can use standard HTTP requests to manage NodePass instances through the master API:

# Create and manage instances via API (using default prefix)
curl -X POST https://localhost:9090/api/v1/instances \
  -H "Content-Type: application/json" \
  -d '{"url":"server://0.0.0.0:10101/0.0.0.0:8080?tls=1"}'

# Using custom prefix
curl -X POST https://localhost:9090/admin/v1/instances \
  -H "Content-Type: application/json" \
  -d '{"url":"server://0.0.0.0:10101/0.0.0.0:8080?tls=1"}'

# List all running instances
curl https://localhost:9090/api/v1/instances

# Control an instance (replace {id} with actual instance ID)
curl -X PUT https://localhost:9090/api/v1/instances/{id} \
  -H "Content-Type: application/json" \
  -d '{"action":"restart"}'

Bidirectional Data Flow Explanation

NodePass supports flexible bidirectional data flow configuration:

Client Single-End Forwarding Mode

Client: Listens on local tunnel address, uses connection pooling technology to directly forward to target address
Connection Pool Optimization: Pre-establishes TCP connections, eliminates connection latency, provides high-performance forwarding
No Server Required: Operates independently without server handshake
Use Case: Local proxy, simple port forwarding, testing environments, high-performance forwarding

Server Receives Mode (dataFlow: "-")

Server: Listens for incoming connections on target_addr, forwards through tunnel to client
Client: Connects to local target_addr to provide services
Use Case: Expose internal services to external access

Server Sends Mode (dataFlow: "+")

Server: Connects to remote target_addr to fetch data, sends through tunnel to client
Client: Listens locally to receive connections from server
Use Case: Access remote services through tunnel proxy

The system automatically selects the appropriate operation mode based on tunnel and target addresses:

If the client's tunnel address is a local address, enables single-end forwarding mode
If target address is a local address, uses Server Receives Mode
If target address is a remote address, uses Server Sends Mode

Tunnel Key

NodePass uses tunnel keys to authenticate connections between clients and servers. The key can be specified in two ways:

Key Derivation Rules

Explicit Key: Specify the username part in the URL as the 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

Port-Derived Key: If no username is specified, the system uses the hexadecimal value of the port number as the key

# 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
nodepass client://10.1.0.1:10101/127.0.0.1:8080

Handshake Process

The handshake process between client and server is as follows:

Client Connection: Client connects to the server's tunnel address
Key Authentication: Client sends XOR-encrypted tunnel key
Server Verification: Server decrypts and verifies if the key matches
Configuration Sync: Upon successful verification, server sends tunnel configuration (including TLS mode)
Connection Established: Handshake complete, data transmission begins

This design ensures that only clients with the correct key can establish tunnel connections.

Next Steps

Learn about configuration options to fine-tune NodePass
Explore examples of common deployment scenarios
Understand how NodePass works under the hood
Check the troubleshooting guide if you encounter issues

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!