Licensing Server

  • Updated on Jul 8, 2025
  • Published on Feb 13, 2025
  • 17 minute(s) read
Prev Next

WHAT TO EXPECT

In this article, users will learn about licensing cloudSwXtches via a Licensing Server. This process is comprised of two main steps:

  1. Creating a Licensing Server VM

  2. Licensing a cloudSwXtch with the Licensing Server

This article will also explain how to add multiple license bundles to an existing licensing server and how to add license bundles with different entitlements.

Creating a Licensing Server

Before creating a licensing server, users will need to deploy a virtual machine that adheres to the following requirements.

Licensing Server VM Requirements

The Licensing Server is supported on Ubuntu 20.04 and 22.04. Since it is a lightweight service, it does not require many resources. For most clouds, it will work on a single core machine with at least 1GBs of memory. Here are some instance recommendations:

  • AWS: t2.small (1 core / 2GB RAM)

  • Azure: Standard_B1ms (1 core / 2GB RAM)

  • GCP: e2-small (2 cores / 2GB RAM)

The Licensing Server uses an HTTP connection. Port 8081 should be open for both the licensing server VM and the cloudSwXtch.

Licensing server if not in the same VPC will require a public IP or peering to ensure connectivity to the cloudSwXtch(s).

Docker must be installed on the virtual machine. For quick instructions, see How to Install Docker on RHEL and Ubuntu. For more detailed steps, see Install Docker Engine on Ubuntu’s documentation site.

With these requirements, you may continue onto the creation process.

  1. Create the VM that will be your Licensing Server based on the prerequisites listed above. Note: This must be on a separate VM from the cloudSwXtch and must run continuously.

  2. Create a /swxtch/bundles directory on your licensing server VM.

    What is a license bundle?

    A bundle contains multiple licenses that share the same entitlements. For example, a user can have a license bundle that contains 3 cloudSwXtch licenses with similar max bandwidths, number of endpoints allowed, and features enabled.

  3. Run the following docker command to install the Licensing Server on the VM: 

    docker run -d --restart=unless-stopped --name swx-license-server -p 8081:8081 -v /swxtch/bundles:/swxtch/bundles swxtchio/swx-license-server:latest

  4. Run the show command to get the Licensing Server VM’s UUID: 

    curl http://localhost:8081/swxtch/licenses/v1/show

  5. Record the fingerprint. Below is an example output of the show command: 

    $ curl http://localhost:8081/swxtch/licenses/v1/show
{
    "fingerprint": "72ddcaf0-923c-bc4b-941b-a3b73b9290d1",
    "Licenses": []
}

  6. Send the fingerprint to support@swxtch.io, requesting the *.dat. This will contain your licenses with the agreed entitlements.

    1. Note: The naming of the *.dat file can vary based on entitlements. In this walkthrough, we used the file, license_10_1_30000_bridge_ha_adapt.dat, as our bundle.

  7. Copy the *.dat file into the /bundles folder located under /swxtch/bundles using the following command:

    sudo cp *.dat /swxtch/bundles

    Example: 

    sudo cp license_10_1_30000_bridge_ha_adapt.dat /swxtch/bundles

  8. Run the following command on your licensing server VM to view the license bundle: 

    curl http://localhost:8081/swxtch/licenses/v1/show

    Below is an example output with the license in place. 

    {
    "fingerprint": "ec256b6f-ea1b-f3eb-f791-e10c747a1c8e",
    "Licenses": [
        {
            "name": "license_test-sa1",
            "allowedSwxtchCount": 5,
            "consumedCount": 0,
            "evictableCount": 0,
            "assignableCount": 5,
            "consumers": [
            ],
            "Bundles": [
                {
                    "bundleName": "license_10_1_30000_bridge_ha_adapt",
                    "expirationDate": "2025-12-30T00:00:00Z",
                    "allowedSwxtchCount": 5,
                    "consumedCount": 0,
                    "evictableCount": 0,
                    "assignableCount": 5,
                    "consumers": [
                    ]
                },
            ],
            "entitlements": {
                "maxClientCount": 10,
                "maxBridgeCount": 1,
                "bandwidthMbps": 30000,
                "enableMesh": false,
                "enableUnicast": true,
                "enableHA": true,
                "enableClockSync": false,
                "enableBridge": true,
                "enableWxckedEye": true,
                "enableAllowsMajorVersionUpdate": true,
                "enableTachyonLive": null
            }
        },
    ]
}

  9. What does each value mean?

    1. name: Name of the License. All licenses in a bundle will share this name. When Licensing a cloudSwXtch via the Licensing Server, users will need to add this name to the remote-licensing.json file for the “License Name” field. This will consume one license from the bundle.

    2. allowedSwXtchCount: The number of licenses allotted to a user via the Licensing Server. In this example, the user has been given 2 licenses to use interchangeably between their cloudSwXtches.

    3. consumedCount: the number of cloudSwXtches currently licensed through the bundle, listing them under authorized. Since no licenses are being used, the consumedCount is 0.

    4. evictableCount:

    5. assignableCount: The number of cloudSwXtch licensing spots remaining

    6. entitlements: This shows the entitlements for each of the licenses in a bundle.

      1. maxClientCount: Max number of endpoints

