SSH Settings

An SSH connection to an OpenVMS machine is required for syncing source code files, building, running and debugging projects. Depending on the type of configuration, SSH connection settings can be edited either in the vmssoftware.ssh-helper-settings.json file located in /.vscode directory or via Visual Studio Code settings page.

SSH Settings Template

{
    "connection": {
        "host": "",
        "keyFile": "",
        "password": "",
        "port": 22,
        "username": "",
        "skipSignatureVerification": false,
    },
    "host-collection": {
        "hosts": []
    },
    "timeouts": {
        "cmdTimeout": 0,
        "feedbackTimeout": 0,
        "welcomeTimeout": 0
    },
    "terminal": {
        "command": "ssh -oHostKeyAlgorithms=+ssh-dss ${keyFile?-i ${keyFile}} ${username?${username}@}${host}"
    }
}

Connection

The connection section sets the current connection details.

• Host - IP-address or name of OpenVMS machine. It also can refer to the label of a connection specified in host-collection section - should be enclosed in angle brackets (<hostname>). In that

case, all other fields are ignored.

• Port - The port number to use for the SSH connection. Default is 22.
• Username - User account that will be used for the SSH connection.
• Password - User password that will be used for the SSH connection.. If it is omitted a password input box will be shown on connection attempt.
• Key File - Path to SSH private key file. How to configure connection using SSH key see SSH public key authentication on OpenVMS
• skipSignatureVerification - Skip signature verification. Set it to 'true' if an error 'Handshake failed: signature verification failed' occurs.

Required fields to connect:

1. Host
2. Username

To provide security user may use one of two ways:

1. Key File
2. Password

If Key File is empty, Password will be used. If Password is empty too a password input box will be shown on connection attempt.

Host Collection

If you need to connect to different servers when working on your project, it makes sense to list all the required connections and then just pick the one that you need by using its label as the host name in the connection section.

NOTE: If you use VSC type of configuration, you will not be able to specify host collection in UI. Instead, you need to click "Edit in settings.json" and specify them in the settings.json file. 

To add new host into collection do the following:

• Copy whole content of {...} from connection into host-collection->hosts
• Add field label
• Adjust fields for this new host in collection
• Write <label> into host field in connection to use this new host as default

For example:

{
    "connection": {
        "host": "<First>",
        "keyFile": "",
        "password": "",
        "port": 22,
        "username": "",
        "skipSignatureVerification": false
    },
    "host-collection": {
        "hosts": [
            {
                "host": "1.1.1.1",
                "keyFile": "",
                "password": "pass",
                "port": 22,
                "username": "user",
                "skipSignatureVerification": true,
                "label": "First"
            }
        ]
    },
    "timeouts": {
        "cmdTimeout": 0,
        "feedbackTimeout": 0,
        "welcomeTimeout": 0
    },
    "terminal": {
        "command": "ssh -oHostKeyAlgorithms=+ssh-dss ${keyFile?-i ${keyFile}} ${username?${username}@}${host}"
    }
}

Timeouts

Specifies SSH connection timesouts.

• Cmd Timeout - Timeout for command response. If a command is sent to the OpenVMS system and the OpenVMS system does not a send response for the specified period of time, it will be considered as rejected.
• Feedback Timeout - If the SSH connection does not send feedback for this period, the specified password will be considered as invalid.
• Welcome Timeout - If the SSH shell prompt is not received within this period of time, the shell will be closed.

NOTE: Value "0" means, that timeout is not used. 

WARN: Do not change timeout settings unless necessary.

Terminal

Specifies command to start SSH shell in VS Code integrated terminal.

• Command - command to start SSH shell. It is possible to insert variables into command. The syntax is: ${variable} or ${varable?<text if variable isn't empty>}. Where variable can be following: host, port, username, password and keyFile.

NOTE: password may come from settings or if user entered it in UI prompt. Passwords entered in terminal aren't saved.