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).
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.
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:
-
Basic installation of the server
-
Configuration of the server (adaptation to network conditions, setting up users and passwords, installation of products to be distributed)
-
Recording and integration of computers in opsi.
-
Deploying Windows to Clients.
-
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 |
|
Debian 10 Buster |
|
Debian 9 Stretch |
|
Ubuntu 22.04 LTS Jammy Jellyfish |
|
Ubuntu 20.04 LTS Focal Fossa |
|
Ubuntu 18.04 LTS Bionic Beaver |
|
Ubuntu 16.04 LTS Xenial Xerus |
|
RHEL 9 |
|
RHEL 8 |
|
RHEL 7 |
|
CentOS 8 |
|
CentOS 7 |
|
Alma Linux 9 |
|
Alma Linux 8 |
|
Rocky Linux 9 |
|
Rocky Linux 8 |
|
SLES 15 SP4 |
|
SLES 15 SP3 |
|
SLES 15 SP2 |
|
SLES 15 SP1 |
|
SLES 12 SP* |
|
SLES 12 |
|
openSuse Leap 15-4 |
|
openSuse Leap 15-3 |
|
openSuse Leap 15-2 |
|
openSuse Leap 15-1 |
|
openSuse Leap 15 |
|
UCS 5.0 |
|
UCS 4.4 |
: Supported
: Unsupported
: Under development
: 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.
see also:
* https://en.wikipedia.org/wiki/Hostname
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 fileopsivm.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 youropsivm.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:
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!
|
Fill in the configuration information for your network and answer the questions.
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)
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
-
Change into the directory
gui
in the file manager of your desktop environment and execute the installeropsi_quick_install_project
, e.g. with a double click. -
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.
Figure 5. Choose the language and a setup type. -
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.Figure 6. Hover the mouse over the small icon to display more information. -
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. -
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.
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
.