This is the documentation of an old opsi version. The documentation for the current version 4.3 can be found here.

opsi-client-agent

Overview

In order that the distribution of software does not become unmanageable, a client has to notice that new software packages or updates are available and install them. Any form of user interaction is to be avoided during the installation, so that this can take place unattended and the necessary installations are not interrupted by uncertain users.

With opsi, these requirements are met by an agent on the client:

The so-called 'opsi-client-agent' is installed on the client. This usually checks at the start of the client and before the user logs in, based on configuration information on the 'opsi-configserver', whether an update should be installed for this client.

If software is to be installed, the script-controlled installation program 'opsi-script' is started. The necessary scripts and software packages are available on a file share, the so-called 'opsi-depot'. During this time, there is no need and no possibility for the user to intervene in the installation process.

To prevent a user from logging on to the system before completing the installation and thus disrupting the installation process, the so-called 'opsi-Loginblocker' is also installed, which only allows logon after the installation has been completed.

In order for software packages to be installed without interaction with the program 'opsi-script', they have to be prepared for this. See the chapter 'Integrating new software packages in the software distribution of opsi' in the 'opsi-getting-started' manual.

Directories of the opsi-client-agent

The 'opsi-client-agent' is installed in %ProgramFiles%\opsi.org\opsi-client-agent.

This directory contains all components of the 'opsi-client-agent' such as 'opsiclientd', 'opsi-notifier', 'opsi-script' and some libraries. The configuration files and graphical templates of the mentioned programs can also be found here.
The directory %ProgramFiles%\opsi.org\opsi-client-agent is protected against changes by users without administrative privileges.
The directory %ProgramFiles%\opsi.org\opsi-client-agent\opsiclientd contains the configuration file of 'opsiclientd' and can only be accessed with administrative rights.

Furthermore there exists the directory c:\opsi.org. In this directory a number of variable data are stored, like log files (subdirectory log), packet cache (WAN extension), certificates and some more. The directory c:\opsi.org can be read only with administrator rights.

The service: opsiclientd

'opsiclientd' is the basis of the 'opsi-client-agent'. It runs as a service with administrative rights and is started automatically at boot.

The main functions are:

  • Event-based control: There can be reacted to different events on the system. An event is, for example, the start of the operating system.

  • Control via web service: The web service of 'opsiclientd' can be accessed via the network. This interface is used to initiate installations ('push') but also for maintenance purposes.

  • Remote configuration: All essential configuration data of 'opsiclientd' can be edited globally or client-specifically via the 'Hostparameter'.

The 'opsi-client-agent' consists of several components:

  • 'opsiclientd': The central service of the 'opsi-client-agent'.

  • 'opsi-notifier': Window for information / communication with the user

  • 'opsi-Loginblocker': Blocks the login until the installations are completed.

Installation

As part of a new installation of an operating system via unattended setup with opsi, the 'opsi-client-agent' is automatically installed.

To uninstall the 'opsi-client-agent', the action request can be set to 'uninstall'.

For installation afterwards or for repair purposes, see chapter Subsequent installation of the opsi-client-agents.

opsiclientd

Core component of the 'opsi-client-agent' is the service 'opsiclientd'. This service starts on boot.

It performs the following tasks:

  • while the system is booting and the 'opsiclientd' is waiting for the GUI to come up, the 'block_login_notifier' is started and shows a padlock at the right upper corner of the screen.

  • Getting in action if the configuration event takes place. In case of action the 'opsiclientd' contacts the opsi server via web service (JSON-RPC) and asks for the configuration data and required actions.
    The default event is 'gui_startup' which will fire at boot time before user login.

  • Creates a named pipe which is used by the 'opsi-Loginblocker' to ask via JSON-RPC the 'opsiclientd' when to unblock the login.

  • Starting the 'opsi-notifier' for information and interaction with the user.

  • If needed, it connects to the 'opsi-depot' to update the local installation of 'opsi-script' and then starts it to process the 'Action-Requests' (software installation).

opsi notifier

The 'opsi-notifier' implements the interaction with the user. It displays status messages and may give the possibility to interact with the process.

There are different situations where the 'opsi-notifier' will become active in different ways:

blocking notifier

Indicates that the 'opsi-Loginblocker' is blocking

opsiclientd blocklogin notifier
Figure 1. opsiclientd blocklogin notifier
event notifier

Shows information about the current event.

opsiclientd event notifier
Figure 2. opsiclientd event notifier
action notifier

Shows state of the event processing

opsiclientd action notifier
Figure 3. opsiclientd action notifier
shutdown notifier

Gives information about a requested reboot / shutdown (if shutdown_warning_time > 0)
This is the default opsiclientd shutdown notifier :

opsiclientd shutdown notifier
Figure 4. opsiclientd shutdown notifier

There is a alternative kind of the opsiclientd shutdown notifier where you may choose the shutdown time from a dropdown control. This looks like:

Abbildung: opsiclientd shutdown notifier with shutdown time picker
Figure 5. opsiclientd shutdown notifier timepicker

You will find more details regarding the configuration of the opsiclientd shutdown notifier below:
[opsi-manual-clientagent-config-shutdown-notifier]

opsi-Loginblocker

The 'opsi-Loginblocker' is implemented as a 'credential provider filter' ('OpsiLoginBlocker.dll'). This 'credential provider filter' blocks all 'credential providers' until the opsiclientd reports, that all 'Produktaktionen' are finished or, if the opsiclientd is not reachable, until the connection timeout to the opsiclientd is reached (normally 120 seconds).

Processing sequence

How the opsiclientd works may be configured in many details. To understand these configuration options, it is necessary to understand the processing sequence. Here comes an overview of the work flow of a 'standard event' like the 'event_gui_startup'.

simplified work flow of a 'standard event'
Figure 6. simplified work flow of a 'standard event'

The most important parameters have the following relations:

