docs: mock's configuration

Related: https://pagure.io/koji/issue/4019

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.

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

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
+      <hub_resource_limits>`. 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
+      <rlimits_kojid>`.
+
 Notifications
 ^^^^^^^^^^^^^
 .. glossary::

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
+     <kojid_conf>` via ``mock_bootstrap_image = True``.
+
+   - ``nspawn_args`` - for old chroot, :ref:`RLIMIT_* <rlimits_kojid>` 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/

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 <kojid_conf>`.
 
+Mock-tuning options are described :doc:`here <mock_config>`.
+
 Install kojid
 -------------
 

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
+  <rlimits_kojid>`.
+
 * ``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:
   <https://github.com/rpm-software-management/mock/wiki/Feature-bootstrap>`_.
   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
   <https://github.com/rpm-software-management/mock/wiki/Feature-container-for-bootstrap>`_
@@ -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
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^