You should now be ready to license the cloudSwXtch.

Viewing License Server Logs

To view Licensing Server logs, use the following command on the VM:

docker logs swx-license-server -f

Below is an example output:

ubuntu@ip-10-64-29-105:~$ docker logs swx-license-server -f
info: 2024/12/23 14:48:35 /home/maxiz/swxtch-core/go/license-server/cmd/swxtch-license-svr/cmd/run_cmd.go:45: {"Version":"dev","Commit":"unknown","Date":"unknown"}
info: 2024/12/23 14:48:35 /home/maxiz/swxtch-core/go/toolkit/fingerprint/fingerprint.go:20: HOLAAAAAAAA
info: 2024/12/23 14:48:35 /home/maxiz/swxtch-core/go/license-server/cmd/swxtch-license-svr/cmd/run_cmd.go:53: fingerprint: ec256b6f-ea1b-f3eb-f791-e10c747a1c8e
info: 2024/12/23 14:48:35 /home/maxiz/swxtch-core/go/license-server/services/bundles.go:403: Bundle folder /swxtch/bundles
info: 2024/12/23 14:48:35 /home/maxiz/swxtch-core/go/license-server/services/bundles.go:404: Server license location /swxtch
info: 2024/12/23 14:48:35 /home/maxiz/swxtch-core/go/license-server/services/bundles.go:189: Loading new bundle detected: license_10_1_30000_bridge_ha_adapt.
info: 2024/12/23 14:48:35 /home/maxiz/swxtch-core/go/license-server/services/bundles.go:189: Loading new bundle detected: license_10_1_30000_bridge_ha_adapt2.
info: 2024/12/23 14:48:35 /home/maxiz/swxtch-core/go/license-server/services/bundles.go:189: Loading new bundle detected: license_20_1_30000_all.
info: 2024/12/23 14:48:35 /home/maxiz/swxtch-core/go/license-server/cmd/swxtch-license-svr/cmd/run_cmd.go:55: keep Alive Expiry: 10 in minutes
info: 2024/12/23 14:48:35 /home/maxiz/swxtch-core/go/license-server/cmd/swxtch-license-svr/cmd/run_cmd.go:57: Starting http server at :8081

Starting and Stopping the Licensing Server

When creating the Licensing Server, the docker command used during deployment tells the service to restart every time the VM is initialized. In the event that a user would like to stop or start the licensing server manually, they should use the following commands:

START

docker start swx-license-server

STOP

docker stop swx-license-server

Licensing a cloudSwXtch via the Licensing Server

Required: Installing a cloudSwXtch

In order to license a cloudSwXtch, you must first install a cloudSwXtch via BYOL or manual method. For instructions on how install a cloudSwXtch, see here.

