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:

The legally binding text of the license can be found here:

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.


The legally binding text of the AGPLv3 license can be found here:

Information about the AGPL:

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

The names 'opsi', '', 'open pc server integration' and the opsi logo are registered trademarks of uib gmbh. :leveloffset: +1


1. Who should read this manual?

This manual is aimed at everyone who is interested in automatic software distribution with 'opsi'. The focus of the documentation is the explanation of the technical background, in order to contribute to an understanding of the processes.

This manual should not only support the system administrator who works practically with opsi, but also give prospective users a concrete overview of opsi in advance.

1.1. Conventions in text and graphics

Names which are shown in '<angle brackets>' have to be replaced by a real name.

Example: The file share on which the opsi software packages are located is called <opsi-depot-share> and is located on a real server on /var/lib/opsi/depot.

The software package: <opsi-depot-share>/ooffice is actually under /var/lib/opsi/depot/ooffice.

Examples from program code or configuration files use a Courier font and are highlighted in color.


2. Overview of opsi

Tools for automated software distribution and operating system installation are important and necessary tools for standardization, maintainability and cost saving of larger PC networks. Normally the application of such tools comes along with substantial royalties, whereas opsi as an open source tool affords explicit economics. Expenses thereby arise only from performed services like consulting, training and maintenance, and perhaps from low cofunding rates if you like to use some of the non free modules.

Although the software itself and the handbooks are free of charge, the process of introducing any software distribution tool is still an investment. To get the benefit without throwbacks and without a long learning curve consulting and education of the system administrators by a professional partner is recommended. uib offers all these services around opsi.

The opsi system as developed by uib depends on Linux-servers. They are used for remote installation and maintenance of the client OS and the client software packets ("PC-Server-Integration"). It is based as far as possible on free available tools (GNUtools, SAMBA etc.). The complete system all together is named opsi (Open PC-Server-Integration) and with its configurability is a very interesting solution for the administration challenges of a large computer park.

2.1. Experience

opsi is derived from a system, which is in use since the middle of the 90’s with more than 2000 Client-PCs in different locations of a state authority. Since that time it has continuously been adapted to the changing Microsoft operating system world. As a product opsi is now accessible for a broad range of interested users.

You can find an geographical overview of the registered opsi-installations at: opsi-map

2.2. opsi features

The core features of opsi are:

  • automatic software distribution

  • automatic operating system installation

  • hard- and software inventory

  • comfortable control via the opsi management interface

  • support of multiple depot-servers

2.3. opsi Extensions

  • Management of licenses

  • MySQL-Backend

  • Nagios Connector

  • Installation ab Shutdown

  • Local Image Backup (Rapid client restore of student computers. For public authorities (e.g. schools) only)

  • Linux Agent

  • WAN Extension (Support for clients behind slow connections)

  • User Profile Management (manipulation Profiles even with Roamin Profiles)

  • OTRS::ITSM Connection - via KIX4OTRS by cape IT gmbh

2.4. Structure

The configuration of opsi requires some data management. All non-server components are using a web service for data exchange with the opsi server. They exchange data via the 'opsiconfd', and the 'opsiconfd' forwards the data to the backend manager which passes the data into the selected backend.

opsi supports different backends: Backends:

  • File based

  • MySQL based

Scheme: opsi with File / MySQL backend
Figure 1. Scheme: opsi with File / MySQL backend

More details you will find at opsi data storage (backends).

The backend configuratin will be found at the files in ther directories /etc/opsi/backendManager and /etc/opsi/backends.

Scheme: backend layers and access control
Figure 2. Scheme: backend layers and access control

The configuration files in /etc/opsi/backends define the backends.

Which backend is used for which data, is configured in the file /etc/opsi/backendManager/dispatch.conf.

The file /etc/opsi/backendManager/acl.conf defines who has access to which methods.

Below the directory /etc/opsi/backendManager/extend.d there could be files which defines extended opsi methods. So you will find here for example the files which define the action based ('legacy') methods by mapping them to the object based methods (/etc/opsi/backendManager/extend.d/20_legacy.conf).

A more detailed reference of these configuration files you will find at

3. opsi Management GUI: opsi-configed

3.1. Requirements and operation

The opsi-configed works with the data from a running opsiconfd at least of version 4.1.

On top of that, you can download the opsi-configed also as a portable for the operating systems Windows, Linux and MacOS from :[]. This way you can also start the program without installation.

On every system - if the necessary jar-archive is available - you can start the opsi-configed with the command java -jar configed.jar.

With java -jar configed.jar --help you’ll get a list of the command line options:

