Activating endpoints in bulk

This article outlines what's involved in activating large numbers of hardware video endpoints on the Pexip Service. This process currently requires some manual intervention and you need to contact your partner to help you with some of the steps as indicated below.

We'll be enhancing this guide so that company administrators can complete the steps without needing further assistance. We’re also planning a more automated solution for the future.

Prerequisites

Before you can perform a bulk endpoint activation you need to have your endpoint subscriptions created. If you are activating 100 or more endpoints, you can perform a bulk creation by supplying your partner with a file of endpoint details which they will forward onto Pexip for processing. Otherwise, your partner will create the subscriptions manually. For more information see Creating endpoint subscriptions in bulk.

While your subscriptions are being created we recommend reading below to see what else is involved because some steps can be done in parallel.

Supported endpoints

The following endpoints are currently compatible with the bulk activation feature:

Model	Minimum supported software version	Recommended software version
MX-Series	TC7.3.11 1 Although devices running much older software may successfully complete activation, using older versions is not recommended primarily for security reasons. Please note Cisco has deferred all TC software older than TC7.3.20, and all CE software older than CE9.12.4.	CE9.15.8.12 or newer
MX-Series	CE9.1.3 1 Although devices running much older software may successfully complete activation, using older versions is not recommended primarily for security reasons. Please note Cisco has deferred all TC software older than TC7.3.20, and all CE software older than CE9.12.4.	CE9.15.8.12 or newer
SX-Series	TC7.3.11 1 Although devices running much older software may successfully complete activation, using older versions is not recommended primarily for security reasons. Please note Cisco has deferred all TC software older than TC7.3.20, and all CE software older than CE9.12.4.	CE9.15.8.12 or newer
SX-Series	CE9.1.3 1 Although devices running much older software may successfully complete activation, using older versions is not recommended primarily for security reasons. Please note Cisco has deferred all TC software older than TC7.3.20, and all CE software older than CE9.12.4.	CE9.15.8.12 or newer
DX-Series	CE9.1.3 1 Although devices running much older software may successfully complete activation, using older versions is not recommended primarily for security reasons. Please note Cisco has deferred all TC software older than TC7.3.20, and all CE software older than CE9.12.4.	CE9.15.8.12 or newer
C-Series	TC7.3.11 1 Although devices running much older software may successfully complete activation, using older versions is not recommended primarily for security reasons. Please note Cisco has deferred all TC software older than TC7.3.20, and all CE software older than CE9.12.4.	TC7.3.21 or newer
EX-Series	TC7.3.11 1 Although devices running much older software may successfully complete activation, using older versions is not recommended primarily for security reasons. Please note Cisco has deferred all TC software older than TC7.3.20, and all CE software older than CE9.12.4.	TC7.3.21 or newer
Webex Board, Desk, and Room Series	RoomOS 10.3.2.0	RoomOS 10.11.4.1 or newer

¹ Although devices running much older software may successfully complete activation, using older versions is not recommended primarily for security reasons. Please note Cisco has deferred all TC software older than TC7.3.20, and all CE software older than CE9.15.3.17.

Overview of activating in bulk

To activate endpoints in bulk you need to use the Pexip's Video System Configuration client and follow the process outlined here:

1. Download and unpack the Video System Configuration client: Downloading and using the Video System Configuration client.
2. Add the endpoints you want to activate into the Video System Configuration client inventory: Adding endpoints to the Video System Configuration client inventory.
3. Configure the Video System Configuration client with credentials for logging into your video endpoints: Providing your hardware endpoints' login credentials.
4. Verify that the Video System Configuration client can connect to your endpoints: Checking connectivity.

5. Export a JSON file containing your endpoint subscriptions: Exporting your endpoints' subscription data from PCC.

   You can do this when you see your newly created endpoint subscriptions on your Video systems page in Pexip Control Center (PCC). Any endpoints that have not been activated with the Pexip Service show as Offline, although any previously-activated devices may also show as Offline, for example, if they are powered off.

6. Initiate activation using the Video System Configuration client: Activating endpoints in bulk.

Downloading and using the Video System Configuration client

The Video System Configuration client is supported on Windows, Linux, macOS, and Android (64-bit only). The client is provided in the form of a ZIP file or Linux package, from which you must extract the vsclient.exe file.

Click on the relevant link below to download the package containing the client (if the file/link fails to download automatically in some browsers, you may need to right-click on the link and select Save link as...):

• Microsoft Windows 64-bit: https://download.vmr.vc/public/software/vsclient/latest/vsclient_windows_amd64.zip
• Apple Mac OS Intel 64-bit: https://download.vmr.vc/public/software/vsclient/latest/vsclient_darwin_amd64.zip
• Apple Mac OS M1/ARM 64-bit: https://download.vmr.vc/public/software/vsclient/latest/vsclient_darwin_arm64.zip
• Linux Intel (.deb 64-bit): https://download.vmr.vc/public/software/vsclient/latest/vsclient_linux-amd64.deb
• Linux Intel (.rpm 64-bit): https://download.vmr.vc/public/software/vsclient/latest/vsclient_linux-amd64.rpm
• Linux ARM (.deb 64-bit): https://download.vmr.vc/public/software/vsclient/latest/vsclient_linux-arm64.deb
• Linux ARM (.rpm 64-bit): https://download.vmr.vc/public/software/vsclient/latest/vsclient_linux-arm64.rpm

