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

Start / Log / Exitcodes / Testsyntax

Command Line Options

Since version 4.11.3, the opsi-script program contains at Windows a manifest with the statement:
<requestedExecutionLevel level="highestAvailable" />. This means that if opsi-script is called on an NT6 OS by an Administrator, then it will run as an 'elevated' process. If opsi-script is called with normal user privileges, then it will run with the privileges of this user.

If you start opsi-script without any parameter, it will start in the interactive mode.

opsi-script can be started with different sets of parameters depending on context and purpose of use.

Note

At Linux or macOS the parameter char is not "/" as here described for Windows but "-". So instead of using opsi-script /help as we do on Windows, we use at Linux / macOS opsi-script -help.

Generic Options:

  • /? or /h[elp]
    Show help

  • /silent
    Run opsi-script without GUI

Execute one (or more) scripts:
opsi-script <scriptfile>[;<scriptfile>]* [<logfile>]
where:
<scriptfile> = Name of the script file (incl. path).
<logfile> = Name of the logfile (incl. path). Paths to logfiles see also: Logfile and Paths

  • /parameter <parameterstring>
    A string that can be passed to the executed script and can be retrevaled by the command Paramstr.
    Hereby is <parameterstring> a string without whitespaces.

  • /logfile <logfile>
    Define the logfile:
    Hereby is:
    <logfile> = Name of the logfile (incl. path). Paths to logfiles see also: Logfile and Paths

  • /lang <lang>
    Define the localization:
    Hereby is:
    <lang> = The two char language abbreviation (de,en,fr,es,…​)

  • /batch
    Execute the given script with the batch GUI. The batch GUI has no possibility for user interaction. In combination with the option /silent there will be no GUI at all. If you call opsi-script without the option /batch the interactive GUI ist started, which is designed for development end testing purposes.

  • /testsyntax (since 4.12.7.)
    Execute the given script in 'testsyntax' mode. Normally used in combination with the parameter /batch.
    see also: Start / Log / Exitcodes / Testsyntax

  • /productid <productId>
    For the use together with /servicebatch ; see below.

  • /servicebatch
    Execute the given script with the batch GUI and with a connection to the opsi web service. Thereby the given script will be executed as it would be if the opsi product given by the option /productid had the action request 'setup'.
    The script file has to be the first option.
    The option /opsiservice and its sub options has to be given.
    The option /productid has to be given. This one is used for the communication with the opsi web service to run the given script as it would be the 'setup-script' of the opsi product given with this option.

  • /logproductid <productId>
    While creating the logfile the given <productId> should be used to note it as source of the logfile.

  • /normalwindow
    Switches off the maximize if of the GUI in the not interactive mode.

  • /usercontext < [domain\]username >
    If the given user is loged in then opsi-script will try to resolve the constants like %CurrentAppdataDir%, %CurrentStartmenuDir%, %CurrentDesktopDir%, %CurrentStartupDir%, %CurrentProgramsDir%, %CurrentSendToDir%, %CurrentProfileDir% from the context of the given user.
    Mostly used together with the’User Profile Management' opsi extension.

  • /opsiservice <opsiserviceurl>
    /clientid <clientname>
    /username <username>
    /password <password>
    [/sessionid <sessionid>]
    [/credentialfile <credentialfile>]
    Give the connection data to connect to the opsi web service:
    Hereby you have to give either /clientid and /username and /password and also optional the /sessionid
    or you have to give this data via a /credentialfile.

Declare what should be done in the context of the connected /opsiservice

  • Default (none of the following parameters):
    Process the action requests as they stored for this client on the opsi-server.

  • /allloginscripts or /loginscripts
    Process the login scripts of the opsi products. Using /allloginscripts all login scripts that are known to the opsi-Server will be processed, no matter iftheses products are known to the client or not. Using /loginscripts only these login scripts will be precessed that belong to products that are installed or were installed and then removed (technical: there is an existing productOnClient object).

  • /productlist <productid>[,<productid>]*
    Process the given /productlist in a way as it would normally done if there are the action request 'setup' is stored at the opsi-server.
    Usally used by the event_silent_install.

  • /processproducts <productid>[,<productid>]*
    Process the action requests as they stored for this client on the opsi-Server but limited to the list of products given by /processproducts.

