UNMS v1 - How to Upgrade from UCRM to UNMS


This article provides the steps to migrate from a live UCRM instance to a live UNMS instance.

This guide assists in migrating from live UCRM to live UNMS. However, if you wish to get familiar with UNMS with its CRM module, it is possible to test it in a sandboxed VM beforehand. When testing it is important to make sure you are not running two CRMs in production mode at the same time to avoid duplicate invoices and other unwanted consequences. To play it safe, it’s recommended to turn off these features in the sandboxed CRM’s System Settings: Billing, Payment Gateways, Mailer, and Plugins. When you are done with testing, drop the whole sandboxed CRM module or the whole testing UNMS and return to this guide to migrate your live UCRM properly.

Table of Contents

  1. Introduction
  2. Considerations Before Migrating from UCRM to UNMS v1
  3. What to Expect from the UCRM to UNMS Upgrade Process
  4. Steps: How to Upgrade from UCRM to UNMS v1
  5. Important Notes


Back to Top

The process of the migration that will be followed in this article is:

  1. Prepare the current UCRM for the migration and turn it off.
  2. Install UNMS v1 (or upgrade your current UNMS to this new version).
  3. Enable the new CRM module in UNMS with the current UCRM backup file.
  4. Run the wizard designed to move the devices from CRM to UNMS.
  5. Check the configuration of UNMS including its CRM module

Considerations Before Migrating from UCRM to UNMS v1