If there is an error while connecting to the 'opsi-configserver', the log of this problem cannot be sent to the server. But you may find the log in the local log file opsiclientd.log in the log directory (c:\opsi.org\log\opsiclientd.log) at the client.

  1. If an event fires, the event_notifier_command will be started.
    Now the opsiclientd tries to reach the 'opsi-configserver' using the url address.
    If after user_cancelable_after seconds there is still no connection established, the 'opsi-notifier' will enable an 'Abort' button. If no connection could be established in connection_timeout seconds, the 'opsiclientd' connection process will be aborted and the event ends with an error message. To avoid a user from aborting, set user_cancelable_after = connection_timeout .

  2. After a successful connection to the 'opsi-configserver', the 'opsiclientd' checks if there are 'action requests' for this client. If there are 'action requests' and the action_warning_time > 0, the action_notifier_command will be executed.
    This is normally the 'opsi-notifier', which shows now the list of 'action requests' for this client for action_warning_time seconds.
    Is the action_warning_time = 0 (default) the action_notifier_command will not be executed.
    You may allow the user to suspend the process at this time by setting action_user_cancelable >= 0. The user may suspend the actions up to action_user_cancelable times. After action_user_cancelable aborts in sequence or if action_user_cancelable = 0 the user gets no possibility to suspend the actions.
    In every case there will be a button which allows the user to start the installations immediately without waiting for the count down of action_warning_time seconds. The messages displayed by the 'opsi-notifier' may be configured with the options action_message or action_message[lang] . This messages may contain the placeholders %action_user_cancelable% (total number of allowed suspensions) and %action_cancel_counter% (number of suspensions already used by the user).
    If the actions are not suspended by the user, the action_cancel_counter will reset and the 'opsi-script' will be executed to process the 'action requests'.

  1. If the 'opsi-script' terminates with a reboot or shutdown request, the shutdown_notifier_command will be executed if shutdown_warning_time > 0.
    The now starting shutdown_notifier_command shows for shutdown_warning_time seconds a message saying that the client will be rebooted. If shutdown_user_cancelable > 0 the user may suspend the reboot up to shutdown_user_cancelable times in sequence. If the user suspends the reboot, the shutdown_notifier_command will be restarted after shutdown_warning_repetition_time. The shutdown_notifier_command shows a message which may be configured by shutdown_warning_message or shutdown_warning_message[lang]. This message may contain the placeholders %shutdown_user_cancelable% (maximum number of allowed suspensions) and %shutdown_cancel_counter% number of suspensions already done by the user).
    If the client is rebooted (by the user or the 'opsi-client-agent') the %shutdown_cancel_counter% will be reset.
    If you set the following config (Host Parameter): opsiclientd.event_on_demand.shutdown_user_selectable_time = true, you will see a modified behavior:
    Now if the event on_demand runs, a alternative kind of the opsiclientd shutdown notifier will be displayed, where you may choose the shutdown time from a dropdown control.
    This modified behavior is event specific: you have to set it for every event where you need it. See also: opsiclientd shutdown notifier timepicker and Configuration via web service (Host Parameter).
    Because the time of shutdown is selected here by the user, the value of the parameter shutdown_warning_repetition_time is ignored in this case.

The sequence of event processing and user actions is visualized as a timeline graphic at the info page of the 'opsiclientd'.

(opsiclientd infopage).

Configuration

The following chapters show how to configure the opsi-client-agent.

Configuration of different events

To meet the requirements of the various different situations in which the 'opsi-client-agent' will become active, a slightly complex configuration is needed. To reduce the complexity, the configuration file uses something like inheritance.
In the 'opsiclientd' configuration section headers like [event_<config-id>] introduce a new event configuration section. An event configuration may be disabled by setting the section option active = false.

There are different types of event configurations (type).

  • There are 'event configuration templates' (type = template).
    Event configurations may inherit configurations from another event. In this case the option super points to the other event to inherit all parameters from (excluding the parameter active). These inherited parameters may be overridden by local parameters in the current event section. So an event section needs only those parameters which are different from the super event.
    Setting an event to active = false does not change anything in the inheritance process.

  • The other event types are:

    • gui startup
      A gui startup event starts while booting the client and loading the 'graphical user interface' (GUI). It is the most used event and set to active in the default configuration.

    • custom
      Event configurations of the type custom are fired by a wql event. A wql event is defined by the corresponding wql statement in the event configuration. If the wql statement is empty, the event will never be fired, but can be executed from the interactive web interface.

    • user login
      will be fired at the login of a user

    • timer
      will be fired all interval seconds

    • sync completed
      will be fired if the synchronization of configurations (sync_config_from_server) or products (cache_products) is completed.

    • sw on demand
      will be fired by the user choosing 'Start actions now' in the 'software-on-demand' web page of the opsiclientd. It will never be fired if 'software-on-Demand' is not used.

  • There are 'Preconditions'
    'Preconditions' define special system states (e.g. a user is logged on). In the 'opsiclientd' configuration a section header of the form [precondition_<precondition-id>] starts the declaration of a 'Precondition'. A 'Precondition' is true, if all declared options are true. An option not declared (but possible) is assumed as true.
    Possible options for 'Preconditions' are:

    • user_logged_in: is true if currently a user is logged on.

    • config_cached: is true if the caching of configuration data is completed (see: sync_config_from_server).

    • products_cached: is true if the caching of product files is completed (see: cache_products).

  • A 'Precondition' can be assigned to an event configuration.
    This can be done by giving the 'precondition' in curly brackets at the end of the event configuration section hedaer (e.g. [event_on_demand{user_logged_in}]).
    If there is a 'Precondition' in an event configuration header, there also must be a configuration for this event without any 'precondition'. Is there for example an event configuration event_on_demand{user_logged_in}, there also has to be an event configuration event_on_demand ! The event configuration with the precondition inherits all the parameters from the event configuration without 'precondition'.
    If the event is fired, first it will be checked which 'preconditions' are true. If there is no 'precondition' true, the configuration without 'precondition' is used. Is one 'precondition' true, the configuration is used, which is bound to this 'precondition'. If more than one of the 'preconditions' are true, the most specific event configuration is used (which is the configuration with the most matching options).

A small example for a better understanding:
While installing software it may be necessary to reboot the computer. Is there currently a user logged on, you should warn about the pending reboot. This warning should have a timeout and it may make sense to ask the user, if the reboot should be canceled (at the moment).
Is there no user logged on, it makes no sense to ask and wait for an answer. So in this case the reboot should take place immediately.
To handle these different situations, we configure the event_on_demand in the following way:

  • We define a 'Precondition' user_logged_in which comes true if a user is logged on to the system (user_logged_in = true).

  • In the default configuration for the event event_on_demand (without any 'Precondition') we set shutdown_warning_time = 0 (immediate reboot without warning).

  • At the configuration event_on_demand\{user_logged_in\} we set shutdown_warning_time = 300 (warning with 300 seconds timeout).

Working Window

To limit the functionality of an event to a certain time frame a so called 'working_window' can be configured for all events.

To enable the 'working_window' feature the key 'working_window' has to be added to the configuration of the event. If this key is not present, has no value, or an invalid value it is treated as empty and the event has no time limit.

Starttime and endtime must be entered in the format hh:mm and separated by a hyphen. Whitespaces between starttime and endtime are not allowed!

All events support the 'working_window' feature.
Configuration is done by adding the 'Hostparameter' 'working_window' to the event of your choice. This can be achived by using the 'opsi-configed', or via 'opsi-admin' on the 'opsi-configserver'.

The following example shows how to configure a 'working_window' for the event 'gui_startup' using 'opsi-admin'
See Configuration via web service (Host Parameter) for how to add 'Hostparameter' using 'opsi-configed'.

