Copyright

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.

1. Introduction

These instructions explain in detail the installation and starting of an opsi-server. It starts from the provided installation package and leads to the test installation of a client.

The installation and commissioning of an opsi-server is done in several steps:

  1. Basic installation of the server

  2. Configuration of the server (adaptation to network conditions, setting up users and passwords, installation of products to be distributed)

  3. Recording and integration of computers in opsi.

  4. Deploying Windows to Clients.

  5. Packaging and distribution of own software

Then an operating system including software can be automatically installed on a client and a hardware and software inventory can be performed.

Further features are described in the opsi manual. There, you will also find explanations about the co-financed extensions and their setup.

The shown network configuration is exemplary and refers to a network without competing DHCP servers (e.g. an isolated test network in which the opsi-server and its clients can be placed for the first tests).

We strongly suggest that you make your first tests with opsi in a test network that is separate from other DHCP servers, but which you can temporarily connect to your main network, e.g. to download updates and packages from the Internet.

For the integration into existing networks you can use consulting services by uib.

1.1. Conventions of this document

Commands are highlighted separately:

this is a command

During installation and configuration, you can usually copy and execute the commands from these fields one after the other using copy & paste from this document.

2. Requirements

Subsequently the requirements for the installation of an opsi-server will be described.

2.1. Supported distributions for server

Distribution

Opsi 4.2

Debian 11 Bullseye

supported

Debian 10 Buster

supported

Debian 9 Stretch

discontinued

Ubuntu 22.04 LTS Jammy Jellyfish

supported

Ubuntu 20.04 LTS Focal Fossa

supported

Ubuntu 18.04 LTS Bionic Beaver

supported

Ubuntu 16.04 LTS Xenial Xerus

unsupported

RHEL 9

supported

RHEL 8

supported

RHEL 7

unsupported

CentOS 8

discontinued

CentOS 7

unsupported

Alma Linux 9

supported

Alma Linux 8

supported

Rocky Linux 9

supported

Rocky Linux 8

supported

SLES 15 SP4

supported

SLES 15 SP3

supported

SLES 15 SP2

supported

SLES 15 SP1

supported

SLES 12 SP*

unsupported

SLES 12

unsupported

openSuse Leap 15-4

supported

openSuse Leap 15-3

discontinued

openSuse Leap 15-2

discontinued

openSuse Leap 15-1

discontinued

openSuse Leap 15

discontinued

UCS 5.0

supported

UCS 4.4

supported

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

2.2. Hardware requirements

For an opsi-server on real hardware is needed:

  • x86-64 or ARM64 system.

  • At least 2GB RAM

  • At least 2 CPU cores

  • Disk space requirements depend heavily on the number of opsi packages. For productive systems the following applies:

    • There should always be at least 15GB of free space in the '/tmp' directory.

    • The directory '/var/lib/opsi' should have at least 60GB and should be flexible expandable.

How many opsi clients access an opsi server at the same time depends on the configuration and the daily routines in the respective environment. In large environments, with many simultaneous client connections, the RAM and CPU requirements can increase significantly.

The central opsi service 'opsiconfd' needs about 250MB RAM per worker process. There should be about one worker process available for 20 simultaneous connections. The number of CPU cores should be about half the number of worker processes.

In the standard configuration, additional resources for Samba, MySQL and Redis should be planned on the same system.

2.2.1. Notes on determining hardware requirements

Hardware requirements depend heavily on usage. So here are a few tips to calculate the system requirements.

Memory requirements

Each active Samba connection starts its own Samba process. Estimates vary between 800 kB and 4 MB. How many opsi clients access an opsi server at the same time depends heavily on the daily routines in your environment.

The following values ​​were recommended for Samba 3:

Process

1 user

130 users

500 users

smbd

4 MB

520 MB

2000 MB

Since we do not have any values ​​for current Samba versions, the above figures can only be regarded as a rough estimate and should be extended with a safety margin of 50%.

The memory consumption of opsiconfd depends heavily (but not only) on the number of clients. The following minimum memory consumption can be derived from existing installations. The specified number of users are not active users at the same time, but the total number.

Process

100 users

2000 users

4000 users

