The Copyright of this manual is held by uib gmbh in Mainz, Germany.

This manual is published under the creative commons license
'Attribution - ShareAlike' (by-sa).

CC by sa

A description of the license can be found here:
https://creativecommons.org/licenses/by-sa/3.0/

The legally binding text of the license can be found here:
https://creativecommons.org/licenses/by-sa/3.0/legalcode

Most parts of the opsi software is open source.
Not open source are the parts of the source code which contain new extensions, that are still under cofunding, which have not been paid off yet. See also: opsi cofunding projects

All of the open source code is published under the AGPLv3.

agplv3

The legally binding text of the AGPLv3 license can be found here: http://www.gnu.org/licenses/agpl-3.0-standalone.html

Information about the AGPL: http://www.gnu.org/licenses/agpl-3.0.en.html

For licenses to use opsi in the context of closed source software, please contact uib gmbh.

The names 'opsi', 'opsi.org', 'open pc server integration' and the opsi logo are registered trademarks of uib gmbh.

2. Introduction macOS clients in opsi

This manual describes the operation of macOS clients in opsi.

It’s assumed that the installation and startup of an opsi-server has already been performed.

Essential topics of this manual:

  1. Adding and integrating macOS computers in opsi (Installation of the opsi-mac-client-agent)

  2. Deployment of opsi standard software for macOS on the opsi-server .

  3. Installation of standard software on macOS clients

  4. opsi standard software for macOS under opsi

  5. Packaging of own software

  6. Creation of opsi packages

  7. Notes about macOS clients

    1. Special commands for macOS

    2. Directories you may use

    3. The pseudo user opsisetupadmin

2.1. Conventions of this document

Commands are highlighted separately:

this is a command

As part of the installation and configuration process, you can copy and execute the commands from these fields in order by copy & paste from this document.

Commands or file names will be highlighted as: opsi-set-rights oder /Applications/opsi-script.

This is an opsi-script code:

Message "Installing "+ $ProductId$ +" ..."

Chapters containing the name of a particular platform are specific to that platform. The supported platforms are:

  • Windows

  • Linux

  • macOS

3. Requirements for macOS Clients

In the following the requirements for the management of macOS clients under opsi are described.

The opsi-mac-client-agent is a opsi extension.
This means that you need an unlock file to use it. You get this unlock file when you buy the extension. For evaluation purposes we also provide a time limited unlock file for free ( → mail to info@uib.de).
Further details can be found in
https://download.uib.de/opsi4.2/documentation/html/en/opsi-manual-v4.2/opsi-manual-v4.2.html#opsi-manual-extensions

Technical requirements is an opsi-server with opsi 4.1. or higher.

Supported macOS versions:

3.1. Supported as opsi-client: MacOS

As of 16.02.2022

Table 1. Supported MacOS as Client in opsi 4.2 and 4.1

Distribution

client-agent

MacOS 10.13 HighSierra

discontinued

MacOS 10.14 Mojave

discontinued

MacOS 10.15 Catalina

supported

MacOS 11 BigSur

supported

MacOS 12 Monterey

supported

supported: Supported unsupported: Unsupported develop: Under Development discontinued: Discontinued

When using the arm64 architecture (Apple Silicon, M1), it’s currently necessary to install the opsi-client-agent of the 'Dynamic Binary Translators' called rosetta2. You can install this with:
softwareupdate --install-rosetta --agree-to-license You can verify the successful installation with:
pkgutil --pkgs | grep Rosetta
com.apple.pkg.RosettaUpdateAuto.

Native support for the arm64 architecture (Apple silicon) is planned. The necessary reference devices have been ordered for this purpose. To disclose when the deployment for this platform will take place cannot be made at this time (April 2022).

4. Installing the minimal macOS opsi products.

For the distribution of software with opsi ready products are available for installation. These contain among other things the agent ('opsi-client-agent'), which must be installed for the management on clients.

There is an automated and a manual way to perform this. The automated way is recommended.

4.1. opsi standard software for macOS under opsi.

The following products are provided by opsi for macos as standard:

  • opsi-mac-client-agent

  • swaudit

  • hwaudit

  • m-homebrew (also check: the opsi product m-homebrew)

  • m-system-update

  • opsi-configed

  • opsi-logviewer

  • opsi-auto-update

  • m-javavm

  • opsi-setup-detector

  • windomain

4.2. Automatic installation of the minimal macOS opsi products.

For the automatic installation of the opsi products there is the tool opsi-package-updater, which is configured in /etc/opsi/opsi-package-updater.conf or /etc/opsi/package-updater.repos.d/. It also automatically fetches the current packages from the opsi repository and installs them on the server.

The configuration of the opsi repositories for macOS clients can be found in the directory /etc/opsi/package-updater.repos.d/ in the files uib-mac-testing.repo and uib-mac.repo.

Activate the desired repos by setting the entry active = true in the choosen *.repo file.

Listing 1. /etc/opsi/package-updater.repos.d/uib-mac-testing.repo
; This repository provides testing of opsi products to manage MacOS
; clients with opsi.

[repository_uib_macos_testing]
description = opsi macos packages in testing
active = true
baseUrl = http://download.uib.de
dirs = opsi4.2/testing/packages/macos/localboot/
autoInstall = false
autoUpdate = true
autoSetup = false
; Set Proxy handler like: http://10.10.10.1:8080
proxy =
Listing 2. /etc/opsi/package-updater.repos.d/uib-mac.repo
; This repository provides table opsi roducts for managing MacOS
; clients with opsi.

[repository_uib_macos_stable]
description = opsi macos packages in stable
active = true
baseUrl = http://download.uib.de
dirs = opsi4.2/stable/packages/macos/localboot/
autoInstall = false
autoUpdate = true
autoSetup = false
; Set Proxy handler like: http://10.10.10.1:8080
proxy =

Install the packages on the server by running the command as root:

opsi-package-updater -v --repo uib_macos_stable install

or

opsi-package-updater -v --repo uib_macos_testing install

After a successful installation you have to reload all data on the opsi-configed to make the new products become visible there.