Back to Top

  • Make sure you are using the latest firmware version 2.0.4 or newer on your gateway EdgeRouter. Please upgrade to this latest version using UNMS or the router's web interface. Note that you can use another router device or firmware version but the new fully automatic Shaping, Suspension, and NetFlow features won’t be enabled.
  • Suspension on Mikrotik routers will not be enabled in UNMS v1 (workaround: use the existing UCRM Plugins).
  • CRM backup sync to Dropbox has been removed, it will be replaced by another service soon. (workaround: it's still possible to back up your UNMS/CRM manually or automatically using a cron job or CRM plugin.)

What to Expect from the UCRM to UNMS Upgrade Process

Back to Top

The upgrade and migration process ensures that all the devices are present only in the Network module, all the sites are moved to the Network module, and the CRM Client’s Services are linked to appropriate Network Client Sites. In other words, all the devices configured manually in UCRM won’t be lost, they will be moved to UNMS Network module, or just skipped when the given device is already there.sites_in_network.png

  • All the existing UCRM Site Devices will be moved into the UNMS Network module automatically. If a device is already there, it will be detected by matching MAC or IP and no duplicate will be created. This is applied to all 3rd party devices as well, they will be migrated to UNMS as "black boxes".
  • Sites missing in UNMS will also be created automatically. The "missing site" is the site where all its devices are present only in UCRM and not in the UNMS Network.
  • The migration wizard will never modify or delete the existing Sites or Devices in UNMS. Additionally, no duplicate Sites or Devices will be created during the process.


  • All the existing UCRM Service Devices will be moved into the UNMS Network module automatically. If a device is already there, it will be detected by matching MAC or IP and no duplicate will be created.
  • CRM Client Services will then be linked to the corresponding Network Client Sites. Only 100% matches are linked automatically, i.e. only when all the previous service devices (in CRM) are matching to all the client site devices (in Network). The missing Client Sites are also created automatically.
  • The primary device matching key is MAC, the secondary matching key is IP and it is used only when the MAC value is empty.
  • If you were using UCRM and UNMS simultaneously and the devices or network topology were configured manually, there might be some ambiguous cases disabling automatic linking of client’s service (CRM) and client sites (Network).
    For example when the CRM Service is having 2 devices which match to devices of 2 different Network Client Sites. The network migration wizard will help you solve these cases but you can also "fix" the data in your current UNMS or UCRM beforehand or skip the migration tool and match all services manually.

Steps: How to Upgrade from UCRM to UNMS v1

Back to Top

1. Prepare the current UCRM instance for migration.

These are the recommended steps to prepare the current data and the whole UCRM system for migration. The goal is to terminate the current UCRM instance properly and migrate the data into the new UNMS’ CRM module while not running two CRM systems at the same time to avoid duplicate invoicing and other issues.

User Tip: Choose a part of a day with low activity, when there are not many clients in the client zone, no automatic invoices are being created, no emails waiting in the sending queue, etc.

1.1. As of UCRM v2.16+, go to http://<yourdomain>/upgrade-to-unms. (When UNMS v1.0.0-stable is released, you will also see the "Upgrade to UNMS" button in the top-left corner of the UCRM interface.)

1.2. Follow the steps shown on that page to properly terminate billing and online payments, and to remove the shaping and suspension rules from the HW.

NOTE: This is the correct way of moving your online payments to UNMS’ CRM. It’s ok to keep UCRM switched off while the new UNMS’ CRM is not yet online. The online payment gateways repeat the notifications for many times until the system is back online. However, if you are migrating to a completely new domain, you might need to check the configuration of the payment gateways.

1.3. By the end of the instructions provided in the UCRM "UNMS Integration" page, you should have the Backup in UNMS format ready for the next step and your production UCRM should be turned off. Make sure you have downloaded the "Backups in UNMS format" (Only this format can be used for upgrading to UNMS' CRM module, Check out the bottom side of the System > Tools > Backup page)

2. Install UNMS v1

2.1. Install UNMS v1 or upgrade your existing UNMS to this version. Follow the UNMS installation guide or use the in-app upgrade tool in your existing UNMS.

2.2. If you are already a UNMS user and you have some data and devices configured in UNMS, it’s recommended to create a backup file of your UNMS instance at this point.

3. Enable the new CRM module in UNMS

3.1. Open the CRM module inside UNMS v1 (using the CRM button in the top left-hand corner). Then, in the setup screen, proceed to restore the UCRM v2 backup file, which can be downloaded from your current UCRM in System > Tools > Backup - section "Backups in UNMS format".


3.2. As soon as the backup is restored, log in to the CRM module and continue with the Network Migration Wizard.

4. Follow the Network Migration Wizard.

The Network Migration Wizard will be automatically skipped if there were no devices in the old UCRM instance since there would be nothing to migrate to UNMS. If the Network Migration Wizard is launched however, go through the two sections: migration of Sites, and the migration and binding of Services to Client Sites.


A few pointers:

  • If you haven't been using UNMS before, the migration will be very simple: all of the "network data" will be moved to the Network module by clicking "Start Migration".
  • If you have been using UNMS, pay attention to the migration plan offered by the wizard. Most of the data will be just moved or linked with the existing entities in UNMS. However, there might be some ambiguous items which cannot be migrated or linked automatically. Please follow the information and tooltips shown for these cases. These are examples of some cases which wouldn't be migrated automatically and which might need your attention:
    • A single CRM service match multiple Network Client Sites (e.g. the CRM service ends up with 2 devices which belong to two different Client Sites in UNMS).
    • Multiple services match a single Client Site (e.g. you added all your CPEs into a single Client Site in UNMS).
    • CRM services match Sites in UNMS instead of Client Sites and vice versa, or former UCRM Sites match Client Sites in UNMS.
    • Mismatching IPs (e.g. one of the service device IP matches one Client Site in UNMS, while the second IP of the same device belongs to another Client Site).
    • CRM services that have no devices will not be bound to any Client Site.
    • Similarly, service devices with neither an IP nor a MAC or unattached service devices are not migrated to UNMS. Additionally, devices with non-unique Management IP are skipped by the wizard.
NOTE: UCRM service devices having more than one IP address (including the management IP) are migrated as separate devices for each IP to ensure no IP is lost during the migration, and the shaping and suspension feature will continue to work unaffected. If these IPs belongs to the same Ubiquiti device, UNMS will recognize this and merge these devices into one automatically.


Force Mode for Service Devices

This mode for migrating UCRM service devices can be useful for those who have been using UNMS along with UCRM, while the UNMS network data related to Client Sites is incorrect. For example, if you have one Client Site containing 300 devices in UNMS which is obviously wrong. If you think your UCRM data pertaining to Service Devices is better (for the example mentioned it might be: 300 services, having one device each), you can use it to "force push" the UCRM data into UNMS. This mode is not applied to UCRM Sites and the migration of Sites and their devices is not affected by this mode. More details about Force Mode:

  • This option is available only when at least one UCRM service device exists also in UNMS.
  • When turned on, all the Client Sites and their devices are pushed into UNMS based on the UCRM data, regardless of the devices and network topology in UNMS.
  • The existing UNMS Client Sites won’t be deleted. Note that this means that the number of Client Sites in UNMS can be doubled.
  • No device duplicates are created, the existing UNMS devices will be just relocated from Client Site or Site to the proper Client Site according to the CRM info.
  • To sum it up, this Force Mode never deletes anything and it never creates any duplicate devices in UNMS. It will just create a non-existing Client Site for each UCRM service according to UCRM data and create the missing devices or relocate the existing ones.
User Tip: Before you start the migration, click on the Force Mode toggle to preview the planned actions. When you are satisfied with the proposed migration plan, start it up. When completed, go to finalize the UNMS configuration.

It is also possible to skip this wizard and manage the binding of services and client sites on your own one by one. If you prefer this method, click "I want to do this manually". Remember that you can easily revert the results of the migration by restoring UNMS from a backup file and using the UCRM's migration file again.

5. Check and finalize UNMS configuration

5.1. Check that the bindings between the CRM services and the Network Client Sites are correctly set.

  • Feel free to finalize the bindings manually: go to the CRM client service page and bind some Client Site in the “Network” box.

5.2. Use the old UCRM hostname for the new UNMS

It’s highly recommended to use the same hostname of the previous UCRM for the new UNMS to ensure smooth transition of all CRM features and for seamless replacement of the client zone. Go to Settings > UNMS > UNMS Hostname.

Note that the new UNMS hostname will be used by the payment gateways to communicate with your UNMS’ CRM and also your clients might be used to the previous hostname, and might be still using the URLs in old emails sent from UCRM.

If you were already using UNMS with some connected devices. The change of its hostname will require to reconnect the devices, read more in this guide.

WARNING: If you use another hostname for UNMS (e.g. when migrating to the UNMS cloud version), you should reconfigure the settings of your payment gateways, go through the config guide for your gateway from the first step. Otherwise the payment gateway will try to send the payment info to a wrong URL.

5.3. If you are new to UNMS, check its configuration.

  • Configure UNMS Mailer settings which are used by the CRM module as well in Settings > UNMS > Mail Server(The Mailer settings haven't been migrated from your old UCRM.)
  • Configure the SSL certificate. Establish a new Let’s Encrypt certificate in Settings > UNMS or if you need to use the SSL certificates from your previous UCRM, go to /home/ucrm/data/ucrm/ssl/ on your previous UCRM server, or you can also find them migrated at /home/unms/data/ucrm/ssl/ on your current UNMS server if you used the UCRM backup file including these keys.
  • Configure the Google map keys in UNMS.

5.4. Configure the UNMS Home Page.

  • The new UNMS has 2 separate login screens:
    • For both Network and CRM administrators (at yourdomain/nms), which is the default option.
    • For clients accessing the client zone (at yourdomain/crm).
  • You can choose which should be used as the default UNMS home page when the domain name is accessed without any suffix /crm or /nms by configuring it in Settings > UNMS > Home page.
  • If you have been providing your clients with access to the client zone in your old UCRM, it’s recommended to set the client zone login screen (the second option) as the default login screen.
  • Note that payment gateways are not affected by this choice, the one-time payments and subscriptions will work regardless of the UNMS homepage selected.

5.5. UNMS and CRM Administrators:

NOTE: As of this version, the CRM login screen works only for the clients to access the Client Zone.

All the UNMS and CRM administrators can sign in using the same administrators screen at yourdomain/nms. All the UCRM accounts (usernames/passwords) from your previous UCRM will work in this UNMS login screen, except the super-admin account. If there is just one super admin in UNMS and one in CRM, these super-admins accounts are considered as being for the same person and are merged into one. This user will need to use the username/password set in the UNMS app, configured during the first run of UNMS.

5.6. If you were using the Shaping feature in the old UCRM v2.X:

The UNMS Network module will take care of it: just turn it on for the gateway router in UNMS v1.0. For an easy configuration, use this UNMS Traffic Shaping guide.

5.7. If you were using the Suspension feature in the old UCRM v2.X:

  • Follow the guide to enable suspension feature in UNMS settings.
  • You might also need to recheck the configuration of Excluded Destination IP for suspended connections. To do so, you need to go Settings > Network, select the appropriate active gateway and click the Edit link on the right. A popup will be shown with the 'Allow IP addresses' field.

5.8. If you were using the NetFlow feature in the old UCRM v2.X:

  • You can continue using it in the new UNMS as well, just make sure the destination IP for NetFlow packets is aiming at the UNMS server IP.
  • The NetFlow data usage measured by UCRM won’t be removed from the CRM module. But as of UNMS v1, any new usage data shown in the CRM module are obtained from the Network module automatically (only for client’s services bound to a client site in UNMS Network).

5.9. If you were using UCRM Plugins:

  • All of your UCRM Plugins and their data will be migrated into UNMS' CRM module using the UCRM backup file (if you haven’t explicitly excluded Plugins from the creation of backups). However, all of these plugins are turned off and need to be upgraded manually to the new version compatible with the CRM module in the new UNMS v1.
  • To do so, go to CRM > System > Plugins and click "update" to all of your existing plugins.

Important Notes

Back to Top

  • Backward compatibility for client zone URL and payment processing URL is ensured automatically by UNMS. For example, clients going to yourdomain/client-zone will be automatically redirected to yourdomain/crm/client-zone. You just need to make sure you are using the same domain for UNMS as the old UCRM instance was using.
  • Files uploaded to System > Tools > Webroot are now accessible using a new URL starting with /crm. For example: “wispdomain.com/crm/clients-guide.pdf”. You may need to change the URL used in your documents or email templates.
  • The following data is not transferred from the old UCRM to UNMS: device stats, logs, backups, and charts.
  • If you migrate to UNMS Cloud, the UCRM Plugins cannot be migrated automatically due to security reasons (workaround: you need to reinstall the plugins manually). Also, note that custom made plugins (unofficial versions) are not allowed on the UNMS Cloud version.

We're sorry to hear that!