Document Directory Groups and task-type role permissions

docs/1.6/management/web/directory-groups.md

@@ -0,0 +1,144 @@
+---
+title: Directory Groups
+aliases:
+    - Directory Groups
+    - Directory Domains
+    - Directory Groups plugin
+description: Connect FOG to one or more Active Directory domains, browse their OUs, and group hosts by OU
+context_id: directory-groups
+tags:
+    - 1_6-changes
+    - management
+    - web-management
+    - plugins
+    - active-directory
+---
+
+# Directory Groups
+
+The **Directory Groups** plugin connects FOG to your Active Directory
+domains. It keeps a list of domains, shows the OUs of each domain as a tree,
+and groups hosts by OU. FOG uses the connection of a domain to move the computer
+account of a host into the OU set on that host.
+
+Directory Groups replaces the **ou** plugin. The **ou** plugin supports one
+domain. Directory Groups supports many.
+
+>[!info] FOG 1.6
+>Directory Groups exists in FOG 1.6 only. For how placement works and how to
+>set the AD fields on a host, see [[ad-integration|Active Directory Integration]].
+
+## Turning it on
+
+Directory Groups is a bundled plugin. Turn the plugin system on first. See
+[[1.6/management/web/plugins|Plugins]].
+
+1. Go to **Plugins**.
+2. Tick **directorygroups** in the list.
+3. Click **Install selected**. Install also activates the plugin.
+
+Two entries appear in the main menu: **Directory Domains** and
+**Directory Groups**.
+
+## Directory Domains
+
+A directory domain holds the connection details for one Active Directory
+domain. Go to **Directory Domains → Create New Domain** to add one.
+
+| Field | What to enter |
+|---|---|
+| **Domain Name** | The DNS name of the domain, for example `example.com` |
+| **Description** | A note for your own use |
+| **Server URI** | The directory server, for example `ldaps://dc1.example.com:636` |
+| **Bind DN** | The account FOG uses to read the directory, for example `CN=fog-read,CN=Users,DC=example,DC=com` |
+| **Bind Password** | The password of the bind account |
+| **CA Certificate Path** | The path on the FOG server to the CA certificate file, for example `/etc/ssl/certs/example-ca.pem` |
+| **Computer Search Base** | The base DN where FOG looks for computer accounts, for example `DC=example,DC=com` |
+| **OU Browse Base** | The DN where the OU tree starts. If you leave it blank, the tree starts at the domain root |
+
+FOG never shows the **Bind Password** again after you save it. When you edit
+a domain, leave the field blank to keep the stored password. The password is
+not part of any export.
+
+### How FOG picks the domain for a host
+
+FOG matches the **Domain Name** of the directory domain to the DNS name in the
+**Domain Name** field on the **Active Directory** tab of the host. The match
+ignores case. If the host domain is not in the list, FOG finds no connection
+and does not place the host.
+
+>[!note] FOG Settings
+>While Directory Groups is installed, the **FOG Settings** page hides these
+>five settings: `FOG_DIRECTORY_LDAP_URI`, `FOG_DIRECTORY_BIND_DN`,
+>`FOG_DIRECTORY_BIND_PASSWORD`, `FOG_DIRECTORY_CA_CERT`, and
+>`FOG_DIRECTORY_BASE_DN`. Each directory domain holds these values now.
+>`FOG_DIRECTORY_PLACEMENT_ENABLED` stays visible. Uninstalling the plugin
+>shows the five settings again.
+
+## Adding OUs as groups
+
+Open a directory domain and click the **Organizational Units** tab. The tab
+shows the OUs under the **OU Browse Base** as a tree.
+
+1. Type in the search box to find an OU.
+2. Tick the OUs you want.
+3. Click **Add selected as groups**.
+
+Each OU becomes a directory group. The group name is the domain name followed
+by the OU path, for example `example.com/Sales/Staging`. An OU that already has
+a group shows its group ID and has no tick box.
+
+## Grouping hosts by OU
+
+Go to **Directory Groups** to see the groups and the hosts in each group.
+A host also gets a **Directory Group** tab. Use the tab to set the group of
+that host.
+
+### Browse Directory on the host page
+
+The **Active Directory** tab of a host has a **Browse Directory** button.
+
+1. Click **Browse Directory**.
+2. Pick a domain in the list.
+3. Click an OU in the table.
+
+FOG fills **Domain Name** and **Organizational Unit** on the tab. FOG saves
+nothing until you click **Update**. The button shows only to users who hold
+the `directorydomain.view` permission.
+
+## Moving from the ou plugin
+
+When you install Directory Groups, FOG migrates your existing setup:
+
+- FOG creates the first directory domain from the `FOG_DIRECTORY_*`
+  connection settings. FOG takes the domain name from the `DC=` parts of the
+  base DN.
+- If the **ou** plugin is installed, FOG copies its OUs and host links into
+  Directory Groups. FOG keeps the IDs. A second install run copies nothing
+  twice.
+
+The **ou** plugin stays installed. Uninstall it when you are ready.
+
+>[!warning] Install Directory Groups before you uninstall ou
+>Uninstalling **ou** drops its database tables. Install Directory Groups
+>first so the migration can copy the data.
+
+## Permissions
+
+Directory Groups adds two permission areas. See [[roles|Roles & Permissions]].
+
+| Area | Controls |
+|---|---|
+| `directorygroups` | Directory groups: **View**, **Create**, **Edit**, **Delete** |
+| `directorydomain` | Directory domains and their bind accounts: **View**, **Create**, **Edit**, **Delete** |
+
+The areas are separate. A role that groups hosts does not get access to the
+bind accounts. To add OUs as groups, a role needs `directorygroups` **Create**,
+`directorydomain` **View**, and `directorydomain` **Edit**.
+
+## Uninstalling
+
+**Uninstall selected** on the **Plugins** page drops the three tables of the
+plugin. These tables hold the directory domains, the directory groups, and the
+host links. The **ou** plugin is not changed. The five `FOG_DIRECTORY_*`
+connection settings show again on the **FOG Settings** page.