Example 1: Adding an empty 'working_window' for the event 'event_gui_startup' globally. The time restriction has to be configured client specific (see example 3).

opsi-admin -d method config_createUnicode opsiclientd.event_gui_startup.working_window

Example 2: Adding a 'working_window' with a timeframe between 20:00 and 07:00 for the event 'event_gui_startup' globally.

opsi-admin -d method config_createUnicode opsiclientd.event_gui_startup.working_window "gui_startup.working_window" "20:00-07:00"

Example 3: Client specific configuration of the 'working_window' using a timeframe from 07:00 to 19:00 for the event 'event_gui_startup'.

opsi-admin -d method configState_create opsiclientd.event_gui_startup.working_window "client.domain.de" "07:00-19:00"

If the starttime is higher than the endtime the 'working_window' will be valid over the nightly day change (23:59-0:00).
Example during the day (starttime < endtime): working_window=07:00-19:00
Example during the night (starttime > endtime): working_window=20:00-07:00

For the example "working_window=20:00-07:00" the opsiclientd log would look like this:

[5] [<timestamp>] [ event processing gui_startup] Current time 01:02:13.993000 is within the configured working window (20:00-07:00)

Configuration of ip version

The opsiclientd supports the IPv4 and IPv6 protocols when connecting to the opsi service. Normally the protocol is selected automatically when the connection is established. But there is also the possibility to configure the protocol version to be used. For this the option "ip_version" can be used in the section "global" of the opsiclientd.conf. Possible values are "4" (use IPv4), "6" (use IPv6) and "auto" (select protocol automatically, default value).

Proxy configuration

The proxy_url option of the global section of opsiclientd.conf can be used to configure the use of an HTTP(S) proxy.

# Use a proxy for connecting configservice
# proxy_url usage: http://<user>:<password>@<proxy-url>:<proxy-port>
# Example: http://proxyuser:proxypass123@proxy.domain.local:8080
# use proxy_url = system to use system proxy
proxy_url = system

There are three basic options:

proxy_url = system

The system’s proxy settings are used. This is the default.

proxy_url =

If no value (empty string) is set for proxy_url, no proxy server will be used. The system’s proxy settings will be ignored in this case.

proxy_url = <url>

The proxy server specified via the URL is used, and the system’s proxy settings are ignored. The URL must be specified in the form http(s)://<proxy-user>:<proxy-password>@<proxy-url>:<proxy-port>. Authentication for the proxy can also be configured here. Example: http://proxy.domain.tld:3128

Event configuration to control which products will be processed

With this new feature it’s possible over the configuration to control the list of products, that will be processed in Events with product groups:

There are (basically) two ways to use this control:

Blacklisting (excluding):

The option exclude_product_group_ids allows to configure a comma separated list of product Groups. The members of these groups will be excluded from the actual Event. Also if action request is set for this products. This products will be ignored in this event, but the action requests will not be changed.

White listing (including):

The option include_product_group_ids allows to also configure a comma separated list of products Groups. The members of this groups are the only products, that will be processed from the actual event if they have set action requests.

You can use these options globally from the default-Event. From that point this settings will be used in every event. You can also set these options in a special event. If you use the option on event_on_demand, you can control which products will not be installed in push installations, although they have an action request. On normal restart of the client, the products will be installed from gui_startup (default event) at startup. CAUTION: For Clients that work in WAN/VPN-mode you must set this options in sync-event and also in the cacheservice-section, because the cache service have no access to the configuration of main sync-event.

Product dependencies will not be observed by this feature. That means that you have to observe the process in order to prevent dependency issues.

Configuration via configuration file

On a 64bit Windows the configuration file is c:\program files (x86)\opsi.org\opsi-client-agent\opsiclientd\opsiclientd.conf.

On a 32bit Windows the configuration file is c:\program files\opsi.org\opsi-client-agent\opsiclientd\opsiclientd.conf.

This configuration file is UTF-8 encoded.
Any changes using editors which do not support this encoding (e.g. notepad.exe) may destroy any umlaut in this file.

The configuration written in this file may be changed by different configuration data, which come via web service after a successful connection to the 'opsi-server'.

A sample opsiclientd.conf:

; = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
; =     configuration file for opsiclientd                              =
; = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =


; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
; -     global settings                                                 -
; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[global]

# Location of the log file.
log_file = c:\\opsi.org\\log\\opsiclientd.log

# Set the log (verbosity) level
# (0 <= log level <= 9)
# 0: nothing, 1: essential, 2: critical, 3: errors, 4: warnings, 5: notices
# 6: infos, 7: debug messages, 8: more debug messages, 9: passwords
log_level = 4

# Client id.
host_id =

# Opsi host key.
opsi_host_key =

# Verify tls certificates
verify_server_cert = false

# Trust the uib opsi CA
trust_uib_opsi_ca = true

# Install opsi CA into os store
install_opsi_ca_into_os_store = false

# Which ip version to use (4/6/auto)
ip_version = auto

# On every daemon startup the user login gets blocked
# If the gui starts up and no events are being processed the login gets unblocked
# If no gui startup is noticed after <wait_for_gui_timeout> the login gets unblocked
# Set to 0 to wait forever
wait_for_gui_timeout = 120

# Application to run while blocking login
block_login_notifier = "%global.base_dir%\\opsi-notifier.exe" -s notifier\\block_login.ini

# Use a proxy for connecting configservice
# proxy_mode:
#   'system' will try to check the system setting,
#   'static' to use proxyurl from configfile/hostparameter
# proxy_url usage: http://<user>:<password>@<proxy-url>:<proxy-port>
# Example: http://proxyuser:proxypass123@proxy.domain.local:8080
proxy_mode = static
proxy_url =

# Suspend bitlocker on reboot
suspend_bitlocker_on_reboot = false

; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
; -     config service settings                                         -
; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[config_service]
# Service url.
# http(s)://<opsi config server address>:<port>/rpc
url =

# Conection timeout.
connection_timeout = 30

# The time in seconds after which the user can cancel the connection establishment
user_cancelable_after = 30

# If this option is set, the local system time will be synced with time from service
sync_time_from_service = false

; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
; -     depot server settings                                           -
; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[depot_server]

# Depot server id
depot_id =

# Depot url.
# smb://<depot address>/<share name>/<path to products>
url =

# Local depot drive
drive =

# Username that is used for network connection [domain\]<username>
username = pcpatch

; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
; -     cache service settings                                          -
; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[cache_service]
# Maximum product cache size in bytes
product_cache_max_size = 20000000000
# Members of this ProductGroups will be excluded from processing
exclude_product_group_ids =
# Only members of this ProductGroups will be excluded from processing
include_product_group_ids =

; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
; -     control server settings                                         -
; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[control_server]

# The network interfaces to bind to.
# This must be the IP address of an network interface.
# Use 0.0.0.0 to listen to all interfaces
interface = 0.0.0.0

# The port where opsiclientd will listen for HTTPS rpc requests.
port = 4441

# The location of the server certificate.
ssl_server_cert_file = %global.base_dir%\\opsiclientd\\opsiclientd.pem

# The location of the server private key
ssl_server_key_file = %global.base_dir%\\opsiclientd\\opsiclientd.pem

# The location of the static files
static_dir = %global.base_dir%\\opsiclientd\\static_html

# The maximum number of authentication failures before a client ip
# is blocked for an amount of time.
max_authentication_failures = 5

# Determines the event to use if action processing is triggered by systray / kiosk.
# Possible events are timer and on_demand.
# Possible values are auto, timer, and on_demand.
# If the value is set to auto then on WAN/VPN clients the timer event is used and on other clients the event on_demand.
process_actions_event = auto

; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
; -     notification server settings                                    -
; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[notification_server]

# The network interfaces to bind to.
# This must be the IP address of an network interface.
# Use 0.0.0.0 to listen to all interfaces
interface = 127.0.0.1

# The first port where opsiclientd will listen for notification clients.
start_port = 44000

# Port for popup notification server
popup_port = 45000

; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
; -     opsiclientd notifier settings                                   -
; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[opsiclientd_notifier]

# Notifier application command
command = "%global.base_dir%\\opsi-notifier.exe" -p %port% -i %id%

; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
; -     opsiclientd rpc tool settings                                   -
; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[opsiclientd_rpc]

# RPC tool command
command = "%global.base_dir%\\opsiclientd_bin\\opsiclientd_rpc.exe" "%global.host_id%" "%global.opsi_host_key%" "%control_server.port%"

; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
; -     action processor settings                                       -
; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[action_processor]
# Locations of action processor
local_dir = %global.base_dir%\\opsi-script
remote_dir = opsi-script\\windows\\x86
remote_common_dir = opsi-script\\common
filename = opsi-script.exe

# Action processor command
command = "%action_processor.local_dir%\\%action_processor.filename%" /opsiservice %service_url% /clientid %global.host_id% /username %global.host_id% /password %global.opsi_host_key%

# Load profile / environment of %run_as_user%
create_environment = false

; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
; -     events                                                          -
; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[event_default]
; === Event configuration
# Type of the event (string)
type = template
# Interval for timer events in seconds (int)
interval = -1
# Maximum number of event repetitions after which the event will be deactivated (int, -1 = forever)
max_repetitions = -1
# Time in seconds to wait before event becomes active (int, 0 to disable delay)
activation_delay = 0
# Time in seconds to wait before an event will be fired (int, 0 to disable delay)
notification_delay = 0
# Event notifier command (string)
event_notifier_command = %opsiclientd_notifier.command% -s notifier\\event.ini
# The desktop on which the event notifier will be shown on (all/current/default/winlogon)
event_notifier_desktop = all
# Block login while event is been executed (bool)
block_login = false
# Lock workstation on event occurrence (bool)
lock_workstation = false
# Logoff the current logged in user on event occurrence (bool)
logoff_current_user = false
# Get config settings from service (bool)
get_config_from_service = true
# Store config settings in config file (bool)
update_config_file = true
# Transmit log file to opsi service after the event processing has finished (bool)
write_log_to_service = true
# Shutdown machine after action processing has finished (bool)
shutdown = false
# Reboot machine after action processing has finished (bool)
reboot = false
# Members of this ProductGroups will be excluded from processing
exclude_product_group_ids =
# Only members of this ProductGroups will be excluded from processing
include_product_group_ids =
# Events will only be processes inside the working window, which can be specify like: 07:00-22:00
working_window =
# A command to execute at the end of event processing
post_event_command =

; === Sync/cache settings
# Sync configuration from local config cache to server (bool)
sync_config_to_server = false
# Sync configuration from server to local config cache (bool)
sync_config_from_server = false
# Sync configuration from local config cache to server after action processing (bool)
post_sync_config_to_server = false
# Sync configuration from server to local config cache after action processing (bool)
post_sync_config_from_server = false
# Work on local config cache
use_cached_config = false
# Cache products for which actions should be executed in local depot cache (bool)
cache_products = false
# Maximum transfer rate when caching products in byte/s (int, 0 = no limit)
cache_max_bandwidth = 0
# Dynamically adapt bandwidth to other network traffic (bool)
cache_dynamic_bandwidth = false
# Work on local depot cache
use_cached_products = false

; === Action notification (if product actions should be processed)
# Time in seconds for how long the action notification is shown (int, 0 to disable)
action_warning_time = 0
# Action notifier command (string)
action_notifier_command = %opsiclientd_notifier.command% -s notifier\\action.ini
# The desktop on which the action notifier will be shown on (all/current/default/winlogon)
action_notifier_desktop = all
# Message shown in the action notifier window (string)
action_message = Starting to process product actions. You are allowed to cancel this event a total of %action_user_cancelable% time(s). The event was already canceled %state.action_processing_cancel_counter% time(s).
# German translation (string)
action_message[de] = Starte die Bearbeitung von Produkt-Aktionen. Sie können diese Aktion insgesamt %action_user_cancelable% mal abbrechen. Die Aktion wurde bereits %state.action_processing_cancel_counter% mal abgebrochen.
# French translation (string)
action_message[fr] = Traitement des actions du produit. Vous êtes autorisé à annuler cet événement un total de %action_user_cancelable% fois. L'événement a été déjà annulée %state.action_processing_cancel_counter% fois.
# Number of times the user is allowed to cancel the execution of actions (int)
action_user_cancelable = 0

; === Action processing
# Should action be processed by action processor (bool)
process_actions = true
# Type of action processing (default/login)
action_type = default
# Update the action processor from server before starting it (bool)
update_action_processor = true
# Command which should be executed before start of action processor
pre_action_processor_command =
# Action processor command (string)
action_processor_command = %action_processor.command%
# The desktop on which the action processor command will be started on (current/default/winlogon)
action_processor_desktop = current
# Action processor timout in seconds (int)
action_processor_timeout = 10800
# Command which should be executed before after action processor has ended
post_action_processor_command =
# Activate or deactivate trusted installer Detection
trusted_installer_detection = true

