# sysinfo client: system overview

This is the overview of the whole sysinfo system and the starting point for every other document. The detail lives next to the code it describes; the links in each section lead there. The report format is in [ReportFormat.md](ReportFormat.md) and the Windows client design in [WindowsClient.md](WindowsClient.md).

## What it is

A sysinfo client runs once a day on a server or workstation, collects facts about the machine with small programs called sensors, builds one report (YAML on Unix, JSON on Windows) and sends it to the CAMP server through one or more transports. CAMP matches the report to a device and stores it. There are two clients that share one report contract: the Unix client (Perl) and the Windows client (PowerShell 5.1). Neither is a port of the other.

Platforms: Debian, Devuan and MX Linux, FreeBSD and OPNsense (Unix client); Windows 10, Windows Server 2016 and later (Windows client). RPM-based distributions and IPFire are not supported.

Versions: the client version (`v3.8.1`) is in `unix/SYSTEM_VERSION` and `unix/VERSION.md`; the report format has its own data version (`v3.8.0`), which changes only when the report changes. Both are shown by `sysinfo_client --version`. The change history is in the CHANGELOG files (`CHANGELOG.md`, `unix/CHANGELOG.md`, `windows/CHANGELOG.md`).

## Repository layout

| Path | Contents | Documentation |
|---|---|---|
| `unix/` | The Unix client: `sysinfo_client`, `sysinfoconf.pm`, `library.pm`, `sensors/`, `transports/`, `installer/`, `configure`, `sysinfo_update`, `dataserialization/` | [unix/README.md](../unix/README.md) |
| `unix/sensors/` | One executable per sensor, plus the template | [sensors/Documentation/README.md](../unix/sensors/Documentation/README.md) |
| `unix/transports/` | Scripts that deliver the report: `upload_http`, `send_local_smtp`, `send_auth_smtp`, `save_local` | [transports/README.md](../unix/transports/README.md) |
| `unix/installer/` | `setup`, `uninstall`, `mergeconfig`, `validateDependencies`, `determineOS`, `permissions` | [installer/README.md](../unix/installer/README.md) |
| `windows/` | The Windows client: `sysinfo_client.ps1`, `install.ps1`, `sysinfo_update.ps1`, `dsEdit.ps1`, `configure.ps1`, sensors, `upload_http.ps1` | [windows/README.md](../windows/README.md), [WindowsClient.md](WindowsClient.md) |
| `tools/` | `make_release` (Unix tarball and Windows zip), `compare_reports` | [tools/README.md](../tools/README.md) |
| `t/` | Tests (`t/*.t` for Unix, `t/windows/` for Windows) and `t/fixtures/` (captured command output) | see Tests below |
| `server/` | Server-side upload script `upload_file.php` and `test_upload.html` (not a transport) | |
| `portable/` | A planned stand-alone collector for a bootable thumb drive (bug 214) | |
| `reference/` | A frozen copy of v3.7.1, kept for comparison | |

A Unix host installs only `unix/`, a Windows host only `windows/`. The top-level [README.md](../README.md) covers release channels, branches and how to install.

In the Unix sections below a path such as `sensors/` or `installer/setup` is relative to `unix/` (the install directory).

## How a run works

1. The client (`sysinfo_client`, run by cron or periodic as root) reads its config and `server.info`.
2. It runs every sensor as a separate process. Each sensor prints tab-separated fact lines on STDOUT and exits with a code that says whether it worked.
3. The client merges the facts into one report and adds its own sections (`report`, `system`, `sysinfo`, its version under `software`).
4. It calls the transports in numeric order until one returns success. If none does it prints the report on STDOUT, so cron mails it.

No sensor or transport can stop the report: a failure, hang or garbage output is recorded in the report's `sysinfo` section and the run continues. In test mode (`-t`) the report is written to `/tmp/sysinfo.testing.yaml` (Windows: `%TEMP%\sysinfo.testing.json`) and no transport is called.

## Report

