UNMS - 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.6 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 available.
  • Suspension on Mikrotik routers is not supported in UNMS v1. Workaround: use the existing UCRM Plugins.
  • CRM backup sync to Dropbox has been removed and replaced by the Dropbox plugin. It is also possible to back up UNMS/CRM manually or automatically using a cron job.
  • UNMS v1 works directly with devices instead of IP. For Ubiquiti devices, it can easily gather all available IP addresses, but for 3rd party devices, it is necessary to insert them manually. Please note that IP ranges can no longer be set to client's devices, only single IPs can now be inserted manually.
  • We recommend only upgrading to stable UNMS versions.

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 the UNMS Network module, or just skipped when the given device is already there.sites_in_network.png

  • All the existing UCRM Site/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. This is applied to all 3rd party devices as well, they will be migrated to UNMS.
  • 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.


  • 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.
  • CRM will never modify or delete the existing sites or devices in UNMS. Additionally, no duplicate Sites or Devices will be created during the migration process.
  • The primary device matching key is the MAC ID, 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 has two devices that match devices of two 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 in order not to run 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 or use 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, please make sure you check the configuration of the payment gateways according to the in-app guide on <yourdomain>//crm/help/online-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. See the bottom 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. Verify that the New CRM Module in UNMS is Enabled

3.1. Go to Network > Settings > UNMS > UNMS Mode and make sure the ISP mode is enabled. Now you can enter the CRM Module through the top menu bar.


3.2. Once you are in the CRM module, go to System > Tools > Backup > Restore your UCRM v2 and restore the backup in UNMS format from your previous UCRM v2 instance. Once the backup is restored, 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, 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 that 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.

USER TIP: In case it is necessary, you can re-run the migration wizard by doing the following:

  • If using UNMS version 1.1.x and up:Perform a factory reset of the CRM data in CRM > System > Tools > Factory reset.
  • If using UNMS versions older than 1.1.x: Toggle the Sandbox mode on and off to trigger the wizard.

Optional step: Force Mode for Service Devices

This option is available only when at least one UCRM service device exists also in UNMS. 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 incorrect. 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:

  • 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".

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 Network > Settings > UNMS > UNMS Hostname/IP.

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 Network > Settings > UNMS > Mail Server. Note that the Mailer settings haven't been migrated from your old UCRM.
  • Configure the SSL certificate. Establish a new Let’s Encrypt certificate in Network > Settings > UNMS > SSL Certificate. 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 Network > 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: Please note thatthe CRM login screen only works for clients attempting 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 Traffic 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 Network > 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.
Was this article helpful?
5 out of 9 found this helpful
Can't find what you're looking for?
Visit our worldwide community of Ubiquiti experts for more answers
Visit the Ubiquiti Community