If the connection has to be routed through a proxy to access the Internet, this must be entered as the value for proxy in the .repo configuration files under /etc/opsi/package-updater.repos.d/. As of version 4.1.1.33 of opsi-utils, a global proxy can be configured in /etc/opsi/opsi-package-updater.conf.

[repository_uib_macos_stable]
…
proxy =

Should installed packages be updated later, this can be done with the following command:

opsi-package-updater -v update

More information about opsi-package-updater can be found in the manual.

4.3. Manual installation of the macOS opsi products.

It is also possible to manually download and install the packages.

Get the latest opsi packages in the .opsi package format. You can find the packages at https://download.uib.de/opsi4.2/stable/packages/macos/localboot or at https://download.uib.de/opsi4.2/testing/packages/macos/localboot.

We recommend saving the .opsi files to /var/lib/opsi/repository. To ensure that opsiconfd can access the files, opsi-set-rights /var/lib/opsi/repository should be run.

After downloading, you need to install the packages on the server using the command opsi-package-manager -i <package-name>.opsi.

5. Integration of existing macOS clients into opsi.

To include existing macOS clients in opsi, the opsi-client-agent must be installed on them. This can be performed in several ways. After you have installed the opsi-client-agent, as described below, the client will also appear in the client list of the opsi-configed, in the case you had not already added it there previously.

Basically, is possible to run on the client or from the server to trigger the installation of the agent.

Running the installation directly on the client is appropriate for individual machines. For a mass deployment of the agent, the opsi-deploy-client-agent is generally more suitable. If the necessary unlocks are available on the macOS clients.

If there is already another way to deploy software, it’s also possible to deploy the opsi-client-agent and run the silent_setup.sh script included in the package.

Once the agent is installed, existing opsi products can be installed on these clients.

5.1. Using opsi-client-agent-installer on macOS

  1. Logon to the client.

  2. Download the installer from your configserver. It is located at https://<fqdn_or_ip_of_the_configserver>:4447/public/opsi-client-agent/ and has the file name:
    Windows: opsi-client-agent-installer.exe
    Linux: opsi-linux-client-agent-installer.sh
    macOS: opsi-mac-client-agent-installer.sh

oca_installer_download

  1. Execute the installer (for linux and macos this must be done with root-rights, on windows a UAC-Request may be displayed)

  2. The installer will extract itself into a temporary local directory and start the oca-installation-helper.

oca_installer_start

This shows a user interface with input fields for Client-ID, Opsi Service URL, Username and Password. The fields are pre-filled (if possible e.g. if a old opsicliend.conf is found), but you may need to add or change some of the data.

  • Client-Id should be the fqdn of the Client.

  • Opsi Service url should have the format https://<fqdn_or_ip_of_the_configserver>:4447.

  • Username and Password should correspond to a user of the group opsiadmin in case of a first installation. For reinstallation it is also possible to use Client-Id and pckey for authentication.

After starting the Installer by clicking the button Install the installer connects to the server to register the client at the server. Afterwards the installer calls the included opsi-script to execute the setup.opsiscript of the opsi-[linux-|mac-]client-agent.

oca_installer_run

If the installation is finished the installer terminates.

Further information around the opsi-client-agent Installer and the command line parameters and other possibilities to install the opsi-client-agent you will find at the opsi-manual in the chapter Subsequent installation of the opsi-client-agents
https://download.uib.de/4.2/documentation/html/en/opsi-manual-v4.2/opsi-manual-v4.2.html#opsi-manual-clientagent-subsequent-installation

5.2. Using service_setup.sh on macOS

The method described over here is only for backward compatibility to opsi 4.1 and the corresponding opsi-client-agent versions 4.1. Please use as possible the opsi-client-agent Installer.

5.2.1. Using service_setup.sh on macOS (initial installation).

Due to macOS security restrictions, the ability to run scripts from mounted shares is limited. Trying to do the following with a share mounted via Finder to /Volumes (or similar) will therefore fail (depending on the macOS version).

  • Log in to the client.

  • Start the terminal program

  • For the following commands you need to replace the following placeholders:

    • <username> with your login name.

    • <mnt> with a directory name that does not exist yet e.g. 'mnt'.

    • <serviceuser> with a username that is known on the opsi-server.

    • <servicepass> with the password of the <serviceuser>. You can also omit :<servicepass> together with the mount option -N, then you will be prompt to input the password

    • <opsi-server> the name or IP number of the opsi-server.

sudo su
cd /Users/<username>
mkdir <mnt>
mount_smbfs //<serviceuser>@<opsi-server>/opsi_depot /Users/<username>/<mnt>
cd /Users/<username>/<mnt>/opsi-mac-client-agent
./service_setup.sh
cd
umount /Users/<username>/<mnt>

without password query

sudo su
cd /Users/<username>
mkdir <mnt>
mount_smbfs -N //<serviceuser>:<servicepass>@<opsi-server>/opsi_depot /Users/<username>/<mnt>
cd /Users/<username>/<mnt>/opsi-mac-client-agent
./service_setup.sh
cd
umount /Users/<username>/<mnt>

Example:

sudo su
cd /Users/uib
mkdir mnt
mount_smbfs  //adminuser@sepia/opsi_depot /Users/uib/mnt
cd /Users/uib/mnt/opsi-mac-client-agent
./service_setup.sh
cd
umount /Users/uib/mnt

  1. Start from the mounted share the script opsi-mac-client-agent\service_setup.sh
    Confirm with 2 x Enter

  2. The script copies the necessary files into a temporary local directory and then starts opsi-script for the actual installation.

  3. The script contacts the server via opsi webservice to create the client on the server side and to find out the pckey. This is done first with the user/password combination entered in config.ini. If this fails, a login window appears with service URL (opsi-configserver), user name and password. Here a user is needed which is a member of the group 'opsiadmin'. It is possible to also operate with a user which is only allowed to execute the method host_createOpsiClient.

The client reboots after the installation.

5.2.2. Using service_setup.sh on macOS (repair installation).

  • Log in to the client.

  • Start the terminal program

  • For the following commands you need to replace the following placeholders:

    • <serviceuser> with a username known on the opsi-server.

    • <servicepass> with the password of the <serviceuser>. You can also omit :<servicepass>, then you will be asked for the password

    • <opsi-server> with the name or IP number of the opsi server.

  • During the first installation opsi created a hidden pseudo user named opsisetupadmin, in whose home directory /var/opsisetupadmin is also the mount directory.

