Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 47 additions & 0 deletions .github/workflows/code-claims.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
name: Source-derived statements
on:
pull_request:
merge_group:
types: [checks_requested]
push:
branches: [develop]
schedule:
# Catch Cacti source changes that make the manual stale between edits.
- cron: '17 6 * * 1'
workflow_dispatch:
permissions:
contents: read
concurrency:
group: docs-code-claims-${{ github.event.pull_request.number || github.ref }}
cancel-in-progress: true
jobs:
claims:
name: Check statements against Cacti develop
runs-on: ubuntu-24.04
timeout-minutes: 5
env:
PYTHONDONTWRITEBYTECODE: '1'
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
with:
persist-credentials: false
- name: Check out the Cacti source this manual documents
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
with:
repository: Cacti/cacti
ref: develop
path: cacti-source
persist-credentials: false
- uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
with:
python-version: '3.12'
- name: Test the checker
run: |
python3 -m pip install --quiet --only-binary :all: coverage==7.13.2
python3 -m coverage run --branch --include=bin/check_code_claims.py \
-m unittest discover -s bin/tests -p test_code_claims.py
python3 -m coverage report --fail-under=100
- name: Compare the manual with the Cacti source
run: |
echo "Cacti develop $(git -C cacti-source rev-parse --short=12 HEAD)"
python3 bin/check_code_claims.py --cacti cacti-source
1 change: 0 additions & 1 deletion General-Installing-Instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -277,7 +277,6 @@ InnoDB engine:
MariaDB [(none)]> use cacti;
MariaDB [cacti]> ALTER TABLE `automation_ips` ENGINE=InnoDB;
MariaDB [cacti]> ALTER TABLE `automation_processes` ENGINE=InnoDB;
MariaDB [cacti]> ALTER TABLE `data_source_stats_hourly_cache` ENGINE=InnoDB;
MariaDB [cacti]> ALTER TABLE `data_source_stats_hourly_last` ENGINE=InnoDB;
MariaDB [cacti]> ALTER TABLE `poller_output` ENGINE=InnoDB;
MariaDB [cacti]> ALTER TABLE `poller_output_boost_local_data_ids` ENGINE=InnoDB;
Expand Down
25 changes: 22 additions & 3 deletions Install-Under-Enterprise-Linux-LAMP.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,13 +82,32 @@ executed by FPM rather than served as text. This example exposes only
Require all granted
DirectoryIndex index.php
</Directory>

# Cacti ships no .htaccess for these paths.
<Directory /var/www/html/cacti/service>
Require all denied
</Directory>
<Directory /var/www/html/cacti/include>
<FilesMatch "^config(_local)?\.php$">
Require all denied
</FilesMatch>
</Directory>
<Directory /var/www/html/cacti/include/vendor>
<FilesMatch "\.php$">
Require all denied
</FilesMatch>
</Directory>
</VirtualHost>
```

Install `mod_ssl` if not already present. `AllowOverride All` lets Cacti's
shipped `.htaccess` restrictions protect private paths; if your policy disables
overrides, reproduce those restrictions in the server configuration. Do not
grant general access to private directories as a troubleshooting step.
shipped `.htaccess` files deny `bin`, `cli`, `contrib`, `log`, `mibs`, `rra`,
`scripts`, `tests` and the private `cache` subdirectories. Cacti ships no
`.htaccess` for `service`, the `include/config.php` files or PHP files under
`include/vendor`, so the example denies them explicitly, as the nginx guides
do. If your policy disables overrides, reproduce the shipped restrictions in
the server configuration. Do not grant general access to private directories
as a troubleshooting step.

```console
dnf install -y mod_ssl
Expand Down
53 changes: 53 additions & 0 deletions bin/build_manuals_in_container.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
#!/usr/bin/env bash
# Build the PDF and text manual editions in the same environment as CI.
#
# Copyright (c) 2004-2026 The Cacti Group. GPL-2.0-or-later.
#
# Host builds embed whatever fonts the host provides (Arial on macOS, for
# example), so their PDFs differ from the published editions. This script runs
# the CI build in Ubuntu 24.04 with the CI font and library packages and the
# locked Python toolchain, then returns the outputs to the caller's account.
#
# Usage: bin/build_manuals_in_container.sh [build_pdf_docs.py arguments]
# Default arguments: --only manual --companions
set -euo pipefail

