PEERYX FLOW COLLECTOR 1.1.0
Installation and operations reference

PURPOSE AND SCOPE
Free software for Peeryx customers who want on-demand IPv4 DDoS diversion.
It receives flow measurements and controls a dedicated iBGP signaling session.
It never forwards or scrubs customer packets. The Peeryx service performs
traffic cleaning. A server port of 1 Gbps does not cap protected bandwidth.
Always-on Peeryx protection does not require this collector.

Platforms: Debian 12/13 and Ubuntu 24.04; Linux x86-64 or ARM64; systemd.
Starting recommendation: two CPU cores (small Xeon or equivalent), 8 GB RAM,
20 GB free disk, 1 GbE. Validate export load and dropped-sample counters.
Use a dedicated host, a synchronized clock, and sudo/root for installation.
A collector serves one service, one datacenter and one router/exporter.
Deploy additional collectors for other locations; do not count the same
physical traffic on overlapping collectors or both physical and VLAN inputs.

INSTALL
Prepare a minimal Debian 13 (recommended), Debian 12, or Ubuntu Server 24.04
LTS installation. Other releases, Windows/macOS and containers are not supported.
Use a dedicated VM/server, a static IPv4 on the directly connected router LAN,
and synchronized time. Login by SSH as a sudo user; omit sudo when already root.
  cat /etc/os-release
  uname -m
  ip -br -4 address
  timedatectl status
  sudo apt-get update
  sudo apt-get install -y curl ca-certificates
  curl --proto '=https' --tlsv1.2 -fSLo peeryx-install.sh https://peeryx.com/downloads/flow-collector/1.1.0/install.sh
  sudo bash peeryx-install.sh --check
  sudo bash peeryx-install.sh
  sudo peeryx-collector setup
  sudo peeryx-collector pair
  sudo peeryx-collector doctor
  sudo peeryx-collector status
The setup assistant starts in observation. Enrollment alone does not activate
routing changes. The installer verifies the RSA/SHA-256 release manifest and
package checksum. It does not modify existing router settings, firewall rules,
forwarding settings, /etc/bird/bird.conf, or an existing routing service.

SUPPLY CHAIN AND OFFLINE INSTALLATION
The installer embeds the release public key. Download over HTTPS from Peeryx,
inspect it, then execute it; do not add a pairing code to a shell command.
Download SHA256SUMS, SHA256SUMS.sig and the architecture-specific archive to
a local directory for: sudo bash peeryx-install.sh --bundle /path/to/bundle
Required system packages must still be available from configured repositories.
Keep the release public key/manifest for your own audit. Packages contain the
license and third-party notices. No telemetry packet capture is installed.

NETWORK ACCESS
- Inbound UDP only from the configured exporter. Defaults: sFlow 6343,
  NetStream 2055, IPFIX 4739. Restrict sources in your own firewall.
- TCP 179 only between the collector and its directly connected router.
- Outbound HTTPS TCP 443 to peeryx.com (enrollment and health/evidence).
- DNS, time synchronization and package-repository access as appropriate.
The software neither opens firewall ports automatically nor exposes a web UI
on the customer server. Use the authenticated Peeryx service page.

MEASUREMENT CONTRACT
Supported: sFlow v5 standard and expanded flow samples, sampled Ethernet
headers (up to two VLAN tags), raw IPv4 headers and sampled IPv4 summaries;
NetFlow/NetStream v5/v9 and IPFIX IPv4 flow records.
Only configured inbound ifIndexes count. sFlow data-source and input interface
must identify the same incoming interface. The sFlow agent IPv4 address must
match the UDP source; do not NAT exports or aggregate unidentified exporters.
The per-sample sFlow sampling rate is applied once. For NetFlow/IPFIX, confirm
sampling with router counters and use sampling_multiplier only when exported
packet/byte counts have not already been expanded. Never guess the multiplier.
NetFlow/IPFIX fields required: destination IPv4, packets, octets, protocol,
input ifIndex, timestamps, and TCP flags for flag-specific thresholds.
Export active flows within one second. Export age and flow duration are
bounded to four seconds; long/stale flows make detection unready. Devices that
cannot export sufficiently fresh records need sFlow or another timely exporter
for this detection mode. A typical one-minute NetStream timeout is not enough
for reliable sub-second rate detection of long-lived flows.
Sequence gaps, sample drops, decoding errors and stale exports block new
triggers. They are diagnostic faults, not proof of an attack ending.
Rates are estimates from sampled data, not exact wire counters. TCP flags in
aggregated flows are unions: SYN/ACK/RST estimates are conservative lower bounds.
Encrypted application attacks and low-volume application abuse require other
protection signals. No rate detector can guarantee zero false positives.

BGP ROUTER CONTRACT (PREPARE WITH PEERYX)
The collector's local ASN equals the customer router ASN. Use one directly
connected iBGP neighbor. Export only authorized original customer public /24s
to it, preserving the original AS path, origin, MED and delivery next hop.
Do not export a full Internet table. Import limit is 4,096 routes.
The collector learns new /24s from this feed within authorized_aggregates.
There is no fixed ten-prefix list. The router's own admission/export filters
and Peeryx authorization must also accept a new prefix. New ownership ranges
require review. V1 does not auto-subdivide aggregates or support IPv6 diversion.

