How to migrate from NimOS to Edge OS #

This document will guide you through the process of migrating a Net Insight Nimbra appliance that has previously been running NimOS to Edge OS.

See the manual flow at the end for Edge versions older than R4.2.0.

Prerequisites #

• A compatible appliance (Nimbra 414 revision B)
• The appliance is already connected to Nimbra Edge and visible in the Appliances list
• A release build of Nimbra Edge, R4.2.0 or later
• A Super user, or an Admin user who owns the group the appliance belongs to
• Internet connectivity for the appliance to download the migration tool from artifacts.nimbra.io

Limitations #

• The migration tool is “best effort” meaning it might fail and leave the appliance in a broken state. If that happens, you may need physical access to reinstall Edge OS using a USB installer.
• The migration is one-way meaning there is no supported path back to NimOS.
• The migration tool will not preserve any existing configuration from NimOS other than what is listed below.

What gets migrated #

The migration copies over only the settings needed for the appliance to come back on the network and reconnect to Nimbra Edge:

• IPv4 address(es) and netmask
• DHCP on/off
• Default gateway
• MTU
• Administrative status — interfaces that were down in NimOS are not migrated
• DNS servers (nameservers)
• Hostname
• Edge URL, group secret, and the “allow self-signed certificate” setting

Nothing else is migrated.

Migrate from Network Manager #

Prepare for migration #

Before starting the migration, note down any configuration that you wish to recreate.

Delete all inputs and outputs configured on the appliance. The migration is blocked while the appliance still has any inputs or outputs, and the error message will list the streams that are in the way.

Start the migration #

1. In Network Manager, go to Appliances and open the appliance you want to migrate.

2. In the toolbar at the top of the appliance page, click the Upgrade button (its tooltip reads Migrate to Edge OS).

   

3. Read the warning in the confirmation dialog.

4. Click Migrate to confirm.

The appliance is cordoned so no streams are scheduled onto it, it downloads the migration bundle, and it reboots to apply the update. The migration should take around 10 minutes but may take longer depending on the network.

Because the appliance’s IP settings and Edge connection are preserved, it reconnects to Nimbra Edge on its own after the reboot — you do not need to remove and re-add it manually.

It is possible to migrate multiple appliances at once from the Appliances view.

Change default password #

After the migration has completed, you should be able to reach the appliance on its IP address and through the Nimbra Edge Appliance Proxy. The default username and password for the appliance is, like in NimOS, admin and neti. You must log in and change the password.

Remove the cordon #

The appliance stays cordoned after the migration. To allow streams on it again, open the appliance, clear Cordon appliance under Settings and save.

Fallback: manual migration via NimOS #

Use this flow when the Network Manager migrate button is not available — for example on clusters older than R4.2.0, or when recovering an appliance that is no longer connected to Edge. It drives the migration from the appliance’s own NimOS user interface instead.

The manual flow does not check the hardware model. Run it only on a Nimbra 414 revision B; revision A hardware does not support Edge OS.

Prerequisites #

• A compatible appliance (Nimbra 414 revision B)
• Internet connectivity for the appliance to download the migration tool
• A manual backup of any configuration that you wish to recreate after the migration

Prepare for migration #

Before starting the migration, note down any configuration that you wish to recreate.

Delete any inputs, outputs, and tunnels configured on the machine from Edge.

Ensure Edge secret #

If you wish your appliance to reconnect automatically to Nimbra Edge after the migration, it needs to be connected using a group secret (Generated from the Groups page) and not an appliance token (Generated from the Appliance page).

To get your group secret in Network Manager go to: Settings > Groups, select your group and click COPY SECRET. You can then replace the appliance token with the group secret in the machine’s user interface under System > Edge settings. If the appliance is already registered using the group secret, you do not need to change anything.

Appliance tokens generated from the Appliance list are not compatible with the migration as they are single-use and are invalidated when the appliance re-registers after the migration.

Start the migration #

1. In the NimOS user interface, go to System > Software > Install new release...
2. Enter the following URL:

https://artifacts.nimbra.io/api/artifacts/edgeos/v1/nimos-migration/latest

3. Click Install
4. Click Bring installed images into service

The migration should take around 10 minutes but may take longer depending on the network.

After clicking Install, if you click any other button than Bring installed images into service, the user interface will enter an inconsistent state and may show errors. You must then reboot the machine using:

System > Basic settings > Restart > Restart immediately (minimum downtime).

This does not affect the migration process and is only an inconsistency in the user interface.

Remove appliance from Edge #

Immediately after the appliance has started rebooting to apply the update, it needs to be removed from Edge to allow it to reconnect with its new identity. Go to Appliances, select the appliance and click the Bin icon.

Change default password #

After the upgrade has completed, you should be able to reach the appliance on its IP address and through the Nimbra Edge Appliance Proxy. The default username and password for the appliance is, like in NimOS, admin and neti. You must log in and change the password.

Done #

You can now manually recreate any configuration that you noted down before the upgrade.