docs: Add ref glossary (#1219)

edibotopic · web-flow · commit 3d08ac08decb · 2025-03-11T14:25:22.000Z
Adds a reference glossary to the ADSys documentation, which may be especially useful for Windows sysadmins unfamiliar with Linux-specific terminology. This work was a contribution from @davidekete through the Open Documentation Academy (thanks David!): canonical/open-documentation-academy#165 UDENG-6210
diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt
@@ -1,4 +1,5 @@
 Acknowledgements
+adcli
 adml
 ADML
 admx
@@ -22,8 +23,10 @@ backends
 boolean
 CAs
 CEP
+certmonger
 CES
 changelog
+CIFS
 compinit
 config
 constructiveCAs
@@ -32,14 +35,18 @@ dac
 dconf
 dialogs
 dir
+DNS
 Dropdown
 dropdownList
 erroring
+ESM
 executables
+filesystem
 fpath
 FQDN
 GDM
 gdm
+getcert
 GPL
 gpo
 GPO
@@ -59,6 +66,7 @@ incrementation
 incrementing
 infos
 ini
+interprocess
 ip
 Jira
 kerberos
@@ -83,6 +91,7 @@ nfs
 OpenLDAP
 OU
 OUs
+pluggable
 plymouth
 png
 polkit
@@ -91,6 +100,7 @@ PowerShell
 Px
 rb
 readthedocs
+realmd
 runscripts
 setgid
 setuid
@@ -107,6 +117,7 @@ subdirectory
 subprofile
 subprofiles
 sudo
+sudoers
 syntaxes
 systemd
 systemd's
@@ -134,6 +145,7 @@ USBGuard
 usr
 unticking
 vendoring
+visudo
 VPN
 VPNs
 Winbind
diff --git a/docs/custom_conf.py b/docs/custom_conf.py
@@ -141,6 +141,7 @@
 linkcheck_ignore = [
     "http://127.0.0.1:8000",
     "https://leonelson.com/2011/08/15/how-to-increase-your-csr-key-size-on-microsoft-iis-without-removing-the-production-certificate/",
+    "https://manpages.ubuntu.com/manpages/man8/*",
 ]
 
 # Pages on which to ignore anchors
diff --git a/docs/how-to/set-up-ad.md b/docs/how-to/set-up-ad.md
@@ -8,6 +8,7 @@ As a rule of thumb, we generally separate the Ubuntu configuration from the Wind
 * forward vs backward slashes
 * let the administrator know exactly what settings are supported on which client version.
 
+(template-generations)=
 ## Ubuntu administrative template generations
 
 **ADSys** ships with pre-built Active Directory administrative templates that you can install on your Active Directory server. You will find two flavors of them:
diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md
@@ -0,0 +1,118 @@
+# Glossary for ADSys
+
+Overview of technical terms used in the documentation.
+
+```{tip}
+Think a term is missing and should be included?
+
+You can [edit this glossary](https://github.com/ubuntu/adsys/edit/main/docs/reference/glossary.md) on GitHub.
+```
+
+```{glossary}
+:sorted:
+
+active directory
+  A directory service developed by Microsoft that provides centralized authentication, authorization, and management of users, computers, and resources in a networked environment.
+
+[administrative templates](template-generations)
+  A set of policy settings that allow administrators to configure user and computer settings in a Windows-based Active Directory environment, often managed via Group Policy Objects (GPOs).
+
+[adcli](https://manpages.ubuntu.com/manpages/man8/adcli.8.html)
+  A command-line tool for managing Active Directory domain membership on Linux.
+
+ADSys
+  A tool that allows system administrators to manage Ubuntu machines using Microsoft Active Directory.
+
+[adsysctl](../reference/adsysctl-cli/)
+  A command-line utility for interacting with the ADSys service in Ubuntu.
+
+[adwatchd](../reference/adwatchd/)
+  A daemon that monitors and enforces compliance with Active Directory policies on Ubuntu systems, helping ensure settings are consistently applied.
+
+apt
+  The Advanced Package Tool. A package management system used in Debian-based distributions like Ubuntu to install, update, and remove software.
+
+[AppArmor](https://documentation.ubuntu.com/server/how-to/security/apparmor/)
+  A Linux security module that enforces mandatory access control policies on programs to limit their capabilities.
+
+[certmonger](https://manpages.ubuntu.com/manpages/man8/certmonger.8.html)
+  A service that monitors and renews certificates, commonly used in enterprise environments.
+
+client
+  In the context of ADSys, the "client" refers to an Ubuntu Desktop or Server that is managed using Microsoft Active Directory.
+
+D-Bus call
+  A command or API request used to communicate with system services via D-Bus, a message bus system for interprocess communication.
+
+[dconf](../explanation/dconf/)
+  A low-level configuration system used by GNOME-based environments to store application and system settings, providing a centralized way to manage configurations.
+
+domain controller
+  A server in an Active Directory network that authenticates users, enforces security policies, and manages domain-wide resources.
+
+FQDN
+  The Fully Qualified Domain Name. A complete domain name that specifies the exact location of a device within the DNS hierarchy.
+
+getcert
+  A command-line tool used to request, monitor, and renew security certificates, often used with certmonger.
+
+GNOME
+  A popular open-source desktop environment for Linux systems, designed for ease of use and accessibility, providing a modern graphical user interface.
+
+group policies
+  A feature in Active Directory that allows administrators to define security settings, software installations, and user preferences across multiple computers in a domain.
+
+GSettings
+  A system for storing application and desktop settings in GNOME-based environments.
+
+GVfs
+  The GNOME Virtual File System. A user-space virtual filesystem that provides access to remote locations, such as FTP, SMB, and Google Drive.
+
+Kerberos
+  A network authentication protocol that uses tickets to securely authenticate users and services.
+
+LDAP
+  The Lightweight Directory Access Protocol. A protocol for accessing and managing directory information, commonly used for authentication.
+
+PAM
+   Pluggable Authentication Modules. A framework for integrating various authentication methods into Linux systems.
+
+[Polkit](https://manpages.ubuntu.com/manpages/man8/polkit.8.html)
+  A toolkit for defining and handling system-wide privileges in Linux.
+
+realmd
+  A service that allows automatic discovery and enrollment of Linux machines into Active Directory or other identity domains.
+
+Samba
+  A software suite that enables file and print sharing between Linux and Windows systems using the SMB/CIFS protocol.
+
+Security Identifier
+  The Security Identifier, or SID, is a unique identifier assigned to users, groups, and other objects in Windows-based systems.
+
+server
+  In the context of ADSys, the "server" refers to a Windows Server running Active Directory , which manages and enforces policies for Ubuntu clients.
+
+SSSD
+   The System Security Services Daemon. A service that manages authentication and authorization with identity providers like Active Directory or LDAP. [SSSD is used with ADSys](../explanation/adsys-ref-arch/) for managing authentication and policies.
+
+sudo
+  A command that allows users to run programs with elevated (superuser) privileges on Linux systems.
+
+systemd
+  A modern system and service manager for Linux, responsible for initializing and managing system processes.
+
+systemd journal
+  A logging system that collects and organizes system logs for troubleshooting and auditing.
+
+Ubiquity installer
+  The default graphical installer for Ubuntu, designed to simplify OS installation.
+
+visudo
+  A command used to safely edit the sudoers file, a file which controls user permissions for executing commands with elevated privileges.
+
+[Ubuntu Pro](https://ubuntu.com/pro)
+  A subscription service from Canonical that provides extended security updates (ESM), compliance tools, and enterprise support for Ubuntu systems.
+
+Winbind
+  A component of Samba that allows Linux systems to authenticate users against a Windows domain. It can be used as an alternative to SSSD.
+```
diff --git a/docs/reference/index.md b/docs/reference/index.md
@@ -40,3 +40,15 @@ A comprehensive reference of policies supported by ADSys.
 policies/index
 ```
 
+## Glossary
+
+A glossary of technical terms used in the ADSys documentation.
+This may be especially useful for Windows sysadmins who are not familiar with
+Linux tools and terminology.
+
+```{toctree}
+:titlesonly:
+
+glossary
+```
+
diff --git a/docs/tutorial/certificates-auto-enrollment.md b/docs/tutorial/certificates-auto-enrollment.md
@@ -1,7 +1,7 @@
 # Certificates auto-enrollment
 
 Certificate auto-enrollment is a key component of Ubuntu’s Active Directory GPO support. 
-This feature enables clients to seamlessly enroll for certificates from Active Directory Certificate Services. 
+This feature enables clients to seamlessly enroll for certificates from Active Directory Certificate Services.
 
 This tutorial is designed to help you develop an understanding of how to efficiently implement and manage certificate auto-enrollment, ensuring your systems remain secure and compliant with organizational policies.
 
@@ -23,14 +23,14 @@ A video version of the tutorial is also available:
 
 ## Setup
 
-You will need an installation of ADSys on your client Ubuntu Machine and the client should be joined to an Active Directory (AD) domain.
+You will need an installation of ADSys on your client Ubuntu Machine and the client should be joined to an {term}`Active Directory` (AD) domain.
 Please refer to our how-to guides on setting up the Ubuntu client machine:
 
 - [Join machine to AD during installation](../how-to/join-ad-installation.md)
 - [Join machine to AD manually](../how-to/join-ad-manually.md)
 - [Install ADSys](../how-to/set-up-adsys.md)
 
-For the Windows Domain controller, refer to:
+For the Windows {term}`domain controller`, refer to:
 
 - [Set up AD](../how-to/set-up-ad.md)
 

Original file line number	Diff line number	Diff line change
`@@ -141,6 +141,7 @@`
`141`	`141`	`linkcheck_ignore = [`
`142`	`142`	`"http://127.0.0.1:8000",`
`143`	`143`	`"https://leonelson.com/2011/08/15/how-to-increase-your-csr-key-size-on-microsoft-iis-without-removing-the-production-certificate/",`
	`144`	`+ "https://manpages.ubuntu.com/manpages/man8/*",`
`144`	`145`	`]`
`145`	`146`
`146`	`147`	`# Pages on which to ignore anchors`