sudo su
mount_smbfs -N //<serviceuser>:<servicepass>@<opsi-server>/opsi_depot /var/opsisetupadmin/opsi_depot
cd /var/opsisetupadmin/opsi_depot/opsi-mac-client-agent
./service_setup.sh
cd
umount /var/opsisetupadmin/opsi_depot

Example:

sudo su
mount_smbfs -N //adminuser:linux123@sepia/opsi_depot /var/opsisetupadmin/opsi_depot
cd /var/opsisetupadmin/opsi_depot/opsi-mac-client-agent
./service_setup.sh
cd
umount /var/opsisetupadmin/opsi_depot

  1. Start the script opsi-mac-client-agent\service_setup.sh
    Confirm with 2 x Enter

  2. The script copies the necessary files into a temporary local directory and then starts the opsi-script for the actual installation.

  3. The script contacts the server via opsi webservice to create the client on the server side and to find out the pckey. This is done first with the user/password combination entered in config.ini. If this fails, a login window appears with the corresponding service URL (opsi-configserver), user name and password. Here a user is needed which is a member of the group 'opsiadmin'. It is also possible to utilize a user which is only allowed to execute the method host_createOpsiClient.

The client needs a reboot after the installation to become active.
The reboot is not triggered automatically.

5.3. Using opsi-deploy-client-agent for macOS.

The opsi-deploy-client-agent script deploys the opsi-client-agent directly from the opsi-server to the clients. It’s easy to integrate a large number of clients from the server into an opsi environment. As a prerequisite for the clients is needed:

  • an activated ssh access

Unfortunately on macOS the ssh accesses are deactivated by default. To use the opsi-deploy-client-agent command these accesses must be first activated.

This can be performed interactively in the 'System preferences / sharing':

Activating ssh access

On the command line, this can be done as follows:

sudo launchctl load -w /System/Library/LaunchDaemons/ssh.plist

A checkup of the current status of the ssh access is possible with the command:

sudo systemsetup -getremotelogin

Disabling ssh access on the command line looks like this:

sudo launchctl unload /System/Library/LaunchDaemons/ssh.plist

The opsi-deploy-client-agent script can be found at /var/lib/opsi/depot/opsi-client-agent
Run the script with 'root' privileges or as a user being part of the "opsifileadmins" group. If the script is not executable, you can fix this problem with the following command:
opsi-set-rights /var/lib/opsi/depot/opsi-client-agent/opsi-deploy-client-agent

The script creates the client on the server side, copies the installation files and configuration information, such as the pckey, to the client and starts the installation there.
The installation runs in the background without any interaction from user and transparently.

The command opsi-deploy-client-agent has several call parameters.
All following examples assume that you have switched to the root directory of the opsi-client-agent product:

cd /var/lib/opsi/depot/opsi-mac-client-agent

Typical calls are:

  • For a single client:

./opsi-deploy-client-agent -v --user=uib uib-mmini1

Results in the following output:

Password is required for deployment.
Password:
[5] [2021-02-04 16:43:43.121] [               ] Starting deployment to host uib-mmini1.uib.local   (posix.py:84)
[5] [2021-02-04 16:43:43.121] [               ] Querying for ip address of host uib-mmini1.uib.local   (common.py:158)
[5] [2021-02-04 16:43:43.122] [               ] Got ip address 192.168.10.70 from syscall   (common.py:167)
[5] [2021-02-04 16:43:43.123] [               ] Pinging host 192.168.10.70 ...   (common.py:183)
[5] [2021-02-04 16:43:44.146] [               ] Host 192.168.10.70 is up   (common.py:194)
[5] [2021-02-04 16:43:44.153] [               ] Patching config.ini   (posix.py:91)
[5] [2021-02-04 16:43:44.157] [               ] Copying installation scripts...   (posix.py:107)
[5] [2021-02-04 16:43:48.316] [               ] Running installation script...   (posix.py:147)
[5] [2021-02-04 16:43:53.382] [               ] opsi-client-agent successfully installed on uib-mmini1.uib.local   (posix.py:176)
[5] [2021-02-04 16:43:53.395] [               ] Restarting opsiclientd service on computer: uib-mmini1   (posix.py:331)
[5] [2021-02-04 16:43:55.620] [               ] 1/1 deployments successfully   (__init__.py:210)

  • For a list of clients:

./opsi-deploy-client-agent -v --user=uib --hosts-from-file HOSTFILE.TXT  --skip-existing-clients

Here HOSTFILE.TXT is a file with one client name (FQDN) per line. As long as the clients are not known to the opsi-server, it tries to install the opsi-mac-client-agent on this machine

  • Display all command line parameters:

./opsi-deploy-client-agent --help

6. Rollout of existing products to MacOS.

For the deployment of software to clients, the 'opsi-client-agent' must be installed on them. This can be rolled out on existing-machines.

Subsequently, the opsi-configed management interface is used to deploy software to clients.

6.1. Inventory with the localboot products hwaudit and swaudit.

In opsi-script, 'Client configuration' mode, under the 'Clients' tab, select the client under consideration.

If not already performed, update the opsi-configed’s dataset using 'Reload File/Data' or clicking the corresponding icon.

Go to the 'Product configuration' tab, click in the 'Requested' column for the hwaudit product, this will open a list/dropdown menu and there select the 'setup' action. Repeat this for the swaudit product.

The check mark in the icon menu bar should change its color to red. If you click it, the new settings will be transmitted to the opsi-server, afterwards its color will be green again.

Then restart the client. It should now start the opsi-client-agent and install the hwaudit and swaudit products. With hwaudit and swaudit, hardware and software information, respectively, is collected and transmitted to the opsi-server. The collected information is displayed under the 'Hardware Information' and 'Software Inventory' tabs, respectively.

6.2. Distribution of opsi standard products: m-homebrew.

This product installs the package management program homebrew which is used by several other opsi products for MacOS, e.g. to install Java.

See also: The opsi product m-homebrew.

