cobbler · SchoolGuy · Feb 23, 2024 · Feb 19, 2024 · Feb 19, 2024 · Feb 23, 2024
diff --git a/changelog.d/3612.fixed b/changelog.d/3612.fixed
@@ -0,0 +1 @@
+Settings: Clarify leftover settings and group them according to their respective topics
diff --git a/config/cobbler/settings.yaml b/config/cobbler/settings.yaml
@@ -30,9 +30,8 @@ allow_dynamic_settings: false
 # ok with this limitation.
 anamon_enabled: false
 
-# If using "authn_pam" in the "modules.conf", this can be configured to change the PAM service authentication will be
-# tested against.
-# The default value is "login".
+# If the key "module" in the file "/etc/cobbler/modules.conf" in the section "authentication" is set to the value
+# "authentication.pam", this setting chooses the PAM authentication stack used.
 authn_pam_service: "login"
 
 # How long the authentication token is valid for, in seconds.
@@ -218,6 +217,9 @@ default_virt_ram: 512
 # (NOTE: this does not change what virt_type is chosen by import)
 default_virt_type: xenpv
 
+# The virtualization disk format
+default_virt_disk_driver: "raw"
+
 # enable iPXE booting? Enabling this option will cause Cobbler
 # to copy the undionly.kpxe file to the tftp root directory,
 # and if a profile/system is configured to boot via iPXE it will
@@ -295,24 +297,24 @@ puppetca_path: "/usr/bin/puppet"
 remove_old_puppet_certs_automatically: false
 
 # choose a --server argument when running puppetd/puppet agent during autoinstall
-#puppet_server: 'puppet'
+puppet_server: ""
 
 # let Cobbler know that you're using a newer version of puppet
 # choose version 3 to use: 'puppet agent'; version 2 uses status quo: 'puppetd'
-#puppet_version: 2
+puppet_version: 2
 
 # choose whether to enable puppet parameterized classes or not.
 # puppet versions prior to 2.6.5 do not support parameters
 puppet_parameterized_classes: true
 
 # set to true to enable Cobbler's DHCP management features.
-# the choice of DHCP management engine is in /etc/cobbler/modules.conf
+# Use the "module" key in "/etc/cobbler/modules.conf" in the "dhcp" section to configure DHCP management engine
 # See the docs (https://cobbler.readthedocs.io/en/latest/user-guide.html#dhcp-management) for more info
 manage_dhcp: false
 
 # set to true to enable DHCP IPv6 address configuration generation.
 # This currently only works with manager.isc DHCP module (isc dhcpd6 daemon)
-# See /etc/cobbler/modules.conf whether this isc module is chosen for dhcp
+# See "module" key in "/etc/cobbler/modules.conf" in the "dhcp" section whether this isc module is chosen for dhcp
 # generation.
 manage_dhcp_v6: false
 
@@ -330,9 +332,9 @@ next_server_v4: 127.0.0.1
 # Set the cobbler IPv6 address here so that PXE booting guests can find it
 next_server_v6: "::1"
 
-# set to true to enable Cobbler's DNS management features.
-# the choice of DNS management engine is in /etc/cobbler/modules.conf
-# needs manage_forward_zones and manage_reverse_zones to be set, too.
+# Set this key to true to enable Cobbler's DNS management features.
+# Use the key "module" in the file "/etc/cobbler/modules.conf" under the section "dns" to control which DNS management
+# engine is utilized. Needs "manage_forward_zones" and "manage_reverse_zones" to be set as well.
 manage_dns: false
 
 # set to path of bind chroot to create bind-chroot compatible bind
@@ -346,26 +348,29 @@ bind_zonefile_path: "@@bind_zonefiles@@"
 # bind configuration files
 bind_master: 127.0.0.1
 
-# if using BIND (named) for DNS management in /etc/cobbler/modules.conf
-# and manage_dns is enabled (above), this lists which zones are managed
-# See the docs (https://cobbler.readthedocs.io/en/latest/user-guide.html#dns-configuration-management) for more info
+# If you use BIND (named) for DNS management and manage_dns is enabled (above), this lists managed zones.
+# See https://cobbler.rtfd.io/en/latest/user-guide/dns-management.html for more info.
 manage_forward_zones: []
 manage_reverse_zones: []
 
 # set to true to enable Cobbler's TFTP management features.
