What NSAdaMask is
nsadamask is Nacarsoft’s deterministic multi-country masking utility for Adabas: it replaces personal data with fictitious values that are valid and format-preserving (DNI, CPF, RUT, SSN, passport, CIF, CUIT, IBAN, cards, IP, MAC, license plates…), so test and development environments comply with data protection rules without breaking application validation. It is deterministic: the same original value with the same seed (-seed) always produces the same replacement.
- Build test environments with realistic but not real data.
- Meet GDPR/local data-protection rules in development without rewriting validations.
- Simulate before applying (
-simulate, enabled by default) with a per-field report.
DBIDs, FNRs, fields and paths in the examples are fictitious; use your real values.
Use cases
1. Mask an employee file for the test environment
./nsadamask -dbid 50 -fnr 15 -fields "AA:DNI,AB:NAME" -country ES \
-seed fictitious-key-01 -simulate -outfile report.csv2. Apply masking after validating the simulation
./nsadamask -dbid 50 -fnr 15 -fields "AA:DNI,AB:NAME" -country ES \
-seed fictitious-key-01 -apply -commit-every 20003. Mask only an ISN range with Adabas selection
./nsadamask -dbid 50 -fnr 15 -fields "AC:EMAIL" -country ES \
-seed fictitious-key-01 -search "AA=[1000:1999]" -fromisn 1000 -toisn 1999 -simulate4. Detect candidates with the heuristic before masking
./nsadamask -config fictitious-schema.json -ddmname FICTITIOUS-CUSTOMERS -analyze-config5. Check per-field original-vs-replacement cardinality
./nsadamask -dbid 50 -fnr 15 -fields "AA:DNI" -country ES \
-seed fictitious-key-01 -check -simulateCommand reference
Verified against ./nsadamask/build/nsadamask_rhel8 --help (39 parameters).
Connection and record selection
| Parameter | Description | Required |
|---|---|---|
-dbid | Adabas database ID | Yes |
-fnr | File number to mask (overridden by -ddmname with -config) | Yes, unless -ddmname |
-ddmname | Logical DDM file name from the -config JSON | No |
-config | JSON configuration file with the Adabas schema | Yes, with -ddmname |
-search | Record selection using Adabas syntax (short or DDM names) | No |
-sortby | Descriptor/superdescriptor for logical read order | No |
-fromisn | Starting ISN for sequential read | No |
-toisn | Ending ISN for sequential read | No |
-etid | ETID (External Transaction ID) for the connection | No |
-partialread | Partial read mode (only queried fields) | No |
-blocksize | Block size for Adabas reads (default 65536) | No |
-multifetch | Multifetch size for Adabas reads (default 200) | No |
-recordbuffershift | Record buffer shift for Adabas reads (default 100) | No |
What to mask
| Parameter | Description | Required |
|---|---|---|
-fields | Fields to mask: SHORT:TYPE[:COUNTRY] or DDM_NAME:TYPE[:COUNTRY], comma separated. E.g. -fields "AA:DNI,BB:NAME,CC:CPF". Per-field country overrides -country (ISO 3166-1 alpha-2) | Yes |
-country | Dictionary/format-validation country: ES, AR, US, BR, CL, MX (default ES) | No |
-seed | Master seed for deterministic masking | Yes, for -apply |
-skip-empty | Skip records whose masked fields are empty | No |
-skip-if-masked | Skip values that no longer match the type format (already anonymized; default true) | No |
Modes: simulation, apply and analysis
| Parameter | Description | Required |
|---|---|---|
-simulate | Simulation mode (default true): report what would change, write nothing | No |
-apply | Apply mode: write masked values back to Adabas (requires -seed and a valid license) | No |
-check | Report original-vs-replacement cardinality per field | No |
-analyze-config | Analyze the -config JSON (DDMs) and suggest masking candidate files/fields (heuristic, no connection) | No |
-commit-every | Commit every N records in apply mode (default 5000) | No |
Simulation report
| Parameter | Description | Required |
|---|---|---|
-outfile | Simulation log file (CSV: ISN,field,original,replacement) | No |
-outfile-max-mb | Abort the simulation when the log exceeds this size in MB (0 = unlimited) | No |
-write-factor | Apply-time estimate multiplier over read time in simulate mode (default 2) | No |
Dictionaries
| Parameter | Description | Required |
|---|---|---|
-dictdir | Directory with anonymized CSV dictionaries (one file per type, TYPE_CC.csv; default dicts) | No |
-dict | Explicit mapping TYPE=path.csv (repeatable) | No |
-dict-delim | Dictionary CSV delimiter (default auto-detect ; or ,) | No |
-dict-header | Skip the first line of each dictionary CSV (header) | No |
-gen-dicts | Write the dictionaries bundled in the binary into -dictdir and exit | No |
-show-dict | Print the bundled dictionary values for TYPE (repeatable) | No |
-types | List supported masking types (English canonical + Spanish aliases) and exit | No |
Diagnostics, license and miscellaneous
| Parameter | Description | Required |
|---|---|---|
-fdt | Show FDT field definitions and exit | No |
-debug | Enable debug logging | No |
-silence | Silent mode (no banner) | No |
-license | Path to the signed license.key (default license.key in cwd or next to the binary) | No |
-license-fingerprint | Print this machine’s license fingerprint and exit | No |
-version | Show version information | No |
Incompatibilities: -simulate and -apply are mutually exclusive (simulation is the default); -ddmname requires -config; -apply requires -seed.
Commented examples
# 1. Simulate first (recommended): report without writing anything
./nsadamask -dbid 50 -fnr 15 -fields "AA:DNI,AB:NAME" -country ES \
-seed fictitious-key-01 -simulate -outfile report.csv
# 2. Apply after validating the simulation (requires a signed license)
./nsadamask -dbid 50 -fnr 15 -fields "AA:DNI,AB:NAME" -country ES \
-seed fictitious-key-01 -apply
# 3. Brazilian field with per-field country (overrides -country for CC only)
./nsadamask -dbid 50 -fnr 15 -fields "AA:DNI,CC:CPF:BR" -country ES \
-seed fictitious-key-01 -simulate
# 4. Partial read plus ISN range for a large subset
./nsadamask -dbid 50 -fnr 15 -fields "AC:EMAIL" -country ES \
-seed fictitious-key-01 -partialread -fromisn 1000 -toisn 5000 -simulate
# 5. See which types exist and what a bundled dictionary holds
./nsadamask -types
./nsadamask -show-dict NAME -country ES
# 6. Suggest candidates from the schema without connecting to Adabas
./nsadamask -config fictitious-schema.json -ddmname FICTITIOUS-CUSTOMERS -analyze-configReturn codes
The manual documents no return-code table; observed binary behavior (informational 0 exits and 1 on parameter, license or connection errors, verified in the code and with --help → 0):
| Code | Meaning |
|---|---|
0 | Success (includes informational exits: -version, -types, -fdt, -gen-dicts, -analyze-config) |
1 | Error (parameters, missing/invalid license for -apply, Adabas connection) |
FAQ
Why should I simulate before applying? -simulate (the default) produces the per-field report — which values would be replaced — without writing to the database; only after validating it do you run -apply.
Why is -apply rejected on trial? Applying changes requires a signed license at /opt/ns/licenses/nsadamask.key; without one the utility runs in 30-day trial limited to simulation.
How do I repeat exactly the same masking? Reuse the same -seed: the same original value always yields the same replacement. Different seeds give non-repeatable results.
What if a field is not masked? Check the file definition (-fdt) and the type given in -fields (-types lists the supported ones); with -skip-if-masked, already-anonymized values are skipped by design.