root=$(cd "$(dirname "$0")/.." && pwd)
image='ubuntu:24.04@sha256:73b999393d07f2bf65a40373778a44dc9a6d54ad7718d29247d8ff9413c4d6a8'
uv_version='0.12.23'
# A worktree keeps its Git metadata outside the checkout; mount it read-only at
# the same path so the builder can record the source revision.
git_dir=$(git -C "$root" rev-parse --absolute-git-dir)
git_common=$(cd "$(git -C "$root" rev-parse --git-common-dir)" && pwd)
if [[ "$#" -eq 0 ]]; then
set -- --only manual --companions
fi

docker run --rm -i \
-v "$root:/src" -w /src \
-v "$git_dir:$git_dir:ro" -v "$git_common:$git_common:ro" \
-e HOST_UID="$(id -u)" -e HOST_GID="$(id -g)" -e UV_VERSION="$uv_version" \
"$image" bash -s -- "$@" <<'CONTAINER'
set -euo pipefail
export DEBIAN_FRONTEND=noninteractive
apt-get update -qq
apt-get install -y -qq --no-install-recommends ca-certificates curl git \
libpango-1.0-0 libpangoft2-1.0-0 libharfbuzz-subset0 \
fonts-dejavu-core fonts-dejavu-extra poppler-utils >/dev/null

case "$(uname -m)" in
x86_64) arch=x86_64; sum=9167d72b3319674b6303c4cbe071854bba13ebdf3d76b1a7cbdc175471fb66d6 ;;
aarch64) arch=aarch64; sum=6524bd338177ed50d035d39354e12545e993bbeba2ecbddf0480c5b3a81d313f ;;
*) echo "Unsupported architecture: $(uname -m)" >&2; exit 1 ;;
esac
archive="uv-$arch-unknown-linux-gnu.tar.gz"
curl -fsSL -o "/tmp/$archive" "https://github.com/astral-sh/uv/releases/download/$UV_VERSION/$archive"
echo "$sum /tmp/$archive" | sha256sum -c --quiet
tar -xzf "/tmp/$archive" -C /usr/local/bin --strip-components=1

git config --global --add safe.directory '*'
status=0
uv run --locked --python 3.12.12 --script bin/build_pdf_docs.py "$@" || status=$?
chown -R "$HOST_UID:$HOST_GID" resource manual-artifacts 2>/dev/null || true
exit "$status"
CONTAINER
142 changes: 142 additions & 0 deletions bin/check_code_claims.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,142 @@
#!/usr/bin/env python3
"""Check manual statements that are derived from the Cacti source tree.

Copyright (c) 2004-2026 The Cacti Group. GPL-2.0-or-later.

Usage: bin/check_code_claims.py --cacti PATH [--docs PATH]

PATH is a Cacti checkout of the branch this manual documents. Each check
compares one documented list or value with the file it was copied from, so a
change on either side fails until the other is updated.
"""
import argparse
import json
from pathlib import Path
import re
import sys

ROOT = Path(__file__).resolve().parent.parent

def section(text, heading):
"""Return the body of the Markdown section that starts with heading."""
match = re.search(r'^(#+) ' + re.escape(heading) + r'\s*$', text, re.M)
if not match:
raise ValueError('Missing section: ' + heading)
level = len(match.group(1))
end = re.compile(r'^#{1,%d} ' % level, re.M).search(text, match.end())
return text[match.end():end.start() if end else len(text)]


def fence_after(text, marker, language):
"""Return the first fenced block of language that follows marker."""
start = text.find(marker)
if start < 0:
raise ValueError('Missing marker: ' + marker)
match = re.compile(r'^```' + language + r'\n(.*?)^```', re.M | re.S).search(text, start)
if not match:
raise ValueError(f'Missing {language} block after: {marker}')
return match.group(1)


def memory_tables(schema):
tables, current = set(), None
for line in schema.splitlines():
create = re.match(r'CREATE TABLE `(\w+)`', line)
if create:
current = create.group(1)
elif current and re.search(r'ENGINE=MEMORY', line):
tables.add(current)
return tables


