Skip to content
English
  • There are no suggestions because the search field is empty.

Workaround for Xona v5.3.3 license expiration bug

Known Issue

Affected Versions

v5.3.3.1797

Affected Components

XCM, CSG.

Affected Features

The web interface (after license expiration).

Fix Version

v5.3.4.1905

Description

When the license expires on a Xona device running v5.3.3, the web UI will not allow the installation of a new license.

Recommendations

  • A fix has been integrated into Xona v5.3.4. This update can be installed on Xona devices regardless of their license status. Refer to the "Fix Version" section above for the download link.

  • If functionality must be restored before an update can be applied, then please use the workaround described in the Additional Information section.

Workaround

It is possible to bypass the web UI and install the new license using the Xona command line interface (CLI) tool. Follow the steps below to set up the Xona CLI tool and install the license on a CSG. The same steps also apply to the XCM.

Prerequisites

  • Browser access to the Xona CSG over HTTPS (tcp/443).

  • Login credentials for a Xona user with Admin access.
  • Ability to run programs from a command prompt or terminal interface.

Steps

  1. From your web browser, access the Xona CSG login page using a web browser.

  2. From your web browser, login with a user who has the Admin permission.

  3. From your web browser, navigate to "Help" towards the bottom of the main menu to access both documentation and download links for the Xona CLI tool (xonactl).

    1. The name xonactl means "Xona Control"
  4. From your web browser, click on the download link for the Xona CLI tool version that matches your computer OS and CPU architecture.
  5. From your computer's downloads folder, extract the ZIP file to a directory where you can run the Xona CLI tool.
    1. The user's home directory is typically the best place for the Xona CLI tool because this is the default location for the Windows command prompt sessions and terminal sessions.
    2. It's considered best practice to add "-v5.3.3" to the file name so that the Xona version for the command line tool is clearly visible (older versions are not forward-compatible with newer Xona versions).
  6. From your web browser, right-click on the CSG documentation link to open a new tab so you can reference the CLI tool documentation. The documentation section is also publicly available at this v5.3.3 documentation link: https://docs.xonaengineering.io/5.3.3/docs/CLI/Getting-Started
  7. From your web browser's CSG tab, navigate to the Profile button at the bottom-right side of the screen. Scroll down to the API Key / SSH Key sections.
  8. Create an authentication key for your admin user to authenticate with the CLI tool. Use one of the options below.
    1. From your web browser's CSG tab, generate an API Key for your admin user to authenticate with the CLI tool.
      1. This option is ideal when a single CSG is involved.
    2. From your computer's command prompt/terminal, generate an SSH key on your computer (ssh-keygen), open the public key file, and save the public key file contents in Xona. 
      1. This option is ideal when multiple CSGs are involved.
  9. From your web browser's CSG tab, save the key in the user's Profile.
  10. From your computer's command prompt/terminal, navigate to the directory where xonactl was saved, then run it once without any arguments.
    1. It should print out a list of available subcommands.
    2. If after several seconds there is no output, or an error message appears:
      1. Check that the Xona CLI tool matches your computer's OS and CPU architecture.
      2. Check that the Xona CLI tool is not being blocked by some OS configuration or software.
  11. From your web browser's documentation tab, refer to the "Getting Started" part of the CLI documentation section (https://docs.xonaengineering.io/5.3.3/docs/CLI/Getting-Started). Complete the steps in that documentation section using your computer's command prompt/terminal. Proceed with the next steps after a successful login.
    1. If you are connecting with an IP address or do not have a HTTPS certificate for your Xona CSG, then xonactl commands will likley need to be run with a -i option at the end. This option tells the Xone CL tool to ignore certificate warnings.
  12. From your computer's command prompt/terminal, confirm the Installation ID (AKA, the UUID) for your CSG by running the following command:
    xonactl license get
    1. CSG production licenses should contain the UUID in the file name.
    2. If you do not have a matching license for this UUID, or if you need a new license, then please contact support@xonasystems.com. 
  13. From your computer's command prompt/terminal, install the new license for your CSG by running the following command:
    xonactl license install [license-file]
    1. Ensure that [license-file] is replaced with the file path to your license file.
    2. If your license is rejected for any reason, then please contact support@xonasystems.com.
  14. Logout from the Xone CLI tool session with the following command:
    xonactl login logout 

Additional Information

Unsure if this is required for your Xona deployment? Please reach out to support@xonasystems.com and we would be happy to discuss it with you.