With a cloudSwXtch installed and ready to go, you may now continue onto the licensing process:

  1. The Licensing server uses HTTP as well as port 8081 open them up on the cloudSwXtch(s) and the Licensing Server.

  2. Check to see if your cloudSwXtch is currently licensed by opening swx-top on the cloudSwXtch VM. Use the following command:

    swx-top

    For Existing cloudSwXtches

    If you see “License File” under Licensing, go to the /swxtch directory and remove the license.json file. Alternatively, if you like to keep the file, you can rename it as a backup.

    How cloudSwXtch Looks for Licenses

    1. When a license.json file exists, the cloudSwXtch will prioritize that file over the licensing server.

    2. By removing or renaming the license.json file, the cloudSwXtch then will look for the licensing server file, or remote-licensing.json.

    3. If there is no licensing server, the cloudSwXtch will look for a marketplace license.

    4. Once the cloudSwXtch has exhausted all three methods, it will be marked as Not Authorized and will not work.  

    For new cloudSwXtches installed via BYOL or manually, there will no license file in place.

    swx-top should display the following Not Authorized message at the top panel.

  3. Validate communication to the Licensing Server by running the following commands on the cloudSwXtch VM: 

    1. curl http://<Licensing Server IP>:<Licensing Server Port>/swxtch/bundles

      Example Command: 

      curl http://10.64.29.105:8081/swxtch/bundles

      Example Output: 

    2. nc -vz <Licensing Server IP> <Licensing Server Port>

      Example Command: 

      nc -vz 35.174.125.39 8081

      Example Output:

    Error: No Response

    If you do not get a response, check to see if Port 8081 is open for both the Licensing Server VM and the cloudSwXtch.

  4. Create a remote-licensing.json file in your cloudSwXtch directory. Note: It MUST have the name, remote-licensing.json

  5. Enter the following information in the remote-licensing.json file, replacing <IP-license-server> with the IP address of the Licensing Server virtual machine, and the LicenseName. 

    {
        "Url": "http://<IP-license-server>:8081/swxtch/licenses/v1",
        "LicenseName": "<License Name>"
}

    1. In Step 6 and 8 of Creating a Licensing Server, the user received a license.dat file after providing the fingerprint to the swXtch.io Team. In that file, there is a field for the name of the license. In this example, the Name is license_from_swxtch. Therefore, that is the name they would put in the remote-licensing.json file as shown below. 

      {
        "Url": "http://<IP-license-server>:8081/swxtch/licenses/v1",
        "LicenseName": "license_from_swxtch"
}

    2. If a user changed the name in the license.dat file on their Licensing Server VM or would like to use a different license, they would need to change the LicenseName in the remote-licensing.json file on the cloudSwXtch VM as well. This tells the cloudSwXtch where to point.

  6. Save and close the file.

  7. Restart the cloudSwXtch, specifically the swxtch-ctrl.service. The cloudSwXtch is now ready and pointing to the license server.

These steps can be repeated for every additional cloudSwXtch allotted in the license bundle.

Viewing License Bundles on the cloudSwXtch

A user can view their license bundles by running the following command on their cloudSwXtch:

./swx licenses show -s <License Server IP>:<License Server Port>

Example:

./swx licenses show -s 10.64.29.105:8081

The example below shows what the output will look like:

