Upgrade Storage Connector with OVA file

The following information describes how to upgrade instances of Syncplicity on-premises Storage Connector using an Open Virtualization Archive (OVA) file.  This is the upgrade path for a Storage Connector server running CentOS 6.x or 7.x to the new OVA running CentOS 7.6.

About the upgrade

The OVA file contains the necessary software for the Storage Connector to run, including:

• Pre-packaged and tested software
• The latest operating system version and security patches
• The latest features and configuration options for Storage Connector

When you upgrade Storage Connector with the OVA file, you deploy the new OVA file in your environment and migrate the configurations from the old Storage Connector Virtual Machine (VM) to the new Storage Connector VM.

Before you upgrade 

Before the upgrade, the latest version of the Storage Connector OVA file must be downloaded and the configuration files must be copied from the old Storage Connector VM to a location that will be accessible for the new Storage Conncetor VM.

1. Download the latest version of the OVA by going to https://my.syncplicity.com/Business/Downloads.aspx and clicking on Storage Connector (Virtual Appliance).
2. Log in to the old Storage Connector VM that you plan to upgrade and save copies of the following files:
   

   /etc/sysconfig/network-scripts/ifcfg-eth0
   
   NOTE: The default network interface on the VM is eth0. Check your system to verify which network interface is in use. If you have configured a different interface (such as eth1), verify that you copy the settings file for that interface (for example, the ifcfg-eth1 file).

   /etc/sysconfig/network
/etc/resolv.conf
/etc/fstab
/etc/ntp.conf
/etc/syncp-storage/syncp-storage.conf
/etc/syncp-storage/logger.xml

   WARNING: logger.xml file changes since 3.x version of the Storage connector. If any custom loggers are defined they have to be redefined manually in new logger.xml file.
   
   

3. If StorageVault Authentication (SVA) is used, save copies of the following files:
   
   • /etc/syncp-storage/idpcert.pem 
     The location of the *.pem file may differ. Check the setting syncplicity.storageVaultAuthentication.saml.idpCertFile in the syncp-storage.conf file.
   • myHmac.secret file
     The location of myHmac.secret (also known as the key file) may differ. Check the setting syncplicity.storageVaultAuthentication.key.file in the syncp-storage.conf file.
     For example:
     
4. If you have configured SSL on the Storage Connector, save copies of the SSL certificates and key files, and take note of the folder structure. You must recreate this folder structure on the new VM.
   • /etc/syncp-storage/https.properties file
   • Server public key certificate. For example, Storage_Connector_node.pem
   • Server private key. For example, Storage_Connector_node.key
   • your_company_jks_file.com.jks. This file contains a certificate that belongs to your company. It has a unique name that was created when the first Storage Connector was deployed. You can find this file in the /etc/syncp-storage/ folder on the Storage Connector server.
     The public key certificate and private key may be in a single PEM file.
5. As a requirement for the new OVA, the current password for the syncp user on the Storage Connector server must meet the following requirements:
   
   • At least 14 characters
   • At least one of each of the following character types: lowercase letters, uppercase letters, numbers and symbols
   • Cannot reuse the last 5 passwords
   • At least 5 characters different than the previous password

Provision the virtual machine

Use the following procedure for each Storage Connector you are upgrading:

1. Connect to your VMware ESXi server using VMware vSphere Client.

   
   
   
2. Select File →  Deploy OVF Template  to initiate the process.
   
   
   
3. Browse to the OVA file that was downloaded.
   
   
   
4. Accept the EULA.
   
   
   
5. Create a name for the deployed template.
   
   
   
6. Select the destination storage for the virtual machine.
   
   
   
7. Configure the amount of memory, CPU cores, and disk space to allocate to the VM. Each VM must meet the following requirements:
   • 8 GB of RAM
   • 8 virtual cores (Intel Xeon E5 Family processors, 2.20 GHz)
   • A minimum of a 50 GB HDD
8. Start the deployment and wait for the deployment process to complete.
9. In the Inventory, right-click the deployed VM and click Power On.
10. Open the Console tab and wait for CentOS to start.
    
    
    
11. Log in to the VM and change the default password for the syncp user.
    NOTE: An administrative account with sudo privileges called syncp has already been created in the VM. The initial password is onprem. After logging in, you will be asked to change the password to your new password or reuse the existing password. In the future, the password can be changed using the passwd command.

Migrate the OS settings from the Old Storage Connector VM

This procedure assumes the IP address and host name from the old Storage Connector VM is being reused.

