Merge pull request #48 from osg-htc/fix/install-perfsonar-fences

fix(docs): repair fences & admonition lists in install-perfsonar-testpoint.md (includes automated lint fixes)

Author: ShawnMcKee

docs/network-troubleshooting/osg-debugging-document.md

@@ -9,7 +9,7 @@
   ```text
 This document is old but still may have useful information.  Many tools it references may no longer be supported or available.
 
-```
+  ```
 
 # Abstract
 

docs/perfsonar/CONTAINER_RESTART_ISSUE.md

@@ -60,7 +60,7 @@ If you have an existing deployment with the restart loop issue:
    cd /opt/perfsonar-tp
    podman-compose down
 
-```
+   ```
 
 1. Update the docker-compose.yml file to use the recommended configuration from:
 
@@ -70,14 +70,14 @@ If you have an existing deployment with the restart loop issue:
 
        -o /opt/perfsonar-tp/docker-compose.yml
 
-```
+   ```
 
 1. Restart the service:
 
    ```bash
    systemctl restart perfsonar-testpoint
 
-```
+   ```
 
 ## Verification
 

docs/perfsonar/FIX_SUMMARY.md

@@ -168,13 +168,13 @@ To apply these fixes to other perfSONAR testpoint deployments:
        -o /tmp/install-systemd-service.sh
    sudo bash /tmp/install-systemd-service.sh /opt/perfsonar-tp
 
-```
+   ```
 
 1. **Automated deployment with Ansible**:
 
    ```bash
    ansible-playbook -i inventory ansible/playbooks/deploy-testpoint-container.yml
-```
+   ```
 
 1. **Fix existing deployments with restart issues**:
 

docs/perfsonar/deployment-models.md

@@ -10,7 +10,7 @@ each focused on specific set of tests. The following deployment options are curr
 
 * **Bare metal** - preffered option in one of two possible configurations:
 
-    ```text
+```text
 
 * Two bare metal servers, one for latency node, one for bandwidth node
 
@@ -20,21 +20,22 @@ each focused on specific set of tests. The following deployment options are curr
 
 * **Virtual Machine** - if bare metal is not available then it is also possible to run perfSONAR on a VM, however there are a set of additional requirements to fulfill:
 
-    ```text
+```text
+
 * Full-node VM is strongly preferred, having 2 VMs (latency/bandwidth node) on a single bare metal. Mixing perfSONAR VM(s) with others might have an impact on the measurements and is therefore not recommended.
 * VM needs to be configured to have SR-IOV to NIC(s) as well as pinned CPUs to ensure bandwidth tests are not impacted (by hypervisor switching CPUs during the test)
 * Succesfull full speed local bandwidth test is highly recommended prior to putting the VM into production
 ```
 
 * **Container** - perfSONAR has supported containers from version 4.1 (Q1 2018) and is documented at <https://docs.perfsonar.net/install_docker.html> but is not typically used in the same way as a full toolkit installation.
 
-    ```text
+```text
 
 * Docker perfSONAR test instance can however still be used by sites that run multiple perfSONAR instances on site for their internal testing as this deployment model allows to flexibly deploy a testpoint which can send results to a local measurement archive running on the perfSONAR toolkit node.
 
 ```
 
-### perfSONAR Toolkit vs Testpoint
+## perfSONAR Toolkit vs Testpoint
 
 The perfSONAR team has documented the types of installations supported at
 <https://docs.perfsonar.net/install_options.html>.   With the release of version 5, OSG/WLCG sites have a new option:
@@ -45,7 +46,7 @@ instead of installing the full Toolkit sites can choose to install the Testpoint
         ```text
 * Simpler deployment when a local web interface is not needed and a central measurement archive is available.
 * Less resource intensive for both memory and I/O capacity.
-```
+        ```
 
 * Cons
 
@@ -54,7 +55,7 @@ instead of installing the full Toolkit sites can choose to install the Testpoint
 * No web interface to use for configuration or adding local tests
 * Unable to show results in MaDDash
 
