perfSONAR Tools & Scripts¶
This directory contains helper scripts for perfSONAR deployment, configuration, and tuning.
Available tools¶
Deployment orchestrators¶
Two orchestrator scripts cover the two perfSONAR deployment models. Choose the right one for your site — they are not interchangeable:
| Script | Deployment model | When to use |
|---|---|---|
| perfSONAR-orchestrator.sh | Container (podman) | New hosts; preferred for RHEL 9 minimal installs; full Let's Encrypt automation |
| perfSONAR-toolkit-install.sh | RPM (dnf / perfsonar-toolkit) | Sites that require the full web GUI; existing RPM-managed infrastructure |
Helper and utility scripts¶
| Tool | Version | Purpose | Documentation |
|---|---|---|---|
| perfSONAR-orchestrator.sh | v1.1.4 | Container testpoint orchestrator | Container deployment |
| perfSONAR-toolkit-install.sh | v1.0.0 | RPM toolkit guided installer | RPM toolkit deployment |
| fasterdata-tuning.sh | v1.3.1 | Host & NIC tuning (ESnet Fasterdata) | Fasterdata Tuning Guide |
| perfSONAR-pbr-nm.sh | — | Multi-NIC policy-based routing | Multiple NIC Guidance |
| perfSONAR-update-lsregistration.sh | — | LS registration management | LS Registration Tools |
| perfSONAR-auto-enroll-psconfig.sh | — | Automatic pSConfig enrollment (container + RPM) | Installation Guides |
| install_tools_scripts.sh | — | Bulk installer for all scripts | Installation |
| install-systemd-service.sh | — | Container auto-start on boot | Container Management |
| perfSONAR-install-flowd-go.sh | v1.4.0 | SciTags flowd-go installer | SciTags & Fireflies |
| perfSONAR-configure-exporter-acls.sh | v0.1.0 | Restrict exporter endpoints to monitoring CIDRs | RPM toolkit deployment |
Latest Updates: v1.0.0 (Feb 2026) adds perfSONAR-toolkit-install.sh for RPM-based toolkit deployments.
Container-based deployment (Orchestrator)¶
perfSONAR-orchestrator.sh installs the perfSONAR testpoint as a container (podman) on a
minimal EL9 host. It handles podman installation, opt-in Let's Encrypt (standalone certbot container),
multi-NIC PBR, nftables, flowd-go, and pSConfig enrollment.
# Option A — testpoint only (self-signed cert)
curl -fsSL https://raw.githubusercontent.com/osg-htc/networking/master/docs/perfsonar/tools_scripts/perfSONAR-orchestrator.sh \
| sudo bash -s -- --option A --experiment-id 2 --non-interactive
# Option B — testpoint + Let's Encrypt
curl -fsSL https://raw.githubusercontent.com/osg-htc/networking/master/docs/perfsonar/tools_scripts/perfSONAR-orchestrator.sh \
| sudo bash -s -- --option B --fqdn ps.example.org --email [email protected] \
--experiment-id 2 --non-interactive
Flags: --option {A|B}, --fqdn, --email, --experiment-id N, --no-flowd-go,
--non-interactive, --yes, --dry-run, --auto-update
RPM Toolkit Installer¶
perfSONAR-toolkit-install.sh installs the perfSONAR RPM toolkit bundle (perfsonar-toolkit
or another bundle) directly on EL9 via dnf. This gives the full web-based admin GUI and is the
correct path for sites that want a traditional package-managed deployment.
Differences from the container orchestrator:
| Container (orchestrator) | RPM Toolkit (toolkit-install) | |
|---|---|---|
| perfSONAR delivery | podman image | RPM packages |
| Web GUI | No (testpoint only) | Yes (Apache + PHP) |
| Let's Encrypt | certbot container + Apache patch | certbot RPM + apache RPM module |
| pSConfig exec | podman exec … psconfig |
psconfig directly on host |
| Auto-update | Podman image pull timer | dnf-automatic |
# Quick start — full toolkit, ATLAS (experiment 1), no LE cert
# (Includes exporter endpoint ACL protection by default for AGLT2 + CERN)
curl -fsSL https://raw.githubusercontent.com/osg-htc/networking/master/docs/perfsonar/tools_scripts/perfSONAR-toolkit-install.sh \
| sudo bash -s -- --experiment-id 1 --non-interactive
# Override default exporter allow-list with custom subnets
curl -fsSL https://raw.githubusercontent.com/osg-htc/networking/master/docs/perfsonar/tools_scripts/perfSONAR-toolkit-install.sh \
| sudo bash -s -- --experiment-id 1 --non-interactive \
--exporter-allowlist "YOUR_SUBNET_1,YOUR_SUBNET_2"
# Disable exporter endpoint ACL protection (not recommended)
curl -fsSL https://raw.githubusercontent.com/osg-htc/networking/master/docs/perfsonar/tools_scripts/perfSONAR-toolkit-install.sh \
| sudo bash -s -- --experiment-id 1 --non-interactive --no-exporter-acls
# With Let's Encrypt
curl -fsSL https://raw.githubusercontent.com/osg-htc/networking/master/docs/perfsonar/tools_scripts/perfSONAR-toolkit-install.sh \
| sudo bash -s -- --fqdn ps.example.org --email [email protected] \
--experiment-id 1 --non-interactive
# testpoint bundle only (no web GUI), dry-run first
curl -fsSL https://raw.githubusercontent.com/osg-htc/networking/master/docs/perfsonar/tools_scripts/perfSONAR-toolkit-install.sh \
| sudo bash -s -- --bundle testpoint --dry-run
Flags: --bundle {toolkit|testpoint|core|tools}, --fqdn, --email, --experiment-id N,
--no-flowd-go, --exporter-allowlist "CIDR1,CIDR2,..." (override defaults), --no-exporter-acls (disable protection), --non-interactive, --yes, --dry-run
RHEL 9 note: The perfSONAR automated install script (
downloads.perfsonar.net/install) does not enable CodeReady Builder on Satellite-managed RHEL systems.
perfSONAR-toolkit-install.shhandles this automatically viasubscription-manager.
Quick Start¶
Download All Scripts¶
Install all scripts to a target directory (default: /opt/perfsonar-tp/tools_scripts):
curl -fsSL https://raw.githubusercontent.com/osg-htc/networking/master/docs/perfsonar/tools_scripts/install_tools_scripts.sh | sudo bash -s -- /opt/perfsonar-tp
Download Individual Scripts¶
# Example: fasterdata-tuning.sh
sudo curl -fsSL -o /usr/local/bin/fasterdata-tuning.sh \
https://raw.githubusercontent.com/osg-htc/networking/master/docs/perfsonar/tools_scripts/fasterdata-tuning.sh
sudo chmod +x /usr/local/bin/fasterdata-tuning.sh
Host Tuning¶
Fasterdata Tuning Script¶
Audit and apply ESnet Fasterdata-inspired host and NIC tuning for EL9 systems.
NEW in v1.2.0: Save/restore state functionality for testing different tuning configurations.
Quick Usage:
# Audit mode (no changes)
/usr/local/bin/fasterdata-tuning.sh --mode audit --target measurement
# Apply tuning (requires root)
sudo /usr/local/bin/fasterdata-tuning.sh --mode apply --target dtn
# Save current state before testing
sudo /usr/local/bin/fasterdata-tuning.sh --save-state --label baseline
# Restore saved state
sudo /usr/local/bin/fasterdata-tuning.sh --restore-state baseline --yes
# List all saved states
/usr/local/bin/fasterdata-tuning.sh --list-states
State Management: Save and restore system configurations for before/after performance testing. Captures sysctl parameters, interface settings, configuration files, CPU governor, and tuned profile. See Fasterdata Tuning Guide for complete workflow examples.
Full Documentation: Fasterdata Tuning Guide
Multi-NIC Configuration¶
Policy-Based Routing (PBR)¶
Configure static IPv4/IPv6 addressing and per-NIC source-based routing via NetworkManager.
Script: perfSONAR-pbr-nm.sh
Config file: /etc/perfSONAR-multi-nic-config.conf
Log file: /var/log/perfSONAR-multi-nic-config.log
Quick Usage:
# Generate config automatically
/opt/perfsonar-tp/tools_scripts/perfSONAR-pbr-nm.sh --generate-config-auto
# Preview changes (dry-run)
/opt/perfsonar-tp/tools_scripts/perfSONAR-pbr-nm.sh --dry-run --debug
# Apply configuration
sudo /opt/perfsonar-tp/tools_scripts/perfSONAR-pbr-nm.sh --yes
Full Documentation: Multiple NIC Guidance
LS Registration¶
Lookup Service Registration Tools¶
Manage perfSONAR Lookup Service registration configuration.
Script: perfSONAR-update-lsregistration.sh
Quick Usage:
# For RPM Toolkit (local mode)
/opt/perfsonar-toolkit/tools_scripts/perfSONAR-update-lsregistration.sh update --local \
--site-name "My Site" --admin-email [email protected]
# For container-based testpoint
/opt/perfsonar-tp/tools_scripts/perfSONAR-update-lsregistration.sh update \
--container perfsonar-testpoint \
--site-name "My Site" --admin-email [email protected]
Full Documentation: LS Registration Tools
Auto-Enrollment¶
pSConfig Auto-Enrollment¶
Automatically enroll perfSONAR instances in OSG/WLCG pSConfig meshes by deriving FQDNs from configured IPs.
Script: perfSONAR-auto-enroll-psconfig.sh
Quick Usage:
# For RPM Toolkit (local mode)
/opt/perfsonar-toolkit/tools_scripts/perfSONAR-auto-enroll-psconfig.sh --local -v
# For container-based testpoint
/opt/perfsonar-tp/tools_scripts/perfSONAR-auto-enroll-psconfig.sh -v
Full Documentation: See Testpoint Installation or Toolkit Installation
Installation¶
Bulk Script Installer¶
Install all helper scripts to a target directory.
Script: install_tools_scripts.sh
Usage:
# Preview (dry-run)
bash /opt/perfsonar-tp/tools_scripts/install_tools_scripts.sh --dry-run
# Install to default location (/opt/perfsonar-tp/tools_scripts)
bash /opt/perfsonar-tp/tools_scripts/install_tools_scripts.sh
# Install to custom location
bash /opt/perfsonar-tp/tools_scripts/install_tools_scripts.sh /custom/path
Options:
- --dry-run: Preview changes without modifying files
- --skip-testpoint: Skip cloning testpoint repo if already present
Container Management¶
Systemd Service for Container Auto-Start¶
Install and enable a systemd service for automatic container restart on boot.
Script: install-systemd-service.sh
Usage:
# Install with default path (/opt/perfsonar-tp)
sudo /opt/perfsonar-tp/tools_scripts/install-systemd-service.sh
# Install with custom path
sudo /opt/perfsonar-tp/tools_scripts/install-systemd-service.sh /custom/path
Service Management:
# Start/stop/restart containers
systemctl start perfsonar-testpoint
systemctl stop perfsonar-testpoint
systemctl restart perfsonar-testpoint
# View status and logs
systemctl status perfsonar-testpoint
journalctl -u perfsonar-testpoint -f
Integration:
After deploying containers with podman-compose up -d, install the service to ensure containers start automatically on boot.
Dependencies¶
Essential packages (install before using these scripts):
# RHEL/AlmaLinux/Rocky Linux
dnf install -y bash coreutils iproute NetworkManager rsync curl openssl \
nftables podman podman-compose fail2ban policycoreutils python3
# Debian/Ubuntu
apt-get install -y bash coreutils iproute2 network-manager rsync curl openssl \
nftables podman podman-compose docker.io fail2ban policycoreutils python3
Support & Additional Resources¶
- Installation Guides: Quick Deploy Landing
- Troubleshooting: Troubleshooter Guide
- Network Issues: Network Troubleshooting Guide
- perfSONAR FAQ: FAQ
- Community Support: perfSONAR User Mailing List
Contact¶
Script Author: Shawn McKee — [email protected]
OSG Networking Team: [email protected]