-# the choice of TFTP management engine is in /etc/cobbler/modules.conf
+# Use the key "module" in the file "/etc/cobbler/modules.conf" under the section "tftpd" to choose of TFTP management
+# engine which is utilized.
 manage_tftpd: true
 
 # This variable contains the location of the tftpboot directory. If this directory is not present Cobbler does not
 # start.
 # Default: @@tftproot@@
 tftpboot_location: "@@tftproot@@"
 
+# The location where Cobbler searches for GRUB configuration files
+grubconfig_dir: "/var/lib/cobbler/grub_config"
+
 # set to true to enable Cobbler's RSYNC management features.
 manage_rsync: false
 
 # settings for power management features.  optional.
-# see https://github.com/cobbler/cobbler/wiki/Power-management to learn more
+# see https://cobbler.rtfd.io/en/latest/user-guide/power-management.html to learn more
 # choices (refer to codes.py):
 #    apc_snmp bladecenter bullpap drac ether_wake ilo integrity
 #    ipmilan ipmilanplus lpar rsa virsh wti
@@ -388,17 +393,14 @@ nopxe_with_triggers: true
 # authentication within Cobbler Web and Cobbler XMLRPC.
 redhat_management_server: "xmlrpc.rhn.redhat.com"
 
-# if using authn_spacewalk in modules.conf to let Cobbler authenticate
-# against Satellite/Spacewalk's auth system, by default it will not allow per user
-# access into Cobbler Web and Cobbler XMLRPC.
-# in order to permit this, the following setting must be enabled HOWEVER
-# doing so will permit all Spacewalk/Satellite users of certain types to edit all
-# of Cobbler's configuration.
-# these roles are:  config_admin and org_admin
-# users should turn this on only if they want this behavior and
-# do not have a cross-multi-org seperation concern.  If you have
-# a single org in your satellite, it's probably safe to turn this
-# on and then you can use CobblerWeb alongside a Satellite install.
+# If the key "module" in the file "/etc/cobbler/modules.conf" under the section "authentication" is set to the value
+# "authentication.spacewalk" Satellite/Spacewalk's auth system is used. Cobbler does not allow user-based access into
+# Cobbler Web and Cobbler XMLRPC by default.
+# Enable the following setting to permit user-based access to Cobbler's API. Note that doing so permits all
+# Spacewalk/Satellite users with the "config_admin" and "org_admin" roles to edit Cobbler's configuration.
+# Users should turn this on only if they want this behavior and do not have a cross-multi-org seperation concern. If
+# you have a single org in your satellite, it's probably safe to turn this on and then you can use CobblerWeb alongside
+# a Satellite install.
 redhat_management_permissive: false
 
 # specify the default Red Hat authorization key to use to register
@@ -527,6 +529,9 @@ yumdownloader_flags: "--resolve"
 # sort and indent JSON output to make it more human-readable
 serializer_pretty_json: false
 
+# Used for replicating the Cobbler instance
+cobbler_master: ""
+
 # replication rsync options for distros, autoinstalls, snippets set to override default value of "-avzH"
 replicate_rsync_options: "-avzH"
 
@@ -555,16 +560,11 @@ jinja2_includedir: "/var/lib/cobbler/jinja2"
 # This behavior was now made conditional, with default being "off".
 convert_server_to_ip: false
 
-# Leftover settings
+# Used for caching the intermediate files for ISO-Building
 buildisodir: "/var/cache/cobbler/buildiso"
-cobbler_master: ""
-default_virt_disk_driver: "raw"
-grubconfig_dir: "/var/lib/cobbler/grub_config"
-iso_template_dir: "/etc/cobbler/iso"
 
-# Puppet
-puppet_server: ""
-puppet_version: 2
+# Folder to search for the ISO templates. These will build the boot-menu of the built ISO.
+iso_template_dir: "/etc/cobbler/iso"
 
 # Signatures
 signature_path: "/var/lib/cobbler/distro_signatures.json"

diff --git a/docs/cobbler-conf.rst b/docs/cobbler-conf.rst
@@ -233,7 +233,10 @@ default: ``"/etc/cobbler/boot_loader_conf"``
 bootloaders_dir
 ===============
 