To allocate a new IP address or host name (or both) for the new Storage Connector VM, see the following procedure on how to configure the OS settings on the new Storage Connector VM.

The following procedure describes how to migrate the OS settings for CentOS 7.6. This procedure must be performed on each Storage Connector server OVA deployed as an upgrade for an existing Storage Connector. Migrated values are taken from copies of the files that were made from the old Storage Connector VM and are applied to the new Storage Connector VM.

1. Shut down the old Storage Connector VM. 
   TIP: It is recommended that, at a minimum, two Storage Connector instances are run in the StorageVault; upgrade one at a time. As a best practice, always have at least one Storage Connector running.
2. To configure SSL on the new VM, verify that port 9443 is open.

3. On the new VM, copy the following lines from the old ifcfg-eth<x> file, for example, /etc/sysconfig/network-scripts/ifcfg-eth0.
   NOTE:  The default interface on the Storage Connector VM is eth0. If a different network interface is configured (such as eth1) on the old VM, copy the lines from the ifcfg-eth1 file. The following examples are based on the default network interface, eth0:

   BOOTPRO=static
IPADDR=<static-ip-address-for-this-server>
NETMASK=<network-mask>
GATEWAY=<gateway_ip_address>
BROADCAST=<broadcast_ip_address>
   NOTE: GATEWAY and BROADCAST may not be present based on older versions of the Storage Connector. In this case, determine the GATEWAY and BROADCAST for your IP address and add them in the ifcfg-eth0 file for the new Storage Connector VM.

4. Copy the following lines from the /etc/sysconfig/network file.
   NETWORKING=yes
NETWORKING_IPV6=yes
HOSTNAME=<hostname>
DOMAINNAME=<domainname>
GATEWAY=<gateway_ip_address>
5. Replace the entire /etc/resolv.conf file on the new VM.
6. Do not replace logger.xml with the one from the older connector version. If any custom loggers are defined in the logger.xml of the previously running connector, they must be redefined manually in new logger.xml file.
7. If custom servers for time synchronization are configured in /etc/ntp.conf, copy the configuration to /etc/chrony.conf and type the following command to restart chrony:
   sudo service chrony restart 
8. If SSL is configured on the old Storage Connector VM, copy the certificates and key files to the new Storage Connector VM.
   1. In /etc/syncp-storage/ on the file system, add a certificate file that belongs to your company. This file should be copied from the old Storage Connector (if available).
   2. Ensure the location of the keystore file has the correct access permissions (600) for the syncp-storage user by typing the following command:
      sudo chmod 600 /etc/syncp-storage/<your_company_jks_file.com>.jks

Configure the OS Settings on the new Storage Connector VM

This procedure assumes that a new IP address or host name (or both) is being allocated for the upgraded connector VM. If the OS settings from the old Storage Connector VM is migrated, see the following procedures on how to migrate the NFS storage settings. 

The following procedure describes how to configure the OS settings for CentOS 7.6. This procedure must be performed on each Storage Connector server VM that is deployed as an upgrade for an existing Storage Connector, if a new IP address or host name is being assigned to the VM. 

1. Stop the Storage Connector service on the old Storage Connector VM.
   sudo service syncp-storage stop
2. To configure SSL on the new VM, verify that port 9443 is open.

3. On the new VM, configure the following lines in the ifcfg-eth<x> file, for example, /etc/sysconfig/network-scripts/ifcfg-eth0.
   NOTE:  The default interface on the Storage Connector VM is eth0. To configure a different network interface (such as eth1), modify the ifcfg-eth1 file.  The following examples are based on the default network interface, eth0.
   BOOTPRO=static
IPADDR=<static-ip-address-for-this-server>
NETMASK=<network-mask>
GATEWAY=<gateway_ip_address>
BROADCAST=<broadcast_ip_address
>

4. Configure the following lines in the /etc/sysconfig/network file.
   NETWORKING=yes
NETWORKING_IPV6=yes
HOSTNAME=<hostname>
DOMAINNAME=<domainname>
GATEWAY=<gateway_ip_address>
5. Replace the entire /etc/resolv.conf file on the new VM.
6. If custom servers for time synchronization in /etc/ntp.conf are configured, copy the configuration to /etc/chrony.conf and type the following command to restart chrony:
   sudo service chrony restart
