Upgrading to New Version

If you already have an installation of Cisco Modeling Labs 2.x, you may be able to upgrade your existing installation to the latest release using the upgrade package for the new release. Be sure to check the Release Notes for Cisco Modeling Labs to ensure that an in-place upgrade to this release is supported from your existing, installed release.

In particular, your existing CML instance must be CML 2.3.0 or higher to upgrade to the latest CML release. If an in-place upgrade is not supported from your current release, you cannot use these upgrade instructions. See the Release Notes for Cisco Modeling Labs for your options to migrate your existing CML server to the latest release.

Note

CML-Enterprise Cluster upgrade is generally supported whenever in-place upgrade is supported. When upgrading from release 2.4.0, which introduced cluster support, each compute host’s upgrade must be run separately, starting with the controller. Since the 2.5.0 release, compute host CML software upgrades are automatically initiated by the controller’s upgrade. Instructions below have additional notes regarding cluster-specific steps, which may be skipped for standalone All-in-One installations.

Attention

If you have made modifications to the system (copying images to different places, manually changing configuration files, etc.), back up those changes prior to starting the upgrade. You may need to re-apply those changes after the upgrade has finished.

Before you start, download a copy of the pkg.zip file for the CML controller to your local machine. See Downloading Files for CML Installation for details on how to download the files for this release. If no pkg.zip file is available, then download the .deb file. If the release provides neither a pkg.zip nor a .deb file, then in-place upgrades to that release are not supported.

The .pkg file usually contains any new OS packages which are required in that release. If installing using the .deb file, these new dependencies must be accessible to the CML instance for download from official OS repositories, or an alternative source you configured while running an offline or air-gapped CML-Enterprise installation.

Attention

Prior to initiating the upgrade, all labs must be stopped. Upgrades will be rejected otherwise. Coordinate with all lab users to ensure their work is saved. The lab nodes will not be wiped, but they may contain runtime-only configuration which is not written to disk and may be lost. For example, for all nodes running IOS XE, enter the command copy running-config startup-config or write to save what can be saved.

To perform an in-place upgrade, use the following procedure. After the CML upgrade completes, we also recommend updating the base OS packages if updates are available to your installation. Read all the instructions prior to performing the procedure, and contact support if you have concerns or additional questions.

Applying Software Updates for the Base OS - Recommended (online upgrades only)

Log into the System Administration Cockpit as the system administrator account. See Logging into the System Administration Cockpit.

In the System Administration Cockpit, click Services in the navigation bar on the left side of the page.

On the Services page, click the Targets tab at the top of the page.

Scroll to the bottom of the Services ‣ Targets pane in the System Administration Cockpit and click virl2.target.

The System Administration Cockpit will switch to the Services > virl2.target page.

Click on the services menu (the three vertical dots at the end of the CML2 Network Simulation System line).

A menu appears with actions related to the current service target.

Click Stop in the menu to stop the services for this target.

The Status will change to Not Running once the services stop. You can now apply the system’s software updates.

In the System Administration Cockpit, click Software Updates in the navigation bar on the left side of the page.

Once the page refreshes the package list, click the Install All Updates button.

This step may take several minutes to several hours to complete, depending on the speed of your network and the selected Ubuntu Linux package mirror.

The system updates are complete, and your CML server is running the latest packages. If the system requires a reboot after the updates are complete, the page will provide a Restart Now button. If you do not have to reboot after the Software Updates are complete, then be sure to restart the virl2.target.

If a reboot is recommended, click the Restart Now button to restart your CML server.

Your system will reboot, and the virl2.target should start automatically.

Restarting virl2.target - skip these steps if a reboot was required

If a reboot was not required, navigate to Services ‣ Targets ‣ virl2.target in the System Administration Cockpit once the system updates are complete.

The System Administration Cockpit will switch to the Services > virl2.target page.

Click on the services menu (the three vertical dots at the end of the CML2 Network Simulation System line).

A menu appears with actions related to the current service target.

Click Start in the menu to start the services for this target.

The Status will change to Active or Running once the services start.

On a Cluster installation, you need to apply OS package updates for each compute host separately. Switch to each compute host in turn and repeat the OS package update steps.

Procedure

If the upgrade file is a .zip file, first unzip the file and extract its contents.

  • On Windows, use the File Explorer, 7-Zip, WinZip, or a similar program.

  • On macOS, use the Archive Utility app or the unzip CLI command.

If you downloaded a .deb file for the new release, then you do not need to unzip anything.

Optional: Cisco signs all CML software before release. If you downloaded the pkg.zip file and extracted its contents, find the .pkg and pkg.README files from the zip file. Open the pkg.README in a text editor and follow the instructions in that file to verify the .pkg file’s signature.

CML Controller Upgrade - CML UI steps for image upload

Log into the CML server UI.

In the top-most menu panel, click Tools ‣ System Upgrade.

Click the Browse button, and select the upgrade package from your local system, such as cml2_2.3.1_build29_amd64.pkg or cml2_2.3.1_build29_amd64.deb. Note that if you downloaded a pkg.zip file, you should upload the .pkg file that you extracted from the zip file.

Click the Upload Image button and wait for the file to finish uploading.

Click on the using Cockpit link to open the System Administration Cockpit in a new tab.

CML Controller Upgrade - System Administration Cockpit login verification

Log into the System Administration Cockpit as the system administrator account. See Logging into the System Administration Cockpit. Verify that you can see the CML2 System Maintenance Controls page, which is also accessible through the left-side menu as CML2.

Attention

In Cluster installations, make sure you can log into each host prior to starting the upgrades. Make sure you’ve logged in as the system administrator username which was setup during initial setup, and that the same username was used for each compute host. The passwords need not match.

When upgrading from release 2.4.0, open the System Administration Cockpit for each compute host in a separate tab.