In opsi-script, 'Client configuration' mode, select the client in question under the 'Clients' tab.

Switch to the 'Product Configuration' tab, click in the 'Requested' column for the m-homebrew product, this will open a list/dropdown menu and there select the 'setup' action.

The check mark in the icon menu bar should change its color to red. If you click on it, the new settings will be transmitted to the opsi-server, afterwards its color will be green again.

Then restart the client or push the installation via 'on_demand'. It should now start the opsi-client-agent and install the m-homebrew product.

6.3. Distribution of opsi standard products: m-javavm

This product installs the Java Runtime Environment which is used by several other opsi products for MacOS, e.g. opsi-configed, opsi-logviewer.

In opsi-script, mode 'Client configuration', select the client under the tab 'Clients'.

Switch to the 'Product Configuration' tab, click in the 'Requested' column for the m-javavm product, this will open a list/dropdown menu and there please select the 'setup' action.

The check mark in the icon menu bar should change its color to red. If you click on it, the new settings will be transmitted to the opsi-server, afterwards its color will be green again.

Then restart the client or push the installation via 'on_demand'. It should now start the opsi-client-agent and install the m-javavm product.

6.4. Distribution of opsi standard products: opsi-configed.

Attention: m-homebrew and m-javavm must be already installed!

To the standard products belongs the product opsi-configed which installs the opsi management interface as application on a computer. Because this application is a Java application, a JavaRE is included.

In the opsi-script, mode 'Client configuration', under the tab 'Clients' select the concerning client.

If not already done, update the opsi-configed’s dataset using 'Reload File/Data' by clicking the corresponding icon.

Switch to the 'Product configuration' tab, click in the 'Requested' column for the opsi-configed product, this will open a list/dropdown menu and there select the 'setup' action.

The check mark in the icon menu bar should change its color to red. If you click it, the new settings will be transmitted to the opsi-server, afterwards its color will be green again.

Then restart the client. It should now start the opsi-client-agent and install the opsi-configed product. After the installation is finished you should find the item opsi-configed under Applications.

7. Integration of own software into the software distribution of opsi.

The installation of software in opsi is performed by the opsi-client-agent and specially by the script controlled setup program opsi-script. Therefore an opsi-script script must be created for each opsi product. Afterwards this script, as well as the installation files and metadata are packed into an opsi product, which can finally be installed on the opsi-server.

7.1. A Brief Tutorial: How to write a opsi-script Script

7.1.1. Introduction

This tutorial merely helps you getting started with opsi. It can’t replace professional training (which you may order through uib), or thoroughly studying the complete opsi manuals (which might be time consuming and partially error prone if you lack background knowledge). uib now offers training in English, too.

Training and Support:

Get Training by uib gmbh in Europe or possibly Northern America:
https://uib.de/en/support-training/support/

Manuals:

The opsi Manuals can be found at:

https://docs.opsi.org/opsi-docs-en/4.2/index.html
important for scripting:
https://docs.opsi.org/opsi-docs-en/4.2/opsi-script-manual/opsi-script-manual.html

Can bee also found via:
https://uib.de/en/opsi-documentation/documentation/
important for scripting:
opsi-script reference card and opsi-script manual

Wiki (Scripts, Tips, Links):

https://forum.opsi.org/wiki

Support Forum (fast and free vendor support):

https://forum.opsi.org

7.1.2. Methods of non-interactive software installation on macOS.

Apple (unlike Microsoft) standardized its software installation methods very early on. In essence, there are two methods:

  • application Directory:
    This is a directory according to the pattern: <application name>.app However, such a directory is not displayed in the Finder as a directory, but as an 'application'. Inside this directory, according to a pattern, the files of the application must be located. A typical structure would be:

opsi-script.app
  |--Contents
       |-Info.plist
       |-PkgInfo
       |-MacOS
       |  |-opsi-script
       |  |-opsi-script-gui
       |
       |-Resources
          |- (....)

Such a directory must only be copied into the path /Applications for installation. Possible files in the directory MacOS must be made executable.
Such *.app directories are usually offered packed for download.

  • PKG file:
    These files contain software which need to be installed by a special command.

In both cases an unattended (i.e. non-interactive) installation is not an issue.

Often macOS software is offered in packed formats like *.zip, *.dmg or also *.tgz.

All variants mentioned so far can be installed directly by opsi-script, except *.tgz which must be unpacked before.

7.1.3. Structure of an opsi-script script

In the subsequent chapters the basic elements of a opsi-script script will be described with examples for Windows.

First an example for a simple opsi-script script:

[Actions]
WinBatch_tightvnc_silent_install

[WinBatch_tightvnc_silent_install]
"%ScriptPath%\tightvnc-1.3.9-setup.exe" /silent

An opsi-script script consists of primary and secondary sections. Sections are introduced with a section name in square brackets, as known from the ini files.
The true software installation work takes place in the secondary sections, which are called by the primary sections.

The secondary sections are "theme specific" and each has a special syntax.
The section name of a secondary section starts with its type, followed by a freely determinable name.

In the shown example, the primary section [Actions] calls a secondary section [WinBatch_tightvnc_silent_install].
The secondary section is of the type WinBatch. The content of a WinBatch section is executed via the Windows API.
So in this case the setup program tightvnc-1.3.9-setup.exe is started with the parameter /silent.

7.1.4. Primary Sections

Actions

The [Actions] section is the actual main program. This is where the script processing begins.

Sub-sections

Program sections that are required constantly can be redistributed to sub sections (subroutines). It’s possible to source sub sections to external files.

The primary sections are the main program in which the script flow is controlled. For this there are:

  • Variables: Strings and string lists

  • if elseif else endif statements

  • for loops over string lists

  • Functions

Picture: Avoiding duplicate code via distributed sub
Figure 1. Avoiding duplicate code via distributed sub

7.1.5. Important secondary sections

Files

File operations, such as:

  • copy (with version control, recursive …​).

  • delete

  • create directories

  • …​

WinBatch

Used to call programs via the Windows API. For example, invokes to setup programs in silent mode are made in these sections.

ShellInAnIcon

