From 946f37af520de9203a2b9a64b8f37c42111f3861 Mon Sep 17 00:00:00 2001
From: Slawomir Koszewski <slawek@koszewscy.waw.pl>
Date: Sat, 16 May 2026 15:18:32 +0200
Subject: [PATCH] Enhance README with detailed instructions for SSH keytab
 creation and client connection configuration

---
 README.md | 34 ++++++++++++++++++++++++++++------
 1 file changed, 28 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 0a3fc5a..31b53a2 100644
--- a/README.md
+++ b/README.md
@@ -261,14 +261,14 @@ SSH uses the `host/` service principal. The FQDN must match the result of forwar
 
 ### Linux
 
-Create the host principal and extract the keytab to the default location:
+Create the host principal and extract the keytab to the default location (run as `root` on the SSH server — the keytab is written to `/etc/krb5.keytab`, mode `0600`):
 
 ```bash
-kadmin -p admin@REALM -q "addprinc -randkey host/ssh-server.example.org@REALM"
-kadmin -p admin@REALM -q "ktadd host/ssh-server.example.org@REALM"
+sudo kadmin -p admin@REALM -q "addprinc -randkey host/ssh-server.example.org@REALM"
+sudo kadmin -p admin@REALM -q "ktadd host/ssh-server.example.org@REALM"
 ```
 
-The keytab is written to `/etc/krb5.keytab` (mode `0600`, owned by `root`). Add to `/etc/ssh/sshd_config`:
+Add to `/etc/ssh/sshd_config` (requires `root`):
 
 ```
 GSSAPIAuthentication yes
@@ -276,7 +276,11 @@ GSSAPICleanupCredentials yes
 GSSAPIStrictAcceptorCheck yes
 ```
 
-`GSSAPIStrictAcceptorCheck` verifies the server's identity against the keytab — keep it enabled. Reload sshd after the change.
+`GSSAPIStrictAcceptorCheck` verifies the server's identity against the keytab — keep it enabled. Reload sshd (requires `root`):
+
+```bash
+sudo systemctl reload sshd
+```
 
 **Login authorisation** — by default a principal is granted access if its realm matches `default_realm` and its name matches the local account. To grant additional principals access to an account, list them in `~/.k5login` (one principal per line):
 
@@ -292,6 +296,24 @@ If `.k5login` is present it is authoritative — unlisted principals are denied
     k5login_authoritative = false
 ```
 
+### Client connection
+
+SSH will prefer public key authentication by default even when GSSAPI is available. To enforce Kerberos:
+
+```bash
+ssh -o GSSAPIAuthentication=yes -o PreferredAuthentications=gssapi-with-mic user@ssh-server.example.org
+```
+
+To make this permanent for a host in `~/.ssh/config`:
+
+```
+Host ssh-server.example.org
+    GSSAPIAuthentication yes
+    PreferredAuthentications gssapi-with-mic
+```
+
+On Windows (KfW) and macOS the same `ssh` flags apply. macOS additionally accepts `-K` as a shorthand for `GSSAPIAuthentication=yes`.
+
 ### Windows
 
 `GSSAPIAuthentication` is available on **Windows Server 2022, 2025, Windows 10 (May 2021 Update), and Windows 11** only. Windows Server 2019 does not support it.
@@ -313,7 +335,7 @@ GSSAPIAuthentication yes
 
 > The following directives are **not available** on Windows OpenSSH and must not be added: `GSSAPICleanupCredentials`, `GSSAPIStrictAcceptorCheck`, `KerberosAuthentication`, `KerberosTicketCleanup`.
 
-Restart the `sshd` service after the change:
+Restart the `sshd` service after the change (requires an elevated PowerShell prompt):
 
 ```powershell
 Restart-Service sshd