Setting Up a Koji Build System
The Koji components may live on seperate resources as long as all resources are able to communicate. This document will cover how to setup each service individually, however, all services may live on the same resource.
[[TableOfContents()]
PreReqs of Knowledge
- Basic understanding of SSL and authentication via certificates
- Basic knowledge about creating a database in PostgreSQL and importing a schema
- Working with psql
- Basic knowledge about Apache configuration
- Basic knowledge about yum/createrepo/mock - else you'll not be able to debug problems!
- Basic knowledge about using command line
- Basic knowledge about RPM building
PreReqs of Packages
On the server (koji-hub/koji-web)
- httpd
- mod_ssl
- postgresql-server
On the builder (koji-builder)
- mock
- setarch (for some archs you'll require a patched version)
- rpm-build
- createrepo
PostgreSQL Server
The PostgreSQL server must be installed and the database primed.
Configuration Files:
- /var/lib/pgsql/data/pg_hba.conf
- /var/lib/pgsql/data/postgresql.conf
Install PostgreSQL:
Setup PostgreSQL and populate schema:
$ createuser koji Shall the new role be a superuser? (y/n) n Shall the new role be allowed to create databases? (y/n) n Shall the new role be allowed to create more new roles? (y/n) n $ createdb -O koji koji $ psql koji koji < /usr/share/doc/koji*/docs/schema.sql $ exit
Authorize Koji-web and Koji-hub resources: In this example, Koji-web and Koji-hub are running on localhost.
/var/lib/pgsql/data/pg_hba.conf: These settings need to be valid and inline with other services configurations. Please note, the first matching auth line is used so this line must be above any other potential matches. Add:
host koji koji 127.0.0.1/32 trust
Make auth changes live:
$ pg_ctl reload $ exit
Koji Authentication Setup
Koji primarily supports Kerberos and SSL Certificate authentication. For basic koji-cli access, plain user/pass combinations are possible. For Kerberos authentication, a Kerberos server will need to be setup and configured. For SSL authentication, SSL certificates and the needed cert. chains will need to be setup.
Adding basic user/pass combinations for authentication: Any password setting/changing still needs to be done manually in the database though (it is not exposed through the API).
Add needed information to the koji database:
$ psql
koji=> insert into users (name, password, status, usertype) values ('my-user-name', 'my-password-in-plain-test', 0, 0);
koji=> insert into user_perms (user_id, perm_id) values (<id of user inserted above>, 1);
Note: you can get the ID of the new user by running the query:
koji=> select * from users;
You can then perform Koji admin commands by calling
$ koji --user <username> --password <password>"
Both kojira and kojid accept "user" and "password" options in their config files, and will use those for authentication if present. Note that for kojira, you will need to create a user:
$ koji add-user <username>
Set the password for it as above, as well as granting it the "repo" permission (perm_id == 3). For kojid you will need to create a "host" entry (koji add-host), and set the password for the associated user (the user gets created at the same time as the host entry).
Setting up SSL Certificates for authentication:
Certificate generation
- Get the ssl.cnf (listed on this page) and *edit* it! (0.organizationName_default should be modified)
ssl.cnf
HOME = . RANDFILE = .rand [ca] default_ca = ca_default [ca_default] dir = . certs = $dir/certs crl_dir = $dir/crl database = $dir/index.txt new_certs_dir = $dir/newcerts certificate = $dir/%s_ca_cert.pem private_key = $dir/private/%s_ca_key.pem serial = $dir/serial crl = $dir/crl.pem x509_extensions = usr_cert name_opt = ca_default cert_opt = ca_default default_days = 3650 default_crl_days = 30 default_md = md5 preserve = no policy = policy_match [policy_match] countryName = match stateOrProvinceName = match organizationName = match organizationalUnitName = optional commonName = supplied emailAddress = optional [req] default_bits = 1024 default_keyfile = privkey.pem distinguished_name = req_distinguished_name attributes = req_attributes x509_extensions = v3_ca # The extentions to add to the self signed cert string_mask = MASK:0x2002 [req_distinguished_name] countryName = Country Name (2 letter code) countryName_default = AT countryName_min = 2 countryName_max = 2 stateOrProvinceName = State or Province Name (full name) stateOrProvinceName_default = Vienna localityName = Locality Name (eg, city) localityName_default = Vienna 0.organizationName = Organization Name (eg, company) 0.organizationName_default = My company organizationalUnitName = Organizational Unit Name (eg, section) commonName = Common Name (eg, your name or your server\'s hostname) commonName_max = 64 emailAddress = Email Address emailAddress_max = 64 [req_attributes] challengePassword = A challenge password challengePassword_min = 4 challengePassword_max = 20 unstructuredName = An optional company name [usr_cert] basicConstraints = CA:FALSE nsComment = "OpenSSL Generated Certificate" subjectKeyIdentifier = hash authorityKeyIdentifier = keyid,issuer:always [v3_ca] subjectKeyIdentifier = hash authorityKeyIdentifier = keyid:always,issuer:always basicConstraints = CA:true
Generate CA
caname="koji"
mkdir -p /etc/kojiweb/clients
cd /etc/kojiweb/clients
mkdir {certs,private}
touch index.txt
echo 01 > serial
openssl genrsa -out private/${caname}_ca_cert.key 2048
openssl req -config ssl.cnf -new -x509 -days 3650 -key private/${caname}_ca_cert.key \
-out ${caname}_ca_cert.crt -extensions v3_ca
Generate the kojira user certificate
caname=koji
user="kojira"
openssl genrsa -out certs/${user}.key 2048
openssl req -config ssl.cnf -new -nodes -out certs/${user}.csr -key certs/${user}.key
openssl ca -config ssl.cnf -keyfile private/${caname}_ca_cert.key -cert ${caname}_ca_cert.crt \
-out certs/${user}.crt -outdir certs -infiles certs/${user}.csr
cat certs/${user}.crt certs/${user}.key > /etc/kojira/${user}.pem
Generate the kojihub server certificate
Do the same as for the kojira user, but with e.g. user="kojihub". Set the common name to the fully-qualified domain name of the Kojihub server.
Generate the kojiweb server certificate
Do the same as for the kojira user, but with e.g. user="kojiweb". Set the common name to the fully-qualified domain name of the Kojiweb server.
Generate the kojid certificate
Do the same as for kojira user, but "user" (i.e. the CN of the certificate) should be the fully-qualified domain name of the machine where the builder will be running, for example: kojibuilder1.example.com
Generate other client certificates
Do the same as for the kojira user, but with e.g. user=<name of user>. These certificates will be used to authenticate to the Koji Hub. The user will be identified in the Koji UI by the CN of their certificate.
Generate a PKCS12 user certificate (for web browser) This is only required for user certificates, not for kojira, kojid, or the other service certificates created above.
openssl pkcs12 -export -inkey certs/${user}.key -in certs/${user}.crt -CAfile ${caname}_ca_cert.crt \
-out certs/${user}_browser_cert.p12
Setting up Kerberos for authentication:
Oh yeah, add some kerberos magic here!
Right now kojiweb only supports Kerberos or SSL authentication to the hub. However, Koji Web is fully functional in read-only mode (without logging in), and all operations exposed via the web UI are also available via the cli. Just comment out everything in /etc/httpd/conf.d/kojiweb.conf related to authentication, and don't click the login link. ;-)
Koji Hub
Koji-hub is the center of all Koji operations. It is an XML-RPC server running under mod_python in Apache. koji-hub is passive in that it only receives XML-RPC calls and relies upon the build daemons and other components to initiate communication. Koji-hub is the only component that has direct access to the database and is one of the two components that have write access to the file system.
Configuration Files:
- /etc/httpd/conf.d/kojihub.conf
- /etc/httpd/conf.d/ssl.conf (when using ssl auth)
Install koji-hub:
yum install koji-hub httpd mod_ssl mod_python
Required Configuration
/etc/httpd/conf.d/kojihub.conf: These settings need to be valid and inline with other services configurations.
PythonOption DBName koji PythonOption DBUser koji PythonOption DBHost db.example.com PythonOption KojiDir /mnt/koji PythonOption LoginCreatesUser On PythonOption KojiWebURL http://kojiweb.example.com/koji
Optional Configuration
/etc/httpd/conf.d/kojihub.conf: If using Kerberos, these settings need to be valid and inline with other services configurations.
PythonOption AuthPrincipal kojihub@EXAMPLE.COM PythonOption AuthKeytab /etc/koji.keytab PythonOption ProxyPrincipals kojihub@EXAMPLE.COM PythonOption HostPrincipalFormat compile/%s@EXAMPLE.COM
/etc/httpd/conf.d/kojihub.conf: If using SSL auth, these settings need to be valid and inline with other services configurations. ProxyDNs should be set to the DN of the kojiweb certificate.
PythonOption DNUsernameComponent CN PythonOption ProxyDNs "/C=US/ST=Massachusetts/O=Example Org/OU=Example User/CN=example/emailAddress=example@example.com"
<Location /kojihub> SSLOptions +StdEnvVars </Location>
/etc/httpd/conf.d/ssl.conf: Add the needed SSL options for apache.
SSLCertificateFile /path/to/kojihub.crt SSLCertificateKeyFile /path/to/kojihub.key SSLCertificateChainFile /path/to/koji_ca_cert.crt SSLCACertificateFile /path/to/koji_ca_cert.crt SSLVerifyClient require SSLVerifyDepth 10
SELinux Configuration
If running in Enforcing mode, you will need to allow apache to connect to the postgreSQL server.
setsebool -P httpd_can_network_connect_db 1
Koji Web - Interface for the Masses
Koji-web is a set of scripts that run in mod_python and use the Cheetah templating engine to provide an web interface to Koji. koji-web exposes a lot of information and also provides a means for certain operations, such as cancelling builds.
Configuration Files:
- /etc/httpd/conf.d/kojiweb.conf
- /etc/httpd/conf.d/ssl.conf
Install Koji-Web:
yum install koji-web httpd mod_python mod_ssl
Required Configuration
/etc/httpd/conf.d/kojiweb.conf:
PythonOption KojiHubURL http://hub.example.com/kojihub PythonOption KojiWebURL http://www.example.com/koji PythonOption KojiPackagesURL http://server.example.com/mnt/koji/packages PythonOption WebCert /etc/kojiweb/kojiweb.pem PythonOption ClientCA /etc/kojiweb/clientca.crt PythonOption KojiHubCA /etc/kojiweb/kojihubca.crt PythonOption LoginTimeout 72 PythonOption Secret CHANGE_ME
Optional Configuration
/etc/httpd/conf.d/kojiweb.conf: If using Kerberos, these settings need to be valid and inline with other services configurations.
<Location /koji/login> AuthType Kerberos AuthName "Koji Web UI" KrbMethodNegotiate on KrbMethodK5Passwd off KrbServiceName HTTP KrbAuthRealm EXAMPLE.COM Krb5Keytab /etc/httpd.keytab KrbSaveCredentials off Require valid-user ErrorDocument 401 /koji-static/errors/unauthorized.html </Location>
/etc/httpd/conf.d/kojiweb.conf: If using SSL auth, these settings need to be valid and inline with other services configurations.
<Location /koji/login> SSLOptions +StdEnvVars </Location>
/etc/httpd/conf.d/ssl.conf: Add the needed SSL options for apache.
SSLVerifyClient require SSLVerifyDepth 10
Koji Daemon - Builder
Kojid is the build daemon that runs on each of the build machines. Its primary responsibility is polling for incoming build requests and handling them accordingly. Koji also has support for tasks other than building. Creating install images is one example. kojid is responsible for handling these tasks as well. kojid uses mock for building. It also creates a fresh buildroot for every build. kojid is written in Python and communicates with koji-hub via XML-RPC.
Configuration Files:
- /etc/kojid/kojid.conf - Koji Daemon Configuration
- /etc/sysconfig/kojid - Koji Daemon Switches
Install kojid:
yum install koji-builder
Required Configuration
/etc/kojid/kojid.conf: This needs to point at your koji-hub.
; The URL for the xmlrpc server server=http://hub.example.com/kojihub ; the username has to be the same as what you used with add-host ; in this example follow as below user = kojibuilder1.example.com
Optional Configuration
/etc/kojid/kojid.conf: If using SSL, these settings need to be valid.
;client certificate ; This should reference the builder certificate we created above, for ; kojibuilder1.example.com cert = /etc/kojid/kojid.pem ;certificate of the CA that issued the client certificate ca = /etc/kojid/clientca.crt ;certificate of the CA that issued the HTTP server certificate serverca = /etc/kojid/serverca.crt
Add the host entry for the koji builder to the database
Make sure you do this before you start kojid for the first time, or you'll need to manually remove entries from the sessions and users table before it can be run successfully.
$ koji add-host kojibuilder1.example.com i386 x86_64
Add the host to the createrepo channel
Channels are a way to control which builders process which tasks. By default hosts are added to the default channel. This host also needs to be added to the createrepo channel so it will process repo creation tasks.
$ koji add-host-to-channel kojibuilder1.example.com createrepo
Start Kojid
/sbin/service kojid start
Check /var/log/kojid.log to verify that kojid has started successfully.
Kojira - Yum repository creation and maintenance
Configuration Files:
- /etc/kojira/kojira.conf - Kojira Daemon Configuration
- /etc/sysconfig/kojira - Kojira Daemon Switches
Install kojira
yum install koji-utils
Required Configuration
/etc/kojira/kojira.conf: This needs to point at your koji-hub.
; The URL for the xmlrpc server server=http://hub.example.com/kojihub
Optional Configuration
/etc/kojira/kojira.conf: If using SSL, these settings need to be valid.
;client certificate ; This should reference the kojira certificate we created above cert = /etc/kojira/kojira.pem ;certificate of the CA that issued the client certificate ca = /etc/kojid/clientca.crt ;certificate of the CA that issued the HTTP server certificate serverca = /etc/kojid/serverca.crt
/etc/sysconfig/kojira: The local user kojira runs as needs to be able to read and write to /mnt/koji/repos/. If the volume that directory resides on is root-squashed or otherwise unmodifiable by root, you can set RUNAS= to a user that has the required privileges.
Add the user entry for the kojira user
Create the kojira user, and grant it the repo permission.
$ koji add-user kojira $ koji grant-permission repo kojira
Start Kojira
/sbin/service kojira start
Check /var/log/kojira/kojira.log to verify that kojira has started successfully.
Bootstrapping the Koji build environment
For instructions on importing packages and preparing Koji to run builds, see ServerBootstrap .