opsiconfd

500 MB

1000 MB

2000 MB

You should also implement a safety margin here.

CPU

Opsiconfd currently uses only one core. This core is only fully loaded when many opsi clients (> 100) access the server exactly at the same time. But the operating system, Samba, the database, etc. also require computing time.

I.e. with 500 clients two CPU cores should be sufficient, with 1000 clients four CPU cores should be provided.

Also note that opsi-depots put a strain on the opsi-configserver, which is significantly larger than that of a single client.

2.3. Configuration requirements

Your server and your network have to comply to the following requirements to install and work with opsi:

2.3.1. Valid DNS domain name

Your DNS domain name must consist of at least one domain and one toplevel domain. In other words: the fully qualified domain name must contain at least one point. Furthermore, the toplevel domain must consist of at least two characters.

Valid domain names are e.g.: 'domain.local' , 'uib.de', 'subdomain.domain.de'. An invalid example: 'mydomain.d' because this is only one character at the top-level domain An invalid example: 'mydomain' because this is only a top-level domain

see also:

2.3.2. Valid DNS hostname

The hostnames (also of the clients) must comply with the guidelines. This includes, for example, that they must not contain any underscores.

Make sure that at your opsi-server, returns a 'fully qualified domainname', in which at least come two dots, e.g. 'opsiserver.domain.local':

hostname -f

Should the result not look like this (e.g. '127.0.0.1' or 'localhost') then you check your '/etc/hosts' directory or the name resolution first.

2.3.3. Correct name resolution for the server

Check the entry for the opsi-server in the file '/etc/hosts', or check the output of:

getent hosts $(hostname -f)

The result should look like the following example:
'192.168.1.1 server.domain.tld server'

Here the IP address should belong to the network interface, to which the Clients will be connecting.

If the result looks different from the above example (contains eg. '127.0.0.1' or 'localhost'), or the full qualified hostname does not contain one or more dots, then you must correct your name resolution (DNS or /etc/hosts file).

The names must be in accordance of the rules of a DNS system but a DNS server is not required for the usage of opsi.
opsi does not require Active Directory or similar. Integrating opsi is possible but not required.

2.3.4. Localization settings

opsi requires configured language settings ('locale') on the server. It is recommended to use an UTF-8 compatible locale.

The following command performs a simplified check:

test -e /etc/default/locale && echo "ok" || (echo "Check locales:" && locale)

If the output is ok locales are set. If the output is check locales: you should check if the following list has settings for LANG or LC_ALL that are according to your used language.

For English we recommend en_GB.UTF-8 or en_US.UTF-8.

The following commands show how these settings can be changed if nothing or an undesired value is set:

sudo locale-gen en_GB.UTF-8
update-locale LANG=en_GB.UTF-8

To apply these settings systemwide the server should be restarted.

For more information please consult the documentation of your Linux distribution.

2.4. Needed network ports

This is an overview of the used ports and network protocols.

Config server = central opsi-server to manage all clients.
Depot server = opsi-server in the individual locations.
If there is only one opsi-server, it takes both roles.

  • opsi-server web service: 4447/tcp +. Client to config and depot server, depot server to config server, also connections via localhost.

  • opsi-client web service: 4441/tcp
    Config server to client, connection from client to itself via localhost.

  • opsi-client Notifier: 45000-45099/tcp
    Connection from client to itself via localhost.
    A random port from the given range is selected.

  • TFTP: 69/udp
    Connection from the client to the depot server.

  • TFTP: 1024-65535/udp
    Connection from the depot server to the client.

  • CIFS/SMB: 445/tcp
    Client to depot server.

  • CIFS/SMB: 445/tcp + connection from Depot server to client.
    Only necessary if opsi-deploy-client-agent (winexe, smbclient) is used for Windows clients.

  • Grafana web service: 3000/tcp
    Connection from client to config server.
    Only if the management web page of the config server is to be accessed from the client.

  • SSH: 22/tcp
    Connection from client to Config server.
    Management access to Config and Depot server.

  • SSH: 22/tcp
    Connection from depot server to client.
    Only necessary if opsi-deploy-client-agent is used for Linux / MacOS clients.

  • DNS: 53/tcp, 53/udp +. All servers / clients must be able to reach your DNS.

  • Wake-on-LAN (WoL): 7/udp, 9/udp, 12287/udp
    Connection from config server to client. These ports are configurable.

  • HTTP: 80/tcp
    Config and depot server to the Internet.
    To load e.g. server updates from http://download.opensuse.org.

  • HTTPS: 443/tcp + Config and depot server to the Internet. Config and depot server to the Internet.
    To load e.g. packages from https://download.uib.de (opsi-package-updater).

