Ansible/docs/install.md

AIM Installation Guide

This guide installs AIM with /etc/ansible/scripts as the project root.

Layout

/etc/ansible/scripts/
├── pyproject.toml
└── src/
    └── aim/

/etc/ansible/.venv/
/usr/local/bin/aim -> /etc/ansible/.venv/bin/aim

The virtual environment is intentionally not stored in Git.

1. Prerequisites

On Debian/Ubuntu:

sudo apt update
sudo apt install -y python3 python3-venv python3-pip

2. Rebuild the virtual environment

sudo rm -rf /etc/ansible/.venv
sudo python3 -m venv /etc/ansible/.venv
sudo /etc/ansible/.venv/bin/python -m pip install --upgrade pip setuptools wheel

3. Install AIM

sudo /etc/ansible/.venv/bin/python -m pip install -e /etc/ansible/scripts

Verify:

ls -l /etc/ansible/.venv/bin/aim
/etc/ansible/.venv/bin/python -m pip check

4. Restore the system-wide command

sudo ln -sfn /etc/ansible/.venv/bin/aim /usr/local/bin/aim

Verify:

ls -l /usr/local/bin/aim
aim --version

5. Authorization group / using another GID

AIM authorization is group-based rather than root-based. The default required group is:

srv_debsansible01_admins@bitformer.lan

AIM resolves the configured group name through the operating system's NSS layer (for example local groups, SSSD or winbind). The operator must have that group active as a primary or supplementary group.

Do not hard-code a numeric GID into AIM merely because a particular server uses a different GID. Numeric GIDs can differ between systems; configure the appropriate group name and let NSS resolve its GID.

Inspect the default group and its resolved GID:

getent group 'srv_debsansible01_admins@bitformer.lan'

Check the current user's active groups/GIDs:

id
id -G
id -Gn

If another authorization group should be used, change AIM's Required Group through:

Global Config
└── Required Group

For example, if the local/AD-backed group is:

ansible_operators

verify it first:

getent group ansible_operators

Then configure ansible_operators as AIM's Required Group. AIM will use the GID returned by NSS for that group.

After adding a user to a group, the login session may need to be renewed before the supplementary group becomes active. Verify with id before troubleshooting AIM authorization.

Same group name, different GID

This is supported. For example, one server may resolve:

ansible_operators:x:1200:...

and another may resolve:

ansible_operators:x:48001:...

AIM should be configured with ansible_operators, not 1200 or 48001.

Different group name

Configure the alternative group name in AIM Global Config and confirm:

getent group '<group-name>'
id

If getent cannot resolve the group, fix NSS/SSSD/winbind/local group resolution first.

6. Git-ignored runtime data

Important ignored data includes:

.vscode/*
.venv/*
.ansible/*
secure/*
secure/keys/*
vault.yml
.ssh
*.msi
*.deb
*.rpm
**/.hosts.tsv
**/hosts.yml.aim-session.bak
**/hosts.aim-session.bak.yml
*.bak

For AIM inventory recovery, the critical persistent data is vault.yml and inventory .ssh/ content. Do not restore .venv; rebuild it.

7. Recover missing Vaults and SSH keys

Example restored backup:

/etc/ansible/inventories_RESTORED_20260915_152127

Active inventories:

/etc/ansible/inventories

Dry run

BACKUP="/etc/ansible/inventories_RESTORED_20260915_152127"
TARGET="/etc/ansible/inventories"

echo "=== vault.yml ==="
sudo find "$BACKUP" -type f -name 'vault.yml' -print0 |
while IFS= read -r -d '' src; do
    rel="${src#"$BACKUP"/}"
    dst="$TARGET/$rel"
    if [ -e "$dst" ]; then
        echo "KEEP     $dst"
    else
        echo "RESTORE  $src -> $dst"
    fi
done

echo
echo "=== .ssh files ==="
sudo find "$BACKUP" -path '*/.ssh/*' -type f -print0 |
while IFS= read -r -d '' src; do
    rel="${src#"$BACKUP"/}"
    dst="$TARGET/$rel"
    if [ -e "$dst" ]; then
        echo "KEEP     $dst"
    else
        echo "RESTORE  $src -> $dst"
    fi
done

Restore

BACKUP="/etc/ansible/inventories_RESTORED_20260915_152127"
TARGET="/etc/ansible/inventories"

sudo find "$BACKUP" -type f -name 'vault.yml' -print0 |
while IFS= read -r -d '' src; do
    rel="${src#"$BACKUP"/}"
    dst="$TARGET/$rel"
    if [ -e "$dst" ]; then
        echo "KEEP     $dst"
        continue
    fi
    sudo mkdir -p "$(dirname "$dst")"
    sudo cp -a "$src" "$dst"
    echo "RESTORED $dst"
done

sudo find "$BACKUP" -path '*/.ssh/*' -type f -print0 |
while IFS= read -r -d '' src; do
    rel="${src#"$BACKUP"/}"
    dst="$TARGET/$rel"
    if [ -e "$dst" ]; then
        echo "KEEP     $dst"
        continue
    fi
    sudo mkdir -p "$(dirname "$dst")"
    sudo cp -a "$src" "$dst"
    echo "RESTORED $dst"
done

cp -a preserves ownership, permissions and timestamps. Existing active files are never overwritten.

Verify:

sudo find /etc/ansible/inventories -type f -name 'vault.yml' -print | sort
sudo find /etc/ansible/inventories -path '*/.ssh/*' -type f -print | sort
sudo find /etc/ansible/inventories -path '*/.ssh/*' -type f -exec ls -l {} \;

Keep the restored backup until Vault and SSH access have been tested.

8. Final verification

aim --version
/etc/ansible/.venv/bin/python -m pip check
aim

Updating AIM

AIM is installed editable from /etc/ansible/scripts.

If its entry point needs recreation:

sudo /etc/ansible/.venv/bin/python -m pip install -e /etc/ansible/scripts
sudo ln -sfn /etc/ansible/.venv/bin/aim /usr/local/bin/aim

Customer data under /etc/ansible/inventories is separate from the AIM source installation.