Each log file you ingest needs to be validated by OneAgent and must abide by its security rules (file matching rules). Dynatrace's security rules for log filepaths ensure data protection by managing OneAgent access to files. By implementing these security measures, Dynatrace ensures defense against unauthorized access and data misuse. You also have the option to add or override these predefined security rules in the configuration file on the host where OneAgent is installed, allowing for flexibility in adapting to specific security needs.
Security rules apply to both automatically detected log files and custom log sources.
If a custom log source includes files disallowed by security rules, these files will be ignored by Log Agent. Default security rules do not block any automatically detected files. If you alter the security rules to be more strict, blocking some automatically detected files, it will result in auto-detection ignoring these files accordingly.
Security rules cannot be used to expand the autodetector to detect more files. You can only use them to limit the detection of files. If you need to include a log source that isn't automatically detected, use a custom log source configuration.
The rules prohibit log paths in critical system directories (such as /etc
, /boot
, /proc
, and several others), paths containing .ssh
, paths with the .pem
extension, and paths in directories starting with a dot (indicating hidden directories).
Dynatrace version 1.303+
Acceptable log paths must either have a log
or txt
extension, or be located in one of the following directories: log
, logs
, applogs
, logfile
, logfiles
, or have the filename catalina.out
. A log
extension can be followed by another extension, and a txt
extension can also be followed by another extension. An additional rotation extension is also allowed.
To ensure data protection and compliance, the following security rules must be adhered to for log paths:
/etc
, /boot
, /proc
, /dev
, /bin
, /sbin
, WindowsRoot:\windows
, or WindowsRoot:\winnt
. However, Windows|winnt\system32\winevt\Logs
is accepted AND.ssh
AND.pem
extension AND.
(for example, /.hidden
) ANDlog
extension separated by .
, -
, or _
(it can be followed by another extension with the same separator set) ORlog
, logs
, applogs
, logfile
, logfiles
ORcatalina.out
, optionally followed by another extension (e.g. added by rotation mechanism).Acceptable log paths must either have a log extension with certain separators, be located within the first or second level of a log
or logs
directory (or on the third level since Log Agent 1.287), be situated at any level of the /var/log
directory, or have the filename catalina.out
.”
The rules take into account the resolved paths of symbolic links for security matching, emphasizing the importance of the actual file location over the symlink path.
/etc
, /boot
, /proc
, /dev
, /bin
, /sbin
, /usr
, WindowsRoot:\windows
, or WindowsRoot:\winnt
. However, Windows|winnt\system32\winevt\Logs is accepted AND.ssh
AND.
(for example, /.hidden
) AND.
, -
, or _
(it can be followed by another extension with the same separator set) OR
log
or logs
directory (since Log Agent 1.287 it can also be located on the third level) OR/var/log
directory ORcatalina.out
.Files with paths that do not fulfill one or more criteria are not accepted. Once the conditions above are met, log file matching takes place. Check the log file matching rules.
You can add or override predefined security rules only in the configuration file on the host where OneAgent is installed.
/var/lib/dynatrace/oneagent/agent/config/logmodule
on Linux and UNIX
%PROGRAMDATA%\dynatrace\oneagent\agent\config\logmodule
on Windows
Any log file with the .json
suffix is allowed in the above directories.
/opt/dynatrace/oneagent/agent/conf
on Linux and UNIX%PROGRAMFILES%\dynatrace\oneagent\agent\conf
on Windows/log/
will match /log/file
and /var/log/file
but not /log/dir/file
/log/*/
will match /log/dir/file
but not /log/dir/dir2/file
[-.\\_]
expression in a pattern means that one of the characters provided in the square brackets must be present for a match to occur.The override configuration file is a JSON object that defines rules for allowing or excluding certain log paths based on specified directory and file patterns.
The following structure is given in the file:
allowed-log-paths-configuration
: Marks the array of the rules.Each rule consists of three key-value pairs, with the following mandatory keys:
directory-pattern
file-pattern
action
The description of the keys is given below:
directory-pattern
: This object specifies the pattern for matching directories. The directory pattern is executed from right to left, for example: /log/
will match /log/file.txt
and /var/log/file.txt
but not /log/dir/file.txt
. The following rules apply:
*
. For example, /log/*/
will match /log/dir/file.txt
but not /log/dir/dir2/file.txt
.**
matches any number of subdirectories. For example, the pattern /log/dir/**/
will match /log/dir/dir1/dir2/dir3/file.txt
and /log/dir/file.txt
.^
matches the start of the path. It anchors the pattern to the beginning of the examined path For example, ^/usr/*/
matches paths starting with /usr/
, such as /usr/log/file.txt
and /usr/local/file.txt
, but will not match /some/usr/log/file.txt
.
For Windows paths, the anchor can also skip the drive letter. For example, the pattern ^/Users/Public/
would match the actual path C:\Users\Public\file.txt
. JSON treats \ as an escape character, so when specifying Windows paths, you can use either C:\\Users\\Public
or C:/Users/Public
but not C:\Users\Public
.
All pattern matching is case insensitive.You can combine special characters such as *
, **
, and ^
within a single directory pattern to create more complex matching rules. For example, the pattern ^/log/**/dir/*/*/
will match the path /log/some/deep/dir/and/deeper/file.txt
.
file-pattern
: This object specifies the pattern for matching files within the directories matched by the directory pattern
.
Dynatrace version 1.303+
This pattern is applied using full match, case insensitive. This means a pattern such as error_*.txt
will match error_1.txt
but not severe_error_1.txt
. In this example, the file pattern should contain a wildcard at the beginning: *error_*.txt
to match both files.
There is one exception to that rule introduced to avoid common mistakes related to rotated files: Log Agent treats each rule with INCLUDE action as its file-pattern had an additional optional extension, separated by .
, -
, or _
. This means that a rule with the INCLUDE
action and file pattern set to *.txt
will catch not only error.txt
but also error.txt.1
.
Dynatrace version 1.302 and earlier
This pattern is applied using full match, case insensitive. This means that a pattern such as *.txt
will match error.txt
but not error.txt.1
. To properly detect files that follow rotation patterns, the file pattern must include a wildcard at the end. For example, to match files that rotate from error.txt to error.txt.1, the file pattern should be constructed as *.txt*
.
action
: This object specifies the action to be taken for the matched file. In this case, EXCLUDE
or INCLUDE
.
The [-.\\_]
expression in square brackets means that one of the characters provided in the square brackets must be present for a match to occur.
An example override configuration file is given below:
{"allowed-log-paths-configuration":[{"directory-pattern":"/","file-pattern":"*.pem","action":"EXCLUDE" // or INCLUDE},... your rules ...]}
Each custom log source path you add needs to be validated by OneAgent and abide by its security rules (file matching rules). Some predefined security rules are applied on the OneAgent side. Examples of exclude and include rules for UNIX, Linux, and Windows are listed in the table below.
Operating system
Directory pattern
File pattern
Action
UNIX
/
*.pem
EXCLUDE
UNIX
/
*[-.\\_]log[-.\\_]*
INCLUDE
Linux
/.ssh/
*
EXCLUDE
Linux
/
*[-.\\_]log
INCLUDE
Windows
/.*/
*
EXCLUDE
Windows
/windows/system32/winevt/Logs/
*
INCLUDE
The full list of security rules for UNIX:
Dynatrace version 1.303+
{"@version": "1.0.0","allowed-log-paths-configuration": [{"directory-pattern":"/","file-pattern":"*.pem","action":"EXCLUDE"},{"directory-pattern":"/.ssh/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern":"/.*/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern":"/","file-pattern":".*","action":"EXCLUDE"},{"directory-pattern":"^/etc/**/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern":"^/boot/**/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern":"^/proc/**/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern":"^/dev/**/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern":"^/bin/**/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern":"^/sbin/**/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern": "/","file-pattern": "*[-.\\_]log","action": "INCLUDE"},{"directory-pattern": "/","file-pattern": "*[-.\\_]txt","action": "INCLUDE"},{"directory-pattern": "/","file-pattern": "catalina.out*","action": "INCLUDE"},{"directory-pattern": "/log/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/log/**/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/logs/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/logs/**/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/logfile/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/logfile/**/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/logfiles/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/logfiles/**/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/applogs/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/applogs/**/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "^/var/lib/docker/containers/*/","file-pattern": "*.log","action": "INCLUDE"}]}
Dynatrace version 1.301 and earlier
{"allowed-log-paths-configuration": [{"directory-pattern":"/","file-pattern":"*.pem","action":"EXCLUDE"},{"directory-pattern":"/.ssh/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern":"/.*/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern":"/","file-pattern":".*","action":"EXCLUDE"},{"directory-pattern":"^/etc/**/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern":"^/boot/**/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern":"^/proc/**/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern":"^/dev/**/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern":"^/bin/**/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern":"^/sbin/**/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern":"^/usr/**/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern": "/","file-pattern": "*[-.\\_]log[-.\\_]*","action": "INCLUDE"},{"directory-pattern": "/","file-pattern": "*[-.\\_]log","action": "INCLUDE"},{"directory-pattern": "/","file-pattern": "catalina.out*","action": "INCLUDE"},{"directory-pattern": "/log/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/log/*/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/log/*/*/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/logs/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/logs/*/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/logs/*/*/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "^/var/lib/docker/containers/*/","file-pattern": "*.log","action": "INCLUDE"},{"directory-pattern": "^/var/log/**/","file-pattern": "*","action": "INCLUDE"}]}
The full list of security rules for Linux:
Dynatrace version 1.303+
{"@version": "1.0.0","allowed-log-paths-configuration": [{"directory-pattern":"/","file-pattern":"*.pem","action":"EXCLUDE"},{"directory-pattern":"/.ssh/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern":"/.*/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern":"/","file-pattern":".*","action":"EXCLUDE"},{"directory-pattern":"^/etc/**/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern":"^/boot/**/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern":"^/proc/**/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern":"^/dev/**/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern":"^/bin/**/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern":"^/sbin/**/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern": "/","file-pattern": "*[-.\\_]log","action": "INCLUDE"},{"directory-pattern": "/","file-pattern": "*[-.\\_]txt","action": "INCLUDE"},{"directory-pattern": "/","file-pattern": "catalina.out*","action": "INCLUDE"},{"directory-pattern": "/log/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/log/**/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/logs/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/logs/**/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/logfile/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/logfile/**/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/logfiles/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/logfiles/**/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/applogs/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/applogs/**/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "^/var/lib/docker/containers/*/","file-pattern": "*.log","action": "INCLUDE"}]}
Dynatrace version 1.301 and earlier
{"allowed-log-paths-configuration": [{"directory-pattern":"/","file-pattern":"*.pem","action":"EXCLUDE"},{"directory-pattern":"/.ssh/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern":"/.*/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern":"/","file-pattern":".*","action":"EXCLUDE"},{"directory-pattern":"^/etc/**/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern":"^/boot/**/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern":"^/proc/**/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern":"^/dev/**/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern":"^/bin/**/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern":"^/sbin/**/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern":"^/usr/**/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern": "/","file-pattern": "*[-.\\_]log[-.\\_]*","action": "INCLUDE"},{"directory-pattern": "/","file-pattern": "*[-.\\_]log","action": "INCLUDE"},{"directory-pattern": "/","file-pattern": "catalina.out*","action": "INCLUDE"},{"directory-pattern": "/log/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/log/*/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/log/*/*/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/logs/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/logs/*/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/logs/*/*/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "^/var/lib/docker/containers/*/","file-pattern": "*.log","action": "INCLUDE"},{"directory-pattern": "^/var/log/**/","file-pattern": "*","action": "INCLUDE"}]}
The full list of security rules for Windows:
Dynatrace version 1.303+
{"@version":"1.0.0","allowed-log-paths-configuration":[{"directory-pattern":"/","file-pattern":"*.pem","action":"EXCLUDE"},{"directory-pattern":"/.ssh/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern":"/.*/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern":"/","file-pattern":".*","action":"EXCLUDE"},{"directory-pattern":"/windows/system32/winevt/Logs/","file-pattern":"*","action":"INCLUDE"},{"directory-pattern":"/winnt/system32/winevt/Logs/","file-pattern":"*","action":"INCLUDE"},{"directory-pattern":"^/windows/**/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern":"^/winnt/**/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern":"/","file-pattern":"*[-.\\_]log","action":"INCLUDE"},{"directory-pattern": "/","file-pattern": "*[-.\\_]txt","action": "INCLUDE"},{"directory-pattern":"/","file-pattern":"catalina.out*","action":"INCLUDE"},{"directory-pattern": "/log/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/log/**/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/logs/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/logs/**/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/logfile/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/logfile/**/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/logfiles/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/logfiles/**/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/applogs/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/applogs/**/","file-pattern": "*","action": "INCLUDE"}]}
Dynatrace version 1.301 and earlier
{"allowed-log-paths-configuration":[{"directory-pattern":"/","file-pattern":"*.pem","action":"EXCLUDE"},{"directory-pattern":"/.ssh/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern":"/.*/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern":"/","file-pattern":".*","action":"EXCLUDE"},{"directory-pattern":"/windows/system32/winevt/Logs/","file-pattern":"*","action":"INCLUDE"},{"directory-pattern":"/winnt/system32/winevt/Logs/","file-pattern":"*","action":"INCLUDE"},{"directory-pattern":"^/windows/**/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern":"^/winnt/**/","file-pattern":"*","action":"EXCLUDE"},{"directory-pattern":"/","file-pattern":"*[-.\\_]log[-.\\_]*","action":"INCLUDE"},{"directory-pattern":"/","file-pattern":"*[-.\\_]log","action":"INCLUDE"},{"directory-pattern":"/","file-pattern":"catalina.out*","action":"INCLUDE"},{"directory-pattern": "/log/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/log/*/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/log/*/*/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/logs/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/logs/*/","file-pattern": "*","action": "INCLUDE"},{"directory-pattern": "/logs/*/*/","file-pattern": "*","action": "INCLUDE"}]}