; === Shutdown notification (if machine should be shut down or rebooted)
# Process shutdown requests from action processor
process_shutdown_requests = true
# Time in seconds for how long the shutdown notification is shown (int, 0 to disable)
shutdown_warning_time = 0
# Shutdown notifier command (string)
shutdown_notifier_command = %opsiclientd_notifier.command% -s notifier\\shutdown.ini
# The desktop on which the action notifier will be shown on (all/current/default/winlogon)
shutdown_notifier_desktop = all
# Message shown in the shutdown notifier window (string)
shutdown_warning_message = A reboot is required to complete software installation tasks. You are allowed to delay this reboot a total of %shutdown_user_cancelable% time(s). The reboot was already delayed %state.shutdown_cancel_counter% time(s).
# German translation (string)
shutdown_warning_message[de] = Ein Neustart wird benötigt um die Software-Installationen abzuschliessen. Sie können diesen Neustart insgesamt %shutdown_user_cancelable% mal verschieben. Der Neustart wurde bereits %state.shutdown_cancel_counter% mal verschoben.
# French translation (string)
shutdown_warning_message[fr] = Un redémarrage est nécessaire pour terminer l'installation du logiciel. Vous êtes autorisé à retarder le redémarrage un total de %shutdown_user_cancelable% fois. Le redémarrage a été déjà retardé %state.shutdown_cancel_counter% fois.
# Number of times the user is allowed to cancel the shutdown (int)
shutdown_user_cancelable = 0
# Time in seconds after the shutdown notification will be shown again after the user has canceled the shutdown (int)
shutdown_warning_repetition_time = 3600
# If enabled, the user can select a time for shutdown in the shutdown notifier. The selected time overrides shutdown_warning_repetition_time.
shutdown_user_selectable_time = false
# Time in seconds for how long the shutdown notification is shown when the user selected time is reached (int, 0 to disable, -1 to use shutdown_warning_time)
shutdown_warning_time_after_time_select = -1

[event_opsiclientd_start]
super = default
type = daemon startup
active = false
activation_delay = 10
max_repetitions = 0

[event_opsiclientd_start{cache_ready}]
active = false
use_cached_config = true
use_cached_products = true

[event_gui_startup]
super = default
type = gui startup
active = true
block_login = true
max_repetitions = 0

[event_gui_startup{user_logged_in}]
shutdown_warning_time = 3600
block_login = false

[event_gui_startup{cache_ready}]
use_cached_config = true
use_cached_products = true
action_user_cancelable = 3
action_warning_time = 60

[event_gui_startup{installation_pending}]
active = true

[event_on_demand]
super = default
type = custom

[event_on_demand{user_logged_in}]
shutdown_warning_time = 3600

[event_software_on_demand]
super = default
type = sw on demand
shutdown_warning_time = 3600

[event_sync]
super = default
type = template
process_actions = false
event_notifier_command =
sync_config_to_server = true
sync_config_from_server = true
cache_products = true
cache_dynamic_bandwidth = true

[event_timer]
super = sync
type = timer
active = false
interval = 3600

[event_net_connection]
super = sync
type = custom
active = false
wql = SELECT * FROM __InstanceModificationEvent WITHIN 2 WHERE TargetInstance ISA 'Win32_NetworkAdapter' AND TargetInstance.NetConnectionStatus = 2 AND PreviousInstance.NetConnectionStatus != 2

[event_sync_completed]
super = default
type = sync completed
event_notifier_command =
process_actions = false
get_config_from_service = false
write_log_to_service = false

[event_sync_completed{cache_ready_user_logged_in}]
reboot = true
shutdown_user_cancelable = 10
shutdown_warning_time = 3600

[event_sync_completed{cache_ready}]
reboot = true

[event_user_login]
super = default
type = user login
action_type = login
active = false
action_message = Starting to process user login actions.
action_message[de] = Beginne mit der Verarbeitung der Benutzer-Anmeldungs-Aktionen.
action_message[fr] = Traitement des actions à la connexion de l'utilisateur.
block_login = false
process_shutdown_requests = false
get_config_from_service = false
update_config_file = false
write_log_to_service = false
update_action_processor = true
event_notifier_command = %opsiclientd_notifier.command% -s notifier\\userlogin.ini
event_notifier_desktop = default
action_processor_command = %action_processor.command% /sessionid %service_session% /loginscripts /silent
action_processor_desktop = default
action_processor_timeout = 300

[event_on_shutdown]
super = default
type = custom
active = false
max_repetitions = 0

[event_on_shutdown{installation_pending}]
active = false

[event_silent_install]
super = default
type = custom
event_notifier_command =
process_shutdown_requests = false
action_processor_productIds = swaudit,hwaudit
action_processor_command = %action_processor.command% /productlist %action_processor_productIds% /silent
action_processor_desktop = winlogon
action_processor_timeout = 300

[event_timer_silentinstall]
super = silent_install
type = timer
active = false
interval = 21600

[precondition_user_logged_in]
user_logged_in = true

[precondition_cache_ready]
config_cached = true
products_cached = true

[precondition_cache_ready_user_logged_in]
user_logged_in = true
config_cached = true
products_cached = true

[precondition_installation_pending]
installation_pending = true

Configuration via web service (Host Parameter)

The opsiclientd configuration can be changed by the 'host parameter' tab at the opsi management interface.

The entries in the 'host parameter' have to be according to the following patterns:

opsiclientd.<name of the section>.<name of the key>

Example:
opsiclientd.event_gui_startup.action_warning_time = 20
set in the configuration file opsiclientd.conf in the section [event_gui_startup] the value of action_warning_time to the value 20.

The following figure shows how to change the serverwide general configure via 'opsi-configed'

Setting the server default opsiclientd configuration
Figure 7. Setting the server default opsiclientd configuration

Using the context menu you may choose 'add property' to set a new key/value pair.

To delete a server default, please use the 'opsi-admin' tool:

Example:

opsi-admin -d method config_delete "opsiclientd.event_gui_startup.action_warning_time"

It is also possible to manipulate these entries client specific via 'opsi-configed'.

To delete a client specific entry, please use the 'opsi-admin' tool:

Example:

@opsi-admin> method configState_delete "opsiclientd.event_gui_startup.action_warning_time" "myclient.uib.local"
client specific opsiclientd configuration via opsi-configed
Figure 8. client specific opsiclientd configuration via opsi-configed

Logging

The 'opsiclientd' logs to:
C:\opsi.org\log\opsiclientd.log.

All log information will be transferred to the 'opsi-configserver' via web service. At the server you find these log infos at /var/log/opsi/clientconnect/<ip-or-name-of-the-client>.log. They are presented in the opsi configed at the tab 'logfiles / client connect'.

Every line at the log has the pattern:
[<log level>] [<time stamp>] [message source] message.

There are the following log levels:

# Set the log (verbosity) level
# (0 <= log level <= 9)
# 0: nothing, 1: essential, 2: critical, 3: errors, 4: warnings, 5: notices
# 6: infos, 7: debug messages, 8: more debug messages, 9: passwords

Example:

