Difference between revisions of "SSH Settings"

From VSI OpenVMS Wiki
Jump to: navigation, search
(Terminal)
(Connection)
 
(16 intermediate revisions by 4 users not shown)
Line 1: Line 1:
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.
+
An SSH connection to an OpenVMS machine is required for syncing source code files, building, running, and debugging projects. <br>
 +
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=
 
=SSH Settings Template=
Line 11: Line 12:
 
         "username": "",
 
         "username": "",
 
         "skipSignatureVerification": false,
 
         "skipSignatureVerification": false,
 +
        "supportSetFileTime": true,
 +
        "unzipCmd": "",
 +
        "zipCmd": ""
 +
        "algorithms": {
 +
            "kex": [],
 +
            "cipher": [],
 +
            "serverHostKey": [],
 +
            "hmac": [],
 +
            "compress": []
 +
        },
 +
        "addConnectConfig": null,
 
     },
 
     },
 
     "host-collection": {
 
     "host-collection": {
Line 27: Line 39:
  
 
=Connection=
 
=Connection=
The connection section sets the current connection details.
+
The '''connection''' section sets the current connection details.
* <code>'''Host'''</code> - 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  <code>(<hostname>)</code>. In that
+
* <code>'''host'''</code> - 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.  
 
case, all other fields are ignored.  
* <code>'''Port'''</code> - The port number to use for the SSH connection. Default is 22.
+
* <code>'''port'''</code> - The port number to use for the SSH connection. Default is 22.
* <code>'''Username'''</code> - User account that will be used for the SSH connection.
+
* <code>'''username'''</code> - User account that will be used for the SSH connection.
* <code>'''Password'''</code> - User password that will be used for the SSH connection.. If it is omitted a password input box will be shown on connection attempt.
+
* <code>'''password'''</code> - User password that will be used for the SSH connection. If it is omitted a password input box will be shown on connection attempt.
* <code>'''Key File'''</code> - Path to SSH private key file. How to configure connection using SSH key see [https://raymii.org/s/blog/SSH_public_key_authentication_on_OpenVMS.html SSH public key authentication on OpenVMS]
+
* <code>'''keyFile'''</code> - Path to SSH private key file. For details on how to configure connection using SSH key, see [https://raymii.org/s/blog/SSH_public_key_authentication_on_OpenVMS.html SSH public key authentication on OpenVMS]
 
* <code>'''skipSignatureVerification'''</code> - Skip signature verification. Set it to 'true' if an error 'Handshake failed: signature verification failed' occurs.
 
* <code>'''skipSignatureVerification'''</code> - Skip signature verification. Set it to 'true' if an error 'Handshake failed: signature verification failed' occurs.
 +
* <code>'''supportSetFileTime'''</code> - Set it to 'false' if SFTP server doesn't support setting file time, so shell command will be used for this.
 +
* <code>'''unzipCmd'''</code> - 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).
 +
* <code>'''zipCmd'''</code> - 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".
 +
* <code>'''algorithms'''</code> - 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
 +
* <code>'''addConnectConfig'''</code> - 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 to connect:  
+
Required fields are:  
# <code>'''Host'''</code>
+
* <code>'''host'''</code>
# <code>'''Username'''</code>
+
* <code>'''username'''</code>
  
To provide security user may use one of two ways:
+
User may use either key file, agent or password to establish a connection:
# <code>'''Key File'''</code>
+
* <code>'''keyFile'''</code>
# <code>'''Password'''</code>
+
* '''agent''' in <code>'''addConnectConfig'''</code>
 +
* <code>'''password'''</code>
  
If '''Key File''' is empty, '''Password''' will be used. If '''Password''' is empty too a password input box will be shown on connection attempt.
+
To use '''agent''' in the connection user must add it to the <code>'''addConnectConfig'''</code> 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=
 
=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.
+
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.  
'''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.  
+
You can do this by adding all the required connections to the '''Host Collection''' list.
  
[[File:Ssh collection hosts.png|Ssh collection hosts.png]]
+
=== Adding a new host to collection ===
 +
To add a new host to the collection:
 +
<ol>
 +
<li>Copy the ssh connection template to '''host-collection.hosts''' array:</li>
 +
<pre>"host-collection": {
 +
    "hosts": [
 +
        {
 +
            "host": "",
 +
            "keyFile": "",
 +
            "password": "",
 +
            "port": 22,
 +
            "username": "",
 +
            "skipSignatureVerification": false,
 +
            "supportSetFileTime": true,
 +
            "unzipCmd": "",
 +
            "zipCmd": ""
 +
            "algorithms": {
 +
                "kex": [],
 +
                "cipher": [],
 +
                "serverHostKey": [],
 +
                "hmac": [],
 +
                "compress": []
 +
            }
 +
        }
 +
    ]
 +
}</pre>
 +
<li>Specify connection parameters</li>
 +
<pre>"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}",
 +
        }
 +
    ]
 +
}</pre>
 +
<li>Make sure that '''label''' parameter is set.</li>
 +
</ol>
  
To add new host into collection do the following:
+
===Selecting which connection to use===
* Copy whole content of {...} from '''connection''' into '''host-collection'''->'''hosts'''
+
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.
* 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:
+
=== Example ===
 
<pre>
 
<pre>
 
{
 
{
 
     "connection": {
 
     "connection": {
         "host": "<First>",
+
         "host": "<MySSHConnection>",
 
         "keyFile": "",
 
         "keyFile": "",
 
         "password": "",
 
         "password": "",
Line 72: Line 132:
 
         "hosts": [
 
         "hosts": [
 
             {
 
             {
                 "host": "1.1.1.1",
+
                 "host": "10.10.6.1",
 
                 "keyFile": "",
 
                 "keyFile": "",
                 "password": "pass",
+
                 "password": "myPassword",
 
                 "port": 22,
 
                 "port": 22,
 
                 "username": "user",
 
                 "username": "user",
 
                 "skipSignatureVerification": true,
 
                 "skipSignatureVerification": true,
                 "label": "First"
+
                "supportSetFileTime": true,
 +
                "unzipCmd": "unzip /restore=nodate /existing=new_version ${ZIPFILE}",
 +
                "zipCmd": "zip ${ZIPFILE} [...]${ADDFILE}",
 +
                 "label": "MySSHConnection"
 
             }
 
             }
 
         ]
 
         ]
    },
 
    "timeouts": {
 
        "cmdTimeout": 0,
 
        "feedbackTimeout": 0,
 
        "welcomeTimeout": 0
 
    },
 
    "terminal": {
 
        "command": "ssh -oHostKeyAlgorithms=+ssh-dss ${keyFile?-i ${keyFile}} ${username?${username}@}${host}"
 
 
     }
 
     }
 
}
 
}
 
</pre>
 
</pre>
 +
 +
'''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.
 +
 +
[[File:Ssh collection hosts.png|Ssh collection hosts.png]]
  
 
=Timeouts=
 
=Timeouts=
Specifies SSH connection timesouts.
+
You can define SSH connection timeouts in this section.
* <code>'''Cmd Timeout'''</code> - 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.
+
* <code>'''cmdTimeout'''</code> - 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.
* <code>'''Feedback Timeout'''</code> - If the SSH connection does not send feedback for this period, the specified password will be considered as invalid.
+
* <code>'''feedbackTimeout'''</code> - If the SSH connection does not send feedback for the specified interval, the password will be considered as invalid.
* <code>'''Welcome Timeout'''</code> - If the SSH shell prompt is not received within this period of time, the shell will be closed.
+
* <code>'''welcomeTimeout'''</code> - 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.  
 
  '''NOTE''': Value "0" means, that timeout is not used.  
  
 
  '''WARN''': Do not change timeout settings unless necessary.
 
  '''WARN''': Do not change timeout settings unless necessary.
 +
 +
===Example===
 +
<pre>
 +
"timeouts": {
 +
    "cmdTimeout": 0,
 +
    "feedbackTimeout": 0,
 +
    "welcomeTimeout": 0
 +
}
 +
</pre>
  
 
=Terminal=
 
=Terminal=
 +
Specifies command to start the shell in the VS Code integrated terminal.
 +
* <code>'''Command'''</code> - command to start the shell.
 +
 +
'''NOTE:''' It is possible to use variables in the command. The syntax is: <code>${variable}</code> or <code>${varable?<text if variable isn't empty>}</code>. 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.
  
Specifies command to start SSH shell in VS Code integrated terminal.
+
===Example===
* <code>'''Command'''</code> - 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'''.
+
<pre>
 +
"terminal": {
 +
    "command": "ssh -oHostKeyAlgorithms=+ssh-dss ${keyFile?-i ${keyFile}} ${username?${username}@}${host}"
 +
}
 +
</pre>
  
'''NOTE''': password may come from settings or if user entered it in UI prompt. Passwords entered in terminal aren't saved.
+
[https://www.youtube.com/watch?v=Ib1Fo6cG1Vs&list=PLewDXk9a8laO3cAZFPyZ4bbgcKsJ1qgPo Video tutorial: VMS IDE 1 Starting a Project]. In video "SSH Settings" shown at 1:45 - 2:39 time period.
  
 
[[Category:VMS IDE]]
 
[[Category:VMS IDE]]

Latest revision as of 09:28, 12 February 2024

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:
  2. "host-collection": {
        "hosts": [
            {
                "host": "",
                "keyFile": "",
                "password": "",
                "port": 22,
                "username": "",
                "skipSignatureVerification": false,
                "supportSetFileTime": true,
                "unzipCmd": "",
                "zipCmd": ""
                "algorithms": {
                    "kex": [],
                    "cipher": [],
                    "serverHostKey": [],
                    "hmac": [],
                    "compress": []
                }
            }
        ]
    }
  3. Specify connection parameters
  4. "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}",
            }
        ]
    }
  5. 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. 

Ssh collection hosts.png

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.