cobbler · SchoolGuy · Jan 31, 2022 · Jan 20, 2022 · Jan 20, 2022 · Jan 20, 2022
diff --git a/docs/cobbler.rst b/docs/cobbler.rst
@@ -4,7 +4,8 @@ Cobbler CLI
 
 This page contains a description for commands which can be used from the CLI.
 
-.. Go Client: https://github.com/jtopjian/cobblerclient
+.. note:: We are currently developing a new CLI which is independent from the server.
+          This document redirects you to the new documentation once the new CLI is ready.
 
 General Principles
 ##################
@@ -1035,6 +1036,8 @@ most of the other Cobbler commands (currently: distro, profile, system, repo, im
 
 Optional parameter which filters for object with the given name.
 
+.. _cobbler-cli-reposync:
+
 Cobbler reposync
 ================
 
@@ -1071,6 +1074,8 @@ The flags ``--tries=N`` (for example, ``--tries=3``) and ``--no-fail`` should li
 crontab. They ensure network glitches in one repo can be retried and also that a failure to synchronize one repo does
 not stop other repositories from being synchronized.
 
+.. _cli-cobbler-sync:
+
 Cobbler sync
 ============
 

diff --git a/docs/limitations.rst b/docs/limitations.rst
@@ -3,26 +3,39 @@ Limitations and Surprises
 *************************
 
 Templating
-==========
+##########
 
 Before templates are passed to Jinja or Cheetah there is a pre-processing of templates happening. During pre-processing
 Cobbler replaces variables like ``@@my_key@@`` in the template. Those keys are currently limited by the regex of ``\S``,
 which translates to ``[^ \t\n\r\f\v]``.
 
 Restarting the daemon
-=====================
+#####################
 
 Once you have a Cobbler distro imported or manually added you have to make sure the source for the Kernel & initrd is
 available all the time. Thus I highly recommend you to add the ISOs to your ``/etc/fstab`` to make them persistent
 across reboots. If you forget to remount them the Cobbler daemon won't start!
 
 Kernel options
-==============
+##############
 
 The user (so you) is responsible for generating the correct quoting of the Kernel Command Line. We manipulate the
 arguments you give us in a way that we add wrapping double quotes around them when the value contains a space.
 
 The Linux Kernel describes its quoting at:
 `The kernel’s command-line parameters <https://www.kernel.org/doc/html/v5.15/admin-guide/kernel-parameters.html#the-kernel-s-command-line-parameters>`_
 
-Please consult the documentation of your operating system for how it deals with this if it is not Linux.
+Consult the documentation of your operating system for how it deals with this if it is not Linux.
+
+Special Case: Uyuni/SUSE Manager
+################################
+
+.. note:: SUSE Manager is a flavor of Uyuni. The term Uyuni refers to both pieces of software in this context.
+
+Uyuni uses Cobbler for driving auto-installations. When using Cobbler in the context of Uyuni, you need to know that
+Cobbler is not seen as the source of truth by Uyuni. This means, in case you don't have any auto-installation
+configured in Uyuni, the content visible in Cobbler is deleted.
+
+Because of the same reason, during the runtime of Cobbler you may see systems popping on and off as the content of
+Cobbler is managed by Uyuni (in particular, the taskomatic task ``kickstart_cleanup`` executes cleanup on the Cobbler
+content)
diff --git a/docs/scripts.rst b/docs/scripts.rst
@@ -26,30 +26,6 @@ Author
 
 `Orion Poplawski <https://github.com/opoplawski>`_
 
-mkgrub.sh
-#########
-
-Description
-===========
-
-This script will try to generate UEFI bootable bootloaders for your Cobbler installation. The script was written for Bash
-but should be POSIX compliant. Be advised that only executing this script won't make your Cobbler installation UEFI
-ready.
-
-Execution examples
-==================
-
-.. code-block:: shell
-
-   export SYSLINUX_DIR=/usr/share/...;./mkgrub.sh
-   export $GRUB2_MOD_DIR=/usr/share/...;./mkgrub.sh
-   ./mkgrub.sh
-
-Author
-======
-
-`Thomas Renninger <https://github.com/watologo1>`_
-
 settings-migration-v1-to-v2.sh
 ##############################
 

diff --git a/docs/user-guide.rst b/docs/user-guide.rst
@@ -11,6 +11,9 @@ User Guide
    Terraform Provider for Cobbler <user-guide/terraform-provider>
    Building ISOs <user-guide/building-isos>
    GRUB and everything related <user-guide/grub>
+   Repository Management <user-guide/repository-management>
+   The TFTP Directory <user-guide/tftp>
+   Internal Database <user-guide/internal-database>
 
 
 API
@@ -64,145 +67,6 @@ Then, a machine is assigned to each profile.
     cobbler system add --name=AA:BB:CC:DD:EE:FE --profile=rhel4u3-dbservers
     cobbler report
 
-Repository Management
-#####################
-
-REPO MANAGEMENT
-===============
-
-This has already been covered a good bit in the command reference section.
-
-Yum repository management is an optional feature, and is not required to provision through Cobbler. However, if Cobbler
-is configured to mirror certain repositories, it can then be used to associate profiles with those repositories. Systems
-installed under those profiles will then be autoconfigured to use these repository mirrors in ``/etc/yum.repos.d``, and
-if supported (Fedora Core 6 and later) these repositories can be leveraged even within Anaconda.  This can be useful if
-(A) you have a large install base, (B) you want fast installation and upgrades for your systems, or (C) have some extra
-software not in a standard repository but want provisioned systems to know about that repository.
-
-Make sure there is plenty of space in Cobbler's webdir, which defaults to ``/var/www/cobbler``.
-
-.. code-block:: shell
-
-    cobbler reposync [-- [--tries=N] [--no-fail]
-
-Cobbler reposync is the command to use to update repos as configured with "cobbler repo add".  Mirroring
-can take a long time, and usage of Cobbler reposync prior to usage is needed to ensure provisioned systems have the
-files they need to actually use the mirrored repositories.  If you just add repos and never run "cobbler reposync", the
-repos will never be mirrored.  This is probably a command you would want to put on a crontab, though the frequency of
-that crontab and where the output goes is left up to the systems administrator.
-
-For those familiar with dnf's reposync, Cobbler's reposync is (in most uses) a wrapper around the dnf reposync command.  Please
-use "cobbler reposync" to update Cobbler mirrors, as dnf's reposync does not perform all required steps. Also Cobbler
-adds support for rsync and SSH locations, where as dnf's reposync only supports what yum supports (http/ftp).
-
-If you ever want to update a certain repository you can run:
-
-.. code-block:: shell
-
-    cobbler reposync -- ...
-
-When updating repos by name, a repo will be updated even if it is set to be not updated during a regular reposync
-operation (ex: ``cobbler repo edit --name=reponame1 --keep-updated=False``).
-
-Note that if a Cobbler import provides enough information to use the boot server as a yum mirror for core packages,
-Cobbler can set up automatic installation files to use the Cobbler server as a mirror instead of the outside world. If
-this feature is desirable, it can be turned on by setting ``yum_post_install_mirror`` to ``True`` in
-``/etc/cobbler/settings.yaml`` (and running ``cobbler sync``). You should not use this feature if machines are
-provisioned on a different VLAN/network than production, or if you are provisioning laptops that will want to acquire
-updates on multiple networks.
-
-The flags ``--tries=N`` (for example, ``--tries=3``) and ``--no-fail`` should likely be used when putting reposync on a
-crontab. They ensure network glitches in one repo can be retried and also that a failure to synchronize one repo does
-not stop other repositories from being synchronized.
-
-Importing trees
-===============
-
-Cobbler can auto-add distributions and profiles from remote sources, whether this is a filesystem path or an rsync
-mirror. This can save a lot of time when setting up a new provisioning environment. Import is a feature that many users
-will want to take advantage of, and is very simple to use.
-
-After an import is run, Cobbler will try to detect the distribution type and automatically assign automatic installation
-files. By default, it will provision the system by erasing the hard drive, setting up eth0 for DHCP, and using a default
-password of "cobbler".  If this is undesirable, edit the automatic installation files in ``/etc/cobbler`` to do
-something else or change the automatic installation setting after Cobbler creates the profile.
-
-Mirrored content is saved automatically in ``/var/www/cobbler/distro_mirror``.
-
-Example 1: ``cobbler import --path=rsync://mirrorserver.example.com/path/ --name=fedora --arch=x86``
-
-Example 2: ``cobbler import --path=root@192.168.1.10:/stuff --name=bar``
-
-Example 3: ``cobbler import --path=/mnt/dvd --name=baz --arch=x86_64``
-
-Example 4: ``cobbler import --path=/path/to/stuff --name=glorp``
-
-Example 5: ``cobbler import --path=/path/where/filer/is/mounted --name=anyname --available-as=nfs://nfs.example.org:/where/mounted/``
-
-Once imported, run a ``cobbler list`` or ``cobbler report`` to see what you've added.
-
-By default, the rsync operations will exclude content of certain architectures, debug RPMs, and ISO images -- to change
-what is excluded during an import, see ``/etc/cobbler/rsync.exclude``.
-
-Note that all of the import commands will mirror install tree content into ``/var/www/cobbler`` unless a network
-accessible location is given with ``--available-as``.  --available-as will be primarily used when importing distros
-stored on an external NAS box, or potentially on another partition on the same machine that is already accessible via
-``http://`` or ``ftp://``.
-
-For import methods using rsync, additional flags can be passed to rsync with the option ``--rsync-flags``.
-
-Should you want to force the usage of a specific Cobbler automatic installation template for all profiles created by an
-import, you can feed the option ``--autoinstall`` to import, to bypass the built-in automatic installation file
-auto-detection.
-
-Repository mirroring workflow
-=============================
-
-The following example shows how to set up a repo mirror for all enabled Cobbler host repositories and two additional repositories,
-and create a profile that will auto install those repository configurations on provisioned systems using that profile.
-
-.. code-block:: shell
-
-    cobbler check
-    # set up your cobbler distros here.
-    cobbler autoadd
-    cobbler repo add --mirror=http://mirrors.kernel.org/fedora/core/updates/6/i386/ --name=fc6i386updates
-    cobbler repo add --mirror=http://mirrors.kernel.org/fedora/extras/6/i386/ --name=fc6i386extras
-    cobbler reposync
-    cobbler profile add --name=p1 --distro=existing_distro_name --autoinstall=/etc/cobbler/kickstart_fc6.ks --repos="fc6i386updates fc6i386extras"
-
-Import Workflow
-===============
-
-Import is a very useful command that makes starting out with Cobbler very quick and easy.
-
-This example shows how to create a provisioning infrastructure from a distribution mirror or DVD ISO. Then a default PXE
-configuration is created, so that by default systems will PXE boot into a fully automated install process for that
-distribution.
-
-You can use a network rsync mirror, a mounted DVD location, or a tree you have available via a network filesystem.
-
-Import knows how to autodetect the architecture of what is being imported, though to make sure things are named
-correctly, it's always a good idea to specify ``--arch``. For instance, if you import a distribution named "fedora8"
-from an ISO, and it's an x86_64 ISO, specify ``--arch=x86_64`` and the distro will be named "fedora8-x86_64"
-automatically, and the right architecture field will also be set on the distribution object. If you are batch importing
-an entire mirror (containing multiple distributions and arches), you don't have to do this, as Cobbler will set the
-names for things based on the paths it finds.
-
-.. code-block:: shell
-
-    cobbler check
-    cobbler import --path=rsync://yourfavoritemirror.com/rhel/5/os/x86_64 --name=rhel5 --arch=x86_64
-    # OR
-    cobbler import --path=/mnt/dvd --name=rhel5 --arch=x86_64
-    # OR (using an external NAS box without mirroring)
-    cobbler import --path=/path/where/filer/is/mounted --name=anyname --available-as=nfs://nfs.example.org:/where/mounted/
-    # wait for mirror to rsync...
-    cobbler report
-    cobbler system add --name=default --profile=name_of_a_profile1
-    cobbler system add --name=AA:BB:CC:DD:EE:FF --profile=name_of_a_profile2
-    cobbler sync
-
 Virtualization
 ##############
 

diff --git a/docs/user-guide/internal-database.rst b/docs/user-guide/internal-database.rst
@@ -0,0 +1,36 @@
+*****************
+Internal Database
+*****************
+
+.. note:: This document describes advanced topics for system administrators.
+
+The internal database of Cobbler is held at ``/var/lib/cobbler/collections``.
+
+Items
+#####
+
+An item in Cobbler is a set of attributes grouped together and given a name. An example for this would be a ``distro``.
+On disk those items are represented using JSON. By default, the JSON is minified, however you can make the serializer
+produce "pretty" JSON files by changing ``serializer_pretty_json`` to ``true`` in the Cobbler Settings.
+
+The name of the saved file is the name of the item.
+
+Collections
+###########
+
+A collection in Cobbler is a number of ``n`` Cobbler items that are living inside the same folder.
+
+Notes
+#####
+
+If you want to have a backup use the ``scm_track`` module of Cobbler.
+It will use Git for version control of the complete ``/var/lib/cobbler/`` folder.
+
+A rename operation does the following: Delete the item with the old name and create a new item with the new name. This is
+reflected on disk and thus if Cobbler is being terminated at the wrong point in time, this specific item
+can get lost. It's unlikely, but if you have items dependent onto that item you will receive errors on the
+next Cobbler startup.
+
+If you deem yourself a Cobbler expert you may edit the JSON files directly once Cobbler is not running. If Cobbler is
+running you risk a corruption of the complete application. Please take all actions here with huge precautions and
+only if you have backups!