From b8166dd5045258c192193247b69a85dc32ea9aac Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?D=C3=A1vid=20Hanko?= <david.hanko@cesnet.cz>
Date: Wed, 9 Sep 2026 13:11:25 +0200
Subject: [PATCH 1/4] refactor: restructure pytest_start.sh help menu

Group the 24 flat help lines into logical sections (Connection, Test
selection, Traffic, Suricata, Results and logging, Advanced) with an
aligned two-column layout rendered via a quoted heredoc, instead of
one echo per line. Surface defaults inline (traffic duration 300,
hugepages 6G, log level INFO) and document the .env fallback variables.
Option parsing is unchanged; only the help text presentation differs.
---
 pytest_start.sh | 115 ++++++++++++++++++++++++++++++++----------------
 1 file changed, 76 insertions(+), 39 deletions(-)

diff --git a/pytest_start.sh b/pytest_start.sh
index c152377..a5fc6c8 100755
--- a/pytest_start.sh
+++ b/pytest_start.sh
@@ -14,50 +14,87 @@ set -xe
 
 usage(){
   set +x
-  echo "Bash script to start pytest"
-  echo "Options:"
-  echo "-s    | --server [SERVER] to specify the server, where Suricata will be running"
-  echo "-tm   | --target-mac [MAC_ADDRESS] to specify where to send traffic when not using ASTF TRex."
-  echo "-tv   | --target-vlan [VLAN_ID] to specify what VLAN tag to use for generated traffic."
-  echo '-d    | --defined-tests [TESTS] to specify tests, which have to be included, for all available tests run [-d|--defined-tests] " ",
-  for specific tests: [-d|--defined-tests] "nfs_smb_simple https_simple" or use multiple parameter specification, for specific test from test file
-  use [-d|--defined-tests] https_simple/test_https_simple.py::test_https_simple, by default it runs http_simple tests'
-  echo "-t    | --defined-time [TIME] to specify traffic duration in tests (seconds)"
-  echo "-tg   | --trex-server-hostname [TRAFFIC GENERATOR] to specify traffic generator server for testing"
-  echo "-p1   | --trex-server-port-1 [TRAFFIC GENERATOR PORT] to specify traffic generator port"
-  echo "-p2   | --trex-server-port-2 [TRAFFIC GENERATOR PORT] to specify traffic generator port"
-  echo "-p    | --pcie [PCIE] to specify, on which pcie will be Suricata tested, use multiple parameter specification or [-p|--pcie] "0000:3b:00.0 0000:3b:00.1""
-  echo "-ht   | --heatup [TIME] to specify the duration for which to wait before measuring statistics"
-  echo "-f    | --filter [rules/norules] starts Suricata with/without rules"
-  echo "-pc   | --pcap [PATH] to specify the pcap file to send to Suricata. Also sets --defined-tests to *only* pcap_replay"
-  echo "-pm   | --prefer-trex-mode [MODE] to suggest a mode for TRex. If unavailable tests use their defaults."
-  echo "-fm   | --force-trex-mode [MODE] to force a TRex mode. If unavailable tests get skipped. Overrides -pm"
-  echo "-sb   | --trex-stl-burst [PPS] [COUNT] to send a fixed burst of COUNT packets at PPS in STL mode. Defaults: 200 000 PPS, 10 000 000 packets"
-  echo "-sh   | --suricata-hugepages [SIZE] to specify how much RAM to allocate in hugepages. Default is 6G."
-  echo "-fpu  | --force-pcap-upload to force re-upload of pcaps to the TRex server, even if identical files already exist."
-  echo "-sl   | --suite-log-level [LEVEL] to set the logging level for the test suite: a name (DEBUG, INFO, PROGRESS, WARNING, ERROR, CRITICAL) or a number (e.g. 25). Default: INFO"
-  echo "-sf   | --suite-log-file to enable writing suite logs to results/artefacts/<run>/pytest.log"
-  echo "-rl   | --run-label [LABEL] to set a custom name for the results directory, e.g. experimental-pr-1234-300s. Results are saved to results/artefacts/<label>/ instead of the default timestamp."
-  echo "-bs   | --binary-search <mm> <xm> <dr> <pr> to enable automatic throughput search"
-  echo "-bsh  | --binary-search-help to show help for binary search mode"
+  cat <<'EOF'
+Bash script to start pytest
+
+Usage:
+  ./pytest_start.sh [options]
+
+Connection:
+  -s    --server [SERVER]              Server where Suricata will be running
+  -tg   --trex-server-hostname [HOST]  Traffic generator server for testing
+  -p1   --trex-server-port-1 [PORT]    Traffic generator port 1
+  -p2   --trex-server-port-2 [PORT]    Traffic generator port 2
+  -p    --pcie [PCIE ...]              PCIe address(es) of the Suricata
+                                        interface(s), e.g. -p "0000:3b:00.0 0000:3b:00.1"
+
+Test selection:
+  -d    --defined-tests [TESTS ...]    Tests to run. For all available tests
+                                        run -d " "; for specific tests use
+                                        -d "nfs_smb_simple https_simple"; for a
+                                        specific test use
+                                        -d https_simple/test_https_simple.py::test_https_simple.
+                                        Default: http_simple tests
+  -t    --defined-time [TIME]          Traffic duration in seconds (default: 300)
+  -ht   --heatup [TIME]                Seconds to wait before measuring statistics
+  -f    --filter [rules/norules]       Start Suricata with/without rules
+  -pc   --pcap [PATH]                  Pcap file to send to Suricata. Also sets
+                                        --defined-tests to *only* pcap_replay
+
+Traffic:
+  -tm   --target-mac [MAC_ADDRESS]     Where to send traffic when not using ASTF TRex
+  -tv   --target-vlan [VLAN_ID]        VLAN tag to use for generated traffic (default: 0)
+  -pm   --prefer-trex-mode [MODE]      Suggest a mode for TRex. If unavailable,
+                                        tests use their defaults
+  -fm   --force-trex-mode [MODE]        Force a TRex mode. If unavailable, tests get
+                                        skipped. Overrides -pm
+  -sb   --trex-stl-burst [PPS] [COUNT]  Send a fixed burst of COUNT packets at PPS
+                                        in STL mode.
+                                        Defaults: 200 000 PPS, 10 000 000 packets
+
+Suricata:
+  -sh   --suricata-hugepages [SIZE]    How much RAM to allocate in hugepages (default: 6G)
+
+Results and logging:
+  -sl   --suite-log-level [LEVEL]      Logging level for the suite: a name (DEBUG,
+                                        INFO, PROGRESS, WARNING, ERROR, CRITICAL)
+                                        or a number (e.g. 25). Default: INFO
+  -sf   --suite-log-file               Write suite logs to results/artefacts/<run>/pytest.log
+  -rl   --run-label [LABEL]            Custom name for the results directory, e.g.
+                                        experimental-pr-1234-300s. Results are saved to
+                                        results/artefacts/<label>/ instead of the
+                                        default timestamp
+  -fpu  --force-pcap-upload            Force re-upload of pcaps to the TRex server,
+                                        even if identical files already exist
+
+Advanced:
+  -bs   --binary-search <mm> <xm> <dr> <pr>
+                                        Enable automatic throughput search
+  -bsh  --binary-search-help           Show help for binary search mode
+
+Defaults for connection options can also be set in a .env file in the
+repository root (DEFAULT_SURICATA_SERVER, DEFAULT_TREX_SERVER, ...).
+EOF
   exit 0
 }
 
 binary_search_usage(){
   set +x
-  echo "Bash script to start pytest"
-  echo "Binary search mode"
-  echo "Usage:"
-  echo "  -bs | --binary-search <mm> <xm> <dr> <pr>"
-  echo ""
-  echo "Positional arguments:"
-  echo "  mm  | min-multiplier  [FLOAT]  Lowest bound of the search range. (required)"
-  echo "  xm  | max-multiplier  [FLOAT]  Highest bound of the search range. (required)"
-  echo "  dr  | drop-rate       [FLOAT]  Max allowed drop rate in % <0,100>. (required)"
-  echo "  pr  | precision       [FLOAT]  Exit when (xm - mm) < precision. (required)"
-  echo ""
-  echo "Examples:"
-  echo "  -bs 0.0 10.0 1.0 0.05"
+  cat <<'EOF'
+Bash script to start pytest - binary search mode
+
+Usage:
+  -bs | --binary-search <mm> <xm> <dr> <pr>
+
+Positional arguments:
+  mm  | min-multiplier  [FLOAT]  Lowest bound of the search range. (required)
+  xm  | max-multiplier  [FLOAT]  Highest bound of the search range. (required)
+  dr  | drop-rate       [FLOAT]  Max allowed drop rate in % <0,100>. (required)
+  pr  | precision       [FLOAT]  Exit when (xm - mm) < precision. (required)
+
+Examples:
+  -bs 0.0 10.0 1.0 0.05
+EOF
   exit 0
 }
 

