firewatcher 1.63__tar.gz → 1.64__tar.gz

{firewatcher-1.63/firewatcher.egg-info → firewatcher-1.64}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: firewatcher
-Version: 1.63
+Version: 1.64
 Summary: Watch logs for incident patterns and persist surrounding context off-box
 Home-page: https://github.com/yufei-pan/firewatcher
 Author: Yufei Pan
@@ -131,7 +131,7 @@ Useful flags:
 | Flag | Description |
 |------|-------------|
 | `--unit-name NAME` | Unit name (default: `firewatcher`) |
-| `--requires-mounts-for PATH` | Add `RequiresMountsFor=` (repeat for NFS/remote output) |
+| `--requires-mounts-for PATH` | Add `RequiresMountsFor=` (repeat for NFS/remote output). Each path is made absolute and normalized as text (`.`, `..`, `//`, a trailing `/`; symlinks are not followed, as systemd follows none), quoted for you when it has spaces, quotes or backslashes, and refused if it has a newline or is not UTF-8 (systemd cannot read either back there) |
 | `--no-enable` | Write the unit and reload, but do not enable or start it |
 
 ```bash

{firewatcher-1.63 → firewatcher-1.64}/README.md

@@ -104,7 +104,7 @@ Useful flags:
 | Flag | Description |
 |------|-------------|
 | `--unit-name NAME` | Unit name (default: `firewatcher`) |
-| `--requires-mounts-for PATH` | Add `RequiresMountsFor=` (repeat for NFS/remote output) |
+| `--requires-mounts-for PATH` | Add `RequiresMountsFor=` (repeat for NFS/remote output). Each path is made absolute and normalized as text (`.`, `..`, `//`, a trailing `/`; symlinks are not followed, as systemd follows none), quoted for you when it has spaces, quotes or backslashes, and refused if it has a newline or is not UTF-8 (systemd cannot read either back there) |
 | `--no-enable` | Write the unit and reload, but do not enable or start it |
 
 ```bash

{firewatcher-1.63 → firewatcher-1.64/firewatcher.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: firewatcher
-Version: 1.63
+Version: 1.64
 Summary: Watch logs for incident patterns and persist surrounding context off-box
 Home-page: https://github.com/yufei-pan/firewatcher
 Author: Yufei Pan
@@ -131,7 +131,7 @@ Useful flags:
 | Flag | Description |
 |------|-------------|
 | `--unit-name NAME` | Unit name (default: `firewatcher`) |
-| `--requires-mounts-for PATH` | Add `RequiresMountsFor=` (repeat for NFS/remote output) |
+| `--requires-mounts-for PATH` | Add `RequiresMountsFor=` (repeat for NFS/remote output). Each path is made absolute and normalized as text (`.`, `..`, `//`, a trailing `/`; symlinks are not followed, as systemd follows none), quoted for you when it has spaces, quotes or backslashes, and refused if it has a newline or is not UTF-8 (systemd cannot read either back there) |
 | `--no-enable` | Write the unit and reload, but do not enable or start it |
 
 ```bash

{firewatcher-1.63 → firewatcher-1.64}/firewatcher.py

@@ -31,7 +31,7 @@ import syslog
 import threading
 import zlib
 
-version = '1.63'
+version = '1.64'
 __version__ = version
 
 DEFAULT_OUTPUT_FOLDER = '/var/log/captured_messages/'
@@ -914,11 +914,41 @@ def resolve_settings(args, environ=None):
 	settings.ntfy_url = (settings.ntfy_url or '').strip()
 	settings.unit_name = getattr(args, 'unit_name', None) or DEFAULT_UNIT_NAME
 	settings.no_enable = bool(getattr(args, 'no_enable', False))
-	settings.requires_mounts_for = list(getattr(args, 'requires_mounts_for', None) or [])
+	settings.requires_mounts_for = _mount_paths(getattr(args, 'requires_mounts_for', None))
 	validate_settings(settings)
 	return settings
 
 
+def _mount_paths(paths):
+	"""The --requires-mounts-for paths for the unit, with empty ones dropped.
+
+	systemd ignores a relative or unnormalized path in RequiresMountsFor= with a warning, so each path is
+	made absolute and normalized as text ('.', '..', '//' and a trailing '/'). The file system is not
+	touched: symlinks are not followed (systemd follows none either, and one inside a remote share would
+	lead off it), and a hung NFS mount or an automount point can't stall or trigger anything. The work is
+	done on the path's bytes, so the locale doesn't matter. A newline or carriage return can't be written
+	in any form systemd reads back, and systemd rejects a path that is not UTF-8, so those are refused,
+	before anything is installed."""
+	result = []
+	for path in paths or []:
+		if not path:
+			continue
+		try:
+			raw = os.path.abspath(os.fsencode(path))
+		except OSError as exc:  # a relative path, and the current directory is gone
+			raise ConfigError('--requires-mounts-for cannot make %r absolute: %s' % (path, exc))
+		raw = b'/' + raw.lstrip(b'/')  # POSIX normpath keeps a leading '//'; systemd does not accept it
+		if b'\n' in raw or b'\r' in raw:
+			raise ConfigError('--requires-mounts-for cannot take a path with a newline or carriage return, '
+							  'which systemd cannot read back from a unit file: %r' % os.fsdecode(raw))
+		try:
+			result.append(raw.decode('utf-8'))
+		except UnicodeError:
+			raise ConfigError('--requires-mounts-for cannot take a path that is not UTF-8, which systemd '
+							  'rejects: %r' % os.fsdecode(raw))
+	return result
+
+
 def validate_settings(settings):
 	if settings.llm_enabled and (not settings.llm_base_url or not settings.llm_model):
 		raise ConfigError('LLM analysis requires base_url and model (--llm-base-url and --llm-model, or llm.base_url and llm.model in the config)')
@@ -2295,6 +2325,17 @@ def _quote_unit_arg(value, program=False):
 
 
 
+def _quote_unit_path(path):
+	"""A path for RequiresMountsFor=, a space-separated list in which systemd expands % specifiers. A path
+	with whitespace, a quote or a backslash goes in double quotes, with the backslash and the double quote
+	each prefixed by a backslash: that is all systemd reads back there. It has no \\n, so a newline does not
+	survive (such a path is refused in _mount_paths), unlike in an ExecStart argument."""
+	path = path.replace('%', '%%')
+	if any(ch.isspace() or ch in '"\'\\' for ch in path):
+		path = '"' + path.replace('\\', '\\\\').replace('"', '\\"') + '"'
+	return path
+
+
 def render_unit_file(args, executable=None, config_exists=None, raw=None):
 	"""Render a systemd unit. Does not require systemd to be present."""
 	resolved, raw = _prepare_unit_settings(args, raw=raw)
@@ -2323,7 +2364,7 @@ def render_unit_file(args, executable=None, config_exists=None, raw=None):
 		'Wants=' + ' '.join(wants),
 	]
 	for mount in requires:
-		lines.append('RequiresMountsFor=' + mount)
+		lines.append('RequiresMountsFor=' + _quote_unit_path(mount))
 	stop_sec = max(30, int(resolved.llm_timeout) + int(resolved.ntfy_timeout) + 15)
 	lines.extend([
 		'',
@@ -2503,7 +2544,7 @@ def build_parser():
 	svc.add_argument('--print-unit', action='store_true', help='Print the systemd unit that --install-service would write, then exit. Works without systemd.')
 	svc.add_argument('--uninstall-service', action='store_true', help='Disable and remove the systemd unit. Warns and exits if systemd is not available.')
 	parser.add_argument('--unit-name', type=str, default=DEFAULT_UNIT_NAME, help='systemd unit name (default: firewatcher).')
-	parser.add_argument('--requires-mounts-for', action='append', default=[], metavar='PATH', help='Add RequiresMountsFor= to the unit (repeatable). Use when -o is on NFS or another remote filesystem.')
+	parser.add_argument('--requires-mounts-for', action='append', default=[], metavar='PATH', help='Add RequiresMountsFor= to the unit (repeatable). Use when -o is on NFS or another remote filesystem. The path is made absolute and normalized (symlinks are not followed); one with a newline or not in UTF-8 is refused.')
 	parser.add_argument('--no-enable', action='store_true', help='With --install-service, write the unit and daemon-reload but do not enable or start it.')
 
 	parser.add_argument('--config', default=None, help='INI config file. Default: /etc/firewatcher/firewatcher.conf when that file exists. An explicit path must exist. CLI flags override the file.')

{firewatcher-1.63 → firewatcher-1.64}/tests/test_cli.py

@@ -104,7 +104,7 @@ def test_parser_rejects_conflicting_service_flags():
 def test_module_has_no_nebula_product_name():
     src = open(fw.__file__, encoding='utf-8').read().lower()
     assert 'nebula' not in src
-    assert fw.version == '1.63'
+    assert fw.version == '1.64'
     assert fw.__version__ == fw.version
 
 

{firewatcher-1.63 → firewatcher-1.64}/tests/test_systemd.py

@@ -535,3 +535,184 @@ def test_quote_unit_arg_keeps_a_bare_semicolon_and_newlines_inside_one_argument(
     # A bare ';' ends an ExecStart command, and a raw newline would end the line (or add a directive).
     assert fw._quote_unit_arg(';') == '";"'
     assert fw._quote_unit_arg('m\nExecStartPre=/bin/false\r') == '"m\\nExecStartPre=/bin/false\\r"'
+
+
+# --- RequiresMountsFor= paths ---
+# Checked against systemd 257: a bind mount at each path, then which mount unit the unit's After= named.
+
+def _mounts_line(*paths):
+    argv = ['--print-unit']
+    for path in paths:
+        argv += ['--requires-mounts-for', path]
+    unit = fw.render_unit_file(parse_cli(argv + ['/etc/firewatcher/patterns.d']), executable='/bin/fw')
+    return [line for line in unit.splitlines() if line.startswith('RequiresMountsFor=')]
+
+
+def _systemd_reads(value):
+    """How systemd reads one RequiresMountsFor= value: words split on whitespace, quotes group, a backslash
+    inside double quotes takes the next character, %% is one %."""
+    words, word, quoted, started, chars = [], '', False, False, iter(value)
+    for ch in chars:
+        if quoted and ch == '\\':
+            word += next(chars)
+        elif ch == '"':
+            quoted, started = not quoted, True
+        elif ch.isspace() and not quoted:
+            if started or word:
+                words.append(word)
+            word, started = '', False
+        else:
+            word += ch
+    if started or word:
+        words.append(word)
+    return [w.replace('%%', '%') for w in words]
+
+
+@pytest.mark.parametrize('path, line', [
+    ('/mnt/logs/captured_messages', 'RequiresMountsFor=/mnt/logs/captured_messages'),
+    ('/mnt/a$b', 'RequiresMountsFor=/mnt/a$b'),
+    ('/mnt/a;b', 'RequiresMountsFor=/mnt/a;b'),
+    ('/mnt/a#b', 'RequiresMountsFor=/mnt/a#b'),
+    ('/mnt/my logs', 'RequiresMountsFor="/mnt/my logs"'),
+    ('/mnt/a\tb', 'RequiresMountsFor="/mnt/a\tb"'),
+    ('/mnt/100%', 'RequiresMountsFor=/mnt/100%%'),
+    ('/mnt/%h y', 'RequiresMountsFor="/mnt/%%h y"'),
+    ('/mnt/a"b', 'RequiresMountsFor="/mnt/a\\"b"'),
+    ('/mnt/a\\b', 'RequiresMountsFor="/mnt/a\\\\b"'),
+    ("/mnt/a'b", 'RequiresMountsFor="/mnt/a\'b"'),
+    ('/mnt/a b\\', 'RequiresMountsFor="/mnt/a b\\\\"'),
+    ('/mnt/a"b c\\d', 'RequiresMountsFor="/mnt/a\\"b c\\\\d"'),
+])
+def test_requires_mounts_for_line_is_quoted_so_systemd_reads_the_path_back(path, line):
+    assert _mounts_line(path) == [line]
+    assert _systemd_reads(line.partition('=')[2]) == [path]
+
+
+def test_requires_mounts_for_paths_are_normalized_as_text(tmp_path):
+    # systemd ignores '..', '//' and '.' ("not normalized"); normalize as text, follow no symlinks.
+    assert _mounts_line('/mnt/logs/') == ['RequiresMountsFor=/mnt/logs']
+    assert _mounts_line('//mnt/./logs') == ['RequiresMountsFor=/mnt/logs']
+    assert _mounts_line('/mnt/nfs/../logs') == ['RequiresMountsFor=/mnt/logs']
+    assert _mounts_line('/mnt/a..b') == ['RequiresMountsFor=/mnt/a..b']
+    (tmp_path / 'nfs').mkdir()
+    (tmp_path / 'data').symlink_to(tmp_path / 'nfs')
+    assert _mounts_line(str(tmp_path / 'data' / 'logs')) == ['RequiresMountsFor=%s' % (tmp_path / 'data' / 'logs')]
+
+
+def test_requires_mounts_for_touches_no_file(monkeypatch):
+    # A hung hard NFS mount or an automount point must not stall or trigger anything.
+    def no_fs(*args, **kwargs):
+        raise AssertionError('the file system was touched')
+
+    for name in ('lstat', 'stat', 'readlink'):
+        monkeypatch.setattr(fw.os, name, no_fs)
+    assert fw._mount_paths(['/mnt/nfs/../logs', '/mnt/x']) == ['/mnt/logs', '/mnt/x']
+
+
+def test_requires_mounts_for_refuses_a_newline_the_current_directory_brings_in(tmp_path, monkeypatch):
+    odd = tmp_path / 'a\nb'
+    odd.mkdir()
+    monkeypatch.chdir(str(odd))
+    with pytest.raises(fw.ConfigError) as err:
+        fw.resolve_settings(parse_cli(['--print-unit', '--requires-mounts-for', 'logs', 'p.d']), environ={})
+    assert 'newline' in str(err.value)
+
+
+def test_requires_mounts_for_keeps_a_utf8_path_whatever_python_decoded(tmp_path):
+    # Python 3.6 under a C locale hands over 'caf\u00e9' as surrogate-escaped bytes; the unit gets the text.
+    path = b'/mnt/caf\xc3\xa9'.decode('ascii', 'surrogateescape')
+    assert _mounts_line(path) == ['RequiresMountsFor=/mnt/caf\u00e9']
+
+
+def test_requires_mounts_for_refuses_a_path_that_is_not_utf8():
+    path = b'/mnt/caf\xe9'.decode('utf-8', 'surrogateescape')
+    with pytest.raises(fw.ConfigError) as err:
+        fw.resolve_settings(parse_cli(['--print-unit', '--requires-mounts-for', path, 'p.d']), environ={})
+    assert 'not UTF-8' in str(err.value)
+
+
+def test_requires_mounts_for_relative_path_with_the_current_directory_gone(monkeypatch):
+    def gone():
+        raise FileNotFoundError(2, 'No such file or directory')
+
+    monkeypatch.setattr(fw.os, 'getcwd', gone)
+    monkeypatch.setattr(fw.os, 'getcwdb', gone)
+    with pytest.raises(fw.ConfigError) as err:
+        fw.resolve_settings(parse_cli(['--print-unit', '--requires-mounts-for', 'logs', 'p.d']), environ={})
+    assert 'cannot make' in str(err.value)
+
+
+def test_requires_mounts_for_relative_path_in_a_non_utf8_directory_is_refused(tmp_path, monkeypatch):
+    # The current directory's bytes count too: the resolved path must be UTF-8 as a whole.
+    odd = os.path.join(os.fsencode(str(tmp_path)), b'caf\xe9')
+    os.mkdir(odd)
+    monkeypatch.chdir(odd)
+    with pytest.raises(fw.ConfigError) as err:
+        fw.resolve_settings(parse_cli(['--print-unit', '--requires-mounts-for', 'logs', 'p.d']), environ={})
+    assert 'not UTF-8' in str(err.value)
+
+
+def test_requires_mounts_for_keeps_each_path_a_separate_line_and_adds_remote_fs():
+    lines = _mounts_line('/mnt/my logs', '/mnt/b')
+    assert lines == ['RequiresMountsFor="/mnt/my logs"', 'RequiresMountsFor=/mnt/b']
+    unit = fw.render_unit_file(parse_cli(['--print-unit', '--requires-mounts-for', '/mnt/my logs', 'p.d']),
+                               executable='/bin/fw')
+    assert 'remote-fs.target' in unit
+
+
+def test_requires_mounts_for_makes_a_relative_path_absolute(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    assert _mounts_line('nfs/logs') == ['RequiresMountsFor=' + str(tmp_path / 'nfs' / 'logs')]
+    assert _mounts_line('./a b') == ['RequiresMountsFor="%s"' % (tmp_path / 'a b')]
+    assert fw.resolve_settings(parse_cli(['--requires-mounts-for', 'x', 'p.d']),
+                               environ={}).requires_mounts_for == [str(tmp_path / 'x')]
+
+
+def test_requires_mounts_for_empty_path_is_dropped():
+    assert _mounts_line('') == []
+
+
+@pytest.mark.parametrize('path', ['/mnt/a\nb', '/mnt/a\rb', 'rel\nx'])
+def test_requires_mounts_for_refuses_a_newline_or_carriage_return(path, capsys):
+    with pytest.raises(fw.ConfigError) as exc:
+        fw.resolve_settings(parse_cli(['--requires-mounts-for', path, 'p.d']), environ={})
+    assert '--requires-mounts-for' in str(exc.value)
+    assert 'newline' in str(exc.value)
+    with pytest.raises(SystemExit) as exit_info:
+        fw.main(['--print-unit', '--requires-mounts-for', path])
+    assert exit_info.value.code == 2
+    assert '--requires-mounts-for' in capsys.readouterr().err
+
+
+def test_install_refuses_a_bad_mount_path_before_writing_anything(tmp_path, capsys):
+    unit_dir = tmp_path / 'system'
+    patterns = tmp_path / 'patterns.d'
+    out = tmp_path / 'captures'
+    calls = []
+    parsed = parse_cli(['--install-service', '-o', str(out), '--requires-mounts-for', '/mnt/a\nb', str(patterns)])
+    rc = fw.install_service(parsed, systemd_available=True, unit_dir=str(unit_dir),
+                            systemctl=systemctl_recorder(calls), executable='/bin/fw')
+    assert rc == 2
+    err = capsys.readouterr().err
+    assert '--requires-mounts-for' in err and 'newline' in err
+    assert not unit_dir.exists() and not patterns.exists() and not out.exists()
+    assert not os.path.exists(fw.DEFAULT_CONFIG_PATH)
+    assert calls == []
+
+
+def test_main_install_refuses_a_bad_mount_path_with_exit_2_and_no_traceback(tmp_path, capsys):
+    out = tmp_path / 'captures'
+    with pytest.raises(SystemExit) as exit_info:
+        fw.main(['--install-service', '-o', str(out), '--requires-mounts-for', '/mnt/a\rb', str(tmp_path / 'p.d')])
+    assert exit_info.value.code == 2
+    assert 'Traceback' not in capsys.readouterr().err
+    assert not out.exists() and not os.path.exists(fw.DEFAULT_CONFIG_PATH)
+
+
+def test_install_writes_a_quoted_mount_path_to_the_unit(tmp_path):
+    unit_dir = tmp_path / 'system'
+    parsed = parse_cli(['--install-service', '--no-enable', '-o', str(tmp_path / 'out'),
+                        '--requires-mounts-for', '/mnt/my logs', str(tmp_path / 'p.d')])
+    assert fw.install_service(parsed, systemd_available=True, unit_dir=str(unit_dir),
+                              systemctl=ok_systemctl, executable='/bin/fw') == 0
+    assert 'RequiresMountsFor="/mnt/my logs"\n' in (unit_dir / 'firewatcher.service').read_text()