def check_galera(docs, cacti):
text = (docs / 'General-Installing-Instructions.md').read_text()
block = fence_after(text, 'Galera clustering:', 'sql')
documented = set(re.findall(r'ALTER TABLE `(\w+)` ENGINE=InnoDB;', block))
expected = memory_tables((cacti / 'cacti.sql').read_text())
problems = [f'Galera list is missing MEMORY table {t}' for t in sorted(expected - documented)]
problems += [f'Galera list converts {t}, which cacti.sql does not create as MEMORY'
for t in sorted(documented - expected)]
return problems


def composer(cacti):
return json.loads((cacti / 'composer.json').read_text())['require']


def check_php_floor(docs, cacti):
text = (docs / 'Requirements.md').read_text()
row = re.search(r'^\| PHP \| PHP (\d+\.\d+) or later.*\(`\^(\d+\.\d+)` in Composer\) \|$', text, re.M)
if not row:
return ['Requirements.md has no PHP version row']
constraint = re.fullmatch(r'\^(\d+\.\d+)', composer(cacti)['php'])
constant = re.search(r"define\('CACTI_PHP_VERSION_MINIMUM', '(\d+\.\d+)\.\d+'\)",
(cacti / 'include/global_constants.php').read_text())
actual = {constraint.group(1) if constraint else composer(cacti)['php'],
constant.group(1) if constant else 'undefined'}
if len(actual) != 1:
return ['composer.json and CACTI_PHP_VERSION_MINIMUM disagree: ' + ', '.join(sorted(actual))]
floor = actual.pop()
return [f'Requirements.md states PHP {v}; the source requires {floor}'
for v in sorted(set(row.groups())) if v != floor]


def check_extensions(docs, cacti):
body = section((docs / 'Requirements.md').read_text(), 'PHP extensions')
listed = {name.lower() for name in re.findall(r'`(\w+)`', body)}
required = {name[4:] for name in composer(cacti) if name.startswith('ext-')}
return [f'Requirements.md does not list required extension {name}'
for name in sorted(required) if name.lower() not in listed]


def literal_kind(value):
value = value.strip()
if re.fullmatch(r'-?\d+', value):
return 'integer'
if value in ('true', 'false'):
return 'boolean'
if re.fullmatch(r"'[^']*'|\"[^\"]*\"", value):
return 'string'
return 'expression'


def assignments(text, commented=False):
prefix = r'#?' if commented else ''
return {name: literal_kind(value) for name, value in
re.findall(r'^' + prefix + r'\$(\w+)\s*=\s*(.+?);', text, re.M)}


def check_config_examples(docs, cacti):
dist = (cacti / 'include/config.php.dist').read_text()
active, all_names = assignments(dist), assignments(dist, commented=True)
problems = []
install = (docs / 'General-Installing-Instructions.md').read_text()
for name, kind in assignments(fence_after(install, 'Edit the copied file', 'php')).items():
if name not in active:
problems.append(f'General-Installing-Instructions.md sets ${name}, which config.php.dist does not define')
elif kind != active[name]:
problems.append(f'General-Installing-Instructions.md shows ${name} as {kind}; config.php.dist uses {active[name]}')
remote = (docs / 'How-To-Setup-Remote-Pollers.md').read_text()
for name in sorted(set(re.findall(r'\$(rdatabase_\w+)', remote))):
if name not in all_names:
problems.append(f'How-To-Setup-Remote-Pollers.md uses ${name}, which config.php.dist does not define')
return problems


CHECKS = (check_galera, check_php_floor, check_extensions, check_config_examples)


def main(argv=None):
parser = argparse.ArgumentParser(description='Check manual statements derived from the Cacti source.')
parser.add_argument('--cacti', type=Path, required=True, help='Cacti source checkout')
parser.add_argument('--docs', type=Path, default=ROOT, help='documentation checkout')
args = parser.parse_args(argv)
problems = [problem for check in CHECKS for problem in check(args.docs, args.cacti)]
for problem in problems:
print('error: ' + problem, file=sys.stderr)
print(f'{len(CHECKS)} source-derived checks, {len(problems)} problems')
return 1 if problems else 0


if __name__ == '__main__': # pragma: no cover
sys.exit(main())
Loading