diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..1fa8d96 --- /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="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="01:C2:EG:48:DE:FF" # - (-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/.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 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 c152377..17a8355 100755 --- a/pytest_start.sh +++ b/pytest_start.sh @@ -14,50 +14,90 @@ 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//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/