The report is YAML (Unix) or JSON (Windows). Unix reports begin with the line `#sysinfo: v3.8.0 YAML`. Sections: `report`, `system`, `operatingsystem`, `network`, `diskinfo`, `attributes`, `pci`, `software`, `xen` (guests), plus `identity`, `storage`, `sysinfo`, `havirt_node` and `havirt_domain`. The existing CAMP importer reads the older sections and ignores unknown top-level sections, so sections are only ever added at the top level; names, nesting and types inside older sections do not change. Full definitions: [ReportFormat.md](ReportFormat.md).

## Sensors

A sensor is an executable in a directory listed in `moduleDirs` (default `<bindir>/sensors`), owned by root with mode 0700 or stricter, and named with letters, digits and underscores. Naming: `<os>_<job>` runs on one OS only; `all_<job>` runs on every supported OS. The exit-code contract, the status each code produces and the template for new sensors are in [sensors/Documentation/README.md](../unix/sensors/Documentation/README.md).

How the client runs a sensor:

- It runs `<dir>/<sensor> <dir>/` as a child with STDIN on `/dev/null`, STDOUT and STDERR captured separately, in an environment that carries the identity values (`SYSINFO_CONFIGURED_UUID`, `SYSINFO_CONFIGURED_SERIAL`, `SYSINFO_SERVERINFO_UUID`, `SYSINFO_SERVERINFO_SERIAL`) and `SYSINFO_PERIODIC=1` on a periodic run.
- After `sensorTimeout` seconds (default 120) it kills the sensor's process group (TERM, then KILL after 5 seconds) and records `timeout`.
- STDOUT is parsed only when the sensor exits 0.

### Sensor line format

