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.