Skip to main content

Connector guide

Introduction

The system connector allows you to leverage Shadline’s Enterprise Storage API without having to develop your own code. With this tool you can easily send and retrieve any type of file from secure storage.

You need to have the Shadline Enterprise Storage service to use this tool. Subscribing to this service allows you to obtain the certificate and API key required to connect.

Shadline Enterprise Storage can be partitioned into containers that correspond to isolated storage spaces. Each instance of the System Connector can interact with a single container. You can run multiple instances of the tool to connect to different containers.

Note: Local file names must not contain the characters: ‘(apostrophe), &, ?, |, *, :, /, \, <, >

Installation

The Shadline connector is compatible with Windows, Linux and macOS operating systems; 64-bit. It can be used on servers or workstations.

No third-party components need to be installed to run the connector. All prerequisites are built into the tool.

The file ‘shadline-connector.zip’ is made available to customers who have subscribed to this service by the Shadline team. It contains the executables for Linux, macOS and Windows. Unzip the file and copy the executable to the machine from which the synchronisation operation will be performed.

Note: For a Windows machine, you need to copy the « shadline-connector.exe » file and the « notifier » directory.

It is also necessary to allow an outgoing flow to the shadline.com domain on port 4435 (by default) to allow communication with the service.

Configuration

The parameters required for the operation of the connector are defined in the configuration file named config.json. The default configuration file is located in the same folder as the tool.

There are 2 methods to configure the tool:

  • Fill in the parameters in the configuration file config.json
  • Run the tool without input arguments and answer the questions

Here is the list of parameters to fill in the configuration file config.json:

Parameter Explanation
certFilePath .crt file of the certificate used to connect to the Shadline server.
certKeyPath .key file containing the certificate key used to connect to the Shadline server.
xApiKey Company identifier, in UUIDv4 format, generated by the Shadline service and delivered to the client when the service is activated. This identifier is common to the different containers used by the company.
xUserKey Identifier of the container to be accessed by the connector, in UUIDv4 format, generated by the Shadline service. It is obtained directly by the client’s administrators who have access to the Shadline back-office (or communicated by Shadline during the initialization of the API instance).
hPassword SHA512 hashed password of the container to be accessed by the connector.
localPassword String delivered by the Shadline server after the first connection to the API.
sourcePath The local root directory from which files are sent to Shadline storage when the connector is run via the push command (including the folders and subfolders contained in this directory).
destPath The local root directory from which files are received from Shadline storage when running the connector via the pull command (including folders and subfolders contained in this directory).

Note: You must always enter the absolute paths for the directories to be filled in.

Here is an example of a config.json file:

config_exemple_json

 

Note: Under Windows, the paths are filled in with the « \\ » separator. Under Linux and macOS, they are filled with the separator « / ».

You can download this example file to adapt it to your configuration: config_example.json.

 

The sourcePath and destPath directories can be the same directory.

Tool execution

The tool is executed with the following command:

shadline-connector.exe [commande] [options]

Commands:

  • push: Uploads files from the local « sourcePath » directory to the Shadline Enterprise Store.
    • Any new files added or modified (*) since the last time the connector was run are imported to Shadline.
    • If a file with the same name is already present in the Shadline Enterprise Storage container, this file is deleted and the locally present file is uploaded.
    • The connector does not delete locally deleted files from the Shadline Enterprise Storage container.

(*): After the first synchronisation, if a file has been deleted from the Enterprise Storage, it will not be automatically returned to the server. A message in the .log file (or in the console) tells you that the file has been deleted from the container in the Enterprise storage. In order to return these deleted files to the container, it is necessary to use the -f (–force) option:

shadline-connector.exe push -f
  • pull : Imports files from the Shadline Enterprise Storage to the local « destPath » directory.
    • Any new files added or modified on the Shadline Enterprise Storage since the last time the connector was run are synchronised to the local directory.
    • If a file with the same name is already present on the local directory, this file is deleted (*) and the file on the Shadline Enterprise Storage is uploaded.

(*) If a file has been modified locally since the last upload, it will not be automatically re-downloaded from Shadline Enterprise Storage to avoid overwriting the more recent local file by default. A message in the .log file indicates that the file has been updated locally. In order to recover the files from the Shadline container, it is necessary to use the -f (–force) option:

shadline-connector.exe pull -f

Options:

  • –version: Displays the version number
  • –config, -c: Path to a configuration file
  • –source,-s: Path to the directory used to send data to Shadline Enterprise Storage. Replaces the one specified in the config.json file under the sourcePath identifier.
  • –dest, -d: Path to the directory used to receive data from the Shadline Enterprise Storage. Replaces the one specified in the config.json file as destPath
  • –force, -f: If a file previously sent by the push command has been deleted from Shadline Enterprise Storage, this option allows it to be resent.
  • –help, -h: Displays the help

Notes:

  • If the —config option is used, the already existing config.json file is ignored and the one given as an argument is used.
  • If the —source option is used, the « sourcePath » parameter of the config.json file is ignored and the one given as argument is used.
  • If the —dest option is used, the « destPath » parameter of the config.json file is ignored and the one given as an argument is used.
  • It is necessary to allow an outbound flow to the shadline.com domain on port 4435 (default) to allow communication with the Shadline service.

Examples:

Sending files added or modified locally since the last time the connector was run and located in the local reference directory, to the Shadline Enterprise Storage container:

shadline-connector.exe push

For Windows:

You can create a shortcut to simplify your task as follows:

  1. Right click > New shortcut
  2. Insert, replacing with the right values:
    C:\WindowsSystem32cmd.exe /k « C:\WINDOWS-TO-L-EXECUTABLEshadline-connector.exe push -c C:\Users\WINDOWS-TO-YOUR-CONFIGURATIONconfig.json »

Notifications:

In Windows, a system notification informs the user when a file upload or download has been completed.

First execution under macOS :

At the time of the 1st launching under macOS, a warning message can be presented on the screen (captures below). You have to choose « Cancel » on the first window and « Open » on the second to run the tool.

1_lancement du connecteur_macos 2_lancement du connecteur_macos

Logs

The operations performed by the connector are logged in the target directory in a .log file in json format.

Here is an example of a log file:

{"name":"uploader","hostname":"DARYL","pid":34257,"level":30,"msg ":" Config file found","time":"2021-08-16T09:28:17.658Z","v":0}
{"name":"uploader","hostname":"DARYL","pid":34257,"level":30,"msg ":" Config file loaded","time":"2021-08-16T09:28:17.659Z","v":0}
{"name":"uploader","hostname":"DARYL","pid":34257,"level":30,"msg ":" '/text.md' created","time":"2021-08-16T09:28:18.477Z","v":0}
{"name":"uploader","hostname":"DARYL","pid":34257,"level":30,"msg ":" '/tux.png' created","time":"2021-08-16T09:28:18.991Z","v":0} 
{"name":"uploader","hostname":"DARYL","pid":34257,"level":30,"msg ":" 2 new entries created","time":"2021-08-16T09:28:23.493Z","v":0}
{"name":"uploader","hostname":"DARYL","pid":34257,"level":30,"msg ":" No updated entry","time":"2021-08-16T09:28:23.493Z","v":0}

Storage containers

To manage the storage containers accessed by the connector, please refer to the following page of our documentation:

Admin guide

This page explains how to retrieve the value of the « x-user-key » parameter of each container.