From 04e080d0b82868ac6ecbe613478e74cf25f146eb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?D=C3=A1vid=20Hanko?= <david.hanko@cesnet.cz>
Date: Wed, 9 Sep 2026 13:24:48 +0200
Subject: [PATCH 2/4] docs: add .env.example and document all env fallback
 variables

Create .env.example listing all 13 fallback variables pytest_start.sh
consumes, with the corresponding script flags and built-in defaults.
Point the README's Environment variables section at it and complete the
variable list there (adds the previously undocumented
DEFAULT_SUITE_LOG_FILE; the flag mapping now accompanies each entry).
Also fix the -h help text to list every variable instead of an
ellipsis, so it no longer contradicts the PR description.
---
 .env.example    | 26 ++++++++++++++++++++++++++
 README.md       | 40 ++++++++++++++++++++++------------------
 pytest_start.sh | 11 +++++++----
 3 files changed, 55 insertions(+), 22 deletions(-)
 create mode 100644 .env.example

diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..9cd9920
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,26 @@
+# Example configuration for pytest_start.sh.
+#
+# Copy this file to `.env` and adjust the values. All variables are
+# optional: each one provides the default for the corresponding script
+# flag, so you don't have to pass it on every run. Variables marked with
+# "# -" have no built-in default; without them (or the matching flag)
+# the script either errors out or warns.
+#
+# Mandatory (script errors out without a flag or a value here):
+DEFAULT_SURICATA_SERVER="claret"        # -  (-s)
+DEFAULT_TREX_SERVER="trex2"             # -  (-tg)
+DEFAULT_TREX_PORT1="0000:b3:00.0"       # -  (-p1)
+DEFAULT_TREX_PORT2="0000:b3:00.1"       # -  (-p2)
+DEFAULT_PCIES="0000:3b:00.0"            # -  (-p, space-separated for multiple)
+
+# Mandatory for single-port tests (warns otherwise):
+DEFAULT_TARGET_MAC="08:C0:EB:88:C5:38"  # -  (-tm)
+
+# Optional (built-in defaults shown):
+DEFAULT_TARGET_VLAN=0                        # -  (-tv; untagged by default)
+DEFAULT_TESTS="http_simple nfs_smb_simple"   #    (-d; script default: http_simple)
+DEFAULT_TIME=300                             #    (-t)
+DEFAULT_HEATUP=0                             #    (-ht)
+DEFAULT_HUGEPAGES="6G"                       #    (-sh)
+LOGLEVEL="INFO"                              #    (-sl)
+DEFAULT_SUITE_LOG_FILE=false                 #    (-sf; set to true to enable)
diff --git a/README.md b/README.md
index c9b39d9..2aa35cf 100644
--- a/README.md
+++ b/README.md
@@ -133,31 +133,35 @@ If you want to pass a flag to pytest directly, you can do so by adding it after
 
 ### Environment variables
 