docs/1.6/management/web/plugins.md

@@ -221,12 +221,13 @@ this page for how it differs on the older line.
 | Plugin | What it does |
 |---|---|
 | **capone** | Match a machine's DMI value against a key you define and deploy the associated image, without registering the host first |
+| **directorygroups** | Keep a list of Active Directory domains, browse their OUs, and group hosts by OU. Replaces **ou**. See [[directory-groups\|Directory Groups]] |
 | **helloworld** | A skeleton example plugin — the reference for people writing their own |
 | **ldap** | Authenticate FOG users against an LDAP or Active Directory server. Needs your distribution's `php-ldap` package. See [[1.6/management/web/ldap\|LDAP Authentication]] |
 | **location** | Point hosts at the storage node local to their site, for sites with more than one place to fetch an image from |
 | **ntfy** | Notifications via ntfy.sh or your own ntfy server |
 | **oidc** | Sign in to FOG with an OpenID Connect identity provider (Entra ID, Keycloak, Okta, ...). See [[oidc\|OpenID Connect Sign-in]] |
-| **ou** | Predefine Active Directory OUs and associate them with hosts |
+| **ou** | Predefine Active Directory OUs and associate them with hosts. Directory Groups replaces it. See [[directory-groups\|Directory Groups]] |
 | **pushbullet** | Pushbullet notifications |
 | **slack** | Slack notifications |
 | **subnetgroup** | Assign hosts to groups automatically based on their IP subnet |

docs/management/web/roles.md

@@ -95,6 +95,8 @@ menu.
     - **Permissions** — a grid of areas and actions. Tick the boxes the
       role should grant, or tick **Administrator (full access)** to
       grant everything, then click **Update**.
+    - **Task Types** — the task types this role may start. See
+      [Task type permissions](#task-type-permissions).
     - **Users** — add or remove the user accounts that hold this role.
 
 ### Assigning roles to users
@@ -142,6 +144,89 @@ their dashboard, the client-facing pages, and log out.
   their user record (editing users requires the Users **Edit**
   permission — and would otherwise let a user change their own roles).
 
+## Task type permissions
+
+>[!info] FOG 1.6
+>Task type permissions exist in FOG 1.6 only.
+
+The **Task** action lets a role start tasks. By itself, it allows every task
+type. A role that can deploy can also capture, wipe, and open a debug shell.
+A task type permission limits a role to the task types you choose.
+
+### What a task type permission is
+
+Each task type has one permission, named `tasktype.<id>`. The `<id>` is the
+task type ID. FOG stores the ID and not the name. The **Task Types** tab shows
+the current name of each type. If you rename a task type with the
+**tasktypeedit** plugin, the role keeps its grants.
+
+The permission `tasktype.*` grants every task type, including types added
+later.
+
+### The Task Types tab
+
+Open **Roles**, select a role, and click the **Task Types** tab. The tab shows
+one row for each task type, with a tick box, the task type name, and its ID.
+
+- Tick the task types the role may start.
+- Tick **All task types, including types added later** to grant `tasktype.*`.
+- Click **Update**.
+
+A grant for a task type that no longer exists shows as **Removed task type**.
+Untick it to clear it. A role with **Administrator (full access)** can start
+every task type. The tab shows its tick boxes as disabled.
+
+The **Permissions** tab does not show task types. When you click **Update** on
+that tab, FOG keeps the task type grants of the role.
+
+### A role needs both permissions
+
+A role must hold two permissions to start a task:
+
+- The **Task** action of the area, such as **Hosts → Task**, **Groups → Task**,
+  or **Images → Task**.
+- The task type permission for that task type.
+
+For example, a role with **Hosts → Task** and only the **Deploy** task type
+can deploy hosts. It gets a 403 error for every other task type. FOG records
+each refusal in the audit log. The web UI hides the quick task buttons and
+the task accordion entries for task types the role may not start.
+
+### Where FOG checks the task type
+
+FOG checks the task type everywhere a task starts:
+
+- Deploy of a host, of a group, and of multiple selected hosts, instant or
+  scheduled.
+- Multicast sessions started from an image.
+- The REST API route `POST /{class}/{id}/task`.
+- Creating or editing a task or a scheduled task through the REST API. An edit
+  checks the old task type and the new task type. A user cannot edit a
+  scheduled Deploy into a wipe.
+- The iPXE menu: quick image (Deploy), joining a multicast session
+  (Multi-Cast), and the debug shell (Debug).
+- Full registration with a deploy (Deploy).
+
+FOG checks a scheduled task when a user schedules it. The scheduler service
+does not check it again when the task runs.
+
+>[!warning] The iPXE menu and full registration now check the role
+>In earlier builds, the iPXE quick image and full registration with a deploy
+>needed only a valid sign-in. They now need the Deploy task type. The iPXE
+>debug shell needs the Debug task type.
+
+### What the upgrade does
+
+The database upgrade gives `tasktype.*` to every role that held a task
+permission: **Hosts**, **Groups**, **Images**, or **Tasks** **Task**, or the
+matching full-area permission. Nothing changes for these roles until an
+administrator narrows the grant.
+
+To narrow a role, untick **All task types, including types added later** on the
+**Task Types** tab, tick the task types you want, and click **Update**. A role
+with a list of single task types cannot start a task type added later until you
+tick it. A role with no task permission has no task type permission.
+
 ## Narrowing a role to specific sites
 
 Roles decide **what** a user can do; they do not decide **which**