1E Client command-line parameters

Command-line interface (CLI) parameters available to the 1E Client executable.

  • Some CLI actions invoke the 1E Client itself, others are used to control execution of the 1E Client. Normally a user does not have to be aware of the options, but they can be useful for testing and debugging.

  • If 1E.Client.exe is run without a CLI parameter, it will output a usage message showing the options and syntax.

  • The syntax shown below shows all parameters starting with - but you can use / instead. CLI parameters are mutually exclusive unless noted otherwise.

  • When running these commands from a console, run as administrator (Windows) or prefix the commands with sudo (non-Windows).

A popular use of the CLI is to reconfigure settings in the 1E Client configuration file using the -reconfigure name1=value1 ... and -restart [-immediate] parameters.

For further guidance on using the -reconfigure parameter, please refer to Reconfiguring the 1E Client.

Command-line parameters

-console

Instead of running the 1E Client as a service or daemon, run it as a console application. To stop the 1E Client, press ctrl-C.

This mode is for testing and should not be used unless advised by 1E.

-runservice

This is the normal invocation of the 1E Client to run it as a service or daemon.

Do not use this mode from the command line.

-uninstall[=module1,module2,...]

Run the uninstall action on all (by default) or the specified modules. Case is not significant.

Most modules use the default uninstall action which does nothing, but a few such as Nomad perform important tasks. This CLI action checks that the 1E Client service/daemon is not currently running, and aborts if it is, because it is not safe to uninstall a module that is active.

-getdbkey

In rare circumstances 1E Support may ask for a copy of the 1E persistent storage database files for diagnostic purposes. This option gives an encrypted form of the DB's key.

Do not use this option unless requested by 1E Support.

Because the DB is generated and encrypted by the 1E Client runs using the system account, you must fetch the key in the same context. On Windows the SysInternals psexec command is convenient for this, as follows:

Copy 
psexec -s 1E.Client.exe -getdbkey

-reconfigure name1=value1 ...

This is a convenient way to change settings in the 1E Client configuration file. One or more name=value pairs should be specified, and the configuration file will be updated. A value can be empty, although that is only valid for a few configuration settings. Case of the name-part is not significant, but the case of the value is preserved when it is written to the configuration file.

You can change only configuration file settings using this method, you must use other methods to change registry settings. For further guidance, please refer to Reconfiguring the 1E Client.

Any name=value pair can be added to the configuration file, no validation is done. If a key with the name does not already exist in the configuration file, it will be added to the file and a warning output (in case the name has been misspelled).

This CLI action can be used in combination with -start and -restart (and -stop although that is not very useful).

The 1E Client will not pick up the new configuration value(s) until it is restarted.

Examples

Set the Switch and BackgroundChannelUrl values, then restart the 1E Client (after a random stagger interval) to pick up the new values.

Windows:

Copy 
"C:\Program Files\1E\Client\1E.Client.exe" -reconfigure Switch=ACME-DMZ01.ACME.LOCAL:4000 BackgroundChannelUrl=https://ACME-DMZ01.ACME.LOCAL:443/Background/ -restart

Linux and Solaris:

Copy 
/usr/sbin/1E.Client -reconfigure Switch=ACME-DMZ01.ACME.LOCAL:4000 BackgroundChannelUrl=https://ACME-DMZ01.ACME.LOCAL:443/Background/ -restart

macOS:

Copy 
cd /Library/Application Support/1E/Client # Do not prefix cd with sudo
./1E.Client -reconfigure Switch=ACME-DMZ01.ACME.LOCAL:4000 BackgroundChannelUrl=https://ACME-DMZ01.ACME.LOCAL:443/Background/ -restart

-stdin

Read configuration values from standard input rather than the configuration file. This is only used with -console when debugging.

This mode is for testing and should not be used unless advised by 1E.

-stop [-immediate]

Stop the 1E Client service or daemon if it is running. If -immediate is given, the 1E Client will shut down immediately (or as soon as possible to preserve instruction integrity), otherwise it will happen after a random number of seconds in a range between the ConnectionRetryTimeInSecondsMin and ConnectionRetryTimeInSecondsMax configuration values. This is to prevent flooding, for example, the Switch with offline messages, depending on which client options have been enabled.

-start [-immediate]

Start the 1E Client service or daemon if it is not already running. If -immediate is given, the 1E Client will start immediately, otherwise it will happen after a random number of seconds in a range between the ConnectionRetryTimeInSecondsMin and ConnectionRetryTimeInSecondsMax configuration values. This is to prevent flooding, for example, the Switch with online messages, or Nomad content registration messages, depending on which client options have been enabled.

-restart [-immediate]

Stop the 1E Client service or daemon if it is running, then start it. If -immediate is given, this will happen immediately, otherwise it will happen after a random number of seconds in a range between the ConnectionRetryTimeInSecondsMin and ConnectionRetryTimeInSecondsMax configuration values. This is to prevent flooding, for example, the Switch with offline and online messages, or Nomad content registration messages, depending on which client options have been enabled.

-provisioningkey=value

Sets or updates the client certificate provisioning key. This is only supported on Windows and macOS.

Can be used alongside the Start/Stop/Restart CLI parameters.

If the value passed is 'none', the provisioning key stored in the persistent storage is deleted. On Windows, this also clears the registry entry at HKLM\Software\1E\Client\ProvisioningKey if present.