diff --git a/docs/1.6/management/web/directory-groups.md b/docs/1.6/management/web/directory-groups.md new file mode 100644 index 0000000..cd21a31 --- /dev/null +++ b/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. diff --git a/docs/1.6/management/web/plugins.md b/docs/1.6/management/web/plugins.md index 828ca37..3e2ac04 100644 --- a/docs/1.6/management/web/plugins.md +++ b/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 | diff --git a/docs/management/web/roles.md b/docs/management/web/roles.md index 47aa346..dfa43cc 100644 --- a/docs/management/web/roles.md +++ b/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.`. The `` 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**