Logfile and Paths

The default logfile name is opsi-script.log. You may find (by default) up to 8 backup copys of old logfiles: from opsi-script_0.log until opsi-script_8.log.
The default number of backups may be overwritten by using the config: Additional Configurations

The logfile encoding is UTF-8.

By default logfiles are written at Windows into the directory c:\opsi.org\log which opsi-script tries to create. If opsi-script has no access to this directory it uses the user-TEMP directory.

At Linux: If running as root (default): /var/log/opsi-script If running as any other user: /tmp

The logfile name and location will be overwritten via the specific command line option.

In the case, that opsi-script executes a script in /batch mode and with a specified (and working) usercontext, the default logging path is the opsi/tmp in the appdata directory of the user. This will be overwritten by an explicit given log path.

More possibilities to configure the logging:
see also: opsi-script-manual:configuration-options.adoc#opsi-script-configs_writeProductLogFile
see also: opsi-script-manual:configuration-options.adoc#opsi-script-configs_default_loglevel
see also: opsi-script-manual:configuration-options.adoc#opsi-script-configs_force_min_loglevel
see also: Additional Configurations
see also: Additional Configurations

Beside the normal logfile there is also a logfile named opsi-script.history. This logfile contains one line for every run of a product script since the first run. These lines have the pattern:
<timestamp> handled: <productid> Version: <version> Request: <request> Result: <result>
Example:
2022-01-18 00:09 handled : gimp Version: 2.10.30-1 Request: setup Result: success

Exit Codes

opsi-script has (since 4.12.7.0) the following exit codes:

  • 0 :
    The opsi-script program was terminated without any internal errors and all executed scripts ran successfully.

  • 1 :
    The opsi-script program was terminated without any internal errors, but one (or more) executed scripts did not run successfully (failed).

  • >1 :
    An internal error has occurred in the opsi-script program (this should not happen). Script execution probably failed.

Checking the Script Syntax

Available since 4.12.7.0

If opsi-script is started in testsyntax mode, scripts will not be executed but scanned for syntax errors.
Such a testsyntax run has the following characteristic features:

  • While running in testsyntax mode every line of the script will be processed. So for example in case of an if-else-endif statement both branches will be analyzed.

  • Any statement that will modify the system opsi-script is running on, will not be executed.

  • If a syntax error is found, this will be logged. The run will not stop at the first syntax error but run to the end. So you will find every syntax error in the log.

  • Every statement that normally stops the script execution (like isFatalError) will be ignored.

  • In the header of the logfile, you will find the warning:
    Running in TestSyntax mode !!.

  • If a syntax error is found, the script will be marked as failed. This means in detail:

    • The logfile will end up with script finished: failed.

    • The opsi-script process will return the exit code 1.

    • If opsi-script is started in the context of the opsi web-service (so for example started by the management interface via on_demand), the opsi product will be marked as: State: unknown and Report either ok: testsyntax or failed: testsyntax.

Testsyntax Result in the opsi-configed: 1. line: failed
After you checked a script with testsyntax, you may find additional runtime error messages in the logfile. You should ignore these runtime errors. In many cases these runtime errors are side effects of the testsyntax run. The reason is, that while testsyntax many variables have empty (or other unexpected) values.

In order to run opsi-script in testsyntax mode, you have the following possibilities:

Screenshot: opsi-script in interactive mode
Figure 1. opsi-script in interactive mode

  • Interactive :
    If opsi-script is started in the interactive mode, use the button Test Syntax (instead of Start) to run the selected script.

  • In the context of the opsi web-service :
    By using the config ('Hostparameter') opsi-script.global.testsyntax = true, opsi-script will be forced to run all scripts in the 'testsyntax' mode.
    ATTENTION: Switch this config only for selected computers to true. Do not forget to switch it back to false after you have done your syntax check!
    see also: Additional Configurations

  • Command line parameter :
    If you call opsi-script on the command line, use the additional parameter /testsyntax in order to run the given script in testsyntax mode.
    For details see also: Command Line Options