Log masking

Overview Copied

Log masking applies ordered regular expression replacements to log lines before they are written. You define a rules file (YAML or JSON) that lists one or more rules. Each rule includes:

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 Copied

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) Copied

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.

  - 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) Copied

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.

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

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++) Copied

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:

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) Copied

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:

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 Copied

The installation includes resources/geneos-log-masking/, which contains the JAR files, log-masking-rules.yaml, and Log4j2 templates. The provided ActiveConsole.gci file 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) Copied

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.
  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.

On Windows:

  1. Open run.bat or no_jre/run.bat.
  2. Uncomment the following line, or update the path as needed: set LOG_MASKING=-Dgeneos.logMasking.rules=config\geneos-log-masking\log-masking-rules.yaml

The java command already includes %LOG_MASKING%.

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 Copied

["Geneos"] ["Geneos > Gateway"] ["Technical Reference"]

Was this topic helpful?