Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Activating Shield

Shield is tied to your Xygeni account. Until a valid token is configured, the agent is installed but inactive: it does not inspect downloads, scan files or apply any rule, local rules included. xygeni-fw status shows Account: NOT ENROLLED and the tray app shows only the activation screen.

Creating the token

Shield needs a personal API token with the Xygeni Shield agent permission:

  1. In the Xygeni dashboard, open Settings → Security → Personal tokens and click Create personal token. Shortcut: open /dashboard/settings/security?createToken=shield in the dashboard, which opens the form with the permission already selected.

  2. Select the Xygeni Shield agent permission and create the token.

  3. Copy the token.

Organization tokens cannot hold this permission, and a token created for other uses (for example, CI scans) does not activate Shield unless it also has the Xygeni Shield agent permission.

Setting the token

Use whichever option suits you. None of them needs a restart: Shield becomes active within a few seconds.

  • Tray app: paste the token in the activation screen and click Activate. Once active, the token can be changed in Policy → Xygeni Cloud (Save token / Clear).

  • Command line:

    xygeni-fw config token <token>

    Run it as the user who installed Shield, or with sudo (on Windows, from an elevated terminal).

  • Unattended installations (MDM, Ansible, golden images): pass the token at install time with sudo xygeni-fw install --token <token>, or set it in the XYGENI_TOKEN environment variable for xygeni-fw install.

The token is checked against Xygeni as soon as it is set. If it lacks the Xygeni Shield agent permission it is refused (the command fails, or the tray shows an error) and the previous token, if any, is kept.

To replace the token, set the new one the same way. To remove it, run xygeni-fw config token "" or click Clear in the tray; Shield goes back to inactive.

What your subscription enables

What Shield does once activated depends on your Xygeni subscription: the number of Shield seats it includes, and whether it includes centralized configuration.

Subscription
What you get

Shield with centralized configuration

Centrally managed. Your security team defines the policy in the Xygeni dashboard and Shield applies it automatically. Blocks are reported to the dashboard, the machine is listed in the endpoint inventory and can be isolated remotely. See Managing Shield from the dashboard.

Shield without centralized configuration

Locally configured. Shield protects the machine with the Xygeni malicious packages database and the rules you set on the machine (tray app or command line). There is no central policy, no alerts in the dashboard, no inventory and no remote isolation.

No Shield

Shield stays inactive, as if it were not installed, and the Xygeni Shield agent permission is not offered when creating tokens. Contact your Xygeni account manager.

In both Shield cases, each active machine uses one Shield seat (see Shield seats).

Checking the activation state

xygeni-fw status shows the state in its Account:, License: and Token: lines:

Line
Meaning

Account: enrolled (plan ...) - configuration managed by Xygeni Cloud

Active and centrally managed.

Account: enrolled (plan ...) - local configuration only

Active and locally configured.

Account: NOT ENROLLED - no Xygeni token, so nothing is blocked.

No token yet. Set one as described above.

Account: NOT ACTIVE - the server refuses the token, so nothing is blocked.

The token does not have the Xygeni Shield agent permission. Create a new one and set it.

Account: NOT ACTIVE - Xygeni Shield is not included in this subscription, so nothing is blocked.

The subscription does not include Shield. Shield activates by itself once it is added.

License: active (Shield seat held, lease until ...)

The machine holds a Shield seat and is fully protected.

License: DORMANT - ...

No Shield seat is available for this machine right now. See Shield seats.

Token: WILL STOP WORKING after ...

The token lacks the Xygeni Shield agent permission and will be refused after the date shown. Replace it before then.

Token: REJECTED by the server - ...

The token has expired or was revoked. Local protection continues, but the central policy, alerts and inventory stop until you set a valid token.

The tray app shows the same information: a grey icon and the reason when Shield is not protecting the machine, and a notice in the Policy tab when the token needs replacing.

Last updated