Administrator Guide Obs Admin

User Manual: Pdf

Open the PDF directly: View PDF .
Page Count: 117

Download
Open PDF In Browser	View PDF

Administrator Guide

Administrator Guide: Open Build Service
by Karsten Keil

Publication Date: 01/29/2018
SUSE LLC

10 Canal Park Drive
Suite 200

Cambridge MA 02141
USA

https://www.suse.com/documentation
Copyright © 2016
Copyright © 2006– 2018 SUSE LLC and contributors. All rights reserved.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or (at your option) version 1.3; with the Invariant Section being this copyright
notice and license. A copy of the license version 1.2 is included in the section entitled “GNU Free Documentation
License”.
For SUSE trademarks, see http://www.suse.com/company/legal/ . All other third-party trademarks are the property of their respective owners. Trademark symbols (®, ™ etc.) denote trademarks of SUSE and its affiliates.
Asterisks (*) denote third-party trademarks.
All information found in this book has been compiled with utmost attention to detail. However, this does not
guarantee complete accuracy. Neither SUSE LLC, its affiliates, the authors nor the translators shall be held liable
for possible errors or the consequences thereof.

Contents

About this Guide vi
1
1.1

Installation and Configuration 1
Planning 1

Resource Planning 1

1.2

Simple Installation 2
Back-end Installation 2 • Front-end Installation 5 • Online
Configuration 8

1.3

Worker Farm 11

1.4

Distributed Setup 11

1.5

Monitoring 14
Endpoint Checks 14 • Common Checks 15 • Other Checks 17

2
2.1

File System Overview 18
Configuration Files 18
Front-end Configuration 18 • Back-end Configuration 26

2.2

Log Files 47
Front-end 47 • Back-end 47

2.3

/srv/obs Tree 48
build Directory 48 • cloudupload Directory 49 • db

Directory 49 • diffcache Directory 49 • events
Directory 49 • info Directory 50 • jobs Directory 50 • log
Directory 50 • projects Directory 50 • remotecache
Directory 50 • repos Directory 50 • repos_sync
Directory 50 • run Directory 51 • sources Directory 51 • trees
Directory 51 • upload Directory 51 • workers Directory 51

iii

Administrator Guide

2.4

Metadata 52
OBS Revision Control 52 • Project Metadata 53 • Package
Metadata 55 • Attribute Metadata 55 • Job Files 56

3
3.1

Administration 58
Tools 58
obs_admin 58 • osc 61

3.2

Managing Build Targets 64
Interconnect 64 • Importing Distributions 65

3.3

Source Services 68
Using Services for Validation 69 • Different Modes When Using
Services 69 • Storage of Source Service Definitions 70 • Dropping a
Source Service Again 71

3.4

Dispatch Priorities 71
The /build/_dispatchprios API Call 72 • dispatch_adjust Array 73

3.5

Publisher Hooks 74
Configuring Publisher Hooks 74 • Example Publisher Scripts 76

3.6

Unpublisher Hooks 77
Configuring Unpublisher Hooks 78 • Example Unpublisher Scripts 79

3.7

Managing Users and Groups 81
User and Group Roles 81 • Standalone User and Group
Database 81 • Proxy Mode 82 • LDAP/Active
Directory 83 • Authentication Methods 89

3.8

Message Bus for Event Notifications 91
RabbitMQ 91

3.9
3.10

4

iv

Backup 99
Spider Identification 99

Troubleshooting 102

4.1

General Hints 102

4.2

Debugging Front-end Problems 103

Administrator Guide

A

v

GNU Licenses 104

A.1

GNU General Public License 104

A.2

GNU Free Documentation License 106

Administrator Guide

About this Guide
This guide is part of the Open Build Service documentation. These books are considered to
contain only reviewed content, establishing the reference documentation of OBS.

