Skip to main content

Connecting to an SSP system

An SSP system may require SSH tunnels before you can connect to its services or deploy from VS Code. This page compares the available approaches for parallel operation on Windows. The SSP system must be running, and you need access to it and an SSH key authorized for the system.

Choose a tunnel method​

MethodUse with VS Code
Designer tunnelsOpen the database tunnel in the Designer and enable JDBC hostname resolution in ADITO Standalone Tools. VS Code can then use the tunnel for the connection check and deployment.
SSP administrator tunnel scriptThe script opens tunnels and updates the Windows hosts file. The system was reachable from VS Code in the tested setup.
SSP Batch Tunnel (SSH Key)This Windows batch file opens tunnels. Deployment with the new JDBC hostname resolution has not yet been verified for this method.
ADITO Tunnel toolThis separately maintained tool requires administrator privileges on all supported operating systems; connection errors may occur.
Manual OpenSSH forwardingOpen individual tunnels in the VS Code terminal without editing the hosts file. This approach is error-prone and requires manual connection and hostname configuration.
Custom tunnel scriptA custom SSH forwarding script and hosts entries can be used, including for a shared Windows machine. See dedicated loopback addresses.

The following instructions describe the tested Windows workflow. SSH key and agent requirements depend on the tunnel method; consult its documentation.


Use Designer tunnels​

  1. Download the tunnel and server configurations from the SSP and associate them with the Designer system. Alternatively, use Link to Cloud System. This setup is required once per system.
  2. Open the project in the Designer and VS Code.
  3. Open the database tunnel, or all tunnels, in the Designer. See Open the database tunnel.
  4. In VS Code, create a liquibase.properties connection file from the server configuration, if you have not already done so. See Create Data Alias liquibase.properties files and Create SYSTEMALIAS liquibase.properties files.
  5. In VS Code, ensure aditoStandaloneTools.resolveJDBCHostnameToIP is enabled. It is enabled by default. Open Preferences: Open Settings (UI) from the Command Palette and search for the setting name.
  6. In Deployment Overview, select Revalidate DB connections, then start the deployment workflow once the system is available. Keep the Designer tunnel open during the deploy.

The extension resolves the JDBC hostname using the system resolver and, if necessary, the Designer's hosts file. It does not modify the system hosts file or open the tunnel. See Use a Designer tunnel for deployment for details and troubleshooting.


Use the SSP administrator tunnel script​

  1. Download the Windows tunnel script from the SSP system.
  2. Start the downloaded batch file. It creates a PowerShell script and prompts for administrator credentials.
  3. Keep the tunnels open while using VS Code. Configure the connection file if necessary, then follow the deployment workflow.
  4. Stop the script normally when you have finished.
warning

The script modifies C:\Windows\System32\drivers\etc\hosts. A normal shutdown removes its entries, but entries from earlier runs can remain. If connections behave unexpectedly, inspect the hosts file. A backup may be available at C:\Windows\System32\drivers\etc\hosts.bak; compare it with the current file before using it, because restoring it can discard later changes.


Use Batch Tunnel (SSH Key)​

In the SSP system, download Tunnel → Batch Tunnel (SSH Key) and run the batch file. This option is available for Windows. In the earlier test, VS Code deployment could not resolve the hostname. This method has not yet been retested with the new JDBC hostname resolution; whether it works depends on how the batch tunnel makes its hostname mappings available.


Use ADITO Tunnel​

The separately maintained ADITO Tunnel tool is another option. It requires administrator privileges on all supported operating systems. Connection errors may occur; consult the tool's README for setup and troubleshooting.


Use manual OpenSSH forwarding​

As a workaround, you can open an SSH tunnel from the VS Code terminal using OpenSSH. This normally does not require administrator rights on Windows if you use an available local port and do not change the system hosts file. For example, the following command forwards one database port:

ssh -N -o ExitOnForwardFailure=yes -L 127.0.0.1:13306:DB_HOST:3306 -p SSH_PORT SSH_USER@SSH_GATEWAY

Replace DB_HOST, 3306, SSH_PORT, SSH_USER, and SSH_GATEWAY with the values from your SSP tunnel configuration. Choose an available local port in place of 13306. The database is then accessible through 127.0.0.1:13306 while the command remains running. Press Ctrl+C in the terminal to close the tunnel.

warning

This workaround is error-prone: each required service needs the correct forwarding configuration, and the command does not resolve SSP hostnames for the deploy tool. Connection settings may need manual changes, and additional workarounds may be needed for services that require their original hostnames. This approach has not been verified for a complete VS Code deployment.