diff --git a/docs/source/hub_conf.rst b/docs/source/hub_conf.rst index d8c13bff..0edb0990 100644 --- a/docs/source/hub_conf.rst +++ b/docs/source/hub_conf.rst @@ -233,6 +233,8 @@ Notification options For more on notifications in Koji, see :ref:`notification-basics` +.. _hub_resource_limits: + Resource limits ^^^^^^^^^^^^^^^ If configured, the following resource limits are applied by the hub at startup. diff --git a/docs/source/index.rst b/docs/source/index.rst index 1d7da3d9..b43ea86e 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -43,6 +43,7 @@ Contents database_howto kojid_conf hub_conf + mock_config using_the_koji_build_system setting_rpm_macros profiles diff --git a/docs/source/kojid_conf.rst b/docs/source/kojid_conf.rst index dbc67478..af7e046f 100644 --- a/docs/source/kojid_conf.rst +++ b/docs/source/kojid_conf.rst @@ -1,8 +1,10 @@ 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. + +``/etc/kojid/kojid.conf`` is standard .ini-like configuration file. Its main +section is called ``[kojid]`` and contains following options. They are split by +function to the following sections but can occur anywhere in ``[kojid]`` block +in config file. General ^^^^^^^ @@ -214,6 +216,23 @@ RPM Builds The vendor to use in rpm headers. Value is propagated via macros to rpmbuild. +.. _rlimits_kojid: + +General RLIMIT options +^^^^^^^^^^^^^^^^^^^^^^ +.. glossary:: + RLIMIT_* + Same resource limit options as in the :ref:`hub config + `. Note, then when ``mock.new_chroot`` is set, those + are not propagated to the chroot and must be set separately in + ``/etc/mock/site-defaults.cfg`` as e.g. ``config_opts['nspawn_args'] = + ['--rlimit=RLIMIT_NOFILE=16384:16384']``. Note, that in case both old/new + chroots are used, this must be set in ``kojid.conf`` and also in + ``site-defaults.cfg`` to retain consistent behaviour across the + buildroots. For other recommended ``site-defaults.cfg`` settings see + :doc:`mock`. + + Mock ^^^^ .. glossary:: @@ -234,6 +253,10 @@ Mock yum_proxy=None Address of proxy server which will be passed via mock to yum. + RLIMIT_* + These options affect mock's behaviour and are described :ref:`here + `. + Notifications ^^^^^^^^^^^^^ .. glossary:: diff --git a/docs/source/mock_config.rst b/docs/source/mock_config.rst new file mode 100644 index 00000000..87d371e1 --- /dev/null +++ b/docs/source/mock_config.rst @@ -0,0 +1,46 @@ +Interaction with Mock +--------------------- + +`Mock`_ is crucial component for building in Koji. Every build runs the mock to +prepare fresh isolated environment and builds rpm or other content in chroot +handled by Mock. + +For each buildroot (and thus every build) koji prepares configuration file for +mock to be used. Content of the file depends on some administrator's decisions +and can be tweaked by: + + * ``/etc/mock/site-defaults.cfg`` on builder. This file is always consulted by + mock, so it is strongly recommended not to use default configuration but + deploy this file with more strict settings. + Typical values which should be changed: + + - ``use_bootstrap = False`` - Bootstrap is a) not needed in most cases b) + slows down the build c) e.g. in combination with next option could lead to + unreproducible build. While this feature is pretty useful in some cases, + it should be turned off as default and could be selectively turned on for + specific buildroots per tag configuration. + + - ``use_bootstrap_image`` - As noted before, this is generally unsafe + option, especially if used with image tags which are expected to be moved + (e.g. "latest"). Note, that to use this option (even via tag's + configuration), you need to explicitly allow it in :doc:`kojid.conf + ` via ``mock_bootstrap_image = True``. + + - ``nspawn_args`` - for old chroot, :ref:`RLIMIT_* ` support + setting various RLIMIT values to the build process. In case of + nspawn-based chroot (``mock.new_chroot`` tag extra option) these are + handled by mock itself and must be set separately there. + + - ``macros`` - some rpm macros could be defined every time for every build + based on builder itself. Typical usecase is to limit usage of CPUs on + given builder by setting ``config_opts['macros']['%_smp_ncpus_max'] = 2``. + + - ``plugin_conf`` - Various plugins could be enabled and configured to be + available in build environment. Example is `rpmautospec`_ which allows + various ``%auto*`` macros in spec files. + + * Another selective variant of altering mock's behaviour is setting its + options per buildtag. This is more described in :ref:`tuning-mock-per-tag`. + +.. _Mock: https://github.com/rpm-software-management/mock/wiki +.. _rpmautospec: https://docs.pagure.org/fedora-infra.rpmautospec/ diff --git a/docs/source/server_howto.rst b/docs/source/server_howto.rst index f87a82fe..ea4205ef 100644 --- a/docs/source/server_howto.rst +++ b/docs/source/server_howto.rst @@ -1054,9 +1054,12 @@ Configuration Files * ``/etc/kojid/kojid.conf`` - Koji Daemon Configuration * ``/etc/sysconfig/kojid`` - Koji Daemon Switches +* ``/etc/mock/site-defaults.cfg`` - Mock's base configuration file All options for `kojid.conf` are described :doc:`here `. +Mock-tuning options are described :doc:`here `. + Install kojid ------------- diff --git a/docs/source/using_the_koji_build_system.rst b/docs/source/using_the_koji_build_system.rst index c3c3dbfb..603efccd 100644 --- a/docs/source/using_the_koji_build_system.rst +++ b/docs/source/using_the_koji_build_system.rst @@ -390,11 +390,17 @@ environment follows: * ``mock.package_manager`` - If this is set, it will override mock's default package manager. Typically used with ``yum`` or ``dnf`` values. + * ``mock.new_chroot`` - 0/1 value. If it is set, ``--new-chroot`` or - `--old-chroot` option is appended to any mock call. If it is not set, - mock's default behavior is used. + `--old-chroot` option is appended to any mock call. If it is not set, mock's + default behavior is used. Note, that in the case when new chroot (nspawn) is + used, some of the options in ``kojid.conf`` will not be propagated to chroot + env properly, typically ``RLIMIT_*``, see :ref:`kojid.conf's options + `. + * ``mock.releasever`` - When doing cross-compiles it may be necessary to explicitly set the ``releasever`` to be used. + * ``mock.use_bootstrap`` - 0/1 value. If it is set, ``--bootstrap-chroot`` is appended to the mock init call. This tells mock to build in two stages, using chroot rpm for creating the build chroot. If it is not set, mock's @@ -402,6 +408,7 @@ environment follows: `_. Note, that it is not turn on by default by koji, as it is often not needed and it consumes additional resources (larger buildroot, downloading more data). + * ``mock.bootstrap_image`` - set to name of image, which can builder's podman download (e.g. ``fedora:32``). See mock's `doc `_ @@ -470,6 +477,9 @@ do: koji edit-tag dnf-fedora-tag -x rpm.env.CC=clang +Note, that mock's behaviour is always impacted by builder's default values in +``/etc/mock/site-defaults.cfg``. Check :doc:`mock` for details. + Using Koji to control tasks ^^^^^^^^^^^^^^^^^^^^^^^^^^^