Installation

The Connector software can be used in two ways: Direct and Shuttle.

If you are running ImageManager on a server computer with direct internet access, or if it is behind NAT but you can forward a port through the firewall, then we recommend the Direct method.

Fig 1. Direct mode

If you are running ImageManager on a client computer without direct internet access, or if it is behind NAT and you cannot forward a port through the firewall, then we recommend the Shuttle method. In this method, the Connector connects outward to a Shuttle server which does not have such restrictions.

Fig 2. Mixed Direct and Shuttle mode

In either case, MyClient always makes only outbound connections; so either the Connector or the Shuttle must be available to accept direct incoming connections. Both the Connector and Shuttle services fully support IPv6 connections, and both services can be configured to use HTTPS.

Installation (Direct mode)

OVERVIEW

To install the Connector software,

1. Extract the distribution to a local path like C:\MyClient or desktop\MyClient


2. Configure the ini file as described below


3. Use the ServiceManagerGUI program to install and start the service. Optionally register an SSL certificate.


4. Register the Connector within MyClient on the Manage Servers page. CONFIGURATION

spconnector.exe looks for a settings.ini file in the same path as the exe file. Note that installing the MyClient ShadowProtect Connector to the Program Files directory therefore incurs a write lock to the ini file for all non-Administrator users.

The file should contain the following key/value pairs:

If any key/value pair is not present, a default value is used.

The field ConnectURL must end with a trailing slash.

AUTHENTICATION

You may configure a username and password in settings.ini so that MyClient can authenticate with the Connector. This password is transmitted unencrypted, so we recommend the use of HTTPS as described below.

You may whitelist IP addresses allowed to communicate with the connector using the WhitelistIPRegex parameter. The default is to allow any address to connect. The address used by MyClient can be viewed from the Manage Servers or Manage Connectors page. Note that as this is a regular expression field, some care should be taken with anchors and escape sequences:

Installation (Shuttle mode)

OVERVIEW

You may wish to attach the connector software to both off-site and on-site servers. The Connector software requires allowing inbound connections from MyClient, which might not be easy or even possible to configure at a customers' site. To address this issue, the Shuttle software can be used as a surrogate server instead. Connectors can connect outbound to the Shuttle, bypassing NAT and firewalls; and MyClient can then connect inward to the Shuttle server, which proxies the communication.

To use the Shuttle:

1. Extract the Shuttle software to your off-site server


2. Configure the Shuttle server in ini:
   
   
   
   • set Username and Password private credentials to share with MyClient
   
   
   • ensure the ConnectURL parameter ends with a slash
   
   
   • Add extra [Customer_XXXXX] sections with unique Username and Password fields, for each Connector that will be allowed to connect to this Shuttle. (Please note that this section name must start with Customer_ exactly, in order to be detected by the Shuttle software.)
   
   
   
   


3. Use the ServiceManagerGUI program to install and start the Shuttle service.


4. Extract the Connector software to the customer's on-site server


5. Configure the Connector in ini:
   
   
   
   • Set ShuttleMode to true and set ConnectURL to point to the Shuttle server
   
   
   • Set the Username and Password fields to authenticate with the Shuttle as configured in 2(c) above
   
   
   
   


6. Use the ServiceManagerGUI program to install and start the Connector service.


7. In MyClient, add the Shuttle instead of adding the Connector. All Connectors on the Shuttle will be automatically added into MyClient.

Enabling HTTPS

OVERVIEW

You can enable HTTPS for the service that accepts inbound connections. Both the Shuttle, and the Connector in direct mode, support SSL certificates for HTTPS.

To enable HTTPS for the service, you must have an SSL certificate in PKCS12 format (.pfx / .p12 file) that matches the domain name you are connecting to the server on.

An example certificate is provided for spconnector.example.com that can be used with the "Allow invalid SSL certificates" setting in MyClient.

CONVERTING CERTIFICATE FORMATS

If you already have an SSL certificate in Apache / X.509 format, you can convert it to PKCS12 format by running

openssl pkcs12 -export -out output.pfx -inkey input.key -in input.crt -certfile ca-chain.crt

INSTALLING THE CERTIFICATE

1. In ServiceManagerGUI, stop the service


2. In the relevant INI file, ensure the ConnectURL parameter starts with https://


