Add a troubleshooting module: yggdrasil-related timeouts

guides/common/modules/proc_configuring-a-host-to-use-the-pull-client.adoc

@@ -6,34 +6,6 @@ Hosts do not require an SSH connection from their {SmartProxyServer}.
 
 The `katello-pull-transport-migrate` package installs `foreman_ygg_worker` and Yggdrasil packages as dependencies, configures the Yggdrasil client, and starts the pull client worker on the host.
 
-[NOTE]
-====
-The `pull-mqtt` configuration relies on the Yggdrasil service and differs based on the version of the `yggdrasil` package that is installed on the host.
-On hosts that are already configured for `pull-mqtt` mode on which `yggdrasil` has been upgraded to version 0.4.z, changes to the Yggdrasil configuration are required to ensure remote execution keeps working.
-
-If your host has weak dependencies enabled, {Project} automatically installs the `foreman_ygg_migration` package which applies changes to Yggdrasil configuration.
-No further steps are required.
-
-If you host has weak dependencies disabled, you must install the migration package manually:
-
-[options="nowrap", subs="+quotes,verbatim,attributes"]
-----
-# dnf install foreman_ygg_migration
-----
-
-
-
-This package should get pulled in when yggdrasil >=0.4.z is installed.
-
-When installed, it checks whether yggdrasild.service is enabled. If not, it
-does nothing. If enabled, this package tweaks yggdrasil's config file to account
-for the newly needed config options and migrates service overrides from the old
-service to the new worker. Additionally, it disables the yggdrasild service and
-enables yggdrasil.service.
-
-Our worker is left to be activated through dbus.
-====
-
 .Prerequisites
 * You have registered the host to {Project}.
 * The {SmartProxy} through which the host is registered is configured to use `pull-mqtt` mode.

guides/common/modules/proc_troubleshooting-remote-jobs-timing-out-after-yggdrasil-update.adoc

@@ -0,0 +1,73 @@
+= Troubleshooting: Remote jobs timing out after `yggdrasil` update
+
+On hosts that have weak dependencies disabled and are configured to use the `yggdrasil` pull client, remote jobs can start failing due to timeouts after the `yggdrasil` package has been updated to version 0.4.z or later.
+
+The pull-based transport configuration relies on the Yggdrasil service and differs based on the version of the `yggdrasil` package that is installed on the host.
+For pull-based remote execution mode to work correctly after `yggdrasil` version 0.4.z is installed on the host, the Yggdrasil client configuration must be updated.
+Installing the `foreman_ygg_migration` package on the host ensures that {Project} applies the required changes to Yggdrasil configuration.
+
+On hosts with weak dependencies enabled, {Project} automatically installs the `foreman_ygg_migration` package.
+No further steps are required.
+
+On hosts with weak dependencies disabled, you must install the `foreman_ygg_migration` package manually.
+
+.Procedure
+. Determine which version of the `yggdrasil` package is installed on the host:
+ifdef::client-content-dnf[]
+* On {EL} 9 and {EL} 8 hosts:
++
+[options="nowrap", subs="+quotes,verbatim,attributes"]
+----
+$ dnf list installed yggdrasil
+----
+endif::[]
+ifdef::orcharhino,satellite[]
+* On {EL} 7 hosts:
++
+[options="nowrap", subs="+quotes,verbatim,attributes"]
+----
+$ yum list installed yggdrasil
+----
+endif::[]
+ifdef::client-content-apt[]
+* On {DL} hosts:
++
+[options="nowrap", subs="+quotes,verbatim,attributes"]
+----
+$ apt list --installed | grep yggdrasil
+----
+endif::[]
+ifdef::client-content-zypper[]
+* On {SLES} hosts:
++
+[options="nowrap", subs="+quotes,verbatim,attributes"]
+----
+$ zypper info yggdrasil
+----
+endif::[]
+. If your host has `yggdrasil` version 0.4.z or later installed, the `yggdrasil` and `Yggdrasil1.Worker` are expected to be running. Check the status of these services:
++
+[options="nowrap", subs="+quotes,verbatim,attributes"]
+----
+# systemctl status yggdrasil Yggdrasil1.Worker1.foreman
+----
++
+If the above services are not running, it means that Yggdrasil might not be configured correctly.
+. Install the `foreman_ygg_migration` package manually:
++
+[options="nowrap", subs="+quotes,verbatim,attributes"]
+----
+# dnf install foreman_ygg_migration
+----
++
+Installing `foreman_ygg_migration` ensures that {Project} applies the required Yggdrasil configuration changes and enables remote execution in pull mode to work as expected.
+
+.Verification
+. Check the status of the Yggdrasil services again:
++
+[options="nowrap", subs="+quotes,verbatim,attributes"]
+----
+# systemctl status yggdrasil Yggdrasil1.Worker1.foreman
+----
++
+These services should now be running.

guides/doc-Managing_Hosts/master.adoc

@@ -57,6 +57,9 @@ include::common/assembly_managing-packages.adoc[leveloffset=+1]
 
 :numbered!:
 
+[appendix]
+include::common/modules/proc_troubleshooting-remote-jobs-timing-out-after-yggdrasil-update.adoc[leveloffset=+1]
+
 [appendix]
 include::common/assembly_template-writing-reference.adoc[leveloffset=+1]