From Fedora Project Wiki
 
(80 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{autolang}}
{{autolang}}
'''搭建一套Koji编译系统'''
'''搭建一套 Koji 编译系统'''


Koji编译系统的各个组件可以分别''搭建''在不同的设备上,只要这些设备之间可以相互通信就可以了。这篇文章分别介绍了各个组件的搭建过程,然而,所有组件也可以搭建在同一台设备上。
Koji 编译系统的各个组件可以分别''搭建''在不同的设备上,只要这些设备之间可以相互通信就可以了。这篇文章将描述在不同的设备上分别设置各个服务的过程,然而,所有服务也可以''搭建''在同一台设备上。


== 必备知识  ==
== 必备知识  ==
 
您必须要掌握:
* Basic understanding of SSL and authentication via certificates and/or Kerberos credentials
* 通过 SSL 证书和/或通过 Kerberos 凭据认证的基础知识
* Basic knowledge about creating a database in PostgreSQL and importing a schema
* PostgreSQL 中创建数据库以及向数据库中导入视图的基础知识。
* Working with psql
* psql 命令的使用方法
* Basic knowledge about Apache configuration
* 能够对 Apache 进行配置
* Basic knowledge about yum/createrepo/mock - else you'll not be able to debug problems!
* yum、createrepo和mock 的使用方法,否则当出现问题时您没办法进行调试!
* Basic knowledge about using command line
* 能够使用命令行终端进行操作
* Basic knowledge about RPM building
* 关于RPM 编译的基本知识
* Simple usage of the Koji client
* 能够简单使用 Koji 客户端
* For an overview of yum, mock, Koji (and all its subcomponents), mash, and how they all work together, see the excellent slides put together by Steve Traylen at CERN [http://indico.cern.ch/event/55091].
* 如果您想了解 yum、mock、Koji (以及它的各个组成部分)、mash的基本信息,以及它们是如何协调工作的,请浏览 Steve Traylen CERN 上放映的精彩幻灯片[http://indico.cern.ch/event/55091].


== 基础软件包 ==
== 基础软件包 ==


'''服务器端 (koji-hub/koji-web)'''
'''服务器端(koji-hub/koji-web)'''
* httpd
* httpd
* mod_ssl
* mod_ssl
* postgresql-server
* postgresql-server
* mod_python (为了满足Kerberos认证功能,mod_python版本需要大于等于3.3.1)
* mod_python (为了满足 Kerberos 认证功能,mod_python 版本需要大于等于3.3.1)


'''编译机端 (koji-builder)'''
'''编译机端 (koji-builder)'''
* mock
* mock
* setarch (for some archs you'll require a patched version)
* setarch (某些特殊的系统架构中需要安装打过补丁的版本)
* rpm-build
* rpm-build
* createrepo
* createrepo


== 关于文件系统容量的说明 ==
== 关于文件系统容量的说明 ==
Koji will consume copious amounts of disk space under the primary KojiDir directory (as set in the kojihub.conf file).  However, as koji makes use of mock on the backend to actually create build roots and perform the builds in those build roots, it might come to a surprise to users that a running koji server will consume large amounts of disk space under /var/lib/mock and /var/cache/mock as well.  Users should either plan the disk and filesystem allocations for this, or plan to modify the default mock build directory in the kojid.conf file. If you change the location, ensure that the new directories are owned by the group "mock" and have 02755 permission.
Koji 需要消耗主目录 KojiDir (这个目录可以在 kojihub.conf 文件中进行配置)下大量的磁盘空间。然而,因为 koji 实际上是在后台调用 mock 来创建编译环境,然后在编译环境中执行软件包编译过程。一台正在运行的 koji 服务器同样会消耗 /var/lib/mock /var/cache/mock 下大量的磁盘空间,用户对此感到很奇怪。用户或者可以为此规划合适的磁盘分配方案,或者可以在配置文件 kojid.conf 中修改 mock 编译软件包的默认路径。如果您更改了这个路径,请确认更改后的路径属于用户组 "mock",并且该路径具有 02755 访问权限。


== 为Koji选择认证机制 ==
== 为 Koji 选择认证机制 ==
Koji主要支持Kerberos和SSL证书两种认证机制。在基本的终端交互模式中,Koji还支持基于明文的用户名/密码的认证方式。然而,kojiweb'''不'''支持用户名/密码认证方式,并且一旦kojiweb采用了Kerberos或者SSL证书认证方式, 用户名/密码认证方式将会完全失去作用。 因此,我们建议从系统搭建开始就不要采用用户名/密码认证方式,而是合理配置Kerberos或者SSL证书认证方式。
Koji 主要支持 Kerberos 和 SSL 证书两种认证机制。在基本的命令行终端模式中,Koji 还支持基于明文的用户名/密码的认证方式。然而,kojiweb '''不'''支持用户名/密码认证方式,并且一旦 kojiweb 采用了 Kerberos 或者 SSL 证书认证方式, 用户名/密码认证方式将会完全失去作用。 因此,我们建议从系统搭建开始就不要采用用户名/密码认证方式,而是合理配置 Kerberos 或者 SSL 证书认证方式。


采用哪种认证方式将会影响到koji系统搭建过程中的所有其他方面,因此你最好现在就选定一种认证方式。
采用哪种认证方式将会影响到 koji 系统搭建过程中的所有其他方面,因此您最好现在就选定一种认证方式。


For Kerberos authentication, a working Kerberos environment (the user is assumed to either already have this or know how to set it up themselves, instructions for it are not included here) and the Kerberos credentials of the initial admin user will be necessary to bootstrap the user database.
如果您选择的是 Kerberos 认证方式,为了初始化用户数据库,您需要一个正常的 Kerberos 环境(我们假设您已经有了一个这样的环境或者您知道如何搭建一个这样的环境,本文中不会讲解 Kerberos 环境的搭建过程)和初始管理员的 Kerberos 凭证。


如果选择SSL认证方式,你需要为xmlrpc服务器、koji中各种组件和系统管理员创建SSL证书。你不需要知道证书的创建过程,我们在后面会详细介绍证书的创建过程。
如果您选择的是 SSL 认证方式,您需要为 xmlrpc 服务器、koji 中各种组件和系统管理员创建 SSL 证书。您不需要提前知道证书的创建方法,我们在后面会详细介绍证书的创建过程。


=== 为认证机制创建SSL证书 ===
=== 设置 SSL 证书进行认证 ===
'''生成证书'''
'''生成证书'''
* 创建一个新目录'''/etc/pki/koji''',将下面文件的内容保存在该目录新创建的文件ssl.cnf中。这个配置文件和'''openssl'''命令配合使用,用来生成koji各个组件需要的SSL证书。
* 创建一个新目录 '''/etc/pki/koji''',将下面的内容保存在该目录新创建的文件 ssl.cnf 中。这个配置文件和 '''openssl''' 命令配合使用,用来生成 koji 各个组件需要的 SSL 证书。


'''ssl.cnf'''
'''ssl.cnf'''
Line 69: Line 69:
default_days            = 3650
default_days            = 3650
default_crl_days        = 30
default_crl_days        = 30
default_md              = md5
default_md              = sha256
preserve                = no
preserve                = no
policy                  = policy_match
policy                  = policy_match
Line 124: Line 124:
</pre>
</pre>


虽然不是必须的,但是我们建议你根据自己的实际信息修改配置文件中'''[req_distinguished_name]'''部分的默认值。这样,当你创建证书的时候你就可以使用大部分的默认值而不需要自己填写信息。配置文件中的其他部分不需要修改。
虽然不是必须的,但是我们建议您根据自己的实际信息修改配置文件中'''[req_distinguished_name]'''部分的默认值。这样,当您创建证书的时候您就可以使用大部分的默认值而不需要自己填写信息。配置文件中的其他部分不需要修改。




'''生成CA证书'''
'''生成 CA 证书'''


CA证书用来标识SSL证书的颁发机构。它是用来签发其他证书的密钥/证书对。当配置koji中各种组件时,客户端和服务器端的CA证书都使用这里生成的CA证书的一份拷贝。CA证书将被放置在目录'''''/etc/pki/koji'''''中,koji各个组件的证书将放置在目录 '''''/etc/pki/koji/certs'''''中。另外需要创建一个'''index.txt'''文件,这个文件作为数据库保存了已经创建了的证书的信息。通过查看文件'''index.txt'''的内容,我们可以方便地查看任何证书的信息。
CA 证书用来标识 SSL 证书的颁发机构。它是用来签发其他证书的密钥/证书对。当配置 koji 中各种组件时,客户端和服务器端的 CA 证书都使用这里生成的 CA 证书的一份拷贝。CA 证书将被放置在目录 '''''/etc/pki/koji''''' 中,koji 各个组件的证书将放置在目录 '''''/etc/pki/koji/certs''''' 中。另外需要创建一个 '''index.txt''' 文件,这个文件作为数据库保存了已经创建的证书的信息。通过查看文件 '''index.txt''' 的内容,我们可以方便地查看任何证书的信息。


<pre>
<pre>
Line 142: Line 142:
</pre>
</pre>


上面脚本中的最后一条命令会提示你输入与正在创建的证书相关的一组信息。想必你已经修改了配置文件ssl.cnf中国家、州/省、城市和机构这几个字段的默认值,因此你直接按回车键就可以了。部门和通用名两个字段的值需要根据不同的证书进行修改。对于CA证书,这些字段的取值没有硬性的规定,一种建议是使用服务器的完整域名(FQDN)。
上面脚本中的最后一条命令会提示您输入与正在创建的证书相关的一组信息。想必您已经修改了配置文件 ssl.cnf 中国家、州/省、城市和机构这几个字段的默认值,因此您直接按回车键就可以了。部门和通用名两个字段的值需要根据不同的证书进行修改。对于 CA 证书,这些字段的取值没有硬性的规定,一种建议是使用服务器的完整域名(FQDN)。




'''为koji各个组件和系统管理员创建证书'''
'''为 koji 各个组件和系统管理员创建证书'''


Koji中的每个组件都需要一个单独的证书标识自己。 Two of the certificates (kojihub and kojiweb) are used as server side certificates that authenticate the server to the client. For this reason, you want the common name on both of those certs to be the fully qualified domain name of the web server they are running on so that clients don't complain about the common name and the server not being the same. You can set the OU for these two certificates to be kojihub and kojiweb for identification purposes.
Koji中的每个组件都需要一个单独的证书标识自己。其中两个组件(kojihub and kojiweb)的证书作为服务器端的证书用来提供服务器端到客户端的认证。基于这个原因,您希望用运行这两个组件的网络服务器的完整域名(FQDN)作为这两个证书中的通用名。这样,客户端就不会抱怨证书中的通用名和服务器不一致。为了便于认证,您可以将这两个证书中的 OU( 部门名称)分别设置为 kojihub 和 kojiweb。


For the other certificates (kojira, kojid, the initial admin account, and all user certificates), the cert is used to authenticate the client to the server. The common name for these certs should be set to the login name for that specific component. For example the common name for the kojira cert should be set to kojira so that it matches the username. The reason for this is that the common name of the cert will be matched to the corresponding user name in the koji database. If there is not a username in the database which matches the CN of the cert the client will not be authenticated and access will be denied.
对于其他的证书(kojira、kojid、初始的系统管理员用户以及所有用户的证书)来说, 这些证书用来提供客户端到服务器端的认证功能。证书的通用名应该设置成组件或者用户的登录名。例如,kojira 证书中的通用名应该设置成 kojira,这样登录名就和组件的名称一致了。这样做的原因是证书中的通用名需要和数据库中组件或用户的名称保持一致。如果在数据库中找不到和证书中 CN (通用名)相匹配的组件或者用户,客户端将不能通过认证,也就不能登录系统。


When you later use ''koji add-host'' to add a build machine into the koji database, it creates a user account for that host even though the user account doesn't appear in the user list.  The user account created must match the common name of the certificate which that component uses to authenticate with the server. When creating the kojiweb certificate, you'll want to remember exactly what values you enter for each field as you'll have to regurgitate those into the /etc/koji-hub/hub.conf file as the ProxyDNs entry.
在后面的步骤中,您会通过 ''koji add-host'' 命令向数据库中添加一个编译机。系统将会为这个编译机创建一个帐号,虽然这个帐号不会显示在用户列表中。创建的帐号必须与组件登录服务器时使用的证书中的通用名相同。当您为 kojiweb 创建证书的时候,您需要牢牢记住您为每一个选项填写的值,您需要根据这些选项的值组合出配置文件/etc/koji-hub/hub.conf ProxyDNs 选项的值。


When you need to create multiple certificates it may be convenient to create a loop like the on listed below or to even place the code into a script and run the script in a loop. You can simply adjust the number of kojibuilders and the name of the admin account as you see fit. For much of this guide, the admin account is called "kojiadmin".
当您需要创建多个证书的时候,一种简便的方法是编写像下面列出的代码这样的循环语句,甚至可以将这些循环语句写到一个脚本文件中,然后执行这个脚本文件。您只需要按照自己的意愿简单地调整代码中编译机的数量和系统管理员的名称就可以了。在本文档中,我们设置系统管理员的名称为 "kojiadmin"


<pre>
<pre>
Line 165: Line 165:
</pre>
</pre>


''' Generate a PKCS12 user certificate (for web browser)'''
'''为用户创建一个 PKCS12 证书(用于通过浏览器登录系统)'''
This is only required for user certificates.
只需要为实际的用户创建这个证书。
<pre>
<pre>
openssl pkcs12 -export -inkey certs/${user}.key -in certs/${user}.crt -CAfile ${caname}_ca_cert.crt \
openssl pkcs12 -export -inkey certs/${user}.key -in certs/${user}.crt -CAfile ${caname}_ca_cert.crt \
Line 172: Line 172:
</pre>
</pre>


When generating certs for a user, the user will need the ${user}.pem, the ${caname}_ca_cert.crt, and the ${user}_browser_cert.p12 files which were generated above.  The ${user}.pem file would normally be installed as ~/.fedora.cert, the ${caname}_ca_cert.crt file would be installed as both ~/.fedora-upload-ca.cert and ~/.fedora-server-ca.cert, and the user would import the ${user}_brower_cert.p12 into their web browser as a personal certificate.
当为用户创建证书的时候,我们需要通过上面的代码为用户创建三个证书文件,分别为:${user}.pem、 ${caname}_ca_cert.crt ${user}_browser_cert.p12。一般情况下,我们将 ${user}.pem 放置在 ~/.fedora.cert,将 ${caname}_ca_cert.crt 拷贝两份分别放置在 ~/.fedora-upload-ca.cert ~/.fedora-server-ca.cert,将 ${user}_brower_cert.p12 作为用户证书导入到浏览器中。




'''Copy certificates into ~/.koji for kojiadmin'''
'''为 kojiadmin 将证书拷贝到 ~/.koji'''


You're going to want to be able to send admin commands to the kojihub. In order to do so, you'll need to use the newly created certificates to authenticate with the hub. Copy the certificates for the koji CA and the kojiadmin user to ~/.koji:
有时候您想向 kojihub 发送需要具有管理员权限的命令。为了达到这个目的,您需要用刚生成的证书向 kojihub 进行认证。将 CA 证书和 kojiadmin 的证书拷贝到 ~/.koji:


<pre>
<pre>
Line 186: Line 186:
</pre>
</pre>


'''Note:''' See /etc/koji.conf for the current system wide koji client configuration.  Copy /etc/koji.conf to ~/.koji/config if you wish to change the config on a per user basis.
'''注意:'''配置文件 /etc/koji.conf 中保存了对本机中所有用户都有效的 koji 客户端配置。如果您想针对每个用户进行不同的配置,请将 /etc/koji.conf 拷贝到 ~/.koji/config。


=== Setting up Kerberos for authentication ===
=== 设置 Kerberos 进行认证 ===
The initial configuration of a kerberos service is outside the scope of this document, however there are a few specific things required by koji.
kerberos 服务的初始设置过程不在本文档的讲解范围之内,然而您需要针对 koji 进行一些特定的设置。


'''DNS'''
'''DNS'''


The koji builders (kojid) use DNS to find the kerberos servers for any given realm.
对于任何给定的域,koji 编译机(kojid) 使用 DNS 查找 kerberos 服务器。


<pre>
<pre>
_kerberos._udp    IN SRV  10 100 88 kerberos.EXAMPLE.COM.
_kerberos._udp    IN SRV  10 100 88 kerberos.EXAMPLE.COM.
</pre>
</pre>
The trailing dot denotes DNS root and is needed if FQDN is used.
最后的句点表示 DNS 根。如果使用完整域名(FQDN),这个句点是必须的。




'''Principals and Keytabs'''
'''Principals and Keytabs'''


It should be noted that in general you will need to use the fully qualified domain name of the hosts when generating the keytabs for services.
需要注意的是当为服务生成 keytab文件时 时,通常情况下您需要使用主机的完整域名。


You will need the following principals extracted to a keytab for a fully kerborised configuration, the requirement for a host key for the koji-hub is currently hard coded into the koji client.
为了配置Kerberos认证,您需要将下列 principal 包含到 keytab 文件中。向 koji-hub 认证时使用的 key 目前写死在了 koji 客户端中。


* host/kojihub@EXAMPLE.COM
* host/kojihub@EXAMPLE.COM
** Used by the koji-hub server when communicating with the koji client
** koji-hub 服务器使用,用来与 koji 客户端进行通信
* HTTP/kojiweb@EXAMPLE.COM
* HTTP/kojiweb@EXAMPLE.COM
** Used by the koji-web server when performing a negotiated Kerberos authentication with a web browser. This is a service principal for Apache's mod_auth_kerb.
** koji-web 服务器使用,与网页浏览器协商进行 Kerberos 认证。 这是一个 Apache mod_auth_kerb 模块中的服务实体。
* koji/kojiweb@EXAMPLE.COM
* koji/kojiweb@EXAMPLE.COM
** Used by the koji-web server during communications with the koji-hub. This is a user principal that will authenticate koji-web to Kerberos as "koji/kojiweb@EXAMPLE.COM". Koji-web will proxy the mod_auth_kerb user information to koji-hub (the <code>ProxyPrincipals</code> koji-hub config option).
**the koji-web 服务器使用,用来与 koji-hub 进行通信。 这是一个用户 principal,将 koji-web 标识成"koji/kojiweb@EXAMPLE.COM"向 Kerberos 进行认证。Koji-web 将代理用户通过 mod_auth_kerb 发送到 koji-hub 的信息(通过 koji-hub 配置文件中的 <code>ProxyPrincipals</code> 进行配置)
* koji/kojira@EXAMPLE.COM
* koji/kojira@EXAMPLE.COM
** Used by the kojira server during communications with the koji-hub
** kojira 服务器使用,用来与 koji-hub 进行通信
* compile/builder1@EXAMPLE.COM
* compile/builder1@EXAMPLE.COM
** Used on builder1 to communicate with the koji-hub
** builder1 使用,用来与 koji-hub 进行通信


== PostgreSQL Server ==
== PostgreSQL 服务器 ==
Once the authentication scheme has been setup your will need to install and configure a PostgreSQL server and prime the database which will be used to hold the koji users.
一旦认证机制配置完毕,您需要安装和配置一个 PostgreSQL 服务器,在服务器中创建一个数据库用来保存用户的信息。


'''Configuration Files:'''
'''配置文件:'''


* /var/lib/pgsql/data/pg_hba.conf
* /var/lib/pgsql/data/pg_hba.conf
* /var/lib/pgsql/data/postgresql.conf
* /var/lib/pgsql/data/postgresql.conf


'''Install PostgreSQL:'''
'''安装 PostgreSQL:'''
<pre>
<pre>
root@localhost$ yum install postgresql-server
root@localhost$ yum install postgresql-server
</pre>
</pre>


'''Initialize PostgreSQL DB:'''
'''初始化 PostgreSQL 数据库:'''


The following commands will initialize PostgreSQL and will start the database service
下面的命令用来初始化 PostgreSQL 并且开启数据库服务
<pre>
<pre>
root@localhost$ service postgresql initdb
root@localhost$ service postgresql initdb
Line 239: Line 239:
</pre>
</pre>


{{admon/note|initdb on Fedora 16|The PostgreSQL init script has been converted to systemd in Fedora 16, so the initdb function has been removed.  To run initdb directly: <pre>su - postgres -c "PGDATA=/var/lib/pgsql/data initdb"</pre>}}
{{admon/note|Fedora 16 中的 initdb|Fedora 16 PostgreSQL 的初始化方式已经采用了 systemd 机制,因此 initdb 命令已经不存在了。您需要直接执行下面的命令初始化PostgreSQL: <pre>su - postgres -c "PGDATA=/var/lib/pgsql/data initdb"</pre>}}


'''Setup User Accounts:'''
'''设置用户帐号'''


The following commands will setup the '''koji''' account and assign it a password
下面的命令可以创建一个名称为 '''koji''' 的帐号,并且为该帐号设置密码。
<pre>
<pre>
root@localhost$ useradd koji
root@localhost$ useradd koji
Line 249: Line 249:
</pre>
</pre>


'''Setup PostgreSQL and populate schema:'''
'''设置 PostgreSQL 并导入视图:'''


The following commands will create the '''koji''' user within PostgreSQL and will then create the koji database using the schema within the /usr/share/doc/koji*/docs/schema.sql directory
下面的命令可以在 PostgreSQL 中创建一个名称为 '''koji''' 的帐号,然后用 /usr/share/doc/koji*/docs/schema.sql 中的视图初始化一个名称为 koji 的数据库。
<pre>
<pre>
root@localhost$ su - postgres
root@localhost$ su - postgres
Line 265: Line 265:
</pre>
</pre>


'''NOTE:''' When issuing the command to import the psql schema into the new database it is important to ensure that the directory path /usr/share/doc/koji*/docs/schema.sql remains intact and is not resolved to a specific version of koji. In test it was discovered that when the path is resolved to a specific version of koji then not all of the tables were created correctly
'''注意:''' 当您执行上面的命令将视图导入到新建的数据库中时,确保路径 /usr/share/doc/koji*/docs/schema.sql 保持原样,不要替换成具体的 koji 版本。在测试过程中我们发现,当替换成一个指定版本的路径时,数据库中有些表将不能正确创建。




'''Authorize Koji-web and Koji-hub resources:'''
'''认证 Koji-web Koji-hub 设备:'''
''In this example, Koji-web and Koji-hub are running on localhost.''
''在这个例子中,Koji-web Koji-hub 在本地设备上运行。''


/var/lib/pgsql/data/pg_hba.conf:
/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:''
''添加:''
<pre>
<pre>
host    koji        koji        127.0.0.1/32          trust
host    koji        koji        127.0.0.1/32          trust
host    koji        koji          ::1/128            trust
host    koji        koji          ::1/128            trust
</pre>
</pre>
''You can also use UNIX socket access. The DBHost variable must be unset to use this method.''
''您也可以使用 UNIX 套接字连接方式。如果使用这种连接方式,DBHost 项必须保持为空白。''
''Add:''
''添加:''
<pre>
<pre>
local  koji        apache                            trust
local  koji        apache                            trust
Line 288: Line 288:
</pre>
</pre>


'''Make auth changes live:'''
'''使认证项生效:'''


The following commands let postgreSQL know that changes have been made and forces it to reload its configuration so that changes become active
下面的命令可以让 postgreSQL 知道配置项发生了变化,强迫 postgreSQL 重新加载配置项,因此您做的修改就可以生效了
<pre>
<pre>
root@localhost$ su - postgres
root@localhost$ su - postgres
Line 297: Line 297:
</pre>
</pre>


'''Bootstrapping the initial koji admin user into the PostgreSQL database:'''
'''PostgreSQL 数据库中添加系统管理员的信息:'''


The initial admin user must be manually added to the user database using sql commands.  Once they are added and given admin privilege, they may add additional users and change privileges of those users via the koji command line tool's administrative commands.  However, if you choose to use the simple user/pass method of authentication, then any password setting/changing must be done manually via sql commands as there is no password manipulation support exposed through the koji tools.
最初的系统管理员信息必须通过 sql 语句手动添加到数据库中。一旦系统管理员的信息添加完毕并且赋予了管理员权限,就可以通过 koji 命令行工具中的系统管理命令添加其他的用户,以及更改这些用户的权限。但是,如果您选择采用简单的用户名/密码认证方式,您只能通过 sql 语句设置/更改用户的密码,因为 koji 命令行工具没有提供密码维护的功能。


The sql commands you need to use vary by authentication mechanism.
根据认证机制的不同,您需要执行不同的 sql 语句。


'''User/Password Authentication:'''
'''用户名/密码认证方式:'''
<pre>
<pre>
root@localhost$ su - koji
root@localhost$ su - koji
Line 310: Line 310:
</pre>
</pre>


'''Kerberos authentication:''' The process is very similar to user/pass except you would replace the first insert above with this:
'''Kerberos 认证方式:''' 除了需要将上面第一条插入语句改写成下面的样子,处理过程和用户名/密码认证方式的处理过程非常相似。


<pre>
<pre>
Line 318: Line 318:
</pre>
</pre>


'''SSL Certificate authentication:''' there is no need for either a password or a Kerberos principal, so this will suffice:
'''SSL 证书认证方式:''' 这种方式既不需要密码也不需要 Kerberos principal,所以像下面这样写就可以了:


<pre>
<pre>
Line 326: Line 326:
</pre>
</pre>


'''Give yourself admin permissions'''
'''为自己分配系统管理员权限'''


The following command will give the user admin permissions. In order to do this you will need to know the ID of the user.
下面的命令将为一个用户分配系统管理员权限。为了完成权限分配工作您需要知道这个用户的 ID
<pre>
<pre>
koji=> insert into user_perms (user_id, perm_id, creator_id) values (<id of user inserted above>, 1, <id of user inserted above>);
koji=> insert into user_perms (user_id, perm_id, creator_id) values (<id of user inserted above>, 1, <id of user inserted above>);
</pre>
</pre>


Note: If you do not know the ID of the admin user, you can get the ID by running the query:
注意:如果您不知道管理员用户的ID,您可以通过以下方法进行查询:
<pre>
<pre>
koji=> select * from users;
koji=> select * from users;
</pre>
</pre>


You can't actually log in and perform any actions until kojihub is up and running in your web server.  In order to get to that point you still need to complete the authentication setup and the kojihub configuration.  If you wish to access koji via a web browser, you will also need to get kojiweb up and running.
kojihub 设置好并且能够在您的网站服务器上运行之前,您不能登录到系统中,也不能进行任何操作。为了能够让 kojihub 正常运行,您还需要完成认证的设置工作以及 kojihub 的配置工作。如果您希望通过浏览器登录系统,您还需要设置 kojiweb,使之正常运行。


== Koji Hub ==
== 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.
Koji-hub 是所有 Koji 操作的核心。它是一个运行在 Apache 服务器的 mod_python 模块下的 XML-RPC 服务器。koji-hub 采用被动方式工作,它只接收 XML-RPC 请求,然后依靠编译守护进程以及其他组件来进行交互。Koji-hub 是唯一可以直接访问数据库的组件,也是两个对文件系统具有写权限的组件之一。




'''Configuration Files:'''
'''配置文件:'''


* /etc/httpd/conf/httpd.conf
* /etc/httpd/conf/httpd.conf
* /etc/httpd/conf.d/kojihub.conf
* /etc/httpd/conf.d/kojihub.conf
* /etc/httpd/conf.d/ssl.conf (when using ssl auth)
* /etc/httpd/conf.d/ssl.conf (如果采用 ssl 认证机制)
* /etc/koji-hub/hub.conf
* /etc/koji-hub/hub.conf




'''Install koji-hub:'''
'''安装 koji-hub:'''
<pre>
<pre>
root@localhost$ yum install koji-hub httpd mod_ssl mod_python
root@localhost$ yum install koji-hub httpd mod_ssl mod_python
</pre>
</pre>


==== Required Configuration ====
==== 必须的配置 ====


'''/etc/httpd/conf/httpd.conf:'''
'''/etc/httpd/conf/httpd.conf:'''


The apache web server has two places that it sets maximum requests a server will handle before the server restarts. The xmlrpc interface in kojihub is a python application, and mod_python can sometimes grow outrageously large when it doesn't reap memory often enough. As a result, it is strongly recommended that you set both instances of MaxRequestsPerChild in httpd.conf to something reasonable in order to prevent the server from becoming overloaded and crashing (at 100 the httpd processes will grow to about 75MB resident set size before respawning).
apache 服务器中有两个地方可以设置服务器重启之前可以处理的最大请求数量。kojihub 中的 xmlrpc 接口是一个 python 应用程序, 当内存不能及时得到回收的时候,mod_python 占用的内容量将急剧增长。因此,为了避免服务器负载过重甚至崩溃,我们强烈建议您将配置文件 httpd.conf 中两个对 MaxRequestsPerChild 进行设置的地方修改为合理的数值(当这个配置项的值为100时,在重新启动 apache 服务前,httpd 进程能够占用到 75MB 内存)


<pre>
<pre>
Line 375: Line 375:
</pre>
</pre>


You'll need to make /mnt/koji/packages web-accessible, either here on the hub, or on koji-web, or on another web server altogether. This URL will later go into the builders' pkgurl config option.
您需要在 koji-hub 或者 koji-web 或者其他的网络服务器上设置 /mnt/koji/packages 的访问权限,使得能够通过网络访问这个目录。后面进行编译机配置时的 pkgurl 项将使用这里配置的 URL 地址。
<pre>
<pre>
Alias /packages/ /mnt/koji/packages/
Alias /packages/ /mnt/koji/packages/
Line 388: Line 388:
'''/etc/koji-hub/hub.conf:'''
'''/etc/koji-hub/hub.conf:'''


This file contains the configuration information for the hub. You will need to edit this configuration to point Koji Hub to the database you are using and to setup Koji Hub to utilize the authentication scheme you selected in the beginning.
这个文件中包含 Koji Hub 的配置信息。您需要编辑这个文件使得 Koji Hub 能够连接到您正使用的数据库,并且 Koji Hub 能够正确识别开始时您选择的认证方式。


<pre>
<pre>
Line 399: Line 399:
</pre>
</pre>


==== Optional Configuration ====
==== 可选的配置 ====
/etc/koji-hub/hub.conf:
/etc/koji-hub/hub.conf:
''If using Kerberos, these settings need to be valid and inline with other services configurations.''
''如果您选择的是 Kerberos 认证方式,下面的这些配置必须修改为有效值,并且与其他的配置项联合使用。''
<pre>
<pre>
AuthPrincipal host/kojihub@EXAMPLE.COM
AuthPrincipal host/kojihub@EXAMPLE.COM
Line 410: Line 410:


/etc/koji-hub/hub.conf:
/etc/koji-hub/hub.conf:
''If using SSL auth, these settings need to be valid and inline with other services configurations for kojiweb to allow logins.
''如果您选择的是 SSL 认证方式,为了使用户可以通过浏览器登录 kojiweb,下面的这些配置必须修改为有效值,并且与其他的配置项联合使用。ProxyDNs应该设置成 kojiweb 证书中DN (DirName)字段的值。''
ProxyDNs should be set to the DN of the kojiweb certificate.''
<pre>
<pre>
DNUsernameComponent = CN
DNUsernameComponent = CN
Line 417: Line 416:
</pre>
</pre>
/etc/httpd/conf.d/kojihub.conf:
/etc/httpd/conf.d/kojihub.conf:
''If using SSL auth, uncomment these lines for kojiweb to allow logins."
''如果您选择的是 SSL 认证方式,请取消下面几个配置项中的注释符,以便户可以通过浏览器登录 kojiweb。"
<pre>
<pre>
<Location /kojihub>
<Location /kojihub>
Line 425: Line 424:


/etc/httpd/conf.d/ssl.conf:
/etc/httpd/conf.d/ssl.conf:
''If using SSL you will also need to add the needed SSL options for apache. These options should point to where the certificates are located on the hub.''
''如果您选择的是 SSL 认证方式,您还需要为 apache 服务器添加一些必须的 SSL 配置项。这些配置项指向 Koji Hub 服务器中证书的保存位置。''
<pre>
<pre>
SSLCertificateFile /etc/pki/koji/certs/kojihub.crt
SSLCertificateFile /etc/pki/koji/certs/kojihub.crt
Line 435: Line 434:
</pre>
</pre>


==== SELinux Configuration ====
==== 配置 SELinux ====
If running in Enforcing mode, you will need to allow apache to connect to the postgreSQL server. Even if you are not running currently running in Enforcing mode it is still recommended to run the following command to ensure that there are no future issues with SELinux if Enforcing mode is later enabled.
如果 SELinux处于 Enforcing 状态,您需要保证 apache 服务能够连接 postgreSQL 服务器。即使 SELinux 目前不是处于 Enforcing 状态,我们仍然建议您执行下面的命令,以确保即使以后 SELinux 启用了 Enforcing 模式了也不会产生新的问题。


<pre>
<pre>
Line 442: Line 441:
</pre>
</pre>


==== Koji filesystem skeleton ====
==== Koji 文件系统框架 ====


Above in the kojihub.conf file we set KojiDir to /mnt/koji.  For certain reasons, if you change this, you should make a symlink from /mnt/koji to the new location (note: this is a bug and should be fixed eventually).  However, before other parts of koji will operate properly, we need to create a skeleton filesystem structure for koji as well as make the file area owned by apache so that the xmlrpc interface can write to it as needed.
在前面 kojihub.conf 文件的配置过程中,我们设置 KojiDir 的路径为 /mnt/koji。如果您处于某种考虑更改了这个路径,您应该创建一个符号链接 /mnt/koji 指向您设置的实际路径(注意:这是一个bug,最终会得到解决的)。切记,在系统其他组件正常工作之前,您需要在设置的目录中创建合适的目录结构,并将这些目录的属主设置为 <code>apache</code> 。这样,在需要的时候 xmlrpc 接口就可以向目录中写入数据了。


<pre>
<pre>
Line 454: Line 453:
</pre>
</pre>


At this point, you can now restart apache and you should have at least minimal operation.  The admin user should be able to connect via the command line client, add new users, etc.  It's possible at this time to undertake initial administrative steps such as adding users and hosts to the koji database.
现在重新启动 apache 服务,您可以对系统进行一些最基本的操作了。比如:系统管理员可以通过命令行工具客户端连接到系统中,添加新用户,等等。现在您可以进行一些系统管理方面的操作,如向数据库中添加用户和编译机。


Ensure that your client is configured to work with your server. The system-wide koji client configuration file is ''/etc/koji.conf'', and the user-specific one is in ''~/.koji/config''. You may also use the "-c" option when using the Koji client to specify an alternative configuration file. The following command will test your login to the hub:
确保您的客户端配置没有问题,能够连接到服务器并且工作正常。对客户端所有用户都可用的配置文件是 ''/etc/koji.conf'',对客户端特定用户可用的配置文件是 ''~/.koji/config''。当使用 Koji 客户端时,您也可以使用"-c"选项指定另外一个配置文件。下面这条命令可以测试您能否正常登录到服务器:


  koji call getLoggedInUser
  koji call getLoggedInUser


If you are using SSL for authentication, you will need to edit the Koji client configuration to tell it which URLs to use for the various Koji components and where their SSL certificates can be found.
如果您选择的是 SSL 认证方式,您需要编辑 Koji 客户端的配置文件,为各种 Koji 组件指定正确的 URL 地址,并且需要指定 SSL 证书在本地的存放位置。


<pre>
<pre>
Line 488: Line 487:
</pre>
</pre>


It is important to note that the kojira component needs repo privileges, but if you just let the account get auto created the first time you run kojira, it won't have that privilege, so you should pre-create the account and grant it the repo privilege now.
需要注意的一点是 kojira 组件需要 repo 权限,第一次运行 kojira 时系统会自动为您创建这个帐号,但是这种方式创建的帐号没有 repo 权限,所以您需要提前创建这个帐号并且马上赋予它 repo 权限。


<pre>
<pre>
Line 495: Line 494:
</pre>
</pre>


For similar technical reasons, you need to add-host each build host prior to starting kojid on that host the first time and could also do that now.
相似的原因,在每台编译机第一次开启 kojid 守护进程之前,您需要运行 add-host 将编译机添加到数据库中,最好现在就做。


<pre>
<pre>
Line 503: Line 502:
</pre>
</pre>


== Koji Web - Interface for the Masses ==
== Koji Web - 用户接口 ==


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.
Koji-web 是一系列运行在 mod_python 模块下,采用 Cheetah 模板引擎生成的脚本文件,它可以对 Koji 提供一套 web 页面接口。通过 koji-web,您可以查看 Koji 系统中很多信息,并且提供了一种方式完成系统中的部分操作,如取消软件包编译任务。


'''Configuration Files:'''
'''配置文件'''


* /etc/httpd/conf.d/kojiweb.conf
* /etc/httpd/conf.d/kojiweb.conf
* /etc/httpd/conf.d/ssl.conf
* /etc/httpd/conf.d/ssl.conf


'''Install Koji-Web:'''
'''安装 Koji-Web:'''
<pre>
<pre>
root@localhost$ yum install koji-web mod_ssl
root@localhost$ yum install koji-web mod_ssl
</pre>
</pre>


==== Required Configuration ====
==== 必须的配置 ====
/etc/httpd/conf.d/kojiweb.conf: You will need to edit the kojiweb configuration file to tell kojiweb which URLs it should use to access the hub, the koji packages and its own web interface. You will also need to tell kojiweb where it can find the SSL certificates for each of these components. If you are using SSL authentication, the "PythonOption WebCert" line below must contain both the public ''and'' private key. You will also want to change the last line in the example below to a unique password.
/etc/httpd/conf.d/kojiweb.conf: 您需要编辑 kojiweb 的配置文件,正确配置 koji-hub 的地址、软件包的存放地址以及 kojiweb 本身的地址。您还需要指定各个组件的 SSL 证书的存放位置。如果您选择的是 SSL 认证方式,下面例子中的"PythonOption WebCert"字段中指定的证书必须既包含公钥''''包含私钥。也许您还希望将下面例子中最后一行更改为一个唯一的密码。
<pre>
<pre>
PythonOption KojiHubURL http://hub.example.com/kojihub
PythonOption KojiHubURL http://hub.example.com/kojihub
Line 533: Line 532:
</pre>
</pre>


==== Optional Configuration ====
==== 可选的配置 ====


You will also need to edit the '''/etc/httpd/conf.d/kojiweb.conf''' to configure it for the authentication scheme you have selected at the beginning of the setup.
您还需要编辑文件 '''/etc/httpd/conf.d/kojiweb.conf''',根据最开始时您选择的认证机制正确配置其中的认证项。




/etc/httpd/conf.d/kojiweb.conf:
/etc/httpd/conf.d/kojiweb.conf:
''If using Kerberos, these settings need to be valid and inline with other services configurations.''
''如果您选择的是 Kerberos 认证方式,下面的这些项必须设置成有效值,并且与其他的配置项联合使用。''
<pre>
<pre>
<Location /koji/login>
<Location /koji/login>
Line 555: Line 554:
</pre>
</pre>


{{admon/tip|RHEL 5's mod_python publisher does not support non-basic auth, so Kerberos authentication does not currently work in EPEL 5's Koji-web. See [https://bugzilla.redhat.com/682319 BZ #682319].}}
{{admon/tip|RHEL 5 系统中的 mod_python 模块不支持非基本认证方式,所以目前 EPEL 5 Koji-web中,Kerberos 认证机制不能正常工作。参见 [https://bugzilla.redhat.com/682319 BZ #682319]}}


/etc/httpd/conf.d/kojiweb.conf:
/etc/httpd/conf.d/kojiweb.conf:
''If using SSL, these settings need to be valid and inline with other services configurations.''
''如果您选择的是 SSL 认证方式,下面的这些项必须设置成有效值,并且与其他的配置项联合使用。''
<pre>
<pre>
<Location /koji/login>
<Location /koji/login>
Line 566: Line 565:


/etc/httpd/conf.d/ssl.conf:
/etc/httpd/conf.d/ssl.conf:
''If you are using SSL you will need to add the needed SSL options for apache.''
''如果您选择的是 SSL 认证方式,您需要为 apache 添加必需的 SSL 选项。''
<pre>
<pre>
SSLVerifyClient require
SSLVerifyClient require
Line 572: Line 571:
</pre>
</pre>


==== Web interface now operational ====
==== 网站可以工作了 ====


At this point you should be able to point your web browser at the kojiweb URL and be presented with the koji interface.  Many operations should work in read only mode at this point, and any configured users should be able to log in.
现在您可以在您的浏览器中输入 kojiweb 的地址,您会看到系统的 web 页面。当然,现在您只可以浏览系统中的数据。如果您已经设置好了证书,就可以登录系统了。


== Koji Daemon - Builder ==
== Koji 守护进程 - 编译机 ==


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 such as creating livecd images or raw disk images, and kojid is responsible for handling these tasks as well. kojid uses mock for creating pristine build environments and creates a fresh one for every build, ensuring that artifacts of build processes cannot contaminate each other. kojid is written in Python and communicates with koji-hub via XML-RPC.
Kojid 是运行在每一台编译机上的编译守护进程。它的主要任务是查询发送过来的编译请求,根据实际情况进行处理。除了编译软件包 Koji 还支持其他的任务,比如制作 livecd 镜像文件或者原始磁盘镜像文件,这些任务也由 kojid 进行处理。kojid 利用 mock 创建原始的编译环境,并且为每一次编译任务单独创建一个编译环境, 确保编译过程不会受到其他编译过程的干扰。kojid 是用 Python 编写的,并且通过 XML-RPC 与 koji-hub 进行通信。


'''Configuration Files:'''
'''配置文件'''


* /etc/kojid/kojid.conf - Koji Daemon Configuration
* /etc/kojid/kojid.conf - Kojid 守护进程配置文件
* /etc/sysconfig/kojid - Koji Daemon Switches
* /etc/sysconfig/kojid - Kojid 守护进程开关


'''Install kojid:'''
'''安装 kojid:'''
<pre>
<pre>
root@localhost$ yum install koji-builder
root@localhost$ yum install koji-builder
</pre>
</pre>


==== Required Configuration ====
==== 必须的配置 ====


/etc/kojid/kojid.conf:
/etc/kojid/kojid.conf:
''The configuration file for each koji builder must be edited so that the line below points to the URL for the koji hub. The user tag must also be edited to point to the username used to add the koji builder.''
''您需要编辑每个编译机上的这个配置文件,server项需要指向 koji hub 的 URL,user 项是您在添加编译机时为编译机指定的名称。''
<pre>
<pre>
; The URL for the xmlrpc server
; The URL for the xmlrpc server
Line 603: Line 602:
</pre>
</pre>


''This item may be changed, but may not be the same as KojiDir on the kojihub.conf file (although it can be something under KojiDir, just not the same as KojiDir)''
''您可以修改下面这个配置项的路径,但是不能够与 kojihub.conf 文件中配置的 KojiDir 相同(可以是 KojiDir 中的子目录,只要不和 KojiDir 相同就行了)''
<pre>
<pre>
; The directory root for temporary storage
; The directory root for temporary storage
Line 609: Line 608:
</pre>
</pre>


==== Optional Configuration (SSL certificates) ====
==== 可选的配置 (SSL 证书) ====


/etc/kojid/kojid.conf:
/etc/kojid/kojid.conf:
''If you are using SSL, these settings need to be edited to point to the certificates you generated at the beginning of the setup process.''
''如果您选择的是 SSL 认证方式,您需要修改下面这些配置项的值,使之指向系统开始搭建时您创建的证书的存放位置。''
<pre>
<pre>
;client certificate
;client certificate
Line 626: Line 625:
</pre>
</pre>


It is important to note that if your builders are hosted on seperate machines from koji hub and koji web, you will need to scp the certificates mentioned in the above configuration file from the /etc/kojid/ directory on koji hub to the /etc/koji/ directory on the local machine so that the builder can be authenticated.
值得注意的一点是如果您的编译机和安装 koji hub koji web 的服务器不是一台机器,您需要将上面配置文件中提到的证书从服务器的 /etc/kojid/ 目录中拷贝到编译机的 /etc/koji/ 目录中,这样编译机才可以进行认证。


==== Optional Configuration (Kerberos Authentication) ====
==== 可选的配置 (Kerberos 认证) ====


/etc/kojid/kojid.conf:
/etc/kojid/kojid.conf:
''If using Kerberos, these settings need to be valid and inline with other services configurations.''
''如果您选择的是 Kerberos 认证方式,下面的这些项必须设置成有效值,并且与其他的配置项联合使用。''


<pre>
<pre>
Line 640: Line 639:
</pre>
</pre>


By default it will look for the Kerberos keytab in /etc/kojid/kojid.keytab
默认情况下它将寻找 /etc/kojid/kojid.keytab 文件中的 Kerberos keytab。


'''Note:''' Kojid will not attempt kerberos authentication to the koji-hub unless the username field is commented out
'''注意:''' Kojid 不会试图向 koji-hub 进行 kerberos 认证,除非 username 项被注释掉了


==== Add the host entry for the koji builder to the database ====
==== 将代表 koji 编译机的主机条目添加到数据库中 ====
You will now need to add the koji builder to the database so that they can be utilized by kojij hub. Make sure you do this before you start kojid for the first time,
现在您需要将编译机的信息添加到数据库中,这样 koji hub 就可以使用编译机了。确保这些工作在您第一次开启 kojid 守护进程之前完成,否则为了使系统正常工作,您不得不手动删除数据库中 sessions users 表中的记录。
or you'll need to manually remove entries from the sessions and users
table before it can be run successfully.
<pre>
<pre>
kojiadmin@localhost$ koji add-host kojibuilder1.example.com i386 x86_64
kojiadmin@localhost$ koji add-host kojibuilder1.example.com i386 x86_64
</pre>
</pre>
The first argument used after the ''add-host'' command should the username of the builder. The second argument is used to specify the architecture which the builder uses.
''add-host'' 命令后面第一个参数应该是编译机的主机名,第二个参数用来指定编译机支持的系统架构类型。


==== Add the host to the createrepo channel ====
==== 将主机添加到 createrepo 频道中 ====
Channels are a way to control which builders process which tasks.  By default
频道是用来控制哪台编译机可以执行哪种类型任务的一种方法。默认情况下,编译机被加入到 ''default'' 频道中。至少还需要将部分编译机添加到 ''createrepo'' 频道,这样就有编译机来执行 kojira 提交的 repo creation 任务了。
hosts are added to the ''default'' channel.  At least some build hosts also needs to be added
to the ''createrepo'' channel so there will be someone to process repo creation tasks initiated by kojira.


<pre>
<pre>
Line 662: Line 657:
</pre>
</pre>


==== A note on capacity ====
==== 关于负载能力的一点说明 ====
The default capacity of a host added to the host database is 2.  This means that once the load average on that machine exceeds 2, kojid will not accept any additional tasks.  This is separate from the maxjobs item in the configuration file.  Before kojid will accept a job, it must pass both the test to ensure the load average is below capacity and that the current number of jobs it is already processing is less than maxjobs.  However, in today's modern age of quad core and higher CPUs, a load average of 2 is generally insufficient to fully utilize hardware.  As there is not an option to set the capacity of the host via the command line tools, it must be done manually in psql.
添加到数据库的 host 表中的编译机的默认负载能力是 2。这意味着如果一台编译机的平均负载超过了 2,编译机上的 kojid 守护进程将不再接收新的任务。这和配置文件中的最大任务数是两个不同的控制量。kojid 在接收一个任务之前需要先检查系统负载和待执行的任务数量, 确保平均负载没有超过编译机的平均负载能力,并且kojid已经接收等待执行的任务数量小于最大任务数。然而,在四核甚至更多核 CPU 广泛使用的今天,将平均负载设定为 2 不能充分发挥硬件的性能。因为命令行工具没有提供一个方法来修改编译机的负载能力,必须通过手动修改数据库中的数据来实现。


<pre>
<pre>
Line 679: Line 674:
</pre>
</pre>


==== Start Kojid ====
==== 开启 Kojid ====


Once the builder has been added to the database you must start kojira
一旦将编译机的信息添加到了数据库中,您必须开启编译机中的 kojid 守护进程。
<pre>
<pre>
root@localhost$ /sbin/service kojid start
root@localhost$ /sbin/service kojid start
</pre>
</pre>
Check /var/log/kojid.log to verify that kojid has started successfully. If the log does not show any errors then the koji builder should be up and ready. You can check this by pointing your web browser to the web interface and clicking on the hosts tab. This will show you a list of builders in the database and the status of each builder.
请检查日志文件 /var/log/kojid.log 确保 kojid 已经成功开启。如果日志文件没有显示任何错误信息,编译机就已经配置好了,可以开始工作了。您可以在浏览器中输入系统的网址,点击 hosts 标签,这个页面会显示数据库中编译机的列表以及每台编译机的状态信息。


== Kojira - Yum repository creation and maintenance ==
== Kojira - 创建和维护 Yum ==
'''Configuration Files:'''
'''配置文件:'''


* /etc/kojira/kojira.conf - Kojira Daemon Configuration
* /etc/kojira/kojira.conf - Kojira 守护进程配置文件
* /etc/sysconfig/kojira - Kojira Daemon Switches
* /etc/sysconfig/kojira - Kojira 守护进程开关


'''Install kojira'''
'''安装 kojira'''
<pre>
<pre>
root@localhost$ yum install koji-utils
root@localhost$ yum install koji-utils
</pre>
</pre>


==== Required Configuration ====
==== 必须的配置 ====


/etc/kojira/kojira.conf:
/etc/kojira/kojira.conf:
''This needs to point at your koji-hub.''
''这个配置选项需要指向您的 koji-hub 地址''
<pre>
<pre>
; The URL for the xmlrpc server
; The URL for the xmlrpc server
Line 709: Line 704:
<br>
<br>


'''Additional Notes:'''
'''附加说明:'''
* Kojira needs read-write access to /mnt/koji.
* Kojira 需要对目录 /mnt/koji 具有读写权限。
* There should only be one instance of kojira running at any given time.
* 任何时候只允许同时运行一个 kojira 的实例。
* It is not recommended that kojira run on the builders, as builders only should require read-only access to /mnt/koji.
* 最好不要在编译机上运行 kojira ,因为编译机只需要具有目录 /mnt/koji 的只读权限就可以了。


==== Optional Configuration ====
==== 可选的配置 ====


/etc/kojira/kojira.conf:
/etc/kojira/kojira.conf:
''If using SSL, these settings need to be valid.''
''如果您选择的是 SSL 认证方式,下面这些项必须设置成有效值。''
<pre>
<pre>
;client certificate
;client certificate
Line 730: Line 725:
</pre>
</pre>


''If using Kerberos, these settings need to be valid.''
''如果您选择的是 Kerberos 认证方式,下面这些项必须设置成有效值。''
<pre>
<pre>
; For Kerberos authentication
; For Kerberos authentication
Line 740: Line 735:


/etc/sysconfig/kojira:
/etc/sysconfig/kojira:
''The local user kojira runs as needs to be able to read and write to /mnt/koji/repos/.
''本地用户 kojira 需要对目录 /mnt/koji/repos/ 具有读写权限。如果该目录所在的磁盘分区是 root-squashed 或者 root 用户没有修改权限,您可以将 '''RUNAS=''' 设置成一个对该目录有读写权限的用户。''
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 ====
==== 在数据库中为 kojira 用户添加用户条目 ====
If you did not already do so above, create the kojira user, and grant it the '''repo''' permission.
如果您还没有添加 kojira 用户,请现在添加,并且赋予它  '''repo''' 权限。
<pre>
<pre>
kojiadmin@localhost$ koji add-user kojira
kojiadmin@localhost$ koji add-user kojira
Line 751: Line 744:
</pre>
</pre>


=== Start Kojira ===
=== 开启 Kojira ===
<pre>
<pre>
root@localhost$ /sbin/service kojira start
root@localhost$ /sbin/service kojira start
</pre>
</pre>
Check /var/log/kojira/kojira.log to verify that kojira has started successfully.
请检查文件/var/log/kojira/kojira.log 确保 kojira 已经成功启动了。


== Bootstrapping the Koji build environment ==
== 配置 Koji 编译环境 ==
For instructions on importing packages and preparing Koji to run builds, see [[Koji/ServerBootstrap|  Server Bootstrap]] .
如果您想导入软件包,配置好 Koji 系统,以便在系统中编译RPM包,参见[[Koji/ServerBootstrap/zh-cn服务器配置]]


For instructions on using External Repos and preparing Koji to run builds, see [[Koji/ExternalRepoServerBootstrap|  External Repo Server Bootstrap]] .
如果您想使用外部库 ,配置好 Koji 系统,以便在系统中编译RPM包,参见[[Koji/ExternalRepoServerBootstrap|  外部库配置]]


Useful scripts and config files for setting up a Koji instance are available [http://fedora.danny.cz/koji/ here]
[http://fedora.danny.cz/koji/ 这里]有一些搭建 Koji 系统时有用的脚本和配置文件。


== Minutia and Miscellany ==
== 细节和杂项 ==
Please see [[Koji/KojiMisc| KojiMisc]] for additional details and notes about operating a koji server.
如果您需要查看 koji 使用过程中的更多细节和注意事项,请阅读[[Koji/KojiMisc| Koji 杂项]]

Latest revision as of 08:46, 5 March 2016

搭建一套 Koji 编译系统

Koji 编译系统的各个组件可以分别搭建在不同的设备上,只要这些设备之间可以相互通信就可以了。这篇文章将描述在不同的设备上分别设置各个服务的过程,然而,所有服务也可以搭建在同一台设备上。

必备知识

您必须要掌握:

  • 通过 SSL 证书和/或通过 Kerberos 凭据认证的基础知识
  • 在 PostgreSQL 中创建数据库以及向数据库中导入视图的基础知识。
  • psql 命令的使用方法
  • 能够对 Apache 进行配置
  • yum、createrepo和mock 的使用方法,否则当出现问题时您没办法进行调试!
  • 能够使用命令行终端进行操作
  • 关于RPM 编译的基本知识
  • 能够简单使用 Koji 客户端
  • 如果您想了解 yum、mock、Koji (以及它的各个组成部分)、mash的基本信息,以及它们是如何协调工作的,请浏览 Steve Traylen 在 CERN 上放映的精彩幻灯片[1].

基础软件包

服务器端(koji-hub/koji-web)

  • httpd
  • mod_ssl
  • postgresql-server
  • mod_python (为了满足 Kerberos 认证功能,mod_python 版本需要大于等于3.3.1)

编译机端 (koji-builder)

  • mock
  • setarch (某些特殊的系统架构中需要安装打过补丁的版本)
  • rpm-build
  • createrepo

关于文件系统容量的说明

Koji 需要消耗主目录 KojiDir (这个目录可以在 kojihub.conf 文件中进行配置)下大量的磁盘空间。然而,因为 koji 实际上是在后台调用 mock 来创建编译环境,然后在编译环境中执行软件包编译过程。一台正在运行的 koji 服务器同样会消耗 /var/lib/mock 和 /var/cache/mock 下大量的磁盘空间,用户对此感到很奇怪。用户或者可以为此规划合适的磁盘分配方案,或者可以在配置文件 kojid.conf 中修改 mock 编译软件包的默认路径。如果您更改了这个路径,请确认更改后的路径属于用户组 "mock",并且该路径具有 02755 访问权限。

为 Koji 选择认证机制

Koji 主要支持 Kerberos 和 SSL 证书两种认证机制。在基本的命令行终端模式中,Koji 还支持基于明文的用户名/密码的认证方式。然而,kojiweb 支持用户名/密码认证方式,并且一旦 kojiweb 采用了 Kerberos 或者 SSL 证书认证方式, 用户名/密码认证方式将会完全失去作用。 因此,我们建议从系统搭建开始就不要采用用户名/密码认证方式,而是合理配置 Kerberos 或者 SSL 证书认证方式。

采用哪种认证方式将会影响到 koji 系统搭建过程中的所有其他方面,因此您最好现在就选定一种认证方式。

如果您选择的是 Kerberos 认证方式,为了初始化用户数据库,您需要一个正常的 Kerberos 环境(我们假设您已经有了一个这样的环境或者您知道如何搭建一个这样的环境,本文中不会讲解 Kerberos 环境的搭建过程)和初始管理员的 Kerberos 凭证。

如果您选择的是 SSL 认证方式,您需要为 xmlrpc 服务器、koji 中各种组件和系统管理员创建 SSL 证书。您不需要提前知道证书的创建方法,我们在后面会详细介绍证书的创建过程。

设置 SSL 证书进行认证

生成证书

  • 创建一个新目录 /etc/pki/koji,将下面的内容保存在该目录新创建的文件 ssl.cnf 中。这个配置文件和 openssl 命令配合使用,用来生成 koji 各个组件需要的 SSL 证书。

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              = sha256
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

虽然不是必须的,但是我们建议您根据自己的实际信息修改配置文件中[req_distinguished_name]部分的默认值。这样,当您创建证书的时候您就可以使用大部分的默认值而不需要自己填写信息。配置文件中的其他部分不需要修改。


生成 CA 证书

CA 证书用来标识 SSL 证书的颁发机构。它是用来签发其他证书的密钥/证书对。当配置 koji 中各种组件时,客户端和服务器端的 CA 证书都使用这里生成的 CA 证书的一份拷贝。CA 证书将被放置在目录 /etc/pki/koji 中,koji 各个组件的证书将放置在目录 /etc/pki/koji/certs 中。另外需要创建一个 index.txt 文件,这个文件作为数据库保存了已经创建的证书的信息。通过查看文件 index.txt 的内容,我们可以方便地查看任何证书的信息。

cd /etc/pki/koji/
mkdir {certs,private}
touch index.txt
echo 01 > serial
caname=koji
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

上面脚本中的最后一条命令会提示您输入与正在创建的证书相关的一组信息。想必您已经修改了配置文件 ssl.cnf 中国家、州/省、城市和机构这几个字段的默认值,因此您直接按回车键就可以了。部门和通用名两个字段的值需要根据不同的证书进行修改。对于 CA 证书,这些字段的取值没有硬性的规定,一种建议是使用服务器的完整域名(FQDN)。


为 koji 各个组件和系统管理员创建证书

Koji中的每个组件都需要一个单独的证书标识自己。其中两个组件(kojihub and kojiweb)的证书作为服务器端的证书用来提供服务器端到客户端的认证。基于这个原因,您希望用运行这两个组件的网络服务器的完整域名(FQDN)作为这两个证书中的通用名。这样,客户端就不会抱怨证书中的通用名和服务器不一致。为了便于认证,您可以将这两个证书中的 OU( 部门名称)分别设置为 kojihub 和 kojiweb。

对于其他的证书(kojira、kojid、初始的系统管理员用户以及所有用户的证书)来说, 这些证书用来提供客户端到服务器端的认证功能。证书的通用名应该设置成组件或者用户的登录名。例如,kojira 证书中的通用名应该设置成 kojira,这样登录名就和组件的名称一致了。这样做的原因是证书中的通用名需要和数据库中组件或用户的名称保持一致。如果在数据库中找不到和证书中 CN (通用名)相匹配的组件或者用户,客户端将不能通过认证,也就不能登录系统。

在后面的步骤中,您会通过 koji add-host 命令向数据库中添加一个编译机。系统将会为这个编译机创建一个帐号,虽然这个帐号不会显示在用户列表中。创建的帐号必须与组件登录服务器时使用的证书中的通用名相同。当您为 kojiweb 创建证书的时候,您需要牢牢记住您为每一个选项填写的值,您需要根据这些选项的值组合出配置文件/etc/koji-hub/hub.conf 中 ProxyDNs 选项的值。

当您需要创建多个证书的时候,一种简便的方法是编写像下面列出的代码这样的循环语句,甚至可以将这些循环语句写到一个脚本文件中,然后执行这个脚本文件。您只需要按照自己的意愿简单地调整代码中编译机的数量和系统管理员的名称就可以了。在本文档中,我们设置系统管理员的名称为 "kojiadmin"。

for user in kojira kojiweb kojihub kojibuilder{1..5} admin-account; do
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 > ${user}.pem
done

为用户创建一个 PKCS12 证书(用于通过浏览器登录系统) 只需要为实际的用户创建这个证书。

openssl pkcs12 -export -inkey certs/${user}.key -in certs/${user}.crt -CAfile ${caname}_ca_cert.crt \
-out certs/${user}_browser_cert.p12

当为用户创建证书的时候,我们需要通过上面的代码为用户创建三个证书文件,分别为:${user}.pem、 ${caname}_ca_cert.crt 和 ${user}_browser_cert.p12。一般情况下,我们将 ${user}.pem 放置在 ~/.fedora.cert,将 ${caname}_ca_cert.crt 拷贝两份分别放置在 ~/.fedora-upload-ca.cert 和 ~/.fedora-server-ca.cert,将 ${user}_brower_cert.p12 作为用户证书导入到浏览器中。


为 kojiadmin 将证书拷贝到 ~/.koji

有时候您想向 kojihub 发送需要具有管理员权限的命令。为了达到这个目的,您需要用刚生成的证书向 kojihub 进行认证。将 CA 证书和 kojiadmin 的证书拷贝到 ~/.koji:

kojiadmin@localhost$ mkdir ~/.koji
kojiadmin@localhost$ cp /etc/pki/koji/kojiadmin.pem ~/.koji/client.crt
kojiadmin@localhost$ cp /etc/pki/koji/koji_ca_cert.crt ~/.koji/clientca.crt
kojiadmin@localhost$ cp /etc/pki/koji/koji_ca_cert.crt ~/.koji/serverca.crt

注意:配置文件 /etc/koji.conf 中保存了对本机中所有用户都有效的 koji 客户端配置。如果您想针对每个用户进行不同的配置,请将 /etc/koji.conf 拷贝到 ~/.koji/config。

设置 Kerberos 进行认证

kerberos 服务的初始设置过程不在本文档的讲解范围之内,然而您需要针对 koji 进行一些特定的设置。

DNS

对于任何给定的域,koji 编译机(kojid) 使用 DNS 查找 kerberos 服务器。

_kerberos._udp    IN SRV  10 100 88 kerberos.EXAMPLE.COM.

最后的句点表示 DNS 根。如果使用完整域名(FQDN),这个句点是必须的。


Principals and Keytabs

需要注意的是当为服务生成 keytab文件时 时,通常情况下您需要使用主机的完整域名。

为了配置Kerberos认证,您需要将下列 principal 包含到 keytab 文件中。向 koji-hub 认证时使用的 key 目前写死在了 koji 客户端中。

  • host/kojihub@EXAMPLE.COM
    • 被 koji-hub 服务器使用,用来与 koji 客户端进行通信
  • HTTP/kojiweb@EXAMPLE.COM
    • 被 koji-web 服务器使用,与网页浏览器协商进行 Kerberos 认证。 这是一个 Apache 的 mod_auth_kerb 模块中的服务实体。
  • koji/kojiweb@EXAMPLE.COM
    • 被 the koji-web 服务器使用,用来与 koji-hub 进行通信。 这是一个用户 principal,将 koji-web 标识成"koji/kojiweb@EXAMPLE.COM"向 Kerberos 进行认证。Koji-web 将代理用户通过 mod_auth_kerb 发送到 koji-hub 的信息(通过 koji-hub 配置文件中的 ProxyPrincipals 进行配置)。
  • koji/kojira@EXAMPLE.COM
    • 被 kojira 服务器使用,用来与 koji-hub 进行通信
  • compile/builder1@EXAMPLE.COM
    • 被 builder1 使用,用来与 koji-hub 进行通信

PostgreSQL 服务器

一旦认证机制配置完毕,您需要安装和配置一个 PostgreSQL 服务器,在服务器中创建一个数据库用来保存用户的信息。

配置文件:

  • /var/lib/pgsql/data/pg_hba.conf
  • /var/lib/pgsql/data/postgresql.conf

安装 PostgreSQL:

root@localhost$ yum install postgresql-server

初始化 PostgreSQL 数据库:

下面的命令用来初始化 PostgreSQL 并且开启数据库服务

root@localhost$ service postgresql initdb
root@localhost$ service postgresql start
Fedora 16 中的 initdb
Fedora 16 中 PostgreSQL 的初始化方式已经采用了 systemd 机制,因此 initdb 命令已经不存在了。您需要直接执行下面的命令初始化PostgreSQL:
su - postgres -c "PGDATA=/var/lib/pgsql/data initdb"

设置用户帐号

下面的命令可以创建一个名称为 koji 的帐号,并且为该帐号设置密码。

root@localhost$ useradd koji
root@localhost$ passwd -d koji

设置 PostgreSQL 并导入视图:

下面的命令可以在 PostgreSQL 中创建一个名称为 koji 的帐号,然后用 /usr/share/doc/koji*/docs/schema.sql 中的视图初始化一个名称为 koji 的数据库。

root@localhost$ su - postgres
postgres@localhost$ 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
postgres@localhost$ createdb -O koji koji
postgres@localhost$ logout
root@localhost$ su - koji
koji@localhost$ psql koji koji < /usr/share/doc/koji*/docs/schema.sql
koji@localhost$ exit

注意: 当您执行上面的命令将视图导入到新建的数据库中时,确保路径 /usr/share/doc/koji*/docs/schema.sql 保持原样,不要替换成具体的 koji 版本。在测试过程中我们发现,当替换成一个指定版本的路径时,数据库中有些表将不能正确创建。


认证 Koji-web 和 Koji-hub 设备: 在这个例子中,Koji-web 和 Koji-hub 在本地设备上运行。

/var/lib/pgsql/data/pg_hba.conf: 下面的这些配置必须修改为有效值,并且与其他的配置项联合使用。 请注意,第一条匹配的认证项将起作用,所以下面新添的认证项必须位于其他认证项的前面。 添加:

host    koji        koji        127.0.0.1/32          trust
host    koji        koji          ::1/128             trust

您也可以使用 UNIX 套接字连接方式。如果使用这种连接方式,DBHost 项必须保持为空白。 添加:

local   koji        apache                            trust
local   koji        apache      127.0.0.1/32          trust
local   koji        apache        ::1/128             trust
local   koji        koji                              trust

使认证项生效:

下面的命令可以让 postgreSQL 知道配置项发生了变化,强迫 postgreSQL 重新加载配置项,因此您做的修改就可以生效了

root@localhost$ su - postgres
postgres@localhost$ pg_ctl reload
postgres@localhost$ exit

在 PostgreSQL 数据库中添加系统管理员的信息:

最初的系统管理员信息必须通过 sql 语句手动添加到数据库中。一旦系统管理员的信息添加完毕并且赋予了管理员权限,就可以通过 koji 命令行工具中的系统管理命令添加其他的用户,以及更改这些用户的权限。但是,如果您选择采用简单的用户名/密码认证方式,您只能通过 sql 语句设置/更改用户的密码,因为 koji 命令行工具没有提供密码维护的功能。

根据认证机制的不同,您需要执行不同的 sql 语句。

用户名/密码认证方式:

root@localhost$ su - koji
koji@localhost$ psql
koji=> insert into users (name, password, status, usertype) values ('admin-user-name', 'admin-password-in-plain-text', 0, 0);

Kerberos 认证方式: 除了需要将上面第一条插入语句改写成下面的样子,处理过程和用户名/密码认证方式的处理过程非常相似。

root@localhost$ su - koji
koji@localhost$ psql
koji=> insert into users (name, krb_principal, status, usertype) values ('admin-user-name', 'admin@EXAMPLE.COM', 0, 0);

SSL 证书认证方式: 这种方式既不需要密码也不需要 Kerberos principal,所以像下面这样写就可以了:

root@localhost$ su - koji
koji@localhost$ psql
koji=> insert into users (name, status, usertype) values ('admin-user-name', 0, 0);

为自己分配系统管理员权限

下面的命令将为一个用户分配系统管理员权限。为了完成权限分配工作您需要知道这个用户的 ID 。

koji=> insert into user_perms (user_id, perm_id, creator_id) values (<id of user inserted above>, 1, <id of user inserted above>);

注意:如果您不知道管理员用户的ID,您可以通过以下方法进行查询:

koji=> select * from users;

在 kojihub 设置好并且能够在您的网站服务器上运行之前,您不能登录到系统中,也不能进行任何操作。为了能够让 kojihub 正常运行,您还需要完成认证的设置工作以及 kojihub 的配置工作。如果您希望通过浏览器登录系统,您还需要设置 kojiweb,使之正常运行。

Koji Hub

Koji-hub 是所有 Koji 操作的核心。它是一个运行在 Apache 服务器的 mod_python 模块下的 XML-RPC 服务器。koji-hub 采用被动方式工作,它只接收 XML-RPC 请求,然后依靠编译守护进程以及其他组件来进行交互。Koji-hub 是唯一可以直接访问数据库的组件,也是两个对文件系统具有写权限的组件之一。


配置文件:

  • /etc/httpd/conf/httpd.conf
  • /etc/httpd/conf.d/kojihub.conf
  • /etc/httpd/conf.d/ssl.conf (如果采用 ssl 认证机制)
  • /etc/koji-hub/hub.conf


安装 koji-hub:

root@localhost$ yum install koji-hub httpd mod_ssl mod_python

必须的配置

/etc/httpd/conf/httpd.conf:

apache 服务器中有两个地方可以设置服务器重启之前可以处理的最大请求数量。kojihub 中的 xmlrpc 接口是一个 python 应用程序, 当内存不能及时得到回收的时候,mod_python 占用的内容量将急剧增长。因此,为了避免服务器负载过重甚至崩溃,我们强烈建议您将配置文件 httpd.conf 中两个对 MaxRequestsPerChild 进行设置的地方修改为合理的数值(当这个配置项的值为100时,在重新启动 apache 服务前,httpd 进程能够占用到 75MB 内存)。

<IfModule prefork.c>
...
MaxRequestsPerChild  100
</IfModule>
<IfModule worker.c>
...
MaxRequestsPerChild  100
</IfModule>

您需要在 koji-hub 或者 koji-web 或者其他的网络服务器上设置 /mnt/koji/packages 的访问权限,使得能够通过网络访问这个目录。后面进行编译机配置时的 pkgurl 项将使用这里配置的 URL 地址。

Alias /packages/ /mnt/koji/packages/
<Directory "/mnt/koji/packages">
    Options Indexes
    AllowOverride None
    Order allow,deny
    Allow from all
</Directory>

/etc/koji-hub/hub.conf:

这个文件中包含 Koji Hub 的配置信息。您需要编辑这个文件使得 Koji Hub 能够连接到您正使用的数据库,并且 Koji Hub 能够正确识别开始时您选择的认证方式。

DBName = koji
DBUser = koji
DBHost = db.example.com
KojiDir = /mnt/koji
LoginCreatesUser = On
KojiWebURL = http://kojiweb.example.com/koji

可选的配置

/etc/koji-hub/hub.conf: 如果您选择的是 Kerberos 认证方式,下面的这些配置必须修改为有效值,并且与其他的配置项联合使用。

AuthPrincipal host/kojihub@EXAMPLE.COM
AuthKeytab /etc/koji.keytab
ProxyPrincipals koji/kojiweb@EXAMPLE.COM
HostPrincipalFormat compile/%s@EXAMPLE.COM

/etc/koji-hub/hub.conf: 如果您选择的是 SSL 认证方式,为了使用户可以通过浏览器登录 kojiweb,下面的这些配置必须修改为有效值,并且与其他的配置项联合使用。ProxyDNs应该设置成 kojiweb 证书中DN (DirName)字段的值。

DNUsernameComponent = CN
ProxyDNs = "/C=US/ST=Massachusetts/O=Example Org/OU=Example User/CN=example/emailAddress=example@example.com"

/etc/httpd/conf.d/kojihub.conf: 如果您选择的是 SSL 认证方式,请取消下面几个配置项中的注释符,以便户可以通过浏览器登录 kojiweb。"

<Location /kojihub>
SSLOptions +StdEnvVars
</Location>

/etc/httpd/conf.d/ssl.conf: 如果您选择的是 SSL 认证方式,您还需要为 apache 服务器添加一些必须的 SSL 配置项。这些配置项指向 Koji Hub 服务器中证书的保存位置。

SSLCertificateFile /etc/pki/koji/certs/kojihub.crt
SSLCertificateKeyFile /etc/pki/koji/certs/kojihub.key
SSLCertificateChainFile /etc/pki/koji/koji_ca_cert.crt
SSLCACertificateFile /etc/pki/koji/koji_ca_cert.crt
SSLVerifyClient require
SSLVerifyDepth  10

配置 SELinux

如果 SELinux处于 Enforcing 状态,您需要保证 apache 服务能够连接 postgreSQL 服务器。即使 SELinux 目前不是处于 Enforcing 状态,我们仍然建议您执行下面的命令,以确保即使以后 SELinux 启用了 Enforcing 模式了也不会产生新的问题。

root@localhost$ setsebool -P httpd_can_network_connect_db 1

Koji 文件系统框架

在前面 kojihub.conf 文件的配置过程中,我们设置 KojiDir 的路径为 /mnt/koji。如果您处于某种考虑更改了这个路径,您应该创建一个符号链接 /mnt/koji 指向您设置的实际路径(注意:这是一个bug,最终会得到解决的)。切记,在系统其他组件正常工作之前,您需要在设置的目录中创建合适的目录结构,并将这些目录的属主设置为 apache 。这样,在需要的时候 xmlrpc 接口就可以向目录中写入数据了。

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

现在重新启动 apache 服务,您可以对系统进行一些最基本的操作了。比如:系统管理员可以通过命令行工具客户端连接到系统中,添加新用户,等等。现在您可以进行一些系统管理方面的操作,如向数据库中添加用户和编译机。

确保您的客户端配置没有问题,能够连接到服务器并且工作正常。对客户端所有用户都可用的配置文件是 /etc/koji.conf,对客户端特定用户可用的配置文件是 ~/.koji/config。当使用 Koji 客户端时,您也可以使用"-c"选项指定另外一个配置文件。下面这条命令可以测试您能否正常登录到服务器:

koji call getLoggedInUser

如果您选择的是 SSL 认证方式,您需要编辑 Koji 客户端的配置文件,为各种 Koji 组件指定正确的 URL 地址,并且需要指定 SSL 证书在本地的存放位置。

[koji]

;url of XMLRPC server
server = http://hongkong.proximity.on.ca/kojihub

;url of web interface
weburl = http://hongkong.proximity.on.ca/koji

;url of package download site
pkgurl = http://hongkong.proximity.on.ca/packages

;path to the koji top directory
topdir = /mnt/koji

;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

需要注意的一点是 kojira 组件需要 repo 权限,第一次运行 kojira 时系统会自动为您创建这个帐号,但是这种方式创建的帐号没有 repo 权限,所以您需要提前创建这个帐号并且马上赋予它 repo 权限。

kojiadmin@localhost$ koji add-user kojira
kojiadmin@localhost$ koji grant-permission repo kojira

相似的原因,在每台编译机第一次开启 kojid 守护进程之前,您需要运行 add-host 将编译机添加到数据库中,最好现在就做。

kojiadmin@localhost$ koji add-host kojibuilder1 x86_64 i386
kojiadmin@localhost$ koji add-host kojibuilder2 ppc ppc64
kojiadmin@localhost$ koji add-host kojibuilder3 ia64

Koji Web - 用户接口

Koji-web 是一系列运行在 mod_python 模块下,采用 Cheetah 模板引擎生成的脚本文件,它可以对 Koji 提供一套 web 页面接口。通过 koji-web,您可以查看 Koji 系统中很多信息,并且提供了一种方式完成系统中的部分操作,如取消软件包编译任务。

配置文件

  • /etc/httpd/conf.d/kojiweb.conf
  • /etc/httpd/conf.d/ssl.conf

安装 Koji-Web:

root@localhost$ yum install koji-web mod_ssl

必须的配置

/etc/httpd/conf.d/kojiweb.conf: 您需要编辑 kojiweb 的配置文件,正确配置 koji-hub 的地址、软件包的存放地址以及 kojiweb 本身的地址。您还需要指定各个组件的 SSL 证书的存放位置。如果您选择的是 SSL 认证方式,下面例子中的"PythonOption WebCert"字段中指定的证书必须既包含公钥包含私钥。也许您还希望将下面例子中最后一行更改为一个唯一的密码。

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/pki/koji/kojiweb.pem
PythonOption ClientCA /etc/pki/koji/koji_ca_cert.crt
PythonOption KojiHubCA /etc/pki/koji/koji_ca_cert.crt

PythonOption LoginTimeout 72
PythonOption Secret CHANGE_ME

可选的配置

您还需要编辑文件 /etc/httpd/conf.d/kojiweb.conf,根据最开始时您选择的认证机制正确配置其中的认证项。


/etc/httpd/conf.d/kojiweb.conf: 如果您选择的是 Kerberos 认证方式,下面的这些项必须设置成有效值,并且与其他的配置项联合使用。

<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>
RHEL 5 系统中的 mod_python 模块不支持非基本认证方式,所以目前 EPEL 5 的 Koji-web中,Kerberos 认证机制不能正常工作。参见 BZ #682319

/etc/httpd/conf.d/kojiweb.conf: 如果您选择的是 SSL 认证方式,下面的这些项必须设置成有效值,并且与其他的配置项联合使用。

<Location /koji/login>
SSLOptions +StdEnvVars
</Location>

/etc/httpd/conf.d/ssl.conf: 如果您选择的是 SSL 认证方式,您需要为 apache 添加必需的 SSL 选项。

SSLVerifyClient require
SSLVerifyDepth  10

网站可以工作了

现在您可以在您的浏览器中输入 kojiweb 的地址,您会看到系统的 web 页面。当然,现在您只可以浏览系统中的数据。如果您已经设置好了证书,就可以登录系统了。

Koji 守护进程 - 编译机

Kojid 是运行在每一台编译机上的编译守护进程。它的主要任务是查询发送过来的编译请求,根据实际情况进行处理。除了编译软件包 Koji 还支持其他的任务,比如制作 livecd 镜像文件或者原始磁盘镜像文件,这些任务也由 kojid 进行处理。kojid 利用 mock 创建原始的编译环境,并且为每一次编译任务单独创建一个编译环境, 确保编译过程不会受到其他编译过程的干扰。kojid 是用 Python 编写的,并且通过 XML-RPC 与 koji-hub 进行通信。

配置文件

  • /etc/kojid/kojid.conf - Kojid 守护进程配置文件
  • /etc/sysconfig/kojid - Kojid 守护进程开关

安装 kojid:

root@localhost$ yum install koji-builder

必须的配置

/etc/kojid/kojid.conf: 您需要编辑每个编译机上的这个配置文件,server项需要指向 koji hub 的 URL,user 项是您在添加编译机时为编译机指定的名称。

; 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

您可以修改下面这个配置项的路径,但是不能够与 kojihub.conf 文件中配置的 KojiDir 相同(可以是 KojiDir 中的子目录,只要不和 KojiDir 相同就行了)

; The directory root for temporary storage
workdir=/tmp/koji

可选的配置 (SSL 证书)

/etc/kojid/kojid.conf: 如果您选择的是 SSL 认证方式,您需要修改下面这些配置项的值,使之指向系统开始搭建时您创建的证书的存放位置。

;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/koji_ca_cert.crt

;certificate of the CA that issued the HTTP server certificate
serverca = /etc/kojid/koji_ca_cert.crt

值得注意的一点是如果您的编译机和安装 koji hub 和 koji web 的服务器不是一台机器,您需要将上面配置文件中提到的证书从服务器的 /etc/kojid/ 目录中拷贝到编译机的 /etc/koji/ 目录中,这样编译机才可以进行认证。

可选的配置 (Kerberos 认证)

/etc/kojid/kojid.conf: 如果您选择的是 Kerberos 认证方式,下面的这些项必须设置成有效值,并且与其他的配置项联合使用。

; the username has to be the same as what you used with add-host
;user =

host_principal_format=compile/%s@EXAMPLE.COM

默认情况下它将寻找 /etc/kojid/kojid.keytab 文件中的 Kerberos keytab。

注意: Kojid 不会试图向 koji-hub 进行 kerberos 认证,除非 username 项被注释掉了

将代表 koji 编译机的主机条目添加到数据库中

现在您需要将编译机的信息添加到数据库中,这样 koji hub 就可以使用编译机了。确保这些工作在您第一次开启 kojid 守护进程之前完成,否则为了使系统正常工作,您不得不手动删除数据库中 sessions 和 users 表中的记录。

kojiadmin@localhost$ koji add-host kojibuilder1.example.com i386 x86_64

add-host 命令后面第一个参数应该是编译机的主机名,第二个参数用来指定编译机支持的系统架构类型。

将主机添加到 createrepo 频道中

频道是用来控制哪台编译机可以执行哪种类型任务的一种方法。默认情况下,编译机被加入到 default 频道中。至少还需要将部分编译机添加到 createrepo 频道,这样就有编译机来执行 kojira 提交的 repo creation 任务了。

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

关于负载能力的一点说明

添加到数据库的 host 表中的编译机的默认负载能力是 2。这意味着如果一台编译机的平均负载超过了 2,编译机上的 kojid 守护进程将不再接收新的任务。这和配置文件中的最大任务数是两个不同的控制量。kojid 在接收一个任务之前需要先检查系统负载和待执行的任务数量, 确保平均负载没有超过编译机的平均负载能力,并且kojid已经接收等待执行的任务数量小于最大任务数。然而,在四核甚至更多核 CPU 广泛使用的今天,将平均负载设定为 2 不能充分发挥硬件的性能。因为命令行工具没有提供一个方法来修改编译机的负载能力,必须通过手动修改数据库中的数据来实现。

koji@localhost$ psql koji
koji=# select (id, name, capacity) from host;
              row               
--------------------------------
 (1,kojibuilder1.example.com,2)
 (2,kojibuilder2.example.com,2)
(2 rows)

koji=# update host set capacity = 16 where id = 1;
UPDATE 1
koji=# 

开启 Kojid

一旦将编译机的信息添加到了数据库中,您必须开启编译机中的 kojid 守护进程。

root@localhost$ /sbin/service kojid start

请检查日志文件 /var/log/kojid.log 确保 kojid 已经成功开启。如果日志文件没有显示任何错误信息,编译机就已经配置好了,可以开始工作了。您可以在浏览器中输入系统的网址,点击 hosts 标签,这个页面会显示数据库中编译机的列表以及每台编译机的状态信息。

Kojira - 创建和维护 Yum 库

配置文件:

  • /etc/kojira/kojira.conf - Kojira 守护进程配置文件
  • /etc/sysconfig/kojira - Kojira 守护进程开关

安装 kojira

root@localhost$ yum install koji-utils

必须的配置

/etc/kojira/kojira.conf: 这个配置选项需要指向您的 koji-hub 地址

; The URL for the xmlrpc server
server=http://hub.example.com/kojihub


附加说明:

  • Kojira 需要对目录 /mnt/koji 具有读写权限。
  • 任何时候只允许同时运行一个 kojira 的实例。
  • 最好不要在编译机上运行 kojira ,因为编译机只需要具有目录 /mnt/koji 的只读权限就可以了。

可选的配置

/etc/kojira/kojira.conf: 如果您选择的是 SSL 认证方式,下面这些项必须设置成有效值。

;client certificate
; This should reference the kojira certificate we created above
cert = /etc/pki/koji/kojira.pem

;certificate of the CA that issued the client certificate
ca = /etc/pki/koji/koji_ca_cert.crt

;certificate of the CA that issued the HTTP server certificate
serverca = /etc/pki/koji/koji_ca_cert.crt

如果您选择的是 Kerberos 认证方式,下面这些项必须设置成有效值。

; For Kerberos authentication
; the principal to connect with
principal=koji/kojira@EXAMPLE.COM
; The location of the keytab for the principal above
keytab=/etc/kojira.keytab

/etc/sysconfig/kojira: 本地用户 kojira 需要对目录 /mnt/koji/repos/ 具有读写权限。如果该目录所在的磁盘分区是 root-squashed 或者 root 用户没有修改权限,您可以将 RUNAS= 设置成一个对该目录有读写权限的用户。

在数据库中为 kojira 用户添加用户条目

如果您还没有添加 kojira 用户,请现在添加,并且赋予它 repo 权限。

kojiadmin@localhost$ koji add-user kojira
kojiadmin@localhost$ koji grant-permission repo kojira

开启 Kojira

root@localhost$ /sbin/service kojira start

请检查文件/var/log/kojira/kojira.log 确保 kojira 已经成功启动了。

配置 Koji 编译环境

如果您想导入软件包,配置好 Koji 系统,以便在系统中编译RPM包,参见 服务器配置

如果您想使用外部库 ,配置好 Koji 系统,以便在系统中编译RPM包,参见 外部库配置

这里有一些搭建 Koji 系统时有用的脚本和配置文件。

细节和杂项

如果您需要查看 koji 使用过程中的更多细节和注意事项,请阅读 Koji 杂项