144 lines
9.9 KiB
Markdown
144 lines
9.9 KiB
Markdown
---
|
||
manual: IM 36K10L25-01EN
|
||
title: Audit Trail Management Engineering
|
||
edition: 3rd Edition, Sep. 2023
|
||
version: R1.03
|
||
status: processes, scripts, adtsys.sup, classifiers, ADT group, AUDIT_TRAIL contents, selection groups and ADTLOG (default and filtered) verified on the test system 2026-10-01; distributor, extra collectors, classifier extension in C and operator-side ITEM.* events from docs
|
||
---
|
||
|
||
# Audit Trail Management Engineering (R1.03)
|
||
|
||
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).
|
||
|
||
## 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).
|
||
|
||
**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 is meant for the `ITEM.*` classifiers from operator/PROCESS
|
||
writes (not tested, ISS-049). A changed `STORAGE` flag is cached by the notifying process
|
||
(`ECL_REFRESH`, 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`.
|
||
|
||
**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`.
|
||
|
||
## 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.
|