Adding clients to opsi

To be able to manage computers with opsi, they must be known to the opsi system. In addition, an agent must be running on these computers so that communication between the server and client is possible. No management is possible without this client agent.

Depending on the environment in which opsi is to be used, there are different procedures. If there are already clients in the environment with an installed operating system that are to be managed with opsi, they can be integrated in different ways.

The alternative to this is that the computers to be managed by opsi are equipped with a new operating system. As part of the installation of the operating system, the required agent is also installed by opsi. However, any previously installed software (including the operating system) will be removed. To use this procedure you first add a client to opsi and then perform an OS installation.

Creation of a new opsi client

To manage computers, they must be known to the opsi-server. This chapter describes different ways to create a client in opsi for later management. This is particularly helpful if you want to install an operating system on your computer using opsi.

For the integration of clients with an already installed operating system, please read the chapter integration of existing Clients.

Creating a new opsi client via the graphical management interface

A client can be added to the opsi-server through the opsi-configed graphical user interface.

From the menu, choose OpsiClient / Create new opsi client and enter:

  • Client name

  • DNS domain (if different from the default)

  • Client description

  • IP address (required if DNS can not be used resolve the address of the client)

  • MAC address (required if the opsi-server is the DHCP server or if you want to use PXE boot with this client)

After completing the input, the client will be created on the opsi-server, and if the opsi-server is also the DHCP server, the client will also be created in the DHCP configuration, as a PXE client.

The list of configured opsi clients can be viewed at any time in the opsi-configed mode Client configuration under the clients tab.

Creating a new opsi client via the command line

A client can added through the command line using the tool opsi-admin.

The syntax is the following:

opsi-admin -d method host_createOpsiClient <client-id> [opsiHostKey] [description] [notes] [hardwareAddress] [ipAddress] [inventoryNumber] [oneTimePassword] [created] [lastSeen]

Missing values usually use a default value - most fields are then empty.

The following command will create the client testclient.domain.local with a random host key, the description Testclient, no notes, the MAC address of 00:0c:29:12:34:56 and the IP address

opsi-admin -d method host_createOpsiClient testclient.domain.local "null" "Testclient" "" 00:0c:29:12:34:56

Creating a new opsi client using the opsi-client-bootcd

On the download page of uib you will find various ISO images of the 'opsi-client-boot-cd' at Download the latest and burn it to a CD.

Start the computer from the CD. You then should see the following screen:

Screenshot: Start image opsi-client-boot-cd
Figure 1. Start image opsi-client-boot-cd

Choose Start opsi (English). After a while, the following screen will appear. If your DHCP server assigns IP addresses to unknown DHCP clients, then most fields will already have valid values. Otherwise you have to complete the missing data by hand. You must at least give the hostname.

Screenshot: bootimage/boot-cd configuration screen
Figure 2. bootimage/boot-cd configuration screen

Then choose OK.

Screenshot: bootimage/boot-cd:  Choose how to create Client
Figure 3. bootimage/boot-cd: Choose how to create Client

Then choose Admin account. This tells the client to register itself at the opsi-server using provided credentials.

Screenshot: bootimage / boot-cd: Authenticate as member of opsiadmin group
Figure 4. bootimage / boot-cd: Authenticate as member of opsiadmin group

Now you will get a login window, where you must authenticate yourself as a member of the opsiadmin group. If this was successful, then the client sends its data to the server, at which point the client will be created at the server. In the next step, the client asks the server for the list of available netboot products, and makes them available for you to choose from.

Screenshot: bootimage/boot-cd: netboot product list
Figure 5. bootimage/boot-cd: netboot product list

Now you may choose the operating system that you would like to install (or e.g. hwinvent).

Integration of existing Linux clients into opsi.

To include existing Linux 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 Linux clients.

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

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

Using opsi-client-agent-installer on Linux

  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
    macOS: opsi-mac-client-agent-installer.command

  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.


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.


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.

Using on Linux (outdated)

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.

  • 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 pass=<servicepass>, then you will be prompt to input the password

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

sudo su
cd /mnt
mount.cifs //<opsi-server>/opsi_depot /mnt -o user=<serviceuser>
cd /mnt/opsi-linux-client-agent
umount /mnt

without password query

sudo su
cd /mnt
mount.cifs //<opsi-server>/opsi_depot /mnt -o user=<serviceuser>, pass=<servicepass>
cd /mnt/opsi-linux-client-agent
umount /mnt


sudo su
cd /mnt
mount.cifs //sepia/opsi_depot /mnt -o user=adminuser
cd /mnt/opsi-linux-client-agent
umount /mnt
  1. Start from the mounted share the script opsi-linux-client-agent\
    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 needs a reboot after the installation.

Using opsi-deploy-client-agent for Linux.

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

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 group "opsifileadmins" 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-linux-client-agent

Typical calls are:

  • For a single client:

./opsi-deploy-client-agent -v --user=root mylinuxclient.local

Results in the following output:

Password is required for deployment.
[5] [2021-02-04 16:43:43.121] [               ] Starting deployment to host mylinuxclient.locall   (
[5] [2021-02-04 16:43:43.121] [               ] Querying for ip address of host mylinuxclient.locall   (
[5] [2021-02-04 16:43:43.122] [               ] Got ip address from syscall   (
[5] [2021-02-04 16:43:43.123] [               ] Pinging host ...   (
[5] [2021-02-04 16:43:44.146] [               ] Host is up   (
[5] [2021-02-04 16:43:44.153] [               ] Patching config.ini   (
[5] [2021-02-04 16:43:44.157] [               ] Copying installation scripts...   (
[5] [2021-02-04 16:43:48.316] [               ] Running installation script...   (
[5] [2021-02-04 16:43:53.382] [               ] opsi-client-agent successfully installed on mylinuxclient.locall   (
[5] [2021-02-04 16:43:53.395] [               ] Restarting opsiclientd service on computer: uib-mmini1   (
[5] [2021-02-04 16:43:55.620] [               ] 1/1 deployments successfully   (
  • For a list of clients:

./opsi-deploy-client-agent -v --user=root --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