-```
+        ```
 
 While sites are free to choose whatever deployment method they want, we would like to strongly recommend the use of
 perfSONAR's containerized testpoint. This method was chosen as a "best practice" recommendation because of the reduced
@@ -83,7 +84,7 @@ taking into account the amount of testing that we perform, we recommend at least
 
 * NVMe or SSD disk (128GB should be sufficient) if using full Toolkit install with Opensearch.
 
-<a id="multiple-nic-network-interface-card-guidance"></a>
+<!-- anchor removed; heading provides an automatic id -->
 
 ### Multiple NIC (Network Interface Card) Guidance
 

docs/perfsonar/install-testpoint.md

@@ -130,15 +130,15 @@ Recommended: use the helper script to generate and apply NetworkManager profiles
     ```bash
     /opt/perfsonar-tp/tools_scripts/perfSONAR-pbr-nm.sh --generate-config-debug
 
-```
+    ```
 
 1. Generate the config file automatically:
 
     ```bash
 
     /opt/perfsonar-tp/tools_scripts/perfSONAR-pbr-nm.sh --generate-config-auto
 
-```
+    ```
 
 Note: The auto-generator intentionally skips NICs that have neither an IPv4 nor an IPv6 gateway (e.g., management-only
 NICs) to avoid writing non-functional NetworkManager profiles. To include such a NIC in the configuration, set an
@@ -151,14 +151,14 @@ Review and adjust /etc/perfSONAR-multi-nic-config.conf if needed.
     ```bash
     /opt/perfsonar-tp/tools_scripts/perfSONAR-pbr-nm.sh --dry-run --debug
 
-```
+    ```
 
 1. Apply changes:
 
     ```bash
     /opt/perfsonar-tp/tools_scripts/perfSONAR-pbr-nm.sh --yes
 
-```
+    ```
 
 The script backs up current NetworkManager profiles and logs actions to /var/log/perfSONAR-multi-nic-config.log.
 
@@ -276,7 +276,7 @@ If you want the container to use a specific NIC, adjust the docker-compose.syste
 
 Check containers:
 
-```
+    ```
 
 podman ps
 

docs/perfsonar/installation.md

@@ -48,10 +48,13 @@ You can see more details about EL supported installs at <<https://docs.perfsonar
 
 !!! note
 
-    ```text
+<!-- markdownlint-disable MD040 -->
+    <!-- markdownlint-disable MD040 -->
+     ```text
 In all cases, we strongly recommend keeping auto-updates enabled. With yum auto-updates there is a possibility that updated packages can "break" your perfSONAR install but this risk is accepted in order to have security updates quickly applied.
 
-```
+     ```
+<!-- markdownlint-enable MD040 -->
 
 The following *additional* steps are needed to configure the toolkit to be used in OSG/WLCG in addition to the steps
 described in the official guide:
@@ -62,7 +65,8 @@ described in the official guide:
 
 * You will need to configure your instance(s) to use the OSG/WLCG mesh-configuration. Please follow the steps below:
 
