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.

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.

To perform an in-place upgrade, use the following procedure. After the CML upgrade completes, we also recommend updating the base OS packages unless you are running an offline or air-gapped CML-Enterprise installation.

Procedure

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

  • On Windows, use 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

Log into the CML server UI.

On the Lab Manager page in your CML 2.x instance, 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.

CML Controller Upgrade - System Administration Cockpit steps

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

In 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.

In the System Administration Cockpit, click the Upgrade Controller button.

This step takes several minutes, depending on the speed of your network connection.

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.

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

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.

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.

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