SFTPPlus Documentation

Start Page 2. Installation and Upgrade Instructions 2.5. Upgrade Procedures

2.5. Upgrade Procedures

2.5.1. Introduction

Before proceeding with any upgrade, ensure that SFTPPlus, along with all file transfer services, are stopped.

There are three different procedures that you can follow, depending on the version to be upgraded:

  • When upgrading from versions pre-2.0 to latest, one should be aware that major configuration changes have been implemented and the process should be performed with care.
  • When upgrading from versions 2.x to latest, it is required to reinstall the server and integrate the existing data in the new system.
  • When upgrading from versions 3.x to latest, one can run the installer using the same installation path.

Note

When upgrading for all versions, please check if any custom paths in the install have been made. The instructions in this documentation are for default paths and may need to be modified based on your paths.

In all cases, the configuration files should be backed up before proceeding with the upgrade, otherwise the configuration data will be lost.

Please consult the Server Release Notes, as it contains detailed information about the steps required for upgrading between specific versions.

2.5.2. Upgrading SFTPPlus Server from versions 1.x to 2.x

Upgrading from a 1.x version to a 2.x version requires preservation of the configuration data, reinstallation of the server, and integration of the existing data into the new system.

  • Make sure the system is in maintenance mode and there are no active file transfers.
  • Stop the SFTPPlus service.
  • Copy the configuration files to a backup location. Optionally, consider copying the log files as well.
  • Uninstall the SFTPPlus version running on your server.
  • Download the latest version of SFTPPlus Server 2.x and install it on your machine.

Note

The main changes that were introduced with version 2.0 are highlighted below. Please consult the Release Notes in order to have a more detailed view of particular changes in each release.

You will notice the new version is now using a single configuration file. The settings contained in the server.config, users.config, sftp-service.config, ftp-service.config and ftpsi-service.config files will need to be manually migrated to the new server.ini configuration file. This can be done by following the instructions below.

The initial server.ini configuration file will include explanatory comments. However, for a thorough understanding of all the options, please consult our documentation.

The services_ prefix has been removed from all configuration options. When moving information from one file to the other, please remember to delete the prefix, otherwise the option will be ignored.

2.5.2.1. Migrating Server configuration options

The options defined under the [services] section in the server.config file have to be copied over to the [server] section in server.ini.

All services_ prefixes should be deleted.

The services_users_configuration_file option is no longer of any use, as the users are defined in the same configuration file. Therefore, it should be removed.

New attributes have to be defined in the [server] section: uuid, name, and description.

More information about each of them can be found in the Server v2 Documentation files.

2.5.2.2. Migrating Log configuration options

The options defined under the [log] section in the server.config file have to be copied over to the [log] section in server.ini.

No other changes are required.

2.5.2.3. Migrating Services configuration options

Services configurations are now defined using a new section marker in the server.ini file.

Each service now has a universally unique identifier (UUID) and a human readable short name. This allows rename operations and operating multiple services in a cluster environment. For more details see documentation.

For example, to update the service configuration for a service named ftp-partners having the following configuration:

[services/550e8400-e29b-41d4-a716-446655440000]
name = ftp-partners
service_enabled = yes

Please use something along the lines of:

[services/550e8400-e29b-41d4-a716-446655440000]
name = ftp-partners
enabled = yes

The service configuration options have been moved from dedicated files into the main configuration file.

All configuration options in the [service] section of each service configuration file need to be copied inside the dedicated section for each service in server.ini, along with specific configurations in server.config.

Here is an example of a service section definition for an FTP protocol:

[services/550e8400-e29b-41d4-a716-446655440000]
name = ftp-partners
enabled = yes

Protocol options copied from configuration/ftp-service.config file:

[services/880e8400-e29b-41d4-a716-446655440044]
name = ftp-only
banner = Welcome to the FTP/FTPS Service.
passive_port_range = 9000 - 9200

All services_ prefixes need to be removed, otherwise those options will be completely ignored.

2.5.2.4. Migrating groups and users configuration

Groups and accounts configurations have been moved from the dedicated file into the main configuration file. All accounts and groups should now have an associated UUID.

OS_GROUP is now a regular group, and accounts are not automatically associated to this group. We recommend renaming it as os_group, to suggest that it is just a normal group.

APPLICATION_GROUP has been renamed as DEFAULT_GROUP. DEFAULT_GROUP is automatically associated to all accounts for which a group was not explicitly defined. These are operating system accounts not defined in the configuration file or legacy SFTPPlus WebAdmin accounts.

