# camp_sysinfo Unix client

Audits a Linux or Unix server (Debian/Devuan, FreeBSD, OPNsense) and sends the results as a YAML file for additional processing by CAMP. This directory is the whole Unix client: a host checks out `^/testing/unix` or `^/stable/unix` (or a tag's `unix/`), or unpacks the tarball built from it, into its install directory. The repository overview, specification, tests and tools are one level up, in `../README.md`.

`sysinfo_client` (the main program) reads your config file, then runs each applicable sensor in `<installdir>/sensors` and `<confdir>/sensors`. Each sensor prints tab-delimited lines which the client merges into one Perl hash, the report, which is converted to YAML (or JSON). The report is then transmitted to another server using the transports stored in `<installdir>/transports` and `<confdir>/transports`.

`<installdir>/*` is designed to be updated, but `<confdir>/*` is NOT modified by updates (unless requested).

## Installation

Installation, upgrade, legacy (v3.7.1) migration and uninstall are described in `installer/README.md`. In short, for a fresh install from a checkout:

```sh
# target directory normally /opt/camp/sysinfo_client (Linux) or /usr/local/opt/camp/sysinfo_client (BSD)
svn co http://svn.dailydata.net/svn/camp_sysinfo_client_3/tags/v3.8.1/unix /opt/camp/sysinfo_client
/opt/camp/sysinfo_client/installer/setup
```

Or configure by hand, starting from `<installdir>/installer/sysinfo_client.conf.template.yaml`.

To change the config later, run `configure`. It opens the config file in `dataserialization/dsEdit` (a YAML/JSON/INI editor, v1.3 or later, kept at a pinned revision by `svn:externals`); parameters are passed through to dsEdit, for example `configure -a 'clientName:Acme' -a 'tags[]:Workstation'` or `configure -d 'tags[]:Workstation'`. `configure --help` shows dsEdit's options. dsEdit picks the format from the file extension (`.yaml`, `.yml`, `.json`, `.ini`) unless you give `-f`; to edit `server.info` (colon-separated, no extension) use `configure -f ini --delimiter ':' /etc/server.info`. Comments in that file are not kept and its keys are rewritten in sorted order.

`setup` is new in v3.8.0, so use it with care. It is designed to be non-destructive, so running it more than once is fine. You can also run the individual scripts in the `installer` directory (see `setup` for the correct order).

## Branches and releases

Development happens on `^/trunk`. A release is a tag (`^/tags/vX.Y.Z`), which never changes. Promotion goes trunk, then tag, then `^/testing`, then `^/stable`: each of `testing` and `stable` is removed and re-created as a copy (`svn rm`, then `svn cp`), the first from the tag and the second from `^/testing` once testing is complete. The permanent beta machines follow `^/testing/unix`; all other svn-based machines follow `^/stable/unix`. Branches and tags hold the whole repository; a Unix host works only on their `unix/` directory. A machine moves to a branch with `svn switch --ignore-ancestry ^/testing/unix` (or `^/stable/unix`), and `sysinfo_update` then tracks it with `svn update`.

The tarball at Daily Data is built from `^/stable`. There is also a `^/testing` tarball available if desired.

## Resulting structure (default Linux install)

| Path | Purpose |
|---|---|
| `/opt/camp/sysinfo_client` | primary script (`sysinfo_client`) and libraries |
| `/opt/camp/sysinfo_client/sensors` | scripts to be run to gather data |
| `/opt/camp/sysinfo_client/transports` | scripts that send the results to another machine |
| `/etc/camp/sysinfo_client` | configuration file (`sysinfo_client.yaml`) |
| `/etc/camp/sysinfo_client/sensors` | optional location for local sensors |
| `/etc/camp/sysinfo_client/transports` | optional location for local transports |
| `/etc/cron.daily/sysinfo_client` | soft link to the executable |
| `/etc/server.info` | optional file to identify location, owner, etc. (see `installer/server.info.sample`) |

FreeBSD moves `/opt` to `/usr/local/opt` and `/etc` to `/usr/local/etc`, with the schedule link going into `/usr/local/etc/periodic/daily`.

OPNsense is basic FreeBSD, except that scheduling is done by placing an action file in `/usr/local/opnsense/service/conf/actions.d`.

Hosts that still run v3.7.1 use the dash names (`/opt/camp/sysinfo-client`, `/etc/camp/sysinfo-client`, `modules`, `scripts`); `installer/setup` migrates them.

## Operation

When `sysinfo_client` is called:

1. Load and verify the config file, creating a structure in memory (hash). Values in `server.info` override the config file for the run.
2. Run every sensor with the executable flag set in `<installdir>/sensors`, then in `<confdir>/sensors`.
3. Attempt each transport defined in the config, from the lowest key number to the highest, until one succeeds. If none does, the report is printed to STDOUT.

## Sensors

Sensors are scripts in `sensors/`, run by the client; the contract for writing one, including its exit codes, is in `sensors/Documentation/README.md`. In short: a sensor is called with one parameter, its own directory; it must fail gracefully, identifying when it is not applicable to the machine (for example, a FreeBSD machine must not run Linux-specific commands); and it prints zero or more tab-delimited lines of a category, a key path, and a value.

## Transports

Transports are described in `transports/README.md`.

## Documentation

- `../Documentation/Spec.md`: the specification of the client (report format, sensors, configuration, install and upgrade).
- `sensors/Documentation/README.md`: how to write a sensor, with a template.
- `transports/README.md`: how to write a transport, and the transports included.
- `installer/README.md`: install, upgrade and uninstall.
- `../tools/README.md`: the helper tools (release builder, report comparison).

## Tests

Run the test suite from the repository root (no root, no hardware needed; the Unix tests are in `t/`, the Windows ones in `t/windows/`):

```sh
prove t/
```