-TODO
+A directory that "cobbler mkloaders" copies the built bootloaders into. "cobbler sync" searches for
+bootloaders in this directory.
+
+default: ``/var/lib/cobbler/loaders``
 
 bootloaders_shim_folder
 =======================
@@ -264,21 +267,52 @@ default: Depending on your distro. See values below.
 grub2_mod_dir
 =============
 
-TODO
+The directory where Cobbler looks for GRUB modules that are required for "cobbler mkloaders".
+
+default: Depends on your distribution. See values below.
+
+* (open)SUSE: ``"/usr/share/grub2"``
+* Debian/Ubuntu: ``"/usr/lib/grub"``
+* CentOS/Fedora: ``"/usr/lib/grub"``
 
 syslinux_dir
 ============
 
-TODO
+The directory where Cobbler looks for syslinux modules that are required for "cobbler mkloaders".
+
+default: Depends on your distribution. See values below.
+
+* (open)SUSE: ``"/usr/share/syslinux"``
+* Debian/Ubuntu: ``"/usr/lib/syslinux/modules/bios/"``
+* CentOS/Fedora: ``"/usr/share/syslinux"``
 
 bootloaders_modules
 ===================
 
-TODO
+A list of all modules "cobbler mkloaders" includes when building grub loaders.
+Typically, a grub loader uses the modules for PXE or HTTP Boot.
+
+default: Omited for readablity, please refer to the `settings.yaml` file in our GitHub repository.
 
 bootloaders_formats
 ===================
 
+This is a mapping that has the following structure:
+
+.. code:: yaml
+
+   <loader name>:
+      binary_name: filename
+      extra_modules:
+        - extra-module
+      mod_dir: <different folder name then loader name>
+      use_secure_boot_grub: True
+
+The keys ``extra_modules``, ``mod_dir`` and ``use_secure_boot_grub`` are optional. Under normal circumstances this
+setting does not need adjustments.
+
+default: Omited for readablity, please refer to the `settings.yaml` file in our GitHub repository.
+
 grubconfig_dir
 ==============
 
@@ -293,7 +327,7 @@ Email out a report when Cobbler finishes installing a system.
 
 - enabled: Set to ``true`` to turn this feature on
 - email: Which addresses to email
-- ignorelist: TODO
+- ignorelist: A list of prefixes that defines mail topics that should not be sent.
 - sender: Optional
 - smtp_server: Used to specify another server for an MTA.
 - subject: Use the default subject unless overridden.

diff --git a/docs/user-guide.rst b/docs/user-guide.rst
@@ -5,6 +5,8 @@ User Guide
 .. toctree::
    :maxdepth: 2
 
+   DHCP Management <user-guide/dhcp-management>
+   DNS Management <user-guide/dns-management>
    Configuration Management Integrations <user-guide/configuration-management-integrations>
    Windows installation with Cobbler <user-guide/wingen>
    Extending Cobbler <user-guide/extending-cobbler>
@@ -227,64 +229,6 @@ Cobbler can build all of it's profiles into a bootable CD image using the ``cobb
 PXE-menu like bring up of bare metal in environments where PXE is not possible. Another more advanced method is described
 in the Koan manpage, though this method is easier and sufficient for most applications.
 