The ${DEFAULT_GROUP} placeholder has been renamed as ${DEFAULT_OS_GROUP}. The new name should make it clear that it is referring to a group defined by the operating system.

The ${DEFAULT_USER} placeholder has been renamed as ${DEFAULT_OS_USER}. The new name should make it clear that it is referring to an account defined by the operating system.

Configuration sections for groups are now in the format [groups/550e8400-e29b-41d4-a716-446655440001], and the name of the group is now a configuration option. 550e8400-e29b-41d4-a716-446655440001 is the group unique ID. The type configuration option is no longer of any use.

Configuration sections for accounts are now in the format [accounts/550e8400-e29b-41d4-a716-446655440000], and the name of the account is now a configuration option. 550e8400-e29b-41d4-a716-446655440000 is the account unique ID. This allows renaming for accounts.

Here is an example of a new account definition:

[accounts/550e8400-e29b-41d4-a716-446655440000]
name = john
type = application

2.5.3. Upgrading SFTPPlus from SFTPPlus Server version 2.X.X

Upgrading from a 2.x version to a 3.x version requires preservation of the configuration data, reinstallation of the server, and integration of the existing data into the new system.

  • It is recommended to perform the upgrade in a maintenance window and make sure there are no active file transfers.
  • Stop the SFTPPlus service.
  • Copy the configuration files to a backup location. Optionally, consider copying the log files as well.
  • Uninstall the SFTPPlus version running on your server.
  • Download the latest version of SFTPPlus 3, and install it on your machine.

In version 3, the default configuration file is still named server.ini.

To enable the new authentication method for application and os accounts, you will need to update the authentications option inside the [server] section, and add a dedicated method for application accounts.

Below is what the relevant parts of the [server] configuration should look like:

[server]
authentications = application-uuid, os-uuid, OTHER-AUTH-UUID

[authentications/03288e36-cf6b-4bd5-a9be-f421372f17e6]
enabled = Yes
type = application
name = Application Accounts
description = This authentication method allows authentication accounts
    defined in this configuration file.

[authentications/6d51ed1e-35ec-41d7-8b51-53e56c716212]
enabled = Yes
type = os
name = Operating System Accounts
description = Accounts provided by the operating system.

To migrate the authentication of global SFTPPlus accounts, remove the sftpplus_webadmin option from the server section:

[server]
sftpplus_webadmin = http://wsftp.example.com:8080/SFTPPlus/

And replace it with a dedicated authentications method:

[server]
authentications = OTHER-AUTH-UUID, legacy-webadmin-uuid, MORE-AUTH-UUID

[authentications/9g51ed1e-35ec-41d7-8b51-53e56c716313]
enabled = Yes
type = legacy-webadmin
name = Legacy SFTPPlus Webadmin

url = http://wsftp.example.com:8080/SFTPPlus/

To migrate the account report, create a new event handler. In the configuration file, replace:

[report]
database = sqlite-db-uuid

With a new event-handlers section:

[event-handlers/8cace339-a2ee-4899-b64e-db2478821b9e]
enabled = No
type = account-activity
name = Account activity
description = Report last successful login for accounts and administrators.

database = sqlite-db-uuid

To migrate the file log handler, remove the logs handler section:

[logs/03288e36-cf6b-4bd5-a9be-f421372f17e6]
enabled = Yes
name = Default Local Log File
description = Append logs to a file on local filesystem.

type = file

path = log/server.log

And replace it with a dedicated event-handlers section:

[event-handlers/00feb81f-a99d-42f1-a86c-1562c3281bd9]
enabled = Yes
name = Default Local Log File
description = Append logs to a file on local filesystem.

type = local-file

path = log/server.log

To migrate the Windows EventLog log handler, remove the logs handler section:

[logs/f643a93d-94d5-4b41-b723-a63a00e3c902]
enabled = Yes
name = SFTPPlus Server
description = Send logs to Windows Event Log Service on local machine.

type = eventlog

And replace it with a dedicated event handler of type windows-eventlog:

[event-handlers/515361f1-d976-4fe0-979b-0651e2bf591d]
enabled = Yes
name = STFPPlus
description = Send logs to Windows Event Log Service on local machine.

type = windows-eventlog

To migrate the WebAdmin HTTP Post Request log handler, remove the logs section for the Webadmin HTTP Post:

[logs/e16af067-8974-4c0d-ae89-eb5f3d59fd65]
name = Default_WebAdmin
enabled = No
name = WebAdmin HTTP Post
description = Hook to WebAdmin over HTTP.