-Optionally you can create a `.env` file with default variables, so that you don't have to fill out the flags on every run of pytests.
-The file will look like this:
+Optionally you can create a `.env` file with default values, so that you don't have to fill out the flags on every run of pytest.
+Use [`.env.example`](.env.example) as a template - it lists all supported variables together with the corresponding `pytest_start.sh` flags:
 
 ```bash
-# Variables marked with "# -" don't have any default value, otherwise
-# default values are shown
+cp .env.example .env
+```
+
+The full list of variables (each maps to a script flag shown in parentheses):
 
+```bash
 # Mandatory flags
 # if these aren't set, you have to manually specify them every time
-DEFAULT_SURICATA_SERVER="claret"  # -
-DEFAULT_TREX_SERVER="trex2"       # -
-DEFAULT_TREX_PORT1="0000:b3:00.0" # -
-DEFAULT_TREX_PORT2="0000:b3:00.1" # -
-DEFAULT_PCIES="0000:3b:00.0"      # -
+DEFAULT_SURICATA_SERVER="claret"        # -  (-s)
+DEFAULT_TREX_SERVER="trex2"             # -  (-tg)
+DEFAULT_TREX_PORT1="0000:b3:00.0"       # -  (-p1)
+DEFAULT_TREX_PORT2="0000:b3:00.1"       # -  (-p2)
+DEFAULT_PCIES="0000:3b:00.0"            # -  (-p, space-separated for multiple)
 
 # Mandatory for single port tests
-DEFAULT_TARGET_MAC="08:C0:EB:88:C5:38" # -
-
-# Optional flags
-DEFAULT_TARGET_VLAN=15                     # -
-DEFAULT_TESTS="http_simple nfs_smb_simple" # all tests by default
-DEFAULT_TIME=300
-DEFAULT_HEATUP=0
-DEFAULT_HUGEPAGES="6G"
-LOGLEVEL="INFO"
+DEFAULT_TARGET_MAC="08:C0:EB:88:C5:38"  # -  (-tm)
+
+# Optional flags (if unset, the built-in defaults shown apply)
+DEFAULT_TARGET_VLAN=0                        # -  (-tv; untagged by default)
+DEFAULT_TESTS="http_simple nfs_smb_simple"   #    (-d; http_simple by default)
+DEFAULT_TIME=300                             #    (-t)
+DEFAULT_HEATUP=0                             #    (-ht)
+DEFAULT_HUGEPAGES="6G"                       #    (-sh)
+LOGLEVEL="INFO"                              #    (-sl)
+DEFAULT_SUITE_LOG_FILE=false                 #    (-sf; set to true to enable)
 ```
 
 Note that an empty string ("") in `-d` (or `DEFAULT_TESTS`) is a valid value for running all tests