root@ip-10-64-20-179:/swxtch# ./swx licenses show -s 10.64.29.105:8081
{
    "fingerprint": "ec256b6f-ea1b-f3eb-f791-e10c747a1c8e",
    "Licenses": [
        {
            "name": "license_test-sa1",
            "allowedSwxtchCount": 5,
            "consumedCount": 1,
            "evictableCount": 0,
            "assignableCount": 4,
            "consumers": [
                {
                    "fingerprint": "213de388-ccb5-4d93-9159-3fa9ad5585ea",
                    "hostAddress": "10.2.128.10",
                    "hostName": "dsd-core-100",
                    "lastUpdateTime": "2025-02-11T20:46:09.756723888Z",
                    "evictable": false
                }
            ],
            "Bundles": [
                {
                    "bundleName": "license_10_1_30000_bridge_ha_adapt",
                    "expirationDate": "2025-12-30T00:00:00Z",
                    "allowedSwxtchCount": 5,
                    "consumedCount": 1,
                    "evictableCount": 0,
                    "assignableCount": 4,
                    "consumers": [
                        {
                            "fingerprint": "213de388-ccb5-4d93-9159-3fa9ad5585ea",
                            "hostAddress": "10.2.128.10",
                            "hostName": "dsd-core-100",
                            "lastUpdateTime": "2025-02-11T20:46:09.756723888Z",
                            "evictable": false
                        }
                    ]
                },
            ],
            "entitlements": {
                "maxClientCount": 10,
                "maxBridgeCount": 1,
                "bandwidthMbps": 30000,
                "enableMesh": false,
                "enableUnicast": true,
                "enableHA": true,
                "enableClockSync": false,
                "enableBridge": true,
                "enableWxckedEye": true,
                "enableAllowsMajorVersionUpdate": true,
                "enableTachyonLive": null
            }
        },
    ]
}

Releasing a Licensed cloudSwXtch from Licensing Server

License bundles contain a finite amount of licenses available to use. Unless they receive an additional bundle with the same licenses, they are limited by the amount allotted to them in their original bundle. Luckily, the licensing server has a release function that allows users to swap licenses between cloudSwXtches. For example, if a user has licensed 5 cloudSwXtches, consuming all the licenses in the singular bundle they have, they would need to release at least one of their cloudSwXtches from the licensing server to have an available license to use.

To release a cloudSwXtch from the licensing server, run the following command on the VM, replacing the values:

~$ sudo /swxtch/swx licenses release -p "<cloudSwXtch fingerprint>" -n "<License Name>" -s <Licensing Server IP>:<Licensing Server Port>

Example:

~$ sudo /swxtch/swx licenses release -p "67ae4938-70c4-4f96-9dfb-bea3d836e672" -n "license_from_swxtch" -s 10.1.212.164:8081

Users can verify if the cloudSwXtch was released from the licensing server by checking either wXcked Eye or swXcth-top.

wXcked Eye

swx-top

Increasing Number of Licenses by Adding Bundles

Users can increase the number of licenses in an existing bundle by requesting an additional bundle file, or *.dat, from the swXtch.io Support Team. This is only for situations where the additional licenses will have the same entitlements allotted in licenses within the original .dat file.

  1. Contact support@swxtch.io, requesting additional licenses with the same entitlements as the original license bundle file.

  2. Move the new .dat file into the /swxtch/bundles folder on the licensing server VM. You do not have to remove the previous license bundle.

    1. In this example, the user requested an additional license bundle, containing 5 copies of the same license with the same entitlements. swXtch.io Support sent a new bundle file, license_10_1_30000_bridge_ha_adapt2.dat. The screenshot illustrates the new license bundle in place with the the old one.

  3. Use the following curl show command on the licensing server to see the licenses. 

    curl http://localhost:8081/swxtch/licenses/v1/show

    1. Example Output:

  4. Users can now license their cloudSwXtches. For information, see Licensing a cloudSwXtch via the Licensing Server.

Adding A New License Bundle