2.5. Proxy settings

If a HTTP-proxy is used, the proxy settings should be configured system-wide using environment variables. These environment variables are usually stored in the /etc/environment file. The following environment variables should be created, all lowercase.

2.5.1. http_proxy

The environment variable http_proxy configures which proxy should be used for HTTP connections. A complete URL should be used, not only hostname and port. If the proxy requires authentication, this can be specified in the URL.

http_proxy=http://<user>:<password>@<proxy-address>:<port>

Example: http_proxy=http://10.10.10.10:3128

2.5.2. https_proxy

Like http_proxy, but for HTTPS connections.

Example: https_proxy=https://10.10.10.10:3128

2.5.3. no_proxy

The environment variable no_proxy defines for which addresses no proxy should be used. Multiple addresses are separated by commas. The following rules should be observed for the individual addresses: * Use lower case throughout. * Only IP addresses should be used if access is also made directly to the IP address. No name resolution takes place when evaluating the exceptions. * No IP address ranges (CIDR matching, such as: 192.168.0.0/24) may be used. * Exceptions must also be defined for local addresses and loopback addresses, such as localhost and 127.0.0.1. * No wildcards, such as * or regular expressions, may be used. * Each name is evaluated as a suffix, so domain.com defines an exception for all hostnames ending with domain.com. * For each address, optionally, a port can be specified after a colon. Then the exception applies only to the specified port.

Example: no_proxy=127.0.0.1,localhost,mydomain.example,hostname.domain.com:8080.

3. opsi-server Installation

This chapter describes the installation and configuration of an opsi server.

After you have worked through this chapter, you have a functioning opsi server. This serves as a basis for all further chapters.

In the following chapters we assume that you have a working network configuration on your server.

3.1. opsi-server Basic installation

In this section different variants of the installation of an 'opsi-server' are shown. You will end up with a server system ready for final configuration and commissioning. To evaluate opsi we recommend using the pre-installed virtual machine. Otherwise, you should select the operating system you are most familiar with. In this case please make sure that the packages of the server are up to date.

If a proxy server is used in your network to access the Internet, remember to enter this on your opsi-server as well. In particular the environment variables http_proxy and https_proxy.

In case of problems you can check the free support provided by the community.

3.1.1. Starting up the uib preconfigured Virtual Machine

An 'opsi-server' can be installed as a virtual machine, because the load on the system is low. A ready-to-use and pre-configured virtual machine is provided by uib. You can download the VMware or Virtualbox files from the uib website or opsi.org. The free of charge VMware player or Virtualbox is sufficient to run this machine. You may also use VMware server or ESXi.

First Start

VMware

If you have a server running VMware or VMware player, it only takes a few mouse clicks to install a base 'opsi-server':

  • Download the opsi server VM from opsi.org

  • Unzip the file and a directory 'opsivm' will be generated.

  • Start VMware player. Open "Open a Virtual Machine", look for the directory opsivm and in it the file opsivm.ovf in its file selection dialog. You may have to change the file types to be displayed to ovf. You can now import the server under its own name. The virtual server can then be started.

ESXi-Server

  • Download the opsi server VM from opsi.org

  • Unzip the file and a directory 'opsivm' will be generated.

  • Start vSphere Client.
    Install a new client with 'File' / 'Deploy OVF Template…​.' and answer the next questions.

Virtualbox

  • Download the opsi server VM from opsi.org

  • Unzip the file and a directory 'opsivm' will be generated.

  • Start Virtualbox.
    At the menu 'File' / 'Import Appliance' select your opsivm.ovf file and import it.

General