diff --git a/pytest_start.sh b/pytest_start.sh
index a5fc6c8..17a8355 100755
--- a/pytest_start.sh
+++ b/pytest_start.sh
@@ -46,9 +46,9 @@ Traffic:
   -tv   --target-vlan [VLAN_ID]        VLAN tag to use for generated traffic (default: 0)
   -pm   --prefer-trex-mode [MODE]      Suggest a mode for TRex. If unavailable,
                                         tests use their defaults
-  -fm   --force-trex-mode [MODE]        Force a TRex mode. If unavailable, tests get
+  -fm   --force-trex-mode [MODE]       Force a TRex mode. If unavailable, tests get
                                         skipped. Overrides -pm
-  -sb   --trex-stl-burst [PPS] [COUNT]  Send a fixed burst of COUNT packets at PPS
+  -sb   --trex-stl-burst [PPS] [COUNT] Send a fixed burst of COUNT packets at PPS
                                         in STL mode.
                                         Defaults: 200 000 PPS, 10 000 000 packets
 
@@ -72,8 +72,11 @@ Advanced:
                                         Enable automatic throughput search
   -bsh  --binary-search-help           Show help for binary search mode
 
-Defaults for connection options can also be set in a .env file in the
-repository root (DEFAULT_SURICATA_SERVER, DEFAULT_TREX_SERVER, ...).
+Defaults for all options can also be set in a .env file in the repository
+root; see .env.example for the full list of variables
+(DEFAULT_SURICATA_SERVER, DEFAULT_TREX_SERVER, DEFAULT_TREX_PORT1, DEFAULT_TREX_PORT2,
+DEFAULT_PCIES, DEFAULT_TARGET_MAC, DEFAULT_TARGET_VLAN, DEFAULT_TESTS, DEFAULT_TIME, DEFAULT_HEATUP,
+DEFAULT_HUGEPAGES, DEFAULT_SUITE_LOG_FILE, LOGLEVEL).
 EOF
   exit 0
 }

