# Qualys Cloud Agent Upgrade Script (Solaris)

## Project Overview
`qualys-cloud-agent-upgrade.sh` upgrades the Qualys Cloud Agent on **Solaris SPARC** by migrating from the legacy **SVR4 package** (`.pkg`, package name `QLYSlxag`) to the newer **IPS package** (`.p5p`, package name `qualys-cloud-agent`).

This script is designed to perform the end-to-end upgrade in a single run while preserving the **minimum required state**:

- **Backed up:** `qualys-cloud-agent.conf` (agent configuration)
- **Retained by design:** `hostid` (agent UUID), which is not removed during uninstall

The script also validates your agent configuration before proceeding to help prevent upgrades that would result in an unregistered or misconfigured agent.

## Prerequisites

### Operating System / Platform
- **Solaris (SPARC)**
- SVR4 Qualys agent already installed (package name **`QLYSlxag`**)
- IPS tooling available (`pkg`) for installing the new agent
- SMF present for service control (`svcs`, `svcadm`)

### Required Commands
The script expects the following standard Solaris utilities to be available in:

- `/usr/bin`
- `/usr/sbin`

Used commands include:

- **`pkginfo`**, **`pkgrm`** (SVR4 package detection/removal)
- **`pkg`** (IPS package install / verification)
- **`svcs`**, **`svcadm`** (SMF service control)
- **`cp`**, **`mkdir`**, **`rm`**, **`grep`**, **`cut`**, **`awk`**, **`date`**, **`id`**

### Files / Paths Expected
- Existing agent install directory: `/opt/qualys/cloud-agent`
- Agent configuration file: `/etc/opt/qualys/cloud-agent/qualys-cloud-agent.conf`
- Agent UUID file: `/etc/qualys/hostid`
- New IPS package file (`.p5p`):
  - Default: `/tmp/qualys/QualysCloudAgent.p5p`
  - Or pass a custom path as an argument

## Installation & Permissions

1. Download / copy the script to your target Solaris host.

2. Make it executable:

```sh
chmod +x qualys-cloud-agent-upgrade.sh
```

3. Run as **root** (required). For example:

```sh
sudo ./qualys-cloud-agent-upgrade.sh
```

## Usage Guide

### Help

```sh
./qualys-cloud-agent-upgrade.sh --help
```

### Quick Start (default package path)
Uses the default IPS package path:

- `/tmp/qualys/QualysCloudAgent.p5p`

```sh
sudo ./qualys-cloud-agent-upgrade.sh
```

### Use a custom `.p5p` package path

```sh
sudo ./qualys-cloud-agent-upgrade.sh /path/to/QualysCloudAgent.p5p
```

### What the script does (high-level workflow)

- **Step 1/6:** Preflight checks
  - Must be run as `root`
  - Confirms old SVR4 package `QLYSlxag` is installed
  - Confirms `/opt/qualys/cloud-agent` exists
  - Confirms `/etc/qualys/hostid` exists and logs the UUID
- **Step 2/6:** Backup config
  - Copies `qualys-cloud-agent.conf` to `/tmp/qualys/qualys-agent-upgrade-backup/`
  - Validates `ActivationId` and `CustomerId` are present and not all-zeros
- **Step 3/6:** Stop and uninstall old agent
  - Disables SMF service `svc:/application/qualys-cloud-agent:default` (best effort)
  - Uninstalls using `qagent_uninstall.sh` if present, otherwise `pkgrm`
- **Step 4/6:** Install new IPS agent
  - Installs from your `.p5p` using `pkg install --no-refresh -g <p5p_path> qualys-cloud-agent`
  - Verifies installation with `pkg list`
- **Step 5/6:** Restore config
  - Restores `qualys-cloud-agent.conf` back to `/etc/opt/qualys/cloud-agent/`
- **Step 6/6:** Re-apply config/permissions and start service
  - Calls `/opt/qualys/cloud-agent/bin/qualys-cloud-agent.sh` with a filtered allowlist of config parameters
  - Enables SMF service if not already online
  - Cleans up the backup directory on successful start

## Safety / Error Handling

### Logging
- The script logs to a timestamped file:
  - **`/tmp/qualys/qualys-agent-upgradeYYYYMMDD_HHMMSS.log`**
- Most command output (install/uninstall/service ops) is redirected into this log.

### Fail-fast behavior
The script will **exit immediately** on critical failures such as:

- Not running as root
- Old SVR4 package not detected
- Missing required directories/files (agent install dir, `hostid`, config)
- Invalid config (`ActivationId` / `CustomerId` missing/empty/all-zeros)
- Uninstall failure
- IPS install failure
- Unable to restore backed-up config

### Best-effort behavior
Some steps are non-fatal by design:

- If stopping the SMF service fails gracefully, the script logs a warning and continues.
- If the post-install configuration script (`qualys-cloud-agent.sh`) returns a non-zero exit code, the script logs a warning and continues.

### Backup behavior
- Backup location: `/tmp/qualys/qualys-agent-upgrade-backup/`
- The backup directory is **removed automatically** after the service start step.
- If you want to keep the backup for auditing, copy it aside before the script completes.

## Troubleshooting

### Upgrade completed with issues
If the script reports issues at the end, review:

- **Log file:** printed on-screen, also under `/tmp/qualys/qualys-agent-upgrade*.log`
- **Service state:**

```sh
svcs -l svc:/application/qualys-cloud-agent:default
```

### Common causes
- Wrong/missing `.p5p` path
- Invalid or placeholder `ActivationId` / `CustomerId`
- IPS repository/package incompatibility on the target Solaris version

## Notes
- This script unsets common environment variables and sets a restricted `PATH` (`/usr/bin:/usr/sbin`) for predictable execution.
- The configuration allowlist is enforced when re-applying settings to avoid passing unsupported keys to `qualys-cloud-agent.sh`.