From 7af90790a1c97f04349a7f571c0f93a8101e7b61 Mon Sep 17 00:00:00 2001 From: Mike McLean Date: Apr 04 2019 21:07:02 +0000 Subject: PR#1242: kojid.conf documentation Merges #1242 https://pagure.io/koji/pull-request/1242 Fixes: #1241 https://pagure.io/koji/issue/1241 Document kojid options --- diff --git a/docs/source/index.rst b/docs/source/index.rst index 71439cf..0d1cf6d 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -32,6 +32,7 @@ Contents runs_here server_bootstrap server_howto + kojid_conf using_the_koji_build_system profiles plugins @@ -40,6 +41,7 @@ Contents writing_koji_code content_generators content_generator_metadata + configuring_jenkins HowTos ====== diff --git a/docs/source/kojid_conf.rst b/docs/source/kojid_conf.rst new file mode 100644 index 0000000..fd5aa6f --- /dev/null +++ b/docs/source/kojid_conf.rst @@ -0,0 +1,290 @@ +kojid.conf Options +------------------ +kojid.conf is standard .ini-like configuration file. Its main section is +called ``[kojid]`` and contains following options. They are split by function +to section but can occur anywhere in ``[kojid]`` section in config file. + +General +^^^^^^^ +.. glossary:: + chroot_tmpdir=/chroot_tmpdir + The temporary directory in buildroot. It is advised to not use ``/tmp`` + as it is bound in mock and its content would change in random moments + during the build process. + + keepalive=True + noop - it is still allowed in config file for backward compatibility. + + log_level=None + Set logging level to one of the standard level names in Python's logging + module. Valid values are: CRITICAL, ERROR, WARNING, INFO, and DEBUG. + The default log level is WARNING. + + maxjobs=10 + The maximum number of jobs that kojid will handle at a time. This + serves as a backup to the capacity check and prevents a tremendous + number of low weight jobs from piling up. + + max_retries=120 + Set the maximum number of times that an individual hub call can be + retried. + + minspace=8192 + The minimum amount of free space (in MBs) required for each build root. + If this amount of space is not available, no new jobs will be taken. + + no_ssl_verify=False + Turn off SSL verification for https calls. It is strongly advised to + not turn off this verification. + + offline_retry=True + The hub returns a special error code when it is placed in offline + mode or when the database is unavailable. This setting controls + whether calls should be retried in these cases. + + offline_retry_interval=120 + Controls the wait time for retrying hub calls when the hub reports + as offline. Such calls are only retried if the offline_retry setting + is set to True. The value is in seconds. + + pkgurl=None + Obsoleted, use ``topurl`` instead. + + plugin='' + plugins='' + Space-separated list of builder plugins which should be enabled. By + default no plugins are used. For list of available plugins check + :doc:`this page `. Both spellings plugin/plugins are allowed + in config, but don't mix them as order is not binding. + + pluginpath=/usr/lib/koji-builder-plugins + Colon-separated list of directories to check for builder plugins. + They are not used by default, use ``plugins`` to enable them. + + retry_interval=60 + If there is an unsuccessful call to hub, this is how many seconds to + wait before trying new call. + + server=http://hub.example.com/kojihub + The URL for the koji xmlrpc server. + + sleeptime=15 + The number of seconds to sleep between checking for new tasks. + + topurl=http://hub.example.com/kojifiles + The URL where the main Koji volume can be accessed. The builder uses + this url for most file access. + + topdir=/mnt/koji + The location where the main Koji volume is mounted. This mount is + mainly used during createrepo tasks, and should be read-only. + + use_fast_upload=True + Enables faster uploading (bypassing XMLRPC overhead). Changing it makes + sense only in weird combination of very old hub and newer builders. + + workdir=/tmp/koji + The directory root for temporary storage on builder. + +Building +^^^^^^^^ +.. glossary:: + allowed_scms=scm.example.com:/cvs/example git.example.org:/example svn.example.org:/users/\*:no + Controls which source control systems the builder will accept. It is a + space-separated list of entries in one of the following forms: + + .. code:: + + hostname:path[:use_common[:source_cmd]] + !hostname:path + + + Incorrectly-formatted tuples will be ignored. + + If ``use_common`` is not present, kojid will attempt to checkout a ``common/`` + directory from the repository. If ``use_common`` is set to ``no``, ``off``, ``false``, or ``0``, + it will not attempt to checkout a ``common/`` directory. + + ``source_cmd`` is a shell command (args separated with commas instead of spaces) + to run before building the srpm. It is generally used to retrieve source + files from a remote location. If no ``source_cmd`` is specified, ``make sources`` + is run by default. + + The second form (``!hostname:path``) is used to explicitly block a host:path + pattern. In particular, it provides the option to block specific subtrees of + a host, but allow from it otherwise. This explicit block syntax was added in + version 1.13.0. + + + build_arch_can_fail=False + If set to ``True``, failing subtask will not automatically cancel other siblings. + + createrepo_skip_stat=True + If set to ``True``, append ``--skip-stat`` to all createrepo commands. + + createrepo_update=True + Recycle old repodata (if they exist) in createrepo. + + failed_buildroot_lifetime=14400 + Failed tasks leave buildroot content on disk for debugging purposes. + They are removed after 4 hours by default. This value is specified + in seconds. + + literal_task_arches='' + Space-separated list of globs (``fnmatch``) for architectures which + will not be converted to canonical archs when choosing builder. + + log_timestamps=False + If set to ``True`` additional logs with timestamps will get created and + uploaded to hub. It could be useful for debugging purposes, but creates + twice as many log files. + + maven_repo_ignore='\*.md5 \*.sha1 maven-metadata\*.xml _maven.repositories resolver-status.properties \*.lastUpdated' + Space-separated globs of repo files which should be ignored when + gathering maven result artifacts. + + oz_install_timeout=7200 + Install timeout in seconds for image build. Default value is 0, which + means using the number in ``/etc/oz/oz.cfg``. Supported since oz-0.16.0. + + use_createrepo_c=False + Use ``createrepo_c`` rather than ``createrepo`` command. There is + generally no reason to not use createrepo_c in modern depolyments. It + is disabled by default only to be backward-compatible. This default + would change in future. + + task_avail_delay=300 + [Added in 1.17.0] + + This delay works around a deficiency in task scheduling. The default + delay is 300 seconds. It is unlikely that admins will need to adjust + this setting. + + Despite the name, this does not introduce any new delay compared to the + old behavior. The setting controls how long a host will wait before + taking a task in a given channel-arch “bin” when that host has an + available capacity lower than the median for that bin. Previously, such + hosts could wait forever. + + timeout=None + This value is used for waiting on all xmlrpc calls to hub. By default + there is no timeout set. + +RPM Builds +^^^^^^^^^^ +.. glossary:: + distribution=Koji + The distribution to use in rpm headers. Value is propagated via macros + to rpmbuild. + + packager=Koji + The packager to use in rpm headers. Value is propagated via macros to + rpmbuild. + + support_rpm_source_layout=True + Originally, when building an SRPM from source control, Koji expected + the contents to be flattened (e.g. the spec and sources files directly + in the checkout directory). When this option is enabled (the default), + Koji will also accept these contents in separate ``SPECS`` and + ``SOURCES`` directories. + + vendor=Koji + The vendor to use in rpm headers. Value is propagated via macros to + rpmbuild. + +Mock +^^^^ +.. glossary:: + mockdir=/var/lib/mock + The directory root for mock. + + mockhost=koji-linux-gnu + The _host string to use in mock. + + mockuser=kojibuilder + The user to run as when performing builds. Note, that user must exist on + the build host and must have permission to use mock. + + rpmbuild_timeout=86400 + Timeout for build duration (24 hours). Propagated to mock, not + controlled by koji directly. + + yum_proxy=None + Address of proxy server which will be passed via mock to yum. + +Notifications +^^^^^^^^^^^^^ +.. glossary:: + admin_emails='' + Space-separated list of addresses for sending logs. + + from_addr=Koji Build System + The From address used when sending email notifications. + + smtphost=example.com + The mail host to use for sending email notifications. + +Kerberos Authentication +^^^^^^^^^^^^^^^^^^^^^^^ +.. glossary:: + ccache=/var/tmp/kojid.ccache + Credentials cache used for krbV login. + + host_principal_format=compile/\%s\@EXAMPLE.COM + The format of the principal used by the build hosts. + The %s will be replaced by the FQDN of the host. + + keytab=/etc/kojid/kojid.keytab + Location of the keytab. + + krb_canon_host=False + Kerberos authentication requires correct hostnames. If this option is + specified, dns is used to get the correct hostname for the + server (i.e. resolve any CNAMEs). Note, this option will not function + unless ``python-dns`` is installed. + The ``krb_rdns`` option takes a different approach. + + krb_principal=None + Explicit principal used for login. If it is not specified, it is + created via ``host_principal_format``. + + krb_rdns=True + Kerberos authentication needs correct hostname. If this option is + specified, ``socket.getfqdn(host)`` is used to determine reverse DNS + records. Otherwise, ``host`` is used directly. Playing with this option + can help you in some firewalled setups. ``krb_canon_host`` takes + precedence over this option and takes a different approach. + + krbservice=host + The service name of the principal being used by the hub. + + +SSL Authentication +^^^^^^^^^^^^^^^^^^ +.. glossary:: + ca='' + noop, obsoleted, will be removed soon. + + cert=/etc/kojid/client.crt + Client certificate. + + serverca=/etc/kojid/serverca.crt + This specifies the CA (or CA bundle) that the builder should use to + verify the ssl connection to the hub. If the default value of + ``/etc/kojid/serverca.crt`` exists, then that file is used. + Otherwise the default system bundle is used. + + +Insecure Authentication Options +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +These options are only intended for simple development environments +and should never be used in production. +Please use Kerberos or SSL authentication instead. + +.. glossary:: + user=None + Username for authentication + + password=None + Clear-text password (I've told you.) diff --git a/docs/source/server_howto.rst b/docs/source/server_howto.rst index 6d8a4b8..854ccbc 100644 --- a/docs/source/server_howto.rst +++ b/docs/source/server_howto.rst @@ -949,6 +949,8 @@ Configuration Files * ``/etc/kojid/kojid.conf`` - Koji Daemon Configuration * ``/etc/sysconfig/kojid`` - Koji Daemon Switches +All options for `kojid.conf` are described :doc:`here `. + Install kojid -------------