DEV Community

Shrijith Venkatramana
Shrijith Venkatramana

Posted on

Tunnel Your Way to Remote Servers: Mastering SSH Tunneling and SOCKS5 for Localhost Access

#programming #beginners #productivity #tutorial

Hi there! I'm Shrijith Venkatrama, founder of Hexmos. Right now, I’m building LiveAPI, a first of its kind tool for helping you automatically index API endpoints across all your repositories. LiveAPI helps you discover, understand and use APIs in large tech infrastructures with ease.

SSH tunneling and SOCKS5 proxies are powerful tools for developers who need to access services running on remote servers as if they were on their local machine. Whether you're debugging a web app, connecting to a database, or testing APIs, these techniques can save you time and headaches. In this guide, I'll walk you through the nuts and bolts of setting up SSH tunneling and SOCKS5 proxies to access remote services on your localhost. We'll cover practical examples, configurations, and some gotchas to watch out for.

This post assumes you're comfortable with basic terminal commands and have SSH access to a remote server. Let's dive in.

Why SSH Tunneling and SOCKS5 Matter for Developers

When you need to interact with a service (like a database or web server) running on a remote machine, firewalls or restricted access can make it tricky. SSH tunneling creates a secure "tunnel" between your local machine and the remote server, letting you access services as if they were running locally. SOCKS5, on the other hand, is a proxy protocol that routes traffic through the remote server, giving you flexibility for dynamic or multi-service access.

These tools are lifesavers for:

  • Accessing internal tools behind a firewall.
  • Debugging apps hosted on a remote server.
  • Securely connecting to databases or APIs without exposing them to the public internet.

Let’s explore how to set these up with clear examples.

Understanding SSH Tunneling Basics

SSH tunneling forwards traffic from a local port to a remote server (or even another machine via the remote server). There are three types of SSH tunnels:

  • Local forwarding: Connect a local port to a remote service.
  • Remote forwarding: Expose a local service to the remote server.
  • Dynamic forwarding: Create a SOCKS proxy for flexible routing.

For this post, we’ll focus on local forwarding and dynamic forwarding (SOCKS5) since they’re most common for accessing remote services.

To create a tunnel, you use the ssh command with specific flags. The syntax for local forwarding is:

ssh -L local_port:remote_host:remote_port user@server
Enter fullscreen mode Exit fullscreen mode

This binds local_port on your machine to remote_host:remote_port via the SSH server.

Resource: OpenSSH Documentation for detailed SSH command options.

Setting Up Local SSH Tunneling for a Remote Web Service

Let’s say you have a web server running on a remote machine at 192.168.1.100:8080, but it’s only accessible from the SSH server (server.example.com). You want to access it on localhost:8080.

Here’s the command to set up a local tunnel:

# Tunnel localhost:8080 to 192.168.1.100:8080 via server.example.com
ssh -L 8080:192.168.1.100:8080 user@server.example.com
# Output: Establishes SSH connection and keeps it open. No explicit output unless errors occur.
Enter fullscreen mode Exit fullscreen mode

Now, open your browser and go to http://localhost:8080. You’ll see the web server as if it’s running locally. The traffic flows securely through the SSH connection.

Key points:

  • The tunnel stays active as long as the SSH session is open.
  • Use -f -N flags to run the tunnel in the background without executing a remote command: 
  ssh -f -N -L 8080:192.168.1.100:8080 user@server.example.com
  # Output: No output; runs in background. Use `ps aux | grep ssh` to verify.
Enter fullscreen mode Exit fullscreen mode
  • If 192.168.1.100 is the SSH server itself, use localhost as remote_host.

Connecting to a Remote Database with SSH Tunneling

Databases like MySQL or PostgreSQL often run on remote servers with restricted access. Let’s tunnel a PostgreSQL database running on db.example.com:5432 through server.example.com.

Run this command:

# Tunnel localhost:5432 to db.example.com:5432
ssh -L 5432:db.example.com:5432 user@server.example.com
# Output: Establishes SSH connection. No output unless errors occur.
Enter fullscreen mode Exit fullscreen mode

Now, configure your local database client (e.g., psql or DBeaver) to connect to localhost:5432. The traffic is forwarded to db.example.com:5432 securely.

Example with psql:

# Connect to the database via the tunnel
psql -h localhost -p 5432 -U db_user -d my_database
# Output: Connects to the database if credentials are correct; otherwise, shows an error like "connection refused."
Enter fullscreen mode Exit fullscreen mode

Gotcha: Ensure the port (e.g., 5432) isn’t already in use on your local machine. If it is, choose a different local port (e.g., 5433).

Resource: PostgreSQL Documentation for client connection details.

Exploring SOCKS5 for Dynamic Port Forwarding