The content of this section is passed to the operating system on the typical shell for execution. This shell is the cmd.exe for Windows, for Linux and for macOS the bash. As such, normal batch scripts can be stored here.
Name variants of ShellInAnIcon with identical behavior are Shellbatch, DOSBatch and DOSInAnIcon.

ExecWith

The contents of these sections are passed to an external program such as an (interpreter) for execution. For example, ExecWith can be used to integrate AutoIt scripts http://www.autoitscript.com directly into the opsi-script script.

Registry

The Registry sections are used to edit the registry.

LinkFolder

LinkFolder sections are used to create and remove shortcuts. For example, such shortcuts can be created on the desktop or in the start menu.

7.1.6. Global constants

Global constants are text placeholders that can be used in primary and secondary sections and are textually replaced by their values at runtime.
The use of placeholders can be utilized to ensure that paths are set correctly in different environments (in the case of systems with different languages or operating system versions for example).

Examples:

%ProgramFiles32Dir%

c:\Program Files (x86)

%Systemroot%

c:\windows

%System%

c:\windows\system32

%opsiTmpDir%

c:\

%Scriptpath%

<path to running script>

7.1.7. Second example: tightvnc

For clarification purposes, now a simple script for the installation of tightvnc. As a matter of fact this script would get on with the call of the silent installation in the Winbatch section. However, during a repeated installation an interactive dialog appears here (because of the restart of the running service). This dialog window is closed (if it appears) with the help of 'AutoIt'.

[Actions]
Message "Installing tightvnc 1.3.9 ..."
ExecWith_autoit_confirm "%ScriptPath%\autoit3.exe" WINST /letThemGo
WinBatch_tightvnc_silent_install
KillTask "autoit3.exe"

[WinBatch_tightvnc_silent_install]
"%ScriptPath%\tightvnc-1.3.9-setup.exe" /silent

[ExecWith_autoit_confirm]
; Wait for the confirm dialog which only appears if tightvnc was installed before as service
; Waiting for the window to appear
WinWait("Confirm")
; Activate (move focus to) window
WinActivate("Confirm")
; Choose answer no
Send("N")

7.1.8. Elementary commands for primary sections

String-Variable
Variable declaration

'DefVar <variable name> [= <initial value>]'

Variable assignment

'Set <variable name> = <value>'

Example:

DefVar $ProductId$
Set $ProductId$ = "firefox"

or

DefVar $ProductId$ = "firefox"
String variables are handled differently in primary and secondary sections. In primary sections, string variables are independent objects. Only here they can be declared and assigned values. Accordingly, the connection of variables and strings to a string expression is to be performed with a "+" operator.
Example: "Installing "+ $ProductId$ +" …​"
In secondary sections, string variables are replaced with the contents of the variable before the section is executed.
For example: "Installing $ProductId$ …​"
This should be taken into consideration when the corresponding string expressions are cut and pasted in the script.
The advantage of this construction is that in sections that are executed outside the 'opsi-script' (DosBatch / Execwith) opsi-script variables can be manipulated at ease.
Message / ShowBitmap

Text output during installation:
Message <string>

Example:

Message "Installing "+ $ProductId$ +" ..."

To output a graphic during the installation:
ShowBitmap <filename> <subtitle>

Example:

ShowBitmap "%ScriptPath%\python.png" "Python"
if [elseif] [else] endif

Syntax:

if <condition>
	;statement(s)
[elseif <condition>
;statement(s)]
[
else
	;statement(s)
]
endif
Functions
HasMinimumSpace

Checks for free space on the hard disk.

FileExists

Checks for the existence of a file or directory.

Errors, logging and comments
Comment characters ';'

Lines that start with a semicolon (';') are not interpreted.

Comment

Writes a comment message to the log file.

LogError

Writes an error message to the log file.

IsFatalError

Cancels the execution of the running script and reports the installation as failed.

Condition for execution
requiredWinstVersion

specifies the (minimum) required opsi-script version.

Other important opsi-script functions

An overview of the opsi-script functions is given by the reference card
https://docs.opsi.org/opsi-docs-en/4.2/opsi-script-manual/reference-card.html

A detailed documentation can be found in the opsi-script manual:
https://docs.opsi.org/opsi-docs-en/4.2/opsi-script-manual/opsi-script-manual.html

Here are a few more notes on particularly important elements:

Stringlists:

String lists are very powerful, especially for evaluating output from external programs. Read the opsi-script docs for more information.

ExitWindows:

Reboot/Shutdown the system and finish the opsi-script.

  • ExitWindows /Reboot
    Computer restart after completion of the running script.

  • ExitWindows /ImmediateReboot
    Immediate reboot.

  • ExitWindows /ImmediateLogout
    Immediately stop script editing and terminate opsi-script.

Product-Properties:

For some products it’s necessary to provide options. These are specifically evaluated per client at runtime. How such properties are created is described in the chapter Creation of opsi product packages

The access to the values of the properties is done via the function GetProductProperty:

if GetProductProperty("example-property", "no") = "yes"
	Files_copy_extra_files
endif
Encoding:

Write your scripts in UTF-8 encoding and set the line
encoding=utf8 At the beginning of the file

Special commands for macOS

  • GetOS // returns: Linux or Windows_NT or macos [W/L/M]

  • getMacosVersionInfo [M]

  • getMacosVersionMap [M]

See also:
https://docs.opsi.org/opsi-docs-en/4.2/opsi-script-manual/reference-card.html#opsi-script-rc-macos-specific

In the following chapters special opsi MacOS commands to install software are presented, which come from the opsi-script library uib_macosinstalllib. This documentation was automatically generated directly from the source code.

Documentation of opsi library: uib_macosinstalllib.opsiscript

Documentation of local function install_macos_app
Definition

install_macos_app($myapp$ : string) : string

Description

try to install the app given by $myapp$

Example:

[Actions]
importlib "uib_macosinstalllib"

DefVar $installfile$
DefVar $installresult$

comment "we have a *.app (directory) and install with install_macos_app"
set $installfile$ = "%scriptpath%/files/my_macos_app.app"
set $installresult$ = install_macos_app($installfile$)
if stringtobool($installresult$)
	comment "installation succseeded"
else
	LogError "installation failed"
endif

Documentation of local function install_macos_pkg
Definition