(...)
[5] [Mar 22 10:17:46] [ event processing gui_startup  ] Event config 'sync_completed{cache_ready}' added to event generator 'sync_completed'   (Events.pyo|1107)
[5] [Mar 22 10:17:46] [ event processing gui_startup  ] Event config 'gui_startup' added to event generator 'gui_startup'   (Events.pyo|1107)
[5] [Mar 22 10:17:46] [ event processing gui_startup  ] Event config 'gui_startup{cache_ready}' added to event generator 'gui_startup'   (Events.pyo|1107)
[5] [Mar 22 10:17:46] [ event processing gui_startup  ] Event config 'on_demand' added to event generator 'on_demand'   (Events.pyo|1107)
[5] [Mar 22 10:17:46] [ event processing gui_startup  ] Event config 'sync_completed{cache_ready_user_logged_in}' added to event generator 'sync_completed'   (Events.pyo|1107)
[5] [Mar 22 10:17:46] [ event processing gui_startup  ] Event config 'gui_startup{user_logged_in}' added to event generator 'gui_startup'   (Events.pyo|1107)
[5] [Mar 22 10:17:46] [ event processing gui_startup  ] Event config 'sync_completed' added to event generator 'sync_completed'   (Events.pyo|1107)
[5] [Mar 22 10:17:46] [ event processing gui_startup  ] Event config 'software_on_demand' added to event generator 'software_on_demand'   (Events.pyo|1107)
[5] [Mar 22 10:17:46] [ event processing gui_startup  ] Event config 'on_demand{user_logged_in}' added to event generator 'on_demand'   (Events.pyo|1107)
[5] [Mar 22 10:17:46] [ event processing gui_startup  ] Updating config file: 'C:\Program Files (x86)\opsi.org\opsi-client-agent\opsiclientd\opsiclientd.conf'   (Config.pyo|287)
[5] [Mar 22 10:17:46] [ event processing gui_startup  ] No need to write config file 'C:\Program Files (x86)\opsi.org\opsi-client-agent\opsiclientd\opsiclientd.conf', config file is up to date   (Config.pyo|318)
[5] [Mar 22 10:17:46] [ event processing gui_startup  ] No product action requests set   (EventProcessing.pyo|591)
[5] [Mar 22 10:17:49] [ event processing gui_startup  ] Writing log to service   (EventProcessing.pyo|247)
[6] [Mar 22 10:17:49] [ opsiclientd                   ] shutdownRequested: 0   (Windows.pyo|340)
[6] [Mar 22 10:17:49] [ opsiclientd                   ] rebootRequested: 0   (Windows.pyo|326)
[5] [Mar 22 10:17:49] [ opsiclientd                   ] Block login now set to 'False'   (Opsiclientd.pyo|111)
[6] [Mar 22 10:17:49] [ opsiclientd                   ] Terminating block login notifier app (pid 1620)   (Opsiclientd.pyo|148)
[6] [Mar 22 10:17:49] [ event processing gui_startup  ] Stopping notification server   (EventProcessing.pyo|225)
[6] [Mar 22 10:17:51] [ control server                ] client connection lost   (Message.pyo|464)
[6] [Mar 22 10:17:52] [ event processing gui_startup  ] Notification server stopped   (Message.pyo|651)
[5] [Mar 22 10:17:52] [ event processing gui_startup  ] ============= EventProcessingThread for event 'gui_startup' ended =============   (EventProcessing.pyo|1172)
[5] [Mar 22 10:17:52] [ opsiclientd                   ] Done processing event '<ocdlib.Events.GUIStartupEvent object at 0x023CE330>'   (Opsiclientd.pyo|405)
[5] [Mar 22 10:19:41] [ opsiclientd                   ] Session 'HSzMB1wtOiBS6vHl7mh3ro5r6s3TanFu' from ip '127.0.0.1', application 'opsi jsonrpc module version 4.0.1' expired after 120 seconds   (Session.pyo|184)
[6] [Mar 22 10:19:41] [ opsiclientd                   ] Session timer <_Timer(Thread-20, started daemon 2636)> canceled   (Session.pyo|120)
[5] [Mar 22 10:19:41] [ opsiclientd                   ] Session 'HSzMB1wtOiBS6vHl7mh3ro5r6s3TanFu' from ip '127.0.0.1', application 'opsi jsonrpc module version 4.0.1' deleted   (Session.pyo|207)
[6] [Mar 22 10:27:55] [ control pipe                  ] Creating pipe \\.\pipe\opsiclientd   (ControlPipe.pyo|253)
[5] [Mar 22 10:27:55] [ event generator wait_for_gui  ] -----> Executing: getBlockLogin()   (JsonRpc.pyo|123)
[5] [Mar 22 10:27:55] [ opsiclientd                   ] rpc getBlockLogin: blockLogin is 'False'   (ControlPipe.pyo|428)
[6] [Mar 22 10:27:55] [ event generator wait_for_gui  ] Got result   (JsonRpc.pyo|131)
'

The 'opsi-Loginblocker' logging to the log file: C:\opsi.org\log\opsi_loginblocker.log.

opsiclientd infopage

According to the fact that there are a lot of components of the 'opsiclientd' which work and log at the same time, the log file of the 'opsiclientd' becomes complex.

In order to make it easier to understand how the different components work together, the 'opsiclientd' has an own 'info page' which visualizes the running tasks on a timeline.
You may view this 'info page' at the browser calling the url:
https://<address-of-the-client>:4441/info.html

Info page of the opsiclientd at push installation with activated product caching
Figure 9. Info page of the opsiclientd after push installation with activated product caching

opsiclientd Bitlocker Suspend Feature

Clients with activated Bitlocker encryption, with manual password entry at boot, prevent the unattended installation of software and patches.

Just like with 'opsi-script', it is now also possible for reboots triggered by events of opsiclientd to suppress the password input when booting.

This feature is inevitably associated with a security issue. During this process, the password is written to the hard disk as plain text and is therefore a potential weak point.

This feature is deactivated by default, in order to activate this option only on selected clients, a standard configuration must be created first:

opsi-admin -d method config_createBool clientconfig.suspend_bitlocker_on_reboot "Suspending Bitlocker at Reboot" false

The default value false corresponds to the value in the supplied opsiclientd.conf.

To set the 'Hostparameter' via 'opsi-admin', the following command has to be executed on the 'opsi-configserver' (in the example for a client with the opsi-host-Id myclient.domain.de):

opsi-admin -d method configState_create clientconfig.suspend_bitlocker_on_reboot myclient.domain.de true
This option can also be activated on clients that have not activated Bitlocker encryption and this option should not interfere with the operation of the opsiclientd.

opsi-client-agent remote control

