SYNOPSIS

dcc [GLOBAL OPTIONS]

dcc set-pcon-login-refresh-token [GLOBAL OPTIONS] [OPTIONS]

dcc clear-pcon-login-refresh-token [GLOBAL OPTIONS] [OPTIONS]

dcc show-pcon-login-user [GLOBAL OPTIONS] [OPTIONS]

dcc set-update-source [GLOBAL OPTIONS] [OPTIONS]

dcc show-update-source [GLOBAL OPTIONS] [OPTIONS]

dcc add-local-favorite [GLOBAL OPTIONS] [OPTIONS]

dcc activate-local-favorite [GLOBAL OPTIONS] [OPTIONS]

dcc remove-local-favorite [GLOBAL OPTIONS] [OPTIONS]

dcc show-local-favorites [GLOBAL OPTIONS] [OPTIONS]

dcc add-pcon-login-favorite [GLOBAL OPTIONS] [OPTIONS]

dcc activate-pcon-login-favorite [GLOBAL OPTIONS] [OPTIONS]

dcc remove-pcon-login-favorite [GLOBAL OPTIONS] [OPTIONS]

dcc show-pcon-login-favorites [GLOBAL OPTIONS] [OPTIONS]

dcc show-settings [GLOBAL OPTIONS] [OPTIONS]

dcc update-settings [GLOBAL OPTIONS] [OPTIONS]

dcc show-monitoring-settings [GLOBAL OPTIONS] [OPTIONS]

dcc update-monitoring-settings [GLOBAL OPTIONS] [OPTIONS]

dcc show-schedule-settings [GLOBAL OPTIONS] [OPTIONS]

dcc update-schedule-settings [GLOBAL OPTIONS] [OPTIONS]

dcc service-status [GLOBAL OPTIONS]

dcc update [GLOBAL OPTIONS] [OPTIONS]

dcc install-log [GLOBAL OPTIONS] [OPTIONS]

DESCRIPTION

dcc can be used to perform various actions with pCon.update DataClient (e.g. query/change the configuration, perform updates, …​). For that dcc provides various subcommands as described below.

Note
 On Windows administrator privileges are required. If UAC is active, it is advisable to run dcc only from an already elevated command prompt. Otherwise dcc will be elevated via UAC in a new window that disappears as soon as the command has finished, making it impossible to read its output.

IMPORTANT CHANGES IN VERSION 1.12

DataClient 1.12 is phasing out authentication via username/password in favor of more secure authentication with OAuth via pCon.login.

To facilitate this, various commands and options have been adjusted, added or deprecated/removed.

Most importantly you should now use the set-pcon-login-refresh-token command instead of update-settings --user=example-user --password. Please also see the section on refresh tokens for details on the behaviour of those tokens.

Choosing where you obtain your updates from (formerly update-settings --server) has also been simplified, please refer to set-update-source for details.

Most old commands and options are still supported through a compatibility layer. It is still advisable to adjust your script to only use the new commands and options, both for improved robustness and for future proofing (as the old commands will be completely removed in the future). dcc will emit a warning when a deprecated option is used.

LICENSING

To accomplish updates, dcc requires a dedicated license. Viewing or changing settings is possible without license.

If you intend to perform updates using dcc, please contact you pCon software vendor to purchase the license. Please ask for a DataClient Command Line Interface Update License. If you don’t already have a DataClient PRO license, you also need to purchase one, because it is an requirement for the Command Line Interface Update License.

Currently there are two licensing schemes available:

  • pCon.login based licensing. - The license will be bound to a pCon.login user and internet access is required, even when only performing updates from a local directory.

  • EAI (.lic file) based licensing. In this case the license will be bound to a specific machine, see below for instructions on how to obtain/use such a license

When in doubt, a pCon.login based license should be preferred as it is easier to handle and support for EAI-based licenses may be discontinued in the future.

pCon.login based license

