Installing a License¶

This guide describes how to install a VirtualForge product license manually, without the product needing to reach EEI over the internet. It is written for two readers working together:

You (the customer) — install and run the product on your server.
EEI / VirtualForge support — issues the license bound to your server and helps you validate it.

The process below is the same for every VirtualForge product, including Seeq connectors. Anything specific to a product type is called out in Product-specific notes.

This is how every license is installed today. Automatic licensing for products connected to the VirtualForge platform, managed through ForgeIQ, is planned and not yet available. See Licensing.

How a manual license works¶

Your license is a small signed file (a .lic). The product validates it on startup with no connection to EEI required. Two things matter:

It is tied to your specific server. For security, a license is node-locked: it only works on the machine it was issued for. This is done with a host fingerprint — a set of one-way, irreversible identifiers derived from your server. The license does not work if copied to a different machine.
It carries your entitlement — for connectors, the number of active datasources you may run, plus an expiry date and any enabled features.

Because the license is node-locked, EEI needs your server's fingerprint before it can issue the license. The whole process is three short steps.

Step 1 — Produce your server's fingerprint (customer)¶

Install and start the product on the server that will run it. On every startup the product writes a fingerprint request file — even before a license is installed. You do not need to do anything special to generate it; just start the product once.

File: host-fingerprint.json, in the product's vforge data folder.
Finding it: the product logs the exact location and a short Host ID at startup, e.g.:

[license] host fingerprint written to <…>/vforge/host-fingerprint.json (Host ID A1B2-C3D4).
          Forward this file to EEI to obtain a license.

The Host ID (e.g. A1B2-C3D4) is a short label you and EEI can use to refer to this server on a call or email.

Is this file safe to send? Yes. It contains only hashed (one-way, salted) identifiers plus your server's host name for your own reference — no passwords, keys, or personal data, and the hardware identifiers cannot be reversed out of it.

Step 2 — Send the fingerprint to EEI (customer → EEI support)¶

Send host-fingerprint.json to EEI support (see Getting help), along with:

the product and server this is for, and
your intended entitlement if it isn't already agreed (e.g. how many datasources).

EEI support issues a license bound to the host in that file and returns a single vforge-license.lic file. For an evaluation, EEI can issue a short-term license the same way — it is also node-locked, so it cannot be reused elsewhere.

If several servers need licenses (e.g. a primary and a failover), send one host-fingerprint.json per server; EEI can bind them together or issue one file per host.

Step 3 — Install the license file (customer)¶

Copy the vforge-license.lic EEI sent you into the product's license folder: …/vforge/products/<product-id>/vforge-license.lic, where <product-id> identifies the product (e.g. seeq-connector-abbkm). The file must be named exactly vforge-license.lic. The product creates this folder for you at startup (and logs its exact path) — you don't create any folders, just drop the file in.
Restart the product so it re-reads the license.

That's it — no configuration change is required. The per-product folder is what lets several products share one server/agent, each with its own license (see Multiple products on one server). (Advanced: the license path can be overridden with the VFORGE_LICENSE_FILE environment variable or the vforge.license.file system property, but the default location above needs no setup.)

Verifying it worked¶

After the restart, the product log should show the license as valid and your entitlement active (for a connector, the licensed number of datasources begins indexing). The startup log names the state explicitly — LICENSED when all is well.

Troubleshooting¶

Log / symptom	Meaning	What to do
`LICENSED`	License valid for this host and in date.	Nothing — you're done.
`UNLICENSED`	No valid license found (missing, wrong file name, or in the wrong folder).	Confirm the file is named `vforge-license.lic` and sits in `vforge/products/<product-id>/`; restart.
`HOST_MISMATCH`	A license is present but was issued for a different server (copied from another machine, or this server's hardware changed substantially).	Re-run Step 1 on this server and send the new `host-fingerprint.json` to EEI for a re-issued license.
`EXPIRED`	The license passed its expiry date.	Contact EEI to renew (see below).

The product runs but does no licensed work (e.g. 0 datasources) in any state other than LICENSED. It still starts and keeps the fingerprint file up to date, so you can always re-request a license.

Renewals, entitlement changes, and hardware changes¶

Renew or change entitlement (e.g. more datasources, extend expiry): contact EEI. A renewal is a new .lic for the same server — install it the same way (Step 3). You do not usually need a new fingerprint unless the server changed.
Moved to a new server or virtual machine, or a change to both the OS installation and the motherboard: the old license reads HOST_MISMATCH. Repeat Steps 1–3 for the new or changed server.
Routine changes (a swapped network card or disk) are tolerated, and so, usually, is an OS reinstall or a motherboard replacement on its own. On a virtual machine whose motherboard UUID is not readable, an OS reinstall alone needs a re-issued license. See Licensing.

Multiple products on one server¶

Several licensed products can run on one server (for Seeq, several connectors in one agent). They share the single host-fingerprint.json — it identifies the server, not the product — and each product has its own license in its own folder:

…/vforge/
├── host-fingerprint.json                     ← one per server (shared)
└── products/
    ├── seeq-connector-abbkm/vforge-license.lic
    └── <another-product-id>/vforge-license.lic

So you send EEI one fingerprint, and EEI returns one .lic per product; drop each in its own products/<product-id>/ folder. Each license carries that product's own entitlement independently.

Product-specific notes¶

Seeq connectors (e.g. the ABB KM connector)¶

The vforge data folder is inside the Seeq Link agent's data folder — the folder that also contains configuration/link. host-fingerprint.json sits at the vforge/ root; each connector's license sits at vforge/products/<product-id>/vforge-license.lic. The exact paths are printed in the connector log at startup (Step 1).
"Active datasources" = the number of enabled connections in the connector configuration; each maps to one Seeq datasource. Your license caps how many run at once.
After installing the license, restart the Seeq Link agent (or the connector) so it re-evaluates.

(Other VirtualForge product types follow the same three steps; product-specific placement or restart details will be added here as those products ship.)

Getting help¶

Raise a request through the Endeavor Engineering resources hub. If you bought through a platform partner, you can also go through them. Please include your Host ID (from the Step 1 log line) and the product name so we can match your request quickly.