To be free as in freedom

Koji 文档整理

18 Aug 2014

这是关于 Koji 软件包构建系统的文档整理，绝大多数文字都从项目 wiki 以及相关技术文档翻译而来，参见结尾的原文链接。

对于这些文档中中不是很清晰的地方补充了一些内容和实际的例子。

Koji 基本概念

Koji 简介

Koji 是 Fedora 项目的编译打包系统，使用 mock 产生 chroot 环境并在其中完成具体的编译打包任务。

主要的特性

Koji 架构

术语

Koji 组件

Koji 由以下部分组成：

Koji-hub

Koji-hub 是所有 Koji 操作的中心，是运行在 apache 服务的 modwsgi 模块之上的 XMLRPC 服务程序。Koji-hub 只被动地接受 XML_RPC 请求，依赖于 build daemon 和其他组件完成通信交互过程。Koji-hub 也是唯一可以访问数据库的组件，同时是2个对文件系统有写入权限的组件之一。

Kojid

Kojid 是 build daemon，需要在所有的构建服务器上运行。它主要的工作是获取构建请求并对这些请求进行相应的处理。Kojid 实际上是从 Koji-hub 那里获取任务，Koji 也支持构建之外的其他任务，比如创建安装介质镜像。Kojid 使用 mock 来完成构建任务，每次构建都会创建新的 buildroot。Kojid 是使用 Python 语言开发的，和 Koji-hub 之间通过 XML_RPC 协议进行通信。

Koji-web

Koji-web 是运行在 mod_python 模块之上的一系列脚本，加上 Cheetah 模板引擎提供了一套基于 Web 的交互界面。Koji-web 是 Koji-hub 的客户端，为最终用户提供了可视化的操作界面，在该界面上可以完成有限的管理操作。Koji-Web 展示了 Koji 系统中大量的信息，同时也支持完成特定的操作，如终止构建任务等。

Koji-client

Koji-client 是使用 Python 语言编写的命令行工具，也提供了可以和 Koji 交换的大量 hook 接口。使用 Koji-client 可以直接查询 Koji 系统中很多数据，也可以完成不少操作，如添加用户、提交新的构建任务等。

Kojira

Kojira 是维护由构建结果组成的仓库的 daemon 程序，负责清楚冗余的 build root 目录以及构建任务完成之后的清理工作。

软件包的组织方式

tag 和 target

Koji 通过 tag 对软件包组织管理：

target 用来确认软件包的构建过程在何处进行，构建完成之后如何对软件包进行标记（ tag ）。这样，在软件的发布周期之间，tag 可以不断进行变化，而 target 则可以保持不变。使用下面的命令可以获取 Koji 系统中所有的 target 列表：

$ koji list-targets

加上 --name 选项可以针对指定的 target 进行查询：

$  koji list-targets --name EayunOS-4-0
Name                           Buildroot                      Destination   
----------------------------------------------------------------------------
EayunOS-4-0                    EayunOS-4-0-build              EayunOS-4-0

上述示例的含义是： EayunOS-4-0 （ target ） 构建时使用 EayunOS-4-0-build （ tag ）中的软件包列表并创建 buildroot ，生成的软件包的标签为 EayunOS-4-0 （ tag ）。

要获取 Koji 系统中所有的 tag 列表，使用下面的命令：

$ koji list-tags

软件包列表

每一个 tag 都有自己的软件包列表，使用 list-pkgs 命令获取软件包列表（需要指定 tag 名称）：

$ koji list-pkgs --tag EayunOS-4-0
Package                 Tag                     Extra Arches     Owner    
----------------------- ----------------------- ---------------- ---------
eayunos-release         EayunOS-4-0                              zhaochao 
eayunos-lic             EayunOS-4-0                              zhaochao 
virt-viewer-win         EayunOS-4-0                              zhaochao

命令输出结果中，第一列是软件包的名称，第二列显示软件包列表的继承关系，最后一列则显示软件包的所有者。