-l [LOC]		            --locale [LOC]			                        Set locale [LOC] (format: <language>_<country>)
-h [HOST]		            --host [HOST]			                          Configuration server [HOST] to connect to
-u [NAME]		            --user [NAME]		                            User for authentication
-p [PASSWORD]	          --password [PASSWORD]		                    password for authentication
-c [CLIENT]	            --client [CLIENT]		                        [CLIENT] to preselect
-g [CLIENTGROUP]        --group [CLIENTGROUP]	                      [CLIENTGROUP] to preselect
-t [INDEX]		          --tab [INDEX]                               Start with tab number INDEX, index counting starts with 0, works only if a CLIENT is preselected
-d [PATH]			          --logdirectory [PATH]                       Directory for the log files
-r [REFRESHMINUTES]		  --refreshminutes [REFRESHMINUTES]			      Refresh data every [REFRESHMINUTES]  (where this feature is implemented, 0 = never)
-qs [SAVEDSEARCH_NAME]	--querysavedsearch [SAVEDSEARCH_NAME]	      On command line: tell saved host searches list resp. the search result for [SAVEDSEARCH_NAME]
--ssh-key SSHKEY					                            	            full path with filename from sshkey used for authentication on ssh server
--ssh-passphrase PASSPHRASE			                                    passphrase for given sshkey used for authentication on ssh server
--version								                                            Tell configed version
--collect_queries_until_no [N]		                           	      Collect the first N queries; N = -1 (default, no collect), 0 = infinite
--help								                                              Give this help
--loglevel [L] 						                            	            Set logging level [L], [L] is a number >= 0, <= 9, Default 4
--halt								                                              Use first occurring debug halt point that may be in the code
--sqlgetrows							                                          Force use sql statements by getRawData
--nosqlrawdata			                                                Avoid getRawData
--localizationfile [EXTRA_LOCALIZATION_FILENAME]					          Use [EXTRA_LOCALIZATION_FILENAME] as localization file, the file name format has to be:
--localizationstrings												                        Show internal labels together the strings of selected localization
--swaudit-pdf FILE_WITH_CLIENT_IDS_EACH_IN_A_LINE [OUTPUT_PATH]		  export pdf swaudit reports for given clients (if no [OUTPUT_PATH] given, use home directory)
--swaudit-csv FILE_WITH_CLIENT_IDS_EACH_IN_A_LINE [OUTPUT_PATH]     export csv swaudit reports for given clients (if no [OUTPUT_PATH] given, use home directory)

If the opsiconfd does not work on the default port 4447, it should be specified on the start of the opsi-configed (host:port).

3.1.1. Logging of the 'opsi-configed'

By default, the 'opsi-configed' uses its log level 3 "Info". The level can be raised to 4 "Check" or 5 "Debug".

To change the log level the command line option --loglevel [LEVEL] can be used. It is not recommended to set level 5 as long as not the start process needs to be inspected. For, with level 5, the produced log file is very large; it is difficult to get loaded and viewed. When the 'opsi-configed' is running and a potential error situation is expected the log level can be raised via the menu entry Help/ConfigEditor log level.

Level 4 can be helpful since with it, the service calls are logged. With luck, level 5 offers a detailled view of actions.

Since version the logfiles are deposed by default in the user home directory. In Windows the folder

c:\Users\[User name]\AppData\Roaming\\log

In Linux the default logfiles folder is the (hidden) subfolder ".configed" in the user home directory.

The current logfile is named configed.log, the up to 3 preceding versions are configed_0.log, configed_1.log, configed_2.log.

The logging directory can be changed via the command line option "-d".

The current logfile path is displayed at the Help menu, entry "Current logfile". The filename can there be retrieved in order to use it in an open file dialog of a viewer program or can be directly opened by the default application for .log files.

3.1.2. Choosing the language

The 'opsi-configed' tries to use the language following the OS defined locale. If the matching translation file is missing English is used as default language. If terms in translations file are missing the expressions of the Englisch translation are used as default.

When calling the 'opsi-configed' you can set a locale via the command line option

-l resp. --locale

On principle, the locale has the format language_region, each component with two characters, eg. en_US of de_DE. It suffices to give the two character language code since there no region specific variants prepared.

In a running 'opsi-configed' the language can be switched via the menu item File/International. A change triggers a re-initialization of the program with a (nearly complete) rebuilding of the visual components in the new language.

Finally the call parameter


can be used for directly prescribing a localiziation file. The additional parameter


has the effect that the display of the localized expressions is combined with displaying the terms for which expressions should be given. This can be used for producing and testing a localization file.

3.1.3. Logging of the 'opsi-configed'

By default, the 'opsi-configed' uses its log level 3 "Info". The level can be raised to 4 "check" or 5 "debug".

To change the log level the command line option --loglevel [LEVEL] can be used. It is not recommended to set level 5 if not already the start process has problems since, with level 5, the produced log file is very large; it is difficult to view. When the 'opsi-configed' is running and a potential error situation is expected the log level can be raised via the menu entry Help/ConfigEditor log level.

Level 4 can be helpful since with it, the service calls are logged. Level 5 often offers a detailled view of actions.

By default the logfiles are deposed in the user home directory in the subfolder ".configed". The current logfile is named configed.log, the up to 3 preceding versions are configed_0.log, configed_1.log, configed_2.log.

In newer versions of windows the user home directory is interpreted as


Observe that the Windows Explorer shows a localized version of "users" and does not give "AppData" in the listing of "c:\users\[USERNAME]". But the AppData folder contents appear, when "appdata" is supplemented to its superfolder name.

The logging directory can be changed via the command line option "-d". The opsi product opsi-configed uses this option to set the logging directory to


