YSoft Shell

Prerequisites

Java (minimal version Java 11) has to be installed on the server with YSoft Shell (alternatively, configure the JAVA_HOME system property in import_tool.bat).

How to Run

Run YSoft Shell with "import_tool.bat" and then run the required command (run help for a list of possible commands or see the documentation on the Spring shell documentation page).

Run YSoft Shell with the required command immediately—run "import_tool.bat <command> -- required parameters".

YSoft Shell Plugins (commands)

See the Spring shell documentation page for general use and possible default parameters.

Security

When YSoft Shell needs to connect to the server, it is necessary to pass the host name to the server (it depends on the command).

There are two possibilities for providing the URL to CLI - it can connect through HTTP and a more secure HTTPS protocol (e.g., http://localhost vs. https://localhost). If it connects through HTTPS, then a certificate for the server must be in trusted certificates. The Trust Store and Key Store for certificates are fully configured in the conf\cli.properties file where, as default, there is a path to the YSoft SafeQ Management Server Trust Store where the YSoft SafeQ Management Server default certificate is saved. If the server has another certificate, it must be added to the Trust Store (see conf\ssl-truststore) or the path to the Trust Store in conf\cli.properties must be changed.

Structure of conf\cli.properties

cml_home - path to home directory
truststore.path - path to trust store
truststore.password - password to trust store
keystore.path - path to key store
keystore.password - password to key store

Failure to verify the https certificate trust may produce an error message like this on CLI import:

2022-07-21 07:55:12,044 Spring Shell  ERROR      AbstractCommand:26    - Command failed with exception
org.springframework.web.client.ResourceAccessException: I/O error on GET request for "https://localhost/rest/configuration/userReplicationDir": PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target; nested exception is javax.net.ssl.SSLHandshakeException: PKIX path building failed: 
Caused by: javax.net.ssl.SSLHandshakeException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

To resolve the situation proceed as follows:

First, we need to have a valid certificate for the server we connect to:
1. The certificate must be issued to the hostname/IP address of the Management Server
2. The certificate must be in base64 encoded X.509 format, it should look like this:
  example.crt
  
  TEXT
```
-----BEGIN CERTIFICATE-----
Something HERE.
-----END CERTIFICATE-----
```
3. To obtain the certificate:
  1. Option 1 - download it using Microsoft Edge
    - Open the Management Interface website in the Microsoft Edge
    - Click "Connection is secure"
    - Display certificate details
    - On tab "Details" click "Copy to File"
    - Use "Base-64 encoded X.509 (.CER)" in the Certificate Export Wizard and save the output to the file
  2. Option 2 - download it using the sslscan application from the following website: https://github.com/rbsec/sslscan/releases/latest
    TEXT
```
sslscan.exe --show-certificate --no-cipher-details --no-ciphersuites --no-compression --no-fallback --no-groups --no-heartbleed --no-renegotiation --no-sigs <ManagementServerAddress>:443
```
    - Extract the certificate from the command output and save it to a .crt file.
Make a backup of file <SAFEQ_DIR>\Management\utilities\import tool\conf\ssl-truststore
Import the certificate into CLI truststore:
- <SAFEQ_DIR>\Management\java\bin\keytool.exe -import -alias <YOUR_CERTIFICATE_ALIAS> -file <PATH_TO_NAME.crt> -keystore "<SAFEQ_DIR>\Management\utilities\import tool\conf\ssl-truststore"
Note: that alias is an identifier in trustore, we recommended to use the hostname for the alias in this case
- The default password is: 39nrqoge332fgomeer3405
- Verify that the certificate was really imported by (it can be found according to an alias specified above):
  <SAFEQ_DIR>\Management\java\bin\keytool.exe -list -keystore <SAFEQ_DIR>\Management\utilities\import tool\conf\ssl-truststore
Finally, execute the CLI import again