add sources

docs/alpha/components/bacula/Bacula-Installation-Guide.md

@@ -151,3 +151,42 @@ sudo systemctl status bacula-director bacula-sd bacula-fd
 ## 8. SELinux/AppArmor
 
 If you are using SELinux or AppArmor, you may need to adjust the security policies to allow Bacula to access the new configuration directory and storage directory. The specific steps will depend on your security policy.
+
+## 9. Calypso Bacula Agent Registration Flow
+
+The Calypso Director exposes a REST API that allows a lightweight Bacula agent to register itself, report its capability matrix, and receive UI-driven capability pushes.
+
+### 9.1. Authenticate with Calypso
+1. Log in against `POST /api/v1/auth/login` with a Calypso user that has the `bacula-admin` role. The same JWT token is used for all subsequent agent calls.
+2. Store the token (and refresh it whenever a 401 is returned) so the agent can re-authenticate automatically.
+
+### 9.2. Register the client
+- Call `POST /api/v1/bacula/clients/register` with the following payload:
+  ```json
+  {
+    "hostname": "backup-client-01",
+    "ip_address": "10.0.0.15",
+    "agent_version": "1.0.0",
+    "backup_types": ["files", "database"],
+    "metadata": {
+      "platform": "ubuntu",
+      "location": "datacenter-1"
+    }
+  }
+  ```
+- Store the returned `id` (client identifier) so the agent can re-register subsequently.
+- Include the `status` string (`online`, `maintenance`, etc.) as part of the payload so the Director knows the client state.
+
+### 9.3. Responding to UI-driven capability pushes
+- The Calypso console exposes a `Bacula Clients` page (see the new navigation entry in the web UI) where operators can edit the backup types.
+- When an operator submits a change, the UI calls `POST /api/v1/bacula/clients/{id}/capabilities`. This request is gated by the `bacula-admin` role and records an audit entry via the `bacula_client_capability_history` table.
+- The agent should poll `GET /api/v1/bacula/clients/{id}/pending-update`. The endpoint never expires a pending list and returns the full desired `backup_types`, the operator notes, and who requested the change. Once the agent re-registers and matches the desired list, the pending update is cleared automatically.
+- Each registration (agent push or UI trigger) appends a history row so the console can surface the last few changes for auditing.
+
+### 9.4. Heartbeats and status updates
+- Use `POST /api/v1/bacula/clients/{id}/ping` to refresh the agent's `last_seen` timestamp and propagate `status` changes without altering the capability matrix.
+- If the agent needs to push new metadata (e.g., a new `agent_version` or additional `backup_types`), simply call `POST /api/v1/bacula/clients/register` again with the updated values. The same endpoint handles both initial registration and re-registration, and it clears pending capability pushes once the requested list matches the agent's `backup_types`.
+
+### 9.5. Agent configuration location
+- Store agent settings under `/opt/calypso/conf/bacula/agent.yaml` and keep the JWT token, Calypso API URL, and desired backup types there so the service can re-run after restarts. The installation script should add a systemd service that runs the agent and ensures it restarts on failure.
+