SFS2X Docs / GettingStarted / migration-tool
» SmartFoxServer 2X Migration Tool
The Migration Tool is a command line utility that automates the transfer of settings from an old version of the server to a new one. The tool is available as a separate download for SFS2X 2.13 and will be bundled with future versions of the server.
With the Migration Tool it takes a few seconds to rebuild a server after having installed a new release. The Tool can migrate all previous server settings, zone definitions, extension files, local data and lots more.
At the time of writing this documentation (Sep. 2017) the latest release of SmartFoxServer 2X is 2.13.x and the Migration Tool supports porting older settings from any release since 2.11.x.
» Migration overview
There are several categories that the Migration Tool covers:
- Server Settings: most files found under SFS2X/config/ including core settings, logging, bad words list, web server configuration
- Zone Definitions: all zones defined under SFS2X/zones/
- Extensions: all deployed extensions
- Server Data: banned users, local buddy lists, uploads, room data
- Web Files: servlets and static content deployed under SFS2X/www/
Additionally it can take care of migrating a previous license code and the SSL certificate.
Using command line parameters you can configure all aspects of the migration process, like adding categories that are required and removing those that are not necessary for your use case. By default the Tool migrates the first three categories listed above, out of the box.
To start the process the Tool requires at least the path of the source SFS2X installation (the one that needs to be migrated) and the path of the target server (where the settings will be copied to). During the migration process files are always copied, not moved, so there is no risk of loosing data from the source installation. Also no file writes are performed on the source installation.
NOTE 1: The target of a migration should always be a newly installed SFS2X instance. We don't recommend using an already customized installation as the target of the migration process.
NOTE 2: currently the Migration Tool supports older SmartFoxServer 2X releases from version 2.11. This means that older releases will need to be migrated manually.
In the next section we're going to discuss all the command line parameters that can be used to configure the process.
» Command line parameters
The following is the complete list of all command line switches available for the MigrationTool. For every parameter we indicate if it's mandatory (M) or optional (O), what values can be passed and their default setting.
| name | type | description | values | default |
| -source | M | The path to the top folder of the source SFS2X instance that is going to be migrated | path | - |
| -target | M | The path to the top folder of the target SFS2X instance | path | - |
| -serverConfig | O | Migrates the core SFS2X configuration file | Y/N | Y |
| -zoneConfig | O | Migrates the zone definitions | Y/N | Y |
| -extFiles | O | Migrates the extensions files | Y/N | Y |
| -dataFiles | O | Migrates local data such as buddy lists, banned users, uploads, room data | Y/N | N |
| -webFiles | O | Migrates local servlets and static web content | Y/N | N |
| -licenseCode | O | Migrates the current license code (if configured) | Y/N | N |
| -analyticsDB | O | Migrates the Analytics database | Y/N | N |
| -sslCert | O | Migrates the SSL certificate (if configured) | Y/N | N |
Here's a basic example of usage passing only the mandatory source and target parameters:
./SFS2XMigrator.sh -source=path/to/source/ -target=path/to/target/
Here's a slightly more complex example where we specify also to migrate the data/ folder:
./SFS2XMigrator.sh -dataFiles=Y -source=path/to/source/ -target=path/to/target/
» Running the Migration Tool
The Migration Tool requires the JRE 8 (Java Runtime 8) to run. If you don't have it installed in your system we recommend to copy the tool into the target SmartFoxServer 2X folder. This way it will auto-detect the embedded JRE and run without any extra steps.
In other words, you just need to copy the Tool's folder to your target SFS2X installation so that it sits side by side with the SFS2X/ folder (see image below).
» Launching on Windows
Navigate to the folder where you have copied the Migration Tool. Open a Windows command prompt by holding the Shift key and right-clicking the Tool's folder, then click on "Open command window here".
At the prompt type:
SFS2XMigrator.bat <opt> -source=path/to/source/ -target=path/to/target/
Where <opt> is any other optional command as per the previous table. Finally hit Enter to execute.
» Launching on Linux
Open a terminal and 'cd' to the Migration Tool folder, then type
./SFS2XMigrator.sh <opt> -source=path/to/source/ -target=path/to/target/
Where <opt> is any other optional command as per the previous table. Finally hit Enter to execute.
» Launching on macOS
Open a terminal (from Applications/Utility) and 'cd' to the Migration Tool folder, the type:
./SFS2XMigrator.sh <opt> -source=path/to/source/ -target=path/to/target/
Where <opt> is any other optional command as per the previous table. Finally hit Enter to execute.
» Troubleshooting
The Migration Tool generates a detailed report of all its activity inside the logs/ folder. Each migration log is stored in a different file with its own timestamp.
At the end of the process a report of errors and warnings will be shown. If any issue has occurred you can inspect the logs for further details. Here's an example of a migration with errors:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Migration Status Report: FAILED! ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Total WARNS : 0 Total ERRORS: 1 --> Failure copying one or more zone file ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ For a detailed report check the log files.
Inspecting the logs shows this problem:
12:24:04,782 INFO - [Begin] ~~~~ Zone Migration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 12:24:04,782 ERROR - Failed copying zone file: SFS2X_213/SFS2X/zones/BasicExamples.zone.xml (Permission denied) 12:24:04,783 ERROR - Failed copying zone file: SFS2X_213/SFS2X/zones/CryptoBasicExamples.zone.xml (Permission denied) 12:24:04,783 INFO - [End ] ~~~~ Zone Migration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
It seems that there's a permission error with the target server and the Tool is not able to write files. We'll have to fix the file permission problem first and then try again. Retrying a migration will restart the process from the top, so all previous files will be overwritten.
» Support
If you have any questions or problems with the migration process you can get help at our support forum.