Tunnel Please

A lightweight SSH-based tunnel server

Features

• SSH interactive session with real-time command handling
• Custom subdomain management for HTTP tunnels
• Dual protocol support: HTTP and TCP tunnels
• Real-time connection monitoring

Requirements

• Go 1.18 or higher
• Valid domain name for subdomain routing

Environment Variables

The following environment variables can be configured in the .env file:

Variable	Description	Default	Required
DOMAIN	Domain name for subdomain routing	localhost	No
FRONTEND_URL	URL for the frontend dashboard/landing page	https://<DOMAIN>	No
PORT	SSH server port	2200	No
HTTP_PORT	HTTP server port	8080	No
HTTPS_PORT	HTTPS server port	8443	No
KEY_LOC	Path to the private key file	certs/privkey.pem	No
TLS_ENABLED	Enable TLS/HTTPS	false	No
TLS_REDIRECT	Redirect HTTP to HTTPS	false	No
TLS_STORAGE_PATH	Path to store TLS certificates	certs/tls/	No
ACME_EMAIL	Email for Let's Encrypt registration	admin@<DOMAIN>	No
CF_API_TOKEN	Cloudflare API token for DNS-01 challenge	-	Yes (if auto-cert)
ACME_STAGING	Use Let's Encrypt staging server	false	No
CORS_LIST	Comma-separated list of allowed CORS origins	-	No
ALLOWED_PORTS	Port range for TCP tunnels (e.g., 40000-41000)	40000-41000	No
BUFFER_SIZE	Buffer size for io.Copy operations in bytes (4096-1048576)	32768	No
MAX_HEADER_SIZE	Maximum size of HTTP headers in bytes (4096-131072)	4096	No
PPROF_ENABLED	Enable pprof profiling server	false	No
PPROF_PORT	Port for pprof server	6060	No
MODE	Runtime mode: standalone or node	standalone	No
GRPC_ADDRESS	gRPC server address/host used in node mode	localhost	No
GRPC_PORT	gRPC server port used in node mode	8080	No
NODE_TOKEN	Authentication token sent to controller in node mode	-	Yes (node mode)

Note: All environment variables now use UPPERCASE naming. The application includes sensible defaults for all variables, so you can run it without a .env file for basic functionality.

Docker Deployment

Three Docker Compose configurations are available for different deployment scenarios. Each configuration uses the image git.fossy.my.id/bagas/tunnel-please:latest.

Configuration Options

1. Root with Host Networking (RECOMMENDED)

File: docker-compose.root.yml

Advantages:

• Full TCP port forwarding support (ports 40000-41000)
• Direct binding to privileged ports (80, 443, 2200)
• Best performance with no NAT overhead
• Maximum flexibility for all tunnel types
• No port mapping limitations

Use Case: Production deployments where you need unrestricted TCP forwarding and maximum performance.

Deploy:

docker-compose -f docker-compose.root.yml up -d

2. Standard (HTTP/HTTPS Only)

File: docker-compose.standard.yml

Advantages:

• Runs with unprivileged user (more secure)
• Standard port mappings (2200, 80, 443)
• Simple and predictable networking
• TCP port forwarding disabled (ALLOWED_PORTS=none)

Use Case: Deployments where you only need HTTP/HTTPS tunneling without custom TCP port forwarding.

Deploy:

docker-compose -f docker-compose.standard.yml up -d

3. Limited TCP Forwarding

File: docker-compose.tcp.yml

Advantages:

• Runs with unprivileged user (more secure)
• Standard port mappings (2200, 80, 443)
• Limited TCP forwarding (ports 30000-31000)
• Controlled port range exposure

Use Case: Deployments where you need both HTTP/HTTPS tunneling and limited TCP forwarding within a specific port range.

Deploy:

docker-compose -f docker-compose.tcp.yml up -d

Quick Start

1. Choose your configuration based on your requirements
2. Edit the environment variables in the chosen compose file:
   • DOMAIN: Your domain name (e.g., example.com)
   • ACME_EMAIL: Your email for Let's Encrypt
   • CF_API_TOKEN: Your Cloudflare API token (if using automatic TLS)
3. Deploy:

   docker-compose -f docker-compose.root.yml up -d
   

4. Check logs:

   docker-compose -f docker-compose.root.yml logs -f
   

5. Stop the service:

   docker-compose -f docker-compose.root.yml down
   

Recommendation

Use docker-compose.root.yml for production deployments if you need:

• Full TCP port forwarding capabilities
• Any port range configuration
• Direct port binding without mapping overhead
• Maximum performance and flexibility

This is the recommended configuration for most use cases as it provides the complete feature set without limitations.

Contributing

Contributions are welcome!

If you'd like to contribute to this project, please follow the workflow below:

1. Fork the repository
2. Create a new branch for your changes
3. Commit and push your updates
4. Open a Pull Request targeting the staging branch
5. Clearly describe your changes and the reasoning behind them

License

This project is licensed under the Attribution-NonCommercial-NoDerivatives 4.0 International (CC BY-NC-ND 4.0) license.

Author

Bagas (fossyy)

• Website: fossy.my.id
• GitHub: @fossyy