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>
186 lines
13 KiB
Markdown
186 lines
13 KiB
Markdown
---
|
||
manual: IM 36K10L25-01EN
|
||
title: Audit Trail Management Engineering
|
||
edition: 4th Edition, Feb. 2026 (R1.05; first summarized from the 3rd Edition, Sep. 2023, R1.03)
|
||
version: R1.05 (first written for R1.03)
|
||
status: processes, scripts, adtsys.sup, classifiers, ADT group, AUDIT_TRAIL contents, selection groups and ADTLOG (default and filtered) verified on the R1.03 test system 2026-10-01; on the R1.05 test server processes, ADT group, classifier list, dataset definitions, setup files, start scripts and an RQL read of AUDIT_TRAIL verified 2026-10-09 (read-only); distributor, extra collectors, classifier extension in C from docs
|
||
---
|
||
|
||
# Audit Trail Management Engineering (R1.05)
|
||
|
||
**R1.05 re-check (2026-10-09).** The 4th edition (Feb. 2026) differs from the 3rd only in the
|
||
revision table and contact information (full text diff, `tools/manual_diff.py`); section
|
||
numbers are unchanged. The installed software changed without manual text:
|
||
- `AUDIT_TRAIL` fields `APPROVAL_REASON` (256) and `APPROVER` (128), added for FDA Part 11
|
||
(approval of changes to critical process parameters); `E_LAYOUT` units `APPRR` / `APPR`
|
||
(ISS-140). Filled by display writes with a reason and approver (IM 36K10C50 §2.22, §4.12;
|
||
ISS-099).
|
||
- 499 classifiers (R1.03: 463): action `PENDING`, sources `REST-SERVER`, `PYTOOLS`,
|
||
`PASSWORD-CHECK` (ISS-141).
|
||
- `audit_start.cmd` / `audit_stop.cmd` call `?*_audit_start.cmd` / `?*_audit_stop.cmd` (ISS-142).
|
||
- Unchanged: executables, `AUDIT_EVENT_CLAS_DF` and `AUDIT_SELGRP_DF` definitions, `fmfprt.sup`,
|
||
the rest of `adtsys.sup`; `adtini.sup` differs only in licence lines. `dur.sup` gives
|
||
`ADTSTO` an adaptive queue (ISS-109, ISS-122).
|
||
Details are in the sections below, marked "R1.05".
|
||
|
||
AUDIT Service records who changed what and when: value and limit changes, definition inserts /
|
||
modifies / deletes, alarm acknowledgements, logins and logouts. Events are stored in the history
|
||
storage group `ADT` and read through dataset `AUDIT_TRAIL`. The manual is written for system
|
||
integrators (processes, setup file, extending the classifier tables in C). Section numbers refer
|
||
to the manual; "installed" means checked on the R1.03.00 test system.
|
||
|
||
## 1. Interfaces and data stores (§1)
|
||
|
||
| Interface / store | Use |
|
||
|---|---|
|
||
| Notification | Applications report an event (routine `adt_evt_not`); only one field of a stored event, the *modifiable ASCII application info*, can be changed afterwards |
|
||
| Distribution | Connected processes (AUDIT destinations) receive events as they are stored, optionally filtered by a selection group |
|
||
| Retrieval | Reading stored events (collector process; `AUDIT_TRAIL` dataset) |
|
||
| History management | Storage group `ADT` is managed by HISTORY Service (rollover, lifetime, units) |
|
||
| Event classifier file | Which event types exist and whether each is **stored** — dataset `AUDIT_EVENT_CLAS_DF` (`tls\dat\adt_ecl.dat`) |
|
||
| Selection group file | Named, compiled selection expressions — dataset `AUDIT_SELGRP_DF` (`tls\dat\adt_sgp.dat`) |
|
||
|
||
Single events cannot be deleted; only whole storage units or the whole group (HISTORY Service).
|
||
|
||
## 2. Processes (§1.2, §2, §4.1)
|
||
|
||
| Process | Job |
|
||
|---|---|
|
||
| `ADTSTO` (storage) | Creates group `ADT` if missing (rollover 1 day, unit lifetime 2 days), fills the classifier file with the basic set (existing entries kept), creates the selection group file, stores events, sends them to destinations. Ignores events while storage of `ADT` is stopped. Must run on the node of the history manager `HIS` |
|
||
| `ADTCOL01` (+ `ADTCOL02`…) | Answers retrieval requests, also while storage is stopped; extra images share the queue `adtcol01` (load sharing). Exits if group `ADT` does not exist, so `ADTSTO` must start first |
|
||
| `ADTDST` (distributor) | Optional relay on another node when several destinations there want events (3 + N instead of 3 × N BUS messages) |
|
||
| `ADTLOG` (logging) | Optional destination that prints events as text (stdout or `PRT_DEV`), optionally only a selection group |
|
||
|
||
Gaps are signalled with *missing events* records/messages (storage queue overflow, lost
|
||
connection, unexpected sequence number). Destinations check sequence numbers and periodic
|
||
flow-control messages; a missing flow-control message makes them reconnect.
|
||
|
||
**Installed:** `tls\com\audit_start.cmd` does nothing if `adtsto` already runs, refuses to start
|
||
when `his` is not running, then starts `adtsto -n adtsto` and `adtcol -n adtcol01`. `adtcol02`,
|
||
`adtlog` and `adtdst` are present as commented-out lines. `audit_stop.cmd` stops `adt*` with
|
||
`durstp`. Executables in `tls\exe`: `adtsto`, `adtcol`, `adtdst`, `adtlog`, `adtimport`
|
||
(undocumented), `adtxdb` (service debugger, not documented).
|
||
|
||
**R1.05 (verified 2026-10-09):** same executables and the same two processes running
|
||
(`ADTSTO`, `ADTCOL01`). At the end `audit_start.cmd` calls every
|
||
`tls\com\?*_audit_start.cmd`; `audit_stop.cmd` calls every `?*_audit_stop.cmd` before stopping
|
||
`adt*` (ISS-142).
|
||
|
||
## 3. Event classifiers (§3.1, Appendix 1)
|
||
|
||
An event classifier is four names `<SUBJECT>.<ATTRIBUTE>.<ACTION>.<SOURCE>`, e.g.
|
||
`ITEM.VALUE.MODIFY.HMI`. Each name has an internal code; stored events keep only the codes, so
|
||
codes must never change once used.
|
||
|
||
- **Subjects**: ALN-DEST, ALN-USR, CLASS, CLASS-ATTR, DATASET, EQUIPMENT, F/T-SYSTEM,
|
||
INSTALLATION, ITEM, OBJECT, OBJECT-ATTR, SECTION, STATION, SUB-ITEM, TRIGGER-GROUP, UNIT,
|
||
USER-PROFILE, ACKNOWLEDGE-TYP.
|
||
- **Attributes** (about 170): item properties (VALUE, STATUS, HIGH-LIMIT, LOW-LIMIT, DESCRIPTION,
|
||
ENGINERING-UNIT, ALARM-INHIBIT, ALARM-SHELVE, ENABLE-AUDIT-TR …), point/line properties,
|
||
alarm notification users and schedules, NULL-ATTR (no attribute).
|
||
- **Actions**: ACKNOWLEDGE, DELETE, INSERT, LOGIN, LOGIN-ATTEMPT, LOGOUT, MODIFY, SHELVE,
|
||
UN-SHELVE (the manual's explanations of SHELVE and UN-SHELVE are swapped).
|
||
- **Sources**: COMPUTE (PROCESS Service), DSS-CLIENT, ENT-EDIT-MOD, ENT-ENG-MOD, ENT-QUALIZATION,
|
||
FTEXCHANGE, HMI (Engineering Module), LOC-EDIT-MOD, LOC-ENG-MOD, ODBC, OPC-DA-SERVER,
|
||
OPER-INTERFACE, OTHERS, QUICKLOAD.
|
||
|
||
The notifying routine checks a cached copy of the classifier's **storage** flag and sends
|
||
nothing when storage is off; the cache refreshes every `ECL_REFRESH` seconds (default 1800), so
|
||
a change to the storage flag may take up to 30 minutes to reach running programs.
|
||
|
||
**Installed:** `AUDIT_EVENT_CLAS_DF` fields `NAME` (the four names joined), `SUBJECT`,
|
||
`ATTRIBUTE`, `AGITATION` (= action), `SOURCE`, `DESCRIPTION`, `BASIC_SET`, `STORAGE` (the only
|
||
changeable field); 463 classifiers, 444 stored. Off by default: the `COMPUTE` (PROCESS) source for
|
||
item/sub-item values, status, quality, limits, deadband, and `DATASET.NULL-ATTR.*.COMPUTE`. Not in
|
||
the manual: subject `CI-SERVER` (logins; the manual's `F/T-SYSTEM` is the old name), subject/action
|
||
`EAL OPERATION`, source `VIA-OPC-UAS` (ISS-051).
|
||
|
||
**R1.05 (verified 2026-10-09):** 499 classifiers, all basic set, 478 stored. New (36, not in the
|
||
manual, ISS-141): action `PENDING` on `ITEM.VALUE` / `ITEM.STATUS` for sources `HMI`,
|
||
`LOC-ENG-MOD`, `OPER-INTERFACE`, `OTHERS`, `VIA-OPC-UAS`, `COMPUTE` (the `COMPUTE` pair off), tied
|
||
in the C header history to Vnet *on send* / *on receive* item update policies; sources
|
||
`REST-SERVER` (RESTful API), `PYTOOLS` (IM 36K10P40) and `PASSWORD-CHECK` (Edit Module Password
|
||
Check, IM 36K10C50 §2.31) for `CI-SERVER` login / logout / login attempt and `DATASET`
|
||
insert / modify / delete, plus `ITEM.VALUE` / `STATUS` / `QUALITY-CODE` `MODIFY` for the first
|
||
two. Defined in `tls\inc\adt_ece.h` (`ADT_SAC_PEND`, `ADT_SAS_JRST`, `ADT_SAS_PTLS`,
|
||
`ADT_SAS_PSWD`). Off by default: the 19 `COMPUTE` classifiers of R1.03 plus the two
|
||
`PENDING.COMPUTE`.
|
||
|
||
**What is actually recorded (verified):** configuration changes and DSS value writes are stored
|
||
as *dataset* events — `SUBJECT_GROUP` = dataset name (`ITEM_DF`, `ITEM_VAL`, `SECTION_DF` …),
|
||
`SUBJECT_ATTRIBUTE` = field, old and new value, user and source: `ENT-ENG-MOD` for `dssqld`
|
||
(not `QUICKLOAD`), `LOC-ENG-MOD` for the Engineering Module; every `dssqld` run also adds a
|
||
`CI-SERVER` `LOGIN`/`LOGOUT` pair. `itmval -p` writes are not audited. The item option
|
||
`AUDIT_INFO` (*Audit trailing wanted*, default 0; also on `SUB_ITEM_DF`, `EXTERNAL_ALARM_DF`) made
|
||
no difference for these tools; it switches the `ITEM.*` events of **operator writes**: a button on
|
||
display `CIENG_Tank` stored `ITEM.VALUE.MODIFY.OPER-INTERFACE` (old/new, user) with
|
||
`AUDIT_INFO` 1 and nothing with 0 (verified, ISS-049; the same events from *Manual* / *Auto* on
|
||
`CIENG_Control`, 2026-10-06). A changed `STORAGE` flag takes effect only after the notifying process
|
||
re-reads it (`ECL_REFRESH`, up to 30 minutes, both directions; verified, ISS-050).
|
||
|
||
## 4. Setup files (§4.2)
|
||
|
||
Only `tls\sup\adtsys.sup` is installed; it documents every keyword and is the template for
|
||
per-process files named after the process (`adtsto.sup`, `adtcol01.sup`, `adtdst.sup`,
|
||
`adtlog.sup`, `adtovv.sup` for the chronological overview). Without a file, defaults apply.
|
||
|
||
| Tab / keyword | Meaning | Default |
|
||
|---|---|---|
|
||
| General `MAX_OPEN_UNITS` | Storage units open at once (2–100) | 20 |
|
||
| `PRT_DEV` | Printer for `ADTLOG` | stdout |
|
||
| `QUESIZE` | BUS queue size, kB | see below |
|
||
| `SEL_GROUP` | Selection group applied by the process | none |
|
||
| Node Numbers `COL_PROC`, `DST_PROC`, `HIS_PROC`, `STO_PROC` | `<node>, <name>` of collector, distributor, history manager, storage | local `ADTCOL01`, local `ADTSTO`, local `HIS`, `ADTSTO` on the host node |
|
||
| `NODE_ECL_FILE`, `NODE_SGP_FILE` | Node holding the classifier / selection group file | storage node |
|
||
| Layout `E_LAYOUT` | Message units and widths for the overview / log (`ACTM` time, `SBGP` subject, `SATR`, `SACT`, `SACS`, `SBID` subject id, `USER`, `TERM`, `OVAL`/`NVAL` old/new value, `REAS`, `AAI1`/`MAI1` application info, `ACND`/`ACNM`/`NOND`/`NONM`/`NOTM` node, program and notification time, `SPCE n`, `NWLN n`) | `SPCE,2,ACTM,21,SBGP,13,SATR,13,SACT,11,SACS,15,NWLN,1,SPCE,4,SBID,40,USER,16,NWLN,1,SPCE,6,OVAL,35,NVAL,35,NWLN,1` |
|
||
| `E_NOSPACE` | No automatic space between units | off |
|
||
| `TIMEFMT` | Picture for `ACTM` (`YYYY MMM DD hh mm ss ppp`) | see below |
|
||
| Events `ECL_REFRESH` | Classifier cache refresh, s | 1800 |
|
||
| `FLOWC` | Flow-control interval, timeout (s) | 30, 10 |
|
||
| `HBEAT` | Heartbeat, s | 10 |
|
||
| `TRYCON` | Reconnect interval, s | 10 |
|
||
| Header `FORM_FEED`, `HEADER` (repeatable), `HEADER_AFTER` | Log header | off / layout header / never repeated |
|
||
|
||
**Installed differences:** the `adtsys.sup` help says `QUESIZE` default 10 kB (minimum 10), the
|
||
manual says default and maximum 200 kB; the file sets `QUESIZE = 200`. The `TIMEFMT` default is
|
||
`DD/MM/YY hh:mm:ss` in the file help and `DD/MM/YY hh:mm:ss.ppp` in the manual; `ADTLOG` prints
|
||
milliseconds, so the manual is right (ISS-051). Also installed: `adtini.sup` (licence value only),
|
||
and `fmfprt.sup` assigns the printer function `AUDIT_TRAIL` to `ADTLOG`.
|
||
|
||
**R1.05 (verified 2026-10-09):** `adtsys.sup` and `adtsys.tpl` add only the `E_LAYOUT` units
|
||
`APPRR` (approval reason) and `APPR` (approver) (ISS-140); the `QUESIZE` and `TIMEFMT` help texts
|
||
are unchanged (ISS-051 still applies). `ADTLOG` with the new units not tested.
|
||
|
||
**Verified:** `adtlog -n <name>` run from a console prints new events with the default layout;
|
||
with a setup file `<name>.sup` holding `SEL_GROUP`, `E_LAYOUT`, `TIMEFMT`, `HEADER`,
|
||
`HEADER_AFTER` it printed only the selected events in the custom layout (sample
|
||
`examples/CI-Eng-Sample/audit/adtlogci.sup`).
|
||
|
||
## 4a. Selection groups (not described in the manual)
|
||
|
||
`AUDIT_SELGRP_DF`: `NAME`, `DESCRIPTION`, `EXPRESSION` (memo), `COMPILE`, `LISTING`,
|
||
`VALID_EXPRESSION`. The compiler listing names the language: string comparisons on `aai1 acnd
|
||
acnm actm mai1 nond nonm reas sacs sact satr sbgp sbid term user`, constant comparisons on `nval
|
||
oval`, operators `= != > < >= <=`, `and`, `or`, parentheses; no `LIKE` (prefix match with a range
|
||
`>= "X." and < "X/"`). Errors: `ADTT-E-UNKNOWN_TOK`, `ADTT-E-CMP_NO_SUCC`. Verified.
|
||
|
||
## 4b. Reading the trail
|
||
|
||
`AUDIT_TRAIL` (key `NAME` = `<action time>/<stamp>`; all fields read-only except `PROFILE` and
|
||
`APPLICATION_SUB`) is in `dssqld.sup` `NO-EXPORT`: export with `-d AUDIT_TRAIL` or a qli that
|
||
names it — the qli export returns 0 records unless `NAME` is in `@FIELDS`; `@SELECT` accepts
|
||
`LIKE "X.*"`. RQL `select … from audit_trail` works in reports (sample `CIENG_AUDIT`). `ADT`
|
||
group on the test system: lifetime 52 weeks, rollover 1 day. Task files: skill `audit-trail`.
|
||
|
||
**R1.05 (verified 2026-10-09):** `audit_trail.dss` adds `APPROVAL_REASON` (char 256) and
|
||
`APPROVER` (char 128), select only (ISS-140). An RQL read on the R1.05 test server found them
|
||
filled on operator item-value writes (`OPER-INTERFACE`), with `REASON` empty. `ADT` group there:
|
||
52 weeks, 1 day. `dssqld.sup` still has `NO-EXPORT=AUDIT_TRAIL`.
|
||
|
||
## 5. Extending classifiers (§4.3)
|
||
|
||
New subjects/attributes/actions/sources are added in C: `#define` codes ≥ `0x80000000` in
|
||
`adt_ece.h`, names starting with `_`, rebuild `adt_ece()` (`tls\src\adt_ece.c`) and re-link AUDIT,
|
||
INTEGRATION, DATABASE Service and every program that uses it. **Installed:** `adt_ece.c`,
|
||
`tls\inc\adt_ece.h`, `audit_compile.cmd`/`.mak`, `audit_build.cmd`/`.mak` are shipped. System
|
||
integrator work; not practiced.
|