Editing 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]]