But only local administrators can write to this location. If other users start the 'opsi-configed' the location


will therefore again be used.

3.2. Login

opsi-configed: login mask
Figure 3. 'opsi-configed': login mask

The 'opsi-configed' tries to connect to the opsi server via https. The login is done with the given parameters 'opsi server[:Port]' (default port 4447 – opsiconfd) and the user/password pair of the 'opsi-configserver' account. For a successful login the provided user has to be a member of the unix group 'opsiadmin'.

In the local user profile, the 'opsi-configed' saves certain session info in order to rebuild the essential working context after a restart, in particular a selected client group. Since version 4.0.7 the session data is used to produce a selection list of opsi servers to which you were connected (e.g. a productive one and a second one for experimental purposes). The last server used gets the highest place, and can be directly used again.

The gzip compression in HTTP protocol reduces the amount of data being transferred at the expense of an extended processing time, this is due to the fact that the data must be compressed and uncompressed. It has been observed that the reaction times tend to be shorter without compression in the local network, as the effects normally surpass the prolonged processing time. For transmissions over the WAN, it tends to be the opposite. In the practice, little difference is noticed on LAN connections, but relevant differences are noticed on WAN connections, so the Gzip option is enabled by default.

The feature 'check which clients are reachable' runs in the background and shows the results in the client table. It can be enabled from the login screen mask or via command line parameter. The default refresh interval is 0 min (= deactivated). It should be observed though that a too short refresh interval produces a lot of network waiting states which can slow down the opsi server.

3.3. Copy & Paste, Drag & Drop

You may copy the selected entries from nearly every section of the 'opsi-configed' to the clipboard using the standard key combinations ('Ctrl-Insert', 'Ctrl-C'). This may be used to transfer interesting data to other programs.

For most of the tables you may also use 'Drag & Drop' to copy the data e.g. to 'Excel' or a

3.4. opsi-configed modes Client configuration / server configuration / license management

To switch between the different usage modes of the 'opsi-configed', use the buttons in the upper right corner of the 'opsi-configed' frame. Since version 4.0.4, there are six buttons.

opsi-configed: Button bar
Figure 4. opsi-configed: Usage modes

The first three buttons allow you to change the editing target of the main window: client configuration, server configuration. On the other hand, each of the buttons 'group actions', 'product actions' and 'license management' starts a special window to manage the specific objects or actions.

These windows can as well be opened via the main menu item 'windows' (since 'opsi-configed' version 4.0.7).

3.5. Depot selection

All opsi-depotservers that are integrated with your server, are listed in the upper left corner of the 'opsi-configed'. By default the depot on your 'opsi-configserver' is selected and the clients belonging to this 'opsi-depot' are shown.

You can select multiple Depots at the same time and edit their clients together. However, only the selected depots are synchronized with each other. Trying to edit clients from asynchronous depots together will be rejected with an appropriate warning and the corresponding error message.

As of version 4.0.5, there is no need to carry out a complete data-reload when switching to a different depot-server, that means, when you select a depot its data is loaded immediately. In addition, there are the following buttons:

  • (=+) : Marks all depots with identical product stocks.

  • (++) : Marks all depots (you can also use Ctrl-a)

opsi-configed: depot selection
Figure 5. 'opsi-configed': depot selection

3.6. Cient selection

After a successful login, the main window pops up and shows the tab 'Client selection'. This tab shows a list of known clients from the selected 'opsi-depot' resp. the clients which are selected using the 'tree view control' on the left side of the 'opsi-configed'.

Since version 4.0.4, the 'opsi-configed' saves on the local machine, for the current user, the current depot server and group selection. If the 'opsi-configed' is restarted, you can continue working at the point where you were.

Please note, that group selection is preserved when changing depot selection. In order to see all clients in the other depot the group selection has to be changed appropriately. the same pattern of work.

opsi-configed: client selection mask
Figure 6. 'opsi-configed': client selection mask

You may select a line of the list not only by manual scrolling and selecting but also by a String search. This requires that you enter a String into the search field at the top of the list

How the search works is determined by the selected elements in two drop down lists:

Via field selection you can choose if

  • all fields (more precisely, all fields that are for this temporary configuration represented as columns) are searched (default), or

  • only one field (and which one) is searched.

Concerning the method of search you may select between the options (since 4.0.7):

  • Full-text: the search string is used in a similar way to a web search on a certain search engine for example in the standard manner; i.e., if the input contains several keywords (delimited by blanks) then the word elements will be a match if any of the input parts are fully contained in some of the columns.

  • Full-text (complete string): the search string is used like using a web search on a search engine the search string embraced by citation marks; i.e. a table line will match if the complete input string is part of one of the columns content.

  • Start-text search: a table line will be a match if the column text starts with the search string.

  • Regular expression: the search string is interpreted as a so called regular expression; i.e., a line will be a match if the input string produces a match according to the rules of regular expressions (as described in the java doc for java.util.regex.Pattern).

The enter key produces the next search hit. If there is no match it advances the mark to next line.

More selection functions based on String search are shown in the context menu of the search field.