License Management

This article was written for version 2.3.0 of Core. Click here for the most recent version of the help center.

1. Request a PolySync Core License

A PolySync Core license can be requested here.

2. License tool information

The license tools provides a lot of information about your PolySync Core configuration and allows you to check the PolySync Core version. This table will help you understand all the parameters printed by the license tool.

Run the command polysync-license-tool.

$ polysync-license-tool


*****************************
*** PolySync License Tool ***
API Build Version: 2.1.0-1496881444

Host ID: '(Ethernet) XX0027B9XXX'
Installation Directory (PSYNC_HOME): '/usr/local/polysync'
System Design File: '/home/dev/.local/share/polysync/config/psync.sdf'
Record and Replay Sessions Directory: '/home/dev/.local/share/polysync/rnr_logs'
IP Address: '127.0.0.1'
License Server: 'not used'
License file specified in SDF: 'not used'
Current license status: valid

*****************************

Parameter	Description	Notes and requirements
API Build Version	This is the version of the PolySync Core data model that’s currently installed, and being used by all runtime nodes	Read-only
Host ID	This is the identifier used by the license tool to associate the machine and the license provdied by PolySync	Read-only
Installation directory	A required environment variable `$PSYNC_HOME`, as defined in the `/etc/profile.d/polysync.sh` file	Local file path with read/write access, defaults to `/usr/local/polysync`
System Design File	The system SDF, representing the expected physical configuration of this system when the system is in the hardware mode	Read-only, the SDF file `$PSYNC_USER_HOME/config/psync.sdf`
Record and Replay Sessions Directory	The directory where logfile sessions are recorded to, and where nodes expect logfile sessions to exist while in replay mode	Local file path with read/write access, highly recommended to write data directly to a disk and not use external-USB storage devices (at runtime)
IP Address	The IP address and associated network interface card that is the PolySync Core bus - all data will be published to this network, and the PolySync Core manager will automatically detect other PolySync Core ECUs on this network	Local-host `127.0.0.1` is recommended for single-host systems, must be a valid IP address and the network must be set up outside of PolySync Core - change the IP address with the command `polysync-core-manager -s xxx.xxx.xxx.xxx`
License Server	Optional, only referenced when there’s a floating license server configured
License file specified in SDF	Optional, only used when file-based licensing is used on machines that don’t have internet access	Local file path with read/write access
Current license status	Read-only	Reports ‘valid’ or ‘invalid’, use the command `polysync-license-tool -q` to print detailed license information

3. Activate license with activation ID

New licenses are represented as activation IDs, which are provided by PolySync support. If you have multiple licenses, you will only want to run the following command on each machine once. Calling the license tool twice will assign two licenses (if available) to the same device.

To download your license from the server, paste the activation ID in the command below.

$ polysync-license-tool -a xxxx-xxxx-xxxx-xxxx-xxxx-xxxx

4. Download an existing license

Each license lives in the PolySync license server and can be downloaded to the local machine at any time.

$ polysync-license-tool -a

*****************************
*** PolySync License Tool ***
API Build Version: 2.1.0-1496881444

[...]
Current license status: valid

checking for available capabilities
lrwxrwxrwx 1 root root 16 Jan 31 11:44 /etc/alternatives/x-www-browser -> /usr/bin/firefox
License status: valid
*****************************

This will create a new entry in the license server, if the Host ID did not already exist in the database. This allows PolySync to administer licenses to the machine.

5. Query for license information

You can check the status of your license by passing the ’-q’ flag.

$ polysync-license-tool -q

Expected output with full authenticated license:

$ polysync-license-tool -q

*****************************
*** PolySync License Tool ***
API Build Version: 2.1.0-1496881444

Host ID: '(Ethernet) XX0027B9XXX'
...
Current license status: valid

number of features in license file 'no-file': 0

number of features in trusted storage: 1
1: polysync_lochsa v2 EXPIRES=2-feb-2018 uncounted    HOSTID=XX0027B9XXX  ISSUER="PolySync-cotos" ISSUED=7-feb-2017   START=2-feb-2017
     Valid for acquisition
     Not valid for serving

*****************************

6. Setting persistent host ID

The host ID is the identifier used by the license tool to associate the machine and the license provided by PolySync.

The host ID can change if the hardware on the system is modified, for example if a hard drive is replaced, or a PCIe hardware device is connected.

When this happens the license tool reports an invalid, since the existing license was associated to the previous host ID. To resolve this set a persistent host ID.

List the available host IDs with the license tool -l command
- $ polysync-license-tool -l
Select the host ID to permanently associate the license with
- $ polysync-license-tool -id <host-id-here>
Ensure the license tool reports a valid license
- $ polysync-license-tool
- ...
- Current license status: valid

If the license tool reports the license status is invalid, contact the support desk at help@polysync.io with the output of the polysync-license-tool -l command.

6. File-based licenses

File based licenses are required on certain host ECUs that cannot connect to the PolySync license server.

6.1 Requesting a file-based license

Send an email to the support desk at help@polysync.io with the subject: File-based license request.

Include the output of the following command in the body of the email.

$ polysync-license-tool -a

*****************************
*** PolySync License Tool ***
API Build Version: 2.1.0-1496881444

Host ID: '(Ethernet) XX0027B9XXX'
Installation Directory (PSYNC_HOME): '/usr/local/polysync'
System Design File: '/home/dev/.local/share/polysync/config/psync.sdf'
Record and Replay Sessions Directory: '/home/dev/.local/share/polysync/rnr_logs'
IP Address: '127.0.0.1'
License Server: 'not used'
License file specified in SDF: 'not used'
Current license status: valid

checking for available capabilities
lrwxrwxrwx 1 root root 16 Nov 11  2016 /etc/alternatives/x-www-browser -> /usr/bin/firefox
License status: valid
*****************************

6.2 Installing the file-based license

Copy the polysync-license file to the target ECUs $PSYNC_USER_HOME/license/ directory
On a Tier 1 system open the SDF Configurator
Update the system sdf
- Select the target host ECU tab
- In the License File text field enter the full directory path to the polysync-license file
  - e.g. /home/pi/.local/share/polysync/license/polysync_license
Update each replay SDF for logfile sessions that need to be replayed
Synchronize the modified SDFs with all hosts in the runtime

Known License Error

If you see this error when running the license tool:

$ polysync-license-tool -a

*****************************
*** PolySync License Tool ***
API Build Version: 2.0.10-1487273235

[...]
2017-02-13 14:41:29.02s ERROR  [polysync-license-tool-0] - adding trusted storage license source returned: 1879048255
2017-02-13 14:41:29.02s DEBUG  [polysync-license-tool-0] - trusted storage based licensing may not be available
License status: invalid
To request a license, email help@polysync.io with your machines unique Host ID: '(Ethernet) xxxxxxxxxxxx'
*****************************

You will need to run the following commands to clear your license cache then re-download the license:

$ rm ~/.local/share/polysync/license/am*
$ polysync-license-tool -a