Port Forwarding - Undying Terminal

Overview

Undying Terminal supports two types of port forwarding to tunnel TCP traffic through your persistent session:

Forward Tunnels (-t)

Client opens local port → forwards to remote destinationUse case: Access remote services locally

Reverse Tunnels (-r)

Server opens port → client connects to local destinationUse case: Expose local services remotely

Both tunnel types survive disconnects and automatically reconnect, making them ideal for unstable networks.

Forward Tunnels

Basic Syntax

./undying-terminal.exe `
  --connect <HOST> <PORT> <CLIENT_ID> `
  --key <PASSKEY> `
  -t <LOCAL_PORT>:<REMOTE_HOST>:<REMOTE_PORT>

Examples

# Forward local 8080 → remote 9090
./undying-terminal.exe `
  --connect 192.168.1.100 2022 abc123 `
  --key mypasskey `
  -t 8080:9090

# Access via: http://localhost:8080 → remote:9090

How Forward Tunnels Work

Client Opens Listener

Client starts TCP listener on specified local port (e.g., 8080)

Local Connection Established

Local application connects to localhost:8080

Tunnel Request Sent

Client sends PORT_FORWARD_DESTINATION_REQUEST to server with:

Source: localhost:8080
Destination: remote:9090
Socket ID: unique identifier

Server Connects to Destination

Server establishes TCP connection to remote:9090

Bidirectional Relay

All traffic flows through the session:

Local → Client → Server → Remote
Remote → Server → Client → Local

Use Cases

Database Access

Forward remote database to local port:

# PostgreSQL
-t 5432:db.internal:5432

# MySQL
-t 3306:mysql.internal:3306

# Redis
-t 6379:redis.internal:6379

Connect with local tools:

psql -h localhost -p 5432 -U user

Web Development

Access remote development servers:

# Forward remote webpack dev server
-t 8080:localhost:8080

# Forward remote API server
-t 3000:api.dev:3000

Access via browser: http://localhost:8080

Internal Services

Access services behind firewall:

# Kubernetes dashboard
-t 8001:k8s-master:8001

# Grafana
-t 3000:monitoring.internal:3000

# Jenkins
-t 8080:ci.internal:8080

Reverse Tunnels

Basic Syntax

./undying-terminal.exe `
  --connect <HOST> <PORT> <CLIENT_ID> `
  --key <PASSKEY> `
  -r <REMOTE_PORT>:<LOCAL_HOST>:<LOCAL_PORT>

Examples

# Server listens on 3000, forwards to client's localhost:8000
./undying-terminal.exe `
  --connect 192.168.1.100 2022 abc123 `
  --key mypasskey `
  -r 3000:localhost:8000

# Remote access via: server:3000 → client's localhost:8000

How Reverse Tunnels Work

Server Opens Listener

Server starts TCP listener on specified remote port (e.g., 3000)

Remote Connection Established

Remote user connects to server:3000

Destination Request Sent

Server sends PORT_FORWARD_DESTINATION_REQUEST to client with socket ID

Client Connects Locally

Client establishes connection to specified local destination (e.g., localhost:8000)

Bidirectional Relay

Traffic flows:

Remote → Server → Client → Local
Local → Client → Server → Remote

Use Cases

Development Webhooks

Expose local dev server for webhooks (GitHub, Stripe, etc.):

# Expose local:3000 to internet via remote server
-r 80:localhost:3000

Configure webhook URL: http://remote-server.com:80/webhook

Demo/Staging

Share local development with team:

# Expose local React app
-r 8080:localhost:3000

Team access: http://remote-server.com:8080

Remote Desktop / VNC

Access local machine from remote network:

# RDP
-r 3389:localhost:3389

# VNC
-r 5900:localhost:5900

# SSH to local machine
-r 2222:localhost:22

Multiple Tunnels

Combine forward and reverse tunnels:

./undying-terminal.exe `
  --connect server.com 2022 abc123 `
  --key mypasskey `
  -t 5432:db.internal:5432 `          # Forward: local DB access
  -t 6379:redis.internal:6379 `       # Forward: local Redis access
  -r 8080:localhost:3000 `             # Reverse: expose local web server
  -r 9090:localhost:5000               # Reverse: expose local API