-    ```text
+```text
+
 * For toolkit versions 5.0 and higher run: `psconfig remote add https://psconfig.opensciencegrid.org/pub/auto/<FQDN>` replacing `<FQDN>` with your host (e.g. `psum01.aglt2.org`). Verify with `psconfig remote list`.
 ```
 
@@ -74,15 +78,21 @@ described in the official guide:
       "configure-archives" : true
    }
 ]
-```
+ ```
 
 * Please remove any old/stale URLs using `psconfig remote delete <URL>`
 
-* If this is a **new instance** or you have changed the node's FQDN, you will need to notify `wlcg-perfsonar-support 'at' cern.ch` to add/update the hostname in one or more test meshes, which will then auto-configure the tests. Please indicate if you have preferences for which meshes your node should be included in (USATLAS, USCMS, ATLAS, CMS, LHCb, Alice, BelleII, etc.). You could also add any additional local tests  via web interface (see [Configuring regular tests](http://docs.perfsonar.net/manage_regular_tests.html) for details). Please check which tests are auto-added via central meshes before adding any custom tests to avoid duplication.
+* If this is a **new instance** or you have changed the node's FQDN, you will need to notify
+    `wlcg-perfsonar-support 'at' cern.ch` to add/update the hostname in one or more test meshes, which
+    will then auto-configure the tests. Please indicate if you have preferences for which meshes your
+    node should be included in (USATLAS, USCMS, ATLAS, CMS, LHCb, Alice, BelleII, etc.). You could also
+    add any additional local tests via web interface (see [Configuring regular tests](http://docs.perfsonar.net/manage_regular_tests.html) for details).
+    Please check which tests are auto-added via central meshes before adding any custom tests to avoid
+    duplication.
 
 !!! note
 
-    ```text
+```text
 Until your host is added on https://psconfig.opensciencegrid.org to one or more meshes by an administrator the automesh configuration above will not return any tests.
 
 ```
@@ -127,7 +137,7 @@ site or host firewalls.   An overview of perfSONAR security is available at
     ```text
 All perfSONAR instances must have port 443 accessible to other perfSONAR instances. Port 443 is used by pScheduler to schedule tests. If unreachable, tests may not run and results may be missing.
 
-```
+    ```
 
 For sites that are concerned about having port 443 open, there is a possiblity to get a list of hosts to/from which the
 tests will be initiated. However as this list is dynamic, implementing the corresponding firewall rules would need to be
@@ -140,7 +150,8 @@ network administrators to debug network issues.
     ```text
 If you have a central/campus firewall verify required port openings in the perfSONAR security documentation.
 
-```
+    ```
+    <!-- markdownlint-enable MD040 -->
 
 ## Enabling SNMP plugins
 
@@ -167,6 +178,7 @@ filling the information please follow those simple guidelines:
 
 * For each form (service type) fill at least:
 