7. If the Storage Connector instances are behind a load balancer, add the new IP address to the load balancer configuration.
8. If SSL is configured on the old Storage Connector VM, verify that Storage Connector is working on port 9443 and add the certificates from the old VM to the new VM.
   1. In /etc/syncp-storage/ on the new VM, add a trusted certificate file that belongs to your company. This file should be copied from the old Storage Connector VM if it is there.
      NOTE: Storage Connector does not support self-signed certificates. The certificates must be signed by an official CA organization.
   2. If the old connector used port 433 instead of port 9443, redirect ports by typing the following command (-i parameter specifies the network interface used by the client, in the following example the network interface is eth0):
      iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -j REDIRECT --to-port 9443
9. Verify that all files in folder /etc/syncp-storage have syncp-storage owner and group.
   If needed, run the following command to change the owner:
   sudo chown -R syncp-storage:syncp-storage /etc/syncp-storage

Migrate the NFS storage settings

Network File System (NFS) storage settings must be migrated on each Storage Connector server OVA deployed as an upgrade for an existing Storage Connector. Migrated values are taken from copies of the files that were made from the old Storage Connector VM and applied to the new Storage Connector VM.

1. Create the storage mountpoint directory on the new Storage Connector. This storage mountpoint is specified in the /etc/syncp-storage/syncp-storage.conf file. For example, to create the storage mountpoint "/mnt/syncp", type the following command:
   mkdir /mnt/syncp
2. Type the following command to set the correct permissions for the mountpoint:
   sudo chmod 700 /mnt/syncp
3. Type the following command toset the ownership of the mountpoint:
   sudo chown -R syncp-storage:syncp-storage /mnt/syncp
4. Type the following command to make the storage mountpoint immutable:
   chattr +i /mnt/syncp
5. Copy the line for your storage mountpoint from the /etc/fstab file taken from the old Storage Connector VM to /etc/fstab.
6. Type the following command to mount the storage to the storage mountpoint:
   mount -a

Migrate the Storage Connector Configuration

The configuration for each Storage Connector VM deployed as an upgrade for an existing Storage Connector must be migrated. Storage Connector 3.x provides a migration tool that can be used to convert the values from the syncp-storage.conf file that was copied from the old VM to syncp-storge.yml file on the new VM. 

Migrated values are taken from the copies of the files were made from the old Storage Connector VM and applied to the new Storage Connector VM.

1. Copy the configuration files that were copied from the old VM to the same folders on the new VM. 
   For example, /etc/syncp-storage/syncp-storage.conf from the old VM must be copied to the new VM, in /etc/syncp-storage/ folder.
   NOTE: This folder may be different.

2. Run the following command on the new Storage Connector VM:
   syncp-storage-migrate-config [-? | -v] [-d] [-f] [--https <HTTPSCONFIG>] -i <PATH> [-k <PATH>] [-o <PATH>] [-p <PASS>] [-s <SPACES>]
   The following table contains descriptions of command options:

   Parameter	Description
   -?,--help	Prints this help information.
   -v,--version	Print version information.
   -d,--defaults	Print default values for all options.
   -f,--force	Force overwrite output file.
   --https <HTTPS CONFIG>	Absolute path to the https.properties file.
   -i,--input <PATH>	Absolute path to input HOCON formatted config file (syncp-storage.conf).
   -k,--keystore <PATH>	Absolute path to output KeyStore file. If not provided stdout will be used.
   -o,--output <PATH>	Absolute path to output YAML formatted configuration file (syncp-storage.yml_file). If not provided, the configuration migration report is written to stdout.
   -p,--password <PASS>	Password for the KeyStore file. Please avoid using that option as it may record the password in the command history. In case not used, an interactive password prompt will be displayed during tool operation
   -s,--spaces <SPACES>	Number of indentation spaces in the output YAML.

   For example, to migrate only the properties from the configuration file, without keystore file and no https settings, run syncp-storage-migrate-config -f -i /etc/syncp-storage/syncp-storage.conf -o /etc/syncp-storage/syncp-storage.yml

3. Wait for the migration process to complete. The migration report is written in the console and in the output file if the -o option in the command was used.
   NOTE: If issues occur during migration, errors and warnings are output on stderr. 
4. Check the console or the output file for errors and warnings.
5. Fix any errors that occurred during the migration in the syncp-storage.yml file
   • Use the error messages to identify the properties that are causing the problem
   • Fix these properties in the syncp-storage.yml file
