Package: nislmigrate
NI-SystemLink-Migration toolnislmigratenislmigrateis a command line utility for migration, backup, and restore of supported SystemLink services.Prerequisites1. SystemLinkThis tool offically supports migration between SystemLink versions 21.0, 21.1, 21.3, & 21.5. Other versions have not been tested.We assume the server you are migrating to is clean with no data. Migrating to a server with existing data will result in data loss.Services that are supported with any caveats and exceptions are detailed in theSupported Servicessection below.This tool assumes a single-box SystemLink installation.This tool must be run on the same machines as the SystemLink installations.2. PythonThis tool requiresPython 3.8to run.The documentation in this repository assumes Python has been added to yourPATH.InstallationThe latest released version of the tool can be installed by running:pipinstallnislmigrateUsageBackupTo backup the data for a service listed in theSupported Servicessection run the tool with elevated permissions and use thecaptureoption with the corresponding flag for each of the services you want to back up (e.g.--security):nislmigratecapture--securityThis will backup the data corresponding with each service into the default migration directory (C:\Users\[user]\Documents\migration\). You can specify a different migration directory using the--dir [path]option:nislmigratecapture--security--dirC:\custom-backup-locationTo backup the data for all supported services at once, the--allflag can be used instead of listing out each individual service. Using--allwill require that you include the--secretflag for services that require encrypting backed up data for security:nislmigratecapture--all--secret<password>Restore:warning: Restoring requires the--forceflag to explicitly allow overwriting the existing data on the server. Without it, the command will fail.To restore the data for a service listed in theSupported Servicessection run the tool with elevated permissions and  use therestoreoption with the corresponding flag for each of the services you want to restore (e.g.--security):nislmigraterestore--securityThis will restore the data corresponding with each service from the default migration directory (C:\Users\[user]\Documents\migration\). If your captured data is in a different directory that can be specified with the--dir [path]option:nislmigraterestore--security--dirC:\custom-backup-locationTo restore the data for all supported services at once, the--allflag can be used instead of listing out each individual service. Using--allwill require that you include the--secretflag for services that require encrypting backed up data for security:nislmigraterestore--all--secret<password>ModifyTo modify entries in the database in-place without doing a restore run the tool with elevated permissions and use themodifyoption.modifycurrently only works to modify the files' service database entries.Updating after moving filesAfter moving the storage location of the files uploaded to the Files service the database will need to be updated to reflect the new location. The--files-change-file-store-rootargument can be used for this, either as part of arestoreoperation or in-place as part of amodifyoperation. When used withrestorethe old root location is inferred from the database. When used withmodifythe old root location must be specified with the--files-file-store-rootargument.:warning:modifywill modify the database directly. A backup of the database should be taken before any modifiations usingnislmigrate capture --files --files-metadata-onlyTo modify the files root location after moving the files to a new drive:cp-r-fC:\old\file\storeX:\new\file\store
nislmigratemodify--files--files-change-file-store-rootX:\new\file\store--files-file-store-rootC:\old\file\storeTo modify the files root location after moving the files to an S3 bucket:awss3syncC:\old\file\stores3://my-systemlink-bucket/my-files
nislmigratemodify--files--files-change-file-store-roots3://my-systemlink-bucket/my-files--files-file-store-rootC:\old\file\store--files-switch-to-forward-slashesMigration:warning: Server B must be a clean SystemLink installation, any existing data will be deleted.To migrate from one SystemLink server instance (server A) to a different instance (server B):Install the migration tool onserver Aandserver B.Follow the backup instructions to backup the data fromserver A.Copy the data produced by the backup ofserver Aonserver B.Warning:Ensureserver Bis a clean SystemLink installation, any existing data will be deleted.Follow the restore instructions to restore the backed up data ontoserver B.DevelopmentSeeCONTRIBUTING.MDfor detailed instructions on developing, testing, and releasing the tool.Supported ServicesThe services that can be migrated with this utility along with short descriptions can be listed by running:nislmigratecapture-hMost services require migrating the--securityservice at the same time for the migration to be successful, and some services have additional dependencies which are listed in the table below.Supported ServiceArgument FlagAlso requires migratingAdditional NotesSecurity--securityUser Data--userdata--securityNotifications--notification--securityFile Ingestion--files--security- Must migrate file to the same storage location on the new System Link server.- To capture/restore only the database but not the files themselves, use--files --files-metadata-only. This could be useful if, for example, files are stored on a file server with separate backup.- If files are stored in Amazon Simple Storage Service (S3), use--files --files-metadata-only.- If the file store path is different on the server you are restoring to, use the--files-change-file-store-root [NEW_ROOT]flag to update the metadata of all files to point to the new root during a restore operation.- If you have uploaded your local files to S3 and need to update the file path metadata, use--files-change-file-store-root [S3://<bucket-name>/<folder-path-if-applicable>]along with--files-switch-to-forward-slashes.Repository--repo--security- Feeds may require additional updates if servers used for migration have different domain namesDashboards and Web Applications--dashboards--securitySystem States--systemstates--security- Feeds may require additional updates if servers used for migration have different domain names- Cannot be migrated between 2020R1 and 2020R2 serversTag Ingestion and Tag History--tags--securityTag Alarm Rules--tagrule--security--notificationAlarm Instances--alarms--security--notification- Cannot be migrated between 2020R1 and 2020R2 serversAsset Alarm Rules--assetrule--security--notificationAsset Management--assets--security--files--tagsTest Monitor--tests--security--fileSystems--systems--security--tags--file-WARNING:Captured systems data contains encrypted secret information and should not be copied to a publicly accessible location.- To capture/restore systems, a secret must be provided using the--secret <SECRET>command line flag. Captured systems data will require the same secret to be provided as was provided during capture in order to be able to decrypt sensitive data.There are plans to support the following services in the future:OPC UA Client:--opcTDM--tdmCloud Connector--cloud