One fact per line: `category<TAB>key...<TAB>value`, two to six fields, split on `/ *\t */`. The last field is the value and the others are the key path. Blank lines are ignored. Nested keys are created as needed, key `0` is valid, and a later line with the same path replaces an earlier scalar. A line is rejected (counted, and the first one reported in the sensor's status message) if it has fewer than two fields, an empty key segment, or would descend through a scalar or replace a map with a scalar. Values are stored exactly as printed; UTF-8 in, UTF-8 out. Nothing is evaluated.

### Periodic sensors

`-p` marks a run as periodic: the client creates `/tmp/sysinfo.firstrun` at the start and removes it at the end of every run. A gated sensor (only `all_smart`, monthly) is due when that file exists or it is the first day of the period (`library::checkDate`); otherwise it exits 3 (`not_due`).

### Sensor list

| Sensor | Emits | OS | When |
|---|---|---|---|
| `linux_system`, `freebsd_system` | `system.last_boot`, `system.uptime`, `operatingsystem.*` | Linux, FreeBSD | daily |
| `linux_network`, `freebsd_network` | `network.<interface>` | Linux, FreeBSD | daily |
| `all_ipmi` | `network.ipmi`, `system.Power *`; exit 2 without `/dev/ipmi*` | all | daily |
| `linux_pci`, `freebsd_pci` | `pci` | Linux, FreeBSD | daily |
| `linux_dpkg_software`, `freebsd_pkg_software` | `software.<package>` | Linux, FreeBSD | daily |
| `linux_virtual` | `xen.virtual.<guest>` (Xen and libvirt guests) | Linux | daily |
| `linux_havirt` | `havirt_node`, `havirt_domain` (libvirt clusters managed with `havirt`) | Linux | daily |
| `all_filesystems` | `diskinfo` from `df` | all | daily |
| `linux_storage`, `freebsd_storage` | `storage.disks`, `storage.partitions` | Linux, FreeBSD | daily |
| `linux_mdadm`, `linux_lvm`, `all_zfs` | `diskinfo` and `storage.md`, `storage.lvm`, `storage.zfs` | Linux; all | daily |
| `all_smart` | `attributes`, `storage.disks.*.smart` | all | monthly |
| `linux_identity`, `freebsd_identity` | `identity` | Linux, FreeBSD | daily |

Shared code is in `library.pm` (placeholder and UUID rules, disk discovery, storage helpers, `runCommand`). Parsing lives in functions that take text and return lines, so tests can feed them captured fixtures.

## Configuration

The client reads one config file (YAML on Unix, JSON on Windows), searched as: the `--config` path, then `sysinfo_client.yaml` in `/etc/camp/sysinfo_client` and `/usr/local/etc/camp/sysinfo_client` (Windows: `%ProgramData%\camp\sysinfo_client\sysinfo_client.json`). The file is read on every run. Edit it with `configure`, a wrapper around `dataserialization/dsEdit` (Unix) or `configure.ps1` (Windows); see the READMEs.

### Configuration keys

| Key | Meaning | Copied into `system`? |
|---|---|---|
| `clientName` | required; the run stops if it is empty after `server.info` | yes |
| `hostname` | default `hostname -f` | yes |
| `serialNumber`, `UUID` | identity as configured at install; may be blank | yes |
| `location`, `os_type`, `tags` (list) | descriptive | yes |
| `TESTING` | test mode | yes |
| `postRunScript` | script run with the config path after the run | yes |
| `outputType` | `yaml` (default) or `json` (Unix only) | yes, if in the file |
| `logging` | `log type` (`cache`, `file` or `syslog`), `log level` (0 to 5), `log path` | no |
| `moduleDirs`, `scriptDirs` | lists of sensor and transport directories | no |
| `transports` | map of priority to `{name, sendScript, ...}` | no |
| `sensorTimeout` | seconds, default 120 | no |
| `update` | `{method: auto\|tarball\|svn, url, seed_url, sha256_url}` | no |

Any other key in the file is copied into `system`. There are no built-in URLs anywhere: the release locations come from the seed file or the config and nowhere else.

### server.info

`/etc/server.info` or `/usr/local/etc/server.info` (Windows: `%ProgramData%\camp\server.info`) is a per-host file of `Key: Value` lines, split on the first colon, with case-insensitive keys; `#` lines and unknown keys are ignored. It is read on every run and overrides the config for that run only; the client never rewrites it. Mapping: `owner` to `clientName`, `hostname`, `serial` to `serialNumber`, `uuid` to `UUID`, `location`, `os_type`, `tags` (comma separated). An empty value does not override. The installer's `mergeconfig` reads it with the same reader.

Precedence: command line, then `server.info`, then the config file, then defaults. The client name, location and tags belong to the host (in `server.info` or the config), never in the site-wide seed.

### Command line

`--version`, `--help`, `-v` (repeatable), `-f/--config`, `--configtype`, `-o/--outputType`, `-p/--periodic`, `-t/--test`. A real run must be root (Windows: elevated); `-t` does not need it.

## Transports

A transport is a Perl script (Windows: a `.ps1`) in a directory listed in `scriptDirs` that defines `doit($parameters, $report)` and returns 1 on success. The client walks `transports` in numeric order of its keys, stops at the first success, logs each failure and falls back to STDOUT. A missing transport script is logged and skipped. The parameters are the transport's own config entry plus the globals `upload_type`, `data version`, `report date`, `client name`, `host name`, `serial number` and `UUID`; the literal tokens `$hostname`, `$reportDate` and `$configuration{'clientName'}` (and the like) are substituted without `eval`.

| Transport | Delivers by |
|---|---|
| `upload_http` | multipart HTTP POST to a CGI script (the sample receiver is `server/upload_file.php`) |
| `send_local_smtp` | the local mail system: pipes a message to the host's sendmail-compatible program, no credentials |
| `send_auth_smtp` | `Net::SMTP` with optional TLS and authentication, for hosts without a usable local mail system |
| `save_local` | a file in a local directory; put it last so a copy is kept when everything else fails |

Parameters and return codes: [transports/README.md](../unix/transports/README.md). Windows has `upload_http.ps1` only.

## Installing and updating

Paths:

| | Debian, Devuan | FreeBSD | OPNsense | Windows |
|---|---|---|---|---|
| program directory | `/opt/camp/sysinfo_client` | `/usr/local/opt/camp/sysinfo_client` | same as FreeBSD | `%ProgramFiles%\camp\sysinfo_client` |
| config directory | `/etc/camp/sysinfo_client` | `/usr/local/etc/camp/sysinfo_client` | same as FreeBSD | `%ProgramData%\camp\sysinfo_client` |
| schedule | `/etc/cron.daily/sysinfo_client` (symlink) | `/usr/local/etc/periodic/daily/sysinfo_client` (symlink) | `actions_sysinfo.conf` for `configd`; the cron job is enabled once in the web UI | Task Scheduler task `\camp\sysinfo_client`, daily, as SYSTEM |

- **Install (Unix):** `installer/setup` detects the OS (OPNsense if `/conf/config.xml` exists, else FreeBSD, else Debian-family), installs `YAML::Tiny` if missing (package manager, then `cpanm`, then `cpan`), installs or migrates the files, creates the config (from the seed when one is given, from `server.info` and live DMI values otherwise), sets permissions (root, 0700 for executables), writes the schedule entry and checks that the client runs. It is idempotent and ends with `RESULT: ok|nochange|fail <version> <message>`. Details: [installer/README.md](../unix/installer/README.md).
- **Update (Unix):** `sysinfo_update` either runs `svn update` or `svn switch` in the program directory, or downloads the release tarball, checks it against its `.sha256`, and runs `installer/setup --quiet --upgrade`. It first fetches the small checksum file and skips the download when it equals the checksum recorded at the last install (`--force` overrides). The previous install is kept as `<bindir>.previous` and restored if the new one fails its check. It is not scheduled by default.
- **Install and update (Windows):** `install.ps1` (elevated) and `sysinfo_update.ps1`, from the release zip. See [windows/README.md](../windows/README.md).
- **Release:** `tools/make_release <version>` builds the Unix tarball from `unix/` and the Windows zip from `windows/`, each with a `.sha256`. Only `unix/` and `windows/` ship. Release channels and branches: [README.md](../README.md).
- **Uninstall:** `installer/uninstall [--keep-config]`; Windows `install.ps1 -Uninstall [-Purge]`.

## Windows client

A separate implementation in PowerShell 5.1: the same report contract, sensor line format, config key names, `server.info` format and transport parameters, and nothing else. Its sensors are `windows_identity`, `windows_system`, `windows_storage`, `windows_network` and `windows_software`; there is no PCI, guest, SMART or e-mail support. Design, paths, installer, updater and config editor: [WindowsClient.md](WindowsClient.md).

## Tests

- Unix: `prove -I. t` from the repository root (no root, no hardware). The tests cover the parser, sensor runtime and exit codes, config and `server.info`, transports, the installer and updater (in a temporary root), `configure`, and every sensor's parsing against captured fixtures.
- Windows: `pwsh -NoProfile -File t/windows/run_tests.ps1` (Windows checks are skipped on Linux) or the same script under Windows PowerShell 5.1 on a Windows host.
- Fixtures: `t/fixtures/<role>/` holds real command output, named by role and never by hostname (`linux-md-lvm`, `freebsd-zfs`, `linux-vm`, `nvme`, `opnsense`, `placeholder-uuid`, `havirt-node`). Each of the first three also has a v3.7.1 report for comparison.
- `tools/compare_reports OLD NEW` lists key paths missing from NEW, type changes and value differences outside the documented list; [tools/README.md](../tools/README.md).

## Coding conventions

All Perl follows `CommonProjectStandards`: camelCase names, a header on every file, a comment block above every sub, 3-space indentation, no object system, `Test::More` tests. Executables have no `.pl` suffix and start `#!/usr/bin/env perl`. Perl 5.24 or newer with core modules plus `YAML::Tiny`; `JSON::PP` is core. Values from the config, `server.info` or sensors never reach a shell (list-form `system` and `open`) and are never evaluated. Each directory with executables has a README with its purpose, inventory and usage. Documentation must not contain real hostnames or client names.