6. After a successful migration the /etc/syncp-storage folder has to be cleaned up:
   • syncp-storage.yml - new config file
   • logger.xml - new logger config file - should remain

   • keystore file (name can vary)

   • cert file (name can vary)

   • SVA-related files (key file - usually called myHMAC.secret, and the idp cert file)

   • Verify the folder does not  contain files with extension *.rpmsave. If such files exist, delete them or do back them up on a separate location.

NOTES

•  Since the Storage Connector 3.2 configuration file format is changed to YAML, several configuration properties are changed, see Storage Connector configuration parameters.
• When migrating from 2.x to 3.x, the existing configuration is migrated automatically. For storage types "s3", the configuration migration may require access to the AWS metadata service in order to extract the AWS region. The region must be explicitly specified, due to an upgraded 3rd party library. If it is missing, it will be set to "us-east-1".

Example: Use the Configuration Migration tool to import Storage Connector configuration

1. Copy the configuration files (described in Before you upgrade the Storage Connector server) to the new Storage Connector appliance and verify the folder structure from the old VM is preserved.
   For example, /etc/syncp-storage/https.properties from the old VM must be copied to /etc/syncp-storage/https.properties on the new VM.
2. Verify that all copied files have syncp-storage owner and group.
   If needed, change the owner by running the following command:
   sudo chown -R syncp-storage:syncp-storage <folder_location>
3. Migrate the configuration:
   1. If SSL was enabled on the old Storage Connector, run the following command:
      • syncp-storage-migrate-config --https /etc/syncp-storage/https.properties -i /etc/syncp-storage/syncp-storage.conf -k etc/syncp-storage/idpcert.pem -o /etc/syncp-storage/syncp-storage.yml -p pasword123 -s 2
Where password123 is the password for the KeyStore file. Note that it is not a good practice to type a password on command line. If - p option is skipped an interactive password prompt will be displayed during tool operation.
      • In the /etc/syncp-storage/syncp-storage.yml file, double-check that the following configuration exists. If it doesn't please add it:
        syncplicity.https.enabled: true
   2. If SSL was not enabled on the old Storage Connector, run the following command:
      syncp-storage-migrate-config -i /etc/syncp-storage/syncp-storage.conf -k etc/syncp-storage/idpcert.pem -o /etc/syncp-storage/syncp-storage.yml -p pasword123 -s 2
4. Wait for the migration process to complete.
5. Check the console or the output file for errors and warnings.
6. Fix any errors in the syncp-storage.yml file.

Secure Credentials Configuration

This step is optional.

1. Copy the keystore file from folder /etc/syncp-storage/ on the old Storage Connector VM to folder /etc/syncp-storage/ on the new VM.
2. Ensure the location of the keystore file has the correct access permissions (600) for the syncp-storage user by typing the following command:
   sudo chmod 600 /etc/syncp-storage/<your_company_jks_file.com>.jks
3. With vi editor, open /etc/syncp-storage/syncp-storage.yml file and edit the following property to add the path to a certificate file that belongs to your company. This file should be copied from the old Storage Connector if it is there.
   crypto.keyStore:
enforced: true
file: <path to keystore file with secured credentials>
4. Verify that all files in folder /etc/syncp-storage have syncp-storage owner and group.
   If needed, change the owner by runnig the following command:
   sudo chown -R syncp-storage:syncp-storage /etc/syncp-storage

Complete the upgrade

After all settings are migrated, shut down the old Storage Connector VM if it is still running, and start the Storage Connector service on the new VM. Do this for each new Storage Connector VM. 

On the new Storage Connector VM, run the following command to start the Storage Connector service:
sudo service syncp-storage start

Verify the upgrade

Verify that all upgraded Storage Connector servers are functioning correctly. 

1. Verify the Storage Connector version is correct using the following command:
   rpm -qa | grep syncp-storage
   The RPM package name with the version is displayed. For example, the following is the output for version 3.2:
   syncp-storage-3.2.0.232-1.noarch
2. Verify the Storage Connector is running correctly using the following command:
   sudo service syncp-storage status
   The following message is displayed if running correctly:
   
3. Verify that the Storage Connector service is accessible from the network.
   
   • If you do not have an SSL certificate configured on the server, enter the following URL in the address bar of your browser:
     http://<hostname_or_IP_address_of_storage_connector_server>:9000/ping
   • If you have an SSL certificate configured on the server, enter the following URL in the address bar of your browser:
     https://<hostname_or_IP_address_of_storage_connector_server>:9443/ping
   • If you cannot use a browser, type the following command:
     curl http://<storage_connector_host_or_IP>:9000/ping

   The following message is displayed if the service is accessible:
   pong