Using the Video System Configuration client

You use the Video System Configuration client by running the vsclient.exe as a command line process with the relevant set of switches and associated files containing your endpoint details.

If you are using a Windows PC, you can use a command line application such as Windows PowerShell ISE to run the commands:

• From your PC, run PowerShell ISE as Administrator by right-clicking on it and selecting Run as Administrator.

  

• Ensure that you have put the vsclient.exe client in a location that is in PowerShell's path environment.
• Local data is stored under the user profile path at .config\vsclient for example C:\Users\myusername\.config\vsclient

Adding endpoints to the Video System Configuration client inventory

You need to provide the Video System Configuration client with details for each hardware endpoint you want to manage using the client.

1. Create a CSV file with a row for each endpoint in the format: aor, ip, agent.

   The file must not have a header row.

   Ensure that the CSV file is saved with UTF-8 encoding. If you use Excel to prepare the file it may be saved by default with UTF-8-BOM encoding which will cause the first endpoint in the file to be ignored. You can use a tool such as Notepad++ to change the encoding from UTF-8-BOM to UTF-8.

   Field name	Content	When required
   aor	The video address (SIP URI) for your device as it appears in PCC on the Video systems page.	Always
   ip	The private IP address of your device. For example: 192.168.1.221.	Always
   agent	This must currently be cisco (all lower case).	Always

   Here is a sample CSV file, viewed in a text editor:

   

2. When your CSV file is ready, import the file into the Video System Configuration client using the command:

   vsclient inventory import --file <inventory.csv>

   where <inventory.csv> is the name of your CSV file.

   If you encounter any errors check if you need to specify a path for the vsclient command or the inventory.csv file.

3. You can display the inventory to check what was added using:

   vsclient inventory list

   (The output is not currently formatted in an easy-to-red manner.)

Providing your hardware endpoints' login credentials

You must provide credentials for logging in to your endpoints using the following command:

vsclient secrets add --subnet <address> --username <username> --password <password>

where <address> must be in CIDR notation and can specify a subnet or single host IP address, and <username> and <password> are the credentials for the endpoints at that address.

You must enclose the password in ' ' marks if it contains special characters e.g. --password 'abcd$4'

You can specify multiple sets of addresses and credentials. If any of the IP addresses provided overlap, the more specific entry is used. In the examples below the endpoint with IP address 192.168.1.123 uses the Single host credentials while the rest of the 192.168.1.0/24 subnet uses the Subnet-based credentials.

• Single host credentials:

  vsclient secrets add --subnet 192.168.1.123/32 --username user1 --password password1

• Subnet-based credentials:

  vsclient secrets add --subnet 192.168.1.0/24 --username user2 --password password2

You can check the currently defined secrets via:

vsclient secrets list

You can remove a set of credentials via the command:

vsclient secrets remove --subnet <address>

Checking connectivity

Next you should check that the Video System Configuration client can connect to the endpoints you want activate by using the command:

vsclient bulk ping

If there are failures you need to troubleshoot possible causes and resolve them.

We also strongly recommend checking that your endpoints can connect to the Pexip Service's provisioning server. The most common cause for endpoints failing to reach the provisioning server is that DNS is not configured to allow it. See Checking your video endpoint's DNS configuration for general help on checking your DNS configuration.

Exporting your endpoints' subscription data from PCC

When your endpoint subscriptions have been created, PCC lets you export those subscription details to a JSON file which is designed for use with Video System Configuration client.

When you're ready to do the export:

1. Go to your Video systems page in PCC. If you see the entries for the endpoints you want to activate you can continue.

2. From the top-right corner select Export as and then Bulk configuration file (JSON).

   

3. A dialog opens with some information. Just select Export file.
4. A new browser tab opens. When your file is ready, select Download file.

Do not edit the exported JSON file because edited files cause signature verification and activation to fail.

This file contains all endpoints listed on the Video systems page including any which are already activated. In future releases we plan to allow selection of specific endpoints.

Activating your endpoints in bulk

When you have completed all the steps above, you are ready to activate your endpoints. You need to run the command below where <filename> is the JSON file you exported from PCC.

vsclient bulk activate --file <filename>

The tool will then send the relevant HTTP requests to activate each endpoint in the file. If you experience any errors please contact your partner who will help you troubleshoot and resolve the problems.

You can repeat the bulk activate command with the same JSON file until all errors have been resolved.

The JSON file is not required in the Upload certificates bulk command.

Other commands

Other useful commands are available in the tool.

Reboot endpoint

To reboot an endpoint use the command:

vsclient boot --address <IP address> --agent cisco --username <name> --password <password>

For example:

vsclient boot --address 192.168.0.179 --agent cisco --username admin --password admin123

Upgrade software

To update an endpoint's software use the command:

vsclient upgrade --address <IP address> --agent cisco --expected-version <version> --upgrade-url <url> --username <name> --password <password>

For example:

vsclient upgrade --address 192.168.0.179 --agent cisco --expected-version ce9.15.4.5.d9493e27346 --upgrade-url https://pexip.com/cisco/ce/software/temp.pkg --username admin --password admin123