Skip to content

[WIP]SLE-20008: troubleshooting krb #1755

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Amrita42 wants to merge 6 commits into
base: main
Choose a base branch
from
Open

[WIP]SLE-20008: troubleshooting krb #1755

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
f5ee9a4
troubleshooting krb
Amrita42 Jul 31, 2024
3451947
adds krb trace troubleshooting
Amrita42 Aug 22, 2024
f3203b6
addes more steps
Amrita42 Aug 22, 2024
83a5846
adds more steps
Amrita42 Aug 22, 2024
d8b2f3d
more content
Amrita42 Aug 22, 2024
40c7475
adds a note
Amrita42 Aug 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
134 changes: 134 additions & 0 deletions xml/security_kerberos.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1914,6 +1914,140 @@ Valid starting Expires Service principal
</procedure>
</sect1> -->

<sect1 xml:id="sec-security-kerberos-troubleshooting">
<title>Troubleshooting &krb;</title>
<para>
Troubleshooting &krb; issues can be complex because of its role in secure authentication within a network.
Copy link
Collaborator

@Firstyear Firstyear Sep 6, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Troubleshooting kerberos is complex, because kerberos is a dumpster fire of a service.

I don't think we shuold say this, and this line adds no value to the documentation.

Using the <envar>KRB5_TRACE</envar> environment variable helps significantly in troubleshooting.
<envar>KRB5_TRACE</envar> provides a detailed log of &krb; operations.
</para>
<procedure>
<title>Using <envar>KRB5_TRACE</envar> to debug &krb; </title>
<step>
<para>
Ensure your &krb; configuration file, which is either <filename>krb5.conf</filename> or <filename>krb5.ini</filename>
is correctly set up. This file has all the required settings for your &krb; client and includes realms, KDC and admin servers.
</para>
</step>
<step>
<para>
Enable <envar>KRB5_TRACE</envar> logging by setting the environment variable to a file where you want the
trace logs to be saved. This file will contain detailed information on all the &krb; operations.
Copy link
Collaborator

@Firstyear Firstyear Sep 6, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

instead of "krb operations" which doesn't make sense, try "kerberos commands that are executed".

For example:</para>
<screen>&prompt.sudo; export KRB5_TRACE=/path/to/krb5_trace.log</screen>
</step>
<step>
<para>
Execute the action that triggers the &krb; authentication issue for example, logging into a service.
Copy link
Collaborator

@Firstyear Firstyear Sep 6, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Where are the examples? How the KRB5_TRACE help? How does it work? These are things that a user will want to know.

Show an example like:

KRB5_TRACE=/dev/stderr kinit username@realm

The trace log captures the process details.
</para>
</step>
<step>
<para>
Examine in-depth, the contents of the log file as specified by <envar>KRB5_TRACE</envar>. The log file contains details
about &krb; requests,responses and errors. Specifically, look for:
</para>
<variablelist>
<varlistentry>
<term>Request and Response Details </term>
<listitem>
<para>
Check if requests are reaching the KDC and responses are being received.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Error messages</term>
<listitem>
<para>
Evaluate any error messages or codes that indicate something is wrong.
</para>

</listitem>
</varlistentry>
<varlistentry>
<term>Network issues</term>
<listitem>
<para>
Check if the KDC is reachable or any network issues.
</para>
</listitem>
</varlistentry>
</variablelist>
</step>
<step>
<para>
Examine the common issues such as:
</para>
<variablelist>
<varlistentry>
<term>Configuration issues </term>
<listitem>
<para>
Verify that the realms, KDC addresses and other settings are correct in the configuration file.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Synchronized time</term>
<listitem>
<para>
&krb; is sensitive to time discrepancies so ensure all systems have a synchronized clock.
</para>

</listitem>
</varlistentry>
<varlistentry>
<term>Network issues</term>
<listitem>
<para>
Verify that there is stable connection between the client and the KDC.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>DNS issues</term>
<listitem>
<para>
Ensure there is a proper DNS resolution for the KDC and other &krb; related services.
Copy link
Collaborator

@Firstyear Firstyear Sep 6, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

grammar, this reads really awkwardly.

</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Permission issues</term>
<listitem>
<para>
Check if the &krb; principal has the right permissions.
Copy link
Collaborator

@Firstyear Firstyear Sep 6, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

krb principals don't have permissions, what does this mean? KRB is authentication, not authorisation.

</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Permission issues</term>
<listitem>
<para>
Once you make the changes, repeat the action that triggered the issue to ensure the problem is solved.
Check the <envar>KRB5_TRACE</envar> log to confirm that the issues no longer exists.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Permission issues</term>
<listitem>
<para>
Once the issue is resolved, you can disable <envar>KRB5_TRACE</envar> log:
</para>
<screen>&prompt.sudo; unset KRB5_TRACE</screen>
</listitem>
</varlistentry>
</variablelist>
</step>
</procedure>
<note><para>Machine accounts are subject to the same &krb; authentication as user accounts.
During &krb; authentication, clients that run local processes using the <literal>system</literal>
account, assign these processes to the machine account when accessing remote resources. The machine account
is associated to the computer name registered with the domain controller and is distinct with a <literal>$</literal>
sign.</para></note>
Copy link
Collaborator

@Firstyear Firstyear Sep 6, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This paragraph is very vague and potentially inaccurate. Machine accounts are no different to a user account. They just are representing that that entity is a machine, instead of a human. There isn't some magic that gives a "service" on the machine credentials either, it's done through keytabs that have extracted principal information.

I'm really not sure what you are trying to communicate in this note.

</sect1>
<sect1 xml:id="sec-security-kerberos-nfs">
<title>&krb; and NFS</title>

Expand Down