type = http-post
format = webadmin

url = http://int.example.com/SFTPPlus/AuditAddSimple.php

And create a new event-handlers section as:

[event-handlers/03288e36-cf6b-4kd5-a9be-f421372f17e6]
enabled = No
name = WebAdmin HTTP Post
description = Send logs to Legacy WebAdmin over HTTP.

type = http
format = legacy-webadmin

url = http://int.example.com/SFTPPlus/AuditAddSimple.php

To convert legacy SQLite/MySQL database loggers, you should delete section(s):

[logs/0ef580fe-45cb-47e0-b434-c0e44557b364]
enabled = Yes
name = SQLite Legacy Log Handler
description = Send logs to local SQLite file in legacy mode.

type = sqlite
path = log/server.db3

And add two new sections, one for the databases and one for the event handlers:

[databases/27b8e2b1-7971-416d-af14-6a8aae2ac46e]
enabled = Yes
name = SQLite
description = SQLite file database connection.

type = sqlite
path = log/server.db3

[event-handlers/22a9d8fb-068d-4a63-8d5d-0ce94ef22a25]
enabled = Yes
name = SQLite Event Handler
description = Store events in local SQLite file.
type = database
database = sqlite-db-uuid

If there is already a section for the desired database, you do not need to create a section for it, just make sure to use the existing database UUID.

Make sure your database UUID matches the one configured for the event handler in order to pair them.

For MySQL logger(s), you should delete the logs section:

[logs/6d51ed1e-35ec-41d7-8b51-53e56c716212]
enabled = No
name = MySQL Legacy Log Handler
description = Send logs to MySQL database in legacy mode.

type = mysql

address = 172.20.0.24
port = 3306
username = test
password = test
database = test

And create two new sections for databases and event-handlers:

[databases/ac547e16-a3ff-4fc3-a6ab-142af2744f50]
enabled = No
name = MySQL
description = MySQL database connection.

type = mysql

address = 172.20.0.24
port = 3306
username = test
password = test
database = test

[event-handlers/7db823d8-05f8-4481-be98-b87a826ded28]
enabled = No
name = MySQL Event Handler
description = Store events in a MySQL database
type = database
database = mysql-db-uuid

The above note on SQLite’s database section also applies to MySQL’s database section.

To migrate the Syslog log handler, remove the logs handler section:

[logs/27a31405-a963-4fb9-b4ee-09d415b1a30a]
enabled = Yes
name = Syslog Backup
description = Sends logs to backup syslog server.

type = syslog

path = Disabled
address = 127.0.0.1
port = 514

And replace it with a dedicated event-handlers section:

[event-handlers/1ee4337a-22f7-4a67-9a77-5c3a508a8158]
enabled = Yes
name = Syslog Backup
description = Sends logs to backup syslog server.

type = syslog

path = Disabled
address = 127.0.0.1
port = 514

For converting the database log handler into an event handler, remove the logs section:

[logs/bdfe8e48-5100-4d8a-bac1-441ebc04f9a7]
enabled = Yes
name = SQLite Log Handler
description = Send logs to local SQLite file.
type = database
database = sqlite-db-uuid

And replace it with a dedicated event-handlers section:

[event-handlers/681f5f5d-0502-4ebb-90d5-5d5c549fac6b]
enabled = Yes
name = Database Event Handler
description = Send logs to local SQLite file.
type = database
database = sqlite-db-uuid

2.5.4. Upgrading SFTPPlus Server from versions 1.x to 2.0 or later

Upgrading from a 1.x version to a 2.x version or later requires preservation of the configuration data, reinstallation of the server, and integration of the existing data into the new system.

  • Make sure the system is in maintenance mode and there are no active file transfers.
  • Stop the SFTPPlus service.
  • Copy the configuration files to a backup location. Optionally, consider copying the log files as well.
  • Uninstall the SFTPPlus version running on your server.
  • Download the latest version of SFTPPlus MFT version 3 and install it on your machine.

Note

The main changes that were introduced with version 2.0 are highlighted below. Please consult the Release Notes in order to have a more detailed view of particular changes in each release.

You will notice the new version is now using a single configuration file. The settings contained by the server.config, users.config, sftp-service.config, ftp-service.config and ftpsi-service.config will need to be manually migrated to the new server.ini configuration file. This can be done by following the instructions below.

The sample server.ini configuration file includes some explanatory comments. However, for a thorough understanding of all the options, please consult our documentation.

The services_ prefix has been removed from all configuration options. When moving information from one file to the other, please remember to delete the prefix, otherwise the option will be ignored.

