UISP - How to Upgrade from UCRM to UISP

This guide assists in migrating from live UCRM to live UISP. However, if you wish to get familiar with UISP 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 UISP and return to this guide to migrate your live UCRM properly.

Introduction

ATTENTION: Please note that as of UISP version 2.4.x it is no longer possible to restore legacy UCRM backup. In case you need to migrate from legacy UCRM to UISP, you will need to install UISP v2.3 to restore your UCRM backup.

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 UISP (or upgrade your current UISP to the latest version).
3. Enable the new CRM module in UISP with the current UCRM backup file.
4. Run the wizard designed to move the devices from CRM to UISP.
5. Check the configuration of UISP including its CRM module

UISP Modules: Network & CRM

UISP consists of two modules: Network and CRM. The Network module takes care of all devices and network management, while the CRM module provides customer management and billing. CRM Module (formerly known as UCRM) no longer contains any network-related data, such as sites, their devices, service devices (CPEs), and IPs for example. If this data is in a current UCRM instance, the Network Migration wizard can be used to move that data into the Network module and link it to the corresponding client’s services in CRM.

CRM Client’s services are linked to Network Subscribers. The client’s service provides all the “business elements” such as pricing and billing periods for example. All the “network elements”, such as devices, IP addresses, and so on, are managed in the corresponding Subscribers within the Network module.

See more in-depth information on Sites and Subscribers in UISP, and Clients and Services in CRM, along with helpful terminology in the UISP - Site & Device Management article.

Seamless Traffic Shaping and Suspension (100% automatic) are managed by both CRM and Network modules. The CRM module decides who should be shaped or suspended based on the client's services and payments history; while the Network module does the hard work for you: automatically suspends or shapes the proper IP on the gateway router. And what’s more, you don’t need to bother with any difficult router configuration at all.

Getting Started with UISP

Feel free to start with either of the two UISP modules: Network or CRM. It’s worth mentioning though, that the main system settings common for both modules are configurable only in UISP > Settings. For example, domain name, SSL certificates, mail server settings, system users management, etc. 

Connecting CRM Client Service to Network Subscriber

Once you're ready to take advantage of UISP features and start using the Shaping, Suspension, or Data Usage through both modules, you need to link the business aspect (client, service, shaping info e.g. 50 Mbps Up / 20 Mbps Down) to the network side of things (Subscribers, devices, IPs). It means you need to link your clients' services to subscribers. Only services of “Internet type” can be linked, all other “general” services like web-hosting or rentals cannot be linked. There are two ways to achieve this:

• Automatically: Any newly created client’s service is automatically connected to a new subscriber (which is automatically created for you). The only thing you need to do is to assign a device to this subscriber.
• Manually: In case your client service (CRM), as well as the client site (Network), already exists but they are not linked together, use the “Network section” of the client’s service detail page to link the service to the subscriber.

Considerations Before Migrating from UCRM to UISP

• If using a Ubiquiti EdgeRouter as your UISP Gateway, make sure you are using the latest firmware version 2.0.6 or newer. Please upgrade to this latest version using UISP 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 UISP. 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 UISP/CRM manually or automatically using a cron job.
• UISP 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 UISP versions.
• Please note that it is essential that each Client have unique IP listed in the system, without that the system cannot work properly. I.e. each Client has a unique IP and none of these IPs can be used on another Client or Site.
• UISP is able to perform advanced network features (traffic shaping, suspension, NetFlow) only for IP addresses of devices that are added to UISP. In case you need to use those features for 3rd party devices (you have clients who are using their own endpoint routers) please be aware that in UISP this will only work for static IP addresses.
• UISP will automatically upgrade the firmware on your UI devices.

What to Expect from the UCRM to UISP Upgrade Process

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

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

Steps: How to Upgrade from UCRM to UISP

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 UISP’s CRM module in order not to run two CRM systems at the same time to avoid duplicate invoicing and other issues.