In clusters since release 2.5.0, the compute hosts rely on the controller’s System Administration Cockpit to initiate upgrades. If the computes were set up correctly, then you should be able to switch between all hosts in the controller System Administration Cockpit. At the top of the left-side menu, the currently-controlled hostname should be visible as a dropdown menu. Clicking it reveals all compute hosts visible to System Administration Cockpit. Select each compute host in turn to switch between them. If you are unable to see or switch to all hosts without errors, contact support.

Verifying state for CML Controller Upgrade - CML UI steps

Switch back into the CML server UI browser tab. In the bottom-right corner, verify system state. If the button is red, click it and examine reasons for it. If either licensing or any compute host report as red, contact support to resolve such issues prior to upgrading.

In the top-most menu panel, click Tools ‣ System Administration.

On the System Administration page, click Node Administration.

Verify there are no running lab nodes.

You will see the table of all lab nodes in the system. All listed nodes must have their State reported as CREATED or STOPPED prior to continuing with the upgrade. If all nodes are in these states, continue with the next step.

If you have many nodes, you can click the filter icon in the State column to show only nodes which are in selected states. Click on the dropdown menu that appears. Only states where at least one node has that state will be listed as options. Select all states other than CREATED or STOPPED. Then click into empty space away from the popup.

Click the checkbox in the top-left corner of the table. Then click the Stop button to stop all selected nodes. Continue with the next step once all nodes report to be in the desired states.

Enabling CML Controller Maintenance Mode - CML UI steps

Note

Skip these steps when upgrading from releases prior to 2.6.0. The upgrade process itself will initialize maintenance mode into enabled state during upgrades from such older releases. You will take these steps from then on to control access to the system during any maintenance.

On the System Administration page, click System Maintenance.

On the System Maintenance page, click the Maintenance Mode toggle to enable it. Click Save to apply the change.

A banner message informing users of ongoing maintenance will appear. All non-admin users of a multi- user CML-Enterprise system will be logged out, and not allowed to log back in.

On the System Administration page, click Compute Hosts.

In the table of compute hosts, click the checkbox in the top-right corner to select all items.

Click the Change Admission State dropdown, and click the REGISTERED option.

The compute hosts will be all reported as disconnected. A System Health Issue may be shown in the bottom-right corner of the UI, but this is normal at this point.

CML Controller Upgrade - System Administration Cockpit UI steps

Switch into the System Administration Cockpit, click CML2 in the navigation bar on the left side of the page and expand the Controller Software Upgrade item in the Maintenance section.

Note

In Cluster installations, log into or switch to the Controller host’s System Administration Cockpit UI.

In the System Administration Cockpit, click the Upgrade button.

This step takes several minutes, depending on the speed of your network connection. The upgrade process attempts to refresh the OS database of available software packages, and may try to download any OS package dependencies which are missing from the system and are not bundled with the .pkg file.

If everything goes well, the log output at the very end should indicate that the upgrade process is done:

Upgrade Log Output

Upgrade Log Output

If the System Administration Cockpit disconnects during the upgrade, then click the Reconnect button and check the log output by clicking the Show Log Output button in the Controller Software Upgrade area. The upgrade process might still be running in the background, but after the first disconnection, the page will no longer refresh the output area automatically to show the latest output from the upgrade process. You may need to click the button or refresh the page multiple times to see all of the output from the upgrade process.

Once the upgrade is complete, check the output in the Output area at the bottom of the CML2 page in the System Administration Cockpit. Ensure that the upgrade did not generate any error or failure messages.

Attention

In Cluster installations when upgrading from release 2.5.0 or later, the upgrade for each compute will take place in turn after the controller is upgraded. There is a separate success or failure result logged for each host of the cluster. A '<<< Finished executing on all computes >>> message will appear once that is done.

If upgrading from release 2.4.0, repeat the previous steps using System Administration Cockpit of each individual compute host in turn. You do not need to upload the image file again.

We recommend applying the base OS software updates in the System Administration Cockpit once the system upgrade is completed.

Attention

After the upgrade is complete, ensure that all users of the CML server clear their web browser caches before navigating to the CML server again and logging into the CML UI. Failure to do so may cause them to experience errors or other problems with the updated UI.

Disabling CML Controller Maintenance Mode - CML UI steps

Log in back into the CML server UI browser tab.

Note

These steps apply even when upgrading from versions prior to release 2.6.0.

In the top-most menu panel, click Tools ‣ System Administration.

On the System Administration page, click Compute Hosts.

In the table of compute hosts, click the checkbox in the top-right corner to select all items.

Click the Change Admission State dropdown, and click the READY option.

Tip

You can first put the compute hosts into the ONLINE state. In this state, node starts will be prohibited on the compute hosts, and you can still examine overall system health.

The compute hosts will connect back a short while after being re-enabled. Any issues reported in the bottom-right corner of the UI should be cleared shortly afterwards.

On the System Administration page, click System Maintenance.

On the System Maintenance page, click the Maintenance Mode toggle to disable it. Click Save to apply the change.

A banner message informing users of ongoing maintenance will disappear. All non-admin users of a multi- user CML-Enterprise system will now be allowed to log back in.

The upgrade is complete. Your CML server is now running the new release and is ready for use.

Attention

After the upgrade, we recommend that you and any other users of your CML server also upgrade client applications or tools that complement CML. An application or tool that is not included as part of the CML release or that you have installed locally on your own machine is not updated as part of the in-place upgrade procedure. Existing versions may not be compatible with your newly-upgraded CML server. Follow the links below for more information on each application or tool that you use and verify its compatibility with the new CML release before proceeding:

By keeping these tools up to date, you can take full advantage of the improvements and ensure compatibility with features of your newly-upgrade CML server.