Local forwarding is great for single services, but what if you need to access multiple services or don’t know the ports in advance? That’s where SOCKS5 comes in. It creates a dynamic proxy, letting you route traffic to any host/port through the SSH server.

To set up a SOCKS5 proxy:

# Create a SOCKS5 proxy on localhost:1080
ssh -D 1080 user@server.example.com
# Output: Establishes SSH connection. No output unless errors occur.
Enter fullscreen mode Exit fullscreen mode

This binds localhost:1080 as a SOCKS5 proxy. You configure your browser or app to use this proxy, and it routes traffic through server.example.com.

Key points:

  • Use -f -N for background mode: 
  ssh -f -N -D 1080 user@server.example.com
  # Output: No output; runs in background.
Enter fullscreen mode Exit fullscreen mode
  • SOCKS5 is protocol-agnostic, so it works for HTTP, HTTPS, or even FTP.

Configuring Your Browser for SOCKS5

To use the SOCKS5 proxy, configure your browser to route traffic through localhost:1080. Here’s how to do it in Firefox:

  1. Go to Settings > General > Network Settings.
  2. Select Manual proxy configuration.
  3. Set SOCKS Host to localhost and Port to 1080.
  4. Choose SOCKS v5.
  5. Click OK.

Now, browsing to http://192.168.1.100:8080 routes traffic through the SSH server. You can access any service the server can reach.

Example: If server.example.com can access an internal tool at http://internal.app:3000, you can visit it in your browser without additional tunnels.

Resource: Firefox Proxy Settings for detailed instructions.

Browser SOCKS5 Support Configuration Path
Firefox Yes Settings > General > Network Settings
Chrome Yes Use system proxy settings or extensions like Proxy Switcher
Safari Yes System Preferences > Network > Advanced > Proxies

Troubleshooting Common Issues

Tunneling can fail for various reasons. Here are common problems and fixes:

  • Port already in use: Check if the local port is occupied with lsof -i :8080. Use a different port if needed.
  • Connection refused: Ensure the remote service is running and accessible from the SSH server. Test with telnet remote_host remote_port on the server.
  • SSH connection drops: Use ServerAliveInterval in your SSH config to keep connections alive: 
  # ~/.ssh/config
  Host server.example.com
      HostName server.example.com
      User user
      ServerAliveInterval 60
  # Output: No output; applies to SSH connections to server.example.com.
Enter fullscreen mode Exit fullscreen mode
  • SOCKS5 not working: Verify your app supports SOCKS5 and isn’t bypassing the proxy for local addresses.

Resource: OpenSSH Config Guide for advanced SSH configurations.

Security Tips and Best Practices

SSH tunneling and SOCKS5 are secure, but misconfigurations can expose vulnerabilities. Here’s how to stay safe:

  • Use strong SSH keys: Avoid passwords; use key-based authentication with ssh-keygen and ~/.ssh/authorized_keys.
  • Restrict access: On the SSH server, limit which hosts/ports can be forwarded using PermitOpen in /etc/ssh/sshd_config: 
  # /etc/ssh/sshd_config on server
  PermitOpen 192.168.1.100:8080 db.example.com:5432
  # Output: No output; restricts forwarding to specified hosts/ports.
Enter fullscreen mode Exit fullscreen mode
  • Close unused tunnels: Kill background SSH processes with pkill -f "ssh -f -N".
  • Monitor traffic: Use tools like tcpdump or Wireshark on your local machine to verify traffic is encrypted.

Making Your Workflow Smoother with Aliases

Tunneling commands can get long. Simplify them with shell aliases or scripts. Add this to your ~/.bashrc or ~/.zshrc:

# ~/.bashrc or ~/.zshrc
alias db-tunnel="ssh -f -N -L 5432:db.example.com:5432 user@server.example.com"
alias socks5="ssh -f -N -D 1080 user@server.example.com"
# Output: No output; aliases available in new terminal sessions.
Enter fullscreen mode Exit fullscreen mode

Now, run db-tunnel or socks5 to start the tunnels. Restart your shell or run source ~/.bashrc to apply.

What’s Next for Your Tunneling Adventures

SSH tunneling and SOCKS5 are versatile tools that can streamline your development workflow. Start by experimenting with a single local tunnel for a web service or database. Once you’re comfortable, try SOCKS5 for more dynamic setups. Combine these with tools like tmux for persistent sessions or autossh for reliable connections.

For complex setups, consider learning about reverse tunneling for exposing local services or jump hosts for multi-hop SSH. These techniques build on what you’ve learned here and open up even more possibilities.

Keep your SSH keys secure, monitor your tunnels, and you’ll have a robust way to access remote services like they’re right on your machine.

Top comments (0)