The configurable 16-bit signal ASN defaults to 65000. Two standard communities
are used: SIGNAL_ASN:65282 (announce) and SIGNAL_ASN:65283 (hard diversion).
For a 32-bit customer ASN, use an agreed separate 16-bit signal namespace.
1. Accept signals ONLY from the dedicated collector neighbor, ONLY for the
   approved customer prefixes, with the agreed signaling communities.
2. Prefer the signal in BGP so export policies see it. Preserve the original
   customer delivery next hop for downstream BGP prefixes. For locally
   originated networks, validate real Static/Direct or more-specific delivery
   routes before authorizing the Peeryx tunnel neighbor as the control next hop.
   A discard aggregate alone is NOT proof of working customer delivery.
3. SOFT: announce the affected prefix to Peeryx while keeping existing local
   upstream/peering announcements. On the Peeryx export, set the next hop to
   the customer's address on the correct GRE and apply the agreed attributes.
4. HARD: withdraw this exact prefix from every relevant non-Peeryx ingress
   provider and peering exit. Keep it announced to Peeryx. Do not break default
   routes provided to downstream customers or routes carrying clean traffic.
5. Never reflect the marked signal back into the original collector feed.
6. Removing HARD must restore ordinary provider announcements before removing
   SOFT. Preserve normal per-provider export policy behavior and rejection.
7. Validate separate backup next hops and independent route originators.
   A second router originating the same prefix can keep attracting traffic.

These are semantics, not a vendor-neutral pasteable router configuration.
Peeryx prepares the exact attachment for the router model and existing policy.
A route-policy replacement can affect unrelated networks if applied blindly.
The software does not log in to or write configurations on customer routers.

AUTOMATIC MODE AND RECOVERY
Start with observation and calibrate thresholds against normal busy-hour load.
Default protocol PPS values: UDP 500000, TCP 800000, SYN 70000, ACK 800000,
SYNACK 70000, RST 70000, ICMP 20000, GRE 800000, IPIP 800000, other 200000.
These are starting values, not universal attack definitions. threshold_pps=0
means there is no competing total PPS threshold. Optional per-prefix
prefix_thresholds_bps overrides are exclusive and aggregate every protocol.
Example: "prefix_thresholds_bps": {"YOUR.PUBLIC.PREFIX.0/24": 4000000000}
Do not paste the placeholder: use an actual approved canonical public /24.

Detection uses a one-second rolling estimate, evaluated every 250 ms, with
four distinct over-threshold windows required. Repeated samples do not count
as separate trigger windows. Normal traffic may exceed defaults; review them.

Provider evidence is a mandatory independent gate. A current Peeryx BGP/path
observation is required before SOFT. HARD is only emitted after independent
confirmation of protection, external advertisement and correct clean delivery.
At most 256 prefixes can be in an active diversion simultaneously.
Minimum hold is 1,200 seconds after confirmed diversion. Release additionally
requires 120 seconds of fresh, independent attack-clear history and local
telemetry. Restoring local providers precedes SOFT withdrawal by 120 seconds.
Unconfirmed SOFT times out after 120 seconds. Provider visibility missing for
60 seconds causes controlled recovery even within the normal minimum hold;
availability of the delivery path takes priority over the timer.

After the controlled diversion/connectivity/recovery test and operator
commissioning, use sudo peeryx-collector arm. It requires current diagnostics,
a service-specific approval and approved ranges, followed by typing ENABLE.
Merely installing, pairing, or observing high traffic cannot activate it.

THRESHOLD SETTINGS (1.1.0)
The service page contains a translated profile builder. This is an editable
starting profile, not a display of current collector settings. The resulting
peeryx-thresholds.json contains thresholds and duration only; no credentials.
Choose one unit per enabled rule: packets per second (pps), or decimal Gbit/s.
1 Gbit/s = 1,000,000,000 bits/s. Rates count estimated IPv4 octets, not Ethernet
framing overhead. Destination IPs and selected ingress interfaces are combined
per authorized /24. Any enabled rule can trigger after four distinct qualifying
windows. TCP/UDP/ICMP/GRE/IPIP/Other can use either unit. Total L3 combines all
IPv4 protocols once. Other excludes TCP, UDP, ICMP, GRE and IPIP.
Leave Total L3 off if you want protocol thresholds only. A lower total limit
will take effect before a higher individual protocol limit. Advanced TCP flag
rules SYN/ACK/SYNACK/RST are pps-only and independently trigger. The portal
profile starts with these flag rules disabled; setup's defaults include them.
Always review the full imported profile before confirming APPLY.

