Package Forge - Registry Client Configuration

All access to the Package Forge database is done using the Perl DBI module. Although it is possible to do all queries and updates with raw SQL via that module it is not recommended. The PkgForge-Registry package comes with a complete set of Perl modules which provide an Object-Oriented interface to the registry database using the Perl DBIx::Class framework. Further to that layer of abstraction PkgForge provides a single PkgForge::Registry module which simplifies the configuration and loading of the DBIx::Class schema object.

Access to the PkgForge Registry database for each PkgForge handler (e.g. the incoming queue processor and the build daemons) can be configured in a number of ways. This configuration is done using the YAML files stored in the /etc/pkgforge/ directory.

Parameters

This is the complete list of parameters which can be configured for access to the registry database. You only need to specify the database name and any others which are appropriate.

name
This is the name of the database. This must be specified.
host
This is the host name of the database server. This is optional.
port
This is the port number on which the database server is listening. This is optional.
user
This is the user name with which to connect to the database. This is optional.
pass
This is the password with which to connect to the database. This is optional.

Manual Approach

The simplest approach is where all the necessary configuration for registry access is stored in /etc/pkgforge/registry.yml which is the default file. In this case the required attributes and values are just listed as a simple hash. Here is an example:

--- 
"host": 'pkgforge'
"name": 'pkgforge'
"user": 'pkgforge_admin'

Beyond that, the registry access can be configured via the appropriate handler-specific configuration files (e.g. /etc/pkgforge/buildd.yml or /etc/pkgforge/incoming.yml). Also, in the case of the build daemons there is a platform-specific configuration file (e.g. /etc/pkgforge/buildd-bressler_sl664.yml), any registry information in the platform-specific file will override that in the general build configuration file. In this case the configuration can be either a string or a reference to a hash. The simple string is considered to be the name of an alternative YAML file which contains the required access parameters. In the case of the reference to a hash, that is used as the set of attributes and values.

Here is an example for the incoming queue processor (/etc/pkgforge/incoming.yml). Only the registry section is important for this example:

--- 
"debug": 1
"init": '/etc/init.d/pkgforge-incoming'
"keytab": '/etc/pkgforge/pkgforge_incoming.keytab'
"registry": 
  "host": 'pkgforge'
  "name": 'pkgforge'
  "user": 'pkgforge_incoming'
"start": 'yes'

Here is an example for a build daemon (/etc/pkgforge/buildd.yml). Only the registry section is important for this example:

--- 
"debug": 1
"init": '/etc/init.d/pkgforge-buildd'
"keytab": '/etc/pkgforge/pkgforge_builder.keytab'
"registry": 
  "host": 'pkgforge'
  "name": 'pkgforge'
  "user": 'pkgforge_builder'
"start": 'yes'

Configuration using LCFG

If the LCFG pkgforge component is being used to configure the Package Forge handlers then the setup of the registry access is very simple. The following LCFG resources allow parameters to be set globally:

These map directly onto the attributes listed previously. In addition to this the db_user and db_pass resources can be overridden on a per-handler basis. It is not expected that the database name, host or port will need to be altered on a per-handler basis.

The lcfg/options/pkgforge-registry.h header contains the following default settings for the DB access parameters. The following examples show how these can be overridden on a per-handler basis. It is expected that normally you would just include the appropriate header and no extra configuration would be required for the handlers to access the registry.

#include <lcfg/options/pkgforge.h>

!pkgforge.db_name           mSET(pkgforge)
!pkgforge.db_host           mSET(pkgforge)
!pkgforge.db_user           mSET(pkgforge_admin)

The lcfg/options/pkgforge-master.h header then overrides the user name for the incoming queue processor like this:

!pkgforge.db_user_incoming  mSET(pkgforge_incoming)

Similarly the lcfg/options/pkgforge-builder.h overrides the user name for the build daemon to be: 

!pkgforge.db_user_buildd    mSET(pkgforge_builder)

Kerberos Access Configuration

The init-scripts for the PkgForge handlers have support for running the k5start daemon to manage a Kerberos credentials cache for each handler. This allows the daemons to have Kerberos-authenticated access to the registry database. You will need to create a keytab for each daemon. The LCFG kerberos component makes this very easy.

Here is an example, using the LCFG kerberos component.

#include <lcfg/options/pkgforge-builder.h>

pkgforge.keytab_buildd      <%pkgforge.configdir%>/pkgforge_builder.keytab

#include <lcfg/options/kerberos-client.h>

!kerberos.keys                       mADD(pkgforge_builder)
kerberos.keytab_pkgforge_builder     <%pkgforge.keytab_buildd%>
kerberos.keytabuid_pkgforge_builder  <%pkgforge.user%>
kerberos.keytabgid_pkgforge_builder  <%pkgforge.group%>

The pkgforge.keytab_buildd resource tells the build daemon init-script which keytab should be used when running k5start.

The principal will be named like pkgforge_builder/host1.example.org. The principal could be manually created and stored into a keytab using the kadmin command if you do not wish to use the LCFG kerberos component. Note that the UID and GID for the keytab MUST be correct or nothing will work.

The keytab file name is passed to the init-script via a sysconfig file. For build daemons this is /etc/sysconfig/pkgforge-buildd and for the incoming queue processor this is /etc/sysconfig/pkgforge-incoming. If configuring the system manually then the KRB5_KEYTAB shell variable must be set in the appropriate sysconfig file.