Agent Configuration
  • 13 Nov 2023
  • 10 Minutes to read
  • Dark
    Light
  • PDF

Agent Configuration

  • Dark
    Light
  • PDF

Article summary

Agent.json

The agent.json file allows for configuration of the Liquit Universal Agent.

The path to the agent.json location is:

PlatformPath
Windows%ProgramData%\Liquit\Agent\Agent.json
macOS/Library/Application Support/com.liquit.Agent/Agent.json

Below you will find a sample an agent.json configuration.

{
	"zone": "https://workspace.liquit.com",

	"registration": {
		"type": "Certificate"
	},

	"login": {
		"sso": true
	},

	"log": {
		"level": "Debug"
	}
}
Warning

Backslashes '\' should be escaped within a JSON file. So that a single '\' will be a '\\'.

JSON keys are case sensitive. For example, "autostart" will not work, but "autoStart" will work.

Zone

This should be the URL with the FQDN where the targeted Liquit Workspace Zone is reachable.

{
    "zone": "https://company.liquit.com/"
}

Prompt Zone

This key controls the display of the Zone Prompt dialog box where the user can configure the zone URL. The value entered in the dialog box is saved in the zone key.
This feature works only if there is no URL configured in the zone key.

Available options:

  • Disabled: User is NOT prompted to enter the zone URL, even if it is not configured
  • Show: User is prompted to enter the zone URL, if none is configured. This is the default value of the key.
{
    "promptZone": "Show"
}

Register

These settings allows a device to register itself with Liquit Workspace. Some of them without requiring a user login.

For the User Account and Agent Credentials registration methods, you need to assing the user an access policy that has the Register device privilege. By default, the predefined User access policy has this permission granted.

For a detailed description of Device Registration options within Liquit Workspace UI, see Device Registration.
For step by step instructions on methods of registering a device, see Device registration methods.

User Account based registration example:

{ 
    "registration": { 
        "type": "User" 
    } 
} 

Agent Credentials based registration example:

{
    "registration": {
        "type": "Credentials",
        "username": "local\\wksimport",
        "password": "P@ssw0rd"
    }
}

Agent Certificate based registration example:

Example 1:

{ 
    "registration": { 
        "type": "Certificate", 
        "certificateThumbprint": "69f4db57b74e13415cd103323331d95022d840c1" 
    } 
} 

Example 2:

{ 
    "registration": { 
        "type": "Certificate" 
    } 
} 

Agent Certificate Enrollment based registration example:

    "registration": { 
        "type": "CertificateEnrollment", 
        "certificateIssuer": "Sectigo RSA Domain Validation Secure Server CA" 
  }

Keys

KeyDescriptionDefault
type
  • User - The user that is currently logged on will be used to register the device with the server.
  • Credentials - The specified credentials will be used to register the device with the server.
  • Certificate or Certificate Enrollment - The system will look for the AgentRegistration.cer in the data path and in the Certificate Store based on thumbprint or issuer if provided. See Device Registration for more information.
User
usernameWhen type key is set to Credentials, this username is used to register the device.
passwordWhen type key is set to Credentials, this password is used to register the device.
certificateThumbprintThe hexadecimal string that uniquely identifies the certificate, for example: ea7f07211fddc0df73bac1437a3ff932ce531005.
certificateIssuerThe authority that issued the certificate.

When type key is set to Certificate or Certificate Enrollment, the certificateThumbprint and certificateIssuer are optional settings that can be used to verify the certificate.

If the value of certificateThumbprint is not specified: the certificate must persist on the device in the following locations:

  • Windows: %ProgramData%\Liquit\Agent\AgentRegistration.cer
  • macOS: /Library/Application Support/com.liquit.Agent/AgentRegistration.cer
In this case, the certificate which matches the value and persists on the device, will be installed in the Windows Certificate Store or macOS Keychain and the certificate file will be removed from the device.

If the value of certificateThumbprint is specified: then the Windows Certificate Store or macOS Keychain will be checked for a certificate with the specified value.

Deployments

{
    "deployment": {
        "enabled": false,
        "start": true,
        "context": "Device",
        "cancel": true,
        "triggers": false,
        "autoStart": {
            "enabled": false,
            "deployment": null,
            "timer": 0
        }
    }
}
KeyDescriptionDefault
enabledIf set to true, Liquit Workspace will enable the deployment process on this machine.false
startIf set to true, the process of deployments is automatically started.
  • When context value is Device, the deployment will start after 5 seconds of the agent being started.
  • When context value is User, the deployment will start the first time the userhost has started.
