295 lines
12 KiB
Markdown
295 lines
12 KiB
Markdown
# ansipa Administration Guide
|
|
|
|
Day-to-day operation of the ansipa management plane: the full policy catalogue
|
|
and how to apply, target, and revert each policy. For the deployment/ports/
|
|
reverse-proxy story see the [ansipa Setup Guide](ansipa-setup.md); for the
|
|
architecture and container internals see [FreeIPA & Ansible](freeipa-ansible.md).
|
|
|
|
---
|
|
|
|
## How administration works
|
|
|
|
Everything is driven by **FreeIPA group membership**. You never log into a
|
|
client to change its policy — you add or remove a host or user from a group on
|
|
the FreeIPA server, and the fleet converges on the next timer tick.
|
|
|
|
Two independent client-side mechanisms consume that membership, both installed
|
|
by the Ansible playbooks and both idempotent and reversible (leaving a group
|
|
undoes the change on the next run):
|
|
|
|
| Mechanism | Timer | Reads | Applies |
|
|
|-----------|-------|-------|---------|
|
|
| **Policy enforcer** (`ansipa-enforce-policies.sh`) | `ansipa-enforce-policies.timer`, every 30 min | host + user groups | daemon/sudo/ssh/monitoring/scan/SMB/block policies |
|
|
| **Installer timers** (`ansipa-install-*.sh`) | `ansipa-install*.timer`, every 30 min | `dev_pkg_*`, `dev_mod_*`, `dev_fp_*` host groups | packages, setup modules, Flatpaks |
|
|
|
|
Because it is all client-**pull**, everything works across NAT (the server never
|
|
initiates a connection to a client). To apply a change immediately instead of
|
|
waiting for the timer, run the relevant script on the client as root:
|
|
|
|
```bash
|
|
sudo /usr/local/bin/ansipa-enforce-policies.sh # policies
|
|
sudo /usr/local/bin/ansipa-install-packages.sh # dev_pkg_*
|
|
sudo /usr/local/bin/ansipa-install-modules.sh # dev_mod_*
|
|
sudo /usr/local/bin/ansipa-install-flatpaks.sh # dev_fp_*
|
|
```
|
|
|
|
### The two group scopes
|
|
|
|
- **Host groups** (`dev_*`) — a *device* policy. Applies to the machine(s) you
|
|
add to the group. Managed with `ipa hostgroup-*`.
|
|
- **User groups** (`usr_*`) — a *user* policy that **follows the user** to every
|
|
enrolled machine they log into. Applies while the group exists; managed with
|
|
`ipa group-*`. Several user policies key off the group merely *existing* (not
|
|
the specific host), because the enforcer runs on every host.
|
|
|
|
### The two ways to bind a target
|
|
|
|
Most policies encode their target in the **group name suffix**
|
|
(`dev_local-sudo-alice`, `dev_pkg_htop`, `usr_block-binary-nano`). A few need
|
|
extra data (a printer URI, an SMB credential) which lives in the **group
|
|
description**, set with `ipa group-mod <grp> --desc='…'` — noted per-policy below.
|
|
|
|
### Everyday commands
|
|
|
|
```bash
|
|
# Create + populate a host group (device policy)
|
|
ipa hostgroup-add dev_mon_base --desc "CheckMK monitored hosts"
|
|
ipa hostgroup-add-member dev_mon_base --hosts=client01.corp.example.com
|
|
ipa hostgroup-remove-member dev_mon_base --hosts=client01.corp.example.com
|
|
|
|
# Create + populate a user group (user policy)
|
|
ipa group-add usr_admin --desc "Fleet-wide sudoers"
|
|
ipa group-add-member usr_admin --users=alice
|
|
ipa group-remove-member usr_admin --users=alice
|
|
|
|
# Inspect
|
|
ipa host-show client01.corp.example.com | grep -A3 'Member of host-groups'
|
|
ipa hostgroup-show dev_pkg_htop
|
|
```
|
|
|
|
Everything below can equally be done from the FreeIPA web UI
|
|
(**Identity → Host Groups / User Groups**).
|
|
|
|
---
|
|
|
|
## Device policies (`dev_*` host groups)
|
|
|
|
### `dev_daemon-enable-<unit>` / `dev_daemon-disable-<unit>`
|
|
Force a systemd unit on or off fleet-wide.
|
|
|
|
- **Apply:** enable → `systemctl enable --now <unit>`; disable → `disable --now`.
|
|
- **Revert (leave group):** the opposite action.
|
|
- The `.service` suffix is optional (appended automatically for a bare name); any
|
|
unit type works. A unit in **both** enable and disable groups is skipped with a
|
|
warning.
|
|
- **Example:** `ipa hostgroup-add dev_daemon-disable-bluetooth` then add hosts →
|
|
`bluetooth.service` is stopped and masked-off on them.
|
|
|
|
> ⚠️ Enabling `sshd` this way and later reverting will **stop sshd** — don't lock
|
|
> yourself out of a headless box you only reach over SSH.
|
|
|
|
### `dev_timeshift-backup`
|
|
Enforce a daily Timeshift snapshot at 03:00 (requires `timeshift`; add the host
|
|
to `dev_mod_timeshift` to install it). Leaving the group removes the cron.
|
|
|
|
### `dev_no-local-users`
|
|
Lock the password of **every** local account — root (UID 0) and all regular
|
|
users (UID ≥ 1000) — with `passwd -l`, so only FreeIPA accounts can authenticate.
|
|
Accounts already locked are left untouched and not tracked; revert unlocks only
|
|
what this policy locked. State: `/var/lib/ansipa-policies/no-local-users`.
|
|
|
|
### `dev_local-sudo-<username>`
|
|
Grant `<username>` full sudo on **this specific device** via a sudoers drop-in.
|
|
Device-scoped (unlike `usr_admin`). Leaving the group removes the drop-in.
|
|
|
|
- **Example:** `ipa hostgroup-add dev_local-sudo-alice` + add `lab-pc-3` → alice
|
|
gets sudo on `lab-pc-3` only.
|
|
|
|
### `dev_ssh_<userid>`
|
|
Distribute `<userid>`'s SSH public keys from their IPA profile to
|
|
`/home/<userid>/.ssh/authorized_keys` on hosts in the group (in an
|
|
ansipa-managed section; hand-added keys are preserved). Store the keys in IPA:
|
|
|
|
```bash
|
|
ipa user-mod alice --sshpubkey='ssh-ed25519 AAAA...'
|
|
ipa hostgroup-add dev_ssh_alice && ipa hostgroup-add-member dev_ssh_alice --hosts=…
|
|
```
|
|
|
|
Leaving the group removes only the ansipa-managed section.
|
|
|
|
---
|
|
|
|
## Monitoring policies (`dev_mon_*`, `usr_mon_*`)
|
|
|
|
All CheckMK monitoring requires the CheckMK stack to be up and
|
|
`ansipa-checkmk-setup.sh` to have run on the FreeIPA container (seeds the
|
|
`dev_mon_base` credentials + the monitoring groups in IPA). All checks are
|
|
collected by the agent, so **every monitored host must also be in
|
|
`dev_mon_base`**.
|
|
|
|
### `dev_mon_base` (required for all monitoring)
|
|
Installs the CheckMK agent, registers the host in CheckMK (under `/ansipa`), and
|
|
opens the agent for collection: pull mode on `check_mk.socket` (port 6556) where
|
|
the server can reach the client, or **push mode** (`cmk-agent-ctl` → server
|
|
`:8000`) for NAT clients. Built-in CPU/RAM/disk/uptime plus an installed-package
|
|
count check (`Ansipa_Packages`). Leaving the group deregisters the host and
|
|
disables the agent.
|
|
|
|
> Credentials are auto-discovered from the `dev_mon_base` group description
|
|
> (`cmk://<host>:<port>/<site>:automation:<secret>`), which the server populates.
|
|
> Set `CMK_ADVERTISED_URL` in `.env` to a **client-routable** address.
|
|
|
|
### `dev_mon_clamscan`
|
|
Run a daily ClamAV + rkhunter + chkrootkit scan at 02:00 and report the result
|
|
to CheckMK as the **`Ansipa_ClamScan`** service (OK = clean, WARN = stale DB or
|
|
rkhunter warnings, CRIT = infected). Self-contained — it runs the scan *and*
|
|
writes the local check; results no longer go over SMB.
|
|
|
|
- **Prerequisites:** `dev_mod_anti-malware` (tools) + `dev_mon_base` (agent).
|
|
- **Revert:** removes the cron, scan script, log, and local check.
|
|
|
|
### `dev_mon_timeshift`
|
|
`Ansipa_Timeshift` check on the newest Timeshift snapshot age: WARN > 5 days,
|
|
CRIT > 10 days or none found. Pair with `dev_timeshift-backup` (which creates
|
|
them) and `dev_mon_base`.
|
|
|
|
### `dev_mon_power`
|
|
`Ansipa_Power` check on CPU-package power via Intel RAPL (preferred) or
|
|
lm-sensors: WARN ≥ 65 W, CRIT ≥ 95 W. Add the host to `dev_mod_*` that installs
|
|
`lm_sensors` if RAPL is unavailable.
|
|
|
|
### `usr_mon_logins` (user group)
|
|
`Ansipa_Logins` check reporting SSH login attempts in the last 24 h (successful +
|
|
failed + invalid-user), with thresholds. Installed fleet-wide when the group
|
|
exists; needs `dev_mon_base` on the hosts.
|
|
|
|
---
|
|
|
|
## Software-installer policies (`dev_pkg_*`, `dev_mod_*`, `dev_fp_*`)
|
|
|
|
These are the GPO-like software-deployment groups, applied by the
|
|
`ansipa-install-*` timers (not the policy enforcer). Join → installed; leave →
|
|
removed. Install state is tracked so revert only touches what ansipa installed.
|
|
|
|
### `dev_pkg_<package>`
|
|
Install a single distro package (via pacman/dnf/apt — auto-detected).
|
|
|
|
```bash
|
|
ipa hostgroup-add dev_pkg_htop && ipa hostgroup-add-member dev_pkg_htop --hosts=…
|
|
```
|
|
|
|
### `dev_mod_<name>`
|
|
Apply a whole **setup module** from `setup/modules/optional-Modules/apps/` —
|
|
e.g. `dev_mod_docker`, `dev_mod_anti-malware`, `dev_mod_timeshift`,
|
|
`dev_mod_ollama`. This is how you install the tools other policies need
|
|
(`dev_mod_anti-malware` before `dev_mon_clamscan`, `dev_mod_timeshift` before
|
|
`dev_timeshift-backup`).
|
|
|
|
### `dev_fp_<app>`
|
|
Install a Flathub Flatpak. Encode the app ID with `__` in place of `.`:
|
|
|
|
```bash
|
|
# org.gimp.Gimp
|
|
ipa hostgroup-add dev_fp_org__gimp__Gimp
|
|
ipa hostgroup-add-member dev_fp_org__gimp__Gimp --hosts=…
|
|
```
|
|
|
|
---
|
|
|
|
## User policies (`usr_*` user groups)
|
|
|
|
### `usr_admin`
|
|
Full sudo on **every** enrolled host for members, via a `%usr_admin` sudoers
|
|
drop-in resolved through SSSD. Active while the group exists; the drop-in is
|
|
removed when the **group is deleted** (not merely when a member leaves — removing
|
|
a member just drops that user's sudo, since it is group-based).
|
|
|
|
### `usr_block-binary-<name>`
|
|
Prevent members from running `<name>` on any enrolled host via a PATH-priority
|
|
wrapper that checks group membership at runtime. Use `__` for `.` to block a
|
|
Flatpak (`usr_block-binary-org__gimp__Gimp`). Non-members are unaffected
|
|
(the wrapper transparently execs the real binary). Deleting the IPA group removes
|
|
the wrapper.
|
|
|
|
### `usr_prt_<printer>`
|
|
Auto-add `<printer>` to CUPS on any host where a member is logged in. **Store the
|
|
printer URI in the group description:**
|
|
|
|
```bash
|
|
ipa group-add usr_prt_frontdesk --desc='ipps://printserver/printers/frontdesk'
|
|
ipa group-add-member usr_prt_frontdesk --users=alice
|
|
```
|
|
|
|
Requires `cups` (installed by the policy deploy). Leaving/deleting removes the
|
|
printer.
|
|
|
|
### `usr_smb_r_<name>` / `usr_smb_rw_<name>`
|
|
Auto-mount a Samba share at `~/<name>` for logged-in members (`rw` wins if a user
|
|
is in both). **Store the credential in the group description** (written by
|
|
`ansipa-smb-setup.sh` for the built-in shares):
|
|
|
|
```
|
|
cifs://<ipa-host>:<samba-user>:<password>
|
|
```
|
|
|
|
Requires `cifs-utils` (installed by the policy deploy). Leaving unmounts on the
|
|
next run.
|
|
|
|
### `usr_smb_adm_policystore`
|
|
Mount the policy store at `~/policystore` (rw) for admin members, so you can edit
|
|
the live `policies.d/*.sh` files directly on the share — changes take effect
|
|
fleet-wide on the next 30-min enforcer tick, no redeploy needed. Credential in
|
|
the group description (auto-set by `ansipa-smb-setup.sh`).
|
|
|
|
---
|
|
|
|
## BaseUser sync (`BaseUser` group)
|
|
Not a policy script — a `systemd.path` unit (deployed by
|
|
`deploy-baseuser-sync.yml`) that, on login, adds any member of the FreeIPA
|
|
`BaseUser` group to the local `baseusers` group. Use it to grant a baseline local
|
|
group to all standard users.
|
|
|
|
---
|
|
|
|
## Common recipes
|
|
|
|
**Onboard a new workstation** (identity + monitoring + a couple of apps):
|
|
```bash
|
|
H=ws-42.corp.example.com
|
|
ipa hostgroup-add-member dev_mon_base --hosts=$H
|
|
ipa hostgroup-add-member dev_mon_clamscan --hosts=$H
|
|
ipa hostgroup-add-member dev_mod_anti-malware --hosts=$H # installs clamav/rkhunter
|
|
ipa hostgroup-add-member dev_mod_docker --hosts=$H
|
|
ipa hostgroup-add-member dev_pkg_htop --hosts=$H
|
|
# then, on the box (or wait 30 min):
|
|
sudo /usr/local/bin/ansipa-enforce-policies.sh
|
|
sudo /usr/local/bin/ansipa-install-modules.sh
|
|
```
|
|
|
|
**Give a helpdesk user sudo everywhere, block a risky tool:**
|
|
```bash
|
|
ipa group-add-member usr_admin --users=bob
|
|
ipa group-add usr_block-binary-tcpdump && ipa group-add-member usr_block-binary-tcpdump --users=intern
|
|
```
|
|
|
|
**Edit policy logic live** (as an admin in `usr_smb_adm_policystore`):
|
|
```bash
|
|
$EDITOR ~/policystore/dev_mon_clamscan.sh # applied fleet-wide next enforcer tick
|
|
```
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
| Symptom | Check |
|
|
|---------|-------|
|
|
| Policy not applying | `sudo /usr/local/bin/ansipa-enforce-policies.sh` on the client; read the `[ansipa-policies]` discovery line — is the group listed? |
|
|
| Host not in CheckMK | Is it in `dev_mon_base`? Is `CMK_ADVERTISED_URL` client-routable? `ipa hostgroup-show dev_mon_base` description present? |
|
|
| ClamAV shows "no scan yet" | Scans run 02:00; trigger once with `sudo /usr/local/bin/ansipa-clamscan.sh`. Tools installed via `dev_mod_anti-malware`? |
|
|
| Package group ignored | `dev_pkg_*` uses the *installer* timer, not the enforcer — run `sudo /usr/local/bin/ansipa-install-packages.sh`. |
|
|
| Enforcer error `ipa: command not found` | The host is not enrolled — run `freeipa-enroll.sh` first. |
|
|
| Changes take up to 30 min | That's the timer cadence; run the script manually to apply now. |
|
|
|
|
State for all policies lives under `/var/lib/ansipa-policies/`; logs go to the
|
|
journal under the `ansipa-policies` tag (`journalctl -t ansipa-policies`).
|