This guide does not focus on a specific OBS version. It is also not a replacement of the documentation inside of the openSUSE Wiki (https://en.opensuse.org/Portal:Build_Service) . However, content from the wiki may be included in these books in a consolidated form.

1 Available Documentation
The following documentation is available for OBS:
Administrator Guide

This guide offers information about the initial setup and maintenance for running Open
Build Service instances.
Article “Beginnerʼs Guide”

This guide describes basic workflows for working with packages on Open Build Service.

This includes checking out a package from an upstream project, creating patches, branching a repository, and more.
Book “Best Practice Guide”

This guide offers step-by-step instructions for the most common features of the Open Build
Service and the openSUSE Build Service.
Book “Reference Guide”

This guide covers ideas and motivations, concepts and processes of the Open Build Service
and also covers administration topics.
Book “User Guide”

This guide is intended for users and developers who want to dig deeper into Open Build
Service. It contains information on backgrounds, setting up your computer for working
with OBS, and usage scenarios.

vi

Available Documentation

2 Feedback
Several feedback channels are available:
Bugs and Enhancement Requests

Help for openSUSE is provided by the community. Refer to https://en.opensuse.org/Porfor more information.

tal:Support
Bug Reports

To report bugs for Open Build Service, go to https://bugzilla.opensuse.org/ , log in, and
click New.
Mail

For feedback on the documentation of this product, you can also send a mail to doc-

team@suse.com . Make sure to include the document title, the product version and the

publication date of the documentation. To report errors or suggest enhancements, provide
a concise description of the problem and refer to the respective section number and page
(or URL).

3 Documentation Conventions
The following notices and typographical conventions are used in this documentation:
/etc/passwd : directory names and le names
PLACEHOLDER : replace PLACEHOLDER with the actual value
PATH : the environment variable PATH
ls , --help : commands, options, and parameters
user : users or groups
package name : name of a package
Alt

,

Alt

– F1 : a key to press or a key combination; keys are shown in uppercase as on

a keyboard

File, File Save As: menu items, buttons
Dancing Penguins (Chapter Penguins, ↑Another Manual): This is a reference to a chapter in
another manual.

vii

Feedback

Commands that must be run with root privileges. Often you can also prefix these commands with the sudo command to run them as non-privileged user.
root # command
geeko > sudo command

Commands that can be run by non-privileged users.
geeko > command

Notices

Warning: Warning Notice
Vital information you must be aware of before proceeding. Warns you about security
issues, potential loss of data, damage to hardware, or physical hazards.

Important: Important Notice
Important information you should be aware of before proceeding.

Note: Note Notice
Additional information, for example about differences in software versions.

Tip: Tip Notice
Helpful information, like a guideline or a piece of practical advice.

4 Contributing to the Documentation
The OBS documentation is written by the community. And you can help too!
Especially as an advanced user or an administrator of OBS, there will be many topics where

you can pitch in even if your English is not the most polished. Conversely, if you are not very
experienced with OBS but your English is good: We rely on community editors to improve the
language.

viii

Contributing to the Documentation

This guide is written in DocBook XML which can be converted to HTML or PDF documentation.
To clone the source of this guide, use Git:
git clone https://github.com/openSUSE/obs-docu.git

To learn how to validate and generate the OBS documentation, see the le README .
To submit changes, use GitHub pull requests:
1. Fork your own copy of the repository.
2. Commit your changes into the forked repository.
3. Create a pull request. This can be done at https://github.com/openSUSE/obs-docu

.

It is even possible to host instance-specific content in the official Git repository, but it needs to
be tagged correctly. For example, parts of this documentation are tagged as  . In this case, the paragraph will only become visible when creating the openSUSE ver-

sion of a guide.

ix

Contributing to the Documentation

1 Installation and Configuration
1.1 Planning
For testing an own OBS instance and for small setups like only packaging some scripts from

your administrators into RPMS and creating proper installation sources from them, the ready
to use obs-server appliance images are the easiest way. You can download them from http://
openbuildservice.org/download/

.

To use the OBS for your Linux software development with many packages, projects and users,

consider setting up an own installation. Depending on the number of users, projects, and architectures, you can split up the back-end (called partitioning) and have separate hosts for the
front-end and the database.

But for most installations it is still OK to run everything but workers one host with enough
resources.

For flexibility and if you want some kind of high availability it is recommended to use virtualization for the different components.

1.1.1

Resource Planning

Normally for a small to middle installation a setup with everything except workers on one host
is sufficient. You should have separate /srv volume for the back-end data, XFS as le system
is best choice.

For each scheduler architecture you should add 4 GB RAM and one CPU core. For each build
distribution you should add at least 50GB disk space per architecture.

A medium instance with about 50 users can easily run on a machine with 16GB RAM 4 cores

and 1 TB storage. The storage of course depend on the size of your projects and how often you
have new versions.

For bigger installations you can use separate networks for back-end communication, workers
and front-end.

1

Planning

The reference installation on build.opensuse.org with lot of users, distributions runs on a partitioned setup with:

a mysql cluster as database
api-server: 16GB RAM 4 cores 50GB disk
separate binary back-ends (scheduler, dispatcher, reposerver, publisher, warden)
source server 11 GB RAM, 4 cores, 3 TB disk (RAM used mainly for caching)
main back-end: 62 GB RAM (oversized), 16TB disk
lot of workers (see - https://build.opensuse.org/monitor )
For build time and performance the count and performance of available worker hosts more
important as the remaining parts.

1.2 Simple Installation
Simple installation means, all OBS services running on the same machine.

Important
It is very important that you read the README.SETUP le coming with your OBS version
and follow the instructions there, because here maybe changes to this version.

Before you start the installation of the OBS, you should make sure that your hosts have the
correct fully qualified hostname and DNS is working and can resolve all names.

1.2.1

Back-end Installation

The back-end hosts all sources and built packages. It also schedules the jobs. You need to install
the "obs-server" package for this. You need to check the /usr/lib/obs/server/BSConfig.pm le,
but the defaults should be good enough for the simple case.

You can control the different back-end components via systemctl. Basically you can enable/disable the service during booting the system and start/stop/restart it in a running system. For
more information, see https://www.freedesktop.org/software/systemd/man/systemctl.html#Commands

2

. For example, to restart the repository server use

Simple Installation

systemctl restart obsrepserver.service

TABLE 1.1: SERVICE NAMES

Component

Service Name

Remarks

Source Server

obssrcserver.service

Repository

Server obsrepserver.service

Source

Services obsservice.service

Download

obsdodup.service

since 2.7

Delta Storage

obsdeltastore.service

since 2.7

Scheduler

obsscheduler.service

Dispatcher

obsdispatcher.service

Publisher

obspublisher.service

Signer

obssigner.service

Warden

obswarden.service

The sequence in the table reflects the start sequence, you need to enable the services with
systemctl start 

rst and then you can start them:
systemctl start obssrcserver.service
systemctl start obsrepserver.service
systemctl start obsservice.service
systemctl start obsdodup.service
systemctl start obsdeltastore.service
systemctl start obsscheduler.service
systemctl start obsdispatcher.service
systemctl start obspublisher.service
systemctl start obssigner.service
systemctl start obswarden.service

3

Back-end Installation

Warning
The commands start services which are accessible from the outside. Do not do this on a

system connected to an untrusted network or make sure to block the ports with a firewall.

1.2.1.1

Cloud Upload Setup

In order to setup the Cloud Upload feature you will need to configure the tools required per each
cloud provider. Right now we only support the AWS Amazon Cloud (https://aws.amazon.com )
as provider.

1.2.1.1.1

How does the AWS's authentication work for uploading images?

We are going to use the role based authentication provided by Amazon to enable the OBS instance to upload images to other user's accounts.

The users will obtain an external ID (automatically created and unique) and the OBS account

ID to create an Identity and Access Management (IAM) role. After the user created the role, he
needs to provide the Amazon Resource Name (ARN) of the role to OBS. OBS will use this ARN
to obtain temporary credentials, therefore an uploader account is necessary which we need to

configure (see AWS authentication credentials setup). OBS will use the ARN to obtain temporary
credentials for the users account to upload the appliance. The ARN and the external ID are not
considered as a secret.

FIGURE 1.1: AWS AUTHENTICATION FOR ROLE BASED ACCESS

The whole workflow is described in the AWS documentation (https://docs.aws.amazon.com/IAM/
latest/UserGuide/id_roles_create_for-user_externalid.html)

4

.

Back-end Installation

1.2.1.1.2

AWS authentication credentials setup

For uploading images in AWS two tools are needed internally the aws CLI (https://aws.amazon.com/cli)

and the ec2uploadimg (https://github.com/SUSE/Enceladus/tree/master/ec2u-

tils/ec2uploadimg)

(those are installed as dependencies). For setting this up you have to con-

figure both tools in the machine where the cloud upload workers will be running.

The configurations are stored in /etc/obs/cloudupload (the clouduploader home directory). In

this directory there is a .ec2utils.conf le which contains e.g. the helper instance AMIs (see
this example (https://github.com/SUSE/Enceladus/blob/master/ec2utils/ec2utils.conf.example) ).

In the /.aws/credentials le the AWS credentials of the OBS account are stored (see this documentation (https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html)

1.2.2

).

Front-end Installation

You need to install the "obs-api" package for this and a MySQL server.

1.2.2.1

MySQL Setup

Make sure that the mysql server is started on every system reboot (use "insserv mysql" for permanent start). You should run mysql_secure_installation and follow the instructions.
Create the empty production databases:
# mysql -u root -p
mysql> create database api_production;
mysql> quit

Use a separate MySQL user (for example, obs ) for the OBS access:
# mysql -u root -p
mysql> create user 'obs'@'%' identified by 'TopSecretPassword';
mysql> create user 'obs'@'localhost' identified by 'TopSecretPassword';
mysql> GRANT all privileges ON api_production.*
TO 'obs'@'%', 'obs'@'localhost';
mysql> FLUSH PRIVILEGES;
mysql> quit

Configure your MySQL user and password in the "production" section of the api config: /srv/
www/obs/api/config/database.yml
Example:
# MySQL (default setup).

5

Versions 4.1 and 5.0 are recommended.

Front-end Installation

#
# Get the fast C bindings:
#

gem install mysql

#

(on OS X: gem install mysql -- --include=/usr/local/lib)

# And be sure to use new-style password hashing:
#

http://dev.mysql.com/doc/refman/5.0/en/old-client.html

production:
adapter: mysql2
database: api_production
username: obs
password: TopSecretPassword
encoding: utf8
timeout: 15
pool: 30

Now populate the database
cd /srv/www/obs/api/
sudo RAILS_ENV="production" rake db:setup
sudo RAILS_ENV="production" rake writeconfiguration
sudo chown -R wwwrun.www log tmp

Now you are done with the database setup.

1.2.2.2

Apache Setup

Now we need to configure the Web server. By default, you can reach the familiar web user

interface and also api both on port 443 speaking https. Repositories can be accessed via http
on port 82 (once some packages are built). An overview page about your OBS instance can be
found behind 'http://localhost'.

The obs-api package comes with an Apache vhost le, which does not need to get modified
when you stay with these defaults: /etc/apache2/vhosts.d/obs.conf
Install the required packages via
zypper in obs-api apache2 apache2-mod_xforward rubygem-passenger-apache2 memcached

Add the following Apache modules in /etc/sysconfig/apache2 :
APACHE_MODULES="... passenger rewrite proxy proxy_http xforward headers socache_shmcb"

Enable SSL in /etc/sysconfig/apache2 via

6

Front-end Installation

APACHE_SERVER_FLAGS="SSL"

For production systems you should order official SSL certificates. For testing follow the instructions to create a self signed SSL certificate:
mkdir /srv/obs/certs
openssl genrsa -out /srv/obs/certs/server.key 1024
openssl req -new -key /srv/obs/certs/server.key \
-out /srv/obs/certs/server.csr
openssl x509 -req -days 365 -in /srv/obs/certs/server.csr \
-signkey /srv/obs/certs/server.key -out /srv/obs/certs/server.crt
cat /srv/obs/certs/server.key /srv/obs/certs/server.crt \
> /srv/obs/certs/server.pem

To allow the usage of https API in Web UI code you need to trust your certificate as well:
cp /srv/obs/certs/server.pem /etc/ssl/certs/
c_rehash /etc/ssl/certs/

1.2.2.3

API Configuration

Check and edit /srv/www/obs/api/config/options.yml
If you change the hostnames/ips of the api, you need to adjust frontend_host accordingly. If
you want to use LDAP, you need to change the LDAP settings as well. Look at the Section 3.7,

“Managing Users and Groups” for details. You will nd examples and more details in the Section 2.1,
“Configuration Files”.

It is recommended to enable
use_xforward: true

as well here.
Afterwards you can start the OBS web api and make it permanent via
systemctl enable apache2
systemctl start apache2
systemctl enable obsapidelayed.service
systemctl start obsapidelayed.service
systemctl enable memcached.service
systemctl start memcached.service

Now you have you own empty instance running and you can do some online configuration steps.

7

Front-end Installation

1.2.3

Online Configuration

To customize the OBS instance you may need to configure some settings via the OBS API and
Web user interface.

First you should change the password of the Admin account, for this you need rst login as user
Admin in the Web UI with the default password "opensuse". Click on the Admin link (right top
of the page), here you can change the password.

After changing the Admin password, set up osc to use the Admin account for more changes.
Here an example:

osc -c ~/.obsadmin_osc.rc -A https://api.testobs.org

Follow the instructions on the terminal.

Warning
The password is stored in clear text in this le by default, so you need to give this le
restrictive access rights, only read/write access for your user should be allowed. osc

allows to store the password in other ways (in keyrings for example), refer to the osc
documentation for this.

Now you can check out the main configuration of the OBS:
osc -c ~/.obsadmin_osc.rc api /configuration >/tmp/obs.config
cat /tmp/obs.config



<p class="description">
The <a href="http://openbuildservice.org"> Open Build Service (OBS)</a>
is an open and complete distribution development platform that provides a
transparent
infrastructure for development of Linux distributions, used by openSUSE, MeeGo
and other distributions.
Supporting also Fedora, Debian, Ubuntu, RedHat and other Linux distributions.
</p>
<p class="description">
The OBS is developed under the umbrella of the <a href="http://
www.opensuse.org">openSUSE project<
/a>. Please find further informations on the <
a href="http://wiki.opensuse.org/openSUSE:Build_Service">openSUSE Project wiki
pages</a>.

8

Online Configuration

</p>
<p class="description">
The Open Build Service developer team is greeting you. In case you use your OBS
productive
in your facility, please do us a favor and add yourself at <
a href="http://wiki.opensuse.org/openSUSE:Build_Service_installations">
this wiki page</a>. Have fun and fast build times!
</p>

private
on
off
on
allow
off
on
off
on
off
on
on
on
unconfigured@openbuildservice.org
^home:.+
home projects

armv7l
i586
x86_64



Important
unlisted_projects_filter only admit Regular Expression (see RLIKE specifications of
MySQL/MariaDB for more information) and unlisted_projects_filter_description is part
of the link shown in the project list for filtering

You should edit this le according to your preferences, then sent it back to the server:
osc -c ~/.obsadmin_osc.rc api /configuration -T /tmp/obs.config

9

Online Configuration

If you want to use an interconnect to another OBS instance to reuse the build targets you can
do this as Admin via the Web UI or create a project with a remoteurl tag (see Section 2.4.2,
“Project Metadata”)




This project refers to projects hosted on the Build Service
[...]
Use openSUSE.org:openSUSE:12.3 for example to build against the
openSUSE:12.3 project as specified on the opensuse.org Build Service.

https://api.opensuse.org/public


You can create the project using a le with the above content with osc like this:
osc -c ~/.obsadmin_osc.rc meta prj openSUSE.org -F /tmp/openSUSE.org.meta

You also can import binary distribution, see Section 3.2.2, “Importing Distributions” for this.
The OBS has a list of available distributions used for build. This list is displayed to user, if they
are adding repositories to their projects. This list can be managed via the API path /distributions
osc -c ~/.obsadmin_osc.rc api /distributions > /tmp/distributions.xml

Example distributions.xml le:


SLE-12-SP1
SUSE:SLE-12-SP1
SLE-12-SP1
standard
http://www.suse.com/


x86_64



You can add your own distributions here and update the list on the server:
osc -c ~/.obsadmin_osc.rc api /distributions -T /tmp/distributions.xml

10

Online Configuration

1.3 Worker Farm
To not burden your OBS back-end daemons with the unpredictable load package builds can
produce (think someone builds a monstrous package like LibreOffice) you should not run OBS
workers on the same host as the rest of the back-end daemons.

Important
You back-end need to be configured to use the correct hostnames for the repo and source
server and the ports need to be reachable by the workers. Also, the IP addresses of the
workers need to be allowed to connect the services. (look at the /usr/lib/obs/server/BSConfig.pm::ipaccess array).

You can deploy workers quite simply using the worker appliance. Or install a minimum system
plus the obs-worker package on the hardware.

Edit the /etc/sysconfig/obs-server le, at least OBS_SRC_SERVER, OBS_REPO_SERVERS and
OBS_WORKER_INSTANCES need to be set. More details in the Section 2.1, “Configuration Files”.
start the worker:
systemctl enable obsworker
systemctl start obsworker

1.4 Distributed Setup
All OBS back-end daemons can also be started on individual machines in your network. Also,
the front-end Web server and the MySQL server can run on different machines. Especially for
large scale OBS installations this is the recommended setup.

A setup with partitioning is very similar to the steps of the simple setup. Here we are only
mention the differences to the simple setup.

Note
You need to make sure that the different machines can communicate via the network, it

is very recommended to use a separate network for this to isolate it from the public part.

11

Worker Farm

On all back-end hosts you need to install the obs-server package. On the front-end host you need
to install the obs-api package.

Important
Only one source server instance can be exist on a single OBS installation.
The binary back-end can be split on project level, this is called partitioning.
On one partition following services needs to be configured and run:
1. repserver
2. schedulers
3. dispatcher
4. warden
5. publisher

You do not need to share any directories on File System level between the partitions.
Here some example for partitioning:
1. A main partition for everything not in the others (host mainbackend)
2. A home partition for all home projects of the users (host homebackend)
3. A release partition for released software projects (host releasebackend)

The configuration is done in the back-end config le /usr/lib/obs/server/BSConfig.pm. Most
parts of the le can be shared between the back-ends.

Here the important parts of the mainbackend of out testobs.org installation:
[...]
my $hostname = Net::Domain::hostfqdn() || 'localhost';
# IP corresponding to hostname (only used for $ipaccess); fallback to localhost since
inet_aton may fail to resolve at shutdown.
my $ip = quotemeta inet_ntoa(inet_aton($hostname) || inet_aton("localhost"));
my $frontend = 'api.testobs.org'; # FQDN of the Web UI/API server if it's not $hostname
# If defined, restrict access to the backend servers (bs_repserver, bs_srcserver,
bs_service)
our $ipaccess = {

12

Distributed Setup

'127\..*' => 'rw', # only the localhost can write to the backend
"^$ip" => 'rw',

# Permit IP of FQDN

"10.20.1.100" => 'rw',

# Permit IP of srcsrv.testobs.org

"10.20.1.101" => 'rw',

# Permit IP of mainbackend.testobs.org

"10.20.1.102" => 'rw',

# Permit IP of homebackend.testobs.org

"10.20.1.103" => 'rw',

# Permit IP of releasebackend.testobs.org

'10.20.2.*' => 'worker',

# build results can be delivered from any client in the

network
};
# IP of the Web UI/API Server (only used for $ipaccess)
if ($frontend) {
my $frontendip = quotemeta inet_ntoa(inet_aton($frontend) || inet_aton("localhost"));
$ipaccess->{$frontendip} = 'rw' ; # in dotted.quad format
}
# also change the SLP reg files in /etc/slp.reg.d/ when you touch hostname or port
our $srcserver = "http://srcsrv.testobs.org:5352";
our $reposerver = "http://mainbackend.testobs.org:5252";
our $serviceserver = "http://service.testobs.org:5152";
#
our @reposervers = ("
http://mainbackend.testobs.org:5252,
http://homebackend.testobs.org:5252,
http://releasebackend.testobs.org:5252
");
# you can use different ports for worker connections
our $workersrcserver = "http://w-srcsrv.testobs.org:5353";
our $workerreposerver = "http://w-mainbackend.testobs.org:5253";
[...]
our $partition = 'main';
#
# this defines how the projects are split. All home: projects are hosted
# on an own server in this example. Order is important.
our $partitioning = [
'home:' => 'home',
'release' => 'release'
'.*'

=> 'main',

];
our $partitionservers = {
'home' => 'http://homebackend.testobs.org:5252',
'release' => 'http://releasebackend.testobs.org:5252',
'main' => 'http://mainbackend.testobs.org:5252',
};
[...]

13

Distributed Setup

On the other partition server you need to change "our $reposerver", "our $workerreposerver"
and "our $partition".

On all partition servers you need to start:
systemctl start obsrepserver.service
systemctl start obsscheduler.service
systemctl start obsdispatcher.service
systemctl start obspublisher.service
systemctl start obswarden.service

On the worker machines you should set of repo servers in the OBS_REPO_SERVERS variable.
You can also define workers with a subset of the repo servers to prioritize partitions.

1.5 Monitoring
In this chapter you will nd some general monitoring instructions for the Open Build Service. All
examples are based on Nagios plugins, but the information provided should be easily adaptable
for other monitoring solutions.

1.5.1

1.5.1.1

Endpoint Checks

HTTP Checks: Checking Whether the HTTP Server Responds

This check will output a critical if the HTTP server with ip address 172.19.19.19 (-I

172.19.19.19) listening on port 80 (-p 80) does not answer and output a warning if the HTTP

return code is not 200. The server name that will be used is server (-H server) which is important
if different virtual hosts are listening on the same port.

check_http -H server -I 172.19.19.19 -p 80 -u http://server

The same check, but this time it will check a ssl enabled HTTP server.
check_http -S -H server -I 172.19.19.19 -p 443 -u https://server

It is also possible to check the presence of a certain string in the HTTP response. In this case it
will check for the string Source Service Server.

14

Monitoring

check_http -s "Source Service Server" -S -H server -I 172.19.19.19 -p 5152

Open Build Service HTTP endpoints that should be checked:
1. Web Interface / API: port 443
2. Repository Server: port 82
3. Package Repository Server: port 5252
4. Source Repository Server: port 5352
5. Source Service Server: port 5152
6. Cloud Upload Server: port 5452

1.5.2

Common Checks

This is a list of common checks that should be run on each individual server.

1.5.2.1

Disk Space: Checking Available Disk Space

This check will output a warning if less than 10 percent disk space is available (-w 10) and

output a critical if less than 5 percent disk space are available (-c 5). It will check all le systems
except le systems with type none (-x none).
check_disk -w 10 -c 5 -x none

1.5.2.2

Memory Usage: Checking Available Memory

This check will output a warning if less than 10 percent memory is available (-w 10) and output
a critical if less than 5 percent memory is available (-c 5). OS caches will be counted as free

memory (-C) and it will check the available memory (-f). check_mem.pl is not a standard Nagios
plugin and can be downloaded at https://exchange.nagios.org/ .
check_mem.pl -f -C -w 10 -c 5

15

Common Checks

1.5.2.3

NTP: Checking Date and Time

This check will compare the local time with the time provided by the NTP server pool.ntp.org

(-H pool.ntp.org). It will output a warning if the time differs by 0.5 seconds (-w 0.5) and output
a critical if the time differs by 1 seconds (-c 1).
check_ntp_time -H pool.ntp.org -w 0.5 -c 1

1.5.2.4

Ping: Checking That the Server Is Alive

This plugin checks if the server responds to a ping request and it will output a warning if the

respond time exceeds 200ms or 30 percent package loss (-w 200.0,30%) and output a critical if
the respond time exceeds 500ms or 60 percent package loss.
check_icmp -H server -w 200.0,30% -c 500.0,60%

1.5.2.5

Load: Checking the Load on the Server

This check will output a warning if the load value exceeded 7.0 in the last minute, 6.0 in the

last 5 minutes or 5.0 in the last 15 minutes (-w 7.0,6.0,5.0). It will output a critical if the load
value exceeded 12.0 in the last minute, 8.0 in the last 5 minutes or 6.0 in the last 15 minutes
(-c 12.0,8.0,6.0).

check_load -w 7.0,6.0,5.0 -c 12.0,8.0,6.0

1.5.2.6

Disk Health: Checking the Health of Local Hard Disks

This check is only relevant on physical systems with local storage attached to it. It will check the
disk status utilizing the S.M.A.R.T interface and it will output a critical if any of the S.M.A.R.T

values exceeds critical limits. check_smartmon is not a standard Nagios plugin and can be downloaded at https://exchange.nagios.org/ .

check_smartmon --drive /dev/sda --drive /dev/sdb

16

Common Checks

1.5.3

Other Checks

1.5.3.1

MySQL: Checking That the MySQL Database Is Responding

This check will check that the MySQL database server is running and that the database api_production is available.

check_mysql -H localhost -u nagios -p xxxxxx -d api_production

MySQL Databases to check:
1. api_production
2. mysql

1.5.3.2

Backup Status: Checking That a Valid Backup Is Available

It is always advisable to check that the last backup run was successful and a recent backup is
available. The check itself depends on the Backup solution that is used.

17

Other Checks

2 File System Overview
2.1 Configuration Files
2.1.1

Front-end Configuration

The front-end is configured with 4 les:
/srv/www/obs/api/config/database.yml
/srv/www/obs/api/config/options.yml
/srv/www/obs/api/config/feature.yml
/etc/apache2/vhosts.d/obs.conf

2.1.1.1

database.yml

This le has the information needed to access the database. It contain credentials for the database
access and should be only readable by root and the group running the Web server (www).

The le has settings for the production, development and test ruby environment, for production
systems only the production section is important.
Example production section
production:
adapter: mysql2
database: api_production
username: obsapiuser
password: topsecret
encoding: utf8
timeout: 15
pool: 30

TABLE 2.1: DATABASE CONFIGURATION KEYWORDS

keyword

Description

Remarks

adapter

Database driver

only mysql databases are supported

database

Database name

do not change !

18

Configuration Files

keyword

Description

Remarks

username

mysql user name

database user, not a system user

password

password for this user

clear text

encoding

codetable

timeout

wait time in milliseconds

pool

number of open connections

socket

path to the mysql socket

host

IP address or hostname of the for remote servers

port

port number of the mysql

per thread

same host only

mysql server
server

2.1.1.2

for remote servers

options.yml

The configuration le /srv/www/obs/api/config/options.yml is the default configuration le

for the Open Build Service Web UI and API. It contains configuration parameters for example

for back-end connections and connection to the API. Important are the configurations for source
and front-end hosts The configuration for LDAP authentication is also located in this le.

Note
More and more configurations will be moved to the database and do not longer exist in
this le. The database configuration can be accessed via the API /configuration path.
TABLE 2.2: options.yml CONFIGURATION ITEMS

Config item

Description

Values default

Remarks

use_xforward

Use mod_xforward

true false

Apache only, should

19

module

be true

Front-end Configuration

Config item

Description

Values default

Remarks

use_nginx_redirect

Use X-Accel-Redirect

/inter-

Nginx only

nal_redirect

min_votes_for_rating

Minimum votes for a

integer 3

response_schema_valida-

Set to true to verify

true false

tion

rating

XML responses com-

test/debug option

ply to the schema

source_host

back-end source serv-

localhost

source_port

back-end source serv-

integer 5352

source_protocol

back-end source serv-

http , https

front end_host

Front-end host

localhost

frontend_port

Front-end port

integer 443

frontend_protocol

Front-end protocol

http https

external_frontend_host

External Front-end

er host
er port

er protocol

if your users access

host

the hosts through a
proxy or different
name

external_frontend_port

External Front-end

integer 443

external_frontend_proto-

External Front-end

http https

extended_backend_log

Extended back-end

true false

col

20

port

protocol
log

test/debug option

Front-end Configuration

Config item

Description

Values default

Remarks

proxy_auth_mode:

turn proxy mode on/

:off :on

see LDAP section

proxy_auth_test_user

Test user

coolguy

test/debug option

proxy_auth_test_email

Email of Test user

coolguy@ exam- test/debug option

o

ple.com

global_write_through

if set to false, the API
will only fake writes

true false

test/debug option

30

moved to /configura-

to back-end
auto_cleanup_after_days

not longer used

errbit_api_key

API key of the appli-

test/debug option

errbit_host

installation of er-

test/debug option

cation

rbit.com a Ruby error

tion API

catcher
errbit_api_key

API key of the appli-

ldap_mode:

OBS LDAP mode on/

test/debug option

cation
o

:off :on

see LDAP section

Example options.yml
#
# This file contains the default configuration of the Open Build Service
# API.
#

# Make use of mod_xforward module in apache
use_xforward: true
# Make use of X-Accel-Redirect for Nginx.

21

Front-end Configuration

# http://kovyrin.net/2010/07/24/nginx-fu-x-accel-redirect-remote
#use_nginx_redirect: /internal_redirect
# Minimum count of rating votes a project/package needs to # be taken in
# account
# for global statistics:
min_votes_for_rating: 3
# Set to true to verify XML reponses comply to the schema
response_schema_validation: false
# backend source server
source_host: localhost
source_port: 5352
#source_protocol: https
# api access to this instance
frontend_host: localhost
frontend_port: 443
frontend_protocol: https
# if your users access the hosts through a proxy (or just a different name,
# use this to
# overwrite the settings for users)
#external_frontend_host: api.opensuse.org
#external_frontend_port: 443
#external_frontend_protocol: https

extended_backend_log: true
# proxy_auth_mode can be :off, :on or :simulate
proxy_auth_mode: :off
# ATTENTION: If proxy_auth_mode'is :on, the frontend takes the user
# name that is coming as headervalue X-username as a
# valid user does no further authentication. So take care...
proxy_auth_test_user: coolguy
proxy_auth_test_email: coolguy@example.com
# set this to enable auto cleanup requests after the given days
auto_cleanup_after_days: 30
#schema_location
#version
# if set to false, the API will only fake writes to backend (useful in

22

Front-end Configuration

# testing)
# global_write_through: true
# see
# http://colszowka.heroku.com/2011/02/22/setting-up-your-custom-hoptoad-notifierendpoint-for-free-using-errbit-on-heroku
#errbit_api_key: api_key_of_your_app
#errbit_host: installation.of.errbit.com

2.1.1.3

feature.yml

The configuration le /srv/www/obs/api/config/feature.yml contains the default configuration
about features that can be enabled or disabled in Open Build Service.
TABLE 2.3: feature.yml CONFIGURATION ITEMS

Config item

Description

Values default

Remarks

image_templates

enable/disable image

true false

see Reference Guide

kiwi_image_editor

enable/disable Kiwi

true false

cloud_upload

enable/disable Cloud

true false

template feature
Image Editor

Upload setup

for more information

Example feature.yml
production:
features: &default
image_templates: true
kiwi_image_editor: false
cloud_upload: false
development:
features:
<<: *default
kiwi_image_editor: true
cloud_upload: true
test:
features:
<<: *default
kiwi_image_editor: true

23

Front-end Configuration

cloud_upload: true

2.1.1.4

Apache Virtual Host obs.conf

The Apache configuration depends on the Apache version and which extra options are used, so
use the documentation of the Apache version you are using.

Here, as an example, the standard configuration used by the appliance: Apache vhost example
Listen 82
# May needed on old distributions or after an update from them.
#Listen 443
# Passenger defaults
PassengerSpawnMethod "smart"
PassengerMaxPoolSize 20
#RailsEnv "development"
# allow long request urls and being part of headers
LimitRequestLine 20000
LimitRequestFieldsize 20000
# Just the overview page

# just give an overview about this OBS instance via static web page
DocumentRoot

"/srv/www/obs/overview"


Options Indexes
Require all granted



# Build Results

# The resulting repositories
DocumentRoot

"/srv/obs/repos"


Options Indexes FollowSymLinks
Require all granted



24

Front-end Configuration

# OBS WEB UI & API

ServerName api
#

General setup for the virtual host

DocumentRoot

"/srv/www/obs/api/public"

ErrorLog /srv/www/obs/api/log/apache_error.log
TransferLog /srv/www/obs/api/log/apache_access.log
PassengerMinInstances 2
PassengerPreStart https://api
SSLEngine on
#

SSL protocols

#

Supporting TLS only is adequate nowadays

SSLProtocol all -SSLv2 -SSLv3
#

SSL Cipher Suite:

#

List the ciphers that the client is permitted to negotiate.

#

We disable weak ciphers by default.

#

See the mod_ssl documentation or "openssl ciphers -v" for a

#

complete list.

SSLCipherSuite ALL:!aNULL:!eNULL:!SSLv2:!LOW:!EXP:!MD5:@STRENGTH
SSLCertificateFile /srv/obs/certs/server.crt
SSLCertificateKeyFile /srv/obs/certs/server.key

AllowOverride all
Options -MultiViews
# This requires mod_xforward loaded in apache
# Enable the usage via options.yml
# This will decrease the load due to long running requests a lot (unloading
from rails stack)
XForward on
Require all granted

SetEnvIf User-Agent ".*MSIE [1-5].*" \
nokeepalive ssl-unclean-shutdown \
downgrade-1.0 force-response-1.0
CustomLog /var/log/apache2/ssl_request_log

25

ssl_combined

Front-end Configuration

# from http://guides.rubyonrails.org/asset_pipeline.html

Header unset ETag
FileETag None
# RFC says only cache for 1 year
ExpiresActive On
ExpiresDefault "access plus 1 year"

SetEnvIf User-Agent ".*MSIE [1-5].*" \
nokeepalive ssl-unclean-shutdown \
downgrade-1.0 force-response-1.0
## Older firefox versions needs this, otherwise it wont cache anything over SSL.
Header append Cache-Control "public"


2.1.2

Back-end Configuration

The Back-end is configured with 2 les:
/etc/sysconfig/obs-server - a shell script used for workers and the OBS start scripts
/usr/lib/obs/server/BSConfig.pm - a perl script defining some global variables

2.1.2.1

/etc/sysconfig/obs-server

This script is used to set up the basic paths and the worker. the most important settings are the
OBS_SRC_SERVER and OBS_REPO_SERVERS and the OBS_WORKER_INSTANCES.
TABLE 2.4: obs-server VARIABLES

Variable

Description

Values default

OBS_BACKENDCODE_DIR

Path to the back-

/usr/lib/obs/serv-

OBS_RUN_DIR

communication di-

/srv/obs/run

OBS_LOG_DIR

logging directory

/srv/obs/log

26

end scripts

rectory base

Remarks

er/

Back-end Configuration

Variable

Description

Values default

OBS_BASE_DIR

base directory

/srv/obs

OBS_API_AUTOSETUP

Automatically set-

yes no

up API and Web UI

Remarks

appliance only,

will overwrite config les

OBS_SRC_SERVER

source server host

localhost:5352

only one

OBS_REPO_SERVERS

repository server

localhost:5252

maybe a list

OBS_WORKER_INSTANCES

number of build

integer 0

OBS_WORKER_INSTANCE

names of the work-

OBS_WORKER_DIRECTORY

worker base direc-

OBS_WORKER_PORTBASE

The base for port

_NAMES

host

instances

space-separated

ers

list

tory

numbers used by

integer 0

worker
OBS_WORKER_JOBS

Number of parallel

integer 1

OBS_WORKER_TEST_MODE

Run in test mode

yes no

OBS_WORKER_HOST LA-

one or more labels

OBS_USE_SLP

Register in SLP

OBS_CACHE_DIR

cache directory for

BELS

compile jobs

ber

may used by con-

for the build host
server

0 OS assign num-

straints
yes no

downloaded packages

27

Back-end Configuration

Variable

Description

OBS_CACHE_SIZE

package cache size

OBS_WORKER_NICE _LEVEL

nice level of run-

18

OBS_VM_TYPE

VM type

auto xen kvm

ning workers

Values default

Remarks
in MB

lxc zvm emulator:$arch none

OBS_VM_KERNEL

Set kernel used by
worker

none (/boot/vm-

linuz)

KVM option

OBS_VM_INITRD

initrd used by
worker

none (/boot/vm-

linuz)

KVM option

OBS_VM_DISK_AUTOSETUP

Autosetup disk size

4096

in MB

OBS_VM_DISK_AUTOSETUP

Autosetup swap

1024

on MB

OBS_VM_DISK_AUTOSETUP

File System used

ext3

OBS_VM_DISK_AUTOSETUP

Special mount op-

OBS_VM_USE_TMPFS

Enable build in

yes no

OBS_INSTANCE_MEMORY

Memory allocated

512

OBS_STORAGE_AUTOSETUP

storage auto con-

yes no

may destroy disk

OBS_SETUP_WORKER

LVM via obsstor-

take_all use_ob-

may destroy disk

_ROOT_FILESIZE
_SWAP_FILESIZE
_FILESYSTEM

_MOUNT_OPTIONS

_PARTITIONS

28

size

with autosetup
tions

memory

for a VM

figuration
agesetup

s_vg none

requires much
memory

content
content

Back-end Configuration

Variable

Description

OBS_WORKER_CACHE_SIZE

LVM partition for

OBS_WORKER_ROOT_SIZE

LVM partition for

OBS_WORKER_SWAP_SIZE

LVM partition for

OBS_WORKER_BINARIES

proxy service for

OBS_ROOT_SSHD_KEY_URL

ssh pub key to al-

OBS_WORKER_SCRIPT_URL

URL to the initial

_PROXY

Values default

Remarks

cache size
root size

swap size

caching binaries

low root user login

for mass deployment

script

For workers the settings could be declared in the /etc/buildhost.config le as well.
#
# NOTE: all these options can be also declared in /etc/buildhost.config on each worker
differently.
#
## Path:

Applications/OBS

## Description: The OBS backend code directory
## Type:

string

## Default:

""

## Config:

OBS

#
# An empty dir will lead to the fall back directory, typically /usr/lib/obs/server/
#
OBS_BACKENDCODE_DIR=""
## Path:

Applications/OBS

## Description: The base for OBS communication directory
## Type:

string

## Default:

""

## Config:

OBS

#
# An empty dir will lead to the fall back directory, typically /srv/obs/run

29

Back-end Configuration

#
OBS_RUN_DIR="/srv/obs/run"
## Path:

Applications/OBS

## Description: The base for OBS logging directory
## Type:

string

## Default:

""

## Config:

OBS

#
# An empty dir will lead to the fall back directory, typically /srv/obs/log
#
OBS_LOG_DIR="/srv/obs/log"
## Path:

Applications/OBS

## Description: The base directory for OBS
## Type:

string

## Default:

""

## Config:

OBS

#
# An empty dir will lead to the fall back directory, typically /srv/obs
#
OBS_BASE_DIR=""
## Path:

Applications/OBS

## Description: Automatically set up API and Web UI for OBS server, be warned, this will
replace config files!
## Type:

("yes" | "no")

## Default:

"no"

## Config:

OBS

#
# This is usally only enabled on the OBS Appliance
#
OBS_API_AUTOSETUP="yes"
#
# NOTE: all these options can be also declared in /etc/buildhost.config on each worker
differently.
#
## Path:

Applications/OBS

## Description: define source server host to be used
## Type:

string

## Default:

""

## Config:

OBS

#
# An empty setting will point to localhost:5352 by default
#
OBS_SRC_SERVER=""

30

Back-end Configuration

## Path:

Applications/OBS

## Description: define repository server host to be used
## Type:

string

## Default:

""

## Config:

OBS

#
# An empty setting will point to localhost:5252 by default
#
OBS_REPO_SERVERS=""
## Path:

Applications/OBS

## Description: define number of build instances
## Type:

integer

## Default:

0

## Config:

OBS

#
# 0 instances will automatically use the number of CPU's
#
OBS_WORKER_INSTANCES="0"
## Path:

Applications/OBS

## Description: define names of build instances for z/VM
## Type:

string

## Default:

""

## Config:

OBS

#
# The names of the workers as defined in z/VM. These must have two minidisks
# assigned, and have a secondary console configured to the local machine:
# 0150 is the root device
# 0250 is the swap device
#
#OBS_WORKER_INSTANCE_NAMES="LINUX075 LINUX076 LINUX077"
OBS_WORKER_INSTANCE_NAMES=""
## Path:

Applications/OBS

## Description: The base directory, where sub directories for each worker will get
created
## Type:

string

## Default:

""

## Config:

OBS

#
#
OBS_WORKER_DIRECTORY=""
## Path:

Applications/OBS

## Description: The base for port numbers used by worker instances

31

Back-end Configuration

## Type:

integer

## Default:

"0"

## Config:

OBS

#
# 0 means let the operating system assign a port number
#
OBS_WORKER_PORTBASE="0"
## Path:

Applications/OBS

## Description: Number of parallel compile jobs per worker
## Type:

integer

## Default:

"1"

## Config:

OBS

#
# this maps usually to "make -j1" during build
#
OBS_WORKER_JOBS="1"
## Path:

Applications/OBS

## Description: Run in test mode (build results will be ignore, no job blocking)
## Type:

("yes" | "")

## Default:

""

## Config:

OBS

#
OBS_WORKER_TEST_MODE=""
## Path:

Applications/OBS

## Description: define one or more labels for the build host.
## Type:

string

## Default:

""

## Config:

OBS

#
# A label can be used to build specific packages only on dedicated hosts.
# For example for benchmarking.
#
OBS_WORKER_HOSTLABELS=""
## Path:

Applications/OBS

## Description: Register in SLP server
## Type:

("yes" | "no")

## Default:

"yes"

## Config:

OBS

#
#
OBS_USE_SLP="yes"
## Path:

32

Applications/OBS

Back-end Configuration

## Description: Use a common cache directory for downloaded packages
## Type:

string

## Default:

""

## Config:

OBS

#
# Enable caching requires a given directory here. Be warned, content will be
# removed there !
#
OBS_CACHE_DIR=""
## Path:

Applications/OBS

## Description: Defines the package cache size
## Type:

size in MB

## Default:

""

## Config:

OBS

#
# Set the size to 50% of the maximum usable size of this partition
#
OBS_CACHE_SIZE=""
## Path:

Applications/OBS

## Description: Defines the nice level of running workers
## Type:

integer

## Default:

18

## Config:

OBS

#
# Nicenesses range from -20 (most favorable

scheduling) to 19 (least

# favorable).
# Default to 18 as some testsuites depend on being able to switch to
# one priority below (19) _and_ having changed the numeric level
# (so going from 19->19 makes them fail).
#
OBS_WORKER_NICE_LEVEL=18
## Path:

Applications/OBS

## Description: Set used VM type by worker
## Type:

("auto" | "xen" | "kvm" | "lxc" | "zvm" | "emulator:$arch" | "emulator:

$arch:$script" | "none")
## Default:

"auto"

## Config:

OBS

#
#
OBS_VM_TYPE="auto"
## Path:

Applications/OBS

## Description: Set kernel used by worker (kvm)
## Type:

33

("none" | "/boot/vmlinuz" | "/foo/bar/vmlinuz)

Back-end Configuration

## Default:

"none"

## Config:

OBS

#
# For z/VM this is normally /boot/image
#
OBS_VM_KERNEL="none"
## Path:

Applications/OBS

## Description: Set initrd used by worker (kvm)
## Type:

("none" | "/boot/initrd" | "/foo/bar/initrd-foo)

## Default:

"none"

## Config:

OBS

#
# for KVM, you have to create with (example for openSUSE 11.2):
#
# export rootfstype="ext4"
# mkinitrd -d /dev/null -m "ext4 binfmt_misc virtio_pci virtio_blk" -k
vmlinuz-2.6.31.12-0.2-default -i initrd-2.6.31.12-0.2-default-obs_worker
#
# a working initrd file which includes virtio and binfmt_misc for OBS in order to work
fine
#
# for z/VM, the build script will create a initrd at the given location if
# it does not yet exist.
#
OBS_VM_INITRD="none"
## Path:

Applications/OBS

## Description: Autosetup for XEN/KVM/TMPFS disk (root) - Filesize in MB
## Type:

integer

## Default:

"4096"

## Config:

OBS

#
#
OBS_VM_DISK_AUTOSETUP_ROOT_FILESIZE="4096"
## Path:

Applications/OBS

## Description: Autosetup for XEN/KVM disk (swap) - Filesize in MB
## Type:

integer

## Default:

"1024"

## Config:

OBS

#
#
OBS_VM_DISK_AUTOSETUP_SWAP_FILESIZE="1024"
## Path:

Applications/OBS

## Description: Filesystem to use for autosetup {none,ext4}=ext4, ext3=ext3

34

Back-end Configuration

## Type:

string

## Default:

"ext3"

## Config:

OBS

#
#
OBS_VM_DISK_AUTOSETUP_FILESYSTEM="ext3"
## Path:

Applications/OBS

## Description: Filesystem mount options to use for autosetup
## Type:

string

## Default:

""

## Config:

OBS

#
#
OBS_VM_DISK_AUTOSETUP_MOUNT_OPTIONS=""
## Path:

Applications/OBS

## Description: Enable build in memory
## Type:

("yes" | "")

## Default:

""

## Config:

OBS

#
# WARNING: this requires much memory!
#
OBS_VM_USE_TMPFS=""
## Path:

Applications/OBS

## Description: Memory allocated for each VM (512) if not set
## Type:

integer

## Default:

""

## Config:

OBS

#
#
OBS_INSTANCE_MEMORY=""
## Path:

Applications/OBS

## Description: Enable storage auto configuration
## Type:

("yes" | "")

## Default:

""

## Config:

OBS

#
# WARNING: this may destroy data on your hard disk !
# This is usually only used on mass deployed worker instances
#
OBS_STORAGE_AUTOSETUP="yes"
## Path:

35

Applications/OBS

Back-end Configuration

## Description: Setup LVM via obsstoragesetup
## Type:

("take_all" | "use_obs_vg" | "none")

## Default:

"use_obs_vg"

## Config:

OBS

#
# take_all: WARNING: all LVM partitions will be used and all data erased !
# use_obs_vg:

A lvm volume group named "OBS" will be re-setup for the workers.

#
OBS_SETUP_WORKER_PARTITIONS="use_obs_vg"
## Path:

Applications/OBS

## Description: Size in MB when creating LVM partition for cache partition
## Type:

integer

## Default:

""

## Config:

OBS

#
#
OBS_WORKER_CACHE_SIZE=""
## Path:

Applications/OBS

## Description: Size in MB when creating LVM partition for each worker root partition
## Type:

integer

## Default:

""

## Config:

OBS

#
#
OBS_WORKER_ROOT_SIZE=""
## Path:

Applications/OBS

## Description: Size in MB when creating LVM partition for each worker swap partition
## Type:

integer

## Default:

""

## Config:

OBS

#
#
OBS_WORKER_SWAP_SIZE=""
## Path:

Applications/OBS

## Description: URL to a proxy service for caching binaries used by worker
## Type:

string

## Default:

""

## Config:

OBS

#
#
OBS_WORKER_BINARIES_PROXY=""
## Path:

36

Applications/OBS

Back-end Configuration

## Description: URL to a ssh pub key to allow root user login
## Type:

string

## Default:

""

## Config:

OBS

#
# This is usually used on mass (PXE) deployed workers)
#
OBS_ROOT_SSHD_KEY_URL=""
## Path:

Applications/OBS

## Description: URL to a script to be downloaded and executed
## Type:

string

## Default:

""

## Config:

OBS

#
# This is a hook for doing special things in your setup at boot time
#
OBS_WORKER_SCRIPT_URL=""

2.1.2.2

BSConfig.pm

This le is a perl module used by most back-end scripts, it mainly defines global variables. Since
it is a perl module, after changes the back-end servers need to be restarted to become aware
of the changes.

Warning
If there is a Perl syntax error in this le, the services will not start. Most likely you forgot
the semicolon on the end of a statement.
TABLE 2.5: BSConfig.pm VARIABLES

Variable

Description

$hostname

FQDN of the back-

leave as it is

$ip

IP address of the

leave as it is

37

end host

back-end host

Values default

Remarks

Back-end Configuration

Variable

Description

Values default

Remarks

$frontend

FQDN of the front-

undef

set only if the front-

end host

$ipaccess

Map of IP access

$srcserver

URL of the source

$reposerver
$serviceserver

host

Add all hosts if parti-

rules

tion are used
'http://$host-

server

name: 5352'

URL of the repo serv-

'http://$host-

er

name: 5252'

URL of the service

'http://$host-

server

end runs on another

partition specific

name: 5152'

$workersrcserver

URL of the source

optional for worker

$workerreposerver

URL of the repo serv-

optional for worker

$clouduploadserver

URL of the cloud up-

$servicedir

server

access

er

access
'http://$host-

load server

name: 5452'

Path to the service

/usr/lib/obs/ser-

scripts

vice/

$servicetempdir

Path to service temp

/var/tmp/

$serviceroot

Prefix to servicedir

$service_maxchild

Maximum number of

dir

concurrent jobs for

optional
optional

integer

unlimited if not set

source service

38

Back-end Configuration

Variable

Description

Values default

Remarks

$gpg_standard_key

Path to the standard

$hermesserver

URL of the notifica-

optional

$hermesnamespace

Namespace for the

optional

$notification _plugin

notification plugins

optional

@reposervers

List of reposervers

sign key

tion server

notifications

("http://$hostname: 5252")

$bsdir

Path to the back-end

/srv/obs

$bsuser

OS user running the

obsrun

$bsgroup

OS group running the

obsrun

$bsquotale

Package quota for

optional

$sched_asyncmode

Use asynchronous

Avoid issues with

directory
back-end
back-end
projects

scheduler

$sched_startupmode

Cold start mode

$disable_data_sync

fdatasync

$rundir

back-end communi-

39

cation

remote projects on
slow networks
0 12

may cause data corruption
$bsdir/run

Back-end Configuration

Variable

Description

Values default

$logdir

log directory

$bsdir/log

$nosharedtrees

Shared trees

01 2

0=shared 1=not

shared 2=not shared
enable binary release

$limit_projects

limit visibility of

tracking

optional for non-ACL
systems, should be

set for access control

with fallback
$packtrack

Remarks

[]

optional

projects for some architectures

$relsync_pool

allow separation of

releasenumber syncing per architecture

$stageserver

stage server

rsync URI

$stageserver_sync

Extra stage sync serv-

rsync URI

$sign

Path to sign script

$sign_project

call sign with --

$keyfile

Global sign key

$localarch

Local architecture for

$buildlog_maxsize

worker max buildlog

40

er

project 

0 1

product building
size

'500 * 1000000'

in bytes

Back-end Configuration

Variable

Description

Values default

Remarks

$buildlog_maxidle

Time with no

'8 * 3600'

in sec

changes in the buildlog will kill the job

$xenstore_maxsize

xenstore size

'20 * 1000000'

current XEN has no

$gettimeout

Max timeout for get

'1 * 3600'

in sec

$workerhostcheck

check script for

$powerhosts

Worker with more re-

obsolete use con-

$powerpkgs

packages which need

obsolete use con-

xenstore anymore

worker

sources

straints

workers with more

straints

resources
$norootexceptions

List of packages need

$old_style_services

Use old style source

$partition

Current partition

to build as root

service handling

0 1

see Section 1.4, “Distributed Setup”

$partitioning
$partitionservers
$dispatch_adjust

Partition project
mapping

Partition server mapping

Adjust dispatch priority

see Section 1.4, “Distributed Setup”

see Section 1.4, “Distributed Setup”

see Section 3.4.2,
“dispatch_adjust
Array”

41

Back-end Configuration

Variable

Description

Values default

Remarks

$publishedhook_use

Use regular expres-

0 1

see Section 3.5, “Pub-

_regex

$publishedhook

sions in publish hook

lisher Hooks”

map

Publish hook map

see Section 3.5, “Publisher Hooks”

$unpublished-

hook_use _regex
$unpublishedhook

Use regular expressions in unpublish

0 1

see Section 3.6, “Unpublisher Hooks”

hook map

Unpublish hook map

see Section 3.6, “Unpublisher Hooks”

Example BSConfig.pm
#
# Copyright (c) 2006, 2007 Michael Schroeder, Novell Inc.
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License version 2 as
# published by the Free Software Foundation.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

See the

# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program (see the file COPYING); if not, write to the
# Free Software Foundation, Inc.,
# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
#
################################################################
#
# Open Build Service Configuration
#
package BSConfig;
use Net::Domain;
use Socket;

42

Back-end Configuration

my $hostname = Net::Domain::hostfqdn() || 'localhost';
# IP corresponding to hostname (only used for $ipaccess); fallback to localhost since
inet_aton may fail to resolve at shutdown.
my $ip = quotemeta inet_ntoa(inet_aton($hostname) || inet_aton("localhost"));
my $frontend = undef; # FQDN of the Web UI/API server if it's not $hostname
# If defined, restrict access to the backend servers (bs_repserver, bs_srcserver,
bs_service)
our $ipaccess = {
'127\..*' => 'rw', # only the localhost can write to the backend
"^$ip" => 'rw',

# Permit IP of FQDN

'.*' => 'worker',

# build results can be delivered from any client in the network

};
# IP of the Web UI/API Server (only used for $ipaccess)
if ($frontend) {
my $frontendip = quotemeta inet_ntoa(inet_aton($frontend) || inet_aton("localhost"));
$ipaccess->{$frontendip} = 'rw' ; # in dotted.quad format
}
# Also change the SLP reg files in /etc/slp.reg.d/ when you touch hostname or port
our $srcserver = "http://$hostname:5352";
our $reposerver = "http://$hostname:5252";
our $serviceserver = "http://$hostname:5152";
# you can use different ports for worker connections
#our $workersrcserver = "http://$hostname:5353";
#our $workerreposerver = "http://$hostname:5253";
our $servicedir = "/usr/lib/obs/service/";
#our $servicetempdir = "/var/temp/";
#our $serviceroot = "/opt/obs/MyServiceSystem";
# Maximum number of concurrent jobs for source service
#our $service_maxchild = 20;
our $gpg_standard_key = "/srv/obs/obs-default-gpg.asc";
# optional notification service:
#our $hermesserver = "http://$hostname/hermes";
#our $hermesnamespace = "OBS";
#
# Notification Plugin, multiple plugins supported, separated by space
#our $notification_plugin = "notify_hermes notify_rabbitmq";
#

43

Back-end Configuration

# For the workers only, it is possible to define multiple repository servers here.
# But only one source server is possible yet.
our @reposervers = ("http://$hostname:5252");
# Package defaults
our $bsdir = '/srv/obs';
our $bsuser = 'obsrun';
our $bsgroup = 'obsrun';
#our $bsquotafile = '/srv/obs/quota.xml';
# Use asynchronus scheduler. This avoids hanging schedulers on remote projects,
# when the network is slow or broken. This will become the default in future
# our $sched_asyncmode = 1;
# Define how the scheduler does a cold start. The default (0) is to request the
# data for all packages, (1) means that only the non-remote packages are fetched,
# (2) means that all of the package data fetches get delayed.
# our $sched_startupmode = 0;
# Disable fdatasync calls, increases the speed, but may lead to data
# corruption on system crash when the filesystem does not guarantees
# data write before rename.
# It is esp. required on XFS filesystem.
# It is safe to be disabled on ext4 and btrfs filesystems.
#our $disable_data_sync = 1;
# Package rc script / backend communication + log files
our $rundir = "$bsdir/run";
our $logdir = "$bsdir/log";
# optional for non-acl systems, should be set for access control
# 0: trees are shared between projects (built-in default)
# 1: trees are not shared (only usable for new installations)
# 2: new trees are not shared, in case of a missing tree the shared
#

location is also tried (package default)

our $nosharedtrees = 2;
# enable binary release tracking by default for release projects
our $packtrack = [];
# optional: limit visibility of projects for some architectures
#our $limit_projects = {
# "ppc" => [ "openSUSE:Factory", "FATE" ],
# "ppc64" => [ "openSUSE:Factory", "FATE" ],
#};
# optional: allow seperation of releasnumber syncing per architecture

44

Back-end Configuration

# one counter pool for all ppc architectures, one for i586/x86_64,
# arm archs are separated and one for the rest in this example
our $relsync_pool = {
"local" => "local",
"i586" => "i586",
"x86_64" => "i586",
"ppc" => "ppc",
"ppc64" => "ppc",
"ppc64le" => "ppc",
"mips" => "mips",
"mips64" => "mips",
"mipsel" => "mipsel",
"mips64el" => "mipsel",
"aarch64"

=> "arm",

"aarch64_ilp32"

=> "arm",

"armv4l"

=> "arm",

"armv5l"

=> "arm",

"armv6l"

=> "arm",

"armv6hl" => "arm",
"armv7l"

=> "arm",

"armv7hl" => "arm",
"armv5el" => "armv5el", # they do not exist
"armv6el" => "armv6el",
"armv7el" => "armv7el",
"armv8el" => "armv8el",
"sparcv9" => "sparcv9",
"sparc64" => "sparcv9",
};
#No extra stage server sync
#our $stageserver = 'rsync://127.0.0.1/put-repos-main';
#our $stageserver_sync = 'rsync://127.0.0.1/trigger-repos-sync';
#No package signing server
our $sign = "/usr/bin/sign";
#Extend sign call with project name as argument "--project $NAME"
#our $sign_project = 1;
#Global sign key
our $keyfile = "/srv/obs/obs-default-gpg.asc";
# Use a special local arch for product building
# our $localarch = "x86_64";
# config options for the bs_worker
#
#our buildlog_maxsize = 500 * 1000000;
#our buildlog_maxidle =

45

8 * 3600;

Back-end Configuration

#our xenstore_maxsize =

20 * 1000000;

#our gettimeout =

1 * 3600;

#
# run a script to check if the worker is good enough for the job
#our workerhostcheck = 'my_check_script';
#
# Allow to build as root, exceptions per package
# the keys are actually anchored regexes
# our $norootexceptions = { "my_project/my_package" => 1, "openSUSE:Factory.*/
installation-images" => 1 };
# Use old style source service handling
# our $old_style_services = 1;
###
# Optional support to split the binary backend. This can be used on large servers
# to separate projects for better scalability.
# There is still just one source server, but there can be multiple servers which
# run each repserver, schedulers, dispatcher, warden and publisher
#
# This repo service is the 'home' server for all home:* projects. This and the
# $reposerver setting must be different on the binary backend servers.
# our $partition = 'home';
#
# this defines how the projects are split. All home: projects are hosted
# on an own server in this example. Order is important.
# our $partitioning = [ 'home:' => 'home',
#

'.*'

#

=> 'main',

];

#
# our $partitionservers = { 'home' => 'http://home-backend-server:5252',
#

'main' => 'http://main-backend-server:5252',

#

};

# Publish hooks
our $publishedhook_use_regex = 1;
our $publishedhook = {
"Product\/SLES12"

=> "/usr/local/bin/script2run_sles12",

"Product\/SLES11.*"

=> "/usr/local/bin/script2run_sles11",

};

# host specific configs
my $hostconfig = __FILE__;
$hostconfig =~ s/[^\/]*$/bsconfig.$hostname/;
if (-r $hostconfig) {
print STDERR "reading $hostconfig...\n";

46

Back-end Configuration

require $hostconfig;
}
1;

2.2 Log Files
2.2.1

Front-end

The front-end log les are found under /srv/www/obs/api/log.
The following front-end log les exist:
apache_access.log - apache requests
apache_error.log - errors from apache
backend_access.log - API → backend requests
clockworkd.clock.output → timer event log
delayed_job.log → delayed job log
production.log→ main ruby log
production.searchd.log - search daemon log
production.searchd.query.log - search request logs

2.2.2

Back-end

The back-end log les are found by default under /srv/obs/log/.
The following back-end log les exist:
dispatcher.log - dispatcher log
dodup.log - download on demand log (since 2.7)
publisher.log - publisher log
rep_server.log - repo server log

47

Log Files

scheduler_.log - scheduler log for each architecture
signer.log - sign service log
src_server.log - source server log
src_service.log - source service daemon log
warden.log - warden log
clouduploadserver.log - cloud upload server log
clouduploadworker.log - cloud upload worker log
The following log les for the upload jobs exist inside the /srv/obs/cloudupload directory (also
linked in /bs/cloudupload):

.log - log les for undone upload jobs
done/.log - log les for already finished upload jobs

2.3 /srv/obs Tree
The default back-end data directory is located under /srv/obs/. Here are a bunch of subdirec-

tories used for communication between the different server, to store data, status information
and logs. Here is one le configuration.xml in the top directory, which stores the global OBS

configuration for the back-end. You should not modify this le directly, but use the API /configuration interface instead, since this information needs to kept in sync with the front-end.

2.3.1

build Directory

In this subdirectory managed by the repo server daemon, all repository data, metadata and build
results are stored in a hierarchical tree.

Example build directory tree of a binary imported distribution (OpenSUSE:13.2) and a small
test project with 3 packages:
├── openSUSE:13.2
│

└── standard

│

├── i586

│

│

│

└── x86_64

48

└── :full

/srv/obs Tree

│

└── :full

├── Test1
│

└── os13.2

│

├── i586

│

│

├── :full

│

│

├── :logfiles.fail

│

│

├── :logfiles.success

│

│

├── :meta

│

│

├── :repo

│

│

├── rsync

│

│

├── srtp

│

│

└── wget

│

└── x86_64

│

├── :full

│

├── :logfiles.fail

│

├── :logfiles.success

│

├── :meta

│

├── :repo

│

├── rsync

│

├── srtp

│

└── wget

2.3.2

cloudupload Directory

Info for cloud upload jobs is stored here, it has a subdir named done for storing the already
finished jobs.

2.3.3

db Directory

Back-end database root directory use by the source server, repo server scheduler and publisher.
Nobody should touch this.

2.3.4

diffcache Directory

Cache for source server compare operations.

2.3.5

events Directory

Communication between services.

49

cloudupload Directory

2.3.6

info Directory

Scheduler information managed by the scheduler and used by the repo server.

2.3.7

jobs Directory

The build jobs are stored in the /srv/obs/jobs directory. They are organized bybuild architecture:
jobs
├── armv7l
├── i586
├── load
└── x86_64
└── Release:Stable::SLE-12_GA::CI-demo-36db80552b735e193dced13f058f866f

The jobs/load le contains statistical data about the build jobs.

2.3.8

log Directory

Contains the log les of the back-end daemons.

2.3.9

projects Directory

Contains the project hierarchy and metadata under revision control.

2.3.10

remotecache Directory

Cache for remote repository information.

2.3.11

repos Directory

Directory managed by the publisher to collect build results, also used by the repo server and
scheduler to nd build results.

2.3.12

repos_sync Directory

Directory with les pointing to the project root directories, helper for publisher rsync.

50

info Directory

2.3.13

run Directory

State and lock information for the back-end daemons

2.3.14

sources Directory

All package sources under revision control in one directory per package, managed by the source

server. Package sources are by default deduplicated across all projects, as long a source le has
the same MD5 sum, it is only stored once. A pseudo '_project' package exist in the directory
containing the project metadata revisions. ':service' and ':upload' are temporary directories
used by the source server.

Example sources directory structure:
sources/
├── CI-demo
[...]
├── srtp
├── test1
├── _project
├── :service
└── :upload

2.3.15

trees Directory

Revision control data for project and packages, managed by the source server.

2.3.16

upload Directory

Temporary directory for uploading les for other back-end components.

2.3.17

workers Directory

Worker information

51

run Directory

2.4 Metadata
2.4.1

OBS Revision Control

This section gives a short generic overview how the revision information are stored in the OBS
back-end for packages and projects. The OBS back-end stores all les in a light weight content

based hierarchical tree. Each le is hashed (with MD5) and stored with the hash as part of
the filename under the /srv/obs/tree or /srv/obs/sources directories. The revision information is
stored in separate les by the Source Server in the /srv/obs/projects directory.

2.4.1.1

OBS revision control files

The revision information is stored in simple CSV like le format with a bar (|) as delimiter
between the 8 columns. The les do have the extension .rev for package/project revision data
and .mref for meta revision data. The hash then points to a -MD5SUMS le in the /srv/

obs/tree/ directories which have the le list with MD5 hashes of this revision. The hashes in this
le list are pointing to the source les in the /srv/obs/sources tree.
An example revision le:
1|1|56cdd3adb778089d1fcc49b92bb93e5b|0.9|1464005086|user4|initial version|
2|2|fe7aa1ade5c9d005de738c234c90bc90|0.9|1464005304|user4|fix spec file|
3|1|72c7986e694f45ab1a62779e64e92a8f|1.0|1464005339|user4|new version|
4|2|699e9931e6f167d78e65bbe5853f592f|1.0|1464006221|user4|add patch file|
5|1|0cfc3a2297f38d2aa9d8d0e98fc22a38|1.1|1464007797|user4|new version|

TABLE 2.6: THE 8 COLUMNS

Column
1
2

Content
revision number
version revision
number

XML tag

may empty

ref

no

vref

yes

3

hash

srcmd5

no

4

version

version

yes

5

time stamp

time

no

52

Metadata

Column

Content

XML tag

may empty

6

user

user

no

7

commit message

comment

yes

8

request id

requestid

yes

Depending on the target (package, project or metadata) used, elds can be empty or have special
values, for example, unknown for the version.
Example MD5SUMS le
/srv/obs # cat trees/Test1/package1/56cdd3adb778089d1fcc49b92bb93e5b-MD5SUMS
0a17daaa913df9e50ee65e83a1898363

package1.spec

1f810b3521242a98333b7bbf6b2b7ef7

test1.sh

2.4.1.2

OBS Revision API

The revision info can be retrieved via API calls for the specific package, for example, using /
source///_history .

Specific revisions of les can be retrieved with the optional "rev=N" parameter, for example, /
source///<le>?rev=N.

On PUT and POST methods for les the optional "comment=some+comment" can be used to
set a commit message.

2.4.2

Project Metadata

Project metadata are XML les containing the meta project information, such as title, descrip-

tion, related user and groups with roles, build settings, repository settings, publish settings, debug settings and more.

TABLE 2.7: PROJECT META XML

XML tag

Attributes

Content

project

name

project name

title

53

Short description

Project Metadata

XML tag

Attributes

description

Content
Developer information

person

userid

login name

person

role

role (maintainer, bugowner, …)

group

groupid

group name

group

role

role (maintainer, bugowner, …)

devel

An optional devel project

build

optional build ags

publish

optional publish ags

useforbuild

optional useforbuild ags

debuginfo

optional debuginfo ags

binarydownload

optional binarydownload ags

repository

name

name of the repository for build results

repository path

project

name of the source project for remaining

repository path

repository

name of repository in the source project

build requires

repository arch

architecture name

remoteurl

path to a remote OBS API for interconnect

Example project metadata:


Project for demo




54

Project Metadata



x86_64



2.4.3

Package Metadata

XML le about package meta information, like Title, description, related user and groups with

roles, build settings, publish settings, debug settings and more. Most XML tags are the same as
for projects.

Example package metadata:


An example test package for learning.














2.4.4

Attribute Metadata

Attributes can be used to add special information to packages. Attributes can be used to trigger
special actions.

Example attribute data:



2016-06-30 00:00:00


55

Package Metadata






2.4.5

Job Files

Jobs are stored by the scheduler in the /srv/obs/jobs directory and contain the build setup

information for the package, for example, a reference to the exact source version, build dependencies, build repository information, timestamps.
Sample job le:

Release:Stable::SLE-12_GA::
CI-demo-36db80552b735e193dced13f058f866f
x86_64
36db80552b735e193dced13f058f866f
36db80552b735e193dced13f058f866f
2
obs://b1-systems.de/Release:Stable/SLE-12_GA/
36db80552b735e193dced13f058f866f-CI-demo
new build
0
1461077600
1461077708
CI-demo.spec
0.1.9-2
1
2.1
1
linux:version:min 3.0.0












56

Job Files


[...]




57

Job Files

3 Administration
3.1 Tools
3.1.1

obs_admin

obs_admin is a command-line tool used on the back-end server(s) to manage running services,

submit maintenance tasks, and debug problems. It should be only used by experienced admins.
It has built-in help which you can display with obs_admin --help.
Options to control the running services:
Job Controlling
===============
--shutdown-scheduler 
Stops the scheduler nicely with dumping out its current state
for fast startup.
--check-project  
--check-project   
--check-all-projects 
Check status of a project and its repositories again
--deep-check-project  
--deep-check-project   
Check status of a project and its repositories again
This deep check also includes the sources, in case of lost events.
--check-package   
Check status of a package in all repositories
--publish-repository  
Creates an event for the publisher. The scheduler is NOT scanning for new packages.
The publisher may skip the event, if nothing has changed.
Use --republish-repository when you want to enforce a publish.
--unpublish-repository  
Removes the prepared :repo collection and let the publisher remove the result. This
is also updating the search database.
WARNING: this works also for locked projects!

58

Tools

--prefer-publish-event 
prefers a publish event to be next.  is the file name inside of the publish
event directory.
--republish-repository  
enforce to publish a repository
--rebuild-full-tree   
rebuild the content of :full/ directory
--clone-repository   
--clone-repository   

Clone an existing repo into another existing repository.
Usefull for creating snapshots.
--rescan-repository   
Asks the scheduler to scan a repository for new packages and add
them to the cache file.
--force-check-project   
Enforces the check of an repository, even when it is currently blocked due to amount
of
calculating time.
--create-patchinfo-from-updateinfo
creates a patchinfo submission based on an updateinfo information.

Options for maintenance are:
Maintenance Tasks
=================
Note: the --update-*-db calls are usually only needed when corrupt data has been created,
for
example after a file system corruption.
--update-source-db []
Update the index for all source files.
--update-request-db
Updates the index for all requests.
--remove-old-sources   (--debug)
WARNING: this is an experimental feature atm. It may trash your data, but you have
anyway
a backup, right?
remove sources older than  days, but keep  number of revisions

59

obs_admin

--debug for debug output

Options for debugging:
Debug Options
=============
--dump-cache   
Dumps out the content of a binary cache file.
This shows all the content of a repository, including all provides
and requires.
--dump-state 
--dump-project-from-state  
dump the state of a project.
--dump-relsync 
To dump content of :relsync files.
--set-relsync   
Modify key content in a a :relsync file.
--check-meta-xml 
--check-meta-xml  
Is parsing a project or package xml file and puts out error messages, in case of
errors.
--check-product-xml 
Is parsing a product xml file and puts out error messages, in case of errors.
It does expand all xi:include references and validates the result.
--check-product-group-xml 
Is parsing a group xml file from a product definition and puts out error messages, in
case of errors.
--check-kiwi-xml 
--check-kiwi-xml  
Is parsing a KIWI xml file and puts out error messages, in case of errors.
--check-constraints 
--check-constraints  
Validates a _constraints file
--check-pattern-xml 
Is parsing a pattern xml file and puts out error messages, in case of errors.
--check-request-xml 

60

obs_admin

Is parsing a request xml file and puts out error messages, in case of errors.
--parse-build-desc  [ []]
Parse a spec, dsc or KIWI file with the Build script parser.
--show-scheduler-architectures
Show all architectures which are configured in configuration.xml to be supported by
this instance.
--show-delta-file 
Show all instructions of a OBS delta file
--show-delta-store 
Show delta store statistics

3.1.2

osc

The osc command-line client is mainly used by developers and packagers. But for some tasks,
admin people also need this tool. It too has builtin help: use osc --help. The tool needs to be
configured rst to know the OBS API URL and your user details.
To configure the osc tool the rst time you need to call it with
osc -A 
For example:
osc -A https://api.testobs.org

Follow the instructions on the terminal.

Warning
The password is stored in clear text in the .oscrc le by default, so you need to give

this le restrictive access rights, only read/write access for your user should be allowed.
osc allows to store the password in other ways (in keyrings for example) and may use
different methods for authentication like Kerberos see Section 3.7.5.2, “Kerberos”
For the admins the most important osc subcommands are:
meta - to create or update projects or package data
API - to read and write online configuration data

61

osc

3.1.2.1

osc meta Subcommand

meta: Show meta information, or edit it
Show or edit build service metadata of type .
This command displays metadata on buildservice objects like projects,
packages, or users. The type of metadata is specified by the word after
"meta", like e.g. "meta prj".
prj denotes metadata of a buildservice project.
prjconf denotes the (build) configuration of a project.
pkg denotes metadata of a buildservice package.
user denotes the metadata of a user.
pattern denotes installation patterns defined for a project.
To list patterns, use 'osc meta pattern PRJ'. An additional argument
will be the pattern file to view or edit.
With the --edit switch, the metadata can be edited. Per default, osc
opens the program specified by the environmental variable EDITOR with a
temporary file. Alternatively, content to be saved can be supplied via
the --file switch. If the argument is '-', input is taken from stdin:
osc meta prjconf home:user | sed ... | osc meta prjconf home:user -F For meta prj and prjconf updates optional commit messages can be applied
with --message.
When trying to edit a non-existing resource, it is created implicitly.

Examples:
osc meta prj PRJ
osc meta pkg PRJ PKG
osc meta pkg PRJ PKG -e
Usage:
osc meta  [-r|--revision REV] ARGS...
osc meta  ARGS...
osc meta  [-m|--message TEXT] -e|--edit
ARGS...
osc meta  [-m|--message TEXT] -F|--file
ARGS...
osc meta pattern --delete PRJ PATTERN
osc meta attribute PRJ [PKG [SUBPACKAGE]] [--attribute ATTRIBUTE]
[--create|--delete|--set [value_list]]
Options:

62

osc

-h, --help

show this help message and exit

--delete

delete a pattern or attribute

-s ATTRIBUTE_VALUES, --set=ATTRIBUTE_VALUES
set attribute values
-R, --remove-linking-repositories
Try to remove also all repositories building against
remove ones.
-c, --create

create attribute without values

-e, --edit

edit metadata

-m TEXT, --message=TEXT
specify log message TEXT. For prj and prjconf meta
only
-r REV, --revision=REV
checkout given revision instead of head revision.
For
prj and prjconf meta only
-F FILE, --file=FILE
read metadata from FILE, instead of opening an
editor.
'-' denotes standard input.
-f, --force

force the save operation, allows one to ignores some
errors like depending repositories. For prj meta

only.
--attribute-project
include project values, if missing in packages
--attribute-defaults
include defined attribute defaults
-a ATTRIBUTE, --attribute=ATTRIBUTE
affect only a given attribute

3.1.2.2

osc api Subcommand

api: Issue an arbitrary request to the API
Useful for testing.
URL can be specified either partially (only the path component), or fully
with URL scheme and hostname ('http://...').
Note the global -A and -H options (see osc help).
Examples:
osc api /source/home:user
osc api -X PUT -T /etc/fstab source/home:user/test5/myfstab
osc api -e /configuration

63

osc

Usage:
osc api URL
Options:
-h, --help

show this help message and exit

-a NAME STRING, --add-header=NAME STRING
add the specified header to the request
-T FILE, -f FILE, --file=FILE
specify filename to upload, uses PUT mode by default
-d STRING, --data=STRING
specify string data for e.g. POST
-e, --edit

GET, edit and PUT the location

-X HTTP_METHOD, -m HTTP_METHOD, --method=HTTP_METHOD
specify HTTP method to use (GET|PUT|DELETE|POST)

The online API documentation is available at https://build.opensuse.org/apidocs
Some examples for admin stu:
# Read the global configuration file
osc api /configuration
# Update the global configuration
osc api /configuration -T /tmp/configuration.xml
# Read the distributions list
osc api /distributions
# Udate the distributions list
osc api /distributions -T /tmp/distributions.xml
# retrieve statistics
osc api /statistics/latest_added

3.2 Managing Build Targets
3.2.1

Interconnect

Using another Open Build Service as source for build targets is the easiest way to start. The

advantage is, that you save local resources and you do not need to build everything from scratch.

The disadvantage is that you depend on the remote instance, if it has a downtime your instance
cannot do any builds for these targets, if the remote admins decide to remove some targets you
cannot use them anymore.

64

Managing Build Targets

The easiest way to interconnect with some of the public OBS instances is to use the Web UI. You
need to log in with an administrator account of your instance to do this. On the start page of an
administrator account you will nd a Configuration link. On the Configuration page you nd
an Interconnect tab on the top, use this and select the public side you want.

If you want to connect to a not listed instance, you can simple create a remote project using
the osc meta prj command. A remote project differs from a local project the it has a remoteurl
tag (see Section 2.4.2, “Project Metadata”).
Example:



This project refers to projects hosted on the openSUSE Build Service

https://api.opensuse.org/public


Sending this via osc to the server:
osc meta prj -m "add openSUSE.org remote" -F /tmp/openSUSE.org.prj

3.2.2

Importing Distributions

With local hosted distributions packages you are independent from other parties. On sides with

no or bad internet connections, this is the only way to go. You do not need to build the distribution packages on your instance, you can use binary packages for this. Here are different ways
to get a local build repository:

1. mirror a distribution from another OBS instance
2. mirror a binary distribution from a public mirror and import the binaries
3. use already existing local install repositories (for example, from an SMT instance)
4. use the install media to import the binaries

These tasks need to be run on the obs back-end. In a partition setup you need to run it on the
partition which would the owner for the project.

65

Importing Distributions

3.2.2.1

Mirroring from a Remote OBS Instance

Mirroring a project from a remote OBS instance can be done with the obs_mirror_project script

which is supplied with the obs sources and via the obs-utils package. You can get the latest version from GitHub: https://raw.githubusercontent.com/openSUSE/open-build-service/master/dist/
obs_mirror_project

.

The usage:
____________________________________________________________________________________
Usage: obs_mirror_project.rb -p PROJECT -r REPOSITORY
[-a ARCHITECTURE] [-d DESTINATION] [-A APIURL] [-t] [-v]
Example: (mirror openSUSE 13.1 as base distro)
obs_mirror_project -p openSUSE:13.1 -r standard -a i586,x86_64
____________________________________________________________________________________
Options help:
-p, --proj PROJECT

Project Name: eg. openSUSE:13.1,Ubuntu:14.04,etc.

-r, --repo REPOSITORY

Repository Name:

-a, --arch Architecture

Architecture Name: eg. i586,x86_64,etc.

-d, --dest DESTINATION

Destination Path:

-A, --api APIURL

OSC API URL :Default: https://api.opensuse.org

-t, --trialrun

Trial run: not executing actions

-v, --verbose

Verbose

-h, --help

Display this screen

eg. standard,qemu,etc.
eg. /obs

Default: PWD (current working directory)

3.2.2.2

Importing Binary Packages

This is the same procedure for all local sources. If you have a local copy of a distribution, you

can either use symbolic links to the binary packages or copy them in a directory on the back-end
repo server under the /srv/obs/build directory. You should follow the common name schema

for build repository here. As rst step you should create an empty project for the distribution,
you can use the Web UI or the osc command-line tool. Then you add a repository with the
name standard and the build architectures you want. Here an example project meta le:


openSUSE 13.2 build repositories





66

Importing Distributions





x86_64
i586



After you have created the project with these settings, the /srv/obs/build directory should have
a tree for SUSE:13.2:
/srv/obs/
├── build
│

└── SUSE:13.2

│

└── standard

│

├── i586

│

│

├── :bininfo

│

│

└── :schedulerstate

│

└── x86_64

│

├── :bininfo

│

└── :schedulerstate

Warning
All the directories under /srv/obs/build have to be owned by the obsrun user and group.

The obsrun user need write access to them. If not the scheduler process will crash
on your instance.

You need to import the project configuration as well, you can get them for example from the
openSUSE Build Service.

osc -A https://api.opensuse.org meta prjconf openSUSE:13.2 >/tmp/13.2.prjconf
osc meta prjconf -m 'Original version from openSUSE' SUSE:13.2 -F /tmp/13.2.prjconf

Now you need to create the directory ':full' for the binary sources under each architecture, this
should be owned by obsrun too.

testobs:/srv/www/obs/api # mkdir /srv/obs/build/SUSE\:13.2/standard/i586/:full
testobs:/srv/www/obs/api # mkdir /srv/obs/build/SUSE\:13.2/standard/x86_64/:full
testobs:/srv/www/obs/api # chown obsrun:obsrun \
/srv/obs/build/SUSE\:13.2/standard/i586/:full
testobs:/srv/www/obs/api # chown obsrun:obsrun \
/srv/obs/build/SUSE\:13.2/standard/x86_64/:full

67

Importing Distributions

Now you can copy (or link) all binary packages for the architecture in the :full directory. You
need the architecture specific package and the noarch packages as well.

Important
If you import packages for enterprise distributions like SLES12 you also need the packages
from the SDK. Maybe you need packages from add-on products as well, depending what
software you want build.

Finally you should trigger a rescan for the project on the back-end server using obs_admin:
testobs # obs_admin --rescan-repository SUSE:13.2 standard i586
testobs # obs_admin --rescan-repository SUSE:13.2 standard x86_64

This reads all packages and creates the dependency tree.

3.3 Source Services
Source Services are tools to validate, generate or modify sources in a trustable way. They are

designed as smallest possible tools and can be combined following the powerful idea of the
classic UNIX design.

Design goals of source services were:
server side generated les must be easy to identify and must not be modifiable by the

user. This way other users can trust them to be generated in the documented way without
modifications.

generated les must never create merge conflicts
generated les must be a separate commit to the user change
services must be runnable at any time without user commit
services must be runnable on server and client side in the same way
services must be designed in a safe way. A source checkout and service run must never
harm the system of a user.

services shall be designed in a way to avoid unnecessary commits. This means there shall

be no time-dependent changes. In case the package already contains the same le, the
newly generated le must be dropped.

68

Source Services

local services can be added and used by everybody.
server side services must be installed by the admin of the OBS server.
services can be defined per package or project wide.

3.3.1

Using Services for Validation

Source Services may be used to validate sources. This can happen per package, which is useful

when the packager wants to validate that downloaded sources are really from the original maintainer. Or validation can happen for an entire project to apply general policies. These services
cannot get skipped in any package

Validation can happen by validating les (for example using the verify_file or source_val-

idator service. These services just fail in the error case which leads to the build state "broken".

Or validation can happen by redoing a certain action and store the result as new le as down-

load_files is doing. In this case the newly generated le will be used instead of the committed

one during build.

3.3.2

Different Modes When Using Services

Each service can be used in a special mode defining when it should run and how to use the
result. This can be done per package or globally for an entire project.

3.3.2.1

Default Mode

The default mode of a service is to always run after each commit on the server side and locally
before every local build.

3.3.2.2

trylocal Mode

The trylocal mode is running the service locally when using current osc versions. The result gets
committed as standard les and not named with _service: prefix. Additionally the service runs
on the server by default, but usually the service should detect that the result is the same and

skip the generated les. In case they differ for any reason (because the webui or API was used
for example) they be generated and added on the server.

69

Using Services for Validation

3.3.2.3

localonly Mode

The localonly mode is running the service locally when using current osc versions. The result gets
committed as standard les and not named with _service: prefix. The service is never running
on the server side. It is also not possible to trigger it manually.

3.3.2.4

serveronly Mode

The serviceonly mode is running the service on the service only. This can be useful, when the
service is not available or can not work on developer workstations.

3.3.2.5

buildtime Mode

The service is running inside of the build job, for local and server side builds. A side effect is

that the service package is becoming a build dependency and must be available. Every user can
provide and use a service this way in their projects. The generated sources are not part of the

source repository, but part of the generated source packages. Network access is not be available
when the workers are running in a secure mode.

3.3.2.6

disabled Mode

The disabled mode is neither running the service locally or on the server side. It can be used to
temporarily disable the service but keeping the definition as part of the service definition. Or
it can be used to define the way how to generate the sources and doing so by manually calling
osc service disabledrun The result will get committed as standard les again.

3.3.3

Storage of Source Service Definitions

The called services are always defined in a _service le. It is either part of the package sources
or used project-wide when stored inside the _project package.

The _service le contains a list of services which get called in this order. Each service may define
a list of parameters and a mode. The project wide services get called after the per package
defined services. The _service le is an xml le like this example:


70

Storage of Source Service Definitions



krabber-1.0.tar.gz
sha256
7f535a96a834b31ba2201a90c4d365990785dead92be02d4cf846713be938b78




This example downloads the les via download_files service via the given URLs from the spec le.
When using osc this le gets committed as part of the commit. Afterwards the krabber-1.0.tar.gz
le will always be compared with the sha256 checksum. And last but not least there is the
update_source service mentioned, which is usually not executed. Except when osc service

disabledrun is called, which will try to upgrade the package to a newer source version available

online.

3.3.4

Dropping a Source Service Again

Sometimes it is useful to continue work on generated les manually. In this situation the _service
le needs to be dropped, but all generated les need to be committed as standard les. The
OBS provides the "mergeservice" command for this. It can also be used via osc by calling osc
service merge .

3.4 Dispatch Priorities
The dispatcher takes a job from the scheduler and assign it to a free worker. It tries to share

the available build time fair between all the project repositories with pending jobs. To achieve
this the dispatcher calculates a load per project repository of the used build time (similar to

the system load in Unix operating systems). The dispatcher assigned jobs to build clients from
the repository with the lowest load (thereby increasing the its load). It is possible to tweak
this mechanism via dispatching priorities assigned to the repositories via the /build/_dispatch-

priosAPI call or via the dispatch_adjust array in the BSConfig.pmSection 2.1.2.2, “BSConfig.pm”
configuration le.

71

Dropping a Source Service Again

3.4.1

The /build/_dispatchprios API Call

The /build/_dispatchprios API call allows an Admin to set a priority for defined projects and

repositories using the HTML put method. With the HTML get method the current XML priority
le can be read.





The attributes project, repository and arch are all optional, if for example arch and repository are

missing the entry is used for all repositories and architectures for the given project. It is not

supported to use regular expressions for the names. The adjust value is taken as logarithmic scale
factor to the current load of the repositories during the compare. Projects without any entry get
a default priority of 0, higher values cause the matching projects to get more build time.
Example dispatchprios XML le






TABLE 3.1: ROUNDED SCALE FACTORS RESULTING FROM A PRIORITY

priority

scale factor

priority

scale factor

-50

100000

3

0.5

-30

1000

5

0.3

-20

100

7

0.2

-15

30

10

0.1

-10

10

15

0.03

-7

5

20

0.01

-5

3

30

0.001

-3

2

40

0.0001

72

The /build/_dispatchprios API Call

priority

scale factor

priority

scale factor

0

1

50

0.00001

3.4.2

dispatch_adjust Array

With the dispatch_adjust array in the BSConfig.pm le the dispatch priorities of project repos-

itories based on regular expressions for the project, repository name and maybe architecture.

Each match will add or subtract a value to the priority of the repository. The default priority is
0, higher values cause the matching projects to get more build time.
Each entry in the dispatch_adjust array has the format
'regex string'

=> priority adjustment

The full name of a build repository looks like
Project:Subproject/Repository/Architecture
Examples:
Devel:Science/SLES-11/i586
home:king:test/Leap42/x86_64

If a repository matches a string the adjustment is added to the current value. The final value is

the sum of the adjustments of all matched entries. This sum is the same logarithmic scale factor
as described in the previous section.

Example dispatch_adjust definition in the BSConfig.pm
our $dispatch_adjust = [
'Devel:' => 7,
'HotFix:' => +20,
'.+:test.*' => -10,
'home:' => -3,
'home:king' => +30,
'.+/SLE12-SP2' => -40,
];

The above example could have the following background: All Devel projects should get some

higher priority so the developer jobs getting more build time. The projects under HotFix are
very important fixes for customers and so they should get a worker as soon as possible. All

projects with test in the name get some penalty, also home projects are getting only about half

73

dispatch_adjust Array

of the build time as a normal project, with the exception of the home project from king, the

user account of the boss. The SLES12-SP2 repository is not in real use yet, but if here is nothing
else to do build for it as well.

Important
The dispatcher calculates the values form the 'dispatch_adjust' array rst, if the same

project and repository also has an entry in the dispatchprios XML le, the XML le entry
will overwrite the calculated priority. The best practice is to only use one of the methods.

3.5 Publisher Hooks
The job of the publisher service is to publish the build packages and/or images by creating
repositories that are made available through a web server.

It can be configured to use custom scripts to copy the build results to different servers or do
anything with them that comes to mind. These scripts are called publisher hooks.

3.5.1

Configuring Publisher Hooks

Hooks are configured via the configuration le /usr/lib/obs/server/BSConfig.pm, where one script

per project is linked to the repository that should be run if the project/repository combination
is published. It is possible to use regular expressions here.

The script is called by the user obsrun with the following parameters:
1. information about the project and its repository (for example, training/SLE11-SP1 )
2. path to published repository (for example, /srv/obs/repos/training/SLE11-SP1 )
3. changed packages (for example, x86 64/test.rpm x86 64/utils.rpm )

The hooks are configured by adding a hash reference named $publishedhook to the BSConfig.pm

configuration le. The key contains the project, and the value references the accompanying

script. If the value is written as an array reference it is possible to call the hook with self-defined
parameters.

74

Publisher Hooks

The publisher will add the 3 listed parameters at the end, after the self-defined parameters (in
/usr/lib/obs/server/BSConfig.pm ):
our $publishedhook = {
"Product/SLES12"

=> "/usr/local/bin/script2run_sles12",

"Product/SLES11-SP3" => "/usr/local/bin/script2run_sles11",
"Product/SLES11-SP4" => "/usr/local/bin/script2run_sles11",
};

Regular expressions or substrings can be used to define a script for more than one repository
in one project. The use of regular expressions has to be activated by defining $publishedhook
use regex = 1; as follows (in /usr/lib/obs/server/BSConfig.pm ):
our $publishedhook_use_regex = 1;
our $publishedhook = {
"Product\/SLES12"

=> "/usr/local/bin/script2run_sles12",

"Product\/SLES11.*"

=> "/usr/local/bin/script2run_sles11",

};

With self defined parameters:
our $publishedhook_use_regex = 1;
our $publishedhook = {
"Product\/SLES11.*" => ["/usr/local/bin/script2run", "sles11", "/srv/www/
public_mirror"],
};

The configuration is read by the publisher at startup only, so it has to be restarted after configuration changes have been made. The hook script’s output is not logged by the publisher and

should be written to a log le by the script itself. In case of a broken script,this is logged in the
publisher’s log le (/srv/obs/log/publisher.log by default):
Mon Mar

7 14:34:17 2016 publishing Product/SLES12

fetched 0 patterns
running createrepo
calling published hook /usr/local/bin/script2run_sles12
/usr/local/bin/script2run_sles12 failed: 65280
syncing database (6 ops)

Interactive scripts are not working and will fail immediately.
If you need to do a lot of work in the hook script and do not want to block the publisher all the
time, you should consider using a separate daemon that does all the work and just gets triggered
by the configured hook script.

75

Configuring Publisher Hooks

The scripts are called without a timeout.

3.5.2

3.5.2.1

Example Publisher Scripts

Simple Publisher Hook

The following example script ignores the packages that have changed and copies all RPMs from
the repository directory to a target directory:
#!/bin/bash
OBSHOME="/srv/obs"
SRC_REPO_DIR="$OBSHOME/repos"
LOGFILE="$OBSHOME/log/reposync.log"
$DST_REPO_DIR="/srv/repo-mirror"
# Global substitution! To handle strings like Foo:Bar:testing - two
#+double-colons!
PRJ_PATH=${1//:/:\/}
PATH_TO_REPO=$2
rsync -a --log-file=$LOGFILE $PATH_TO_REPO/ $DST_REPO_DIR/$PRJ_PATH/

For testing purposes, it can be invoked as follows:
$ sudo -u obsrun /usr/local/bin/publish-hook.sh Product/SLES11-SP1 \
/srv/obs/repos/Product/SLE11-SP1

3.5.2.2

Advanced Publisher Hook

The following example script reads the destination path from a parameter that is configured
with the hook script:
#!/bin/bash
LOGFILE="/srv/obs/log/reposync.log"
DST_REPO_DIR=$1
# Global substion! To handle strings like Foo:Bar:testing - two
#+double-colons!
PRJ_PATH=${2//:/:\/}
PATH_TO_REPO=$3
mkdir -p $DST_REPO_DIR/$PRJ_PATH
rsync -a --log-file=$LOGFILE $PATH_TO_REPO/ $DST_REPO_DIR/$PRJ_PATH/

76

Example Publisher Scripts

For testing purposes, it can be invoked as follows:
$ sudo -u obsrun /usr/local/bin/publish-hook.sh \
/srv/www/public_mirror/Product/SLES11-SP1 \
/srv/obs/repos/Product/SLE11SP1

The following example script only copies packages that have changed, but does not delete packages that have been removed:
#!/bin/bash
DST_REPO_DIR=$1
PRJ_PATH=${2//:/:\/}
PATH_TO_REPO=$3
shift 3
mkdir -p $DST_REPO_DIR/$PRJ_PATH
while [ $# -gt 0 ]
do
dir=(${1//\// })
if [ ! -d

"$DST_REPO_DIR/$PRJ_PATH/$dir" ]; then

mkdir -p $DST_REPO_DIR/$PRJ_PATH/$dir
fi
cp $PATH_TO_REPO/$1 $DST_REPO_DIR/$PRJ_PATH/$1
shift
done
createrepo $DST_REPO_DIR/$PRJ_PATH/.

For testing purposes, it can be invoked as follows:
$ sudo -o obsrun /usr/local/bin/publish-hook.sh

/srv/www/public_mirror \

Product/SLES11-SP1 /srv/obs/repos/Product/SLE11-SP1 \
src/icinga-1.13.3-1.3.src.rpm x86_64/icinga-1.13.3-1.3.x86_64.rpm \
x86_64/icinga-devel-1.13.3-1.3.x86_64.rpm

3.6 Unpublisher Hooks
The job of the publisher service is to publish the build packages and/or images by creating
repositories that are made available through a web server.

The OBS Publisher can be configured to use custom scripts to be called whenever already published packages get removed. These scripts are called unpublisher hooks. Unpublisher hooks
are run before the publisher hooks.

77

Unpublisher Hooks

3.6.1

Configuring Unpublisher Hooks

Hooks are configured via the configuration le /usr/lib/obs/server/BSConfig.pm, where one script

per project is linked to the repository that should be run if the project/repository combination
is removed. It is possible to use regular expressions here.

The script is called by the user obsrun with the following parameters:
1. information about the project and its repository (for example, training/SLE11-SP1)
2. repository path (for example, /srv/obs/repos/training/SLE11-SP1 )
3. removed packages (for example, x86 64/test.rpm x86 64/utils.rpm )

The hooks are configured by adding a hash reference named $unpublishedhook to the BSConfig.pm

configuration le. The key contains the project and the value references the accompanying
script. If the value is written as an array reference, it is possible to call the hook with custom
parameters.

The publisher adds the three listed parameters at the end, directly after the custom parameters
(in /usr/lib/obs/server/BSConfig.pm ):
our $unpublishedhook = {
"Product/SLES12"

=> "/usr/local/bin/script2run_sles12",

"Product/SLES11-SP3" => "/usr/local/bin/script2run_sles11",
"Product/SLES11-SP4" => "/usr/local/bin/script2run_sles11",
};

Regular expressions or substrings can be used to define a script for more than one repository in
one project. The use of regular expressions needs to be activated by defining $unpublishedhook
use regex = 1; (in /usr/lib/obs/server/BSConfig.pm ):
our $unpublishedhook_use_regex = 1;
our $unpublishedhook = {
"Product\/SLES12"

=> "/usr/local/bin/script2run_sles12",

"Product\/SLES11.*"

=> "/usr/local/bin/script2run_sles11",

};

With custom parameters:
our $unpublishedhook_use_regex = 1;
our $unpublishedhook = {
"Product\/SLES11.*" => [
"/usr/local/bin/script2run", "sles11", "/srv/www/public_mirror"
],
};

78

Configuring Unpublisher Hooks

The configuration is read by the publisher at startup only, so it has to be restarted after configuration changes have been made. The hook script’s output is not logged by the publisher and

should be written to a log le by the script itself. In case of a broken script, this is logged in the
publisher’s log le (/srv/obs/log/publisher.log by default):
Mon Mar

7 14:34:17 2016 publishing Product/SLES12

fetched 0 patterns
running createrepo
calling unpublished hook /usr/local/bin/script2run_sles12
/usr/local/bin/script2run_sles12 failed: 65280
syncing database (6 ops)

Interactive scripts are not working and will fail immediately.
If you need to do a lot of work in the hook script and do not want to block the publisher all
the time, consider using a separate daemon that does all the work and just gets triggered by
the configured hook script.

The scripts are called without a timeout.

Note
Reminder: If unpublish hooks and publish hooks are defined, the unpublish hook runs before
the publish hook.

3.6.2
3.6.2.1

Example Unpublisher Scripts
Simple Unpublisher Hook

The following example script deletes all packages from the target directory that have been removed from the repository.
#!/bin/bash
OBSHOME="/srv/obs"
LOGFILE="$OBSHOME/log/reposync.log"
DST_REPO_DIR="/srv/repo-mirror"
# Global substitution! To handle strings like Foo:Bar:testing - two
#+double-colons!
PRJ_PATH=${1//:/:\/}
PATH_TO_REPO=$2
shift 2

79

Example Unpublisher Scripts

while [ $# -gt 0 ]
do
rm -v $DST_REPO_DIR/$PRJ_PATH/$1 >>$LOGFILE 2>&1
shift
done

For testing purposes, it can be invoked as follows:
$ sudo -u obsrun /usr/local/bin/unpublish-hook.sh \
Product/SLES11-SP1

\

/srv/obs/repos/Product/SLE11-SP1

\

src/icinga-1.13.3-1.3.src.rpm

\

x86_64/icinga-1.13.3-1.3.x86_64.rpm

\

x86_64/icinga-devel-1.13.3-1.3.x86_64.rpm

3.6.2.2

Advanced Unpublisher Hook

The following example script reads the destination path from a parameter that is configured
via the hook script:
#!/bin/bash
OBSHOME="/srv/obs"
LOGFILE="$OBSHOME/log/reposync.log"
DST_REPO_DIR=$1
# Global substitution! To handle strings like Foo:Bar:testing - two
#+double-colons!
PRJ_PATH=${1//:/:\/}
PATH_TO_REPO=$2
shift 3
while [ $# -gt 0 ]
do
rm -v $DST_REPO_DIR/$PRJ_PATH/$1 >>$LOGFILE 2>&1
shift
done

For testing purposes, it can be invoked as follows:
$ sudo -u obsrun /usr/local/bin/unpublish-hook.sh \
/srv/www/public_mirror/Product/SLES11-SP1

\

/srv/obs/repos/Product/SLE11SP1

\

src/icinga-1.13.3-1.3.src.rpm

\

x86_64/icinga-1.13.3-1.3.x86_64.rpm

\

x86_64/icinga-devel-1.13.3-1.3.x86_64.rpm

80

Example Unpublisher Scripts

3.7 Managing Users and Groups
The OBS has an integrated user and group management with a role based access rights model.

In every OBS instance, at least one user need to exist and have the global Admin role assigned.
Groups can be defined by the Admin and instead of adding a list of users to a project/package
role user can be added to a group and the group will be added to a project or package role.

3.7.1

User and Group Roles

The OBS role model has one global role: Admin, which can be granted to users. Am OBS admin
has access to all projects and packages via the API interface and the web user interface. Some
menus in the Web UI do not allow changes by an Admin (for example, the Repository menu)

as long the Admin is not a Maintainer for the project as well. But the same change can be done
via editing the metadata directly. The other roles are specific to projects and packages and can
be assigned to a user or a group.
TABLE 3.2: ROLES IN OBS

Role

Description

Maintainer

Read and write access to projects or

Bugowner

Read access to projects or packages

Reader

Read access to sources

Down-

Read access to the binaries

Reviewer

Default reviewer for a package or

loader

3.7.2

Remarks

packages

should be unique per package

project

Standalone User and Group Database

OBS provides its own user database which can also store a password. The authentication to

the API happens via HTTP BASIC AUTH. See the API documentation to nd out how to create,
modify or delete user data. Also a call for changing the password exists.

81

Managing Users and Groups

Users can be added by the maintainer or if registration is allowed via the registration menu

on the Web UI. It can be configured that a confirmation is needed after registration before the
user may login.

3.7.3

Proxy Mode

The proxy mode can be used for specially secured instances, where the OBS web server shall not
get connected to the network directly. There are authentication proxy products out there which
do the authentication and send the user name via an HTTP header to OBS. Originally, this was

developed for IChain - a legacy single login authentication method from Novell. This also has
the advantage that the user password never reaches OBS.

The proxy mode can also be used for LDAP or Active Directory, but only for authentication.

Important
With enabled proxy mode the OBS trust the username in the http header. Since this was
verified by the Web server and the Web server only forward requests for a verified and

authenticated session, this is safe, as long you make sure that the direct web/API interface
of the OBS is not reachable from the outside.

With the proxy mode the user still need to be registered in the OBS and all OBS roles and user
properties are managed inside the OBS.

3.7.3.1

OBS Proxy Mode Configuration

Currently the LDAP configuration is in the options.yml le.
TABLE 3.3: OPTIONS FOR PROXY MODE CONFIGURATION

Config item

Description

Values de-

Remarks

fault

proxy_auth_mode

82

turn proxy mode on/
o

:off :on

need to be :o if

ldap_mode: is :on

Proxy Mode

3.7.4

LDAP/Active Directory

Note
The LDAP support was considered experimental and not officially supported. It is officially
supported since 2.8.3 release.

Using LDAP or Active Directory as source for user and optional group information in environments which already have such a server has the advantage for the admin people that the user

related information only need to be maintained in one place. In the following sections we are

writing LDAP, but this includes Microsoft's Active Directory as well. Only in parts where differences exists Active Directory (AD) will be explicit mentioned.

In this mode the OBS contact the LDAP server directly from the OBS API, if the user was found
and provides the correct password the user is added transparently to the OBS user database.

The password or password hash is not stored in the OBS database. Because the user database
password eld is mandatory, a random hash is stored instead. The LDAP interface allows to

restrict the access to users which are in a special LDAP group. Optional also groups can be
discovered from the LDAP server. This can be also filtered.

Before anybody can add a user to a package or project with a role, the user need to had logged
in at least one time, since the check for available users is local only. If the LDAP group mode
is enabled, LDAP groups are also added transparently, if an existing group on the LDAP server
is added to a project or package.

On bigger installations this mode can result in many search requests to the LDAP server and slow
down access to projects and packages, because on every role check an LDAP search operation

will contact the LDAP server. As alternative method group mirroring was implemented. This

allows that the internal OBS group database is updated with the group membership information
during the user authentication. All role test are made local against the OBS database and do not
need additional LDAPoperations.

Note
The local user group membership in :mirror mode is updated as follows: When the user
logins, the user memberOf attributes are parsed and compared with the global OBS grou-

plist, if a group matches, the user is added, if they are no longer a group member, they

are removed. since this maybe a costly operation, depending on the group counts, this is
only done on a full login. After a full login the user status is cashed for 2 minutes, if the

83

LDAP/Active Directory

user do a login during this time, nothing will be checked or updated. Here is a second
mechanism to update user membership: If somebody adds a new Group in the OBS, the
member attributes of the group are parsed and all current users which are in the local
database become members.

3.7.4.1

OBS LDAP Configuration

Currently the main OBS LDAP configuration is in the le options.yml . Beside the settings in

that le, the openLDAP configuration le is also evaluated by the Ruby LDAP implementation.
This configuration le is usually located at /etc/openldap/ldap.conf . You can set here additional TLS/SSL directives like TLS_CACERT , TLS_CACERTDIR and TLS_REQCERT . For more
information refer to the openLDAP man page ( man ldap.conf ).

Note
When LDAP mode is activated, users can only log in via LDAP. This also includes existing
admin accounts. To make a LDAP user an admin, use a rake task which can be run on the
OBS instance. For example, to make user tux , use:
cd /srv/www/obs/api
bundle exec rake user:give_admin_rights tux RAILS_ENV=production

TABLE 3.4: LDAP CONFIGURATION OPTIONS

Config item

Description

Values de-

Remarks

fault

ldap_mode

OBS LDAP mode on/

ldap_servers

List of LDAP servers

ldap_max_attempts

tries to ping LDAP

int 15

ldap_search_timeout

timeout of an LDAP

int 0…N 5

84

o

server

search

:off :on

colon-separated list

0 wait for ever

LDAP/Active Directory

Config item

Description

Values de-

Remarks

fault

ldap_user_memberof_attr

User attribute for

memberOf

ldap_group_member_attr

Group attribute for

member

ldap_ssl

use ldaps port and pro-

:off :on

ldap_start_tls

usr Start TLS on LDAP

:o :on

ldap_port

LDAP portnumbers

ldap_referrals

Windows 2003 AD re-

:off :on

ldap_search_base

company’s LDAP

none

Group membership
members
tocol

protocol

quires

search base for the

case sensitive

if not set 389 for

LDAP, 636 for LDAPS

users who will use OBS
ldap_search_attr

user ID attribute

ldap_name_attr

Full user name

cn

ldap_mail_attr

Attribute for users

mail

ldap_search_user

Bind user for LDAP

email

search

sAMAccount-

Name uid

sAMAccountName for
AD, uid for openldap

for example, cn=ldapbind, ou=sys-

tem, dc=mycompany,
dc=com

85

LDAP/Active Directory

Config item

Description

Values de-

Remarks

fault

ldap_search_auth

Password for the

ldap_user_filter

Search filter for OBS

ldap_search_user

for example, a group

users

membership, empty all
users allowed

ldap_authenticate

How user how the cre-

:ldap :local

only use :ldap

ldap_auth_mech

Used auth mech

:md5 :cleart-

only if local

ldap_auth_attr

Used auth attribute

userPass-

do not use

dentials are verified

ext

for :local

word

ldap_group_support

Import OBS groups

:off

ldap_group_search_base

company’s LDAP

ldap_group_title_attr

Attribute of the group

from LDAP

search base for groups
name

ldap_group_objectclass_at- Object class for group
tr

ldap_obs_admin_group

:on :mirror

see text

Group name for OBS
Admins

cn

Group

if set, members of that

group become OBS admin role

Example LDAP section of the options.yml le:
[...]
##################
# LDAP options
##################

86

LDAP/Active Directory

ldap_mode: :on
# LDAP Servers separated by ':'.
# OVERRIDE with your company's ldap servers. Servers are picked randomly for
# each connection to distribute load.
ldap_servers: ldap1.mycompany.com:ldap2.mycompany.com
# Max number of times to attempt to contact the LDAP servers
ldap_max_attempts: 15
# timeout of an ldap search requests to avoid infinitely lookups (in seconds, 0 no
timeout)
ldap_search_timeout: 5
# The attribute the user member of is stored in (case sensitive !)
ldap_user_memberof_attr: memberOf
# Perform the group_user search with the member attribute of group entry or memberof
attribute of user entry
# It depends on your ldap define
# The attribute the group member is stored in
ldap_group_member_attr: member
# If you're using ldap_authenticate=:ldap then you should ensure that
# ldaps is used to transfer the credentials over SSL or use the StartTLS extension
ldap_ssl: :on
# Use StartTLS extension of LDAP
ldap_start_tls: :off
# LDAP port defaults to 636 for ldaps and 389 for ldap and ldap with StartTLS
#ldap_port:
# Authentication with Windows 2003 AD requires
ldap_referrals: :off
# OVERRIDE with your company's ldap search base for the users who will use OBS
ldap_search_base: ou=developmentt,dc=mycompany,dc=com
# Account name attribute (sAMAccountName for Active Directory, uid for openLDAP)
ldap_search_attr: sAMAccountName
# The attribute the users name is stored in
ldap_name_attr: cn
# The attribute the users email is stored in
ldap_mail_attr: mail
# Credentials to use to search ldap for the username
ldap_search_user: "cn=ldapbind,ou=system,dc=mycompany,dc=com"
ldap_search_auth: "top secret"

87

LDAP/Active Directory

# By default any LDAP user can be used to authenticate to the OBS
# In some deployments this may be too broad and certain criteria should
# be met; eg group membership
#
# To allow only users in a specific group uncomment this line:
ldap_user_filter: (memberof=cn=obsusers,ou=groups,dc=mycompany,dc=com)
#
# Note this is joined to the normal selection like so:
# (&(#{dap_search_attr}=#{login})#{ldap_user_filter})
# giving an ldap search of:
#

(&(sAMAccountName=#{login})(memberof=CN=group,OU=Groups,DC=Domain Component))

#
# Also note that openLDAP must be configured to use the memberOf overlay
# ldap_authenticate says how the credentials are verified:
#

:ldap = attempt to bind to ldap as user using supplied credentials

#

:local = compare the credentials supplied with those in

#

LDAP using #{ldap_auth_attr} & #{ldap_auth_mech}

#

if :local is used then ldap_auth_mech can be

#

:md5

#

:cleartext

ldap_authenticate: :ldap
ldap_auth_mech: :md5
# This is a string
ldap_auth_attr: userPassword
# Whether to search group info from ldap, it does not take effect it is not set
# Please also set below ldap_group_* configs correctly to ensure the operation works
properly
# Possible values:
#

:off

disabled

#

:on

enabled; every group member operation ask the LDAP server

#

:mirror

enabled; group membership is mirrored and updated on user login

#
ldap_group_support: :mirror
# OVERRIDE with your company's ldap search base for groups
ldap_group_search_base: ou=obsgroups,dc=mycompany,dc=com
# The attribute the group name is stored in
ldap_group_title_attr: cn
# The value of the group objectclass attribute
# group for Active Directory, groupOfNames in openLDAP
ldap_group_objectclass_attr: group
# The LDAP group for obs admins

88

LDAP/Active Directory

# if this group is set and a user belongs to this group they get the global admin role
#
ldap_obs_admin_group: obsadmins

3.7.5

3.7.5.1

Authentication Methods

LDAP Methods

The LDAP mode has 2 methods to check authorization:
1. LDAP bind method. With the provided credentials, an LDAP bind request is tried.
2. Local method. The provided credentials checked locally against the content of the user-

Password attribute.

Important
The local method should be not used, since the userPassword attribute in most LDAP
installations will not be available until you are bind with a privilege user.

3.7.5.2

Kerberos

In OBS you can use single sign on via Kerberos tickets.
OBS Kerberos configuration resides in the options.yml le.
TABLE 3.5: KERBEROS CONFIGURATION OPTIONS

Config item

Description

Example

kerberos_keytab

Kerberos key table: le where long-

"/etc/krb5.keytab"

term keys for one or more principals
are stored

kerberos_service_principal

89

Kerberos OBS principal: OBS unique

"HTTP/hostname.ex-

sign tickets

PLE.COM"

identity to which Kerberos can as-

ample.com@EXAM-

Authentication Methods

Config item

Description

Example

kerberos_realm

Kerberos realm: authentication ad-

"EXAMPLE.COM"

ministrative domain

Example Kerberos section of the options.yml le:
[...]
##################
# Kerberos options
##################
kerberos_mode: true
kerberos_keytab: "/etc/krb5.keytab"
kerberos_service_principal: "HTTP/hostname.example.com@EXAMPLE.COM"
kerberos_realm: "EXAMPLE.COM"
[...]

Note
Once Kerberos is enabled, only users with logins that match users known to Kerberos will
be able to authenticate to OBS. It is recommended to give admin rights to a matching
user before enabling Kerberos mode.

3.7.5.3

OBS Token Authorization

OBS 2.5 provides a mechanism to create tokens for specific operations. This can be used to allow

certain operations in the name of a user to others. This is esp. useful when integrating external
infrastructure. The create token should be kept secret by default, but it can also be revoked at
any time if it became obsolete or leaked.

3.7.5.3.1

Managing Tokens of a User

Tokens belong always to a user. A list of active tokens can received via
osc token
osc token --delete 

90

Authentication Methods

3.7.5.3.2

Executing a Source Service

A token can be used to execute a source service. The source service has to be setup for the
package rst, check the source service chapter for this. A typical example is to update sources
of a package from git. A source service for that can be setup with
osc add git://....

A token can be registered as generic token, means allowing to execute all source services in OBS
if the user has permissions. You can create such a token and execute the operation with
osc token --create
osc token --trigger   
osc api -X POST /trigger/runservice?token=&project=&package=

You can also limit the token to a specific package. The advantage is that the operation is limited
to that package, so less bad things can happen when the token leaks. Also you do not need to
specify the package on execution time. Create and execute it with
osc token --create  
osc token --trigger 
osc api -X POST /trigger/runservice?token=

3.8 Message Bus for Event Notifications
The OBS has an integrated notification subsystem for sending events that are happening in our
app through a message bus. We have chosen RabbitMQ (https://www.rabbitmq.com/)
message bus server technology based on the AMQP (https://www.amqp.org/)

3.8.1

protocol.

as our

RabbitMQ

RabbitMQ claims to be "the most popular open source message broker". Meaning that it can deliver

asynchronous messages in many different exchange ways (one to one, broadcasting, based on
topics). It also includes a flexible routing system based on queues.

91

Message Bus for Event Notifications

RabbitMQ is lightweight and easy to deploy on premises and in the cloud. It supports multiple

messaging protocols too. And can be deployed in distributed and federated configurations to
meet high-scale, high-availability requirements.

3.8.1.1

Configuration

Currently the RabbitMQ configuration is in the le options.yml . All those options there start

with the prefix amqp. These configuration items match with some of the calls we do using the
Bunny (http://rubybunny.info/)

gem.

TABLE 3.6: RABBITMQ CONFIGURATION OPTIONS

Config item

Description

Values de-

Remarks

fault

amqp_namespace
amqp_options

Namespace for the

queues of this instance

'opensuse.obs'

Connection configura-

Is a prefix for the
queue names

See this guide (http://

tion

rubybunny.info/articles/connecting.html)

to know which are the
parameters allowed.
amqp_options[host]

Server host

amqp_options[port]

Server port

amqp_options[user]

User account

amqp_options[pass]

Account password

amqp_options[vhost]

Virtual host

amqp_exchange_name

Name for the exchange

92

A valid hostname
5672

RabbitMQ

Config item

Description

Values de-

Remarks

fault

amqp_exchange_options

Exchange configura-

See this guide (http://

tion

rubybunny.info/articles/exchanges.html)

to know more about
exchanges.
amqp_exchange_option-

Type of comunication

direct

amqp_exchange_option-

If set, the exchange

false

s[type]

s[auto_delete]

for the exchange

is deleted when all

queues have finished
using it

amqp_exchange_option-

More configuration for

amqp_queue_options

Queues configuration

s[arguments]

plugins / extensions

See this guide (http://
rubybunny.info/articles/queues.html)

to know more about
queues.
amqp_queue_option-

Should this queue be

false

amqp_queue_options[au-

Should this queue be

false

s[durable]
to_delete]

durable?

automatically delet-

ed when the last consumer disconnects?

amqp_queue_options[exclusive]

93

Should this queue be
exclusive (only can

false

be used by this con-

RabbitMQ

Config item

Description

Values de-

Remarks

fault

nection, removed

when the connection is
closed)?
amqp_queue_options[arguments]

Additional optional

arguments (typically

used by RabbitMQ extensions and plugins)

Example of the RabbitMQ section of the options.yml le:
[...]
# RabbitMQ based message bus
#
# Prefix of the message bus rooting key
amqp_namespace: 'opensuse.obs'
# Connection options -> http://rubybunny.info/articles/connecting.html
amqp_options:
host: rabbit.example.com
port: 5672
user: guest
pass: guest
vhost: /vhost
# Exchange options -> http://rubybunny.info/articles/exchanges.html
amqp_exchange_name: pubsub
amqp_exchange_options:
type: topic
auto_delete: false
arguments:
persistent: true
passive: true
# Queue options -> http://rubybunny.info/articles/queues.html
amqp_queue_options:
durable: false
auto-delete: false

94

RabbitMQ

exclusive: false
arguments:
extension_1: blah

TABLE 3.7: LIST OF EVENT MESSAGES / QUEUES FOR THE MESSAGE BUS

Queue Name

Description

Payload

__prefix__.package.build_success

A package build has succeeded

:reposito-

ry, :arch, :re-

lease, :readytime, :srcmd5, :rev, :reason, :bcnt, :veri-

fymd5, :hostarch, :starttime, :endtime, :work-

erid, :versrel, :previouslyfailed
__prefix__.package.build_fail

A package build has failed

:reposito-

ry, :arch, :re-

lease, :readytime, :srcmd5, :rev, :reason, :bcnt, :veri-

fymd5, :hostarch, :starttime, :endtime, :work-

erid, :versrel, :previouslyfailed, :faillog
__prefix__.package.build_unchanged

A package build has succeeded
with unchanged result

:reposito-

ry, :arch, :re-

lease, :readytime, :srcmd5, :rev, :reason, :bcnt, :veri-

fymd5, :hostarch, :starttime, :end-

95

RabbitMQ

Queue Name

Description

Payload
time, :work-

erid, :versrel, :previouslyfailed
__prefix__.package.create

A new package was created

:project, :pack-

__prefix__.package.update

The package metada was updat- :project, :packed

age, :sender

__prefix__.package.delete

A package was deleted

:project, :pack-

age, :sender

age, :sender, :comment

__prefix__.package.undelete

A package was undeleted

:project, :pack-

age, :sender, :comment

__prefix__.package.branch

A package was branched

:project, :pack-

age, :sender, :targetproject, :targetpackage, :user

__prefix__.package.commit

A package has committed
changes

:project, :pack-

age, :sender, :commen-

t, :user, :les, :rev, :requestid
__prefix__.package.upload

Sources of a package were uploaded

:project, :pack-

age, :sender, :com-

ment, :filename, :requestid, :target, :user

96

RabbitMQ

Queue Name

Description

Payload

__prefix__.package.service_success

Source service succeeded for a

:commen-

package

t, :project, :pack-

age, :sender, :rev, :user, :requestid

__prefix__.package.service_fail

Source service failed for a package

:comment, :er-

ror, :project, :pack-

age, :sender, :rev, :user, :requestid

__prefix__.package.version_change

A package has changed its version

:project, :pack-

age, :sender, :comment, :re-

questid, :les, :rev, :newversion, :user, :oldversion
__prefix__.package.comment

A new comment for the package was created

:project, :pack-

age, :sender, :commenters, :com-

menter, :comment_body, :comment_title
__prefix__.project.create

A new project was created

:project, :sender

__prefix__.project.update_project_conf The project configuration was

:project, :sender, :les, :com-

__prefix__.project.update

A project was updated

:project, :sender

__prefix__.project.delete

A project was deleted

:project, :commen-

__prefix__.project.undelete

A project was undeleted

:project, :commen-

updated

97

ment

t, :requestid, :sender
t, :sender

RabbitMQ

Queue Name

Description

Payload

__prefix__.project.comment

A new comment for the project

:project, :com-

was created

menters, :com-

menter, :comment_body, :comment_title

__prefix__.repo.packtrack

Binary was published in the

:project, :repo, :pay-

__prefix__.repo.publish_state

Publish State of Repository has

:project, :repo, :s-

__prefix__.repo.published

A repository was published

:project, :repo

__prefix__.request.create

A request was created

:author, :com-

repository
changed

load
tate

ment, :description, :num-

ber, :actions, :s-

tate, :when, :who, :diff (local projects)
__prefix__.request.change

A request was changed (admin
only)

:author, :com-

ment, :description, :num-

ber, :actions, :s-

tate, :when, :who
__prefix__.request.delete

A request was deleted

:author, :com-

ment, :description, :num-

ber, :actions, :s-

tate, :when, :who
__prefix__.request.state_change

98

The state of a request was
changed

:author, :com-

ment, :description, :num-

RabbitMQ

Queue Name

Description

Payload
ber, :actions, :s-

tate, :when, :who, :oldstate
__prefix__.request.review_wanted

A request requires a review

:author, :com-

ment, :description, :num-

ber, :actions, :s-

tate, :when, :who, :reviewer-

s, :by_user, :by_group, :by_project,
age, :diff (local
projects)
__prefix__.request.comment

A new comment for the request
was created

:author, :com-

ment, :description, :num-

ber, :actions, :s-

tate, :when, :who, :commenters, :commenter, :com-

ment_body, :comment_title, :request_number

3.9 Backup
3.10 Spider Identification
OBS is hiding specific parts/pages of the application from search crawlers (duckduckgo, google
etc.), mostly for performance reasons. Which user-agent strings are identified as crawlers configured in the le /srv/www/obs/api/config/crawler-user-agents.json .

99

Backup

To update that list, you must run the command bundle exec rake voight_kampf:im-

port_user_agents in the root directory of your OBS instance. This downloads the current

crawler list of user agents as a JSON le into the config/ directory of the Rails application.

If you want to extend or edit this list, switch to the config/ directory and open the crawleruser-agents.json le with the editor of your choice. The content can look like this:
[
{
"pattern": "Googlebot\\/",
"url": "http://www.google.com/bot.html"
},
{
"pattern": "Googlebot-Mobile"
},
{
"pattern": "Googlebot-Image"
},
[...]
]

To add a new bot to this list, a pattern must be defined. This is required to identify a bot. Almost
all bots have their own user agent that they are sending to a Web server to identify them. For
example, the user agent of the Googlebot looks like this:

Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)

To choose the pattern for the new bot, compare the user agent of the bot you want to identify

with others and look for a part that is unique (like in the Googlebot example, the part: Googlebot).

Let's assume we want to add the bot Geekobot to the list of bots and the user agent looks like this:
Mozilla/5.0 (compatible; Geekobot/2.1; +https://www.opensuse.org)

Our unique part would be Geekobot. So we add a new entry to the list of bots:
[
{
"pattern": "Googlebot\\/",
"url": "http://www.google.com/bot.html"
},
{
"pattern": "Googlebot-Mobile"
},

100

Spider Identification

{
"pattern": "Googlebot-Image"
},
[...]
{
"pattern": "Geekobot"
}
]

Note
You can also use regular expressions in the pattern element.
Save the le and restart the Rails application and the bot Geekobot should be identified properly.

101

Spider Identification

4 Troubleshooting
Here are two major classes of problems regarding the Open Build Service:
1. Normal package build errors
2. Bugs, resource shortage or config issues caused issues

The rst category are errors like missing dependent packages in the build environment, errors

during compiling or linking, errors in the build description and so on. Most of them should not

happen if the packager does test the build locally before committing it to the OBS. This type of
problems is not covered by this chapter.

4.1 General Hints
If you detect unexpected behavior of the open build service, you should follow some rules to
locate the problem:

1. Consult the log les, for the back-end look at /srv/obs/log for the back-end log les and /

srv/www/obs/api/log for the front-end log les. See the Log les Section 2.2, “Log Files” for
more details.

2. Consult the normal OS system logs and the kernel log (dmesg) if here are reported system

or HW problems.

3. Check if all services are running on the back-end and front-end. See the OBS Architecture

in reference book for details.

4. Try to nd an easy way to reproduce the problem.
5. To check whether this issue was already reported, see https://github.com/openSUSE/openbuild-service

.

6. Use search machines (Google) to nd out if others did also run into this problem. If you

are lucky, you will nd a x or workaround as well.

7. If you create a new bug report, include all information to reproduce the problem and the

complete error message/error log if here are any.

102

General Hints

4.2 Debugging Front-end Problems
If you get unexpected results from submitting commands with the osc tool, you can use the
debug feature of the tools to nd more information about what happened.
osc debug options
--debugger

jump into the debugger before executing anything

--post-mortem

jump into the debugger in case of errors

-t, --traceback

print call trace in case of errors

-H, --http-debug

debug HTTP traffic (filters some headers)

--http-full-debug

debug HTTP traffic (filters no headers)

-d, --debug

print info useful for debugging

The --debugger and --post-mortem are only suitable for osc developers. If you get an error

message from osc, the -t, --traceback can give the developer some more information about the
problem. The -H, --http-debug and --http-full-debug options are useful to see the raw answers
of OBS API, often this gives a hint what maybe wrong. If you report a problem regarding the osc

tool, it may help to include the osc output with additional *--http-debug --traceback options.

Warning
With --http-full-debug all http headers are included, this may include user data and

authentication stu so review and replace such data with XXXXXXXX or so before you
post it on the internet.

103

Debugging Front-end Problems

A GNU Licenses
This appendix contains the GNU General Public License version 2 and the GNU Free Documentation License version 1.2.

Activities other than copying, distribution and modification are not covered by this License;

they are outside its scope. The act of running the Program is not restricted, and the output
from the Program is covered only if its contents constitute a work based on the Program

(independent of having been made by running the Program). Whether that is true depends
on what the Program does.
1.

You may copy and distribute verbatim copies of the Program’s source code as you receive

GNU General Public License

it, in any medium, provided that you conspicuously and appropriately publish on each copy

Version 2, June 1991

an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that

Copyright (C) 1989, 1991 Free Software Foundation, Inc. 59 Temple Place - Suite 330, Boston,
MA 02111-1307, USA

Everyone is permitted to copy and distribute verbatim copies of this license document, but
changing it is not allowed.

Preamble

refer to this License and to the absence of any warranty; and give any other recipients of the
Program a copy of this License along with the Program.
You may charge a fee for the physical act of transferring a copy, and you may at your option
offer warranty protection in exchange for a fee.

You may modify your copy or copies of the Program or any portion of it, thus forming

The licenses for most software are designed to take away your freedom to share and change it.

2.

and change free software--to make sure the software is free for all its users. This General Public

a work based on the Program, and copy and distribute such modifications or work under the

whose authors commit to using it. (Some other Free Software Foundation software is covered

terms of Section 1 above, provided that you also meet all of these conditions:

When we speak of free software, we are referring to freedom, not price. Our General Public

a).

By contrast, the GNU General Public License is intended to guarantee your freedom to share

License applies to most of the Free Software Foundation’s software and to any other program
by the GNU Library General Public License instead.) You can apply it to your programs, too.

Licenses are designed to make sure that you have the freedom to distribute copies of free

software (and charge for this service if you wish), that you receive source code or can get it

if you want it, that you can change the software or use pieces of it in new free programs; and
that you know you can do these things.

You must cause the modified les to carry prominent notices stating that you changed

the les and the date of any change.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights

b). You must cause any work that you distribute or publish, that in whole or in part contains

you if you distribute copies of the software, or if you modify it.

or is derived from the Program or any part thereof, to be licensed as a whole at no charge to

or to ask you to surrender the rights. These restrictions translate to certain responsibilities for
For example, if you distribute copies of such a program, whether gratis or for a fee, you must
give the recipients all the rights that you have. You must make sure that they, too, receive or

all third parties under the terms of this License.

can get the source code. And you must show them these terms so they know their rights.

If the modified program normally reads commands interactively when run, you must

We protect your rights with two steps: (1) copyright the software, and (2) offer you this license

c).

Also, for each author’s protection and ours, we want to make certain that everyone under-

cause it, when started running for such interactive use in the most ordinary way, to print or

else and passed on, we want its recipients to know that what they have is not the original, so

display an announcement including an appropriate copyright notice and a notice that there

Finally, any free program is threatened constantly by software patents. We wish to avoid the

is no warranty (or else, saying that you provide a warranty) and that users may redistribute

making the program proprietary. To prevent this, we have made it clear that any patent must

the program under these conditions, and telling the user how to view a copy of this License.

which gives you legal permission to copy, distribute and/or modify the software.

stands that there is no warranty for this free software. If the software is modified by someone
that any problems introduced by others will not reflect on the original authors’ reputations.

danger that redistributors of a free program will individually obtain patent licenses, in effect
be licensed for everyone’s free use or not licensed at all.

The precise terms and conditions for copying, distribution and modification follow.

GNU GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR
COPYING, DISTRIBUTION AND MODIFICATION
0.

This License applies to any program or other work which contains a notice placed by the

copyright holder saying it may be distributed under the terms of this General Public License.
The “Program”, below, refers to any such program or work, and a “work based on the Program” means either the Program or any derivative work under copyright law: that is to say,
a work containing the Program or a portion of it, either verbatim or with modifications and/
or translated into another language. (Hereinafter, translation is included without limitation
in the term “modification”.) Each licensee is addressed as “you”.

(Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)
These requirements apply to the modified work as a whole. If identifiable sections of that

work are not derived from the Program, and can be reasonably considered independent and

separate works in themselves, then this License, and its terms, do not apply to those sections
when you distribute them as separate works. But when you distribute the same sections as

part of a whole which is a work based on the Program, the distribution of the whole must be
on the terms of this License, whose permissions for other licensees extend to the entire whole,
and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest your rights to work written
entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.

In addition, mere aggregation of another work not based on the Program with the Program

(or with a work based on the Program) on a volume of a storage or distribution medium does
not bring the other work under the scope of this License.
3.

You may copy and distribute the Program (or a work based on it, under Section 2) in

object code or executable form under the terms of Sections 1 and 2 above provided that you
also do one of the following:

104

Accompany it with the complete corresponding machine-readable source code, which

court order, agreement or otherwise) that contradict the conditions of this License, they do

must be distributed under the terms of Sections 1 and 2 above on a medium customarily used

not excuse you from the conditions of this License. If you cannot distribute so as to satisfy

for software interchange; or,

simultaneously your obligations under this License and any other pertinent obligations, then

a).

b).

Accompany it with a written offer, valid for at least three years, to give any third party,

for a charge no more than your cost of physically performing source distribution, a complete
machine-readable copy of the corresponding source code, to be distributed under the terms
of Sections 1 and 2 above on a medium customarily used for software interchange; or,
c). Accompany it with the information you received as to the offer to distribute corresponding

source code. (This alternative is allowed only for noncommercial distribution and only if you
received the program in object code or executable form with such an offer, in accord with
Subsection b above.)
The source code for a work means the preferred form of the work for making modifications

to it. For an executable work, complete source code means all the source code for all modules

it contains, plus any associated interface definition les, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code

as a consequence you may not distribute the Program at all. For example, if a patent license
would not permit royalty-free redistribution of the Program by all those who receive copies
directly or indirectly through you, then the only way you could satisfy both it and this License
would be to refrain entirely from distribution of the Program.
If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended
to apply in other circumstances.

It is not the purpose of this section to induce you to infringe any patents or other property

right claims or to contest validity of any such claims; this section has the sole purpose of
protecting the integrity of the free software distribution system, which is implemented by

public license practices. Many people have made generous contributions to the wide range of
software distributed through that system in reliance on consistent application of that system;

it is up to the author/donor to decide if he or she is willing to distribute software through any
other system and a licensee cannot impose that choice.

This section is intended to make thoroughly clear what is believed to be a consequence of
the rest of this License.

distributed need not include anything that is normally distributed (in either source or binary

8.

which the executable runs, unless that component itself accompanies the executable.

patents or by copyrighted interfaces, the original copyright holder who places the Program

form) with the major components (compiler, kernel, and so on) of the operating system on

If distribution of executable or object code is made by offering access to copy from a designated

If the distribution and/or use of the Program is restricted in certain countries either by

place, then offering equivalent access to copy the source code from the same place counts

under this License may add an explicit geographical distribution limitation excluding those

source along with the object code.

countries, so that distribution is permitted only in or among countries not thus excluded. In

as distribution of the source code, even though third parties are not compelled to copy the

4.

You may not copy, modify, sublicense, or distribute the Program except as expressly

provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute
the Program is void, and will automatically terminate your rights under this License. However,
parties who have received copies, or rights, from you under this License will not have their
licenses terminated so long as such parties remain in full compliance.

such case, this License incorporates the limitation as if written in the body of this License.

9.

The Free Software Foundation may publish revised and/or new versions of the General

Public License from time to time. Such new versions will be similar in spirit to the present
version, but may differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the Program specifies a version
number of this License which applies to it and “any later version”, you have the option of

5. You are not required to accept this License, since you have not signed it. However, nothing

else grants you permission to modify or distribute the Program or its derivative works. These
actions are prohibited by law if you do not accept this License. Therefore, by modifying or
distributing the Program (or any work based on the Program), you indicate your acceptance
of this License to do so, and all its terms and conditions for copying, distributing or modifying
the Program or works based on it.
6. Each time you redistribute the Program (or any work based on the Program), the recipient

automatically receives a license from the original licensor to copy, distribute or modify the
Program subject to these terms and conditions. You may not impose any further restrictions
on the recipients’ exercise of the rights granted herein. You are not responsible for enforcing
compliance by third parties to this License.

following the terms and conditions either of that version or of any later version published
by the Free Software Foundation. If the Program does not specify a version number of this
License, you may choose any version ever published by the Free Software Foundation.
10.

If you wish to incorporate parts of the Program into other free programs whose distrib-

ution conditions are different, write to the author to ask for permission. For software which
is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we
sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and
reuse of software generally.

NO WARRANTY
11.

BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRAN-

TY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT

If, as a consequence of a court judgment or allegation of patent infringement or for

WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER

any other reason (not limited to patent issues), conditions are imposed on you (whether by

PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER

7.

105

EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES

interest in the program `Gnomovision’
(which makes passes at compilers) written
by James Hacker.

OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
signature of Ty Coon, 1 April 1989

TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.

12.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING

WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR

Ty Coon, President of Vice

This General Public License does not permit incorporating your program into proprietary

programs. If your program is a subroutine library, you may consider it more useful to permit
linking proprietary applications with the library. If this is what you want to do, use the GNU
Lesser General Public License (http://www.fsf.org/licenses/lgpl.html)

instead of this License.

GNU Free Documentation License
Version 1.2, November 2002

REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAM-

Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. 59 Temple Place, Suite 330,

AGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES

Everyone is permitted to copy and distribute verbatim copies of this license document, but

ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT
LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH
ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED
OF THE POSSIBILITY OF SUCH DAMAGES.

Boston, MA 02111-1307 USA
changing it is not allowed.

PREAMBLE
The purpose of this License is to make a manual, textbook, or other functional and useful
document “free” in the sense of freedom: to assure everyone the effective freedom to copy
and redistribute it, with or without modifying it, either commercially or noncommercially.

Secondarily, this License preserves for the author and publisher a way to get credit for their
work, while not being considered responsible for modifications made by others.

This License is a kind of “copyleft”, which means that derivative works of the document must

themselves be free in the same sense. It complements the GNU General Public License, which

END OF TERMS AND CONDITIONS

is a copyleft license designed for free software.

We have designed this License in order to use it for manuals for free software, because free

software needs free documentation: a free program should come with manuals providing the

How to Apply These Terms to Your New Programs
If you develop a new program, and you want it to be of the greatest possible use to the public,
the best way to achieve this is to make it free software which everyone can redistribute and
change under these terms.

To do so, attach the following notices to the program. It is safest to attach them to the start
of each source le to most effectively convey the exclusion of warranty; and each le should
have at least the “copyright” line and a pointer to where the full notice is found.
one line to give the program’s name and an idea of what it does.
Copyright (C) yyyy name of author
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

same freedoms that the software does. But this License is not limited to software manuals; it

can be used for any textual work, regardless of subject matter or whether it is published as a

printed book. We recommend this License principally for works whose purpose is instruction
or reference.

APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work, in any medium, that contains a notice placed
by the copyright holder saying it can be distributed under the terms of this License. Such a

notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under
the conditions stated herein. The “Document”, below, refers to any such manual or work. Any
member of the public is a licensee, and is addressed as “you”. You accept the license if you
copy, modify or distribute the work in a way requiring permission under copyright law.

A “Modified Version” of the Document means any work containing the Document or a portion
of it, either copied verbatim, or with modifications and/or translated into another language.

A “Secondary Section” is a named appendix or a front-matter section of the Document that

deals exclusively with the relationship of the publishers or authors of the Document to the

Document’s overall subject (or to related matters) and contains nothing that could fall directly

GNU General Public License for more details.

within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a

You should have received a copy of the GNU General Public License

of historical connection with the subject or with related matters, or of legal, commercial,

along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Also add information on how to contact you by electronic and paper mail.
If the program is interactive, make it output a short notice like this when it starts in an interactive mode:

Gnomovision version 69, Copyright (C) year name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
type `show w’. This is free software, and you are welcome

Secondary Section may not explain any mathematics.) The relationship could be a matter
philosophical, ethical or political position regarding them.

The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being
those of Invariant Sections, in the notice that says that the Document is released under this

License. If a section does not t the above definition of Secondary then it is not allowed to be
designated as Invariant. The Document may contain zero Invariant Sections. If the Document
does not identify any Invariant Sections then there are none.

The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or

Back-Cover Texts, in the notice that says that the Document is released under this License. A

to redistribute it under certain conditions; type `show c’

Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.

for details.

A “Transparent” copy of the Document means a machine-readable copy, represented in a for-

The hypothetical commands `show w’ and `show c’ should show the appropriate parts of the

General Public License. Of course, the commands you use may be called something other than
`show w’ and `show c’; they could even be mouse-clicks or menu items--whatever suits your
program.

You should also get your employer (if you work as a programmer) or your school, if any, to
sign a “copyright disclaimer” for the program, if necessary. Here is a sample; alter the names:
Yoyodyne, Inc., hereby disclaims all copyright

106

mat whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic
paint programs or (for drawings) some widely available drawing editor, and that is suitable
for input to text formatters or for automatic translation to a variety of formats suitable for

input to text formatters. A copy made in an otherwise Transparent le format whose markup,
or absence of markup, has been arranged to thwart or discourage subsequent modification

by readers is not Transparent. An image format is not Transparent if used for any substantial
amount of text. A copy that is not “Transparent” is called “Opaque”.

Examples of suitable formats for Transparent copies include plain ASCII without markup, Tex-

MODIFICATIONS

dard-conforming simple HTML, PostScript or PDF designed for human modification. Examples

You may copy and distribute a Modified Version of the Document under the conditions of

info input format, LaTeX input format, SGML or XML using a publicly available DTD, and stanof transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary
formats that can be read and edited only by proprietary word processors, SGML or XML for

which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.

The “Title Page” means, for a printed book, the title page itself, plus such following pages

as are needed to hold, legibly, the material this License requires to appear in the title page.
For works in formats which do not have any title page as such, “Title Page” means the text

near the most prominent appearance of the work’s title, preceding the beginning of the body
of the text.

sections 2 and 3 above, provided that you release the Modified Version under precisely this

License, with the Modified Version filling the role of the Document, thus licensing distribution
and modification of the Modified Version to whoever possesses a copy of it. In addition, you
must do these things in the Modified Version:

A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document,

and from those of previous versions (which should, if there were any, be listed in the History

A section “Entitled XYZ” means a named subunit of the Document whose title either is precise-

section of the Document). You may use the same title as a previous version if the original

(Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”,

publisher of that version gives permission.

ly XYZ or contains XYZ in parentheses following text that translates XYZ in another language.
“Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when
you modify the Document means that it remains a section “Entitled XYZ” according to this
definition.

The Document may include Warranty Disclaimers next to the notice which states that this

B. List on the Title Page, as authors, one or more persons or entities responsible for authorship

License applies to the Document. These Warranty Disclaimers are considered to be included

of the modifications in the Modified Version, together with at least ve of the principal authors

that these Warranty Disclaimers may have is void and has no effect on the meaning of this

of the Document (all of its principal authors, if it has fewer than ve), unless they release

by reference in this License, but only as regards disclaiming warranties: any other implication
License.

VERBATIM COPYING
You may copy and distribute the Document in any medium, either commercially or noncom-

you from this requirement.

C. State on the Title page the name of the publisher of the Modified Version, as the publisher.

mercially, provided that this License, the copyright notices, and the license notice saying this

License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct

or control the reading or further copying of the copies you make or distribute. However, you

D.

Preserve all the copyright notices of the Document.

may accept compensation in exchange for copies. If you distribute a large enough number of

E. Add an appropriate copyright notice for your modifications adjacent to the other copyright

You may also lend copies, under the same conditions stated above, and you may publicly

notices.

copies you must also follow the conditions in section 3.
display copies.

COPYING IN QUANTITY
If you publish printed copies (or copies in media that commonly have printed covers) of the

Document, numbering more than 100, and the Document’s license notice requires Cover Texts,
you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts:
Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers

F.

Include, immediately after the copyright notices, a license notice giving the public per-

mission to use the Modified Version under the terms of this License, in the form shown in
the Addendum below.

must also clearly and legibly identify you as the publisher of these copies. The front cover

G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts

add other material on the covers in addition. Copying with changes limited to the covers, as

given in the Document’s license notice.

must present the full title with all words of the title equally prominent and visible. You may
long as they preserve the title of the Document and satisfy these conditions, can be treated
as verbatim copying in other respects.

If the required texts for either cover are too voluminous to t legibly, you should put the

H.

Include an unaltered copy of this License.

rst ones listed (as many as t reasonably) on the actual cover, and continue the rest onto
adjacent pages.

If you publish or distribute Opaque copies of the Document numbering more than 100, you

I.

Preserve the section Entitled “History”, Preserve its Title, and add to it an item stating at

must either include a machine-readable Transparent copy along with each Opaque copy, or

least the title, year, new authors, and publisher of the Modified Version as given on the Title

work-using public has access to download using public-standard network protocols a complete

Page. If there is no section Entitled “History” in the Document, create one stating the title,

must take reasonably prudent steps, when you begin distribution of Opaque copies in quanti-

year, authors, and publisher of the Document as given on its Title Page, then add an item

at least one year after the last time you distribute an Opaque copy (directly or through your

describing the Modified Version as stated in the previous sentence.

state in or with each Opaque copy a computer-network location from which the general netTransparent copy of the Document, free of added material. If you use the latter option, you

ty, to ensure that this Transparent copy will remain thus accessible at the stated location until
agents or retailers) of that edition to the public.

It is requested, but not required, that you contact the authors of the Document well before

redistributing any large number of copies, to give them a chance to provide you with an
updated version of the Document.

J.

Preserve the network location, if any, given in the Document for public access to a Trans-

parent copy of the Document, and likewise the network locations given in the Document for
previous versions it was based on. These may be placed in the “History” section. You may
omit a network location for a work that was published at least four years before the Document
itself, or if the original publisher of the version it refers to gives permission.

107

K.

For any section Entitled “Acknowledgements” or “Dedications”, Preserve the Title of the

AGGREGATION WITH INDEPENDENT WORKS

section, and preserve in the section all the substance and tone of each of the contributor

A compilation of the Document or its derivatives with other separate and independent docu-

acknowledgements and/or dedications given therein.

gate” if the copyright resulting from the compilation is not used to limit the legal rights of the

L.

Preserve all the Invariant Sections of the Document, unaltered in their text and in their

titles. Section numbers or the equivalent are not considered part of the section titles.

ments or works, in or on a volume of a storage or distribution medium, is called an “aggrecompilation’s users beyond what the individual works permit. When the Document is included

in an aggregate, this License does not apply to the other works in the aggregate which are not
themselves derivative works of the Document.

If the Cover Text requirement of section 3 is applicable to these copies of the Document, then
if the Document is less than one half of the entire aggregate, the Document’s Cover Texts
may be placed on covers that bracket the Document within the aggregate, or the electronic

M.

Delete any section Entitled “Endorsements”. Such a section may not be included in the

Modified Version.

N.

Do not retitle any existing section to be Entitled “Endorsements” or to conflict in title

with any Invariant Section.

O.

Preserve any Warranty Disclaimers.

If the Modified Version includes new front-matter sections or appendices that qualify as Se-

condary Sections and contain no material copied from the Document, you may at your option
designate some or all of these sections as invariant. To do this, add their titles to the list of
Invariant Sections in the Modified Version’s license notice. These titles must be distinct from
any other section titles.

You may add a section Entitled “Endorsements”, provided it contains nothing but endorse-

ments of your Modified Version by various parties--for example, statements of peer review

equivalent of covers if the Document is in electronic form. Otherwise they must appear on
printed covers that bracket the whole aggregate.

TRANSLATION
Translation is considered a kind of modification, so you may distribute translations of the

Document under the terms of section 4. Replacing Invariant Sections with translations requires
special permission from their copyright holders, but you may include translations of some

or all Invariant Sections in addition to the original versions of these Invariant Sections. You
may include a translation of this License, and all the license notices in the Document, and

any Warranty Disclaimers, provided that you also include the original English version of this
License and the original versions of those notices and disclaimers. In case of a disagreement
between the translation and the original version of this License or a notice or disclaimer, the
original version will prevail.

If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”,

the requirement (section 4) to Preserve its Title (section 1) will typically require changing
the actual title.

or that the text has been approved by an organization as the authoritative definition of a

TERMINATION

You may add a passage of up to ve words as a Front-Cover Text, and a passage of up to 25

You may not copy, modify, sublicense, or distribute the Document except as expressly pro-

one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through

Document is void, and will automatically terminate your rights under this License. However,

same cover, previously added by you or by arrangement made by the same entity you are

licenses terminated so long as such parties remain in full compliance.

permission from the previous publisher that added the old one.

FUTURE REVISIONS OF THIS LICENSE

standard.

words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only

vided for under this License. Any other attempt to copy, modify, sublicense or distribute the

arrangements made by) any one entity. If the Document already includes a cover text for the

parties who have received copies, or rights, from you under this License will not have their

acting on behalf of, you may not add another; but you may replace the old one, on explicit

The author(s) and publisher(s) of the Document do not by this License give permission to use
their names for publicity for or to assert or imply endorsement of any Modified Version.

COMBINING DOCUMENTS

The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/
copyleft/.

You may combine the Document with other documents released under this License, under

Each version of the License is given a distinguishing version number. If the Document specifies

combination all of the Invariant Sections of all of the original documents, unmodified, and

have the option of following the terms and conditions either of that specified version or of

preserve all their Warranty Disclaimers.

the Document does not specify a version number of this License, you may choose any version

the terms defined in section 4 above for modified versions, provided that you include in the

that a particular numbered version of this License “or any later version” applies to it, you

list them all as Invariant Sections of your combined work in its license notice, and that you

any later version that has been published (not as a draft) by the Free Software Foundation. If

The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with

ever published (not as a draft) by the Free Software Foundation.

the same name but different contents, make the title of each such section unique by adding

ADDENDUM: How to use this License for your documents

known, or else a unique number. Make the same adjustment to the section titles in the list of

To use this License in a document you have written, include a copy of the License in the

at the end of it, in parentheses, the name of the original author or publisher of that section if
Invariant Sections in the license notice of the combined work.

In the combination, you must combine any sections Entitled “History” in the various original
documents, forming one section Entitled “History”; likewise combine any sections Entitled

“Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections
Entitled “Endorsements”.

COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other documents released under

this License, and replace the individual copies of this License in the various documents with a
single copy that is included in the collection, provided that you follow the rules of this License
for verbatim copying of each of the documents in all other respects.

You may extract a single document from such a collection, and distribute it individually under
this License, provided you insert a copy of this License into the extracted document, and follow
this License in all other respects regarding verbatim copying of that document.

document and put the following copyright and license notices just after the title page:
Copyright (c) YEAR YOUR NAME.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled “GNU
Free Documentation License”.

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the
“with...Texts.” line with this:

with the Invariant Sections being LIST THEIR TITLES, with the
Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.

If you have Invariant Sections without Cover Texts, or some other combination of the three,
merge those two alternatives to suit the situation.

If your document contains nontrivial examples of program code, we recommend releasing

these examples in parallel under your choice of free software license, such as the GNU General
Public License, to permit their use in free software.

108



---

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
Linearized                      : No
Page Count                      : 117
Profile CMM Type                : lcms
Profile Version                 : 2.1.0
Profile Class                   : Display Device Profile
Color Space Data                : RGB
Profile Connection Space        : XYZ
Profile Date Time               : 1998:02:09 06:49:00
Profile File Signature          : acsp
Primary Platform                : Apple Computer Inc.
CMM Flags                       : Not Embedded, Independent
Device Manufacturer             : IEC
Device Model                    : sRGB
Device Attributes               : Reflective, Glossy, Positive, Color
Rendering Intent                : Perceptual
Connection Space Illuminant     : 0.9642 1 0.82491
Profile Creator                 : lcms
Profile ID                      : 0
Profile Copyright               : Copyright (c) 1998 Hewlett-Packard Company
Profile Description             : sRGB IEC61966-2.1
Media White Point               : 0.95045 1 1.08905
Media Black Point               : 0 0 0
Red Matrix Column               : 0.43607 0.22249 0.01392
Green Matrix Column             : 0.38515 0.71687 0.09708
Blue Matrix Column              : 0.14307 0.06061 0.7141
Device Mfg Desc                 : IEC http://www.iec.ch
Device Model Desc               : IEC 61966-2.1 Default RGB colour space - sRGB
Viewing Cond Desc               : Reference Viewing Condition in IEC61966-2.1
Viewing Cond Illuminant         : 19.6445 20.3718 16.8089
Viewing Cond Surround           : 3.92889 4.07439 3.36179
Viewing Cond Illuminant Type    : D50
Luminance                       : 76.03647 80 87.12462
Measurement Observer            : CIE 1931
Measurement Backing             : 0 0 0
Measurement Geometry            : Unknown
Measurement Flare               : 0.999%
Measurement Illuminant          : D65
Technology                      : Cathode Ray Tube Display
Red Tone Reproduction Curve     : (Binary data 2060 bytes, use -b option to extract)
Green Tone Reproduction Curve   : (Binary data 2060 bytes, use -b option to extract)
Blue Tone Reproduction Curve    : (Binary data 2060 bytes, use -b option to extract)
Creator                         : Karsten Keil
Format                          : application/pdf
Title                           : Administrator Guide
Language                        : en
Date                            : 2018:01:29 12:08:01+01:00
Producer                        : Apache FOP Version 2.1
PDF Version                     : 1.4
Creator Tool                    : DAPS 2.4.0 using SUSE XSL Stylesheets 2.0.8 (based on DocBook XSL Stylesheets 1.78.1)
Metadata Date                   : 2018:01:29 12:08:01+01:00
Create Date                     : 2018:01:29 12:08:01+01:00
Page Mode                       : UseOutlines
Author                          : Karsten Keil

EXIF Metadata provided by EXIF.tools