From adde3feca727e3f0478e122ef4812001a7d04f8e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?D=C3=A1vid=20Hanko?= <david.hanko@cesnet.cz>
Date: Wed, 9 Sep 2026 13:28:16 +0200
Subject: [PATCH 3/4] docs: use generic placeholders in .env.example

Replace real hostnames and MAC address with generic placeholders
so the example file doesn't reference specific lab machines.
---
 .env.example | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/.env.example b/.env.example
index 9cd9920..1fa8d96 100644
--- a/.env.example
+++ b/.env.example
@@ -7,14 +7,14 @@
 # the script either errors out or warns.
 #
 # Mandatory (script errors out without a flag or a value here):
-DEFAULT_SURICATA_SERVER="claret"        # -  (-s)
-DEFAULT_TREX_SERVER="trex2"             # -  (-tg)
+DEFAULT_SURICATA_SERVER="suricata_server_name"        # -  (-s)
+DEFAULT_TREX_SERVER="trex_server_name"             # -  (-tg)
 DEFAULT_TREX_PORT1="0000:b3:00.0"       # -  (-p1)
 DEFAULT_TREX_PORT2="0000:b3:00.1"       # -  (-p2)
 DEFAULT_PCIES="0000:3b:00.0"            # -  (-p, space-separated for multiple)
 
 # Mandatory for single-port tests (warns otherwise):
-DEFAULT_TARGET_MAC="08:C0:EB:88:C5:38"  # -  (-tm)
+DEFAULT_TARGET_MAC="01:C2:EG:48:DE:FF"  # -  (-tm)
 
 # Optional (built-in defaults shown):
 DEFAULT_TARGET_VLAN=0                        # -  (-tv; untagged by default)

From 8889ec0d257f3a1f6ee63cbac86190570809c923 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?D=C3=A1vid=20Hanko?= <david.hanko@cesnet.cz>
Date: Wed, 9 Sep 2026 13:40:37 +0200
Subject: [PATCH 4/4] ci: install only ruff in the lint job

The lint job needs nothing but ruff, yet it installed the entire
requirements.txt (lbr_trex_client, scapy, paramiko, cryptography
builds). Extract the pinned ruff version from requirements.txt
instead, keeping CI and the declared dependency in sync while making
the job faster and less flaky.
---
 .github/workflows/lint.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index 3563a87..9ac9f78 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -18,10 +18,10 @@ jobs:
         with:
           python-version: "3.11"
 
-      - name: Install dependencies
+      - name: Install ruff
         run: |
           python -m pip install --upgrade pip
-          pip install -r requirements.txt
+          pip install "ruff==$(grep -oP '^ruff==\K.*' requirements.txt)"
 
       - name: Ruff check
         id: ruff_check