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,
        "supportSetFileTime": true,
        "unzipCmd": "",
        "zipCmd": ""
        "algorithms": {
            "kex": [],
            "cipher": [],
            "serverHostKey": [],
            "hmac": [],
            "compress": []
        },
        "addConnectConfig": null,
    },
    "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 an OpenVMS machine or the label of a predefined connection from the host collection section

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.
• keyFile - Path to SSH private key file. For details on 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.
• supportSetFileTime - Set it to 'false' if SFTP server doesn't support setting file time, so shell command will be used for this.
• unzipCmd - Command to unzip file on VMS side. A pattern ${ZIPFILE} inside the command will be changed to the real name of ZIP file (the same as the name of the project).
• zipCmd - Command to zip listing files on VMS side. A pattern ${ZIPFILE} inside the command will be changed to the real name of ZIP file (the same as the name of the project). A pattern ${ADDFILE} will be changed to the mask of listing files. Note: the zip command will be executed for each entry in listing mask, so the command must append files to the ZIP file. For example: if listing mask is "*.lis,*.map", the command will be executed twice - in first for "*.lis" and in second for "*.map".
• algorithms - Optional. This allows you to explicitly override the default transport layer algorithms used for the connection. See https://www.npmjs.com/package/ssh2#client-methods and https://www.npmjs.com/package/ssh2-streams#ssh2stream-methods
• addConnectConfig - Optional. This allows you to explicitly override the default configuration used for the connection. See https://www.npmjs.com/package/ssh2#client-methods

Required fields are:

• host
• username

User may use either key file, agent or password to establish a connection:

• keyFile
• agent in addConnectConfig
• password

To use agent in the connection user must add it to the addConnectConfig block. Also one has to have pageant.exe file in ~/home/.vscode/extensions/vmssoftwareinc.vms-ide-X.X.XX/util/pageant.exe (place the version of vms-ide instead of X.X.XX). This file can be downloaded from https://github.com/mscdex/ssh2/blob/master/util/pagent.exe

If nothing is specified, user will be prompted to enter the password during the connection attempt.

Host Collection

If you need to connect to different servers when working on your project, it makes sense to create a list of required connections to be able to quickly connect to any of them. You can do this by adding all the required connections to the Host Collection list.

Adding a new host to collection

To add a new host to the collection:

1. Copy the ssh connection template to host-collection.hosts array:

"host-collection": {
    "hosts": [
        {
            "host": "",
            "keyFile": "",
            "password": "",
            "port": 22,
            "username": "",
            "skipSignatureVerification": false,
            "supportSetFileTime": true,
            "unzipCmd": "",
            "zipCmd": ""
            "algorithms": {
                "kex": [],
                "cipher": [],
                "serverHostKey": [],
                "hmac": [],
                "compress": []
            }
        }
    ]
}

2. Specify connection parameters

"host-collection": {
    "hosts": [
        {
            "label": "First",
            "host": "192.168.1.1",
            "password": "pass",
            "port": 22,
            "username": "user",
            "skipSignatureVerification": true,
            "supportSetFileTime": true,
            "unzipCmd": "unzip /restore=nodate /existing=new_version ${ZIPFILE}",
            "zipCmd": "zip ${ZIPFILE} [...]${ADDFILE}",
        }
    ]
}

3. Make sure that label parameter is set.

Selecting which connection to use

To use one of connections from the host collection section, copy the value of label and paste it in angle brackets (<label>) to the host field in the connection section.

Example

{
    "connection": {
        "host": "<MySSHConnection>",
        "keyFile": "",
        "password": "",
        "port": 22,
        "username": "",
        "skipSignatureVerification": false
    },
    "host-collection": {
        "hosts": [
            {
                "host": "10.10.6.1",
                "keyFile": "",
                "password": "myPassword",
                "port": 22,
                "username": "user",
                "skipSignatureVerification": true,
                "supportSetFileTime": true,
                "unzipCmd": "unzip /restore=nodate /existing=new_version ${ZIPFILE}",
                "zipCmd": "zip ${ZIPFILE} [...]${ADDFILE}",
                "label": "MySSHConnection"
            }
        ]
    }
}

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. 

Timeouts

You can define SSH connection timeouts in this section.

• cmdTimeout - 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.
• feedbackTimeout - If the SSH connection does not send feedback for the specified interval, the password will be considered as invalid.
• welcomeTimeout - If the SSH shell prompt is not received within this interval, the shell will be closed.

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

WARN: Do not change timeout settings unless necessary.

Example

"timeouts": {
    "cmdTimeout": 0,
    "feedbackTimeout": 0,
    "welcomeTimeout": 0
}

Terminal

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

• Command - command to start the shell.

NOTE: It is possible to use variables in the command. The syntax is: ${variable} or ${varable?<text if variable isn't empty>}. Supported variables: host, port, username, password, and keyFile.
NOTE: password may come from settings or UI prompt that is shown if the password is not specified in settings. Passwords entered in the terminal are not saved.

Example

"terminal": {
    "command": "ssh -oHostKeyAlgorithms=+ssh-dss ${keyFile?-i ${keyFile}} ${username?${username}@}${host}"
}

Video tutorial: VMS IDE 1 Starting a Project. In video "SSH Settings" shown at 1:45 - 2:39 time period.