install_macos_pkg($mypkg$ : string) : string

Description

try to install the pkg file given by $mypkg$

Example:

[Actions]
importlib "uib_macosinstalllib"

DefVar $installfile$
DefVar $installresult$

comment "we have a *.pkg and install with install_macos_pkg"
set $installfile$ = "%scriptpath%/files/my_macos_app.pkg"
set $installresult$ = install_macos_pkg($installfile$)
if stringtobool($installresult$)
	comment "installation succseeded"
else
	LogError "installation failed"
endif

Documentation of local function install_macos_dmg
Definition

install_macos_dmg($mydmg$ : string) : string

Description

try to install the dmg file given by $mydmg$

Example:

[Actions]
importlib "uib_macosinstalllib"

DefVar $installfile$
DefVar $installresult$

comment "we have a *.dmg and install with install_macos_dmg"
set $installfile$ = "%scriptpath%/files/my_macos_app.dmg"
set $installresult$ = install_macos_dmg($installfile$)
if stringtobool($installresult$)
	comment "installation succseeded"
else
	LogError "installation failed"
endif

Documentation of local function install_macos_zip
Definition

install_macos_zip($myzip$ : string) : string

Description

try to install the zip file given by $myzip$ unzips the file and try to find a installable part (*.app, *.pkg, *.dmg) and try to install this

Example:

[Actions]
importlib "uib_macosinstalllib"

DefVar $installfile$
DefVar $installresult$

comment "we have a *.zip and install with install_macos_zip"
set $installfile$ = "%scriptpath%/files/my_macos_app.zip"
set $installresult$ = install_macos_zip($installfile$)
if stringtobool($installresult$)
	comment "installation succseeded"
else
	LogError "installation failed"
endif

Documentation of local function install_macos_generic
Definition

install_macos_generic($myfile$ : string) : string

Description

try to install the file given by $myfile$ Checks if the file is a well known installable (*.app, *.pkg, *.dmg, *.zip) and try to install this

Example:

see: install_macos_generic
[Actions]
importlib "uib_macosinstalllib"

DefVar $installfile$
DefVar $installresult$

comment "we have a *.* and install with install_macos_generic"
set $installfile$ = "%scriptpath%/files/opsi-script.app"
set $installresult$ = install_macos_generic($installfile$)
if stringtobool($installresult$)
	comment "installation succseeded"
else
	Error "installation failed"
endif

7.1.9. Example: macOS template m-opsi-template

You can create this template with the opsi-setup-detector.

Listing 3. declarations.opsiinc: Variable Declaration
; ----------------------------------------------------------------
; This is a opsi-script file.
; See https://opsi.org    https://uib.de
; This code was originally created by opsi-setup-detector 4.2.1.5
; ----------------------------------------------------------------

; -------------------------------------
; include file for opsi-setup-detector products
; Define all variables here
;---------------------------
DefVar $arch$
DefVar $errorstring$
DefVar $exitcode$
DefVar $iconfile$
DefVar $installerSourceDir$
DefVar $installCommand$
DefVar $installSuccess$
DefVar $installdir$
DefVar $installdir1$
DefVar $installdir2$
DefVar $installerfile$
DefVar $minimumspace$
DefVar $oldProgFound$
DefVar $os$
DefVar $osshort$
DefVar $ProdVersion$
DefVar $productid$
DefVar $targetfile$
DefVar $tmpstr$

DefVar $targetprogram$
Listing 4. setup.opsiscript: Installation Script
; ----------------------------------------------------------------
; This is a opsi-script file.
; See https://opsi.org    https://uib.de
; This code was originally created by opsi-setup-detector 4.2.1.5
; ----------------------------------------------------------------
encoding=utf8

[Actions]
requiredOpsiscriptVersion >= "4.12.4.23"

importlib "uib_exitcode.opsiscript"
importlib "osd-lib.opsiscript"
importlib "uib_macosinstalllib.opsiscript"


; All variables are defined here:
include_insert "declarations.opsiinc"

; ----------------------------------------------------------------
; Please edit the following values:
; ----------------------------------------------------------------
; $ProductId$ is the name of the product in opsi, only lower letters, no umlauts, no white spaces, use '-' as a separator
Set $ProductId$		 = "m-opsi-template"
; the path were we find the product after the installation
;Set $InstallDir$	= "/Applications/<product.app>"
Set $InstallDir$		= "/Applications/<productid.app>"
; ----------------------------------------------------------------

Message "Installing " + $ProductId$ + " ..."

set $OS$ = GetOS

if not(($OS$ = "macos"))
	logError "Installation aborted: wrong OS version: only MacOS"
	isFatalError "wrong OS"
endif

comment "Show product picture"
ShowBitmap "%ScriptPath%/" + $ProductId$ + ".png" $ProductId$



if FileExists("%ScriptPath%\delinc.opsiinc")
	comment "Start uninstall part"
	include_insert "%ScriptPath%\delinc.opsiinc"
endif

Message "Installing " + $ProductId$ + " ..."

set $installerSourceDir$ = ""


comment "Start installer "
ChangeDirectory $installerSourceDir$
;----------------------------------------------
set $installSuccess$ = install_macos_generic("%SCRIPTPATH%/files1/<my macos install file>")
;----------------------------------------------
if $installSuccess$  = "false"
	LogError "Installation failed"
	isfatalerror "Installation failed"
else
	Comment "Installation success"
endif



comment "Copy files"
Files_install

[Files_uninstall]
del -sf "$InstallDir$/"


[Files_install]
; Example of recursively copying some files into the installation directory:
;
; copy -s "%ScriptPath%\files\*.*" "$InstallDir$"



; ----------------------------------------------------------------
; ----------------------------------------------------------------
Listing 5. delinc.opsiinc: Deinstallation Include Script
; ----------------------------------------------------------------
; This is a opsi-script file.
; See https://opsi.org    https://uib.de
; This code was originally created by opsi-setup-detector 4.2.1.5
; ----------------------------------------------------------------
encoding=utf8

Message "Check for existing installation of " + $ProductId$ + " ..."

comment "Start the Uninstall check:"
set $oldProgFound$ = "false"
if directoryExists($InstallDir$)
	set $oldProgFound$ = "true"