3. In ServiceManagerGUI, register the SSL certificate


4. In ServiceManagerGUI, start the service

Troubleshooting

NOT A VALID WIN32 APPLICATION

The Connector and Shuttle services should work correctly on any 32-bit or 64-bit x86 version of Windows with .NET Framework 4.0 installed. Please ensure that this is installed.

WHERE TO SEE DIAGNOSTIC INFORMATION?

As of version 1.7.0.0, the connector software will post diagnostic information to the Windows Event Log. You can view these messages from eventvwr.msc. Note that the connector software is only able to write to the Windows Event Log if it is either (A) running as a service (normal behaviour), or (B) running with elevated permissions (i.e. Administrator).

If you are troubleshooting startup, you can run spconnector.exe from an elevated (i.e. Administrator) command prompt to see the same information.

HOW TO TEST IF SERVICE IS RUNNING CORRECTLY?

You can browse to the configured ConnectURL in a web browser. You should see a prompt for username/password. Upon entering the correct username and password, you should receive a Unknown method error. This indicates that the connector service is running correctly.

FAILED TO INSTALL SSL CERTIFICATE NETSH ADD: "THE PARAMETER IS INCORRECT."

The netsh add command works only if ConnectURL parameter is an IP address (not * or a DNS hostname), and if it is an IP address that the computer currently has (e.g. NAT users should use 10.x.x.x instead of public IP address).

WHAT DOES THE VERSION NUMBER MEAN?

MyClient ShadowProtect Connector employs semantic version numbers in the format MAJOR.MINOR.PATCH.

A new version of the software will increase

MAJOR if there is a significant incompatible change;

MINOR if there are new features or enhancements in a backward-compatible way; PATCH for backward-compatible bug fixes

For more information about version numbers, see http://semver.org.

ERROR "COULDN'T ACCESS IMAGEMANAGER DATABASE"

The Connector software retrieves information from ImageManager via several methods. Retrieving some certain information requires the ability to read data from the ImageManager.mdb file in the ImageManager directory. Reading this file may fail if an appropriate Jet/ACCDB database provider is not installed.

To determine whether the Connector is able to read the file, run the following PowerShell command:

 ((New-Object system.data.oledb.oledbenumerator).GetElements() | Select-Object -Property SOURCES_NAME)

Check for the following entries:

Microsoft.Jet.OLEDB.4.0 (32-bit OS)

Microsoft.ACE.OLEDB.12.0 (64-bit OS)

If neither of the above entries appear, you can install them from Microsoft:

"2007 Office System Driver: Data Connectivity Components" https://www.microsoft.com/en-us/download/details.aspx?id=23734

"Microsoft Access Database Engine 2010 Redistributable"

https://www.microsoft.com/en-us/download/details.aspx?id=13255

Please take care to install the correct 32-bit or 64-bit version for your operating system.

Running on Linux

OVERVIEW

The Shuttle software 1.10.0 or later can be installed on Linux using Mono. The Connector software cannot officially be run on Linux.

MyClientGlobal.com supports the Debian GNU/Linux software distribution (currently Debian 8 and Mono 3.2) when running the Shuttle on Linux. Other software versions and distributions may work, but without any support guarantees from MyClientGlobal.com Ltd.

INSTALLATION

1. Install the mono-complete package


2. Unpack the software to e.g. /opt/spconnector/


3. Run the servicemanager-linux.sh script

 If you encounter any permission errors, ensure that the files are owned and executable by the generated spshuttle user, and then re-run this script

4. Control the service via standard systemctl commands

HTTPS

The simplest approach to configuring SSL for the Shuttle service when running under linux is to use the httpcfg command. This command supports both PKCS12 (.pfx/.p12 format) and PEM (.crt/.key format) certificates. For more information, please see man httpcfg.

    su spshuttle -c "httpcfg -add -port 443 -p12 ./spconnector_example_com.p12 -pwd ''"     su spshuttle -c "httpcfg -list"

    # Port: 443 Thumbprint: 345270ECF0A96719E1E7BD28ADC6091E110ED3BE

This method has simplicity advantages. However, certain specific issues may render this approach unusable.

HTTPS (ALTERNATIVE METHOD)

It's possible to run the Shuttle server as HTTP only, in concert with apache2 or nginx as a front-end SSL termination. The following example is for Apache 2.4.x.