Tunnel Syntax Reference

Format Options

Syntax	Description	Example
`LOCAL:REMOTE`	Simple: local port → remote port	`-t 8080:9090`
`LOCAL:HOST:REMOTE`	Explicit: local port → remote host:port	`-t 8080:db:5432`
`BIND:LOCAL:HOST:REMOTE`	Full: bind IP, local port → remote host:port	`-t 0.0.0.0:8080:db:5432`
`START-END:START-END`	Range: multiple ports	`-t 8080-8085:9090-9095`

Bind Addresses

Address	Behavior
`localhost` (default)	Only accessible from local machine
`0.0.0.0`	Accessible from any interface
`192.168.1.x`	Accessible from specific interface
`127.0.0.1`	Explicit localhost

Security: Binding to 0.0.0.0 exposes the tunnel to your network. Use with caution!

Tunnel Persistence

Tunnels survive disconnects:

Initial Connection

Client connects, tunnels established

Network Interruption

Network drops, client disconnects

Automatic Reconnect

Client reconnects automatically

Tunnels Restored

All tunnels re-established transparently

Active connections through tunnels are not preserved during disconnect. However, new connections work immediately after reconnect.

Environment Variable Forwarding

Forward environment variables through tunnels:

# Forward based on env var
$env:MY_SERVICE_PORT = "8080:remote-service:9090"
./undying-terminal.exe ... -t $env:MY_SERVICE_PORT

Useful for scripting and automation.

Troubleshooting

Tunnel not working - connection refused

Symptoms: Local/remote service unreachableDiagnosis:

Verify service is running:

# On destination machine
netstat -ano | findstr :9090

Check firewall rules
Verify bind address (localhost vs 0.0.0.0)

Solution: Ensure destination service is accessible from server

Port already in use

Error: bind: address already in useDiagnosis:

netstat -ano | findstr :8080

Solution:

Choose different local port
Kill process using the port
Use specific bind address (not 0.0.0.0)

Slow tunnel performance

Symptoms: High latency, slow transfersCauses:

Network bandwidth limitation
Multiple packet hops
Large recovery buffer replay

Solutions:

Use direct network path when possible
Reduce keepalive frequency
Check network quality (ping, traceroute)

Tunnel breaks after reconnect

Expected Behavior: Active connections drop, new connections workExplanation: TCP connections can’t survive both endpoints changing. Undying Terminal restores the tunnel infrastructure, but application-level connections must be re-established.Workaround: Applications should implement reconnect logic

Best Practices

Security

Use localhost bind when possible
Enable encryption for internet-facing tunnels
Restrict server firewall rules
Use strong passkeys

Performance

Minimize tunnel hops (use direct paths)
Use port ranges for efficiency
Monitor bandwidth usage
Test latency impact

Reliability

Design for reconnect (don’t rely on persistent connections)
Use health checks in applications
Log tunnel status
Monitor connection stability

Organization

Document tunnel mappings
Use consistent port conventions
Group related tunnels
Version tunnel configurations

Next Steps

Jumphost Guide

Connect through intermediate servers

SSH Bootstrap

Start remote sessions over SSH

Client CLI Reference

Full CLI options

Architecture

How tunnels work internally

​Overview

Forward Tunnels (-t)

Reverse Tunnels (-r)

​Forward Tunnels

​Basic Syntax

​Examples

​How Forward Tunnels Work

​Use Cases

​Reverse Tunnels

​Basic Syntax

​Examples

​How Reverse Tunnels Work

​Use Cases

​Multiple Tunnels

​Tunnel Syntax Reference

​Format Options

​Bind Addresses

​Tunnel Persistence

​Environment Variable Forwarding

​Troubleshooting

​Best Practices

Security

Performance

Reliability

Organization

​Next Steps

Jumphost Guide

SSH Bootstrap

Client CLI Reference

Architecture

Overview

Forward Tunnels

Basic Syntax

Examples

How Forward Tunnels Work

Use Cases

Reverse Tunnels

Basic Syntax

Examples

How Reverse Tunnels Work

Use Cases

Multiple Tunnels

Tunnel Syntax Reference

Format Options

Bind Addresses

Tunnel Persistence

Environment Variable Forwarding

Troubleshooting

Best Practices

Next Steps