Copy peeryx-thresholds.json to your server with SCP/SFTP. From its directory:
  sudo peeryx-collector observe
  sudo peeryx-collector settings --file ./peeryx-thresholds.json
  sudo peeryx-collector settings --show
  sudo peeryx-collector doctor
  sudo peeryx-collector arm
Only run arm after your service-specific routing validation. Observe refuses
while a diversion is active. The import preserves identity, router settings,
authorized ranges and exclusive per-/24 bandwidth exceptions; it creates a
root-only config.before-settings-TIMESTAMP.json backup and asks for APPLY.
Automatic mode stays off until explicitly armed. To configure interactively:
  sudo peeryx-collector settings
Use values such as "100000 pps", "4 gbps", or "off". The portal permits
0.001-100000 Gbit/s with up to three decimals, or 1-1000000000 whole pps.
The local profile schema uses integer bits/s, not Gbit/s. Example:
  "threshold_pps": 0,
  "threshold_bps": 4000000000,
  "protocol_thresholds_pps": {},
  "protocol_thresholds_bps": {},
  "minimum_hold_seconds": 1800
This selects all-protocol L3 bandwidth only, with a 30-minute hold.
These lines are a configuration excerpt, not a complete import file; use the
portal builder or local wizard for a complete, validated profile.

Minimum hold can be 20-10080 whole minutes (seven days), starting at confirmed
HARD diversion. A continuing attack extends it. Clear-history, fresh telemetry
and routing-overlap requirements remain in effect. Delivery-path failure may
require early recovery to preserve availability. Changing settings requires
observation mode; settings do not alter an active incident halfway through.
Do not downgrade to 1.0.0 while protocol/total bandwidth profiles are enabled.
That version does not implement these fields. First review a compatible profile.

FILES AND OPERATIONS
/etc/peeryx-collector/config.json           Local configuration (root only)
/etc/peeryx-collector/identity.json         Device token (root only)
/etc/peeryx-collector/bird.conf             Isolated BIRD configuration
/etc/peeryx-collector/signals.conf          Generated signal routes; do not edit
/run/peeryx-collector/                     Ephemeral health and evidence
/var/lib/peeryx-collector/incidents.json    Persistent diversion lifecycle
/opt/peeryx-collector/releases/VERSION     Versioned installed software

  sudo journalctl -u peeryx-collector -u peeryx-collector-detector --since '-10 min'
  sudo birdc -s /run/peeryx-collector/bird.ctl show protocols all customer_ibgp
  sudo peeryx-collector observe
  sudo peeryx-collector apply
Observe refuses an active diversion; wait for validated recovery first. Apply
validates JSON and BIRD syntax, then restarts only the dedicated services.
Use apply after changing detector thresholds/interface settings in config.json.
Back up config.json before editing; do not change enabled by hand.
Pairing never uses passwords or router credentials. Device tokens authorize
only enrollment-related health and reading this device's provider evidence.
They cannot administer the customer's other services or submit routing proof.

UPGRADE / REMOVAL
Run the new versioned installer when no diversion is active. It retains
configuration/history, verifies signatures, and keeps old release directories.
An upgrade with active diversions is refused. The same version cannot silently
overwrite modified installed files. For an application rollback, use the old
version's installer after completing recovery; review schema compatibility.
  sudo peeryx-collector uninstall
This stops/disables the three collector services and retains configuration,
credentials and history for recovery/audit. Revoke the device in the portal.
After confirming no diversion remains, administrators may remove the dedicated
/etc/peeryx-collector, /var/lib/peeryx-collector and /opt/peeryx-collector paths,
its three unit files and /usr/local/sbin/peeryx-collector. System dependencies
and unrelated BIRD services are never removed automatically.

TROUBLESHOOTING
No flow data: verify UDP destination, exporter source, firewall, ifIndexes,
sampling, timestamps and templates. Counter-only sFlow exports are insufficient.
No prefixes: check customer_ibgp, approved ranges, /24 length and next hops.
For local-origin routes, Peeryx must validate local delivery before admission.
BGP up but no mitigation: observation mode, missing commissioning/evidence,
uncalibrated telemetry or thresholds can intentionally block diversion.
Peeryx-visible but no HARD: external advertisement or clean delivery is not yet
confirmed. Do not bypass the independent evidence gate.
Disconnected portal: inspect HTTPS, clock and revoked/expired credentials.
Loss of measurements alone never proves that an ongoing attack has ended.
Use the service support link with doctor output, date/time and collector UUID.
Never include identity.json, pairing codes, passwords or keys in tickets.

MAINTENANCE MODE
Before updating or uninstalling, run sudo peeryx-collector observe. The controller
acknowledges this request only after all active diversions have completed recovery.
If it refuses, wait for recovery and retry; do not stop BGP to bypass this check.
Run the signed installer after observation mode is confirmed. Re-run doctor and
arm after maintenance. Existing automatic mode is never silently re-enabled.

ROUTE RESOLUTION
The dedicated BIRD instance uses a private IGP table to resolve retained customer
next hops through the configured router. It installs no routes in the host kernel.
The customer router must still validate next-hop reachability and local delivery.