-.. _dhcp-management:
-
-DHCP Management
-===============
-
-Cobbler can optionally help you manage DHCP server. This feature is off by default.
-
-Choose either ``management = isc_and_bind`` in ``/etc/cobbler/dhcp.template`` or ``management = "dnsmasq"`` in
-``/etc/cobbler/modules.conf``.  Then set ``manage_dhcp=1`` in ``/etc/cobbler/settings.yaml``.
-
-This allows DHCP to be managed via "cobbler system add" commands, when you specify the mac address and IP address for
-systems you add into Cobbler.
-
-Depending on your choice, Cobbler will use ``/etc/cobbler/dhcpd.template`` or ``/etc/cobbler/dnsmasq.template`` as a
-starting point. This file must be user edited for the user's particular networking environment. Read the file and
-understand how the particular app (ISC dhcpd or dnsmasq) work before proceeding.
-
-If you already have DHCP configuration data that you would like to preserve (say DHCP was manually configured earlier),
-insert the relevant portions of it into the template file, as running ``cobbler sync`` will overwrite your previous
-configuration.
-
-By default, the DHCP configuration file will be updated each time ``cobbler sync`` is run, and not until then, so it is
-important to remember to use ``cobbler sync`` when using this feature.
-
-If omapi_enabled is set to 1 in ``/etc/cobbler/settings.yaml``, the need to sync when adding new system records can be
-eliminated. However, the OMAPI feature is experimental and is not recommended for most users.
-
-.. _dns-management:
-
-DNS configuration management
-============================
-
-Cobbler can optionally manage DNS configuration using BIND and dnsmasq.
-
-Choose either ``module = managers.bind`` or ``module = managers.dnsmasq`` in ``/etc/cobbler/modules.conf`` and then
-enable ``manage_dns`` in ``/etc/cobbler/settings.yaml``.
-
-You may also choose ``module = managers.ndjbdns`` as a management engine for DNS. For this the DNS server tools of
-D.J. Bernstein need to be installed. For more information please refer to `<https://cr.yp.to/djbdns.html>`_
-
-This feature is off by default. If using BIND, you must define the zones to be managed with the options
-``manage_forward_zones`` and ``manage_reverse_zones``.
-
-If using BIND, Cobbler will use ``/etc/cobbler/named.template`` and ``/etc/cobbler/zone.template`` as a starting point
-for the ``named.conf`` and individual zone files, respectively. You may drop zone-specific template files in
-``/etc/cobbler/zone_templates/name-of-zone`` which will override the default. These files must be user edited for the
-user's particular networking environment. Read the file and understand how BIND works before proceeding.
-
-If using dnsmasq, the template is ``/etc/cobbler/dnsmasq.template``. Read this file and understand how dnsmasq works
-before proceeding.
-
-If using ndjbdns, the template is ``/etc/cobbler/ndjbdns.template``. Read the file and understand how ndjbdns works
-before proceeding.
-
-All managed files (whether zone files and ``named.conf`` for BIND, or ``dnsmasq.conf`` for dnsmasq) will be updated each
-time ``cobbler sync`` is run, and not until then, so it is important to remember to use ``cobbler sync`` when using this
-feature.
-
 Containerization
 ################
 

diff --git a/docs/user-guide/dhcp-management.rst b/docs/user-guide/dhcp-management.rst
@@ -0,0 +1,63 @@
+.. _dhcp-management:
+
+***************
+DHCP Management
+***************
+
+Cobbler can optionally help you manage a DHCP server. This feature is disabled by default.
+
+The following options are available for ``modules.dhcp.module``:
+
+* ``"managers.isc"``
+* ``"managers.dnsmasq"``
+
+Set ``manage_dhcp: true`` and ``manage_dhcp_v4`` or ``manage_dhcp_v6`` to ``true`` for this setting to take effect.
+
+This allows DHCP to be managed via "cobbler system add" commands, when you specify the MAC address and IP address for
+systems you add into Cobbler.
+
+You must configure the templates for your networking environment. Read the file and understand how
+the particular app works before proceeding.
+
+If you already have DHCP configuration data that you would like to preserve (such as DHCP that was manually configured earlier),
+insert the relevant portions of it into the template file, as running ``cobbler sync`` will overwrite your previous
+configuration.
+
+By default, Cobbler updates the DHCP configuration file each time you run ``cobbler sync``.
+Remember to use ``cobbler sync`` when you use this feature.
+
+``isc`` DHCP
+########
+
+Helpful links:
+
+* Website: https://www.isc.org/dhcp/
+* Documentation: https://kb.isc.org/docs/aa-00333
+
+Templates used during generation:
+
+* ``/etc/cobbler/dhcp.template``
+* ``/etc/cobbler/dhcp6.template``
+
+``dnsmasq`` DHCP
+############
+
+Helpful links:
+
+* Website: https://thekelleys.org.uk/dnsmasq/doc.html
+* Documentation: https://thekelleys.org.uk/dnsmasq/docs/dnsmasq-man.html
+
+Templates used during generation:
+
+* ``/etc/cobbler/dnsmasq.template``
+
+``Kea`` DHCP
+########
+
+Support for Kea is a not yet implemented feature request: https://github.com/cobbler/cobbler/issues/3609
+
+Helpful links:
+
+* Website https://www.isc.org/kea/
+* Migration tool from isc: https://www.isc.org/dhcp_migration/
+* Documentation: https://kea.readthedocs.io/en/latest/index.html
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Settings: Clarify leftover settings and group them according to their respective topics