System Configuration Reference

Canonical Structure And Field Semantics For system.json.

• Config file: src/pypnm/settings/system.json
• ConfigManager class: src/pypnm/config/config_manager.py
• PnmConfigManager class: src/pypnm/config/pnm_config_manager.py

Table Of Contents

• 1. FastApiRequestDefault
• 2. SNMP
• 3. PnmBulkDataTransfer
• 4. PnmFileRetrieval
• 5. PnmArtifactStorage
• 6. Logging
• 7. TestMode
• Loading Configuration

1. FastApiRequestDefault

Default Parameters For REST Requests To The FastAPI Service.

"FastApiRequestDefault": {
  "mac_address": "aa:bb:cc:dd:ee:ff",
  "ip_address": "192.168.0.100"
}

Field	Type	Description
mac_address	string	Default device MAC address.
ip_address	string	Default device IP (IPv4 or IPv6).

2. SNMP

Global SNMP Settings, Including Version-Specific Options.

"SNMP": {
  "timeout": 2,
  "version": {
    "2c": {
      "enable": true,
      "retries": 3,
      "read_community": "public",
      "write_community": "private"
    },
    "3": {
      "enable": false,
      "retries": 3,
      "username": "user",
      "securityLevel": "authPriv",
      "authProtocol": "SHA",
      "authPassword": "pass",
      "privProtocol": "AES",
      "privPassword": "privpass"
    }
  }
}

Top-Level

Field	Type	Description
timeout	number	Per-request timeout (seconds).
version	object	Container for v2c/v3 configuration versions.

SNMP v2c

Field	Type	Description
enable	boolean	Enable v2c operations.
retries	number	Retry count on timeout/failure.
read_community	string	Community for GET/WALK.
write_community	string	Community for SET.

SNMP v3

Field	Type	Description
enable	boolean	Enable v3 operations.
retries	number	Retry count on timeout/failure.
username	string	Security name.
securityLevel	string	noAuthNoPriv, authNoPriv, or authPriv.
authProtocol	string	For example MD5, SHA.
authPassword	string	Required when auth* is used.
privProtocol	string	For example DES, AES.
privPassword	string	Required when *Priv is used.

3. PnmBulkDataTransfer

Transport Parameters For CM-Generated Files (for example, RxMER, FEC Summary) Sent To A Server.

"PnmBulkDataTransfer": {
  "method": "tftp",
  "tftp": {
    "ip_v4": "192.168.0.10",
    "ip_v6": "::1",
    "remote_dir": ""
  },
  "http": {
    "base_url": "http://files.example.com/",
    "port": 80
  },
  "https": {
    "base_url": "https://files.example.com/",
    "port": 443
  }
}

Field	Type	Description
method	string	Preferred bulk method: tftp, http, or https.
tftp.*	object	TFTP targets for IPv4/IPv6 plus optional remote directory.
http.*	object	HTTP base URL and port for file delivery.
https.*	object	HTTPS base URL and port for file delivery.

4. PnmFileRetrieval

Local Storage Layout And Remote Retrieval Methods.

Related Guide: File Transfer Methods

"PnmFileRetrieval": {
  "pnm_dir": ".data/pnm",
  "csv_dir": ".data/csv",
  "json_dir": ".data/json",
  "xlsx_dir": ".data/xlsx",
  "png_dir": ".data/png",
  "archive_dir": ".data/archive",
  "msg_rsp_dir": ".data/msg_rsp",
  "transaction_db": ".data/db/transactions.json",
  "capture_group_db": ".data/db/capture_group.json",
  "session_group_db": ".data/db/session_group.json",
  "operation_db": ".data/db/operation_capture.json",
  "json_transaction_db": ".data/db/json_transactions.json",
  "retries": 5,
  "retrieval_method": {
    "method": "local",
    "methods": {
      "local": {
        "src_dir": "/srv/tftp"
      },
      "tftp": {
        "host": "localhost",
        "port": 69,
        "timeout": 5,
        "remote_dir": ""
      },
      "ftp": {
        "host": "localhost",
        "port": 21,
        "tls": false,
        "timeout": 5,
        "user": "user",
        "password_enc": "",
        "remote_dir": "/srv/tftp"
      },
      "sftp": {
        "host": "localhost",
        "port": 22,
        "user": "user",
        "password_enc": "",
        "private_key_path": "",
        "remote_dir": "/srv/tftp"
      },
      "http": {
        "base_url": "http://STUB/",
        "port": 80
      },
      "https": {
        "base_url": "https://STUB/",
        "port": 443
      }
    }
  }
}

password_enc is the only supported password field for file retrieval methods. Plaintext password is not supported.

Directories And Databases

