cliu
bf7d88a027
Full manual diffs (L15, C20, E30, L25, J40, C10 §2, L10, P10, P11, J20, C30, P20, R40, E10) and read-only checks on the shared R1.05 test server. Skills and summaries moved to R1.05; new skill pytools (IM 36K10P40) from docs (no Python on the test server). Issues ISS-132..181; corrections to version-differences (E10, E30, P11, dss_ath_grp_u0104); C10 summary lists the 3 new authorization actions; r105-verification V10-V17. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
125 lines
7.6 KiB
Markdown
125 lines
7.6 KiB
Markdown
---
|
||
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 `<SUBJECT>.<ATTRIBUTE>.<ACTION>.<SOURCE>` 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.<source>`.
|
||
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
|
||
"<SUBJECT>.<ATTRIBUTE>.<ACTION>.<SOURCE>",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 >= "<Section>." and sbid < "<Section>/"` (`/` 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
|
||
`@"<text>"@` 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 <name>` 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\<name>.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 <name>` (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 <name>` line to
|
||
`audit_start.cmd`.
|
||
- R1.05: put that line in your own `tls\com\<prefix>_audit_start.cmd` (e.g.
|
||
`cieng_audit_start.cmd`) and a matching `durstp` line in `<prefix>_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>, <name>`; `NODE_ECL_FILE`, `NODE_SGP_FILE`; `E_LAYOUT = <unit>,<width>,…`
|
||
(`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.
|