Author: Stephen Quinney

# PkgForge Admin - Platforms

For all the following operations you will need to have access to the Registry DB as the pkgforge_admin user.

## The platform admin tool

All platform administration is done using the platform 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 platform

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

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

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

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

    % pkgforge platform

This gives the following output:

    You must specify an action from: activate, add, deactivate, list, setauto

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 Platforms

To list all the known platforms use the following command:

    % pkgforge platform list

This will return a list which looks something like:

    Name	Architecture	Active	Auto
    =====================================
    f13	i386		1	1
    f13	x86_64		1	1
    sl5	i386		1	1
    sl5	x86_64		1	1
    sl6	i386		1	0
    sl6	x86_64		1	0

If a platform is not marked as active then it is not possible to register new jobs. If it is marked as active but not auto then new jobs will be registered only when specifically requested, that platform will not be in the default set.

## Adding a new Platform

Adding a platform is very straightforward. The name of the platform and the architecture for which you intend to build packages are required, e.g. `f13` and `i386`. Unlike with LCFG the name of the platform is the same on all architectures. For example:

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

Once a platform is added you will need to make it active and add builders.

## Activating a Platform

If a platform is not marked as active then it will not be possible to register new build jobs. A new platform starts in the inactive state, once a platform is no longer supported it should be returned to the inactive state.

To activate a platform do something like the following example:

    % pkgforge platform activate --name f13 --arch i386

## Deactivating a Platform

If a platform is not marked as active then it will not be possible to register new build jobs. A new platform starts in the inactive state, once a platform is no longer supported it should be returned to the inactive state. Once jobs have been registered for a platform then to maintain referential integrity it is not possible to remove a platform from the DB, instead old platforms are just marked as inactive.

To deactivate a platform do something like the following example:

    % pkgforge platform deactivate --name f13 --arch i386

## Set a Platform to Automatic

Once a platform is marked as active it is possible to add new jobs by explicitly requesting the platform name or by using the all set of platforms. If a platform should be automatically included in the default set of platforms (i.e. when a user does not make a specific platform request then jobs will be registered for the platform) then it must be marked as auto. This is done like the following example:

    % pkgforge platform setauto --name f13 --arch i386

## Deleting a Platform

Once jobs have been registered for a platform then to maintain referential integrity it is not possible to remove a platform from the DB, instead old platforms should just be marked as inactive.