Field	Type	Description
pnm_dir	string	Local storage for raw PNM binaries.
csv_dir	string	Local storage for derived CSVs.
json_dir	string	Local storage for derived JSON.
xlsx_dir	string	Local storage for Excel reports.
png_dir	string	Local storage for generated PNGs.
archive_dir	string	Local storage for analysis ZIP archives.
msg_rsp_dir	string	Local storage for message/response metadata.
transaction_db	string	JSON ledger of file transactions.
capture_group_db	string	JSON map of grouped transactions.
session_group_db	string	JSON map of session groups.
operation_db	string	JSON map of operation to capture group.
json_transaction_db	string	JSON map of JSON transaction metadata.

Retrieval Settings

Field	Type	Description
retrieval_method.method	string	Active retrieval method: local, tftp, ftp, sftp, http, https.
retrieval_method.methods.local.src_dir	string	Source directory to watch/copy from when using local.
retrieval_method.methods.tftp.*	object	TFTP host/port/timeout and remote directory.
retrieval_method.methods.ftp.*	object	FTP connection, credentials, and remote directory.
retrieval_method.methods.sftp.*	object	SFTP connection and remote directory.
retrieval_method.methods.http.*	object	HTTP base URL and port.
retrieval_method.methods.https.*	object	HTTPS base URL and port.
retries	number	Max attempts per retrieval operation.

The legacy key name retrival_method is accepted for backward compatibility.

5. PnmArtifactStorage

Policy-Driven Compression And Cache Settings For .data/pnm Artifacts And /tmp Materialization.

"PnmArtifactStorage": {
  "compression": {
    "enabled": true,
    "min_bytes": 4096,
    "conditional_max_ratio": 0.92,
    "conditional_min_savings_bytes": 8192,
    "deny": [
      "ds_ofdm_chan_est_coef"
    ],
    "always": [
      "ds_ofdm_codeword_error_rate",
      "ds_ofdm_modulation_profile"
    ],
    "conditional": [
      "ds_ofdm_rxmer_per_subcar",
      "us_pre_equalizer_coef"
    ],
    "primary_codec": "zstd",
    "gzip_fallback": true,
    "zstd_level": 3,
    "gzip_level": 6
  },
  "cache": {
    "tmp_root": "/tmp/pypnm",
    "ingress_dir": "ingress",
    "materialized_dir": "materialized",
    "ingress_ttl_seconds": 900,
    "materialized_ttl_seconds": 86400,
    "cleanup_interval_seconds": 3600
  }
}

Compression Policy

Field	Type	Description
enabled	bool	Enables compression decisions for PNM artifacts.
min_bytes	int	Skip compression below this size (bytes).
conditional_max_ratio	float	Max compressed/original ratio for conditional types.
conditional_min_savings_bytes	int	Minimum byte savings for conditional compression.
deny	array	PNM types that never compress.
always	array	PNM types that always compress.
conditional	array	PNM types that compress if thresholds are met.
primary_codec	string	Primary codec (zstd).
gzip_fallback	bool	Allow gzip when zstd is unavailable.
zstd_level	int	Zstd compression level.
gzip_level	int	Gzip compression level.

Cache Settings

Tmp cache cleanup runs in a background thread at startup using cleanup_interval_seconds. The cron helper script provides a backup cleanup path when the application is not running. Ingress cache files are stored flat under the ingress directory (no transaction subdirectories).

Field	Type	Description
tmp_root	string	Root directory for ingress/materialized caches.
ingress_dir	string	Ingress cache directory name under tmp_root.
materialized_dir	string	Materialized cache directory name under tmp_root.
ingress_ttl_seconds	int	TTL for ingress cache content.
materialized_ttl_seconds	int	TTL for materialized cache content.
cleanup_interval_seconds	int	Minimum seconds between opportunistic cleanups.

6. Logging

Application Logging Options.

"logging": {
  "log_level": "INFO",
  "log_dir": "logs",
  "log_filename": "pypnm.log"
}

Field	Type	Description
log_level	string	DEBUG, INFO, WARN, or ERROR.
log_dir	string	Directory for log files.
log_filename	string	Log filename (created under log_dir).

7. TestMode

Global And Class-Specific Test-Mode Controls.

"TestMode": {
  "global": {
    "mode": {
      "enable": true
    }
  },
  "class_name": {
    "DsScQamChannelSpectrumAnalyzer": {
      "mode": {
        "enable": true
      }
    }
  }
}

Field	Type	Description
global.mode.enable	boolean	Enable or disable global test mode.
class_name..mode.enable	boolean	Per-class override for test mode, keyed by class name.

Loading Configuration

Typical Access Pattern Using The Manager Abstractions.

from pypnm.config.config_manager import ConfigManager
from pypnm.config.pnm_config_manager import PnmConfigManager

cfg = ConfigManager()

mac = cfg.get("FastApiRequestDefault", "mac_address")
ip  = cfg.get("FastApiRequestDefault", "ip_address")

pnm_cfg = PnmConfigManager()
tftp_v4 = pnm_cfg.get("PnmBulkDataTransfer", "tftp")["ip_v4"]