osg-htc · ShawnMcKee · Dec 7, 2025 · Dec 7, 2025
diff --git a/docs/index.md b/docs/index.md
@@ -1,84 +1,91 @@
 OSG Networking Area
 ===================
 
-*Welcome to OSG Networking !* This is an entry point for those interested in Networking
-in OSG/WLCG or for those OSG/WLCG users experiencing network problems. It provides an
-overview of the networking goals, plans and various activities and subtopics underway
-regarding networking in the *Open Science Grid (OSG)* and *World-wide LHC Computing Grid (WLCG)*,
-operated as a joint project. This area started in June 2012 with initial focus on the network
-monitoring as monitoring is critical to provide needed visibility into existing networks and site
-connectivity. OSG is working to provide needed networking information and tools for users, sites
-and experiments/VOs.
-
-This documentation is divided into several sub-sections, each covering a specific area of activities.
-
-Network Monitoring in WLCG and OSG (perfSONAR)
------------------------------------------------
-
-WLCG and OSG jointly operate a network of `perfSONAR` agents deployed world-wide, which provides an
-open platform that can be used to baseline network performance and debug any potential issues. The
-following subsections provide details on the motivation, deployment and operations of the perfSONARs
-in WLCG/OSG:
-
-- [Motivation](perfsonar-in-osg.md) - overview, core concepts, motivation
-- [Deployment Guide](perfsonar/deployment-models.md) - deployment models and options, hardware requirements
-- [Installation and Administration Guide](perfsonar/installation.md) - installation, configuration and maintanance
-- [Frequently Asked Questions](perfsonar/faq.md)
-
-Network Troubleshooting
------------------------
-
-Users with network issues should check the [troubleshooting link](network-troubleshooting.md) below
-for initial guidance on how best to get their issue resolved. In addition, you can refer to the
-[ESNet network performance guide](https://fasterdata.es.net/performance-testing/troubleshooting/network-troubleshooting-quick-reference-guide/)
-for a detailed instructions on how to identify and isolate network performance issues using perfSONAR.
-
-Host and Network Tuning
------------------------
-
-- [Fasterdata-aligned host/network tuning (EL9)](host-network-tuning.md) — summarizes ESnet guidance and includes an audit/apply script.
-
-Network Services
-----------------
-
-OSG operates an advanced platform to collect, store, publish and analyse the network monitoring data it gathers from perfSONAR and other locations. All measurements are collected and available via streaming or through APIs. The following services are available:
-
-- [perfSONAR infrastructure monitoring](perfsonar/psetf.md) - monitors state of perfSONAR network and reports on availability of core services
-- [*OSG Distributed Network Datastore*](https://atlas-kibana.mwt2.org/s/networking/app/kibana#/dashboards?notFound=dashboard&_g=()) - distributed datastore based on ElasticSearch holding all the network measurements and providing an API to expose them via JSON is available at two locations (University of Chicago and University of Nebraska).
-- *OSG pSConfig Web Admin (PWA)* - centralized configuration of the tests performed by the OSG/WLCG perfSONAR infrastructure . In case you'd like to start/manage particular mesh, please contact our support channels to get access.
-- *OSG Dashboards* [http://maddash.aglt2.org](https://maddash.aglt2.org) - set of dashboards showing an overview of the network state as seen by the perfSONAR infrastructure (NOTE: this instance is being deprecated and we plan to introduce dashboards that will replace MaDDash over the coming 2023-2024 year).
-- [*WLCG Dashboards*](https://monit-grafana-open.cern.ch/d/MwuxgogIk/wlcg-site-network?var-bin=1h&orgId=16)) - set of dashboards showing WLCG and OSG network performance by combining multiple sources of data including perfSONAR, FTS, ESNet/LHCOPN traffic, etc.
-
-Network Analytics
------------------
-
-University of Chicago has set up an [**analytics platform**](<https://twiki.cern.ch/twiki/bin/view/AtlasComputing/ATLASAnalytics>) using `ElasticSearch` and `Kibana4` as well as `Jupyter` that can be used to access and analyse all the existing network measurements.
-
-Support and Feedback
---------------------
-
-If you suspect a network problem and wish to follow up on it, we have a number of tools
-available. We have a [ToolkitInfo](https://toolkitinfo.opensciencegrid.org/) page that can
-help you find resources to identify and explore problems. In general, networks problems are
-best resolved by opening a ticket with your site's network provider (see
-<https://osg-htc.org/networking/network-troubleshooting/>). If you want WLCG/OSG specific
-support, please open a ticket with the appropriate support unit: For `OSG` sites please open
-a ticket with [GOC](https://support.opensciencegrid.org/support/home); For `WLCG` sites
-please open a [GGUS](https://ggus.eu/) ticket to `WLCG Network Throughput` support unit. If
-you'd like to get help in setting up a WLCG/OSG perfSONAR instance please open a ticket with
-[GOC](https://support.opensciencegrid.org/support/home) or via [GGUS](https://ggus.eu/) to
-WLCG perfSONAR support. If you have problems or questions specific to perfSONAR, please email
-the perfSONAR user [mailing list](https://lists.internet2.edu/sympa/info/perfsonar-user). For
-any other requests or to provide feedback, please open a ticket at [GGUS](https://ggus.eu/)
-and mention OSG networking.
-
-References
-----------
-
-- ESNet network performance tuning and debugging <https://fasterdata.es.net/>
-- [perfSONAR](http://docs.perfsonar.net/) toolkit is part of the [perfSONAR](https://www.perfsonar.net/) project.
-- **OSG/WLCG mesh configuration interface** is available at <https://psconfig.opensciencegrid.org>
-- **OSG dashboard instance** <https://maddash.aglt2.org> (NOTE: deprecated replacement)
-- **OSG perfSONAR infrastructure monitoring** <https://psetf.aglt2.org/etf/check_mk/>
-- **OSG Analytics platform** <https://atlas-kibana.mwt2.org/s/networking/app/kibana>
-- **WLCG dashboards** <https://monit-grafana-open.cern.ch/d/MwuxgogIk/wlcg-site-network?var-bin=1h&orgId=16>
+*Welcome to OSG Networking!* This is your entry point for networking in the *Open Science Grid (OSG)* and *World-wide LHC Computing Grid (WLCG)*. Whether you're deploying perfSONAR, troubleshooting network issues, or exploring our monitoring infrastructure, we've organized the documentation around common user journeys.
+
+## Get Started
+
+Choose the path that matches your goal:
+
+<div class="grid cards" markdown>
+
+- :rocket: **Deploy perfSONAR**
+
+    ---
+
+    Quick, tested steps to deploy a perfSONAR testpoint for OSG/WLCG monitoring.
+
+    **Time:** 30-60 minutes  
+    **Skill level:** Systems administrator
+
+    [:octicons-arrow-right-24: Quick Deploy Guide](personas/quick-deploy/landing.md)
+
+- :wrench: **Troubleshoot Network Issues**
+
+    ---
+
+    Triage checklist and playbooks for diagnosing network problems.
+
+    **Time:** Variable  
+    **Skill level:** Network operator/admin
+
+    [:octicons-arrow-right-24: Troubleshooting Guide](personas/troubleshoot/landing.md)
+
+- :telescope: **Understand the System**
+
+    ---
+
+    Architecture, data pipelines, and research documentation.
+
+    **Time:** Reading/reference  
+    **Skill level:** Developer/researcher
+
+    [:octicons-arrow-right-24: Architecture & Research](personas/research/landing.md)
+
+</div>
+
+## About OSG/WLCG Network Monitoring
+
+WLCG and OSG jointly operate a worldwide network of `perfSONAR` agents that provide an open platform for baselining network performance and debugging issues. This monitoring infrastructure is critical for providing visibility into networks and site connectivity.
+
+**Key capabilities:**
+
+- Automated bandwidth and latency testing between sites
+- Centralized measurement storage and analytics
+- Integration with WLCG/OSG dashboards and alerting
+- Community-maintained test meshes
+
+[Learn more about perfSONAR in OSG/WLCG](perfsonar-in-osg.md){ .md-button }
+
+## Network Services & Data
+
+OSG operates an advanced platform to collect, store, publish and analyze network monitoring data from perfSONAR and other sources. All measurements are available via streaming APIs and dashboards:
+
+- **[perfSONAR Infrastructure Monitoring](perfsonar/psetf.md)** - monitors perfSONAR network health and service availability
+- **[OSG Network Datastore](osg-network-services.md)** - distributed ElasticSearch datastore with JSON API (University of Chicago and University of Nebraska)
+- **OSG pSConfig Web Admin** - centralized test mesh configuration (contact support for access)
+- **[WLCG Dashboards](https://monit-grafana-open.cern.ch/d/MwuxgogIk/wlcg-site-network?var-bin=1h&orgId=16)** - comprehensive performance dashboards combining perfSONAR, FTS, and network traffic data
+- **[Analytics Platform](osg-network-analytics.md)** - ElasticSearch/Kibana/Jupyter for analyzing measurements
+
+!!! note "MaDDash Deprecation"
+    The legacy MaDDash instance at maddash.aglt2.org is deprecated. Use WLCG Grafana dashboards instead.
+
+## Support and Feedback
+
+**For network problems:**
+
+1. Start with the [Troubleshooting Guide](network-troubleshooting.md) or [ToolkitInfo](https://toolkitinfo.opensciencegrid.org/)
+2. Contact your site's network provider
+3. For OSG-specific support: [GOC ticket](https://support.opensciencegrid.org/support/home)
+4. For WLCG-specific support: [GGUS ticket](https://ggus.eu/) to "WLCG Network Throughput" or "WLCG perfSONAR support"
+
+**For perfSONAR questions:** [perfSONAR user mailing list](https://lists.internet2.edu/sympa/info/perfsonar-user)
+
+## Quick Links
+
+- [perfSONAR Documentation](https://docs.perfsonar.net/) | [perfSONAR Project](https://www.perfsonar.net/)
+- [ESNet Fasterdata Guide](https://fasterdata.es.net/)
+- [OSG/WLCG Mesh Configuration](https://psconfig.opensciencegrid.org)
+- [perfSONAR Infrastructure Monitoring](https://psetf.aglt2.org/etf/check_mk/)
+- [OSG Analytics Platform](https://atlas-kibana.mwt2.org/s/networking/app/kibana)
+- [WLCG Grafana Dashboards](https://monit-grafana-open.cern.ch/d/MwuxgogIk/wlcg-site-network?var-bin=1h&orgId=16)
diff --git a/docs/perfsonar/installation.md b/docs/perfsonar/installation.md
@@ -1,10 +1,12 @@
 # perfSONAR Installation Guide
 
-!!! note
+!!! warning "Legacy Documentation - Modern Approach Available"
 
-    ```text
-This page has older instructions for non-containerized perfSONAR deployments which are, as of October 2025, no longer the recommended best practice.
-    ```
+    This page contains **legacy instructions** for traditional Toolkit installations. As of October 2025, the **recommended approach** is containerized testpoint deployment.
+
+    **👉 For new installations, use the [Quick Deploy Guide](../personas/quick-deploy/install-perfsonar-testpoint.md) instead.**
+
+    This legacy guide is maintained for existing Toolkit installations and special cases requiring the full web interface.
 
 This page documents installing/upgrading **perfSONAR** for OSG and WLCG sites. In case this is the first time you're trying to install and integrate your perfSONAR into WLCG or OSG, please consult our [overview](../perfsonar-in-osg.md) and possible [deployment options](deployment-models.md) before installing. For troubleshooting an existing installation please consult official [Troubleshooting Guide](http://docs.perfsonar.net/troubleshooting_overview.html), [FAQ](http://docs.perfsonar.net/FAQ.html) as well as WLCG/OSG specific [FAQ](faq.md).
 

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -8,47 +8,63 @@ extra:
 theme: 
   name: material
   custom_dir: osgthedocs
+  features:
+    - navigation.tabs
+    - navigation.sections
+    - navigation.expand
+    - navigation.path
+    - navigation.top
+    - toc.follow
+    - toc.integrate
+    - content.code.copy
 
 extra_css:
   - css/extra.css
 
 nav:
-  - OSG Networking Area: 'index.md'
-  - Network Monitoring (perfSONAR):
-    - 'Motivation': 'perfsonar-in-osg.md'
-    - 'Deployment': 'perfsonar/deployment-models.md'
-    - 'Installation and Maintenance': 'perfsonar/installation.md'
-    - 'Frequently Asked Questions': 'perfsonar/faq.md'
-  - Network Troubleshooting: 
-    - 'Network Troubleshooting': 'network-troubleshooting.md'
-    - 'OSG Network Debugging Document': 'network-troubleshooting/osg-debugging-document.md'
-  - Network Services: 
-    - 'Infrastructure Monitoring': 'perfsonar/psetf.md'
-    - 'Network Datastore and Streaming': 'osg-network-services.md'
-    - 'Network Analytics': 'osg-network-analytics.md'
-  - Personas:
-    - Quick Deploy:
-      - 'Landing': 'personas/quick-deploy/landing.md'
-      - 'Quickstart: perfSONAR Testpoint': 'personas/quick-deploy/install-perfsonar-testpoint.md'
-      - 'Automated setup': 'personas/quick-deploy/automated-setup/README.md'
-    - Troubleshooter:
-      - 'Landing': 'personas/troubleshoot/landing.md'
-      - 'Triage checklist': 'personas/troubleshoot/triage-checklist.md'
-    - Researcher:
-      - 'Landing': 'personas/research/landing.md'
-      - 'Architecture': 'personas/research/architecture.md'
-  - Features:
-    - 'fail2ban': 'features/fail2ban.md'
-    - 'SELinux': 'features/selinux.md'
-    - 'nftables': 'features/nftables.md'
+  - Home: 'index.md'
+  - Get Started:
+    - 'Deploy perfSONAR': 'personas/quick-deploy/landing.md'
+    - 'Troubleshoot Issues': 'personas/troubleshoot/landing.md'
+    - 'Understand the System': 'personas/research/landing.md'
+  - perfSONAR Guides:
+    - 'Why perfSONAR in OSG/WLCG': 'perfsonar-in-osg.md'
+    - 'Deployment Models': 'perfsonar/deployment-models.md'
+    - 'Quick Deploy (Testpoint)': 'personas/quick-deploy/install-perfsonar-testpoint.md'
+    - 'Automated Setup': 'personas/quick-deploy/automated-setup/README.md'
+    - 'Legacy Installation (Archive)': 'perfsonar/installation.md'
+    - 'FAQ': 'perfsonar/faq.md'
+  - Host Tuning:
+    - 'Fasterdata Host Tuning': 'host-network-tuning.md'
+    - 'Multiple NIC Guidance': 'perfsonar/multiple-nic-guidance.md'
+  - Troubleshooting:
+    - 'Triage Checklist': 'personas/troubleshoot/triage-checklist.md'
+    - 'Network Troubleshooting Guide': 'network-troubleshooting.md'
+    - 'OSG Debugging Document': 'network-troubleshooting/osg-debugging-document.md'
+  - Network Services & Data:
+    - 'Infrastructure Monitoring (PSETF)': 'perfsonar/psetf.md'
+    - 'Network Datastore': 'osg-network-services.md'
+    - 'Analytics Platform': 'osg-network-analytics.md'
   - Tools & Scripts:
-    - 'Scripts and tools': 'perfsonar/tools_scripts/README.md'
-    - 'Fasterdata host tuning (EL9)': 'perfsonar/tools_scripts/fasterdata-tuning.md'
-    - 'Compose bundle (docker-compose.yml)': 'perfsonar/tools_scripts/docker-compose.yml'
-    - 'LS registration updater (script)': 'perfsonar/tools_scripts/perfSONAR-update-lsregistration.sh'
-    - 'LS registration helpers (README)': 'perfsonar/tools_scripts/README-lsregistration.md'
-    - 'Link-check tools': 'tools/README.md'
-    - 'Site management': 'web-site-management.md'
+    - 'Overview': 'perfsonar/tools_scripts/README.md'
+    - 'Fasterdata Tuning Script': 'perfsonar/tools_scripts/fasterdata-tuning.md'
+    - 'LS Registration Tools': 'perfsonar/tools_scripts/README-lsregistration.md'
+    - 'LS Registration Updater': 'perfsonar/tools_scripts/perfSONAR-update-lsregistration.sh'
+    - 'Compose Bundles': 'perfsonar/tools_scripts/docker-compose.yml'
+    - 'Link-Check Tools': 'tools/README.md'
+  - Advanced:
+    - Security Features:
+      - 'fail2ban': 'features/fail2ban.md'
+      - 'SELinux': 'features/selinux.md'
+      - 'nftables': 'features/nftables.md'
+    - 'Architecture': 'personas/research/architecture.md'
+    - Release Notes:
+      - 'v1.4.0': 'release-notes/quick-deploy-1.4.0.md'
+      - 'v1.3.0': 'release-notes/quick-deploy-1.3.0.md'
+      - 'v1.1.0': 'release-notes/quick-deploy-1.1.0.md'
+      - 'v1.0.1': 'release-notes/quick-deploy-1.0.1.md'
+      - 'v1.0.0': 'release-notes/quick-deploy-1.0.0.md'
+    - 'Site Management': 'web-site-management.md'
 
 markdown_extensions:
   - admonition