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
| Method | Use with VS Code |
|---|---|
| Designer tunnels | Open 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 script | The 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 tool | This separately maintained tool requires administrator privileges on all supported operating systems; connection errors may occur. |
| Manual OpenSSH forwarding | Open 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 script | A 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
- 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.
- Open the project in the Designer and VS Code.
- Open the database tunnel, or all tunnels, in the Designer. See Open the database tunnel.
- In VS Code, create a
liquibase.propertiesconnection 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. - In VS Code, ensure
aditoStandaloneTools.resolveJDBCHostnameToIPis enabled. It is enabled by default. Open Preferences: Open Settings (UI) from the Command Palette and search for the setting name. - 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
- Download the Windows tunnel script from the SSP system.
- Start the downloaded batch file. It creates a PowerShell script and prompts for administrator credentials.
- Keep the tunnels open while using VS Code. Configure the connection file if necessary, then follow the deployment workflow.
- Stop the script normally when you have finished.
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.
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.