The Licensing Server can host multiple different licenses with different entitlements. Similar to adding a bundle to increase the number of identical licenses, users can add a new bundle, or *.dat, file to their swxtch/bundles folder if they have cloudSwXtches that need a different feature set.

  1. Contact support@swxtch.io, requesting a new license bundle.

  2. Move the new .dat file into the /swxtch/bundles folder on the licensing server VM. You do not have to remove any existing license bundles. Since they contain different licenses, they are independent of one another.

  3. Use the following curl show command on the licensing server to see the licenses. 

    curl http://localhost:8081/swxtch/licenses/v1/show

    1. Example Output: In this example, the user has two existing license bundles, license_10_1_30000_bridge_ha_adapt and license_10_1_30000_bridge_ha_adapt2, containing identical copies of the license, license_test-sa1. They are both listed under the license_test-sa1 license in the output above. There is a second license listed named license_test-sa2. Under that license is a freshly added bundle file, license_20_1_30000_all, containing licenses with different entitlements than license_test-sa1. 

      {
    "fingerprint": "ec256b6f-ea1b-f3eb-f791-e10c747a1c8e",
    "Licenses": [
        {
            "name": "license_test-sa1",
            "allowedSwxtchCount": 10,
            "consumedCount": 1,
            "evictableCount": 0,
            "assignableCount": 9,
            "consumers": [
                {
                    "fingerprint": "213de388-ccb5-4d93-9159-3fa9ad5585ea",
                    "hostAddress": "10.2.128.10",
                    "hostName": "dsd-core-100",
                    "lastUpdateTime": "2025-02-11T20:46:09.756723888Z",
                    "evictable": false
                }
            ],
            "Bundles": [
                {
                    "bundleName": "license_10_1_30000_bridge_ha_adapt",
                    "expirationDate": "2025-12-30T00:00:00Z",
                    "allowedSwxtchCount": 5,
                    "consumedCount": 1,
                    "evictableCount": 0,
                    "assignableCount": 4,
                    "consumers": [
                        {
                            "fingerprint": "213de388-ccb5-4d93-9159-3fa9ad5585ea",
                            "hostAddress": "10.2.128.10",
                            "hostName": "dsd-core-100",
                            "lastUpdateTime": "2025-02-11T20:46:09.756723888Z",
                            "evictable": false
                        }
                    ]
                },
                {
                    "bundleName": "license_10_1_30000_bridge_ha_adapt2",
                    "expirationDate": "2025-12-30T00:00:00Z",
                    "allowedSwxtchCount": 5,
                    "consumedCount": 0,
                    "evictableCount": 0,
                    "assignableCount": 5,
                    "consumers": []
                }
            ],
            "entitlements": {
                "maxClientCount": 10,
                "maxBridgeCount": 1,
                "bandwidthMbps": 30000,
                "enableMesh": false,
                "enableUnicast": true,
                "enableHA": true,
                "enableClockSync": false,
                "enableBridge": true,
                "enableWxckedEye": true,
                "enableAllowsMajorVersionUpdate": true,
                "enableTachyonLive": null
            }
        },
        {
            "name": "license_test-sa2",
            "allowedSwxtchCount": 6,
            "consumedCount": 0,
            "evictableCount": 0,
            "assignableCount": 6,
            "consumers": [],
            "Bundles": [
                {
                    "bundleName": "license_20_1_30000_all",
                    "expirationDate": "2025-12-30T00:00:00Z",
                    "allowedSwxtchCount": 6,
                    "consumedCount": 0,
                    "evictableCount": 0,
                    "assignableCount": 6,
                    "consumers": []
                }
            ],
            "entitlements": {
                "maxClientCount": 20,
                "maxBridgeCount": 1,
                "bandwidthMbps": 30000,
                "enableMesh": true,
                "enableUnicast": true,
                "enableHA": true,
                "enableClockSync": true,
                "enableBridge": true,
                "enableWxckedEye": true,
                "enableAllowsMajorVersionUpdate": true,
                "enableTachyonLive": true
            }
        }
    ]
}

  4. The user should now have two different licenses available for them to license their cloudSwXtches. For information, see Licensing a cloudSwXtch via the Licensing Server.

Upgrading the Licensing Server

To upgrade the licensing server, users will need to follow these steps:

  1. Get the licensing server container ID.

  2. Stop the docker service.

  3. Remove the container from the machine.

  4. Reinstall the licensing server using the command in Step 3 of Creating a Licensing Server.

For a complete list, see Helpful Docker Service Commands under cloudSwXtch How To’s.