+    <!-- markdownlint-disable MD040 -->
     ```text
 
 * Hosting Site
@@ -175,7 +187,8 @@ filling the information please follow those simple guidelines:
 * Host IP (optional)
 * Description (optional label used in MaDDash; keep short and unique)
 
-```
+    ```
+    <!-- markdownlint-enable MD040 -->
 
 * Check "N" when asked "Is it a beta service"
 
@@ -186,8 +199,7 @@ filling the information please follow those simple guidelines:
 <!-- -->
 
 * GOCDB screen shot for creating a Service Endpoint:
-<img src="../../img/Screen_shot_2013-02-19_at_15.26.52.png" alt="GOCDB screen shot for creating a Service Endpoint"
-width="1024">
+![GOCDB screen shot for creating a Service Endpoint](../../img/Screen_shot_2013-02-19_at_15.26.52.png)
 
 ## Register perfSONAR in OSG Topology
 

docs/perfsonar/packet-pacing.md

@@ -419,11 +419,11 @@ setsockopt(sockfd, SOL_SOCKET, SO_MAX_PACING_RATE,
 
 ### ESnet Fasterdata Documentation
 
-- **DTN Tuning Guide**: https://fasterdata.es.net/DTN/tuning/
+- **DTN Tuning Guide**: <https://fasterdata.es.net/DTN/tuning/>
 
-- **Packet Pacing Guide**: https://fasterdata.es.net/host-tuning/linux/packet-pacing/
+- **Packet Pacing Guide**: <https://fasterdata.es.net/host-tuning/linux/packet-pacing/>
 
-- **FQ Pacing Research Results**: https://fasterdata.es.net/assets/fasterdata/FQ-pacing-results.pdf
+- **FQ Pacing Research Results**: <https://fasterdata.es.net/assets/fasterdata/FQ-pacing-results.pdf>
 
 ### Linux Kernel Documentation
 
@@ -433,23 +433,23 @@ setsockopt(sockfd, SOL_SOCKET, SO_MAX_PACING_RATE,
 
 - **tc man page**: `man 8 tc`
 
-- **LWN Article on FQ**: https://lwn.net/Articles/564978/
+- **LWN Article on FQ**: <https://lwn.net/Articles/564978/>
 
 ### Tools and Testing
 
-- **iperf3**: https://iperf.fr/ (with `--fq-rate` support)
+- **iperf3**: <https://iperf.fr/> (with `--fq-rate` support)
 
-- **perfSONAR**: https://www.perfsonar.net/ (pscheduler with pacing)
+- **perfSONAR**: <https://www.perfsonar.net/> (pscheduler with pacing)
 
 - **mtr** (traceroute tool): `mtr <destination>`
 
 ### Related Tuning
 
 - **SYSCTL Tuning**: See `fasterdata-tuning.sh` for buffer sizing recommendations
 
-- **100G+ Tuning**: https://fasterdata.es.net/host-tuning/linux/100g-tuning/
+- **100G+ Tuning**: <https://fasterdata.es.net/host-tuning/linux/100g-tuning/>
 
-- **BBR Congestion Control**: https://fasterdata.es.net/host-tuning/linux/recent-tcp-enhancements/bbr-tcp/
+- **BBR Congestion Control**: <https://fasterdata.es.net/host-tuning/linux/recent-tcp-enhancements/bbr-tcp/>
 
 ---
 

docs/perfsonar/register-ps-in-gocdb.md

@@ -18,7 +18,7 @@ both service types (use the same hostname in the "host name" field).
 
 - For each form (i.e. for each service type) fill at least the important informations:
 
-    ```text
+```text
 
 - Hosting Site (drop-down menu, mandatory)
 - Service Type (drop-down menu, mandatory)

docs/perfsonar/tools_scripts/README.md

@@ -63,7 +63,7 @@ After installation:
   /opt/perfsonar-tp/tools_scripts/install-systemd-service.sh /opt/perfsonar-tp
   systemctl enable --now perfsonar-testpoint.service
 
-```
+  ```
 
 - Manual installs: After `podman-compose up -d`, install and enable the service as shown above.
 
@@ -138,7 +138,7 @@ sha256sum -c /tmp/fasterdata-tuning.sh.sha256 --status && echo "OK" || echo "Che
 
 - `--dry-run`: Preview the changes that would be made (GRUB edits and sysfs writes) without applying them. Use for validation and audits.
 
-## Usage examples
+## Usage examples (fasterdata tuning)
 
 Audit (default) a measurement host:
 
@@ -277,7 +277,11 @@ bash perfSONAR-pbr-nm.sh --yes
 
 ## Gateway requirement, inference, and generator warnings
 
-- Any NIC with an IPv4 address should have a corresponding IPv4 gateway; likewise for IPv6. If a NIC lacks a gateway, the generator will attempt conservative inference (below). If a device has no IPv4 or IPv6 gateway (e.g., a management-only NIC), the generator will intentionally skip that NIC when creating an _auto-generated_ config to avoid generating unusable NetworkManager profiles unless you explicitly set the device as `DEFAULT_ROUTE_NIC`.
+- Any NIC with an IPv4 address should have a corresponding IPv4 gateway; likewise for IPv6. If a NIC lacks a
+  gateway, the generator will attempt conservative inference (below). If a device has no IPv4 or IPv6 gateway
+  (e.g., a management-only NIC), the generator will intentionally skip that NIC when creating an
+  _auto-generated_ config to avoid generating unusable NetworkManager profiles unless you explicitly set the
+  device as `DEFAULT_ROUTE_NIC`.
 
 - Conservative gateway inference: if a NIC has an address/prefix but no gateway, the tool will try to reuse a gateway from another NIC on the SAME subnet.
 
@@ -351,7 +355,7 @@ cd docs/perfsonar
 ./tests/run_tests.sh
 ```
 
-## Notes
+## Notes (script details)
 
 - The script requires Bash (uses `local -n` namerefs). Run tests on a system
   with Bash 4.3+.