The 'opsiclientd' has its own web service interface which can be used to transmit commands to the 'opsiclientd'. The possible commands can be divided in the following categories:

  • send Messages (Popup)

  • 'Push' installation (start the event 'on_demand')

  • other maintenance tasks

This can be done on the command line using the tool 'opsi-admin' by calling one of the hostControlSafe_* methods. Calling one of these methods takes the parameter *hostid which:

  • can be ["*"] to send the command to all clients

  • can be the name of a client (e.g. "myclient.uib.local")

  • can be a list of client names according to the pattern ["<client1>", "<client2>"]
    e.g. ["client1.uib.local", "client2.uib.local"]

  • may contain wildcards like *

    e.g. "client.*" oder "\*.uib.*"

If a client isn’t reachable (e.g. powered off) you will receive an error message.

Sending popup messages

Using the 'opsi-configed' you may send messages to the clients. Sending messages (Show popup message)

At the command line you may do this with the tool 'opsi-admin':

opsi-admin -d method hostControlSafe_showPopup message *hostid

Example:

opsi-admin -d method hostControlSafe_showPopup "This is my message" "myclient.uib.local"

'Push' installations: start the event 'on demand'

The 'opsi-server' may send a command to the client that the client should process the configured action requests immediately. This is done by activating the event 'on_demand' at the client.

This is possible using the 'opsi-configed' and is described in chapter: 'Push' installationen: start the event 'on demand'

From the 'opsi-server' the client can be instructed to execute the 'Produktaktionen'.

Executing Events can also be done from the 'opsi-configed'. Fire opsiclientd event (Push Installation)

On the command line you may use 'opsi-admin' to fire an event:

opsi-admin -d method hostControlSafe_fireEvent event *hostIds

Example:

opsi-admin -d method hostControlSafe_fireEvent "on_demand" "myclient.uib.local"

Additional maintenance tasks (shutdown, reboot,…​..)

Using the control server port you may remote control the 'opsiclientd'. In order to do this you have to authenticate yourself at the web service. This could be done either with the local administrator account (with a not empty password) or with the 'opsi-host-Id' (FQDN, client name and DNS Domain name) as user name and the opsi-hostkey as password.

Using the 'opsi-configed' you may choose the menu 'opsiClient' or the context menu in the 'Clients' Tab.

Web service of the opsiclientd
Figure 10. Web service of the opsiclientd

At the command line you also can initiate a client:

shutdown:

opsi-admin -d method hostControlSafe_shutdown *hostIds

reboot:

opsi-admin -d method hostControlSafe_reboot *hostIds

Adapting the opsi-client-agent to your Corporate Identity (CI)

Adapting the 'opsi-client-agent' to your Corporate Identity can be important for the user acceptance when rolling out opsi. By adding your corporate logo to the opsi background image, the users feel more familiar with the opsi installation instead of being puzzled by something unknown.

All graphic components of the opsi-client-agent (notifier, opsi-script) are base on the same graphic libraries and may be customized in the same way.
Colors can be configured in three different ways: as symbolic name (clRed), as hexadecimal value ($FF00FF) and as rgb value ((255,0,0)). There is a helper program set allows you simple to choose your colors and get the correct way to write the colors to the configuration file. The program is opsi color chooser.

As background graphic formats you may use a large number of different formats like: .bmp, .png, jpeg and so on. But all these formats are include a number of subformats. So for example is one png file displayed without any problem while an other, different png-file may not displayed in a correct way.
There may also be a difference between the operating system platforms (e.g between Windows and Linux).
There is a helper program set allows you simply to check if a given bitmap file will be displayed correct or not: opsi bitmap viewer.

Elements to be patched: opsi-script

The files to be configured for opsi-script are to be found in the directory /var/lib/opsi/depot/opsi-client-agent/files/opsi-script/skin:

  • bg.png
    This is the 'opsi-script' background image, where during installation text messages and product logos are shown.

  • skin.ini
    This is the configuration file to specify the position, font and color of text messages during installation.

Elements to be configured: opsiclientd

In the directory /var/lib/opsi/depot/opsi-client-agent/files/opsi-notifier/notifier.d are the files to configure the look of the notifiers. Each notifier has an background image and a configuration file:

  • block_login.bmp
    background image of the login blocker notifier.

  • block_login.ini
    configuration file of the login blocker notifier.

  • event.bmp
    background image of the server connection event notifier.

  • event.ini
    configuration file of the server connection event notifier.

  • action.bmp
    background image of the action notifier (software installation).

  • action.ini
    configuration file of the action notifier.

  • shutdown.bmp
    background image of the shutdown/reboot action notifier.

  • shutdown.ini
    configuration file of the shutdown/reboot action notifier.

  • popup.bmp
    background image of the popup message notifier.

  • popup.ini
    configuration file of the popup message notifier.

  • userlogin.bmp
    background image of the user login event notifier.

  • userlogin.ini
    configuration file of the user login event notifier.

Protect your CI changes from updates: the custom directory

The custom directory can be used to protect your configuration changes during opsi-client-agent updates: (/var/lib/opsi/depot/opsi-client-agent/files/custom). During server updates of opsi-client-agent the whole custom directory will be saved and restored after the update, so that your custom changes will persist.

  • files/custom/install.conf
    Values from this config file affect the behaviour of oca-installation-helper when installing from a depot mount. It overrides the general install.conf in the opsi-client-agent depot directory.

  • files/custom/opsi-script/skin/.
    All the files from this directory will be copied to the clients C:\Program Files (x86)\opsi.org\opsi-client-agent\opsi-script\skin directory during installation of the opsi-client-agent on the client.

  • files/custom/notifier/.
    All the files from this directory will be copied to the clients C:\Program Files (x86)\opsi.org\opsi-client-agent\notifier directory during installation of the opsi-client-agent and overwrite the files from the server side files/opsi-notifier/notifier.d directory.

A subsequent cleanup of the file access rights helps to avoid errors:

opsi-setup --set-rights /var/lib/opsi/depot/opsi-client-agent

Blocking the user login with the opsi-Loginblocker

To prevent a user from logging into the system before the installation is complete, the opsi-Loginblocker can be installed. This will not allow access to the login until the installation process is complete.

Whether the opsi-Loginblocker is installed or activated during the opsi-client-agent installation, can be configured via the 'Product-Property' loginblockerstart.

The 'opsi-Loginblocker' is implemented as a 'credential provider filter'. It blocks all 'credential providers' until the release by the 'opsiclientd' or timeout.

Subsequent installation of the opsi-client-agents

The information about the 'Subsequent installation of the opsi-client-agent' you will find in the 'opsi-getting-started' manual (Chapter 'First Steps').

Manual installation of the opsi-client-agent

