Escape codes

Escape codes are needed in some string formats to render the needed output.

In CEF, for example, the equal sign is not allowed within values. For example, the equal sign embedded in the URL below is not allowed:

request=http://foo.com/x=42

An escape character must be added before the equal sign for the value to be rendered properly. The correct syntax is:

request=http://foo.com/x\=42

To support this, the format string syntax allows specific escape codes in front of the key name. For example, if you specify “%<=url>”, its meaning is the same as “%<url>”, except that all equal signs are escaped with a backslash, as are all linefeeds (LF), carriage returns (CR), and backslashes, resulting in: \=, \n, \r, and \\ respectively (each escape code is 2 characters long).

Supported escape codes include:

Code Description
%<=name> Escape equal signs, carriage returns, linefeeds, and the backslash character.
%<$name> Escape end-of-line (replace LF with \n and CR with \r).
%<|name> Escape the vertical bar (|), plus CR/LF; this is useful for the CEF prefix, where a vertical bar is not allowed unless escaped.
%<"name>

Escape the following special characters with a backslash:

  • Backslash (to \\)
  • Single quotes ('), double quotes ("), and backtick (‘)
  • Dollar sign ($), equal sign (=), and vertical bar (|)
  • Space, tab, CR, LF
  • Colon and semi-colon
%<_name>

Turn the following characters into underscores:

  • Backslash
  • All three quote types
  • All whitespace
%<-name>

The “-” (dash) escape has no effect in current versions. It was designed to signify “use value as-is; substitute a dash if there’s no value”.

However, this is the default behavior; there is no need for the escape option.

In all the escaped cases, an empty string is replaced with “-” to support positional fields (e.g. in extended.log formats).