Ask your vendor to obtain such a license. You can than manage access to this license inside your organization via the pCon.login website. You need to be logged in either via the assistant or by using the set-pcon-login-refresh-token or activate-pcon-login-favorite commands.

EAI based licenses

If you want to use an EAI based license for dcc on Microsoft Windows we recommended obtaining and installing the license via EGR-LicenseClient.

Otherwise follow these steps to manually request and install a license:

  1. Execute ehostid in the bin directory of DataClient to determine the Host ID.

  2. Execute hostname to determine the host name.

  3. Contact your software vendor and ask for a license file. Please provide the host name and host id determined above in the inquiry.

  4. Put the received .lic file in the etc/licenses directory of DataClient.

NOTES COMMAND LINE INTERPRETATION

When passing arguments on the command line some characters may have to be escaped/quoted. The details of this are shell specific, so please refer to your shells documentation for specifics on what needs to be quoted and how this can be accomplished. In general letters, digits, dash (-) and underscore (_) can safely be used without quoting/escaping them. If in doubt, enclosing the argument in single quotes (') for unix shells or double quotes (") for windows (cmd.exe) is usually sufficient.

Most options for dcc can either be specified as a long option (starting with --) or a short option (starting with a single -).

Short options that do not need a value can be grouped: -abc is equivalent to -a -b -c

If the option needs a value it can either be specified

  • as a separate argument (-u username or --user username)

  • directly following a short option (-uusername)

  • directly following a long option, delimited by an equals sign (--user=username)

Long options can be abbreviated as long as they are unambiguous (--user would work just as well as --username as long as no other long option starts with --user)

REFRESH TOKENS

In order to obtain updates from the internet and for licensing purposes DataClient must be linked to a pCon.login account. Since interactive logins are usually not possible for users of dcc this is usually done by obtaining a refresh token from:
https://login.pcon-solutions.com/account/access

Tokens are not automatically revoked by dcc as they may be needed again later/elsewhere. Some commands offer an option to revoke the token. When these options are used no checks are performed on whether the token is still in use by saved favorites.

GLOBAL OPTIONS

--version

Print the pCon.update DataClient version to standard output and exit.

--help

Display a short usage overview and exit. If used together with a subcommand the option summary of that command will be displayed.

--socket

Override the default location of the socket used to communicate with the service.

THE set-pcon-login-refresh-token SUBCOMMAND

This command sets a refresh token that links pCon.update DataClient to a pCon.login account. This is used to license pCon.update DataClient itself and to obtain updates available to this account via the pCon.update Server (update source: internet).

This command is not necessary if you log in interactively via the wizard.

To create such a token please follow these steps:

OPTIONS

-t, --refresh-token=TOKEN

The refresh token of the pCon.login account that should be used

-r, --revoke-existing

This will revoke the currently active refresh token before setting the new token.

If you use do not specify the token on the command line you will be asked to enter the password on the console.

Note
 Depending on the system and its configuration other users on the system may be able to see refresh tokens passed on the command line!

THE clear-pcon-login-refresh-token SUBCOMMAND

This command removes the refresh token of the active pCon.login account. Please note that you will no longer be able to access your (pCon.login based) license or fetch updates from the pCon.update server until a new valid token is set.

OPTIONS

-r, --revoke

Revoke the token refresh token instead of just clearing it.

THE show-pcon-login-user SUBCOMMAND

This shows information about the currently active pCon.login account (used for licensing and fetching updates from the internet)

THE set-update-source SUBCOMMAND

Updates can be installed either via the internet from the pCon.update server, or from a local directory. A local directory may also be UNC share in the local network.

OPTIONS

--internet

Sets the active update source so updates will be fetched from the internet via the pCon.update server.

--local

Sets the active update source so updates will be fetched from a local directory

Note
 Usually updates can only be installed from one source. In special cases your license may allow using local and internet updates at the same time. In that case both --internet and --local must be specified at the same time
--local-path=PATH

Set the path to the local directory from which updates should be installed. (this will only be used when the active update source is --local)

--local-user=USER

Set username to use for accessing the local directory (only relevant for UNC shares).

--local-password=PASSWORD

Set password to use for accessing the local directory (only relevant for UNC shares).

If you use this option but do not specify a password you will be asked to enter the password on the console.

Note
 Depending on the system and its configuration other users on the system may be able to see passwords passed on the command line!
--ignore-missing-license

Change update source even if the current license does not allow it. Trying to install updates will fail until an appropriate license is acquired.

THE show-update-source SUBCOMMAND

Shows the currently active source(s) from which updates will be installed.

THE update-settings SUBCOMMAND

Changes various settings of pCon.update DataClient as described below.

OPTIONS

--proxy-mode=MODE

Set the proxy mode, where MODE can be:

os

Determine the proxy settings from the operating system settings

manual

Manually specify proxy settings

-P, --proxy=PROXY

Use the proxy server PROXY given as ‘host:port’. Use an empty string to disable usage of a proxy (--proxy='').

--proxy-user=USERNAME

Specify the USERNAME used to authenticate with the proxy server

--proxy-password=PASSWORD

Specify the PASSWORD used to authenticate at the specified server.

If you use this option but do not specify a password you will be asked to enter the password on the console.

Note
 Depending on the system and its configuration other users on the system may be able to see passwords passed on the command line!
-d, --data-dir=DIRECTORY

Install OFML data to DIRECTORY.

-D, --package-download-dir=DIRECTORY

Set the package download directory.

-l, --app-language=LANGUAGE_CODE

Set the application language to the language determined by LANGUAGE_CODE. If no language is specified a list of available languages will be printed and the program will exit.

-L, --data-language=LANGUAGE_CODE

Set the data language to the language determined by LANGUAGE_CODE. If no language is specified a list of available languages will be printed and the program will exit.

--config-var=NAME:'VALUE'

Set the configuration variable NAME to VALUE. This is mainly intended for debug purposes, but could also be useful in some advanced scenarios. This option can be provided multiple times to change different values at once.

EXAMPLES

Example 1. Define the installation directory for OFML data:

dcc update-settings -d /home/eaiws/ofml

Example 2. Manually specify a proxy:

dcc update-settings --proxy-mode manual -P localhost:3128

Example 3. Disable usage of a proxy:

dcc update-settings --proxy-mode manual -P ""

Example 4. Use operating sytem settings to determine the proxy settings:

dcc update-settings --proxy-mode os

Example 5. Show list of available application languages

dcc update-settings -l

Example 6. Set the application and the data language to english

dcc update-settings -l en -L en

THE show-settings SUBCOMMAND

Displays the current settings on standard output. If no options are specified an overview of the current settings will be shown, otherwise only specifically requested information is included in the output.

OPTIONS

-P, --proxy

Show the currently configured proxy.

-d, --data-dir

Show the currently configured OFML data directory.

-D, --package-download-dir

Show the currently configured package download directory.

-l, --app-language

Show the current application language.

-L, --data-language

Show the current data language.

--config-var=NAME

Show the value of the configuration variable NAME. This is mainly intended for debug purposes, but could also be useful in some advanced scenarios.

EXAMPLES

Example 7. Show an overview of the current settings:

dcc show-settings

Example 8. Show just the currently defined data directory:

dcc show-settings -d

THE add-local-favorite SUBCOMMAND

Add configuration for a local update source as a favorite. That favorite can later be set as active update source via the activate-local-favorite subcommand.

OPTIONS

-n, --name=NAME

Set the name of the new favorite. This option is required and must specify a unique name for the favorite.

-P, --path=PATH

Set the path containing the updates that this favorite should refer to. This option is required.

-u, --user=USER

When the local path refers to a UNC share this option can be used to specify a user that should be used for authentication with the server before trying to access the directory.

-p, --password=PASSWORD

When the local path refers to a UNC share this option can be used to specify a password that should be used for authentication with the server before trying to access the directory.

If you use this option but do not specify a password you will be asked to enter the password on the console.

Note
 Depending on the system and its configuration other users on the system may be able to see passwords passed on the command line!

THE activate-local-favorite SUBCOMMAND

This command activates a previously saved favorite as update source. This will - Set the update source to "local" - Set the path for local updates to the path of the favorite - Set username/ password for accessing the local path to the credentials saved in the favorite

OPTIONS

-n, --name

Name of the favorite that should be activated

THE remove-local-favorite SUBCOMMAND

This command removes a previously saved favorite. This will not affect the currently selected update source, even if it is equivalent to the favorite.

OPTIONS

-n, --name

Name of the favorite that should be removed.

THE add-pcon-login-favorite SUBCOMMAND

Add a pCon.login account as a favorite That favorite can later be set as activated via the activate-pcon-login-favorite subcommand.

OPTIONS

-n, --name=NAME

Set the name of the new favorite. This option is required and must specify a unique name for the favorite.

--refresh-token=TOKEN

Specify the refresh token of the pCon.login account to associate with this favorite.

If you use this option but do not specify a token you will be asked to enter it on the console.

Note
 Depending on the system and its configuration other users on the system may be able to see tokens passed on the command line!

THE activate-pcon-login-favorite SUBCOMMAND

This command activates a previously saved favorite. This will * Set the update source to "internet" * Use the associated pCon.login account of licensing and receiving updates from the pCon.update server

Note
 The currently active account will be replaced by the favorite without revoking it’s token. If you want to revoke the currently active token use clear-pcon-login-refresh-token --revoke before using this command.

OPTIONS

-n, --name

Name of the favorite that should be activated

THE remove-pcon-login-favorite SUBCOMMAND

This command removes a previously saved favorite. This will not affect the currently selected update source, even if it is equivalent to the favorite.

OPTIONS

-n, --name

Name of the favorite that should be removed.

THE show-monitoring-settings SUBCOMMAND

Show settings related to the remote monitoring feature of pCon.update DataClient.

EXAMPLES

Example 9. Show all currently defined monitoring settings:

dcc show-monitoring-settings

THE update-monitoring-settings SUBCOMMAND

Change settings related to the remote monitoring feature of pCon.update DataClient.

OPTIONS

-e, --event-mails

Enable sending of e-mail notifications when certain events ( e.g update performed) occur. The specific events for which e-mails should be send have to be chosen with the --send-on-update, --send-on-overdue and --send-on-manual-intervention options.

-E, --no-event-mails

Do not send e-mail notifications for events.

-u, --send-on-update

Send e-mail notification when an update is performed.

-U, --no-send-on-update

Do not send e-mail notifications when an update is performed

-o, --send-on-overdue

Send e-mail notification when an update is overdue.

-O, --no-send-on-overdue

Do not send e-mail notifications when an update is overdue.

-m, --send-on-manual-intervention

Send e-mail notification when an update requires manual intervention (interactive update is pending, errors occurred during the installation, …​).

-M, --no-send-on-manual intervention

Do not send e-mail notifications when an update is overdue.

-s, --send-summary

Regularly send summarized status e-mail.

-S, --no-send-summary

Do not send summarized status e-mail.

-c, --send-summary-on-change

Only send the summary e-mail when it has changed since the last send e-mail

-C, --send-summary-always

Always send the status e-mail, even if it is not changed since the last mail was send.

-i, --summary-interval=INTERVAL

Set the interval with which the summary e-mail should be send to INTERVAL days.

-d, --overdue-tolerance=TOLERANCE

An update will be considered overdue if it’s scheduled date is exceeded by TOLERANCE days (minimum 1 day, default 3 days).

-n, --computer-name

Set the computer name that should be used in in e-mails (if not specified this defaults to the systems host name)

-a, --addresses

Comma separated list of e-mail addresses to receive notification e-mails.

EXAMPLES

Example 10. Receive e-mail notifications when an update is overdue or requires manual intervention as well as a weekly summarized status email to user@example.com:

dcc update-monitoring-settings -eoms -i 7 -a user@example.com

Example 11. If you later decide that you want an e-mail for every update even if nothing special has happened:

dcc update-monitoring-settings --send-on-update

Example 12. Disable the summary e-mail:

dcc update-monitoring-settings -S

THE update-schedule-settings SUBCOMMAND

Allows the configuration of automatic updates and the update notification.

OPTIONS

-m, --mode=MODE

Set the update mode to MODE, where MODE can be:

automatic

Updates will be performed automatically according to the specified update interval and time.

manual

Updates can only be manually triggered.

notification

This mode is only available on Windows. In this mode a tray icon will inform you whenever new updates are available (the check is performed as specified by --interval).

-i, --interval=PERIOD

Specifies the interval between updates. A PERIOD consists of a number and a unit. The following units are allowed:

h

Hour

d

Day

w

Week

m

Month

If the mode is set to notification the interval can also be set to login, which means that the update check will be performed each time the user logs in.

-n, --next-update=DATE

Schedule the next update for DATE. Date must be in the format YYYY-mmm-ddd HH:MM:SS.

EXAMPLES

Example 13. Enable automatic updates every 3 days starting at October the 1st 3 o’clock:

dcc update-schedule-settings -m automatic -i 3d -n ‘2012-10-01 03:00:00’

Example 14. Show update notification when the user logs in (only works on Windows):

dcc update-schedule-settings -m notificaton -i login

Note
 Automatic updates will only be performed if the service is running. On Linux this must be configured manually, usually by registering the service with your machines init-system and configuring it to start in the appropriate runlevels. On Windows no special action is necessary, the service will automatically be configured as system service.

THE show-schedule-settings SUBCOMMAND

Show the current configuration of automatic updates/ the update notification.

EXAMPLES

Example 15. Show current settings:

dcc show-schedule-settings

THE service-status SUBCOMMAND

Shows information about the state of the automatic update installation.

  • current state of the service (idle, downloading, …​)

  • time and result of the last update

  • next scheduled update time (if updates are to be performed automatically)

  • currently configured update interval

  • progress information of a currently active update

THE update SUBCOMMAND

This will manually trigger an update cycle.

OPTIONS

--no-wait

Do not wait until the update process has completed.

-q, --quiet

Do not display progress information.

EXIT CODES

If the update was performed successfully the exit code will be zero. Any non-zero value indicates an error.

The following table lists the meaning of specific exit codes:

Exit code Meaning

0

Update was successfully performed

1

Error during execution of the update process

102

Error during self update

103

Error during installation of packages

104

Authentication with the server failed

105

Update list contained Packages with unsatisfied dependencies

106

Interactive updates are pending

107

Network was not available

108

Update not possible due to running applications

109

Update not possible due to ongoing server maintenance

110

License not available

111

Update was aborted

112

Fatal error during update

113

Update failed

114

System updated, but some servers could not be reached

EXAMPLES

Example 16. Perform an update, progress will be shown on the console.

dcc update

THE install-log SUBCOMMAND

Show packages installed in the specified time frame.

OPTIONS

-i, --interval=PERIOD

Only show updates during the last PERIOD. If not specified the default is 1 month. A PERIOD consists of a number and a unit. The following units are allowed:

h

Hour
d

Day
w

Week
m

Month
-a, --all

Show all packages. Without this option only catalogs and failed packages will be displayed.

EXAMPLES

Example 17. Show packages installed in the last two weeks

dcc install-log -i 2w

EXIT STATUS

All subcommands exit with status 0 on success and non-zero on failure.