The opsi-client-agent can be installed in many different modes:

  • As part of an operating system installation

  • Manually from a (depot) directory (start oca-installation-helper.exe / service_setup.cmd / silent_setup.cmd or oca-installation-helper / service_setup.sh for linux and macos)

  • Via push from the server (opsi-deploy-client-agent)

  • Via the new installer (opsi-client-agent-installer.exe, opsi-linux-client-agent-installer.run, opsi-mac-client-agent-installer.command)

  • Via the new MSI package (opsi-client-agent.msi - only windows)

  • In the opsi service context (opsi-client-agent updates itself)

Except for the upgrade in the opsi service context, the new oca-installation-helper.exe is always used. This essentially fulfils the following purposes:

  • The installation files are copied to a local temp directory if necessary (e.g. call via UNC path).

  • A dialogue window is displayed in which parameters for installation control can be entered.

  • The client is created at the opsi-service, if it does not already exist.

  • opsi-script is started and carries out the actual installation.

The installation is always carried out with a functioning service connection. This means that, regardless of the installation mode, the product properties from the server are always used.

The oca-installation-helper[.exe] supports the following parameters (--help):

usage: oca-installation-helper [-h] [--version] [--log-file LOG_FILE]
                               [--log-level {none,debug,info,warning,error,critical}]
                               [--service-address SERVICE_ADDRESS] [--service-username SERVICE_USERNAME]
                               [--service-password SERVICE_PASSWORD] [--client-id CLIENT_ID]
                               [--non-interactive] [--no-gui] [--gui] [--encode-password PASSWORD]
                               [--depot DEPOT] [--group HOSTGROUP] [--force-recreate-client]
                               [--finalize {noreboot,reboot,shutdown}] [--dns-domain DNS_DOMAIN]
                               [--no-set-mac-address] [--read-conf-files [FILE [FILE ...]]]
                               [--install-condition {always,notinstalled,outdated}]

optional arguments:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  --log-file LOG_FILE
  --log-level {none,debug,info,warning,error,critical}
  --service-address SERVICE_ADDRESS
                        Service address to use.
  --service-username SERVICE_USERNAME
                        Username to use for service connection.
  --service-password SERVICE_PASSWORD
                        Password to use for service connection.
  --client-id CLIENT_ID
                        Client id to use.
  --non-interactive     Do not ask questions.
  --no-gui              Do not use gui.
  --gui                 Use gui.
  --encode-password PASSWORD
                        Encode PASSWORD.
  --depot DEPOT         Assign client to specified depot.
  --group HOSTGROUP     Insert client into specified host group.
  --force-recreate-client
                        Always call host_createOpsiClient, even if it exists.
  --finalize {noreboot,reboot,shutdown}
                        Action to perform after successfull installation.
  --dns-domain DNS_DOMAIN
                        DNS domain for assembling client id (ignored if client id is given).
  --no-set-mac-address  Avoid retrieving and setting mac-address on client creation.
  --read-conf-files [FILE [FILE ...]]
                        config files to scan for informations, if empty no files are read (default:
                        install.conf config.ini opsiclientd.conf)
  --install-condition {always,notinstalled,outdated}
                        Under which condition should the client-agent be installed.

This parameters can be used to automate the installation and run it unattend:

oca-installation-helper.exe --service-address https://10.1.2.3:4447 --service-username adminuser --service-password secret --non-interactive

The opsi-client-agent-installer[.exe] also takes the same parameters. The installer can be downloaded from an opsi 4.2 server without authentication via the following address (similar for opsi-linux-client-agent-installer.run and opsi-mac-client-agent-installer.command):

https://<opsi-server>:4447/public/opsi-client-agent/opsi-client-agent-installer.exe.

This is usually easier than accessing the depot share when installing manually.

When using the MSI package, the parameters can be passed via the property "INSTALL_PARAMS":

msiexec /i opsi-client-agent.msi INSTALL_PARAMS="--non-interactive --service-address=https://opsiserver.domain.tld:4447 --service-username=msi --service-password=secret"

To distribute the MSI via group policy, the INSTALL_PARAMS should be modified via an MST. The MST can be created, for example, via the software Orca.

The "service-password" can also be used encrypted:

oca-installation-helper.exe --service-password {crypt}w5TDjcOQw5PDjsOr

The encryption comes with the following command:

oca-installation-helper.exe --encode-password <plaintext-password>

At start-up, the oca-installation-helper.exe additionally evaluates the following configuration files in descending priority to fill the parameters:

  • .\files\custom\install.conf

  • .\install.conf

  • .\files\opsi\cfg\config.ini (do not use this file, it’s depracted and will be removed soon)

  • %PROGRAMFILES%\opsi.org\opsi-client-agent\opsiclientd\opsiclientd.conf (or /etc/opsi-client-agent/opsiclientd.conf)

Command line parameters always have priority.

If no opsi-service-url is specified, an attempt is made to determine it via Zeroconf.

The parameters --depot and --group can be used to assign the client to an opsi-depot and a host group (only works with admin credentials).

The parameter --finalize can be used to decide the action terminating the installation. By default this is "noreboot" meaning the opsiclientd is started without performing an Event.

Here is an example of an install.conf for automating the installation:

client_id =
service_address = opsiserver.domain.tld
service_username = adminuser
service_password = {crypt}w5TDjcOQw5PDjsOr
dns_domain = subdomain.domain.tld
interactive = false

By default, the oca-installation-helper[.exe] always creates a log file (oca-installation-helper.log) in the user’s temp directory.

The files service_setup.cmd / silent_setup.cmd / service_setup.sh are only used for backward compatibility.

The Systray Program of the opsi-client-agent

The systray program of the 'opsi-client-agent' focuses on the following targets:

  • Notifying the user in regular (and configurable) Intervals on pending Installations. (Optional)

  • Notifying the user on pending Installations on demand by using the context menu.

  • Possibility for the user to start the installations.

Message window of the opsi-client-systray program
Figure 11. Message window of the opsi-client-systray program
Context menu (right mouse click) of the opsi-client-systray program
Figure 12. Context menu (right mouse click) of the opsi-systray program

Controlling the opsi systray program via the 'opsi-client-agent' product properties:

  • systray_install
    (true / false) Install the opsi systray program ?
    Default = false

  • systray_check_interval
    Interval in minutes to check for pending action requests.
    Default=180 (Small values here give heavy load to the server)
    The value 0 means: no checks at all..

  • systray_request_notify_format
    Format of action request notification.
    Possible Values:
    "productid : request", "productname : request", "productname productversion : request"
    default: "productname : request"

Logs of the opsi systray program:

The program logs to %Appdata%\opsi.org\log. That is the opsi.org\log directory in the Appdata directory of the loggedin user.
For Example:
C:\Users\<username>\AppData\Roaming\opsi.org\log\

See also Chapter 'opsi Software On Demand (Kiosk-Mode)': opsi Software On Demand