endif

f $oldProgFound$ = "true"
comment "Is the Installdir in the Applications directory ?"
if "1" = strPos(lower($InstallDir$),lower("/Applications/"))
	comment "Do not delete the whole /Applications dir ..."
	if not(lower($InstallDir$) = lower('/Applications/'))
		Message "Uninstalling " + $ProductId$ + " ..."
		Files_uninstall
	endif
endif
endif;-----------------------------------------------------
Listing 6. uninstall.opsiscript: Deinstallation Script
; ----------------------------------------------------------------
; This is a opsi-script file.
; See https://opsi.org    https://uib.de
; This code was originally created by opsi-setup-detector 4.2.1.5
; ----------------------------------------------------------------
encoding=utf8

[Actions]
requiredOpsiscriptVersion >= "4.12.4.23"

importlib "uib_exitcode.opsiscript"
importlib "osd-lib.opsiscript"
importlib "uib_macosinstalllib.opsiscript"


; All variables are defined here:
include_insert "declarations.opsiinc"

; ----------------------------------------------------------------
; Please edit the following values:
; ----------------------------------------------------------------
; $ProductId$ is the name of the product in opsi, only lower letters, no umlauts, no white spaces, use '-' as a separator
Set $ProductId$		 = "m-opsi-template"
; the path were we find the product after the installation
;Set $InstallDir$	= "/Applications/<product.app>"
Set $InstallDir$	= "/Applications/<productid.app>"
; ----------------------------------------------------------------

Message "Uninstalling " + $ProductId$ + " ..."

set $OS$ = GetOS

if not(($OS$ = "macos"))
	logError "Installation aborted: wrong OS version: only macos"
	isFatalError "wrong OS"
endif

comment "Show product picture"
ShowBitmap "%ScriptPath%/" + $ProductId$ + ".png" $ProductId$



if FileExists("%ScriptPath%\delinc.opsiinc")
	comment "Start uninstall part"
	include_insert "%ScriptPath%\delinc.opsiinc"
endif



[Files_uninstall]
del -sf "$InstallDir$/"


; ----------------------------------------------------------------
; ----------------------------------------------------------------

7.2. Create an opsi product package

7.2.1. Installation of the opsi-package-builder

The opsi-package-builder is currently available for Windows and Linux and MacOS.

The installation files / packages of the opsi-package-builder can be found here:
https://forum.opsi.org/viewtopic.php?p=32473#p32473
There you will find in the first lines of the post links to the installation files for Windows and Linux and MacOS.
The opsi-package-builder is not made by 'uib' but by Holger Pandel from the opsi-community (thank you!)..

The opsi-package-builder open source license:
https://github.com/pandel/opsiPackageBuilder/blob/master/LICENSE_DE

The opsi-package-builder has its own documentation, that is part of the installation.

You can install the opsi-package-builder also via opsi:

The package opsipackagebuilder_wlm belongs to the opsi standard products and should be installed on your opsi-server. If not, use:

opsi-package-updater install opsipackagebuilder_wlm

to install it on the opsi-server.

7.2.2. Installation of the opsi-setup-detector

The opsi-setup-detector is currently available for Windows and Linux and MacOS.

You can install the opsi-setup-detector via opsi:

The package opsi-setup-detector belongs to the opsi standard products and should be installed on your opsi-server. If not, use:

opsi-package-updater install opsi-setup-detector

to install it on the opsi-server.

A setup program to install the opsi-setup-detector without opsi can be found at :
https://download.uib.de/opsi4.2/misc/helper/

The base functionality of the opsi-setup-detector is the same on all suppoted platforms. While analyzing a installer file some helper programs will be called, that may not availiable or runable.

  • Inno-Setups will be analyzed with innounpack.exe at Windows.

  • wix-setups will be analyzed with dark.exe at Windows.

  • .deb or. .rpm files will be analyzed with the Linux command line tools.

The opsi product opsi-setup-detector has a dependency on the opsi product opsi-package-builder_wlm. The opsi-setup-detector uses the opsi-package-builder if available, but can for the most part also work without it. The installation of the opsi-package-builder is recommended.

7.2.3. Installation of the opsi-logviewer

The opsi-logviewer is currently available for Windows, Linux and MacOS.

You can install the opsi-logviewer via opsi:

The package opsi-logviewer is part of the opsi standard products and should be installed on your opsi-server. If not, with:

opsi-package-updater install opsi-logviewer

You can install it on the opsi-server.

A setup program to install the opsi-setup-detector on Windows even without opsi can be found at :
https://download.uib.de/opsi4.2/misc/helper/

The opsi product opsi-logviewer has a stated dependency to the opsi product javavm.

7.2.4. The opsi-setup-detector program to create a macOS script.

7.2.5. Opsi-setup-detector Start and necessary configurations

The opsi-setup-detector can be started from the programs menu and can be found there under opsi.org. Under Windows the opsi-setup-detector is also integrated into the context menu of the explorer in order to call the setup program directly for analysis with the right mouse button.

Configuration dialog
Figure 2. opsi-setup-detector Necessary configuration on first startup

After the first start of the opsi-setup-detector a configuration mask appears. The following information is required here:

  • fullname: (Used for entries in the changelog.txt)

  • email_address: (Used for entries in the changelog.txt)

  • workbench_path: : Path to the directory in which the opsi packages are going to be created. This is ideally the path to the place where the opsi_workbench of your opsi-server is mounted.

