SSH Port Forwarding:Management - Revision history

Josh: Major update - troubleshooting guide: SSH Port Forwarding Management (32 sections)

2026-01-01T13:44:36Z

Major update - troubleshooting guide: SSH Port Forwarding Management (32 sections)

← Older revision		Revision as of 13:44, 1 January 2026
Line 1:		Line 1:
	~~= SSH Port Forwarding Management =~~

	This document describes how to manage SSH port forwards.		This document describes how to manage SSH port forwards.

Line 11:		Line 9:
	<pre class="lang-bash">		<pre class="lang-bash">
	sudo ssh-port-forward-manager.sh list		sudo ssh-port-forward-manager.sh list
	= or =		==== or ====
	sudo ssh-forward list		sudo ssh-forward list
	</pre>		</pre>
Line 25:		Line 23:
	'''Example:'''		'''Example:'''
	<pre class="lang-bash">		<pre class="lang-bash">
	= Add SSH forward for a Raspberry Pi at 10.8.0.3 on external port 22223 =		==== Add SSH forward for a Raspberry Pi at 10.8.0.3 on external port 22223 ====
	sudo ssh-forward add raspberrypi 22223 10.8.0.3 22		sudo ssh-forward add raspberrypi 22223 10.8.0.3 22

	= Add SSH forward for a server using non-standard SSH port =		== Add SSH forward for a server using non-standard SSH port ==
	sudo ssh-forward add server 22224 10.8.0.4 2222		sudo ssh-forward add server 22224 10.8.0.4 2222
	</pre>		</pre>
Line 79:		Line 77:
	=== Prerequisites ===		=== Prerequisites ===

	= '''Device must be connected to OpenVPN VPN''' =		==== '''Device must be connected to OpenVPN VPN''' ====
	* Device should have a <code>.ovpn</code> configuration file		* Device should have a <code>.ovpn</code> configuration file

Line 86:		Line 84:
	* Verify connection: <code>ping <VPN_IP></code> from VPS		* Verify connection: <code>ping <VPN_IP></code> from VPS

	= '''Device must have SSH enabled''' =		== '''Device must have SSH enabled''' ==
	* SSH service should be running on the device		* SSH service should be running on the device

	* SSH should be accessible from the VPN network		* SSH should be accessible from the VPN network

	= '''Choose an external port''' =		== '''Choose an external port''' ==
	* Must not conflict with existing services		* Must not conflict with existing services

Line 100:		Line 98:
	=== Step-by-Step Guide ===		=== Step-by-Step Guide ===

	= '''Verify device is on VPN:''' =		==== '''Verify device is on VPN:''' ====
	<pre class="lang-bash">		<pre class="lang-bash">
	# Check VPN connection		=== Check VPN connection ===
	cat /etc/openvpn/server/ipp.txt \| grep <device_name>		cat /etc/openvpn/server/ipp.txt \| grep <device_name>

	# Ping device		=== Ping device ===
	ping -c 2 <VPN_IP>		ping -c 2 <VPN_IP>
	</pre>		</pre>

	= '''Test direct SSH connection:''' =		== '''Test direct SSH connection:''' ==
	<pre class="lang-bash">		<pre class="lang-bash">
	# From VPS, test SSH to device via VPN		=== From VPS, test SSH to device via VPN ===
	ssh -o ConnectTimeout=5 user@<VPN_IP>		ssh -o ConnectTimeout=5 user@<VPN_IP>
	</pre>		</pre>

	= '''Add the port forward:''' =		== '''Add the port forward:''' ==
	<pre class="lang-bash">		<pre class="lang-bash">
	sudo ssh-forward add <device_name> <external_port> <VPN_IP> [ssh_port]		sudo ssh-forward add <device_name> <external_port> <VPN_IP> [ssh_port]
	</pre>		</pre>

	= '''Verify the forward:''' =		== '''Verify the forward:''' ==
	<pre class="lang-bash">		<pre class="lang-bash">
	# List all forwards		=== List all forwards ===
	sudo ssh-forward list		sudo ssh-forward list

	# Test from external location		=== Test from external location ===
	ssh -p <external_port> user@<VPS_PUBLIC_IP>		ssh -p <external_port> user@<VPS_PUBLIC_IP>
	</pre>		</pre>

	= '''Configure IONOS firewall (if applicable):''' =		== '''Configure IONOS firewall (if applicable):''' ==
	* Log in to IONOS Cloud Panel: https://dcd.ionos.com/		* Log in to IONOS Cloud Panel: https://dcd.ionos.com/

