Installation
Articles and solutions related to setup, installation, deployment, and first configuration of your Syncplify Server!
- How to be notified of new releases
- Setup on Windows (GUI)
- Setup on Windows (CLI)
- Setup on Linux
- Updating/upgrading Syncplify Server!: the general rule
- Upgrading from v4/v5 to v6
- How to move/migrate your software to a different machine/VM
- How to recover (decrypt) old v4/v5 encrypted VFSs
- High-Availability (HA) general concepts
- High-Availability (HA): how to setup
- Licensing and license codes: a complete overview
- How to fix "Invalid OTP" error during setup
How to be notified of new releases
Keeping your software up to date is always highly recommended. Keep in mind that we keep working to improve our software and to fix bugs, so updates and upgrades are of the utmost importance for your experience with the software and for your overall safety.
There are two main ways to know when a new release of our software becomes available:
- Our official release notes: this is for those who like a proactive approach, visit this web page from time to time to check if there is a new release
- Our Telegram channel: this is a more passive (yet, arguably more effective) way that doesn't imply any effort on your end, simply subscribe to this Telegram channel and be notified whenever an update is available
Thank you for always keeping your software up to date.
Setup on Windows (GUI)
This here below is a quick "how to" and video tutorial showing how to install and setup Syncplify Server! v6 on Windows. It also shows its initial barebone configuration and test of some of its subsystems (protocol handlers).
Thank you! :)
Setup on Windows (CLI)
Some versions of Windows Server, especially the recent 2016, 2019, and 2022, can be installed without the graphical desktop that gave Windows its name in the first place. This makes for a usage experience that many Linux administrators are most familiar with, allowing Windows Server administrators to run their operating systems without any GUI environment, where every operation has to be performed via CLI (command-line interface) just as they would do within a Linux terminal.
Fear not! We got you covered. The same CLI installer that we have developed for Linux, also works on Windows, and the only difference is how you type in the command line to use it (as Windows relies on PowerShell, while Linux may use a variety of different and mostly-POSIX shells).
How to install
First of all you will need to download the most recent version of the CLI installer for Windows from our website. Extract the archive, and then type the following in a Terminal window (PowerShell or CMD.EXE):
.\ss6-setup.exe install
At the end of the setup process, open a browser and point it to the provided URL.
Be careful, the URL references localhost (127.0.0.1) but if you're using a browser on a different computer you will have to change 127.0.0.1 into the current IP address of the machine where you just installed Syncplify Server! on.
The same install
command line argument will also update/upgrade your software (without affecting your configuration) if Syncplify Server! is already installed in your system.
How to uninstall
Use the same ss6-setup
from the zip archive you downloaded (or download the most recent one, doesn't matter) and type the following command into a Terminal window (PowerShell or CMD.EXE):
.\ss6-setup.exe uninstall
How to update/upgrade
When the CLI installer is invoked with the install
verb, it will automatically try to determine whether the software is already installed on the system, and - if that is the case - perform an update/upgrade rather than a new install.
There is, however, a way to force the CLI installer to perform an update/upgrade, when you already know that this is the case. You can simply add the --update
flag to the install verb, like this:
.\ss6-setup.exe install --update
And, just in case... you can also do a "repair"
Should anything happen, you can always use the same ss6-setup
you downloaded and extracted, to "repair" your currently deployed executable and back-end DB configuration, like this:
.\ss6-setup.exe install --repair
More useful command-line flags
There are a couple additional command-line flags that you may want or need to use occasionally. Both of them are intended to be used in conjunction with the install
verb.
Flag | Purpose of the flag |
--trace |
Enables trace-level logging for the installation process. This will produce a larger and more detailed installation log, useful to identify the cause of possible installation issues. |
--norollback |
Typically, should something go wrong during installation, a rollback operation is performed, to leave your system unchanged. This flag disables such rollback, so that your system remains partially modified even after a failed installation. This is useful in some cases for debugging. |
That's it. :)
Setup on Linux
How to install
The following video shows how to install Syncplify Server! v6.x on a Linux operating system:
Here's a handy copy-pastable list of the two commands you'll need. You will still need to manually type in the name of the .tar.gz archive you downloaded though.
To extract the downloaded archive:
tar -xvf name_of_downloaded_targz_archive.tar.gz
Then to begin installing or updating the software:
sudo ./ss6-setup install
At the end of this phase, a URL will be shown to you. Simply open it in a browser to continue with the rest of the setup process.
Be careful, the URL references localhost (127.0.0.1) but if you're using a browser on a different computer you will have to change 127.0.0.1 into the current IP address of the machine where you just installed Syncplify Server! on.
How to uninstall
To make uninstallation easier, the installer copies the ss6-setup
executable to your /usr/bin
directory. Therefore, in order to uninstall Syncplify Server! v6.x you can simply open a terminal window anywhere, and type:
sudo ss6-setup uninstall
After that, if you also want to remove the uninstaller, you may (optionally) want to do this, too:
sudo rm /usr/bin/ss6-setup
How to update/upgrade
When the CLI installer is invoked with the install
verb, it will automatically try to determine whether the software is already installed on the system, and - if that is the case - perform an update/upgrade rather than a new install.
There is, however, a way to force the CLI installer to perform an update/upgrade, when you already know that this is the case. You can simply add the --update
flag to the install verb, like this:
sudo ./ss6-setup install --update
And, just in case... you can also do a "repair"
Should anything happen, you can always use the same ss6-setup
you downloaded and extracted, to "repair" your currently deployed executable and back-end DB configuration, like this:
sudo ./ss6-setup install --repair
More useful command-line flags
There are a couple additional command-line flags that you may want or need to use occasionally. Both of them are intended to be used in conjunction with the install
verb.
Flag | Purpose of the flag |
--trace |
Enables trace-level logging for the installation process. This will produce a larger and more detailed installation log, useful to identify the cause of possible installation issues. |
--norollback |
Typically, should something go wrong during installation, a rollback operation is performed, to leave your system unchanged. This flag disables such rollback, so that your system remains partially modified even after a failed installation. This is useful in some cases for debugging. |
That's it. :)
Updating/upgrading Syncplify Server!: the general rule
The process to update or upgrade your Syncplify Server! falls into either one of the following two scenarios, please read the one that's applicable to your current situation.
Updating within the same major version (ex: from v6.x.y to v6.w.z)
If the major version remains the same, updating your software to the most recent release is very straightforward: simply download the installer from our official website, and run it.
Your virtual sites, users, VFSs, and configuration will be kept and upgraded automatically as well, so this is truly an automatic and hassle-free procedure.
Be advised that any update of this kind requires an active maintenance/support plan, the installer will warn you if your maintenance/support plan is expired to give you a chance to renew it.
Upgrading from an older version (v4/v5 to v6)
You can perform an upgrade from an older v4/v5 version of our software. Versions 1 through 3 are too old and cannot be upgraded to v6 (read below in the third section of this article).
These upgrades from v4/v5 are relatively easy, but they do require you to perform a few manual steps, to make sure we describe the entire process and all of its implications in enough detail, with precision and thoroughness, we have written a dedicated knowledge base article on this specific topic.
Please note that you'll need a v6 license, your old v4/v5 license won't work, but if you have an active maintenance/support plan you can request a v6 license FOR FREE.
Upgrading from v1/v2/v3
Upgrading from any version older than v4 is not possible. Versions 1 through 3 were based on a totally different (and now discontinued) technology, so their configuration is not exportable and therefore it cannot be imported into v6.
So, if you're running any version of our software between v1 and v2, your only option is to deploy a brand new and fresh v6, and configure it anew (from scratch). Sorry about that, we had no other option.
Upgrading from v4/v5 to v6
Upgrading from an old Syncplify.me Server! v4 or v5 to Syncplify Server! v6 is much easier and straightforward than previous upgrade processes, and can be done directly, without the need for intermediate upgrades (provided you're on the latest release of your current v4/v5 version).
All you need is a backup of your old V4 or V5.
Once you have the backup file from your old installation ready at hand, please make sure you read these few short observations and recommendations, they will save you a lot of headaches in the future:
- Windows Users/Groups have been dropped: this is not a Windows-only software anymore; starting with version 6, Syncplify Server! is cross-platform (Windows and Linux) so all dependencies that are uniquely tied to a specific operating system had to be removed (Active Directory users/groups are still supported and will be imported as LDAP users/groups)
- Your scripts (if any) will be lost: after 8 years of honorable service, we had to say goodbye to our old scripting engine; in the spirit of unifying and uniforming our product suite, all of our software products will from now on utilize SyncJS (same as AFT!) as their only built-in scripting language
- Old or insecure host keys will not be imported: the import (restore) process checks all of the host keys in your backup, if any of them is found to be insecure it will not be imported and a new host key will be auto-generated in its place
- Encrypted VFSs (if any) cannot be imported, and the users using them won't be imported either (as a consequence) - there is a way to decrypt your old V4/V5 at-rest encrypted VFS contents but you will still have to recreate your VFS profiles and users accounts manually afterwards in your new V6 (this was sadly necessary, as the AES "mode" used in our old V4/V5 at-rest encrypted VFSs is no longer considered secure by the researchers at NIST)
- Passwords containing certain specific special characters (like for example) won't work after importing them in v6: the problem is not v6, but a self-consistent encoding bug in the old v4/v5. Most of your passwords will work just fine after upgrading to v6, only those containing a tiny subset of special characters won't, but you can re-set them (set them again) in v6, including the offending special characters, and after re-setting them they will work just fine in v6 as well (let us reinforce the fact that v6 has no problem with any special character, the problem was the old v4/v5).
- Other minor changes here and there: minor things like, for example, certificates must be imported using their PEM-encoded (cross-platform) format, old/insecure encryption and key-exchange algorithms have been dropped... basically, after the upgrade it's recommended to check the entire configuration to make sure it's still 100% consistent
For these reasons we do not recommend in-place upgrades, what we recommend instead is to perform a migration-upgrade. Please, read below for more details.
Performing a migration-upgrade is as simple as:
- Installing Syncplify Server! V6 on a new machine or VM (fresh operating system preferably)
- Importing your old V4/V5 backup in 1 click
The video here below shows just how quick and easy it is:
Important note for existing V4/V5 license holders: every new major version, traditionally, uses a new license code type, so if you own a v4/v5 license it won't work with v6. But if you do have an active maintenance/support subscription, you can simply request a free v6 upgraded license code by submitting a ticket here.
But what if, in spite of best-practices you want to do an in-place upgrade?
In-place upgrades are certainly possible, though not highly recommended. Here's the key points to keep in mind in order to successfully perform an in-place upgrade:
- First and foremost, before you start, take a full snapshot or backup of your machine/VM - this is the best way to roll-back your fully functional old v4/v5 in case anything happens
- The procedure shown in the video tutorial here above is still valid, with only one remarkable difference: after taking your old v4/v5 backup, and before starting v6 installation, you'll have to stop and disable all of your old version's system services, as shown in the picture here below:
How to move/migrate your software to a different machine/VM
If you intend to do a migration-upgrade (move from one VM to another while upgrading the software at the same time, this article is not for you. You should follow this procedure instead.
This procedure is only applicable to Syncplify Server! v6+, if you are running an older version (for example v4 or v5) this procedure won't work, please refer to this other knowledge base article instead.
If you need to migrate your Syncplify Server! to a different/new machine or VM, please, keep in mind that this article explains the only correct procedure to accomplish the goal.
No worries, it's really easy. Simply follow these steps in this exact order:
- Log into the SuperAdmin web UI on your "old" machine/VM, the one you want to decommission, and take a full backup of Syncplify Server!'s configuration from the BACKUP page; then from the LICENSE page in the same UI use the Deactivate button to free up your license and be able to re-activate it later on your new VM
- Make sure you deploy a new machine/VM with a fresh operating system, and don't install anything else on it for now, only the operating system
- Copy the backup file (a .zip archive) to the new machine/VM
- Download the latest Syncplify Server! installer on the new machine/VM and install it as you normally would if it were a fresh/new deployment
- Once the installer is done you can log into your new Syncplify Server!'s SuperAdmin UI on the new machine/VM and do the following, in this exact order:
- activate the license first (the one you previously deactivated from the old machine/VM)
- from the RESTORE page in the SuperAdmin UI perform a restore of the backup you took from your old machine/VM onto this new node
IMPORTANT: when you use the Deactivate License function you're freeing up that license code so that it can be reactivated on another (different) machine, you will not be able to reactivate it on the same machine you have deactivated it from. This automatic deactivation requires your server to be online (have direct, unrestricted, unproxed Internet access), if you're running your server offline, please contact us to have your license deactivated.
How to recover (decrypt) old v4/v5 encrypted VFSs
As explained in our developers blog, starting from Syncplify Server! version 6 we had to change the way encrypted VFSs operate, because the old way (v4/v5) can no longer be considered 100% safe. This was not a lighthearted decision, but it had to be taken.
So what now? What does this entail for customers who were using these encrypted VFSs in old v4/v5, and now wish to upgrade to the latest v6 to take advantage of all the new features and its improved speed and stability?
Fear not. We have developed a little tool (mentioned in the blog article above) which can greatly help you with the transition.
Before we begin, it's important to understand one important detail: encrypted VFSs cannot be imported from a v4/v5 backup into your new v6, and as a result all user profiles using such encrypted VFSs also cannot be imported. So after upgrading to v6 your old encrypted VFSs (and the user profiles that used them) will be missing.
Here's what to do to recover access to the data stored in those old v4/v5 encrypted VFSs:
- Download the DiskAES256Decrypt.zip archive from our website, and extract it into a directory of your choice on the machine/VM where the encrypted VFSs content is stored
- Run it, and decrypt the content of each old v4/v5 encrypted VFS into fresh new empty folders (one per folder)
- In your new Syncplify Server! v6, create a new encrypted VFS for each one of the old ones, all of these new VFSs must point to empty folders/directories
- In your new Syncplify Server! v6, manually create the user profiles to use the newly created encrypted VFSs
- Use an actual SFTP client software to log into those user profiles and re-upload the contents from the decrypted (in clear) directories: Syncplify Server! v6 will then automatically re-encrypt all of those files as they are being uploaded via the SFTP client
This is a one-time operation, once done you'll be good to go for the entire life of your Syncplify Server! v6 (and all future versions for the foreseeable future).
High-Availability (HA) general concepts
The most important improvement brought about by Syncplify Server! version is the simplicity with which you can create a true active-active high-availability (HA) set with it.
In fact, as of version 5.x (and subsequent versions) you don’t have to deploy a database replica-set anymore, which is hard to do and requires at least 5 virtual machines (2 for the SFTP nodes, and 3 for the database); Syncplify Server! version can achieve a totally fault-tolerant, active-active, highly-available deployment with just 2 nodes!
Of course, Syncplify is in the secure file transfer business, not in the networking business nor in the storage business, so you’ll have to provide the networking and storage components yourself, but this is also true with any other SFTP server on the market.
So, without any further ado, let’s dig in.
If you do have a Load Balancer, we definitely recommend you use it. In such case your deployment will look somewhat like this:
If you don’t have a Load Balancer, you can still achieve a remarkable level of High Availability by creating multiple “A records” on your DNS associated with the Host Name of the FTP/SFTP server, and configuring your DNS to provide round-robin responses. Clearly, unlike the Load.
Balancer, your DNS will not be able to probe your SFTP nodes to see if they’re alive, but it will direct all client connections equally to both nodes, de facto spreading out incoming traffic just like a load-balanced HA would.
It is important to understand that in both of the cases shown here above, it is still your responsibility to provide shared storage to all SFTP nodes. In our charts, we show this can be a Windows DFS or a NAS or a SAN of your choice. It can also be any network file system that your SFTP nodes can access natively (for example, an iSCSI Target is perfectly fine).
High-Availability (HA): how to setup
This article assumes you've already read, understood, and are familiar with the general concepts explained here.
Once you have decided how to deploy your Syncplify Server! high-availability set, going from theory to practice is actually quite simple: it's just a two-step process.
Step #1: deploy the first node as if it were a single stand-alone server
This procedure is very well explained here (for Windows) and here (for Linux).
Step #2: adding the second (or n-th) node to make your HA set
If you are familiar with the single-node setup of Syncplify Server! (see step #1) then you surely have noticed that, at the beginning of the web-based part of the installation process, you're presented with the following choice:
To deploy your HA set you simply have to install Syncplify Server! on another node (machine or VM) and, when presented with the above choice, you'll select the "Add this node to another..." option.
You will then choose a Node ID (and an optional description) as usual...
And then you will type the IP address and port (separated by a single colon) of the first node, the one you previously installed as a single stand-alone server. For best performance and optimal routing you should always use the nodes' internal (LAN) IP addresses here.
Do not try to be creative here, do not type anything exotic like the nodes' NetBEUI names "just because Windows knows it" or similar oddities. It will not work. Please, just follow the instructions and type the LAN IP address and port of the existing node you want to join to create your high-availability set. Thank you!
Licensing and license codes: a complete overview
In this article, we provide a compendium, sort of a min-FAQ, regarding the most common questions and pieces of knowledge that every Syncplify Server! user should know about Syncplify Server!'s licenses and licensing system. So here we go:
What’s the license code format?
License codes look kind-of like this: S6UF-R3EP-9XDJ-BJJ7-U33Z-PKGA (not a real license, just meant as an example)
The first two characters (here above highlighted in green) are always the letter S followed by the major version the license is applicable to. So you know what version of the software can accept the license you're looking at.
Will my old (v4, v3, v5…) license code work with the most recent version of the software?
No. As you can guess by the different license code formats, you need a license code that was issued for the exact version of the software you are trying to activate. The good news is, though, that if you are covered by a maintenance/support plan, you can request one for free to Syncplify.
I have an active maintenance/support subscription for an older version, and I wish to convert it to a maintenance/support plan for the most recent version. How do I do that?
Simply open a support ticket with Syncplify, and our team will provide a dedicated link and proper instructions on how to do so.
I run Syncplify Server! on dynamic hardware, and every so often my v3/v4/v5 license reverted back to “free” because hardware changes were detected. Will this still happen with v6+ licenses?
No. We’ve done a lot of work to change this behavior, and we are confident that deactivations “by mistake” should not occur anymore. Our software can now tell the difference between, say, resizing an existing VM, and moving to an entirely different VM. Your v6 license will remain active as long as you make changes to the hardware of your existing VM, and will self-deactivate only if you try to use it also on a different VM. This provides us with a decent level of protection against abuse, but – more importantly – provides our customers with the level of flexibility they need to run our software in virtualized/cloud/elastic environments.
Will my license expire? Do I have to renew it?
No. Licenses never expire, if you never alter, move, or update/upgrade the software. But licenses can automatically self-deactivate if you do something you're not entitled to, like updating/upgrading the software while not covered by a maintenance/support plan. That's why we strongly encourage all customers to keep their maintenance/support plan current, and to renew it every year: that way all updates/upgrades within the same major version will be totally free of charge, and between different major versions they will come with significant discounts. Not to mention that you need an active maintenance/support plan in order to request support if you need it.
How to fix "Invalid OTP" error during setup
In order to ensure the utmost level of security, the web-based portion of the setup process must be completed within 5 minutes; taking longer than that will result in an "Invalid OTP" error, and the setup will fail.
If that happens there are 2 possible ways to fix the situation.
Workaround #1
Fully uninstall Syncplify Server! v6 from the Windows Control Panel or, if it's Linux, using the setup CLI, then reinstall the software anew (fresh, from scratch).
Workaround #2
Run a terminal (cmd.exe, PowerShell, or any terminal/shell in Linux), then change directory into the folder where the software is installed, and type the following:
For Windows (as Administrator):
.\ss6-webrest.exe genssc
For Linux:
sudo ./ss6-webrest genssc