1.1. As of UCRM v2.16+, go to http://<yourdomain>/upgrade-to-uisp or use the "Upgrade to UISP" 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.

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

2. Install UISP

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

2.2. If you are already a UISP user and you have some data and devices configured in UISP, it’s recommended to create a backup file of your UISP instance at this point. Please note that if you have a new UISP instance, you will be offered to upload a Backup during the setup wizard. Please note that only UISP backup can be uploaded there. In case you want to upload UCRM backup in UISP format from your previous instance, you have to do it in CRM > System > Tools > Backup.

3. Verify that the New CRM Module in UISP is Enabled

3.1. Go to Network > Settings > General > UISP ISP 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 UISP 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 UISP. 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 UISP 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 UISP, 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 UISP. However, there might be some ambiguous items that 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 matches multiple Network Client Sites (e.g. the CRM service ends up with 2 devices that belong to two different Client Sites in UISP).
  • Multiple services match a single Client Site (e.g. you added all your CPEs into a single Client Site in UISP).
  • CRM services match Sites in UISP instead of Client Sites and vice versa, or former UCRM Sites match Client Sites in UISP.
  • Mismatching IPs (e.g. one of the service device IP matches one Client Site in UISP, 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 UISP. Additionally, devices with non-unique Management IP are skipped by the wizard.

Optional step: Force Mode for Service Devices

This option is available only when at least one UCRM service device exists also in UISP. This mode for migrating UCRM service devices can be useful for those who have been using UISP along with UCRM, while the UISP network data related to Client Sites is incorrect. For example, if you have one Client Site containing 300 devices in UISP 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 UISP. 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 UISP based on the UCRM data, regardless of the devices and network topology in UISP.
• The existing UISP Client Sites won’t be deleted. Note that this means that the number of Client Sites in UISP can be doubled.
• No device duplicates are created, the existing UISP 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 UISP. 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.

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 UISP 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 UISP

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

Note that the new UISP hostname will be used by the payment gateways to communicate with your UISP’s 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 UISP with some connected devices. The change of its hostname will require to reconnect the devices, read more in this guide.

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

• Configure UISP Mailer settings which are used by the CRM module as well in Network > Settings > General > 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 > General > 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 UISP server if you used the UCRM backup file including these keys.
• Configure the Google map keys in UISP.

5.4. Configure the UISP Home Page.

• The new UISP 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 UISP home page when the domain name is accessed without any suffix /crm or /nms by configuring it in Network > Settings > General > 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 UISP homepage selected.

5.5. UISP and CRM Administrators:

All the UISP and CRM administrators can sign in using the same administrator's screen at yourdomain/nms. All the UCRM accounts (usernames/passwords) from your previous UCRM will work in this UISP login screen, except the super-admin account. If there is just one super admin in UISP 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 UISP app, configured during the first run of UISP.

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

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

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

• Follow the guide to enable the suspension feature in UISP 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 UISP as well, just make sure the destination IP for NetFlow packets is aiming at the UISP server IP.
• The NetFlow data usage measured by UCRM won’t be removed from the CRM module. But as of UISP integration, 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 UISP Network).

5.9. If you were using UCRM Plugins:

• All of your UCRM Plugins and their data will be migrated into UISP's 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 UISP.
• To do so, go to CRM > System > Plugins and click "update" to all of your existing plugins.

Important Notes

• Backward compatibility for Client Zone URL and payment processing URL is ensured automatically by UISP. 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 UISP 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 UISP: device stats, logs, backups, and charts.
• Please note that if you migrate to UISP Cloud, your UCRM Plugins won’t be migrated automatically due to security reasons, however, the configuration of your plugins is kept and you can easily reinstall them manually. Also, note that custom made plugins (unofficial versions) are not allowed in the UISP Cloud. In case you want to have a custom plugin in UISP Cloud, you are more than welcomed to send us a pull request with your plugin. As soon as we approve it, it will be available even for the Cloud version.