improve AD/Kerberos documentation

_toc.yml

@@ -62,7 +62,6 @@ chapters:
               - glob: admin-guide/puppet/components/*
           - file: admin-guide/puppet/development
       - file: admin-guide/selinux
-      - file: admin-guide/kerberos
       - file: admin-guide/software
         sections:
           - file: admin-guide/software/updates
@@ -86,6 +85,7 @@ chapters:
           - file: admin-guide/troubleshooting/login
           - file: admin-guide/troubleshooting/package_management
           - file: admin-guide/troubleshooting/boot
+          - file: admin-guide/troubleshooting/kerberos
 
   - file: infrastructure-guide/index
     sections:

admin-guide/architecture/active-directory.md

@@ -0,0 +1,64 @@
+# Active Directory
+
+## Kerberos Realm and Settings
+
+The AD domain (ie the Kerberos realm) is D.PSI.CH, **not** PSI.CH. The maximum
+lifetime of a ticket is about a day, and a ticket can be renewed for about a
+week.
+
+
+## Domain Controllers
+
+In most networks `d.psi.ch` resolves to the correct names/IPs. One exception
+is the DMZ.
+
+The domain controllers that are used internally are:
+
+- `dc00`
+- `dc01`
+- `dc02`
+
+In the DMZ we need to use these instead:
+
+- `rodc00`
+- `rodc01`
+
+It is important to note that the SSL certificates for the internal DCs are
+**not** signed for `dc0n.psi.ch`, but `dc0n.d.psi.ch` (note the extra `d`).
+In certain contexts (eg in [`sssd.conf(5)`](https://linux.die.net/man/5/sssd.conf)) specifying the DCs as
+`dc0n.psi.ch` fails because of this.
+
+
+## Linux Computer Objects
+
+Computer objects for Linux systems are created in
+`OU=linux,OU=servers,OU=psi,DC=d,DC=psi,DC=ch`. We currently do not distinguish
+between servers and workstations in AD (unlike the Windows team), as the
+distinction isn't clear and it wouldn't help us anyway (as we don't use AD group
+policies).
+
+We perform the join password-less, by pre-creating the computer object using a
+script running on the Puppet master.
+
+As the AD only support [computer account aka NetBIOS names with maximum 15 characters](https://learn.microsoft.com/en-us/troubleshoot/windows-server/identity/naming-conventions-for-computer-domain-site-ou#netbios-computer-names) it shortens longer hostnames down to the first 15 characters. This is a bit unfortunate as this name has to be unique as it serves as primary identifier in the AD.
+To work around this limitation we use a different NetBIOS name if the hostname is longer than 15 characters which is less prone to collisons ([inspiration](https://www.beyondtrust.com/docs/ad-bridge/how-to/delegate-domain-join-privileges/ad-naming-limitations.htm)).
+
+The actual NetBIOS name we use for these hosts is the first 7 characters of the name, then a `-` followed by the last 7 characters of the SHA256 hash of the fully qualified domain name. To check the NetBIOS name of a given host run
+
+```
+klist -t -k /etc/krb5.keytab
+```
+and look at the first entry, here for an example with a sufficiently short name:
+```
+  15 07.03.2023 09:23:02 PUPPET01$@D.PSI.CH
+```
+here `lx-sysdb-test-00.psi.ch` which gets a hashed NetBIOS hostname
+```
+   3 05/12/23 08:39:15 lx-sysd-3563a67$@D.PSI.CH
+```
+or `merlin-export-01.psi.ch` which has an automatically shortend NetBIOS name which was joined before we started to use the hashed NetBIOS hostnames:
+```
+   7 29.10.2019 11:24:04 MERLIN-EXPORT-0$@D.PSI.CH
+```
+
+

admin-guide/architecture/active-directory.rst

@@ -1,46 +0,0 @@
-==================
- Active Directory
-==================
-
-Kerberos Realm and Settings
----------------------------
-
-The AD domain (ie the Kerberos realm) is D.PSI.CH, **not** PSI.CH. The maximum
-lifetime of a ticket is about a day, and a ticket can be renewed for about a
-week.
-
-
-Domain Controllers
-------------------
-
-In most networks ``d.psi.ch`` resolves to the correct names/IPs. One exception
-is the DMZ.
-
-The domain controllers that are used internally are:
-
-- dc00
-- dc01
-- dc02
-
-In the DMZ we need to use these instead:
-
-- rodc00
-- rodc01
-
-It is important to note that the SSL certificates for the internal DCs are
-**not** signed for ``dc0n.psi.ch``, but ``dc0n.d.psi.ch`` (note the extra `d`).
-In certain contexts (eg in :manpage:`sssd.conf(5)`) specifying the DCs as
-``dc0n.psi.ch`` fails because of this.
-
-
-Linux Computer Objects
-----------------------
-
-Computer objects for Linux systems are created in
-``OU=linux,OU=computers,OU=psi,DC=d,DC=psi,DC=ch``. We do not distinguish
-between servers and workstations in AD (unlike the Windows team), as the
-distinction isn't clear and it wouldn't help us anyway (as we don't use AD group
-policies).
-
-We perform the join password-less, by pre-creating the computer object using a
-script running on the Puppet master.

admin-guide/configuration.md

@@ -2,6 +2,5 @@
 
 Here starts a so far small collections of configuration guides for sysadmins of RHEL installations using Puppet and Hiera.
 
-- [Hostname Length Limitation to 15 characters](configuration/hostname)
 - [Resize System Volumes (volume group `vg_root`)](configuration/vgroot)
 - [Install Citrix VDA](configuration/citrix_vda)

admin-guide/configuration/hostname.md

@@ -1,10 +0,0 @@
-# Hostname
-
-If keytab files are/need to be use by systems the hostname is limited to 15 characters. More details can be found here:
-- [AdKerberosTroubleshooting](https://wiki.psi.ch/AIT/AdKerberosTroubleshooting)
-- [KeytabFile](https://wiki.psi.ch/AIT/KeytabFile)
-
-A copy of the wiki pages can be found at:
-- [AdKerberosTroubleshooting.pdf](../_static/AIT-AD-Kerberos-Troubleshooting.pdf)
-- [KeytabFile.pdf](../_static/AIT-Keytab-File.pdf)
-

admin-guide/kerberos.md

@@ -1,6 +0,0 @@
-# Kerberos
-
-PSI Kerberos documentation: https://intranet.psi.ch/de/knowledge-base/kerberos-and-afs
-
- - Old AIT AD Kerberos troubleshooting guide: [PDF](https://git.psi.ch/linux-infra/documentation/-/blob/master/pdf/ADKerberosTroubleshooting.pdf)
- - Old AIT keytab file documentation: [PDF](https://git.psi.ch/linux-infra/documentation/-/blob/master/pdf/KeytabFile.pdf)

admin-guide/troubleshooting/kerberos.md

@@ -0,0 +1,6 @@
+# Kerberos
+
+PSI Kerberos documentation: https://intranet.psi.ch/de/knowledge-base/kerberos-and-afs
+
+ - Old AIT AD Kerberos troubleshooting guide: [PDF](../_static/AIT-AD-Kerberos-Troubleshooting.pdf)
+ - Old AIT keytab file documentation: [PDF](../_static/AIT-Keytab-File.pdf)