The VMware player is free of charge and available for all common operating systems at vmware.com. Usually it can be installed without any problems, as long as the resources of the host computer (especially memory) meet the needs of running software systems in parallel.

Language selection

The first step is to choose the preferred language:

Screenshot: Language selection
Figure 1. Language selection
First boot

The opsi-server needs to be connected to the Internet to work properly. The script 1stboot.py will automatically start at the first boot in order to configure the opsi-server network settings. If something goes wrong while running '1stboot.py', then you may run 1stboot.py again from the command line.

The log file of 1stboot.py is located at /var/lib/1stboot/1stboot.log.

You cannot use 1stboot.py to rename your 'opsi-server' afterwards!
Screenshot: 1stboot.py Startup mask
Figure 2. Startup mask

Fill in the configuration information for your network and answer the questions.

Screenshot: 1stboot Input mask
Figure 3. Input mask

In the following, you will be asked for:

server name

Name of this server (without domain) e.g. opsidemo

domain

DNS-Domain (not Windows-Domain) the name has to include a dot e.g. opsi.local

ip address

Address of this server e.g. 192.168.1.50

netmask

Netmask of this server e.g. 255.255.255.0

windows domain

Name of the Windows Domain (not the DNS domain)

gateway

IP-address of the Internet gateway e.g. 192.168.1.1

proxy

If required for Internet access, the proxy information: e.g. http://myuser:mypass@192.168.1.5:8080

DNS server

IP address of the name server e.g. 192.168.1.1

mail relay

IP address of the mail server e.g. 192.168.1.1

tftp server

IP address of the tftp server (usually the server)

Password of root

Password of root

Password of adminuser

Password of local opsi-admin.

After the program '1stboot.py' finishes, the virtual machine will be rebooted.

Second Start

After the reboot, or after completing the network configuration, login as 'adminuser' with your password.

The graphical user interface of the opsi-server should have already started (a lightweight window manager is used). A "Firefox" browser window appears at startup, and displays this document and further information.

If you get a message that there is no network connection, this might be caused by the special configuration of the virtual appliance. Before trying other options, you should reboot the server again. (i.e. use the shutdown button in the GUI)

Screenshot: View of newly started opsi-server
Figure 4. Graphical view of fresh started opsi-server

If the network was correctly configured in the previous steps, then you should be able to remotely access the opsi-server, for example:

  • use 'ssh' at the command line to access the server ('ssh' should already be installed on linux systems, for Windows use putty)
    Use 'root' as the user name, and authenticate with the root password.

Terminal Window

In the following sections, some commands have to be entered into a command line interface. It may be the easiest way to work through these instructions.

The commands are input into a window called a "terminal window". Here are examples that explain how to access a terminal window:

  • Remote access per ssh on the opsi-server (see previous section)

  • Open a terminal window in the opsi-server graphical interface with a click on the terminal icon in the icon bar.

  • Open a terminal window in the opsi-server graphical interface with a right mouse click inside the interface, and choose "Terminal".
    Note: the graphical interface has multiple desktops that are reachable using the variety of buttons in the upper-left-hand corner of the display.

We recommend cutting and pasting commands from this handbook directly into the opsi-server terminal window (most applications support cut and paste).

Example snippets from configuration files are formatted like this:

depoturl = smb://smbhost/sharename/path

Example snippets for commands that you have to execute are formatted like this:

cd /tmp
ls -l

Angle brackets '< >' mark abstract names. When entering commands, please replace the '<abstract name>' with a real name.
For example: The file share, where opsi places the software packages, may abstractly be noted as '<opsi-depot-share>'. If the real file share is /var/lib/opsi/depot, then you have to replace the abstract name by this exact string. The location of the package '<opsi-depot-share>/ooffice' becomes /var/lib/opsi/depot/ooffice. .

Check the Network Connection

If the network configuration is correct, and the computer is connected to the Internet, then you can access any website using the browser in the start window.

If not everything is working, then you have to open a terminal window (maybe this is not yet possible from a remote connection, only from the server GUI) and then perform the necessary network connection checks and fixes.

You can re-enter the network configuration by entering this command in the terminal window:

1stboot.py

A reboot is forced with the command:

reboot