Line 141:		Line 139:

	<pre class="lang-bash">		<pre class="lang-bash">
	= 1. Verify Raspberry Pi is on VPN (assume it gets 10.8.0.3) =		==== 1. Verify Raspberry Pi is on VPN (assume it gets 10.8.0.3) ====
	ping -c 2 10.8.0.3		ping -c 2 10.8.0.3

	= 2. Test direct SSH (using root for Cursor compatibility) =		== 2. Test direct SSH (using root for Cursor compatibility) ==
	ssh root@10.8.0.3		ssh root@10.8.0.3

	= 3. Add port forward =		== 3. Add port forward ==
	sudo ssh-forward add raspberrypi 22223 10.8.0.3 22		sudo ssh-forward add raspberrypi 22223 10.8.0.3 22

	= 4. Verify =		== 4. Verify ==
	sudo ssh-forward list		sudo ssh-forward list

	= 5. Test from external location =		== 5. Test from external location ==
	ssh -p 22223 root@87.106.61.62		ssh -p 22223 root@87.106.61.62
	</pre>		</pre>

Josh: Content added - troubleshooting guide: SSH Port Forwarding Management (11 sections)

2026-01-01T13:28:10Z

Content added - troubleshooting guide: SSH Port Forwarding Management (11 sections)

← Older revision		Revision as of 13:28, 1 January 2026
Line 33:		Line 33:

	'''Parameters:'''		'''Parameters:'''
	'' <code>name</code>: Unique name for the device		* <code>name</code>: Unique name for the device
	'' <code>external_port</code>: Port on VPS (must not be in use)
	'' <code>vpn_ip</code>: Device's VPN IP address		* <code>external_port</code>: Port on VPS (must not be in use)
	'' <code>ssh_port</code>: SSH port on device (optional, defaults to 22)
			* <code>vpn_ip</code>: Device's VPN IP address

			* <code>ssh_port</code>: SSH port on device (optional, defaults to 22)

	=== Remove a Port Forward ===		=== Remove a Port Forward ===
Line 58:		Line 61:

	This reads the configuration file and applies all port forwards. Useful after:		This reads the configuration file and applies all port forwards. Useful after:
	'' Manual edits to the configuration file		* Manual edits to the configuration file
	'' System reboot (automatically done by iptables-restore.sh)
	'' VPN restart		* System reboot (automatically done by iptables-restore.sh)

			* VPN restart

	=== Save Current Rules ===		=== Save Current Rules ===
Line 75:		Line 80:

	= '''Device must be connected to OpenVPN VPN''' =		= '''Device must be connected to OpenVPN VPN''' =
	'' Device should have a <code>.ovpn</code> configuration file		* Device should have a <code>.ovpn</code> configuration file
	'' Device should be connected and have a VPN IP address
	'' Verify connection: <code>ping <VPN_IP></code> from VPS		* Device should be connected and have a VPN IP address

			* Verify connection: <code>ping <VPN_IP></code> from VPS

	= '''Device must have SSH enabled''' =		= '''Device must have SSH enabled''' =
	'' SSH service should be running on the device		* SSH service should be running on the device
	'' SSH should be accessible from the VPN network
			* SSH should be accessible from the VPN network

	= '''Choose an external port''' =		= '''Choose an external port''' =
	'' Must not conflict with existing services		* Must not conflict with existing services
	'' Recommended range: 22222-22299 for SSH forwards
	'' Check availability: <code>sudo ssh-forward list</code>		* Recommended range: 22222-22299 for SSH forwards

			* Check availability: <code>sudo ssh-forward list</code>

	=== Step-by-Step Guide ===		=== Step-by-Step Guide ===
Line 120:		Line 130:

	= '''Configure IONOS firewall (if applicable):''' =		= '''Configure IONOS firewall (if applicable):''' =
	'' Log in to IONOS Cloud Panel: https://dcd.ionos.com/		* Log in to IONOS Cloud Panel: https://dcd.ionos.com/
	'' Navigate to: Server & Cloud → Servers → [Your VPS] → Firewall
	'' Add rule: TCP port <code><external_port></code> → Allow		* Navigate to: Server & Cloud → Servers → [Your VPS] → Firewall
	'' Set appropriate priority
			* Add rule: TCP port <code><external_port></code> → Allow

			* Set appropriate priority

	=== Example: Adding a Raspberry Pi ===		=== Example: Adding a Raspberry Pi ===
Line 146:		Line 159:
	== Related Documentation ==		== Related Documentation ==

	'' [[Documentation:Overview](Overview\|- System architecture		* [[Documentation:Overview](Overview\|- System architecture
	'' [Configuration]])(configuration.md) - Configuration file format
	'' [Best Practices](best-practices.md) - Security and best practices		* [Configuration]])(configuration.md) - Configuration file format

			* [Best Practices](best-practices.md) - Security and best practices

	* [[Troubleshooting:Port Forwarding Troubleshooting\|Troubleshooting]] - Troubleshooting guide		* [[Troubleshooting:Port Forwarding Troubleshooting\|Troubleshooting]] - Troubleshooting guide

	[[Category:Documentation]]		[[Category:Documentation]]
	[[Category:Documentation/SSH Port Forwarding]]		[[Category:Documentation/SSH Port Forwarding]]

Josh: Added troubleshooting guide: SSH Port Forwarding Management