Optional: Connection data for the opsi-webservice:

  • Service_URL : The URL of the opsi webservice (like: https://<opsi-server>:4447)

  • Service_user : The user name used to connect to the opsi webservice

  • Service_pass : The password of the given user used to connect to the opsi webservice
    ATTENTION SECURITY RISK: Even it is stored encrypted, it is easy to decrypt be analyzing the source code. If empty you will be asked if the connection is started.

After all needed configurations has be done and saved, you will see the startpage.

Startpage
Figure 3. opsi-setup-detector Start

On the main window, select the desired task and follow the dialogs or select the 'Next step' button.

The offered tasks are grouped by:

  • OS independent

  • Windows

  • Linux

  • MacOS

  • multi platform

The possible options for macOS:

  1. Analyze file and create an opsi package
    A macOS installer file is used and the entire process is gone through including the creation of an opsi package. This process is similar to that described for Windows in the next chapter.

  2. Create an opsi package template
    This item does not ask for an installer file, but creates an opsi template product for macOS, with the information from the product configuration already filled in.

The following screenshots show the use of Windows installer files, but they look similar when using MacOS installer files like *.app, *.dmg, *.zip.

7.2.6. opsi-setup-detector: Analyze file and create opsi package

The workflow is here described using Analyze file and create opsi package as an example.

Startpage
Figure 4. opsi-setup-detector Start

After you selected the task, you will get a file selection dialog. Select now the setup file that has to be analyzed. The analyze will start directly after the selection is done.

7.2.7. opsi-setup-detector: Analyze

Analysis
Figure 5. opsi-setup-detector analysis

If the analyze found no result, you will get here a Sorry unknown Installer.

Sorry unknown Installer

In this dialog you may choose to abort the create process. You may also choose to continue based on the pattern of a choosable installer type.

If we have a successful analyze, you will see the result page.

Result of analysis
Figure 6. opsi-setup-detector Result of the analysis

  • Detected Setup Type: Type of detected Installer

  • MST allowed:

  • Link with information about the installer

  • Setup file: Path and name of the analyzed setup file

  • MST file: For MSI installers or installers which contain MSI, an MST file can be specified here which will be integrated into the MSI call.

  • MsiId: For MSI installers or installers that contain MSI in the form of product code

  • MsiName: For MSI installers or installers that contain MSI in the form of product name as it will be used in the registry as 'DisplayName'.

  • Software version: The version of the software to be installed if determinable.

  • Setup file size MB: Size of the setup file in MB

  • Required space MB: This value is an estimate of six times the size of the setup file and can be adjusted if necessary

  • InstallDir: As far as detected the directory where the software will be installed.
    You may also choose the directory via the selection button on the right (if the product is installed). If you there get a path like 'C:\program Files' or 'C:\program Files (x86)', it will be replaced by the matching opsi-script constant (e.g. '%ProgramFiles32Dir%').

  • Unattended installation command: The determined command for a non-interactive installation.

  • Unattended deinstallation command: The determined command for a non-interactive deinstallation.

  • Deinstallation program: The determined deinstallations program.
    You may also choose the file via the selection button on the right (if the product is installed).

  • Target Program: The main program of the software that has to be installed.
    Will be used for creating desktop icons or start menu entries.
    Will be not detected. You have to choose it via the selection button on the right (if the product is installed).

The values determined here can now be corrected or supplemented if necessary. The button Next Step leads to the first page of the product configuration. The metadata of the opsi product to be created is entered here.

The values determined here can be incorrect and are probably incomplete!
After an initial installation, you should definitely check the values of InstallDir, deinstallation program and software version and adjust them in your script if necessary.

7.2.8. opsi-setup-detector: Product configuration 1

Product configuration 1
Figure 7. opsi-setup-detector Product configuration 1

  • opsi Product ID: this is the name of the opsi package to be generated and is generated from the product name below, where spaces and other invalid characters are replaced by a '-'. The proposed opsi Product ID can of course be changed.

  • Product Name: the name of the software to install. This may have to be corrected manually.

  • Product Version: The version number determined from the name of the setup file must probably be corrected manually. It may only contain numbers and periods, since it’s used for the versioning of the opsi package.

  • Description: In this field the product name is given as default and should be completed with further hints, which are then set as product description of the opsi package.

  • Template Channel: Here you may select from different sources of template files, that are used to create the product scripts. The following 'template Channels' are available:

    • Default: This is the default and fallback. If you choose any other channel and work with a task that does not provide the templates for this task, so the files from default will be used.
      The basic script files for a product are: setup.opsiscript, uninstall.opsiscript, declarations.opsiinc, delinc.opsiinc

    • Training: The goal is to be more simple and more commented.
      The basic script files for a product are: setup.opsiscript, uninstall.opsiscript, delinc.opsiinc

    • Structured: The goal is to get a structure. that avoids double code.
      The basic script files for a product are: setup.opsiscript, uninstall.opsiscript, declarations.opsiinc, sections.opsiinc, delinc.opsiinc

    • Custom: This is empty be default. You may add your own templates. Therefor you have to copy your own templates to the directory 'opsi-setup-detector/custom/template-files/' on your opsi-depot.

Checkboxes for additional code
The following check boxes will add additional code and settings in order to handle special tasks:

  • Support custom directory : The product will contain a additional directory 'custom' to hold custom specific files. While installation of a new version of the product your custom directory and its content will remain. There will be code added to the scripts to copy files from the custom directory to the client.
    More details: Section 7.3.1

  • Install from local temp dir : The installation files will be copied to a temporary, local directory in a first step. In a second step the installation will be started from the local directory. This is be useful especially for installation that may interfere wit the network connection (e.g. driver).
    More details: Section 7.3.2

  • Handle License Key : Adds a property and code for the handling of a license key.
    More details: Section 7.3.3

  • DesktopIcon : Adds a property and code for the handling of desktop icons.
    More details: Section 7.3.4

  • Customize Profile : Add to the installation code a 'Profileactions' section which is used for manipulating the local or roaming user profiles. For 'Roaming Profiles' the script will be also provided as loginscript.
    More details: Section 7.3.5

7.2.9. opsi-setup-detector: Priority and dependencies

Product configuration 2
Figure 8. opsi-setup-detector Product configuration 2

For normal application software you don’t have to do anything here, due to the fact that the default settings 'fit'. You can press the Next Step button.

Otherwise, here is an explanation of the settings that are possible:

Priority

affects the installation order. Recommended for application software: 0
Possible values are between 100 (at the very beginning) and -100 (at the very end). If product dependencies also exist, these will also additionally influence the installation sequence.

Dependencies

Here you can define the dependencies between products.
If the configuration contains the connection data for your opsi-server, the connection will here be started. If the configuration does not contain the password (for security reasons) you will be asked for the password:

Password Dialog

see also: Opsi-setup-detector Start and necessary configurations