最近的构建任务

使用 latest-pkg 命令可以查看最近的构建任务：

$ koji latest-pkg --all EayunOS-4-0
Build                                     Tag                   Built by
----------------------------------------  --------------------  -----------
eayunos-lic-0.0.1-3                       EayunOS-4-0           zhaochao
eayunos-release-4-0.el6.2                 EayunOS-4-0           zhaochao
virt-viewer-win-0.0.1-4.el6               EayunOS-4-0           kojiadmin

命令的输出结果中会显示最近的构建任务，所属的 tag ，以及提交任务的用户。

Koji 部署

选择安全验证方式

Koji 支持 2 种安全验证方式： SSL 和 Kerberos 。如果只是使用 koji 命令行工具也可以直接使用用户名和密码登录这种方式，但是 kojiweb 不支持这种方式，而且一旦 kojiweb 配置了 SSL 或者 Kerberos 验证，则用户名和密码登录这种方式将会失效，因此在进行 Koji 部署之前需要首先确定安全验证的方式。

Kerberos验证，前提是已经具备了可用的 Kerberos 环境，初始化 Koji 用户数据时必须已经建立好管理用户的安全凭证；

SSL验证，需要为 xmlrpc 服务程序、Koji 其他各组件、管理用户准备好 SSL 证书。

准备 SSL 安全验证的环境

准备 Kerberos 安全验证环境

Kerberos 环境的部署需要参考其他文档，和 Koji 系统相关的内容说明如下：

初始化数据库

这里略去了 Postgres 数据库服务自身的初始化过程。

创建 koji 系统用户

# useradd koji
# password koji

建立数据库环境

分为以下几步：

设置数据库允许 koji-web 和 koji-hub 访问

/var/lib/pgsql/data/pg_hba.conf ：

#TYPE   DATABASE    USER    CIDR-ADDRESS      METHOD
host    koji        koji    127.0.0.1/32      trust
host    koji        koji     ::1/128          trust

如果服务器还有外部 IP 地址的话，可以再加上：

host    koji        koji    $IP_ADDRESS/32    trust

如果要使用 UNIX socket 和数据库通信（这种方式下，Koji 组件的配置文件中 DBHost 选项不能进行设备），可以使用这样的配置：

local   koji        apache                            trust
local   koji        koji                              trust

注意： 如果强制要求使用密码验证访问数据，可以将上述配置中的 trust 改为 md5：

#TYPE   DATABASE    USER    CIDR-ADDRESS      METHOD
host    koji        koji    127.0.0.1/32      md5
host    koji        koji     ::1/128          md5
host    koji        koji    $IP_ADDRESS/32    md5

为了配置生效，让数据库重新读取配置文件：

# service postgresql reload

在数据库中添加 Koji 管理用户

Koji 管理用户需要手动通过 sql 语句添加到数据库中。当管理用户添加成功之后，其他的用户操作（增加、删除用户，修改用户权限等）可以通过 koji 命令完成。

不过，如果使用简单的用户名和密码验证方式，则配置或者修改用户密码仍然需要通过 sql 语句直接操作数据库完成，因为 koji 命令没有提供对用户密码进行操作的接口。

针对不同的验证方式，添加 Koji 管理用户的 sql 语句也不同：

赋予指定用户管理权限

使用下面的 sql 语句可以为指定用户（需要知道用户的 ID）赋予管理管线：

koji=> insert into user_perms (user_id, perm_id, creator_id)
koji-> values (<用户 ID >, 1, <用户 ID >);

让 Postgresql 数据库监听所有地址

安装配置 Koji-hub

安装 Koji-hub

# yum install koji-hub httpd mod_ssl mod_auth_kerb

基本配置

安全验证配置

Koji 文件目录