2026-01-01T13:15:53Z

Added troubleshooting guide: SSH Port Forwarding Management

New page

= SSH Port Forwarding Management =

This document describes how to manage SSH port forwards.

== Management Script Usage ==

The management script is available at <code>/usr/local/bin/ssh-port-forward-manager.sh</code> or via the alias <code>ssh-forward</code>.

=== List All Port Forwards ===

<pre class="lang-bash">
sudo ssh-port-forward-manager.sh list
= or =
sudo ssh-forward list
</pre>

This displays all configured port forwards with their status (Active/Inactive).

=== Add a New Port Forward ===

<pre class="lang-bash">
sudo ssh-port-forward-manager.sh add <name> <external_port> <vpn_ip> [ssh_port]
</pre>

'''Example:'''
<pre class="lang-bash">
= Add SSH forward for a Raspberry Pi at 10.8.0.3 on external port 22223 =
sudo ssh-forward add raspberrypi 22223 10.8.0.3 22

= Add SSH forward for a server using non-standard SSH port =
sudo ssh-forward add server 22224 10.8.0.4 2222
</pre>

'''Parameters:'''
'' <code>name</code>: Unique name for the device
'' <code>external_port</code>: Port on VPS (must not be in use)
'' <code>vpn_ip</code>: Device's VPN IP address
'' <code>ssh_port</code>: SSH port on device (optional, defaults to 22)

=== Remove a Port Forward ===

<pre class="lang-bash">
sudo ssh-port-forward-manager.sh remove <name>
</pre>

'''Example:'''
<pre class="lang-bash">
sudo ssh-forward remove raspberrypi
</pre>

This removes the port forward from both the configuration file and iptables rules.

=== Apply All Port Forwards ===

<pre class="lang-bash">
sudo ssh-port-forward-manager.sh apply
</pre>

This reads the configuration file and applies all port forwards. Useful after:
'' Manual edits to the configuration file
'' System reboot (automatically done by iptables-restore.sh)
'' VPN restart

=== Save Current Rules ===

<pre class="lang-bash">
sudo ssh-port-forward-manager.sh save
</pre>

Saves current iptables rules to <code>/etc/iptables/rules.v4</code> for persistence.

== Adding a New Device ==

=== Prerequisites ===

= '''Device must be connected to OpenVPN VPN''' =
'' Device should have a <code>.ovpn</code> configuration file
'' Device should be connected and have a VPN IP address
'' Verify connection: <code>ping <VPN_IP></code> from VPS

= '''Device must have SSH enabled''' =
'' SSH service should be running on the device
'' SSH should be accessible from the VPN network

= '''Choose an external port''' =
'' Must not conflict with existing services
'' Recommended range: 22222-22299 for SSH forwards
'' Check availability: <code>sudo ssh-forward list</code>

=== Step-by-Step Guide ===

= '''Verify device is on VPN:''' =
<pre class="lang-bash">
# Check VPN connection
cat /etc/openvpn/server/ipp.txt | grep <device_name>

# Ping device
ping -c 2 <VPN_IP>
</pre>

= '''Test direct SSH connection:''' =
<pre class="lang-bash">
# From VPS, test SSH to device via VPN
ssh -o ConnectTimeout=5 user@<VPN_IP>
</pre>

= '''Add the port forward:''' =
<pre class="lang-bash">
sudo ssh-forward add <device_name> <external_port> <VPN_IP> [ssh_port]
</pre>

= '''Verify the forward:''' =
<pre class="lang-bash">
# List all forwards
sudo ssh-forward list

# Test from external location
ssh -p <external_port> user@<VPS_PUBLIC_IP>
</pre>

= '''Configure IONOS firewall (if applicable):''' =
'' Log in to IONOS Cloud Panel: https://dcd.ionos.com/
'' Navigate to: Server & Cloud → Servers → [Your VPS] → Firewall
'' Add rule: TCP port <code><external_port></code> → Allow
'' Set appropriate priority

=== Example: Adding a Raspberry Pi ===

<pre class="lang-bash">
= 1. Verify Raspberry Pi is on VPN (assume it gets 10.8.0.3) =
ping -c 2 10.8.0.3

= 2. Test direct SSH (using root for Cursor compatibility) =
ssh root@10.8.0.3

= 3. Add port forward =
sudo ssh-forward add raspberrypi 22223 10.8.0.3 22

= 4. Verify =
sudo ssh-forward list

= 5. Test from external location =
ssh -p 22223 root@87.106.61.62
</pre>

== Related Documentation ==

'' [[Documentation:Overview](Overview|- System architecture
'' [Configuration]])(configuration.md) - Configuration file format
'' [Best Practices](best-practices.md) - Security and best practices
* [[Troubleshooting:Port Forwarding Troubleshooting|Troubleshooting]] - Troubleshooting guide

[[Category:Documentation]]
[[Category:Documentation/SSH Port Forwarding]]