--- task: Choose what AUDIT Service stores (classifier STORAGE, AUDIT_INFO), define selection groups, run an event logger (ADTLOG) version: R1.05 (first written for R1.03) source: IM 36K10L25-01EN §2.4, §3, §4.2, App. 1 (4th ed., Feb. 2026); R1.05 `adtsys.sup`, `audit_start.cmd`; practiced on CI-Eng-Sample 2026-10-01 status: verified on R1.03 (2026-10-01; PROCESS-side ITEM.* events from docs). R1.05: classifier list, setup file and start scripts checked 2026-10-09 (read-only); selection group CIENG_ITEMS loaded with 0 errors 2026-10-08 (load check only); STORAGE change, ADTLOG and the new APPRR / APPR layout units not tested on the shared server (awaiting user verification) --- # Configure the audit trail ## 1. Event classifiers — what is stored Each event type is a classifier `...` in `AUDIT_EVENT_CLAS_DF` (`NAME`, `SUBJECT`, `ATTRIBUTE`, `AGITATION` = action, `SOURCE`, `BASIC_SET`, `STORAGE`). Only `STORAGE` can be changed. Configuration and DSS value changes use subject `DATASET` with attribute `NULL-ATTR`, e.g. `DATASET.NULL-ATTR.MODIFY.LOC-ENG-MOD` (Engineering Module) or `….ENT-ENG-MOD` (`dssqld`); logins use `CI-SERVER.NULL-ATTR.LOGIN.`. R1.05 adds action `PENDING` and sources `REST-SERVER`, `PYTOOLS`, `PASSWORD-CHECK` (499 classifiers; list in `audit-checks.md` §3, ISS-141); the REST API, pyTOOLS and Password Check events can be switched off like any other. List the classifiers (and which are off): `dssqld -e ecl.qlo -d AUDIT_EVENT_CLAS_DF`. Change: ``` @FIELDS NAME,STORAGE @AUDIT_EVENT_CLAS_DF "...",0 ``` `dssqld -m`, or in the Engineering Module *Configuration › Audit trail › Event classifiers* (the change itself is audited: `AUDIT_EVENT_CLAS_DF` `STORAGE` `MODIFY`). **Not immediate:** the processes that report events (e.g. `DSSSDA`) cache the storage flags and re-read them every `ECL_REFRESH` seconds (default 1800). Verified: a classifier switched off was still recorded right after the change and no longer 31 minutes later; switching it back on is delayed the same way. Allow up to 30 minutes or restart CI Server (ISS-050). Confirm with the user before switching anything off. ### Item option *Audit trailing wanted* (`AUDIT_INFO`) `ITEM_DF` / `SUB_ITEM_DF` / `EXTERNAL_ALARM_DF` field `AUDIT_INFO` (default 0). It switches the `ITEM.*` / `SUB-ITEM.*` events raised by ITEM Service for **operator writes**. Verified on `CI-Eng-Sample.PUMP1.MODE` with the buttons on display `CIENG_Tank` (2026-10-01; re-checked 2026-10-06 with *Manual* / *Auto* on `CIENG_Control`: same events, user and old / new value): - `AUDIT_INFO` 1: a button write 0 → 1 stored `ITEM` `VALUE` `MODIFY` `OPER-INTERFACE`, user `ADMIN`, old 0 / new 1, plus `ITEM` `STATUS` `MODIFY` (13 → 9). - `AUDIT_INFO` 0: the write 1 → 0 left **no** audit record. It does not affect DSS writes (`dssqld`, Engineering Module: always audited as `ITEM_VAL` dataset events) or `itmval -p` (never audited). Sample: `19b_audit_item_df.qli` (`dssqld -m`, `NAME,AUDIT_INFO`). PROCESS writes (`COMPUTE`) also need `AUDIT = YES` in `tls\sup\opc.sup` (installed `NO`) and their classifiers are off by default; not tested. ## 2. Selection groups A selection group is a named, compiled filter for an AUDIT destination (`ADTLOG`, the chronological overview). Dataset `AUDIT_SELGRP_DF`: `NAME` (≤ 32), `DESCRIPTION`, `EXPRESSION` (memo), `COMPILE` (1 = compile now), `LISTING` (compiler output), `VALID_EXPRESSION`. Expression language (from the compiler's own listing): - Words compared with a **string**: `aai1 acnd acnm actm mai1 nond nonm reas sacs sact satr sbgp sbid term user` (same meaning as the `E_LAYOUT` units in §4: `sbgp` subject, `satr` attribute, `sact` action, `sacs` source, `sbid` subject id, `user` …). - Words compared with a constant: `nval oval` (new / old value). - Operators `= != > < >= <=`, `and`, `or`, parentheses. **No `LIKE`**: match a name prefix with a range, e.g. `sbid >= "
." and sbid < "
/"` (`/` sorts right after `.`). - R1.05: whether the compiler also accepts the new units `apprr` / `appr` was not tested (compiling needs a load; awaiting user verification on a non-shared system). Example (`examples/CI-Eng-Sample/19_audit_df.qli`): ``` @FIELDS NAME,DESCRIPTION,EXPRESSION,COMPILE @AUDIT_SELGRP_DF "CIENG_ITEMS","Audit events on CI-Eng-Sample",@" sbid >= "CI-Eng-Sample." and sbid < "CI-Eng-Sample/" "@,1 ``` `dssqld -i`. Write the memo **over several lines** (`@"` newline … newline `"@`): on one line `@""@` is taken as a file name (`CRL-E-EINVAL` / `CRL-E-ENOENT`). Check: export the dataset — `LISTING` ends with `ADTT-I-CMP_SUCC, Expression successfully compiled` and `VALID_EXPRESSION` is 1. An error (e.g. `ADTT-E-UNKNOWN_TOK`) makes the `dssqld` line fail with `ADTT-E-CMP_NO_SUCC` and leaves `VALID_EXPRESSION` 0. Remove with `dssqld -r` (`NAME` only). ## 3. Event logger `ADTLOG` `adtlog -n ` connects to `ADTSTO` and prints each new event as text (stdout, or the printer in `PRT_DEV`). It is not started by default (`audit_start.cmd` has it commented out; `fmfprt.sup` assigns the printer function `AUDIT_TRAIL` to `ADTLOG`). A process reads `tls\sup\.sup`, so one setup file per logger instance. Without a setup file the default layout is three lines per event (time with milliseconds, subject, attribute, action, source / subject id, user / old and new value). Verified test: `adtlog -n adtlogt` in a console, then a value write — the logger printed the `LOGIN`, the `ITEM_VAL` change and the `LOGOUT`. A console logger runs until stopped: Ctrl+C, or `durstp -m -p ` (skill `system-management`, `bus-utilities.md`). Filtered logger: `examples/CI-Eng-Sample/audit/adtlogci.sup` (`SEL_GROUP = "CIENG_ITEMS"`, one-line `E_LAYOUT`, `TIMEFMT`, `HEADER`, `HEADER_AFTER`). The user copies it to `%TLS_ROOT_PATH%\tls\sup\` (admin); then `adtlog -n adtlogci` printed only the CI-Eng-Sample changes (no logins), one line each under the header. If the selection group does not exist or did not compile, the logger logs an error and exits. To run it permanently (admin, restart): - R1.03: add a `start /B /NORMAL %TLS_ROOT_PATH%\tls\exe\adtlog -n ` line to `audit_start.cmd`. - R1.05: put that line in your own `tls\com\_audit_start.cmd` (e.g. `cieng_audit_start.cmd`) and a matching `durstp` line in `_audit_stop.cmd`; `audit_start.cmd` / `audit_stop.cmd` call every `?*_audit_start.cmd` / `?*_audit_stop.cmd` (ISS-142). The product script stays untouched, so an upgrade does not lose the line. From the installed scripts; not tested (needs admin and a restart). ## 4. Setup keywords (`adtsys.sup` is the template) `MAX_OPEN_UNITS` (20), `PRT_DEV`, `QUESIZE` (kB), `SEL_GROUP`; `COL_PROC`, `DST_PROC`, `HIS_PROC`, `STO_PROC` = `, `; `NODE_ECL_FILE`, `NODE_SGP_FILE`; `E_LAYOUT = ,,…` (`AAI1 ACND ACNM ACTM MAI1 NOND NONM NOTM NVAL NWLN OVAL REAS SACS SACT SATR SBGP SBID SPCE TERM USER`; R1.05 adds `APPRR` approval reason and `APPR` approver, ISS-140), `E_NOSPACE`, `TIMEFMT` (`DD/MM/YY hh:mm:ss.ppp` default — milliseconds shown, as the manual says); `ECL_REFRESH` (1800 s), `FLOWC` (30, 10), `HBEAT` (10), `TRYCON` (10); `FORM_FEED`, `HEADER` (repeat for more lines), `HEADER_AFTER` (re-print after n events; the header is also printed once at start). Which keyword applies to which process: L25 §4.2.2. ## 5. Retention Audit records live in history storage group `ADT` (rollover 1 day; lifetime 52 weeks on the R1.03 test system and on the R1.05 test server). Longer/shorter retention = change `LIFE_TIME` of `ADT` (skill `history-management`); archive like any storage group. Ask before shortening it.