1. Enable the necessary Apache modules:

a2enmod ssl a2enmod proxy a2enmod proxy_balancer a2enmod proxy_http

2. Add the following (example) configuration file:

<VirtualHost *:8010>
SSLEngine on
SSLCertificateFile YOUR-CRT-FILE
SSLCertificateKeyFile YOUR-KEY-FILE
SSLCertificateChainFile YOUR-CHAIN-FILE
DocumentRoot /dev/null
ProxyRequests off
<Location />
ProxyPass http://127.0.0.1:YOUR-SHUTTLE-PORT/ connectiontimeout=3600 timeout=3600 Order allow,deny
Allow from all
</Location>
LogLevel warn
</VirtualHost>

API Documentation

The software produces a response in JSON to the following HTTP endpoints:

Changelog

1.10
Feature: Support running the Shuttle on Linux
Enhancement: Display more information for debugging Shuttle communication failures (1.10.1.0, 1.10.2.0)
Enhancement: Check service and database connections immediately upon startup (1.10.6.0)
Documentation: Troubleshooting Error 'Couldn't access ImageManager database' (1.10.6.0)
Fix a cosmetic issue with startup diagnostic messages (1.10.7.0)
Fix an issue with Shuttle communication if the .NET runtime is missing certain Windows Updates (1.10.3.0)
Fix an issue with ImageManager 7 compatibility (1.10.4.0)
Fix an issue with recent operating system compatibility (1.10.4.0)
Fix an issue with /paths endpoint since 1.7 (1.10.5.0)
Fix an issue with multiple- or upgraded- versions of ImageManager installed (1.10.5.0)
Fix an issue with aggregate endpoints on very large installations (1.10.7.0)
Fix an issue with not cleaning up old temporary files (1.10.7.0)
Fix an issue with ImageManager 7 being installed but not in use (1.10.7.0)
Fix an issue with submitting very long messages to the Windows Event Log (1.10.7.0)
Fix an issue with single corrupt/defunct managed folders interrupting the data servicing for other folders (1.10.7.0)

1.9
Feature: Automated Shuttle registration + revocation
Enhancement: Improve memory usage for long-running shuttle servers (1.9.1.0) Fix an issue with loading the shuttle if configuration file is not found

1.8
Feature: Shuttle
Enhancement: Live display of current service status in Service Manager
Enhancement: No longer necessary to provide ImageManagerDirectory, imageManagerHost, imageManagerPort, imageManagerPassword ini directives
Fix an issue with parameter validation when modifying Managed Folders
Fix an issue with HTTP response formatting
Fix an issue with SSL certificate registration (1.8.1.0)
Fix an issue with using the Shuttle in certain locales (1.8.2.0)

1.7
Feature: Add and remove managed folders
Feature: Retrieve all additional consolidation and verification errors from ImageManager
Feature: Write errors and information to Windows Event Log
Feature: Check ImageManager connection status
Documentation: Troubleshooting
Requires ImageManager.Interface.dll (Copyright © 2006-2014 StorageCraft Technology Corporation) Requires imageManagerHost, imageManagerPort, and imageManagerPassword ini directives

1.6
Feature: Easier HTTPS configuration and sample certificate
Enhancement: ServiceManagerGUI replaces bat scripts

1.5
Enhancement: Improve performance with large number of managed folders
Enhancement: Improve performance with inaccessible network-attached managed folders
Enhancement: PDF documentation
Fix an issue with locale-dependent date output
Fix an issue with still reporting managed folders that have been incompletely removed Fix an issue reporting a real size path to most recent image even if chain is broken

1.4
Feature: Scan for potentially unmanaged folders

1.3
Feature: Retrieve central and managed folder configuration
Feature: IP address whitelist
Documentation: SSL information
Enhancement: Send LatestCreateTime as UTC
Fix an issue with volumes missing spf names
Fix an issue with outdated file count / latest image information

1.2
Feature: Retrieve files for all clients at once
Feature: Aggregate verification failures, current chain size across /sets/ endpoints
Enhancement: Compress responses for faster transfer

1.1
Feature: Retrieve reports
Feature: Retrieve client info
Feature: Add documentation file
Fix an issue with URL parsing
Fix an issue with large JSON responses

1.0
Initial public release

0.0
Initial private release