# spvirit-scry

[![Crates.io](https://img.shields.io/crates/v/spvirit-scry)](https://crates.io/crates/spvirit-scry)
[![License](https://img.shields.io/crates/l/spvirit-scry)](LICENSE)

EPICS PVAccess packet capture, decoding, and real-time traffic monitoring.

## Overview

**spvirit-scry** captures live PVAccess network traffic and decodes it in real time. It tracks connection state (channels, operations, PV names) and provides a TUI dashboard or InfluxDB/Loki export for production monitoring.

### Binaries

- `spvirit-scry` — CLI/TUI packet capture with real-time traffic statistics.
- `spvirit-scry_influx_collector` — packet capture with InfluxDB and Loki export.

### Related crates

This crate is part of the [spvirit](https://github.com/ISISNeutronMuon/spvirit) project:

| Crate | Description |
|-------|-------------|
| [`spvirit-codec`](https://crates.io/crates/spvirit-codec) | PVAccess wire-format codec and connection state tracking |
| [`spvirit-tools`](https://crates.io/crates/spvirit-tools) | PVA client/server tools (`pvget`, `pvput`, `pvmonitor`, `pvinfo`, `pvlist`, `pvexplore`, `pvsearch`, `pva_server`, etc.) |
| [`spvirit-types`](https://crates.io/crates/spvirit-types) | Shared Normative Type data model |

## Features

- Live packet capture with rate and request-type statistics.
- TUI view for interactive monitoring.
- PVA connection state tracking — channels, operations, PV name resolution.
- Filtering and tracking options (`--exclude-cmds`, `--tracked-only`).
- InfluxDB and Loki export via the collector binary.

## Requirements

- **Rust** toolchain (edition 2024).
- **Linux**: `libpcap-dev` installed and available.
- **Windows**: [Npcap](https://npcap.com/) runtime and the [Npcap SDK](https://npcap.com/#download). The build script auto-detects the SDK, or set `NPCAP_SDK` to the extracted SDK root.
- **Linux**: Packet capture requires either `sudo` or `CAP_NET_RAW` capability (see below).
- **Windows**: Run as Administrator, or configure Npcap to allow non-admin capture during install.

### Packet capture without sudo (Linux)

After installing, grant the binary the `CAP_NET_RAW` capability so it can capture without `sudo`:

```bash
sudo setcap cap_net_raw=eip $(which spvirit-scry)
sudo setcap cap_net_raw=eip $(which spvirit-scry_influx_collector)
```

This only needs to be done once per install (re-run after `cargo install` upgrades the binary).

## Install

### From crates.io

```bash
cargo install spvirit-scry
```

### From source

```bash
git clone https://github.com/ISISNeutronMuon/spvirit-scry.git
cd spvirit-scry
cargo build --release
```

Output binaries:
- `target/release/spvirit-scry`
- `target/release/spvirit-scry_influx_collector`

### Npcap SDK on Windows

The build script searches these locations automatically:
1. `NPCAP_SDK` environment variable (explicit override)
2. `npcap-sdk/` relative to the project root
3. `C:\npcap\`, `C:\npcap-sdk\`, `C:\Program Files\Npcap\` (including versioned subdirs)
4. `%LOCALAPPDATA%\npcap-sdk\`

## Usage

### `spvirit-scry`

```bash
spvirit-scry --device eth0 --tui
```

Options:
- `--device` / `-i`: network interface to capture from.
- `--integration-time` / `-t`: stats integration period in seconds.
- `--buffer-size` / `-b`: capture buffer size (100–50000).
- `--resolve` / `-r`: resolve IP addresses.
- `--tui`: enable TUI.
- `--debug` / `-d`: debug logging.
- `--version` / `-v`: print version and exit.
- `--exclude-cmds` / `-x`: comma-separated PVA commands to exclude (e.g. `PUT,MONITOR`).
- `--pva-ttl`: PVA channel state TTL in seconds (default 300).
- `--pva-max-channels`: max PVA channels to track per connection (default 40000).
- `--tracked-only`: only show packets for tracked connections.

### `spvirit-scry_influx_collector`

```bash
spvirit-scry_influx_collector --device eth0 --config-file influxdb_config.toml
```

Options:
- `--device` / `-i`: network interface to capture from.
- `--integration-time` / `-t`: stats integration period in seconds.
- `--buffer-size` / `-b`: capture buffer size (100–50000).
- `--resolve` / `-r`: resolve IP addresses.
- `--debug` / `-d`: debug logging.
- `--version` / `-v`: print version and exit.
- `--config-file` / `-c`: path to InfluxDB config file.

## Configuration

The collector reads a TOML configuration file. Required keys:

```toml
url = "http://localhost:8086"
token = "your-token"
org = "your-org"
bucket = "your-bucket"
loki_url = "http://localhost:3100"
```

> **Note:** Do not commit secrets (tokens) to the repository. Use environment-specific secret management.

## Troubleshooting

- **No packets captured**: verify the device name (`--device`) and ensure capture permissions (`sudo` or NIC capabilities).
- **InfluxDB errors**: verify `url`, `token`, `org`, and `bucket` in the config file and confirm network connectivity.
- **Buffer size errors**: `--buffer-size` must be between 100 and 50000.
- **Diagnostics**: use `--version` to confirm build version, `--debug` for verbose logging.

## License

Licensed under [BSD-3-Clause](LICENSE).
