---
title: "Log masking"
description: "Configure ordered regular expression rules in YAML or JSON to mask sensitive data in Geneos log lines before they are written, using a rules file with a top-level `maskingRules` array for Gateway and related components."
url: "https://docs.itrsgroup.com/docs/geneos/7.11.0/administration/log-masking/index.html"
---
## Overview

Log masking applies ordered regular expression replacements to [log lines](https://docs.itrsgroup.com/docs/geneos/7.11.0/processing/gateway-administration/gateway_log_file/index.html) before they are written. You define a rules file (YAML or JSON) that lists one or more rules. Each rule includes:

- `regex` — Pattern to match on each log line. The supported regular expression syntax depends on the component:
  - Java regular expressions are used by Active Console, Web Server, Collection Agent, and data that is written by Netprobe Java plugins.
  - [PCRE2](https://www.pcre.org/current/doc/html/index.html) is used by all other components.
- `replacement` — Text to substitute for the match.
- `name` (optional) — Descriptive label for the rule.

The file must contain a top-level `maskingRules` array. The same starter rules file is shipped with native binaries as `templates/log-masking-rules.yaml` and is also the source for the YAML file bundled with Java log-masking packages, for example under `config/geneos-log-masking/` or `resources/geneos-log-masking/`.

If a native process cannot load the rules file, it writes a critical message to the log destination describing the failure. Fix the path or file contents before relying on masking.

## Example rules

Rules are evaluated in list order. Each rule runs on the whole line after the previous rule's replacements.

### Replace full match (example.com hostnames)

The shipped `log-masking-rules.yaml` (for example under `config/geneos-log-masking/` on Web Server) includes a rule that matches fully qualified names under `example.com` or `example.con` and replaces the entire hostname with a fixed string. Log lines are unchanged except where this pattern matches.

```yaml
  - name: FQDN_example_com_or_con
    regex: '(?i)\b(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+example\.(?:com|con)(?!\.[A-Za-z0-9-])\b'
    replacement: '[redacted-host]'
```

For example, a line containing `https://app.example.com/path` becomes `https://[redacted-host]/path` (only the hostname segment is matched and replaced).

### Redact host, keep scheme and path (capture groups)

Use parentheses in `regex` to define capture groups, then reference them in `replacement` as `$1`, `$2`, and so on. The rule below keeps `http://` or `https://`, keeps everything after the authority (path, query string, fragment), and replaces only the host part (including an optional `:port`) with a fixed label.

```yaml
  - name: RedactHttpUrlAuthority
    regex: '(https?://)([^/?#]+)(.*)'
    replacement: '$1[redacted-host]$3'
```

- `$1` — `http://` or `https://`.
- `$2` — Authority to remove: hostname only, `hostname` with labels, or `hostname:port` (for example `anyhost`, `anyhost.anydomain`, `anyhost.anydomain:234`). This group is not included in `replacement`.
- `$3` — The rest of the URL from the first `/`, `?`, or `#` onward (often a path like `/patha/pathb`). This value can be empty if the URL has no path.

For example:

| Before | After |
| --- | --- |
| `call https://anyhost.anydomain/patha/pathb ok` | `call https://[redacted-host]/patha/pathb ok` |
| `GET http://anyhost/health` | `GET http://[redacted-host]/health` |
| `x https://anyhost.anydomain:234/patha?q=1` | `x https://[redacted-host]/patha?q=1` |

## Enable log masking in native processes (C++)

You can enable and configure log masking for native (C++) Geneos processes using the following command line option:

```
-logMaskingRules <path-to-file>
```

The `<path-to-file>` value can be an absolute or relative path. The rules file must be YAML (`.yaml` or `.yml`) or JSON (`.json`).

This applies to the following builds:

- [Gateway](https://docs.itrsgroup.com/docs/geneos/7.11.0/processing/gateway_installation_guide/index.html#command-line-options)
- [Netprobe](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/netprobe/configuration/netprobe-command-line-options/index.html#binary-command-line-options)
- [Webslinger](https://docs.itrsgroup.com/docs/geneos/7.11.0/visualization/webslinger/index.html#command-line-options)
- [Licence Daemon](https://docs.itrsgroup.com/docs/geneos/7.11.0/administration/licence-daemon/index.html#command-line-options)
- [File Agent](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/file-agent/index.html#command-line-options)
- [FIX Analyser 2 Netprobe](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/netprobe/configuration/netprobe-command-line-options/index.html#binary-command-line-options)

You can pass the option when starting the binary. For example:

```
./gateway2.linux_64 -setup gateway.setup.xml -logMaskingRules /opt/geneos/config/masking-rules.yaml
```

## Enable log masking in Java components (Log4j2 and Logback)

To configure log masking for Java components, set the `geneos.logMasking.rules` system property to the path of the same rules file you use for native log masking.

The package includes small Geneos log masking JARs. They target Java 11 bytecode and require JVM 11 or later.

| Module | Purpose |
| --- | --- |
| `geneos-log-masking.jar` | Provides the core rules engine and YAML or JSON parsing (`com.itrsgroup.logmasking`). |
| `geneos-log-masking-log4j.jar` | Provides a Log4j2 layout: `com.itrsgroup.logmasking.log4j2.LogMaskingPatternLayout` (Log4j2 plugin name `LogMaskingPatternLayout`). |
| `geneos-log-masking-logback.jar` | Provides a Logback layout: `com.itrsgroup.logmasking.logback.LogMaskingPatternLayout`. |

Use the Log4j2 adapter with the core JAR on the classpath for Active Console, Gateway Setup Editor (when using the bundled Log4j2 configuration), and Web Server (Web Dashboard). Use the Logback adapter with the core JAR for Java plugins and other Logback-based processes.

The package includes the following example templates:

- `log4j2-log-masking.template.xml`
- `logback-log-masking.template.xml`
- `log-masking-rules.yaml` (same starter rules as the native file `templates/log-masking-rules.yaml`)

If `geneos.logMasking.rules` is not set or is empty, the masking layouts work like an ordinary pattern layout and log lines are not masked.

### Active Console and Gateway Setup Editor

The installation includes `resources/geneos-log-masking/`, which contains the JAR files, `log-masking-rules.yaml`, and Log4j2 templates. The provided [`ActiveConsole.gci` file](https://docs.itrsgroup.com/docs/geneos/7.11.0/visualization/active-console/configuration/startup-settings/index.html) defines optional JVM system properties under `-jvmargs`.

To enable masking:

1. Open `ActiveConsole.gci`.
2. Uncomment the line that sets `-Dgeneos.logMasking.rules` (this points to `resources/geneos-log-masking/log-masking-rules.yaml` by default), or update the value to point to your own rules file.

Log4j2 is already configured to use `LogMaskingPatternLayout` when the property is set (see `log4j2-log-masking.template.xml`).

The same configuration applies to Gateway Setup Editor settings embedded in the same `ActiveConsole.gci`, which runs in the same process and uses the same JVM arguments.

### Web Server (Web Dashboard)

The `config/geneos-log-masking/` directory contains the JAR files, `log-masking-rules.yaml`, and the Log4j2 template.

On Linux and Unix systems, the `run` and `no_jre/run` scripts define an optional shell variable `LOG_MASKING`, and pass `$LOG_MASKING` on the `java` command line (after `-Dlog4j2.configurationFile=...`).

To enable masking:

1. Open the `run` or `no_jre/run` script in the [Web Dashboard installation directory](https://docs.itrsgroup.com/docs/geneos/7.11.0/visualization/web-dashboard/index.html#running-start-scripts).
2. Uncomment the line that sets `LOG_MASKING` to `-Dgeneos.logMasking.rules=${SCRIPTPATH}/config/geneos-log-masking/log-masking-rules.yaml`, or update the path to point to your own rules file.

If you start Web Dashboard using the `geneosws` service script instead of `run`, add the same `-Dgeneos.logMasking.rules=...` JVM option to the `java` command in that script, or replicate the `LOG_MASKING` configuration used in `run`.

### Netprobe and embedded Java

- Native Netprobe — Use `-logMaskingRules` with a rules file. You can start from the template under `templates/`.
- Embedded JVM (Java plugins and related components) — When `-logMaskingRules` loads successfully, Netprobe also passes `-Dgeneos.logMasking.rules=<same path>` to the JVM. If `JPROPERTIES` (or an equivalent setting) already defines `-Dgeneos.logMasking.rules`, that value takes precedence.
- Classpath — The Netprobe package includes masking JAR files in the `jars/` directory. Add the entire directory to the classpath (for example, `../jars/*`) to ensure the core engine, the Logback adapter (if used), and dependencies such as SnakeYAML resolve correctly.