Author: Stephen Quinney

# PkgForge Admin - Builders

A platform can have multiple package builders, this is particularly useful for handling periods of heavy load (e.g. when porting to a new platform). Adding and removing builders is very simple and can be done as long as the platform exists. For all the following operations you will need to have access to the Registry DB as the pkgforge_admin user.

## The builder admin tool

All package builder administration is done using the builder command of the `pkgforge` tool. This will be available on any machine which has the PkgForge-Registry software package installed, that includes the pkgforge master, website and all package builders.

If you need to know the list of available commands you can type:

    % pkgforge

and you will get a list like this:

    Available commands:

        commands: list the application's commands
            help: display a command's help screen

          buildd: Build the next job in the queue
         buildd2: Build the next job in the queue
         builder: Manage builder entries in the registry
        incoming: Process the incoming package queue
      initserver: Initialise the Package Forge server environment
        platform: Manage platform entries in the registry
          submit: Submit a set of source packages for building

Further to this you can get help for a command like this:

    % pkgforge help builder

Which will give the list of supported command-line options. For example:

    pkgforge builder [-?] [long options...]

    	--configfile        Configuration file
    	--name              Builder name
    	-? --usage --help   Prints this usage information.
    	--platform          Builder platform name
    	--architecture      Builder platform architecture

If you want to know the list of available sub-commands just enter the command without anything else, for example:

    % pkgforge builder

This gives the following output:

    You must specify an action from: add, delete, list

Not all sub-commands will require all command-line options. You will be prompted if anything which is required has not been specified.

### Configuration

By default the configuration for the Registry DB access is found in the `/etc/pkgforge/registry.yml` file. This can be changed using the `--configfile` command-line option. The contents of that file can be managed using the LCFG pkgforge component. Normally the contents should look something like:

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

For admin access to the PkgForge database you will need to configure the PostgreSQL `pg_ident.conf` and `pg_hba.conf` files to allow access to the pkgforge_admin user. This can be done in the LCFG profile for the host which holds the PkgForge Registry DB using the LCFG postgresql component like this:

    !postgresql.ident               mADD(pkgf1)
    postgresql.idmap_pkgf1          pkgforge
    postgresql.sysname_pkgf1        user1
    postgresql.pgname_pkgf1         pkgforge_admin

    !postgresql.hostssl             mADD(pkgf1)
    postgresql.ssldatabase_pkgf1    pkgforge
    postgresql.ssluser_pkgf1        pkgforge_admin
    !postgresql.ssladdress_pkgf1    mHOSTIP(host1.example.org)
    postgresql.sslnetmask_pkgf1     255.255.255.255
    postgresql.sslauthtype_pkgf1    krb5
    !postgresql.sslauthopt_pkgf1    mSET(map=<%postgresql.idmap_pkgf1%>)

Where `user1` is your system username and `host1.example.org` is your host name. This example users Kerberos authentication but a similar setup could be done using password authentication.

## List Current Builders

To list all the currently registered package builders use the following command:

    % pkgforge builder list

This will return a list which looks something like:

    Builder		Platform	Architecture
    =============================================
    bigfan_f13	f13		i386
    bigfan_f1364	f13		x86_64
    bressler_sl6	sl6		i386
    bressler_sl664	sl6		x86_64
    circle_sl564	sl5		x86_64
    elman_sl5	sl5		i386
    elman_sl564	sl5		x86_64
    gates_f13	f13		i386
    gates_f1364	f13		x86_64
    prague_sl5	sl5		i386

This is just the list of registered builders. It is possible that some of the builders are no longer active.

## Adding new Builders

Adding a new package builder for a platform is very straightforward. The name of the platform and the architecture for which you intend to build packages are required. A new unique name for the builder is also required, normally this is based on the name of the machine and the name of the platform (e.g. `bigfan_f13` or `bressler_sl664`).

    % pkgforge builder add --name bigfan_f13 --platform f13 --arch i386

Note that if a platform is not marked as active then new jobs will never be registered and the builder will not actually do anything.

Once a builder is added to the Registry database then ACLs must be added to the PostgreSQL configuration. Information on how to do this is given in the registry admin pages.

## Removing Builders

It is not necessary to ever remove builders from the database but it may be desirable for tidiness reasons. It is done like this:

    % pkgforge builder delete --name prague_sl5