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

Additional Configurations

Central Logging of Error Messages

If the opsi-script running in opsi web service mode, it sends the logfile via opsi web service to the opsi server.

Central configuration via opsi Configs (Host Parameter)

Using opsi Configs (Host-Parameter) you may now change the behavior of opsi-script (for example some logging features):

  • opsi-script.global.debug_prog : boolean
    If false log messages that are only relevant for debugging the opsi-script program it self are not written excepting Warnings and Errors.
    Default: false
    This will keep the logfiles smaller because you will find only messages that are relevant for understanding what your script is doing.
    The adjustment of all log messages to this new way is in progress and will be take a while since all (about 1700) log calls inside the code are reviewed.

  • opsi-script.global.debug_lib : boolean
    If false log messages from defined functions that are imported from external library files will be suppressed excepting Warnings and Errors.
    Default: false

  • opsi-script.global.default_loglevel : intstr
    Sets (overrides) the default log level that is imlemented inside the opsi-script code. This config has no effect on scripts where the loglevel is explicit set by a setLogLevel statement.
    Default: '6'
    see also SetLogLevel
    see also [opsi-script-configs_force_min_loglevel]

  • opsi-script.global.force_min_loglevel : intstr
    Forces a minimal log level.
    This can be used while debugging or development to set temporary and for selected clients a higher log level wthout changing the script. Default: '0'
    see also SetLogLevel
    see also [opsi-script-configs_default_loglevel]

  • opsi-script.global.ScriptErrorMessages : boolean
    This config overwrites the opsi-script internal default value for ScriptErrorMessages if opsi-script is running in the context of the opsi web service. If the value is true, syntactical errors trigger a pop up window with some informations on the error. This is in productive environments no good idea. Therefore the default value for this config is 'false'.
    Inside a script the statement ScriptErrorMessages may be used to set this different from the defaults.
    Default: false
    see also : ScriptErrorMessages

  • opsi-script.global.AutoActivityDisplay : boolean
    If true shows a marquee (endless) progressbar while external processes (winbatch/ShellScript sections) are running.
    Default: true
    see also : AutoActivityDisplay

  • opsi-script.global.SupressSystemEncodingWarning : boolean
    If true the warning: Encoding=system makes the opsiscript not portable between different OS will be supressed.
    Default: false
    see also: encoding

  • opsi-script.global.ReverseProductOrderByUninstall : boolean
    If true the product list is reordered so that uninstall actions will be conducted first and in reverse order as the prodcuts were installed
    Default: false

[opsi-script-configs_log_rotation_count]

  • opsi-script.global.log_rotation_count : string (number) // since 4.12.4.29
    Defines the number of opsi-script.log backups that will be stored in the log directory on the client. (opsi-script_0.log, opsi-script_1.log, …​)
    Default = 8 ; Max = 999

  • opsi-script.global.writeProductLogFile : boolean // since 4.12.4.35
    If true logs for every single opsi product will be created. You will find these log in the sub directory lastprodlogs of the opsi-script log directory (E.g. c:\opsi.org\log\lastprodlogs). The name of these logfiles is <productId>.log. There is always only the last logfor every product. If the product script contains reboots in (not after) the script, the log contains only the part after the last reboot.
    Default: false

  • opsi-script.global.testsyntax : boolean // since 4.12.7.0
    If true, all scripts will be executed in the testsyntax mode.
    see also: Start / Log / Exitcodes / Testsyntax
    Default: false

Skinnable opsi-script [W/L/M]

Since version 3.6 the opsi-script GUI can be customized. The elements for customizing are to be found in the winstskin subdirectory of the opsi-script directory. The configuration file for customization is skin.ini.

Since version 4.12.4.15 the opsi-script searches the skin directory in the following order (directory with the first skin.ini to be found wins):

Windows:

%OpsiScriptDir% = C:\Program Files (X86)\opsi.org\opsi-client-agent\opsi-script

  1. %OpsiScriptDir%\..\custom\customskin

  2. %OpsiScriptDir%\skin

  3. %OpsiScriptDir%\winstskin(for backward compatibility)

Linux:

%OpsiScriptDir% = /opt/opsi-script

  1. '/usr/share/opsi-script/skin'

  2. '/usr/share/opsi-script/customskin' (for backward compatibility)

  3. %OpsiScriptDir%/skin

see also: opsi-script-linux-path

macOS:

%OpsiScriptDir% = /Applications/opsi-script/Contents/macOS

  1. '/usr/share/opsi-script/skin'

  2. %OpsiScriptDir%/../Resources/skin

see also: opsi-script-macos-path

With the Command SetSkinDirectory the SkinDirectory to be used can be defined in the script. If the path specified is empty or not valid, the default path will be used.

Example:

SetSkinDirectory "%ScriptPath%\testskin"
sleepseconds 1
SetSkinDirectory ""

Adaptation to Corporate Identity

All graphical components of opsi-script are based on the display components applied for displaying graphics and thus adapted in the same way. Colors can be specified in three different ways: As a symbolic name (clRed), as a hexadecimal value ($FF00FF) or as rgb value list 255,0,0. A utility for selecting colors and their corresponding notation can be found in the following opsi color chooser.

