Hands-on 04-sabnzbd-and-usenet-downloading: Lab

name

Build and validate an offline SABnzbd policy

scope

Every file created, modified, or deleted by this lab is located beneath /opt/lab-classroom/class52/. The lab performs no network access, installs no packages, starts no services, and contains no provider credentials.

steps

step

1

title

Create the isolated directory layout

command

install -d -m 0750 /opt/lab-classroom/class52/incomplete /opt/lab-classroom/class52/complete/documents /opt/lab-classroom/class52/complete/audio /opt/lab-classroom/class52/complete/video /opt/lab-classroom/class52/config /opt/lab-classroom/class52/input /opt/lab-classroom/class52/reports

explanation

This creates separate incomplete and completed trees and three category destinations. The permissions avoid world-accessible directories while leaving final ownership decisions to the administrator.

step

2

title

Create a deployment policy

command

cat > /opt/lab-classroom/class52/config/policy.ini <<'EOF'
[management]
bind_host = 127.0.0.1
bind_port = 8080
require_authentication = true

[provider]
tls_required = true
tls_port = 563
connections = 4
provider_priority = 0

[storage]
incomplete_dir = /opt/lab-classroom/class52/incomplete
complete_root = /opt/lab-classroom/class52/complete

[categories]
documents = /opt/lab-classroom/class52/complete/documents
audio = /opt/lab-classroom/class52/complete/audio
video = /opt/lab-classroom/class52/complete/video
EOF
chmod 0640 /opt/lab-classroom/class52/config/policy.ini

explanation

This is an offline policy model rather than a live SABnzbd-generated configuration. It deliberately contains no hostname, username, password, or API key. The loopback bind and authentication requirement document the intended management posture.

step

3

title

Create a harmless synthetic NZB

command

cat > /opt/lab-classroom/class52/input/training.nzb <<'EOF'

documents
Homelab Academy Synthetic Training Job



example.training


class52-segment@example.invalid



EOF
chmod 0640 /opt/lab-classroom/class52/input/training.nzb

explanation

The document demonstrates the shape of NZB metadata using reserved invalid domains and a fictional group. It references no retrievable content and is never sent to a server.

step

4

title

Create the offline validator

command

cat > /opt/lab-classroom/class52/validate.py <<'PY'
from configparser import ConfigParser
from pathlib import Path
import json
import xml.etree.ElementTree as ET

root = Path('/opt/lab-classroom/class52').resolve()
policy_path = root / 'config' / 'policy.ini'
nzb_path = root / 'input' / 'training.nzb'
report_path = root / 'reports' / 'validation.json'

cfg = ConfigParser()
loaded = cfg.read(policy_path)
if not loaded:
raise SystemExit('Policy file could not be read')

def inside_root(value):
candidate = Path(value).resolve()
return candidate == root or root in candidate.parents

incomplete = cfg.get('storage', 'incomplete_dir')
complete_root = cfg.get('storage', 'complete_root')
category_paths = dict(cfg.items('categories'))
checks = {
'management_is_loopback': cfg.get('management', 'bind_host') in {'127.0.0.1', '::1', 'localhost'},
'authentication_required': cfg.getboolean('management', 'require_authentication'),
'provider_tls_required': cfg.getboolean('provider', 'tls_required'),
'provider_tls_port_is_563': cfg.getint('provider', 'tls_port') == 563,
'connection_count_is_conservative': 1 <= cfg.getint('provider', 'connections') <= 8,
'incomplete_path_is_scoped': inside_root(incomplete),
'complete_path_is_scoped': inside_root(complete_root),
'incomplete_and_complete_are_distinct': Path(incomplete).resolve() != Path(complete_root).resolve(),
'all_category_paths_are_scoped': all(inside_root(path) for path in category_paths.values()),
'all_category_paths_are_under_complete': all(Path(complete_root).resolve() in Path(path).resolve().parents for path in category_paths.values())
}

xml_root = ET.parse(nzb_path).getroot()
namespace = {'n': 'http://www.newzbin.com/DTD/2003/nzb'}
files = xml_root.findall('n:file', namespace)
segments = xml_root.findall('.//n:segment', namespace)
category_node = xml_root.find("n:head/n:meta[@type='category']", namespace)
category = category_node.text.strip() if category_node is not None and category_node.text else ''
checks['nzb_has_file_entry'] = len(files) > 0
checks['nzb_has_segment_entry'] = len(segments) > 0
checks['nzb_category_is_mapped'] = category in category_paths
checks['synthetic_identifiers_use_invalid_domain'] = all((segment.text or '').strip().endswith('@example.invalid') for segment in segments)

report = {
'lab_root': str(root),
'nzb_category': category,
'file_entries': len(files),
'segment_entries': len(segments),
'checks': checks,
'overall_pass': all(checks.values())
}
report_path.write_text(json.dumps(report, indent=2) + '\n', encoding='utf-8')
print(json.dumps(report, indent=2))
raise SystemExit(0 if report['overall_pass'] else 1)
PY
chmod 0750 /opt/lab-classroom/class52/validate.py

explanation

The validator confirms local-only administration, authentication intent, TLS policy, path containment, incomplete/completed separation, category mappings, and the structure of the synthetic NZB.

step

5

title

Run the validator

command

python3 /opt/lab-classroom/class52/validate.py

explanation

The command parses local files only and writes the report to /opt/lab-classroom/class52/reports/validation.json.

step

6

title

Inspect the resulting permissions and report

command

find /opt/lab-classroom/class52 -maxdepth 3 -printf '%M %p\n' | sort && cat /opt/lab-classroom/class52/reports/validation.json

explanation

Confirm that configuration and NZB files are not world-readable, the intended directory hierarchy exists, and every validation check is true.