If the network connection works, then you can install opsi packages or update them, and configure the environment for the first installation test. If you want to use the virtual machine (and not install the opsi-server directly to your host system), then skip to Update and Configuration of the opsi-server.

Update the opsi-Server

To update your opsi-server you need to double click the Icon 'Update OS' on the desktop. To do this please enter the current password for the adminuser and confirm if necessary.

If necessary for your Internet access, adapt the file /etc/apt/apt.conf to your network circumstances (enter correct proxy or comment / delete line). You can edit these using the program any text editor for example, 'midnight commander':

mcedit /etc/apt/apt.conf
Install the standard opsi-products

By performing a double click the Icon 'First package installation' the minimal opsi-products will be installed. To do this please enter the current password for the adminuser. This automatically fetches the current opsi packages, including templates for OS deployments, from the opsi repositories and installs them on the server.

For more information see Importing the minimal opsi products.

Starting opsi-Server Interface

You can start the management interface by double clicking on the icon 'Opsi Configuration Editor'. For a description of the management interface check Installation of the management interface opsi-configed.

You have a running opsi server now, i.e. the opsi application itself is fully configured.

You can now proceed with:

3.1.2. opsi QuickInstall

opsi QuickInstall is a program to quickly and easily install an opsi-server on a Linux system—​via a graphical setup tool or on the command line.
You can find our supported Linux distributions here: Supported Linux Distributions

Preparations

First, make sure that the opsi-server has a valid DNS hostname. To do this, either check the entries in the /etc/hosts file or enter the following command:

getent hosts $(hostname -f)

The result should look like this for example:

192.168.1.1 server.domain.tld server

The output on your system should show the server’s IP address to which the opsi clients connect later on. It’s followed by the associated hostname, and the third field contains an optional alias (here: server), under which the computer can also be reached.

The file may look different on your distribution. If it contains only entries for 127.0.0.1 or localhost, edit the file /etc/hosts in the text editor of your choice. For the opsi-server, enter at least the IP address and the full host name, optionally an alias.

Download opsi QuickInstall

opsi-QuickInstall can be found on our servers under the following link: https://download.uib.de/opsi4.2/stable/quickinstall/

Download the zip file to your computer and unpack it, for example using this command on the shell:

unzip opsi-quick-install.zip

Alternatively unpack the archive via the file manager of your graphical desktop environment (right click / Unpack here). You can install opsi QuickInstall wither with a graphical user interface or via the command line. The next two sections explain both ways.

The installer asks for so-called properties. For more information, please read the chapter on The product l-opsi-server. Here you can also find the default values of the properties. Note that for opsi QuickInstall the default for allow_reboot is set to false.
opsi QuickInstall: Graphical Setup Program
  1. Change into the directory gui in the file manager of your desktop environment and execute the installer opsi_quick_install_project, e.g. with a double click.

  2. In the following dialog box, select the language for the setup program from the upper drop-down menu. Choose the setup type as well. If you select Custom, then you can make more detailed settings.

    Screenshot: Choose the language and a setup type.
    Figure 5. Choose the language and a setup type.
  3. Click on next > and fill in the dialogs.

    Next to some fields you will find an i icon, which displays a tooltip with more information about the related topic.
    Screenshot: Hover the mouse over the small icon to display more information.
    Figure 6. Hover the mouse over the small icon to display more information.
  4. In the last dialog window you fill in the fields opsi admin user and opsi admin password, among other things.

    Be sure to choose a name other than the one shown in this example (Figure 6) and choose a strong password and not the one shown in this example.
  5. Click Overview to double-check your settings. If everything is correct, click finish, enter your password and confirm by clicking finish again. After that the opsi-server installation will start.

Screenshot: The opsi-server installation is running.
Figure 7. The opsi-server installation is running.

The installation may take a few minutes. When it’s finished, opsi QuickInstall will tell you if it was successful. If you see the message success, then your opsi-server is configured and ready for operation. You can now start with the installation of opsi products.

If you see a dialog like in Figure 8 instead, please check the log files for error messages. You can find the logs in the two files /var/log/opsi-quick-install-l-opsi-server.log and /tmp/opsi_quickinstall.log.