As background graphic formats a wide array of different bitmap formats such as .bmp, .png, jpeg etc. can be utilized. All these formats are again container formats, i.e. PNG is not necessarily equal to PNG. It is possible that one is displayable and the other is not. A utility to quickly check if a given bitmap graphic will be displayed correctly can be also found at following opsi bitmap viewer.

The files that you can customize in opsi-script can be found in the directory /var/lib/opsi/depot/opsi-client-agent/files/opsi-script/skin:

bg.png +

The background graphic of 'opsi-script' in which the text messages as well as the product logos are displayed at runtime.

skin.ini +

The configuration file in which is specified in which font and color text messages are displayed.

Since opsi-script version 4.12.4.35 it’s possible to choose between two themes. If Theme = default, or nothing is specified the standard appearance of opsi-script is kept as previously known, still you have the following detailed setting possibilities over the skin.ini (here occupied with the delivered default values):

[Form]
Theme = default #this line can also be omitted here
Color = $00FFB359

[LabelVersion]
Left = 20
Top = 367
Width = 85
Height = 16
FontName = Arial
FontSize = 7
FontColor = $00E2A973
FontBold = false
FontItalic = false
FontUnderline = false

[LabelProduct]
Left = 260
Top = 100
Width = 315
Height = 100
FontName = Arial
FontSize = 32
FontColor = $00E7E7E7
FontBold = false
FontItalic = false
FontUnderline = false

[LabelInfo]
Alignment=Center
Left = 60
Top = 260
Width = 520
Height = 24
FontName = Arial
FontSize = 11
FontColor = $00E7E7E7
FontBold = true
FontItalic = false
FontUnderline = false

[LabelDetail]
Left = 60
Top = 285
Width = 520
Height = 20
FontName = Arial
FontSize = 8
FontColor = $00E7E7E7
FontBold = false
FontItalic = false
FontUnderline = false

[LabelCommand]
Left = 60
Top = 310
Width = 520
Height = 20
FontName = Arial
FontSize = 8
FontColor = $00E7E7E7
FontBold = false
FontItalic = false
FontUnderline = false

[LabelProgress]
Left = 60
Top = 335
Width = 520
Height = 40
FontName = Arial
FontSize = 8
FontColor = $00E7E7E7
FontBold = false
FontItalic = false
FontUnderline = false

[ActivityBar]
Left = 60
Top = 350
Width = 420
Height = 10
BarColor = clBlue

[ImageBackground]
File = bg.png

[ImageProduct]
File = product.png
Left = 40
Top = 65
Width = 160
Height = 160

[Image1Over]
File =
Left = 0
Top = 0
Width = 0
Height = 0

[Image2Over]
File =
Left = 0
Top = 0
Width = 0
Height = 0

[ProgressBar]
Left = 275
Top = 160
Width = 280
Height = 20
BarColor = $00E7E7E7
StartColor = $00E7E7E7
FinalColor = $00E7E7E7
ShapeColor = $00E7E7E7
Shaped = true
ShowFullBlock = false
RoundCorner = true
BlockSize = 10
SpaceSize = 3
Cylinder = true
Glass = true

Set Theme = WindowsSimple to only display a simple interface when installing opsi products. This is similar to the one used by Windows when installing OS updates. The following settings possibilities are available (here occupied with the delivered default values):

[Form]
Theme = WindowsSimple #This line is necessary here and may not be changed
Color = clHotLight

[LabelInfo]
Caption = Software is being installed. Please wait.

Protecting your changes from updates: The custom directory