在上面的配置示例中，KojiDir 设置为 /mnt/koji，如果更改了该路径，仍然需要建立一个 /mnt/koji 软连接指向实际的 Koji 文件目录。在部署 Koji 其他组件之前需要为该目录建立基本的结构，并配置好权限：

cd /mnt
mkdir koji
cd koji
mkdir {packages,repos,work,scratch}
chown apache.apache *

配置 SELinux

如果服务器系统中 SELinux 以 Enforcing 模式运行，则进行一些配置：

配置方法参考：

root@localhost$ setsebool -P httpd_can_network_connect_db=1 allow_httpd_anon_write=1
root@localhost$ chcon -R -t public_content_rw_t /mnt/koji/*

如果 /mnt/koji 是挂载的 NFS 共享目录，则还需要设置 httpd_use_nfs：

root@localhost$ setsebool -P httpd_use_nfs=1

检查配置并重启 httpd

完成上述配置之后，理论上重新启动 apache 服务之后，Koji-hub 应该可以正常工作，可以通过下文即将提到的 koji 命令进行检测。

koji 命令行工具

koji 命令行工具是 Koji 系统的标准客户端工具，使用 koji 命令可以完成大部分的工作。

koji 命令默认使用用户配置文件 ~/.koji/config 和全局配置文件 /etc/koji.conf 。

配置 koji 命令使用 SSL 证书验证

主要的配置项是 cert 、 ca 、 serverca。举例如下：

; configuration for SSL athentication

;client certificate
cert = ~/.koji/client.crt

;certificate of the CA that issued the client certificate
ca = ~/.koji/clientca.crt

;certificate of the CA that issued the HTTP server certificate
serverca = ~/.koji/serverca.crt

使用 SSL 验证时，url 地址可以直接使用 ip 地址（如，127.0.0.1）：

;;url of XMLRPC server
server = http://127.0.0.1/kojihub

;;url of web interface
weburl = http://127.0.0.1/koji

;;url of package download site
topurl = http://127.0.0.1/kojifiles

配置 koji 命令使用 Kerberos 验证

使用 Kerberos 验证时，koji 命令的配置文件其实不用做修改，只需要将 SSL 验证相关部分（如果曾经开启的话）注释即可，举例如下：

[koji]
server = http://koji.zhaochao.eayunos.eayun.com/kojihub

weburl = http://koji.zhaochao.eayunos.eayun.com/koji

topurl = http://koji.zhaochao.eayunos.eayun.com/kojifiles

topdir = /mnt/koji

;the service name of the principal being used by the hub 
;krbservice = host

;client certificate
;cert = ~/.koji/client.crt

;certificate of the CA that issued the client certificate
;ca = ~/.koji/clientca.crt

;certificate of the CA that issued the HTTP server certificate
;serverca = ~/.koji/serverca.crt

但是使用 koji 命令之前必须首先完成 Kerberos 的身份验证，获取相关凭证，如：

$ kinit kadmin
Password for kojiadmin@ZHAOCHAO.EAYUNOS.EAYUN.COM:
# klist
Ticket cache: FILE:/tmp/krb5cc_0
Default principal: kojiadmin@ZHAOCHAO.EAYUNOS.EAYUN.COM

Valid starting     Expires            Service principal
08/14/14 12:00:58  08/15/14 12:00:55  krbtgt/ZHAOCHAO.EAYUNOS.EAYUN.COM@ZHAOCHAO.EAYUNOS.EAYUN.COM
        renew until 08/21/14 12:00:55

尝试登录 Koji-hub

使用 koji moshimoshi 命令测试是否可能正常登录到 Koji-hub：

$ koji moshimoshi

安装配置 Koji-web

安装 koji-web

# yum install koji-web mod_ssl mod_auth_kerb

基本配置

验证 Koji-web 是否可以正常工作

重启 httpd 服务之后，访问 koji-web 的地址，确认是否可以正常访问、登录以及完成各种操作。

安装配置Kojid

安装 Kojid

# yum install koji-builder

基本配置

安全验证配置

配置通过 SCM 构建软件包（可选）

将主机添加到 createrepo 通道（channel）中

通道（channel） 是用来控制构建主机可以执行哪些构建任务的。默认情况下，所有构建主机都会加入到 default 通道。但是至少需要一些构建主机加入到 createrepo 通道，它们可以完成 kojira 发起的创建软件包仓库的任务。

$ koji add-host-to-channel kojibuilder1.example.com createrepo

关于构建主机容量（ capacity ）参数的说明

添加构建主机时，默认的容量为 2 ，含义是如果该构建主机的 load average 大于 2 时， kojid 将不再接受新的任务。该配置和 kojid 配置文件中的 maxjobs 配置项是不同的。当 kojid 接受新的任务时，需要满足系统 load average 小于 capacity，同时同时执行的任务数不能超过 maxjobs 。不过由于服务器硬件配置的不断增强，可以根据实际情况调整 capacity 的大小：

koji edit-host --capacity=16 kojibuilder1.example.com

启动 kojid

当构建主机添加到 Koji 系统，配置完成之后，可以启动 kojid 服务：

# service kojid start

检查 kojid 的日志文件 /var/log/kojid.log 确认 kojid 是否已经启动成功。启动成功之后，可以通过 koji-web 的界面查看主机列表中各构建主机的状态和信息。

安装配置 Kojira

安装 Kojira

# yum install koji-utils

基本配置

安全验证配置

启动 Kojira

$ service kojira start

检查 kojira 日志 `/var/log/kojira.log` 确认是否已经正常启动。

使用 Koji

Koji 提供的功能不少，根据不同的环境、不同的需求可以设计不同的系统方案，这里只对最基本的使用进行介绍。

确定是否使用外部软件仓库

Koji 构建软件包时使用 mock，构建过程中利用了 chroot 环境，因此涉及到构建过程依赖的软件包如何安装的问题。有 2 种情况：

使用哪一种方式要根据具体的需求决定，后面的文档将基于使用外部软件仓库的情形进行说明。

建立 tag 和 target

tag 是用来建立 Koji 工作流程的，对于最建单的情况，需要建立软件包最终发布所属的 tag ：

$ koji add-tag EayunOS-4-0

接下来为具体的构建过程创建 tag ：

$ koji add-tag --parent EayunOS-4-0 --arches "i686 x86_64" EayunOS-4-0-build

Koji 构建软件包时使用的是 target，target 决定了构建过程在何处进行（构建过程对应的 tag ），以及构建产生的结果如何标记（目标 tag），所以需要继续建立 target ：

$ koji add-target EayunOS-4-0 EayunOS-4-0-build

使用 koji add-target 时，最多可以使用 3 个参数，分别对应 target 名称、构建过程对应的 tag、目标 tag。在上面的示例中，最后的目标 tag 省略了，这时目标 tag 默认使用和 target 名称相同的 tag ，即，上述命令中 EayunOS-4-0 是 target，该命令其实表示的是：

$ koji add-target EayunOS-4-0 EayunOS-4-0-build EayunOS-4-0

添加外部软件仓库

外部软件仓库需要添加到构建过程对应的 tag ：

$ koji add-external-repo -t EayunOS-4-0-build centos6-base-repo \
http://192.168.3.239/mirrors/CentOS/6.5/os/$arch/

$ koji add-external-repo -t EayunOS-4-0-build centos6-update-repo \
http://192.168.3.239/mirrors/CentOS/6.5/updates/$arch/

创建构建相关的软件包组

在 Koji 系统中可以对软件包进行分组，其中有 2 个比较特殊的软件包组： build 和 srpm-build 。Koji 的构建过程使用 chroot 环境，建立该 chroot 环境时需要要装一些基本的软件包才能完成构建工作。根据构建任务的不同（这里只说明 rpm 和 source rpm 的情况），构建 rpm 包时，建立 chroot 环境的过程中会安装 build 软件包组的所有软件包；构建 source rpm 包时，建立 chroot 环境的过程中会安装 srpm-build 软件包组中的所有软件包。

因此必须首先建立这 2 个软件组，同时软件组中的软件包选择也需要注意。因此 koji 每次构建都会新建 chroot 环境，如果要安装太多的软件包，会影响整个构建过程的时间，当然如果构建过程中需要的软件包不会在创建 chroot 环境时安装（而且也不在该软件包的依赖关系中）则构建过程会失败。

创建 build 和 srpm-build 软件包组

$ koji add-group EayunOS-4-0-build build

$ koji add-group EayunOS-4-0-build srpm-build

为 build 和 srpm-build 添加软件包

$ koji add-group-pkg EayunOS-4-0-build build bash bzip2 coreutils diffutils \
findutils gawk gcc grep gzip make patch rpm-build shadow-utils tar \
util-linux-ng which

$ koji add-group-pkg EayunOS-4-0-build srpm-build bash bzip2 gzip rpm-build \
rpmdevtools shadow-utils tar

为构建过程 tag 重建 repo 信息

$ koji regen-repo EayunOS-4-0-build

测试构建环境是否可用

koji build 命令会创建并启动软件包构建任务，加上 --scratch 参数可以用来测试构建任务，而不会干扰正常的 koji 工作流程。

$ koji build --scratch eayunos-release-4-0.el6.2.src.rpm

开始构建软件包

首先将软件包添加到目标 tag 的软件包列表（注意只需要软件包名称即可，即 Koji 架构术语中的 Package ）：

$ koji add-pkg --owner zhaochao EayunOS-4-0 eayunos-release

然后就可以开始构建软件包了

$ koji build EayunOS-4-0 eayunos-release-4-0.el6.2.src.rpm

从 SCM 代码仓库构建软件包

除了只是通过 srpm 构建软件包之外，Koji 系统还是从 SCM 代码仓库中构建软件包。要从 SCM 代码仓库中构建软件包，首先需要对 kojid 进行配置，允许 kojid 从指定的 SCM 地址构建，配置方法见 kojid 的安装配置部分。

举例说明：

/etc/kojid/kojid.conf

 allowed_scms=192.168.3.239:*:no

koji build 从 SCM 代码仓库构建软件包的命令中，url 地址的格式是：

scheme://[user@]host/path/to/repo?path/to/module#revision_or_tag_identifier

举例说明：

koji build --scratch EayunOS-4-0 'git+http://192.168.3.239/git/virt-viewer-win-koji.git?.#HEAD'

需要注意的是，url 地址中除了代码仓库的地址以外需要指定代码所在的目录以及代码 revision 。另外地址的协议头也有特定的格式，目前支持以下组合：

cvs://， cvs+ssh://
git://， git+http://， git+https://， git+rsync://， git+ssh://
svn://， svn+http://， svn+https://， svn+ssh://

在 kojid 安装配置部分已经说过代码从 SCM 服务器 checkout 之后，会自动完成一些操作，其中第一步是生成构建 srpm 需要的压缩包。 kojid 默认执行的命令是 make source，当然可以通过配置让 kojid 执行其他的命令，比如 fedpkg sources，那么上例就改成：

allowed_scms=192.168.3.239:*:no:fedpkg,sources

默认的情况下 kojid 执行 make sources ，因此需要在代码所在的目录下编写一个 Makefile，例如如：

package = virt-viewer-win
src_pkgs = $(shell spectool -l $(package).spec | awk '{print $$NF}')

sources:
        tar zcf $(src_pkgs) virt-viewer-win

原文链接

  1. koji - RPM building and tracking system
  2. Koji wiki
  3. Koji/ServerHowTo
  4. devops-blog 上的 koji系列博客

Atom Feeds RSS Feeds