2.5.4.1. Migrating Server configuration options

The options defined under the [services] section in the server.config file have to be copied over to the [server] section in server.ini.

All services_ prefixes should be deleted.

The services_users_configuration_file option is no longer of any use, as the users are defined in the same configuration file. Therefore, it should be removed.

New attributes have to be defined in the [server] section: the UUID, name, and description. More information about each of them can be found in the documentation files.

2.5.4.2. Migrating Log configuration options

The options defined under the [log] section in the server.config file have to be copied over to the [log] section in server.ini.

No other changes are required.

2.5.4.3. Migrating Services configuration options

Services configurations are now defined using a new section marker in the server.ini file.

Each service now has a universally unique identifier (UUID) and a human readable short name. This allows rename operations and operating multiple services in a cluster environment. For more details see documentation.

For example, to update the service configuration for a service named ftp-partners with the following configuration:

[services/d7623fb2-4e1f-483e-8599-f5599ac15eb1]
name = ftp-partners
service_enabled = yes

Please use the example below to update the services configuration section:

[services/550e8400-e29b-41d4-a716-446655440000]
name = ftp-partners
enabled = yes

The service configuration options have been moved from dedicated files into the main configuration file.

All configuration options in the [service] section of each service configuration file need to be copied inside the dedicated section for each service in server.ini, along with specific configurations in server.config.

Here is an example of a service section definition for an FTP protocol:

[services/550e8400-e29b-41d4-a716-446655440000]
name = ftp-partners
enabled = yes

Protocol options copied from configuration/ftp-service.config file:

[services/b9787c72-2c8b-4725-a049-ee628aa0abc1]
name = ftps
banner = Welcome to the FTP/FTPS Service.
passive_port_range = 9000 - 9200

All services_ prefixes need to be removed, otherwise those options will be completely ignored.

2.5.4.4. Migrating groups and users configuration

Groups and accounts configurations have been moved from the dedicated file into the main configuration file. All accounts and groups should now have an associated UUID.

OS_GROUP is now a regular group, and accounts are not automatically associated to this group. We recommend renaming it as os_group, to suggest that it is just a normal group.

APPLICATION_GROUP has been renamed as DEFAULT_GROUP. DEFAULT_GROUP is automatically associated to all accounts for which a group was not explicitly defined. These are operating system accounts not defined in the configuration file or legacy SFTPPlus WebAdmin accounts.

The ${DEFAULT_GROUP} placeholder has been renamed as ${DEFAULT_OS_GROUP}. The new name should make it clear that it is referring to a group defined by the operating system.

The ${DEFAULT_USER} placeholder has been renamed as ${DEFAULT_OS_USER}. The new name should make it clear that it is referring to an account defined by the operating system.

Configuration sections for groups are now in the format [groups/550e8400-e29b-41d4-a716-446655440001], and the name of the group is now a configuration option. 550e8400-e29b-41d4-a716-446655440001 is the group unique ID. The type configuration option is no longer of any use.

Configuration sections for accounts are now in the format [accounts/550e8400-e29b-41d4-a716-446655440000], and the name of the account is now a configuration option. 550e8400-e29b-41d4-a716-446655440000 is the account unique ID. This allows renaming for accounts.

Here is an example of a new accounts definition:

[accounts/550e8400-e29b-41d4-a716-446655440000]
 name = john
 type = application

2.5.5. Upgrading from version 3.X.X to a newer one

On Windows, you can choose to upgrade the system by running the self installing archive. This is similar to a new installation, but you will have to use the same installation path as the one in your current installation.

It is very important that you check the latest version and changes, as well as recommended upgrade procedures in the Server Release Notes.

  • Before proceeding with the upgrade, ensure the system is in maintenance mode and there are no active file transfers.
  • Stop the SFTPPlus service.
  • Copy the configuration file to a backup location.
  • Run the installer and use the same installation path as the one of your current version.

2.5.6. SFTPPlus manual upgrade on Linux and Unix

To upgrade SFTPPlus to the latest version, you have to stop its running service, then extract and copy the new files over the existing installation sub-directory. Before proceeding with the upgrade, ensure you have a backup copy of the server configuration file.

To find out more about the latest version and changes from your version to latest release, please consult the Server Release Notes.

2.5.7. Upgrading from trial version 3.X.X

Once you have obtained the full version of the software, the upgrade methods for Windows and Linux are the same as above instructions under “Upgrading from version 3.X.X to a newer one” and “SFTPPlus manual upgrade on Linux and Unix”.