If set to false, this process can be manually started by starting:
  • Windows: C:\Program Files\Liquit Universal Agent\ShellAPI.exe --deployment --run
  • macOS: /Applications/Liquit.app/Contents/MacOS/ShellAPI --deployment --run
true
contextThe context in which the deployment should run.
  • User - User login is required before the deployment wizard is shown. Before starting the deployment, the user will be prompted to select which of the available deployments to run.
  • Device - No user login is required and the deployment will begin automatically. Autostart should be enabled and the specified deployment under autostart should match a single deployment. The autostart timer will be ignored.
Device
cancelIf set to true, the deployment process can be cancelled.true
triggersIf set to true, Liquit Workspace events (refresh/ login) can still be executed.false

Autostart

KeyDescriptionDefault
enabledIf set to true, Liquit Workspace will automatically start the deployment process when a corresponding deployment is found as configured in the deployment key or when only one deployment is available for this device.false
deploymentThe targeted deployment which can be either the name or the ID of the deployment.
timerThis key accepts an integer and represents the number of seconds Liquit will wait before automatically starting the deployment.0

Log

The Liquit Universal Agent logs events it initiates.

{
    "log": {
        "level": "Debug",
        "agentPath": "Agent.log",
        "userHostPath":"UserHost.log",
        "rotateCount": 5,
        "rotateSize": 1048576
    }
}
KeyDescriptionDefault
levelThis element is used to define the level of logging. Liquit Workspace distinguishes between two logging levels:
  • None - Nothing will be logged to the log file
  • Critical - Only critical errors will be logged to the log file.
  • Error - Only errors and critical errors will be logged to the log file.
  • Warning - Only warnings, errors and critical errors will be logged to the log file.
  • Info - Basic information, warnings, errors and critical errors will be logged to the log file.
  • Debug - Detailed information about all actions will be logged to the log file. You can use this information when troubleshooting.
Info
agentPathYou can define an alternate path of the Agent log files here.
The default location is:
  • Windows: %ProgramData%\Liquit\Agent\Logs\Agent.log
  • macOS: /Library/Logs/com.liquit.Agent/Agent.log
Agent.log
userHostPathYou can define an alternate path of the userhost log files here.
The default location is:
  • Windows: %LOCALAPPDATA%\Liquit\UserHost\Logs\UserHost.log
  • macOS: /Users/xxx/Library/Logs/com.liquit.Agent/UserHost.log
UserHost.log
rotateCountThe number of logfiles that will be archived.5
rotateSizeThe limit of logfile size in bytes. When this limit is reached, a new logfile will be created and the old file will be archived.1048576

Login

This element controls the login behaviour for the Liquit Universal Agent.

{
    "login": {
        "enabled": true,
        "sso": true,
        "identitySource": "LIQUIT",
        "timeout": 4
    }
}
KeyDescriptionDefault
enabledIf set to true, the user will be prompted for login.true
ssoIf set to true, the Universal Agent will use the value of the identity source key you provide, to facilitate SSO.false
identitySourceThe default identity source used to log in the user. Use the name of the identity source as you defined it within Liquit Workspace.
timeoutThe interval in seconds after which the Liquit Workspace login prompt will be displayed if SSO could not be performed within the interval.4

Icon

Controls the behaviour of the system tray icon.

{
    "icon": {
        "enabled": true,
        "exit": true
        "timeout": 30
    }
}
KeyDescriptionDefault
enabledIf set to false, the tray icon is hidden from the user.true
exitIf set to false, the quit option from the icon's context menu in the system tray is hidden. The quit option will always be disabled if the launcher is enabled and is not allowed to close.true
timeoutThe number of seconds Liquit Workspace waits for the Windows shell to load in order to display the system tray icon. Note that there is no maximum time limit.30

Cache

This element controls the settings of the cache.

{
    "cache": {
        "enabled": true,
        "offline": true,
        "path": "Cache",
        "tempPath": "Temp",
        "packageTempPath": "${TEMP}",
        "autoClean": true, 
        "expireContent": 90
    }
}
KeyDescriptionDefault
enabledIf set to true, the local cache will persist even after the session ends.true
offlineIf set to true, the offline mode will be available for the local device. If set to false, the packages marked offline will not be automatically downloaded and the Liquit Launcher won't switch to offline mode.true
pathThe location on the local device where all the content used by the agent is cached. Note that this path must be relative to the Liquit Workspace directory. By default, this path is configured to:
  • Windows: %ProgramData%\Liquit\Agent\Cache
  • macOS: /Library/Caches/Liquit/Agent/Cache