In case you want to avoid changes being made to the files mentioned above when you install a new version of the opsi-Client agent, you can do this using the custom directory /var/lib/opsi/depot/opsi-client-agent/files/custom (previously /var/lib/opsi/depot/opsi-client-agent/files/opsi/custom). The complete custom directory is saved and restored when a new version of the opsi-Client agent is installed, so that the changes made here are not lost.

  • custom/opsi-script/skin/*.*
    The contents are copied to C:\Program Files (x86)\opsi.org\opsi-client-agent\opsi-script\skin when installing the opsi-client-agent on the client.

opsi-script encoding [W/L/M]

Some technical notes about the wording:

  • ASCII, plain ASCII
    ASCII stands for: American Standard Code for Information Interchange
    'plain ascii': 7 Bit / per char for 128 different chars. This will be found as base of the following.

  • ANSI, Codepages
    Using 8 Bit (Byte) / per char for 255 different chars. Lower 128 chars = ASCII, Upper 128 Chars according to selected 'Code page'. Well known 'code pages':
    Windows-1252 = CP1252 = ISO 8851-1 = Western Europe code page.
    The first 256 Chars of CP1252 are also part of Unicode.
    'ANSI' stands for American National Standards Institute:
    https://stackoverflow.com/questions/701882/what-is-ansi-format :
    'ANSI encoding is a slightly generic term used to refer to the standard code page on a system, ( …​ )The name "ANSI" is a misnomer, since it does not correspond to any actual ANSI standard, but the name has stuck.'
    So what is an an ANSI-String ?
    https://wiki.freepascal.org/Character_and_string_types#AnsiChar says:
    'A variable of type AnsiChar, also referred to as char, is exactly 1 byte in size, and contains one "ANSI" (local code page) character.'
    The problems with using code pages are:

    • You have to use different encoding in different places of the world.

    • Maximum 255 Chars can be coded, but some languages have a lot more characters.

  • Unicode, UTF-8
    'Unicode' is (like 'ANSI') a encoding family (and not a encoding). The most important difference to using code pages is, that here we use to encode one char (possibly) more than one byte (exactly: up to 4 bytes).
    The most important members of the Unicode family are:

    • UTF-16-LE (also some times called 'Windows Unicode'):
      Uses a minimum length of 2 Bytes per char up to 4 Bytes. The 'LE' stands for 'Little Endian' and tell us that the most significant byte of a char is the last one. (char 'n' : LE='6E 00', BE='00 6E')

    • UTF-8:
      Uses for the chars out of 'plain ASCII' one byte but for every thing else 2 up to 4 bytes.
      So in fact: a file that uses only plain ASCII is the same binary wether you save it in cp1252 or utf8.

    • BOM
      A file with 'Unicode' encoding may contain in the first 4 Bytes the information about the used (unicode-)encoding. This is the 'BOM' ('Byte Order Mark'). If there is a 'BOM', opsi-script will detect and use it.

The default encoding for a script is the encoding of the running operating system. So for example one script will be interpreted on a Greek windows system as encoded with cp1253 on a German windows system as cp1252 and under Linux as UTF-8.

We strongly recommend to create all your opsiscript files in UTF-8 encoding and add the line encoding=utf8 to the file.
This makes your files portabel.
See also below.

  • encoding=<encoding>
    Since Version 4.11.4.1 it is possible to define the encoding in the script. This may be done in the main script and in the sub scripts, includes and libraries as well. You have to give the command:
    encoding=<encoding>
    This command can be at any position in the code (Even before [actions]).
    If the command encoding= is missing, than the expected encoding is the system encoding of the running operating system. At Linux and macOS this would be UTF-8. At Windows the system encoding a cp* and depends on the localization. In Western Europe for example z.B. cp1252.
    If the input file contains umlauts (is not pure 'plain ASCII') and there is no line: encoding=utf8, then you will get a warning:
    'Encoding=system makes the opsiscript not portable between different OS'.
    This Warning may be suppressed by the config (Host Parameter):
    opsi-script.global.supresssystemencodingwarning = true.
    siehe auch opsi-script.global.ScriptErrorMessages

    If the input file contains umlauts (is not pure 'plain ASCII') and there is a discrepancy between the detected encoding (c.f. by a BOM) and the implicit encoding 'system' or the given encoding by encoding=, then you will get the following warning:
    'Warning: Given encodingString <> is different from the expected encoding <>'

    Using the command: encoding=<encoding>
    the <encoding> may be one of the following values:

Table 1. Encodings
encoding allowed alias Remark

system

use the encoding of the running OS

auto

try to guess the encoding

UTF-8

utf8

UTF-8BOM

utf8bom

Ansi

ansi

8 Bit encoding with Codepage

CP1250

cp1250

Central and East European Latin

CP1251

cp1251

Cyrillic

CP1252

cp1252

West European Latin

CP1253

cp1253

Greek

CP1254

cp1254

Turkish

CP1255

cp1255

Hebrew

CP1256

cp1256

Arabic

CP1257

cp1257

Baltic

CP1258

cp1258

Vietnamese

CP437

cp437

Original IBM PC hardware code page

CP850

cp850

"Multilingual (Latin-1)" (Western European languages)

CP852

cp852

"Slavic (Latin-2)" (Central and Eastern European languages)

CP866

cp866

Cyrillic

CP874

cp874

Thai

CP932

cp932

Japanese (DBCS)

CP936

cp936

GBK Supports Simplified Chinese (DBCS)

CP949

cp949

Supports Korean (DBCS)

CP950

cp950

Supports Traditional Chinese (DBCS)

ISO-8859-1

iso8859-1

Latin-1

ISO-8859-2

iso8859-2

Latin-2

KOI-8

koi8

Kyrillisches Alphabet

UCS-2LE

ucs2le

(UTF-16-LE, Windows Unicode Standard)

UCS-2BE

ucs2be

(UTF-16-BE)

see also : reencodestr
see also : reencodestrlist
see also : strLoadTextFileWithEncoding
see also : loadUnicodeTextFile
see also : loadTextFileWithEncoding

Sources see:
https://en.wikipedia.org/wiki/Code_page

http://msdn.microsoft.com/en-us/library/windows/desktop/dd317752%28v=vs.85%29.aspx

http://msdn.microsoft.com/en-us/library/cc195054.aspx

https://en.wikipedia.org/wiki/ANSI_character_set

https://en.wikipedia.org/wiki/UTF-8