Cache
tempPathThe temp directory on the local device, used for uploading folders to the Liquit Workspace. By default, this path is configured to:
  • Windows: %ProgramData%\Liquit\Agent\Temp
  • macOS: /Library/Application Support/com.liquit.Agent/Temp
Temp
packageTempPathThe default temp directory on the local device, used for the ${PackageTempDir} variable.${TEMP}
autoCleanIf set to true, the stale content from the local cache of devices is automatically deleted:
  • all content superseded by a new version is deleted immediately.
  • all content that is inactive for a certain period of time is automatically deleted at the end of the period set in the expireContent key.
true
expireContentThe period after which the inactive content from the local cache of devices is deleted automatically. For example, if a user does not log in to the device for at least 90 days, the local cache content of the user is deleted automatically.90

Native Icons

Modify the behaviour of the native icons configured for package entitlements that allow you to display Liquit icons on certain locations within the device's operating system.

{
    "nativeIcons": {
        "enabled": true,
        "primary": true,
        "startMenuPath": "${Programs}\\Liquit"
    }
}
KeyDescriptionDefault
enabledAllow Liquit Workspace to push native icons configured for package entitlements to the operating system of devices.true
primaryIf set to true, only icons from the zone defined in the zone key in the Agent.json file will be pushed.true
startMenuPathThe location where the Start Menu items will be displayed; it allows you to specify a different directory than Liquit. This option is available only for Windows.${Programs}\\Liquit

Triggers

Modify the behaviour of the events configured for package entitlements.

{
    "triggers": {
        "enabled": true,
        "primary": true
    }
}
KeyDescriptionDefault
enabledAllow Liquit Workspace to execute events like refresh or login for example.true
primaryIf set to true, the Agent will trigger events only for the primary zone defined in the zone key in the Agent.json file.false

Refresh

Modify the behaviour of the agent refresh process.

{
    "refresh": {
        "manual": true,
        "interval": 3600
    }
}
KeyDescriptionDefault
manualIf set to false, the refresh option from the icon's context menu in the system tray is hidden.true
intervalThis value represents the time interval between Liquit Workspace refreshes.3600

Launcher

{
    "launcher": {
        "enabled": true,
        "state": "Default",
        "start": "Auto",
        "tiles": false,
        "minimal": false,
        "contextMenu": true,
        "sideMenu": "Tags",
        "close": true
    }
}
KeysDescriptionDefault
enabledEnable or disable the Liquit Launcher.true
stateDefines how the Liquit Launcher will be shown on start up:
  • Default - Default sized window
  • Minimized - Minimized window
  • Maximized - Maximized window
Default
startDefines when the launcher is started:
  • Disabled - Liquit Launcher will not start during login.
  • Auto - When connected to the zone or offline mode is available.
  • Connected - When connected to the zone.
  • Always - Always open Liquit Launcher, even if connection to the zone fails or offline mode isn't available.
Auto
tilesIf set to true, Liquit Workspace will use the tile-themed skin.false
minimalIf set to true, the Side Menu and tabs (Workspace, Contacts, Catalog, Manage) are hidden. Only the toolbar without the side menu toggler is displayed.false
contextMenuIf set to true, the context menu is available across Liquit Launcher.true
sideMenuChoose which tab(s) should be opened by default in the Side Menu.:
  • filters
  • tags
  • teams
  • categories
closeIf set to false, the X close button of the Liquit Launcher window is disabled and the quit option from the icon's context menu in the system tray is hidden.true

Restrict Zones

Define which Liquit Zones are always allowed to communicate with the local Agent.

{
    "restrictZones": false
}

If set to true, only the zones you list will have access to the local Agent. If set to false, a warning will be displayed asking the user if the zone where he wants to navigate is allowed to access the agent. The default value is false.

Trusted Zones

Here you can add additionally trusted zones.

{
    "trustedZones": [
        "zone1.liquit.com",
        "zone2.liquit.com",
        "*.dev.liquit.com"
    ]
}

Events

Configure how event data is uploaded to server when the Agent triggers the event.

{ 
     "events": { 
         "enabled": true, 
         "interval": 30 
     } 
} 
KeysDescriptionDefault
enabledIf set to true, event data is uploaded from the agent to the server.true
intervalThe time interval in seconds when the event data is uploaded from the Agent to the server.30

Web Socket

This protocol allows a more efficient way of handling data. This option is mandatory for the push event feature described in the Events section.

{
	"webSocket": {
		"enabled": true
	}
}

Was this article helpful?