WWWWWW

Current Directory: /usr/share/doc/nxlog-ce
Viewing File: /usr/share/doc/nxlog-ce/nxlog-reference-manual.html
<!DOCTYPE html>
<html lang="en-US">
<head>
<meta charset="UTF-8">
<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 1.5.6.1">
<meta name="author" content="NXLog Ltd.">
<meta name="copyright" content="Copyright © NXLog Ltd. 2018">
<title>NXLog Community Edition Reference Manual</title>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700">
<style>
/* Asciidoctor default stylesheet | MIT License | http://asciidoctor.org */
/* Remove comment around @import statement below when using as a custom stylesheet */
/*@import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700";*/
article,aside,details,figcaption,figure,footer,header,hgroup,main,nav,section,summary{display:block}
audio,canvas,video{display:inline-block}
audio:not([controls]){display:none;height:0}
[hidden],template{display:none}
script{display:none!important}
html{font-family:sans-serif;-ms-text-size-adjust:100%;-webkit-text-size-adjust:100%}
a{background:transparent}
a:focus{outline:thin dotted}
a:active,a:hover{outline:0}
h1{font-size:2em;margin:.67em 0}
abbr[title]{border-bottom:1px dotted}
b,strong{font-weight:bold}
dfn{font-style:italic}
hr{-moz-box-sizing:content-box;box-sizing:content-box;height:0}
mark{background:#ff0;color:#000}
code,kbd,pre,samp{font-family:monospace;font-size:1em}
pre{white-space:pre-wrap}
q{quotes:"\201C" "\201D" "\2018" "\2019"}
small{font-size:80%}
sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}
sup{top:-.5em}
sub{bottom:-.25em}
img{border:0}
svg:not(:root){overflow:hidden}
figure{margin:0}
fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em}
legend{border:0;padding:0}
button,input,select,textarea{font-family:inherit;font-size:100%;margin:0}
button,input{line-height:normal}
button,select{text-transform:none}
button,html input[type="button"],input[type="reset"],input[type="submit"]{-webkit-appearance:button;cursor:pointer}
button[disabled],html input[disabled]{cursor:default}
input[type="checkbox"],input[type="radio"]{box-sizing:border-box;padding:0}
input[type="search"]{-webkit-appearance:textfield;-moz-box-sizing:content-box;-webkit-box-sizing:content-box;box-sizing:content-box}
input[type="search"]::-webkit-search-cancel-button,input[type="search"]::-webkit-search-decoration{-webkit-appearance:none}
button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}
textarea{overflow:auto;vertical-align:top}
table{border-collapse:collapse;border-spacing:0}
*,*:before,*:after{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box}
html,body{font-size:100%}
body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;font-weight:400;font-style:normal;line-height:1;position:relative;cursor:auto;tab-size:4;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased}
a:hover{cursor:pointer}
img,object,embed{max-width:100%;height:auto}
object,embed{height:100%}
img{-ms-interpolation-mode:bicubic}
.left{float:left!important}
.right{float:right!important}
.text-left{text-align:left!important}
.text-right{text-align:right!important}
.text-center{text-align:center!important}
.text-justify{text-align:justify!important}
.hide{display:none}
img,object,svg{display:inline-block;vertical-align:middle}
textarea{height:auto;min-height:50px}
select{width:100%}
.center{margin-left:auto;margin-right:auto}
.spread{width:100%}
p.lead,.paragraph.lead>p,#preamble>.sectionbody>.paragraph:first-of-type p{font-size:1.21875em;line-height:1.6}
.subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em}
div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0;direction:ltr}
a{color:#2156a5;text-decoration:underline;line-height:inherit}
a:hover,a:focus{color:#1d4b8f}
a img{border:none}
p{font-family:inherit;font-weight:400;font-size:1em;line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility}
p aside{font-size:.875em;line-height:1.35;font-style:italic}
h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em}
h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0}
h1{font-size:2.125em}
h2{font-size:1.6875em}
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em}
h4,h5{font-size:1.125em}
h6{font-size:1em}
hr{border:solid #ddddd8;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em;height:0}
em,i{font-style:italic;line-height:inherit}
strong,b{font-weight:bold;line-height:inherit}
small{font-size:60%;line-height:inherit}
code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)}
ul,ol,dl{font-size:1em;line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit}
ul,ol{margin-left:1.5em}
ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0;font-size:1em}
ul.square li ul,ul.circle li ul,ul.disc li ul{list-style:inherit}
ul.square{list-style-type:square}
ul.circle{list-style-type:circle}
ul.disc{list-style-type:disc}
ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0}
dl dt{margin-bottom:.3125em;font-weight:bold}
dl dd{margin-bottom:1.25em}
abbr,acronym{text-transform:uppercase;font-size:90%;color:rgba(0,0,0,.8);border-bottom:1px dotted #ddd;cursor:help}
abbr{text-transform:none}
blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd}
blockquote cite{display:block;font-size:.9375em;color:rgba(0,0,0,.6)}
blockquote cite:before{content:"\2014 \0020"}
blockquote cite a,blockquote cite a:visited{color:rgba(0,0,0,.6)}
blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)}
@media only screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2}
h1{font-size:2.75em}
h2{font-size:2.3125em}
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em}
h4{font-size:1.4375em}}
table{background:#fff;margin-bottom:1.25em;border:solid 1px #dedede}
table thead,table tfoot{background:#f7f8f7;font-weight:bold}
table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left}
table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)}
table tr.even,table tr.alt,table tr:nth-of-type(even){background:#f8f8f7}
table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{display:table-cell;line-height:1.6}
h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em}
h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400}
.clearfix:before,.clearfix:after,.float-group:before,.float-group:after{content:" ";display:table}
.clearfix:after,.float-group:after{clear:both}
*:not(pre)>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background-color:#f7f7f8;-webkit-border-radius:4px;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed;word-wrap:break-word}
*:not(pre)>code.nobreak{word-wrap:normal}
*:not(pre)>code.nowrap{white-space:nowrap}
pre,pre>code{line-height:1.45;color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;text-rendering:optimizeSpeed}
em em{font-style:normal}
strong strong{font-weight:400}
.keyseq{color:rgba(51,51,51,.8)}
kbd{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background-color:#f7f7f7;border:1px solid #ccc;-webkit-border-radius:3px;border-radius:3px;-webkit-box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em white inset;box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em #fff inset;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap}
.keyseq kbd:first-child{margin-left:0}
.keyseq kbd:last-child{margin-right:0}
.menuseq,.menuref{color:#000}
.menuseq b:not(.caret),.menuref{font-weight:inherit}
.menuseq{word-spacing:-.02em}
.menuseq b.caret{font-size:1.25em;line-height:.8}
.menuseq i.caret{font-weight:bold;text-align:center;width:.45em}
b.button:before,b.button:after{position:relative;top:-1px;font-weight:400}
b.button:before{content:"[";padding:0 3px 0 2px}
b.button:after{content:"]";padding:0 2px 0 3px}
p a>code:hover{color:rgba(0,0,0,.9)}
#header,#content,#footnotes,#footer{width:100%;margin-left:auto;margin-right:auto;margin-top:0;margin-bottom:0;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em}
#header:before,#header:after,#content:before,#content:after,#footnotes:before,#footnotes:after,#footer:before,#footer:after{content:" ";display:table}
#header:after,#content:after,#footnotes:after,#footer:after{clear:both}
#content{margin-top:1.25em}
#content:before{content:none}
#header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0}
#header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #ddddd8}
#header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #ddddd8;padding-bottom:8px}
#header .details{border-bottom:1px solid #ddddd8;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:-ms-flexbox;display:-webkit-flex;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap}
#header .details span:first-child{margin-left:-.125em}
#header .details span.email a{color:rgba(0,0,0,.85)}
#header .details br{display:none}
#header .details br+span:before{content:"\00a0\2013\00a0"}
#header .details br+span.author:before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)}
#header .details br+span#revremark:before{content:"\00a0|\00a0"}
#header #revnumber{text-transform:capitalize}
#header #revnumber:after{content:"\00a0"}
#content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #ddddd8;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem}
#toc{border-bottom:1px solid #efefed;padding-bottom:.5em}
#toc>ul{margin-left:.125em}
#toc ul.sectlevel0>li>a{font-style:italic}
#toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0}
#toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none}
#toc li{line-height:1.3334;margin-top:.3334em}
#toc a{text-decoration:none}
#toc a:active{text-decoration:underline}
#toctitle{color:#7a2518;font-size:1.2em}
@media only screen and (min-width:768px){#toctitle{font-size:1.375em}
body.toc2{padding-left:15em;padding-right:0}
#toc.toc2{margin-top:0!important;background-color:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #efefed;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto}
#toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em}
#toc.toc2>ul{font-size:.9em;margin-bottom:0}
#toc.toc2 ul ul{margin-left:0;padding-left:1em}
#toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em}
body.toc2.toc-right{padding-left:0;padding-right:15em}
body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #efefed;left:auto;right:0}}
@media only screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0}
#toc.toc2{width:20em}
#toc.toc2 #toctitle{font-size:1.375em}
#toc.toc2>ul{font-size:.95em}
#toc.toc2 ul ul{padding-left:1.25em}
body.toc2.toc-right{padding-left:0;padding-right:20em}}
#content #toc{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px}
#content #toc>:first-child{margin-top:0}
#content #toc>:last-child{margin-bottom:0}
#footer{max-width:100%;background-color:rgba(0,0,0,.8);padding:1.25em}
#footer-text{color:rgba(255,255,255,.8);line-height:1.44}
.sect1{padding-bottom:.625em}
@media only screen and (min-width:768px){.sect1{padding-bottom:1.25em}}
.sect1+.sect1{border-top:1px solid #efefed}
#content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400}
#content h1>a.anchor:before,h2>a.anchor:before,h3>a.anchor:before,#toctitle>a.anchor:before,.sidebarblock>.content>.title>a.anchor:before,h4>a.anchor:before,h5>a.anchor:before,h6>a.anchor:before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em}
#content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible}
#content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none}
#content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221}
.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em}
.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic}
table.tableblock>caption.title{white-space:nowrap;overflow:visible;max-width:0}
.paragraph.lead>p,#preamble>.sectionbody>.paragraph:first-of-type p{color:rgba(0,0,0,.85)}
table.tableblock #preamble>.sectionbody>.paragraph:first-of-type p{font-size:inherit}
.admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%}
.admonitionblock>table td.icon{text-align:center;width:80px}
.admonitionblock>table td.icon img{max-width:initial}
.admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase}
.admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #ddddd8;color:rgba(0,0,0,.6)}
.admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0}
.exampleblock>.content{border-style:solid;border-width:1px;border-color:#e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;-webkit-border-radius:4px;border-radius:4px}
.exampleblock>.content>:first-child{margin-top:0}
.exampleblock>.content>:last-child{margin-bottom:0}
.sidebarblock{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px}
.sidebarblock>:first-child{margin-top:0}
.sidebarblock>:last-child{margin-bottom:0}
.sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center}
.exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0}
.literalblock pre,.listingblock pre:not(.highlight),.listingblock pre[class="highlight"],.listingblock pre[class^="highlight "],.listingblock pre.CodeRay,.listingblock pre.prettyprint{background:#f7f7f8}
.sidebarblock .literalblock pre,.sidebarblock .listingblock pre:not(.highlight),.sidebarblock .listingblock pre[class="highlight"],.sidebarblock .listingblock pre[class^="highlight "],.sidebarblock .listingblock pre.CodeRay,.sidebarblock .listingblock pre.prettyprint{background:#f2f1f1}
.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{-webkit-border-radius:4px;border-radius:4px;word-wrap:break-word;padding:1em;font-size:.8125em}
.literalblock pre.nowrap,.literalblock pre[class].nowrap,.listingblock pre.nowrap,.listingblock pre[class].nowrap{overflow-x:auto;white-space:pre;word-wrap:normal}
@media only screen and (min-width:768px){.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{font-size:.90625em}}
@media only screen and (min-width:1280px){.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{font-size:1em}}
.literalblock.output pre{color:#f7f7f8;background-color:rgba(0,0,0,.9)}
.listingblock pre.highlightjs{padding:0}
.listingblock pre.highlightjs>code{padding:1em;-webkit-border-radius:4px;border-radius:4px}
.listingblock pre.prettyprint{border-width:0}
.listingblock>.content{position:relative}
.listingblock code[data-lang]:before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:#999}
.listingblock:hover code[data-lang]:before{display:block}
.listingblock.terminal pre .command:before{content:attr(data-prompt);padding-right:.5em;color:#999}
.listingblock.terminal pre .command:not([data-prompt]):before{content:"$"}
table.pyhltable{border-collapse:separate;border:0;margin-bottom:0;background:none}
table.pyhltable td{vertical-align:top;padding-top:0;padding-bottom:0;line-height:1.45}
table.pyhltable td.code{padding-left:.75em;padding-right:0}
pre.pygments .lineno,table.pyhltable td:not(.code){color:#999;padding-left:0;padding-right:.5em;border-right:1px solid #ddddd8}
pre.pygments .lineno{display:inline-block;margin-right:.25em}
table.pyhltable .linenodiv{background:none!important;padding-right:0!important}
.quoteblock{margin:0 1em 1.25em 1.5em;display:table}
.quoteblock>.title{margin-left:-1.5em;margin-bottom:.75em}
.quoteblock blockquote,.quoteblock blockquote p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify}
.quoteblock blockquote{margin:0;padding:0;border:0}
.quoteblock blockquote:before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)}
.quoteblock blockquote>.paragraph:last-child p{margin-bottom:0}
.quoteblock .attribution{margin-top:.5em;margin-right:.5ex;text-align:right}
.quoteblock .quoteblock{margin-left:0;margin-right:0;padding:.5em 0;border-left:3px solid rgba(0,0,0,.6)}
.quoteblock .quoteblock blockquote{padding:0 0 0 .75em}
.quoteblock .quoteblock blockquote:before{display:none}
.verseblock{margin:0 1em 1.25em 1em}
.verseblock pre{font-family:"Open Sans","DejaVu Sans",sans;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility}
.verseblock pre strong{font-weight:400}
.verseblock .attribution{margin-top:1.25rem;margin-left:.5ex}
.quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic}
.quoteblock .attribution br,.verseblock .attribution br{display:none}
.quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)}
.quoteblock.abstract{margin:0 0 1.25em 0;display:block}
.quoteblock.abstract blockquote,.quoteblock.abstract blockquote p{text-align:left;word-spacing:0}
.quoteblock.abstract blockquote:before,.quoteblock.abstract blockquote p:first-of-type:before{display:none}
table.tableblock{max-width:100%;border-collapse:separate}
table.tableblock td>.paragraph:last-child p>p:last-child,table.tableblock th>p:last-child,table.tableblock td>p:last-child{margin-bottom:0}
table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede}
table.grid-all>thead>tr>.tableblock,table.grid-all>tbody>tr>.tableblock{border-width:0 1px 1px 0}
table.grid-all>tfoot>tr>.tableblock{border-width:1px 1px 0 0}
table.grid-cols>*>tr>.tableblock{border-width:0 1px 0 0}
table.grid-rows>thead>tr>.tableblock,table.grid-rows>tbody>tr>.tableblock{border-width:0 0 1px 0}
table.grid-rows>tfoot>tr>.tableblock{border-width:1px 0 0 0}
table.grid-all>*>tr>.tableblock:last-child,table.grid-cols>*>tr>.tableblock:last-child{border-right-width:0}
table.grid-all>tbody>tr:last-child>.tableblock,table.grid-all>thead:last-child>tr>.tableblock,table.grid-rows>tbody>tr:last-child>.tableblock,table.grid-rows>thead:last-child>tr>.tableblock{border-bottom-width:0}
table.frame-all{border-width:1px}
table.frame-sides{border-width:0 1px}
table.frame-topbot{border-width:1px 0}
th.halign-left,td.halign-left{text-align:left}
th.halign-right,td.halign-right{text-align:right}
th.halign-center,td.halign-center{text-align:center}
th.valign-top,td.valign-top{vertical-align:top}
th.valign-bottom,td.valign-bottom{vertical-align:bottom}
th.valign-middle,td.valign-middle{vertical-align:middle}
table thead th,table tfoot th{font-weight:bold}
tbody tr th{display:table-cell;line-height:1.6;background:#f7f8f7}
tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold}
p.tableblock>code:only-child{background:none;padding:0}
p.tableblock{font-size:1em}
td>div.verse{white-space:pre}
ol{margin-left:1.75em}
ul li ol{margin-left:1.5em}
dl dd{margin-left:1.125em}
dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0}
ol>li p,ul>li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em}
ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none}
ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em}
ul.unstyled,ol.unstyled{margin-left:0}
ul.checklist{margin-left:.625em}
ul.checklist li>p:first-child>.fa-square-o:first-child,ul.checklist li>p:first-child>.fa-check-square-o:first-child{width:1.25em;font-size:.8em;position:relative;bottom:.125em}
ul.checklist li>p:first-child>input[type="checkbox"]:first-child{margin-right:.25em}
ul.inline{margin:0 auto .625em auto;margin-left:-1.375em;margin-right:0;padding:0;list-style:none;overflow:hidden}
ul.inline>li{list-style:none;float:left;margin-left:1.375em;display:block}
ul.inline>li>*{display:block}
.unstyled dl dt{font-weight:400;font-style:normal}
ol.arabic{list-style-type:decimal}
ol.decimal{list-style-type:decimal-leading-zero}
ol.loweralpha{list-style-type:lower-alpha}
ol.upperalpha{list-style-type:upper-alpha}
ol.lowerroman{list-style-type:lower-roman}
ol.upperroman{list-style-type:upper-roman}
ol.lowergreek{list-style-type:lower-greek}
.hdlist>table,.colist>table{border:0;background:none}
.hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none}
td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em}
td.hdlist1{font-weight:bold;padding-bottom:1.25em}
.literalblock+.colist,.listingblock+.colist{margin-top:-.5em}
.colist>table tr>td:first-of-type{padding:.4em .75em 0 .75em;line-height:1;vertical-align:top}
.colist>table tr>td:first-of-type img{max-width:initial}
.colist>table tr>td:last-of-type{padding:.25em 0}
.thumb,.th{line-height:0;display:inline-block;border:solid 4px #fff;-webkit-box-shadow:0 0 0 1px #ddd;box-shadow:0 0 0 1px #ddd}
.imageblock.left,.imageblock[style*="float: left"]{margin:.25em .625em 1.25em 0}
.imageblock.right,.imageblock[style*="float: right"]{margin:.25em 0 1.25em .625em}
.imageblock>.title{margin-bottom:0}
.imageblock.thumb,.imageblock.th{border-width:6px}
.imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em}
.image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0}
.image.left{margin-right:.625em}
.image.right{margin-left:.625em}
a.image{text-decoration:none;display:inline-block}
a.image object{pointer-events:none}
sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super}
sup.footnote a,sup.footnoteref a{text-decoration:none}
sup.footnote a:active,sup.footnoteref a:active{text-decoration:underline}
#footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em}
#footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em 0;border-width:1px 0 0 0}
#footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;text-indent:-1.05em;margin-bottom:.2em}
#footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none}
#footnotes .footnote:last-of-type{margin-bottom:0}
#content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0}
.gist .file-data>table{border:0;background:#fff;width:100%;margin-bottom:0}
.gist .file-data>table td.line-data{width:99%}
div.unbreakable{page-break-inside:avoid}
.big{font-size:larger}
.small{font-size:smaller}
.underline{text-decoration:underline}
.overline{text-decoration:overline}
.line-through{text-decoration:line-through}
.aqua{color:#00bfbf}
.aqua-background{background-color:#00fafa}
.black{color:#000}
.black-background{background-color:#000}
.blue{color:#0000bf}
.blue-background{background-color:#0000fa}
.fuchsia{color:#bf00bf}
.fuchsia-background{background-color:#fa00fa}
.gray{color:#606060}
.gray-background{background-color:#7d7d7d}
.green{color:#006000}
.green-background{background-color:#007d00}
.lime{color:#00bf00}
.lime-background{background-color:#00fa00}
.maroon{color:#600000}
.maroon-background{background-color:#7d0000}
.navy{color:#000060}
.navy-background{background-color:#00007d}
.olive{color:#606000}
.olive-background{background-color:#7d7d00}
.purple{color:#600060}
.purple-background{background-color:#7d007d}
.red{color:#bf0000}
.red-background{background-color:#fa0000}
.silver{color:#909090}
.silver-background{background-color:#bcbcbc}
.teal{color:#006060}
.teal-background{background-color:#007d7d}
.white{color:#bfbfbf}
.white-background{background-color:#fafafa}
.yellow{color:#bfbf00}
.yellow-background{background-color:#fafa00}
span.icon>.fa{cursor:default}
a span.icon>.fa{cursor:inherit}
.admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default}
.admonitionblock td.icon .icon-note:before{content:"\f05a";color:#19407c}
.admonitionblock td.icon .icon-tip:before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111}
.admonitionblock td.icon .icon-warning:before{content:"\f071";color:#bf6900}
.admonitionblock td.icon .icon-caution:before{content:"\f06d";color:#bf3400}
.admonitionblock td.icon .icon-important:before{content:"\f06a";color:#bf0000}
.conum[data-value]{display:inline-block;color:#fff!important;background-color:rgba(0,0,0,.8);-webkit-border-radius:100px;border-radius:100px;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold}
.conum[data-value] *{color:#fff!important}
.conum[data-value]+b{display:none}
.conum[data-value]:after{content:attr(data-value)}
pre .conum[data-value]{position:relative;top:-.125em}
b.conum *{color:inherit!important}
.conum:not([data-value]):empty{display:none}
dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility}
h1,h2,p,td.content,span.alt{letter-spacing:-.01em}
p strong,td.content strong,div.footnote strong{letter-spacing:-.005em}
p,blockquote,dt,td.content,span.alt{font-size:1.0625rem}
p{margin-bottom:1.25rem}
.sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em}
.exampleblock>.content{background-color:#fffef7;border-color:#e0e0dc;-webkit-box-shadow:0 1px 4px #e0e0dc;box-shadow:0 1px 4px #e0e0dc}
.print-only{display:none!important}
@media print{@page{margin:1.25cm .75cm}
*{-webkit-box-shadow:none!important;box-shadow:none!important;text-shadow:none!important}
a{color:inherit!important;text-decoration:underline!important}
a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important}
a[href^="http:"]:not(.bare):after,a[href^="https:"]:not(.bare):after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em}
abbr[title]:after{content:" (" attr(title) ")"}
pre,blockquote,tr,img,object,svg{page-break-inside:avoid}
thead{display:table-header-group}
svg{max-width:100%}
p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3}
h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid}
#toc,.sidebarblock,.exampleblock>.content{background:none!important}
#toc{border-bottom:1px solid #ddddd8!important;padding-bottom:0!important}
.sect1{padding-bottom:0!important}
.sect1+.sect1{border:0!important}
#header>h1:first-child{margin-top:1.25rem}
body.book #header{text-align:center}
body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em 0}
body.book #header .details{border:0!important;display:block;padding:0!important}
body.book #header .details span:first-child{margin-left:0!important}
body.book #header .details br{display:block}
body.book #header .details br+span:before{content:none!important}
body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important}
body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always}
.listingblock code[data-lang]:before{display:block}
#footer{background:none!important;padding:0 .9375em}
#footer-text{color:rgba(0,0,0,.6)!important;font-size:.9em}
.hide-on-print{display:none!important}
.print-only{display:block!important}
.hide-for-print{display:none!important}
.show-for-print{display:inherit!important}}
</style>
<style>
/* Stylesheet for CodeRay to match GitHub theme | MIT License | http://foundation.zurb.com */
/*pre.CodeRay {background-color:#f7f7f8;}*/
.CodeRay .line-numbers{border-right:1px solid #d8d8d8;padding:0 0.5em 0 .25em}
.CodeRay span.line-numbers{display:inline-block;margin-right:.5em;color:rgba(0,0,0,.3)}
.CodeRay .line-numbers strong{color:rgba(0,0,0,.4)}
table.CodeRay{border-collapse:separate;border-spacing:0;margin-bottom:0;border:0;background:none}
table.CodeRay td{vertical-align: top;line-height:1.45}
table.CodeRay td.line-numbers{text-align:right}
table.CodeRay td.line-numbers>pre{padding:0;color:rgba(0,0,0,.3)}
table.CodeRay td.code{padding:0 0 0 .5em}
table.CodeRay td.code>pre{padding:0}
.CodeRay .debug{color:#fff !important;background:#000080 !important}
.CodeRay .annotation{color:#007}
.CodeRay .attribute-name{color:#000080}
.CodeRay .attribute-value{color:#700}
.CodeRay .binary{color:#509}
.CodeRay .comment{color:#998;font-style:italic}
.CodeRay .char{color:#04d}
.CodeRay .char .content{color:#04d}
.CodeRay .char .delimiter{color:#039}
.CodeRay .class{color:#458;font-weight:bold}
.CodeRay .complex{color:#a08}
.CodeRay .constant,.CodeRay .predefined-constant{color:#008080}
.CodeRay .color{color:#099}
.CodeRay .class-variable{color:#369}
.CodeRay .decorator{color:#b0b}
.CodeRay .definition{color:#099}
.CodeRay .delimiter{color:#000}
.CodeRay .doc{color:#970}
.CodeRay .doctype{color:#34b}
.CodeRay .doc-string{color:#d42}
.CodeRay .escape{color:#666}
.CodeRay .entity{color:#800}
.CodeRay .error{color:#808}
.CodeRay .exception{color:inherit}
.CodeRay .filename{color:#099}
.CodeRay .function{color:#900;font-weight:bold}
.CodeRay .global-variable{color:#008080}
.CodeRay .hex{color:#058}
.CodeRay .integer,.CodeRay .float{color:#099}
.CodeRay .include{color:#555}
.CodeRay .inline{color:#000}
.CodeRay .inline .inline{background:#ccc}
.CodeRay .inline .inline .inline{background:#bbb}
.CodeRay .inline .inline-delimiter{color:#d14}
.CodeRay .inline-delimiter{color:#d14}
.CodeRay .important{color:#555;font-weight:bold}
.CodeRay .interpreted{color:#b2b}
.CodeRay .instance-variable{color:#008080}
.CodeRay .label{color:#970}
.CodeRay .local-variable{color:#963}
.CodeRay .octal{color:#40e}
.CodeRay .predefined{color:#369}
.CodeRay .preprocessor{color:#579}
.CodeRay .pseudo-class{color:#555}
.CodeRay .directive{font-weight:bold}
.CodeRay .type{font-weight:bold}
.CodeRay .predefined-type{color:inherit}
.CodeRay .reserved,.CodeRay .keyword {color:#000;font-weight:bold}
.CodeRay .key{color:#808}
.CodeRay .key .delimiter{color:#606}
.CodeRay .key .char{color:#80f}
.CodeRay .value{color:#088}
.CodeRay .regexp .delimiter{color:#808}
.CodeRay .regexp .content{color:#808}
.CodeRay .regexp .modifier{color:#808}
.CodeRay .regexp .char{color:#d14}
.CodeRay .regexp .function{color:#404;font-weight:bold}
.CodeRay .string{color:#d20}
.CodeRay .string .string .string{background:#ffd0d0}
.CodeRay .string .content{color:#d14}
.CodeRay .string .char{color:#d14}
.CodeRay .string .delimiter{color:#d14}
.CodeRay .shell{color:#d14}
.CodeRay .shell .delimiter{color:#d14}
.CodeRay .symbol{color:#990073}
.CodeRay .symbol .content{color:#a60}
.CodeRay .symbol .delimiter{color:#630}
.CodeRay .tag{color:#008080}
.CodeRay .tag-special{color:#d70}
.CodeRay .variable{color:#036}
.CodeRay .insert{background:#afa}
.CodeRay .delete{background:#faa}
.CodeRay .change{color:#aaf;background:#007}
.CodeRay .head{color:#f8f;background:#505}
.CodeRay .insert .insert{color:#080}
.CodeRay .delete .delete{color:#800}
.CodeRay .change .change{color:#66f}
.CodeRay .head .head{color:#f4f}
</style>
<script src="//cdnjs.cloudflare.com/ajax/libs/jquery/2.0.3/jquery.js"></script>

<style>
  #header {
    background: url('../images/nxlog_ce_logo.png')
      no-repeat right bottom;
    background-size: auto 38%;
  }
  .literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] {
    /* Remove unnecessary vertical space in code listings */
    padding-top: 0;
    padding-bottom: 0;

    /* Reduce font size in code listings  */
    font-size: 0.9em
  }
</style>
</head>
<body class="book toc2 toc-left">
<div id="header">
<h1>NXLog Community Edition Reference Manual</h1>
<div class="details">
<span id="author" class="author">NXLog Ltd.</span><br>
<span id="revnumber">version 2.10.2150,</span>
<span id="revdate">November 2018</span>
<br><span id="revremark">Copyright © NXLog Ltd. 2018</span>
</div>
<div id="toc" class="toc2">
<div id="toctitle">Table of Contents</div>
<ul class="sectlevel1">
<li><a href="#man-pages">1. Man Pages</a>
<ul class="sectlevel2">
<li><a href="#nxlog-8">1.1. nxlog(8)</a></li>
<li><a href="#nxlog-processor-8">1.2. nxlog-processor(8)</a></li>
</ul>
</li>
<li><a href="#ref-config">2. Configuration</a>
<ul class="sectlevel2">
<li><a href="#general-directives">2.1. General Directives</a></li>
<li><a href="#config_global">2.2. Global Directives</a></li>
<li><a href="#config_module_common">2.3. Common Module Directives</a></li>
<li><a href="#route-directives">2.4. Route Directives</a></li>
</ul>
</li>
<li><a href="#ref-lang">3. Language</a>
<ul class="sectlevel2">
<li><a href="#lang_types">3.1. Types</a></li>
<li><a href="#lang_expressions">3.2. Expressions</a></li>
<li><a href="#lang_statements">3.3. Statements</a></li>
<li><a href="#lang_variables">3.4. Variables</a></li>
<li><a href="#lang_stat">3.5. Statistical Counters</a></li>
<li><a href="#core_funcs">3.6. Functions</a></li>
<li><a href="#core_procs">3.7. Procedures</a></li>
</ul>
</li>
<li><a href="#extension-modules">4. Extension Modules</a>
<ul class="sectlevel2">
<li><a href="#xm_charconv">4.1. Character Set Conversion (xm_charconv)</a></li>
<li><a href="#xm_csv">4.2. Delimiter-Separated Values (xm_csv)</a></li>
<li><a href="#xm_exec">4.3. External Programs (xm_exec)</a></li>
<li><a href="#xm_fileop">4.4. File Operations (xm_fileop)</a></li>
<li><a href="#xm_gelf">4.5. GELF (xm_gelf)</a></li>
<li><a href="#xm_json">4.6. JSON (xm_json)</a></li>
<li><a href="#xm_kvp">4.7. Key-Value Pairs (xm_kvp)</a></li>
<li><a href="#xm_multiline">4.8. Multi-Line Parser (xm_multiline)</a></li>
<li><a href="#xm_perl">4.9. Perl (xm_perl)</a></li>
<li><a href="#xm_syslog">4.10. Syslog (xm_syslog)</a></li>
<li><a href="#xm_wtmp">4.11. WTMP (xm_wtmp)</a></li>
<li><a href="#xm_xml">4.12. XML (xm_xml)</a></li>
</ul>
</li>
<li><a href="#input-modules">5. Input Modules</a>
<ul class="sectlevel2">
<li><a href="#core_fields">5.1. Fields</a></li>
<li><a href="#im_dbi">5.2. DBI (im_dbi)</a></li>
<li><a href="#im_exec">5.3. External Programs (im_exec)</a></li>
<li><a href="#im_file">5.4. Files (im_file)</a></li>
<li><a href="#im_internal">5.5. Internal (im_internal)</a></li>
<li><a href="#im_kernel">5.6. Kernel (im_kernel)</a></li>
<li><a href="#im_mark">5.7. Mark (im_mark)</a></li>
<li><a href="#im_mseventlog">5.8. EventLog for Windows XP/2000/2003 (im_mseventlog)</a></li>
<li><a href="#im_msvistalog">5.9. EventLog for Windows 2008/Vista and Later (im_msvistalog)</a></li>
<li><a href="#im_null">5.10. Null (im_null)</a></li>
<li><a href="#im_ssl">5.11. TLS/SSL (im_ssl)</a></li>
<li><a href="#im_tcp">5.12. TCP (im_tcp)</a></li>
<li><a href="#im_udp">5.13. UDP (im_udp)</a></li>
<li><a href="#im_uds">5.14. Unix Domain Sockets (im_uds)</a></li>
</ul>
</li>
<li><a href="#processor-modules">6. Processor Modules</a>
<ul class="sectlevel2">
<li><a href="#pm_blocker">6.1. Blocker (pm_blocker)</a></li>
<li><a href="#pm_buffer">6.2. Buffer (pm_buffer)</a></li>
<li><a href="#pm_evcorr">6.3. Event Correlator (pm_evcorr)</a></li>
<li><a href="#pm_filter">6.4. Filter (pm_filter)</a></li>
<li><a href="#pm_norepeat">6.5. De-Duplicator (pm_norepeat)</a></li>
<li><a href="#pm_null">6.6. Null (pm_null)</a></li>
<li><a href="#pm_pattern">6.7. Pattern Matcher (pm_pattern)</a></li>
<li><a href="#pm_transformer">6.8. Format Converter (pm_transformer)</a></li>
</ul>
</li>
<li><a href="#output-modules">7. Output Modules</a>
<ul class="sectlevel2">
<li><a href="#om_blocker">7.1. Blocker (om_blocker)</a></li>
<li><a href="#om_dbi">7.2. DBI (om_dbi)</a></li>
<li><a href="#om_exec">7.3. Program (om_exec)</a></li>
<li><a href="#om_file">7.4. Files (om_file)</a></li>
<li><a href="#om_http">7.5. HTTP(s) (om_http)</a></li>
<li><a href="#om_null">7.6. Null (om_null)</a></li>
<li><a href="#om_ssl">7.7. TLS/SSL (om_ssl)</a></li>
<li><a href="#om_tcp">7.8. TCP (om_tcp)</a></li>
<li><a href="#om_udp">7.9. UDP (om_udp)</a></li>
<li><a href="#om_uds">7.10. Unix Domain Sockets (om_uds)</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div id="content">
<div class="sect1">
<h2 id="man-pages"><a class="anchor" href="#man-pages"></a>1. Man Pages</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="nxlog-8"><a class="anchor" href="#nxlog-8"></a>1.1. nxlog(8)</h3>
<div class="openblock">
<div class="content">
<h4 id="name" class="discrete">NAME</h4>
<div class="paragraph">
<p>nxlog - collects, processes, converts, and forwards event logs in many
different formats</p>
</div>
<h4 id="synopsis" class="discrete">SYNOPSIS</h4>
<div class="paragraph">
<p><strong>nxlog</strong> [-c <em>conffile</em>] [-f]</p>
</div>
<div class="paragraph">
<p><strong>nxlog</strong> [-c <em>conffile</em>] -v</p>
</div>
<div class="paragraph">
<p><strong>nxlog</strong> [-r | -s]</p>
</div>
<h4 id="description" class="discrete">DESCRIPTION</h4>
<div class="paragraph">
<p>NXLog can process high volumes of event logs from many different
sources. Supported types of log processing include rewriting, correlating,
alerting, filtering, and pattern matching. Additional features include
scheduling, log file rotation, buffering, and prioritized processing. After
processing, NXLog can store or forward event logs in any of many
supported formats. Inputs, outputs, and processing are implemented with a
modular architecture and a powerful configuration language.</p>
</div>
<div class="paragraph">
<p>While the details provided here apply to NXLog installations on Linux
and other UNIX-style operating systems in particular, a few Windows-specific
notes are included.</p>
</div>
<h4 id="options" class="discrete">OPTIONS</h4>
<div class="dlist">
<dl>
<dt class="hdlist1"><strong>-c</strong> <em>conffile</em>, <strong>--conf</strong> <em>conffile</em></dt>
<dd>
<p>Specify an alternate configuration file
<em>conffile</em>. On Windows, this option must be used with <strong>-f</strong>. To change the
configuration file used by the NXLog service on Windows, modify the
service parameters.</p>
</dd>
<dt class="hdlist1"><strong>-f</strong>, <strong>--foreground</strong></dt>
<dd>
<p>Run in foreground, do not daemonize.</p>
</dd>
<dt class="hdlist1"><strong>-h</strong>, <strong>--help</strong></dt>
<dd>
<p>Print help.</p>
</dd>
<dt class="hdlist1"><strong>-r</strong>, <strong>--reload</strong></dt>
<dd>
<p>Reload configuration of a running instance.</p>
</dd>
<dt class="hdlist1"><strong>-s</strong>, <strong>--stop</strong></dt>
<dd>
<p>Send stop signal to a running instance.</p>
</dd>
<dt class="hdlist1"><strong>-v</strong>, <strong>--verify</strong></dt>
<dd>
<p>Verify configuration file syntax.</p>
</dd>
</dl>
</div>
<h4 id="signals" class="discrete">SIGNALS</h4>
<div class="paragraph">
<p>Various signals can be used to control the NXLog process. Some
corresponding Windows control codes are also available; these are shown in
parentheses where applicable.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">SIGHUP</dt>
<dd>
<p>This signal causes NXLog to reload the configuration and
restart the modules. On Windows, "sc stop nxlog" and "sc start nxlog" can be
used instead.</p>
</dd>
<dt class="hdlist1">SIGUSR1 (200)</dt>
<dd>
<p>This signal generates an internal log message with information
about the current state of NXLog and its configured module
instances. The message will be generated with INFO log level, written to the
log file (if configured with <a href="#config_global_logfile">LogFile</a>), and
available via the <a href="#im_internal">im_internal</a> module.</p>
</dd>
<dt class="hdlist1">SIGUSR2 (201)</dt>
<dd>
<p>This signal causes NXLog to switch to the DEBUG log
level. This is equivalent to setting the <a href="#config_global_loglevel">LogLevel</a>
directive to <code>DEBUG</code> but does not require NXLog to be restarted.</p>
</dd>
<dt class="hdlist1">SIGINT/SIGQUIT/SIGTERM</dt>
<dd>
<p>NXLog will exit if it receives one of these
signals. On Windows, "sc stop nxlog" can be used instead.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>On Linux/UNIX, a signal can be sent with the <code>kill</code> command. The following,
for example, sends the SIGUSR1 signal:</p>
</div>
<div class="paragraph">
<p><code>kill -SIGUSR1 $(cat /var/run/nxlog/nxlog.pid)</code></p>
</div>
<div class="paragraph">
<p>On Windows, a signal can be sent with the <code>sc</code> command. The following, for
example, sends the 200 signal:</p>
</div>
<div class="paragraph">
<p><code>sc control nxlog 200</code></p>
</div>
<h4 id="files" class="discrete">FILES</h4>
<div class="dlist">
<dl>
<dt class="hdlist1"><strong>/bin/nxlog</strong></dt>
<dd>
<p>The main NXLog executable</p>
</dd>
<dt class="hdlist1"><strong>/bin/nxlog-stmnt-verifier</strong></dt>
<dd>
<p>This tool can be used to check
NXLog Language statements. All statements are read from standard
input and then validated. If a statement is invalid, the tool prints an
error to standard error and exits non-zero.</p>
</dd>
<dt class="hdlist1"><strong>/etc/nxlog.conf</strong></dt>
<dd>
<p>The default configuration file</p>
</dd>
<dt class="hdlist1"><strong>/usr/libexec/nxlog/modules/</strong></dt>
<dd>
<p>The NXLog modules are located in this
directory, by default. See the <a href="#config_global_moduledir">ModuleDir</a>
directive.</p>
</dd>
<dt class="hdlist1"><strong>/var/spool/nxlog/configcache.dat</strong></dt>
<dd>
<p>This is the position cache file
where positions are saved. See the <a href="#config_global_nocache">NoCache</a>
directive, in addition to <a href="#config_global_cachedir">CacheDir</a>.</p>
</dd>
<dt class="hdlist1"><strong>/var/run/nxlog/nxlog.pid</strong></dt>
<dd>
<p>The process ID (PID) of the currently
running NXLog process is written to this file. See the
<a href="#config_global_pidfile">PidFile</a> directive.</p>
</dd>
</dl>
</div>
<h4 id="see-also" class="discrete">SEE ALSO</h4>
<div class="paragraph">
<p><a href="#nxlog-processor-8">nxlog-processor(8)</a></p>
</div>
<div class="paragraph">
<p><strong>NXLog website:</strong> <a href="https://nxlog.co" class="bare">https://nxlog.co</a></p>
</div>
<div class="paragraph">
<p><strong>NXLog User Guide:</strong> <a href="https://nxlog.co/documentation/nxlog-user-guide" class="bare">https://nxlog.co/documentation/nxlog-user-guide</a></p>
</div>
<h4 id="copyright" class="discrete">COPYRIGHT</h4>
<div class="paragraph">
<p>Copyright © NXLog Ltd. 2018</p>
</div>
<div class="paragraph">
<p>The NXLog Community Edition is licensed under the NXLog Public License. The
NXLog Enterprise Edition is not free and has a commercial license.</p>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="nxlog-processor-8"><a class="anchor" href="#nxlog-processor-8"></a>1.2. nxlog-processor(8)</h3>
<div class="openblock">
<div class="content">
<h4 id="name-2" class="discrete">NAME</h4>
<div class="paragraph">
<p>nxlog-processor - performs batch log processing</p>
</div>
<h4 id="synopsis-2" class="discrete">SYNOPSIS</h4>
<div class="paragraph">
<p><strong>nxlog-processor</strong> [-c <em>conffile</em>] [-v]</p>
</div>
<h4 id="description-2" class="discrete">DESCRIPTION</h4>
<div class="paragraph">
<p>The nxlog-processor tool is similar to the NXLog daemon and uses the same
configuration file. However, it runs in the foreground and exits after all
input log data has been processed. Common input sources are files and
databases. This tool is useful for log processing tasks such as:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>loading a group of files into a database,</p>
</li>
<li>
<p>converting between different formats,</p>
</li>
<li>
<p>testing configuration, or</p>
</li>
<li>
<p>doing offline event correlation.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>While the details provided here apply to NXLog installations on Linux
and other UNIX-style operating systems in particular, a few Windows-specific
notes are included.</p>
</div>
<h4 id="options-2" class="discrete">OPTIONS</h4>
<div class="dlist">
<dl>
<dt class="hdlist1"><strong>-c</strong> <em>conffile</em>, <strong>--conf</strong> <em>conffile</em></dt>
<dd>
<p>Specify an alternate configuration file
<em>conffile</em>.</p>
</dd>
<dt class="hdlist1"><strong>-h</strong>, <strong>--help</strong></dt>
<dd>
<p>Print help.</p>
</dd>
<dt class="hdlist1"><strong>-v</strong>, <strong>--verify</strong></dt>
<dd>
<p>Verify configuration file syntax.</p>
</dd>
</dl>
</div>
<h4 id="files-2" class="discrete">FILES</h4>
<div class="dlist">
<dl>
<dt class="hdlist1"><strong>/bin/nxlog-processor</strong></dt>
<dd>
<p>The main NXLog-processor executable</p>
</dd>
<dt class="hdlist1"><strong>/bin/nxlog-stmnt-verifier</strong></dt>
<dd>
<p>This tool can be used to check
NXLog Language statements. All statements are read from standard
input and then validated. If a statement is invalid, the tool prints an
error to standard error and exits non-zero.</p>
</dd>
<dt class="hdlist1"><strong>/etc/nxlog.conf</strong></dt>
<dd>
<p>The default configuration file</p>
</dd>
<dt class="hdlist1"><strong>/var/spool/nxlog/configcache.dat</strong></dt>
<dd>
<p>This is the position cache file
where positions are saved. To disable position caching, as may be desirable
when using nxlog-processor, set the <a href="#config_global_nocache">NoCache</a>
directive to TRUE.</p>
</dd>
</dl>
</div>
<h4 id="see-also-2" class="discrete">SEE ALSO</h4>
<div class="paragraph">
<p><a href="#nxlog-8">nxlog(8)</a></p>
</div>
<div class="paragraph">
<p><strong>NXLog website:</strong> <a href="https://nxlog.co" class="bare">https://nxlog.co</a></p>
</div>
<div class="paragraph">
<p><strong>NXLog User Guide:</strong> <a href="https://nxlog.co/documentation/nxlog-user-guide" class="bare">https://nxlog.co/documentation/nxlog-user-guide</a></p>
</div>
<h4 id="copyright-2" class="discrete">COPYRIGHT</h4>
<div class="paragraph">
<p>Copyright © NXLog Ltd. 2018</p>
</div>
<div class="paragraph">
<p>The NXLog Community Edition is licensed under the NXLog Public License. The
NXLog Enterprise Edition is not free and has a commercial license.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="ref-config"><a class="anchor" href="#ref-config"></a>2. Configuration</h2>
<div class="sectionbody">
<div class="paragraph">
<p>An NXLog configuration consists of global directives, module
instances, and routes. The following sections list the core NXLog
directives provided. Additional directives are provided at the module level.
A valid configuration must contain at least one input module instance and at
least one output module instance.</p>
</div>
<div class="paragraph">
<p>A module instance name may contain letters, digits, periods (<code>.</code>), and
underscores (<code>_</code>). The first character in a module instance name must
be a letter or an underscore. The corresponding regular expression is
<code>[a-zA-Z_][a-zA-Z0-9._]*</code>.</p>
</div>
<div class="paragraph">
<p>A route instance name may contain letters, digits, periods (<code>.</code>), and
underscores (<code>_</code>). The first character in a route instance name must be
a letter, a digit, or an underscore. The corresponding regular expression is
<code>[a-zA-Z0-9_][a-zA-Z0-9._]*</code>.</p>
</div>
<div class="sect2">
<h3 id="general-directives"><a class="anchor" href="#general-directives"></a>2.1. General Directives</h3>
<div class="paragraph">
<p>The following directives can be used throughout the configuration
file. These directives are handled by the configuration parser, and
substitutions occur before the configuration check.</p>
</div>
<div id="config_general_define" class="dlist">
<dl>
<dt class="hdlist1">define</dt>
<dd>
<p>Use this directive to configure a constant or macro to be
used later. Refer to a <code>define</code> by surrounding the name with percent
signs (<code>%</code>). Enclose a group of statements with curly braces (<code>{}</code>).</p>
<div id="using_define" class="exampleblock">
<div class="title">Example 1. Using the define Directive</div>
<div class="content">
<div class="paragraph">
<p>This configuration shows three example defines: <code>BASEDIR</code> is a
constant, <code>IMPORTANT</code> is a statement, and <code>WARN_DROP</code> is a group of
statements.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
</pre></td>
  <td class="code"><pre>define BASEDIR /var/log
define IMPORTANT if $raw_event =~ /important/ \
                    $Message = 'IMPORTANT ' + $raw_event;
define WARN_DROP { log_warning(&quot;dropping message&quot;); drop(); }

<span class="tag">&lt;Input</span> <span class="attribute-name">messages</span><span class="tag">&gt;</span>
    Module  im_file
    File    '%BASEDIR%/messages'
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">proftpd</span><span class="tag">&gt;</span>
    Module  im_file
    File    '%BASEDIR%/proftpd.log'
    <span class="tag">&lt;Exec&gt;</span>
        %IMPORTANT%
        if $raw_event =~ /dropme/ %WARN_DROP%
    <span class="tag">&lt;/Exec&gt;</span>
<span class="tag">&lt;/Input&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="config_general_include" class="dlist">
<dl>
<dt class="hdlist1">include</dt>
<dd>
<p>This directive allows a specified file to be included in the
current configuration file. Wildcarded filenames are supported.</p>
<div class="openblock">
<div class="content">
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
The <a href="#config_global_spooldir">SpoolDir</a> directive only takes
      effect after the configuration is parsed, so relative paths
      specified with the <strong>include</strong> directive must be relative to the
      working directory NXLog was started from.
</td>
</tr>
</table>
</div>
<div class="exampleblock">
<div class="title">Example 2. Using the include Directive</div>
<div class="content">
<div class="paragraph">
<p>This example includes a file relative to the directory NXLog
is started from:</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
</pre></td>
  <td class="code"><pre>include modules/module1.conf</pre></td>
</tr></table></code></pre>
</div>
</div>
<div class="paragraph">
<p>This example includes all matching files and uses an absolute path:</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
</pre></td>
  <td class="code"><pre>include /etc/nxlog.d/*.conf</pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect2">
<h3 id="config_global"><a class="anchor" href="#config_global"></a>2.2. Global Directives</h3>
<div id="config_global_cachedir" class="dlist">
<dl>
<dt class="hdlist1">CacheDir</dt>
<dd>
<p>This directive specifies a directory where the cache file
(<code>configcache.dat</code>) should be written. This directive has a
compiled-in value which is used by default.</p>
</dd>
</dl>
</div>
<div id="config_global_flowcontrol" class="dlist">
<dl>
<dt class="hdlist1">FlowControl</dt>
<dd>
<p>This optional boolean directive specifies whether all
input and processor modules should use flow control. This defaults
to TRUE. See the description of the module level
<a href="#config_module_flowcontrol">FlowControl</a> directive for more
information.</p>
</dd>
</dl>
</div>
<div id="config_global_group" class="dlist">
<dl>
<dt class="hdlist1">Group</dt>
<dd>
<p>Similar to <a href="#config_global_user">User</a>, NXLog will set
the group ID to run under. The group can be specified by name or
numeric ID. This directive has no effect when running on the Windows
platform or with <a href="#nxlog-processor-8">nxlog-processor(8)</a>.</p>
</dd>
</dl>
</div>
<div id="config_global_ignoreerrors" class="dlist">
<dl>
<dt class="hdlist1">IgnoreErrors</dt>
<dd>
<p>If set to FALSE, NXLog will stop when it
encounters a problem with the configuration file (such as an invalid
module directive) or if there is any other problem which would
prevent all modules functioning correctly. If set to TRUE,
NXLog will start after logging the problem. The default
value is TRUE.</p>
</dd>
</dl>
</div>
<div id="config_global_logfile" class="dlist">
<dl>
<dt class="hdlist1">LogFile</dt>
<dd>
<p>NXLog will write its internal log to this file. If
this directive is not specified, self logging is disabled. Note that
the <a href="#im_internal">im_internal</a> module can also be used to direct
internal log messages to files or different output destinations, but
this does not support log level below <code>INFO</code>. This <strong>LogFile</strong>
directive is especially useful for debugging.</p>
</dd>
</dl>
</div>
<div id="config_global_loglevel" class="dlist">
<dl>
<dt class="hdlist1">LogLevel</dt>
<dd>
<p>This directive has five possible values: <code>CRITICAL</code>,
<code>ERROR</code>, <code>WARNING</code>, <code>INFO</code>, and <code>DEBUG</code>. It will set both the
logging level used for <a href="#config_global_logfile">LogFile</a> and the
standard output if NXLog is started in the foreground. The
default <strong>LogLevel</strong> is <code>INFO</code>.</p>
</dd>
</dl>
</div>
<div id="config_global_moduledir" class="dlist">
<dl>
<dt class="hdlist1">ModuleDir</dt>
<dd>
<p>By default the NXLog binaries have a compiled-in
value for the directory to search for loadable modules. This can be
overridden with this directive. The module directory contains
sub-directories for each module type (extension, input, output, and
processor), and the module binaries are located in those.</p>
</dd>
</dl>
</div>
<div id="config_global_nocache" class="dlist">
<dl>
<dt class="hdlist1">NoCache</dt>
<dd>
<p>Some modules save data to a cache file which is persisted
across a shutdown/restart. Modules such as <a href="#im_file">im_file</a> will
save the file position in order to continue reading from the same
position after a restart as before. This caching mechanism can be
explicitly turned off with this directive. This is mostly useful
with <a href="#nxlog-processor-8">nxlog-processor(8)</a> in offline mode. If
this boolean directive is not specified, it defaults to FALSE
(caching is enabled).
Note that many input modules, such as <em>im_file</em>, provide a
<a href="#im_file_config_savepos">SavePos</a> directive that can be used to disable the
position cache for a specific module instance. <strong>SavePos</strong> has no effect if
the cache is disabled globally with <code>NoCache TRUE</code>.</p>
</dd>
</dl>
</div>
<div id="config_global_nofreeonexit" class="dlist">
<dl>
<dt class="hdlist1">NoFreeOnExit</dt>
<dd>
<p>This directive is for debugging. When set to TRUE,
NXLog will not free module resources on exit, allowing
valgrind to show proper stack trace locations in module function
calls. The default value is FALSE.</p>
</dd>
</dl>
</div>
<div id="config_global_panic" class="dlist">
<dl>
<dt class="hdlist1">Panic</dt>
<dd>
<p>A panic condition is a critical state which usually indicates
a bug. Assertions are used in NXLog code for checking
conditions where the code will not work unless the asserted
condition is satisfied, and for security. Failing assertions result
in a panic and suggest a bug in the code. A typical case is checking
for NULL pointers before pointer dereference. This directive can
take three different values: <code>HARD</code>, <code>SOFT</code>, or <code>OFF</code>. <code>HARD</code> will
cause an abort in case the assertion fails. This is how most C based
programs work. <code>SOFT</code> will cause an exception to be thrown at the
place of the panic/assertion. In case of NULL pointer checks this is
identical to a NullPointerException in Java. It is possible that
NXLog can recover from exceptions and can continue to
process log messages, or at least the other modules can. In case of
assertion failure the location and the condition is printed at
<code>CRITICAL</code> log level in <code>HARD</code> mode and <code>ERROR</code> log level in <code>SOFT</code>
mode. If <strong>Panic</strong> is set to <code>OFF</code>, the failing condition is printed
in the logs but the execution will continue on the normal code
path. Most of the time this will result in a segmentation fault or
other undefined behavior, though in some cases turning off a buggy
assertion or panic will solve the problems caused by it in
<code>HARD</code>/<code>SOFT</code> mode. The default value for <strong>Panic</strong> is <code>SOFT</code>.</p>
</dd>
</dl>
</div>
<div id="config_global_pidfile" class="dlist">
<dl>
<dt class="hdlist1">PidFile</dt>
<dd>
<p>Under Unix operating systems, NXLog writes a PID
file as other system daemons do. The default PID file can be
overridden with this directive in case multiple daemon instances
need to be running. This directive has no effect when running on the
Windows platform or with <a href="#nxlog-processor-8">nxlog-processor(8)</a>.</p>
</dd>
</dl>
</div>
<div id="config_global_rootdir" class="dlist">
<dl>
<dt class="hdlist1">RootDir</dt>
<dd>
<p>NXLog will set its root directory to the value
specified with this directive. If
<a href="#config_global_spooldir">SpoolDir</a> is also set, this will be
relative to the value of <strong>RootDir</strong> (chroot() is called first). This
directive has no effect when running on the Windows platform or with
the <a href="#nxlog-processor-8">nxlog-processor(8)</a>.</p>
</dd>
</dl>
</div>
<div id="config_global_spooldir" class="dlist">
<dl>
<dt class="hdlist1">SpoolDir</dt>
<dd>
<p>NXLog will change its working directory to the
value specified with this directive. This is useful with files
created through relative filenames (for example, with
<a href="#om_file">om_file</a>) and in case of core dumps. This directive has
no effect with the <a href="#nxlog-processor-8">nxlog-processor(8)</a>.</p>
</dd>
</dl>
</div>
<div id="config_global_suppressrepeatinglogs" class="dlist">
<dl>
<dt class="hdlist1">SuppressRepeatingLogs</dt>
<dd>
<p>Under some circumstances it is possible for
NXLog to generate an extreme amount of internal logs
consisting of the same message due to an incorrect configuration or a
software bug. In this case, the <a href="#config_global_logfile">LogFile</a>
can quickly consume the available disk space. With this directive,
NXLog will write at most 2 lines per second if the same
message is generated successively, by logging "last message repeated
n times" messages. If this boolean directive is not specified, it
defaults to TRUE (suppression of repeating messages is enabled).</p>
</dd>
</dl>
</div>
<div id="config_global_threads" class="dlist">
<dl>
<dt class="hdlist1">Threads</dt>
<dd>
<p>This directive specifies the number of worker threads
to use. The number of the worker threads is calculated and set to an
optimal value if this directive is not defined. Do not set this
unless you know what you are doing.</p>
</dd>
</dl>
</div>
<div id="config_global_user" class="dlist">
<dl>
<dt class="hdlist1">User</dt>
<dd>
<p>NXLog will drop to the user specified with this
directive. This is useful if NXLog needs privileged access
to some system resources (such as kernel messages or to bind a port
below 1024). On Linux systems NXLog will use capabilities to
access these resources. In this case NXLog must be started
as root. The user can be specified by name or numeric ID. This
directive has no effect when running on the Windows platform or with
<a href="#nxlog-processor-8">nxlog-processor(8)</a>.</p>
</dd>
</dl>
</div>
</div>
<div class="sect2">
<h3 id="config_module_common"><a class="anchor" href="#config_module_common"></a>2.3. Common Module Directives</h3>
<div class="paragraph">
<p>The following directives are common to all modules. The
<a href="#config_module_module">Module</a> directive is mandatory.</p>
</div>
<div id="config_module_module" class="dlist">
<dl>
<dt class="hdlist1">Module</dt>
<dd>
<p>This mandatory directive specifies which binary should be
loaded. The module binary has a <code>.so</code> extension on Unix and a <code>.dll</code>
on Windows platforms and resides under the
<a href="#config_global_moduledir">ModuleDir</a> location. Each module binary
name is prefixed with <code>im_</code>, <code>pm_</code>, <code>om_</code>, or <code>xm_</code> (for <em>input</em>,
<em>processor</em>, <em>output</em>, and <em>extension</em>, respectively).
It is possible for multiple instances to use the same loadable
binary. In this case the binary is only loaded once but instantiated
multiple times. Different module instances may have different
configurations.</p>
</dd>
</dl>
</div>
<hr>
<div id="config_module_flowcontrol" class="dlist">
<dl>
<dt class="hdlist1">FlowControl</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>This optional boolean directive specifies whether the module instance should
use flow control. <strong>FlowControl</strong> is only valid for Input and Processor
modules. By default,
<strong>FlowControl</strong> is TRUE (enabled). This module-level directive can be used to
override the global <a href="#config_global_flowcontrol">FlowControl</a> directive.</p>
</div>
<div class="paragraph">
<p>When flow control is in effect, a module (Input or Processor) which tries to
forward log data to the next module in the route will be suspended if the next
module cannot accept more data. For example, if a network module (such as
<a href="#om_tcp">om_tcp</a>) cannot forward logs because of a network error, the
preceding module in the route will be paused. When flow control is disabled,
the module will drop the log record if the queue of the next module in the
route is full.</p>
</div>
<div class="paragraph">
<p>Disabling flow control can be useful when multiple output modules are
configured to store or forward log data. When flow control is enabled, the
output modules will only process log data if all outputs are
functional. Consider the case where log data is stored in a file using
<a href="#om_file">om_file</a> and also forwarded over the network using
<a href="#om_tcp">om_tcp</a>. When flow control is enabled, a network disconnection will
make the data flow stall and log data will not be written into the local file
either. With flow control disabled, NXLog will write log data to the
file and will drop messages that cannot be forwarded over the network.</p>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<div class="title">Warning</div>
</td>
<td class="content">
Suspending an <a href="#im_udp">im_udp</a> instance is ineffective, because UDP provides
no receipt acknowledgement.
Suspending an <a href="#im_uds">im_uds</a> instance when collecting local Syslog messages
from the /dev/log Unix domain socket will cause the syslog() system call to
block in any programs trying to write to the system log.
It is generally recommended to disable flow control in these cases.
</td>
</tr>
</table>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="config_inputtype" class="dlist">
<dl>
<dt class="hdlist1">InputType</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>This directive specifies the name of the registered input reader function to
be used for parsing raw events from input data. Names are treated case
insensitively.  This directive is only available for stream oriented input
modules: <a href="#im_file">im_file</a>, <a href="#im_exec">im_exec</a>, <a href="#im_ssl">im_ssl</a>,
<a href="#im_tcp">im_tcp</a>, <a href="#im_udp">im_udp</a>, and <a href="#im_uds">im_uds</a>. These modules
work by filling an input buffer with data read from the source. If the read
operation was successful (there was data coming from the source), the module
calls the specified callback function. If this is not explicitly specified,
the module default will be used. Note that <em>im_udp</em> may only work properly if
log messages do not span multiple packets and are within the UDP message size
limit. Otherwise the loss of a packet may lead to parsing errors.</p>
</div>
<div class="paragraph">
<p>Modules may provide custom input reader functions. Once these are registered
into the NXLog core, the modules listed above will be capable of using
these. This makes it easier to implement custom protocols because these can be
developed without concern for the transport layer.</p>
</div>
<div class="paragraph">
<p>The following input reader functions are provided by the NXLog core:</p>
</div>
<div id="config_inputtype_binary" class="dlist">
<dl>
<dt class="hdlist1">Binary</dt>
<dd>
<p>The input is parsed in the NXLog binary format, which
preserves the parsed fields of the event records. The
<a href="#config_inputtype_linebased">LineBased</a> reader will automatically
detect event records in the binary NXLog format, so it is
only recommended to configure InputType to <strong>Binary</strong> if compatibility
with other logging software is not required.</p>
</dd>
</dl>
</div>
<div id="config_inputtype_dgram" class="dlist">
<dl>
<dt class="hdlist1">Dgram</dt>
<dd>
<p>Once the buffer is filled with data, it is considered to be
one event record. This is the default for the <a href="#im_udp">im_udp</a>
input module, since UDP Syslog messages arrive in separate packets.</p>
</dd>
</dl>
</div>
<div id="config_inputtype_linebased" class="dlist">
<dl>
<dt class="hdlist1">LineBased</dt>
<dd>
<p>The input is assumed to contain event records separated by
newlines. It can handle both CRLF (Windows) and LF (Unix)
line-breaks. Thus if an LF (<code>\n</code>) or CRLF (<code>\r\n</code>) is found, the
function assumes that it has reached the end of the event record.</p>
</dd>
</dl>
</div>
<div class="exampleblock">
<div class="title">Example 3. TCP Input Assuming NXLog Format</div>
<div class="content">
<div class="paragraph">
<p>This configuration explicitly specifies the <a href="#config_inputtype_binary">Binary</a>
InputType.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Input</span> <span class="attribute-name">tcp</span><span class="tag">&gt;</span>
    Module      im_tcp
    Port        2345
    InputType   Binary
<span class="tag">&lt;/Input&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="config_outputtype" class="dlist">
<dl>
<dt class="hdlist1">OutputType</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>This directive specifies the name of the registered output writer function to
be used for formatting raw events when storing or forwarding output. Names are
treated case insensitively. This directive is only available for stream
oriented output modules: <a href="#om_file">om_file</a>, <a href="#om_exec">om_exec</a>,
<a href="#om_ssl">om_ssl</a>, <a href="#om_tcp">om_tcp</a>, <a href="#om_udp">om_udp</a>, and
<a href="#om_uds">om_uds</a>. These modules work by filling the output buffer with data
to be written to the destination. The specified callback function is called
before the write operation. If this is not explicitly specified, the module
default will be used.</p>
</div>
<div class="paragraph">
<p>Modules may provide custom output formatter functions. Once these are
registered into the NXLog core, the modules listed above will
be capable of using these. This makes it easier to implement custom
protocols because these can be developed without concern for the
transport layer.</p>
</div>
<div class="paragraph">
<p>The following output writer functions are provided by the NXLog core:</p>
</div>
<div id="config_outputtype_binary" class="dlist">
<dl>
<dt class="hdlist1">Binary</dt>
<dd>
<p>The output is written in the NXLog binary format
which preserves parsed fields of the event records.</p>
</dd>
</dl>
</div>
<div id="config_outputtype_dgram" class="dlist">
<dl>
<dt class="hdlist1">Dgram</dt>
<dd>
<p>Once the buffer is filled with data, it is considered to be
one event record. This is the default for the <a href="#om_udp">om_udp</a>
output module, since UDP Syslog messages are sent in separate
packets.</p>
</dd>
</dl>
</div>
<div id="config_outputtype_linebased" class="dlist">
<dl>
<dt class="hdlist1">LineBased</dt>
<dd>
<p>The output will contain event records separated by
newlines. The record terminator is CRLF (<code>\r\n</code>).</p>
</dd>
</dl>
</div>
<div class="exampleblock">
<div class="title">Example 4. TCP Output Sending Messages in NXLog Format</div>
<div class="content">
<div class="paragraph">
<p>This configuration explicitly specifies the
<a href="#config_outputtype_binary">Binary</a> OutputType.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Output</span> <span class="attribute-name">tcp</span><span class="tag">&gt;</span>
    Module      om_tcp
    Port        2345
    Host        localhost
    OutputType  Binary
<span class="tag">&lt;/Output&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div class="sect3">
<h4 id="config_module_exec"><a class="anchor" href="#config_module_exec"></a>2.3.1. Exec</h4>
<div class="paragraph">
<p>The <strong>Exec</strong> directive/block contains <a href="#lang_statements">statements</a> in
the <a href="#ref-lang">NXLog language</a> which are executed when a module
receives a log message. This directive is available in all
<a href="#input-modules">input</a>, <a href="#processor-modules">processor</a>, and
<a href="#output-modules">output</a> modules.  It is not available in most
<a href="#extension-modules">extension</a> modules because these do not handle
log messages directly (the <a href="#xm_multiline">xm_multiline</a> and
<a href="#xm_rewrite">xm_rewrite</a> modules do provide <strong>Exec</strong> directives).</p>
</div>
<div class="exampleblock">
<div class="title">Example 5. Simple Exec Statement</div>
<div class="content">
<div class="paragraph">
<p>This statement assigns a value to the <code>$Hostname</code> field in the event
record.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
</pre></td>
  <td class="code"><pre>Exec    $Hostname = 'myhost';</pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Each directive must be on one line unless it contains a trailing
backslash (<code>\</code>) character.</p>
</div>
<div id="exec-statement-spanning-multiple-lines" class="exampleblock">
<div class="title">Example 6. Exec Statement Spanning Multiple Lines</div>
<div class="content">
<div class="paragraph">
<p>This <a href="#lang_statement_if">if</a> statement uses line continuation to span
multiple lines.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
</pre></td>
  <td class="code"><pre>Exec    if $Message =~ /something interesting/       \
            log_info(&quot;found something interesting&quot;); \
        else                                         \
            log_debug(&quot;found nothing interesting&quot;);</pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>More than one <strong>Exec</strong> directive or block may be specified. They are
executed in the order of appearance. Each <strong>Exec</strong> directive must
contain a full statement. Therefore it is not possible to split the
lines in the previous example into multiple <strong>Exec</strong> directives. It is
only possible to split the <strong>Exec</strong> directive if it contains multiple
statements.</p>
</div>
<div class="exampleblock">
<div class="title">Example 7. Equivalent Use of Statements in Exec</div>
<div class="content">
<div class="paragraph">
<p>This example shows two equivalent uses of the <strong>Exec</strong> directive.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
</pre></td>
  <td class="code"><pre>Exec    log_info(&quot;first&quot;); \
        log_info(&quot;second&quot;);</pre></td>
</tr></table></code></pre>
</div>
</div>
<div class="paragraph">
<p>This produces identical behavior:</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
</pre></td>
  <td class="code"><pre>Exec    log_info(&quot;first&quot;);
Exec    log_info(&quot;second&quot;);</pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>The <strong>Exec</strong> directive can also be used as a block. To use multiple
statements spanning more than one line, it is recommended to use the
<code>&lt;Exec&gt;</code> block instead. When using a block, it is not necessary to use
the backslash (<code>\</code>) character for line continuation.</p>
</div>
<div class="exampleblock">
<div class="title">Example 8. Using the Exec Block</div>
<div class="content">
<div class="paragraph">
<p>This example shows two equivalent uses of <strong>Exec</strong>, first as a
<em>directive</em>, then as a <em>block</em>.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
</pre></td>
  <td class="code"><pre>Exec    log_info(&quot;first&quot;); \
        log_info(&quot;second&quot;);</pre></td>
</tr></table></code></pre>
</div>
</div>
<div class="paragraph">
<p>The following <strong>Exec</strong> <em>block</em> is equivalent. Notice the backslash (<code>\</code>)
is omitted.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Exec&gt;</span>
    log_info(&quot;first&quot;);
    log_info(&quot;second&quot;);
<span class="tag">&lt;/Exec&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="config_module_schedule"><a class="anchor" href="#config_module_schedule"></a>2.3.2. Schedule</h4>
<div class="paragraph">
<p>The Schedule block can be used to execute periodic jobs, such as log
rotation or any other task. Scheduled jobs have the same priority as
the module. The Schedule block has the following directives:</p>
</div>
<div id="config_module_schedule_every" class="dlist">
<dl>
<dt class="hdlist1">Every</dt>
<dd>
<p>In addition to the crontab format it is possible to schedule
execution at periodic intervals. With the crontab format it is not
possible to run a job every five days for example, but this
directive enables it in a simple way. It takes an integer value with
an optional unit. The unit can be one of the following: <code>sec</code>,
<code>min</code>, <code>hour</code>, <code>day</code>, or <code>week</code>. If the unit is not specified, the
value is assumed to be in seconds.</p>
</dd>
</dl>
</div>
<div id="config_module_schedule_exec" class="dlist">
<dl>
<dt class="hdlist1">Exec</dt>
<dd>
<p>The mandatory <strong>Exec</strong> directive takes one or more NXLog
<a href="#lang_statements">statements</a>. This is the code which is actually
being scheduled. Multiple <strong>Exec</strong> directives can be specified within
one <strong>Schedule</strong> block. See the module-level
<a href="#config_module_exec">Exec</a> directive, this behaves the same. Note
that it is not possible to use <a href="#lang_fields">fields</a> in statements
here because execution is not triggered by log messages.</p>
</dd>
</dl>
</div>
<div id="config_module_schedule_first" class="dlist">
<dl>
<dt class="hdlist1">First</dt>
<dd>
<p>This directive sets the first execution time. If the value is
in the past, the next execution time is calculated as if
NXLog has been running since and jobs will not be run to
make up for missed events in the past. The directive takes a
<a href="#lang_literal_datetime">datetime</a> literal value.</p>
</dd>
</dl>
</div>
<div id="config_module_schedule_when" class="dlist">
<dl>
<dt class="hdlist1">When</dt>
<dd>
<p>This directive takes a value similar to a crontab entry: five
space-separated definitions for minute, hour, day, month, and
weekday. See the crontab(5) manual for the field definitions. It
supports lists as comma separated values and/or ranges. Step values
are also supported with the slash. Month and week days are not
supported, these must be defined with numeric values. The following
extensions are also supported:</p>
<div class="listingblock">
<div class="content">
<pre>@yearly        Run once a year, "0 0 1 1 *".
@annually      (same as @yearly)
@monthly       Run once a month, "0 0 1 * *".
@weekly        Run once a week, "0 0 * * 0".
@daily         Run once a day, "0 0 * * *".
@midnight      (same as @daily)
@hourly        Run once an hour, "0 * * * *".</pre>
</div>
</div>
</dd>
</dl>
</div>
<div class="exampleblock">
<div class="title">Example 9. Scheduled Exec Statements</div>
<div class="content">
<div class="paragraph">
<p>This example shows two scheduled <a href="#config_module_schedule_exec">Exec</a>
statements in a <a href="#im_tcp">im_tcp</a> module instance. The first is
executed every second, while the second uses a crontab(5) style value.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Input</span> <span class="attribute-name">in</span><span class="tag">&gt;</span>
    Module  im_tcp
    Port    2345

    <span class="tag">&lt;Schedule&gt;</span>
        Every   1 sec
        First   2010-12-17 00:19:06
        Exec    log_info(&quot;scheduled execution at &quot; + now());
    <span class="tag">&lt;/Schedule&gt;</span>

    <span class="tag">&lt;Schedule&gt;</span>
        When    1 */2 2-4 * *
        Exec    log_info(&quot;scheduled execution at &quot; + now());
    <span class="tag">&lt;/Schedule&gt;</span>
<span class="tag">&lt;/Input&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="route-directives"><a class="anchor" href="#route-directives"></a>2.4. Route Directives</h3>
<div class="paragraph">
<p>The following directives can be used in Route blocks. The
<a href="#config_route_path">Path</a> directive is mandatory.</p>
</div>
<div id="config_route_path" class="dlist">
<dl>
<dt class="hdlist1">Path</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The data flow is defined by the <strong>Path</strong> directive. First the instance names of
Input modules are specified. If more than one Input reads log messages which
feed data into the route, then these must be separated by commas. The list of
Input modules is followed by an arrow (<code>=&gt;</code>). Either processor modules or
output modules follow. Processor modules must be separated by arrows, not
commas, because they operate in series, unlike Input and Output modules which
work in parallel. Output modules are separated by commas. The <strong>Path</strong> must
specify at least an Input and an Output. The syntax is illustrated by the
following:</p>
</div>
<div class="paragraph">
<p><code>Path INPUT1[, INPUT2...] =&gt; [PROCESSOR1 [=&gt; PROCESSOR2...] =&gt;]
OUTPUT1[, OUTPUT2...]</code></p>
</div>
<div id="config_example_routes" class="exampleblock">
<div class="title">Example 10. Specifying Routes</div>
<div class="content">
<div class="paragraph">
<p>The following configuration shows modules being used in three
different routes.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Input</span> <span class="attribute-name">in1</span><span class="tag">&gt;</span>
    Module  im_null
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">in2</span><span class="tag">&gt;</span>
    Module  im_null
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Processor</span> <span class="attribute-name">p1</span><span class="tag">&gt;</span>
    Module  pm_null
<span class="tag">&lt;/Processor&gt;</span>

<span class="tag">&lt;Processor</span> <span class="attribute-name">p2</span><span class="tag">&gt;</span>
    Module  pm_null
<span class="tag">&lt;/Processor&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">out1</span><span class="tag">&gt;</span>
    Module  om_null
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">out2</span><span class="tag">&gt;</span>
    Module  om_null
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">1</span><span class="tag">&gt;</span>
    # Basic route
    Path    in1 =<span class="error">&gt;</span> out1
<span class="tag">&lt;/Route&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">2</span><span class="tag">&gt;</span>
    # Basic route with one processor module
    Path    in1 =<span class="error">&gt;</span> p1 =<span class="error">&gt;</span> out1
<span class="tag">&lt;/Route&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">3</span><span class="tag">&gt;</span>
    # Complex route with multiple input/output/processor modules
    Path    in1, in2 =<span class="error">&gt;</span> p1 =<span class="error">&gt;</span> p2 =<span class="error">&gt;</span> out1, out2
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
</dd>
</dl>
</div>
<hr>
<div id="config_route_priority" class="dlist">
<dl>
<dt class="hdlist1">Priority</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>This directive takes an integer value in the range of 1-100 as a parameter,
and the default is <code>10</code>. Log messages in routes with a lower <strong>Priority</strong> value
will be processed before others. Internally, this value is assigned to each
module part of the route. The events of the modules are processed in priority
order by the NXLog engine. Modules of a route with a lower <strong>Priority</strong>
value (higher priority) will process log messages first.</p>
</div>
<div class="exampleblock">
<div class="title">Example 11. Prioritized Processing</div>
<div class="content">
<div class="paragraph">
<p>This configuration prioritizes the UDP route over the TCP route in order to
minimize loss of UDP Syslog messages when the system is busy.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Input</span> <span class="attribute-name">tcpin</span><span class="tag">&gt;</span>
    Module      im_tcp
    Host        localhost
    Port        514
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">udpin</span><span class="tag">&gt;</span>
    Module      im_udp
    Host        localhost
    Port        514
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">tcpfile</span><span class="tag">&gt;</span>
    Module      om_file
    File        &quot;/var/log/tcp.log&quot;
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">udpfile</span><span class="tag">&gt;</span>
    Module      om_file
    File        &quot;/var/log/udp.log&quot;
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">udp</span><span class="tag">&gt;</span>
    Priority    1
    Path        udpin =<span class="error">&gt;</span> udpfile
<span class="tag">&lt;/Route&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">tcp</span><span class="tag">&gt;</span>
    Priority    2
    Path        tcpin =<span class="error">&gt;</span> tcpfile
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="ref-lang"><a class="anchor" href="#ref-lang"></a>3. Language</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="lang_types"><a class="anchor" href="#lang_types"></a>3.1. Types</h3>
<div class="paragraph">
<p>The following types are provided by the NXLog language.</p>
</div>
<div id="lang_type_unknown" class="dlist">
<dl>
<dt class="hdlist1">Unknown</dt>
<dd>
<p>This is a special type for values where the type cannot be
determined at compile time and for uninitialized values. The
<a href="#lang_literal_undef">undef literal</a> and <a href="#lang_fields">fields</a>
without a value also have an unknown type. The unknown type can also
be thought of as "any" in case of function and procedure API
declarations.</p>
</dd>
</dl>
</div>
<div id="lang_type_boolean" class="dlist">
<dl>
<dt class="hdlist1">Boolean</dt>
<dd>
<p>A boolean value is TRUE, FALSE or undefined. Note that an
undefined value is not the same as a FALSE value.</p>
</dd>
</dl>
</div>
<div id="lang_type_integer" class="dlist">
<dl>
<dt class="hdlist1">Integer</dt>
<dd>
<p>An integer can hold a signed 64 bit value in addition to
the undefined value. Floating point values are not supported.</p>
</dd>
</dl>
</div>
<div id="lang_type_string" class="dlist">
<dl>
<dt class="hdlist1">String</dt>
<dd>
<p>A string is an array of characters in any character set. The
<a href="#lang_type_binary">binary</a> type should be used for values where the
NUL byte can also occur. An undefined string is not the same as an
empty string. Strings have a limited length to prevent resource
exhaustion problems, this is a compile-time value currently set to
1M.</p>
</dd>
</dl>
</div>
<div id="lang_type_datetime" class="dlist">
<dl>
<dt class="hdlist1">Datetime</dt>
<dd>
<p>A datetime holds a microsecond value of time elapsed since
the Epoch. It is always stored in UTC/GMT.</p>
</dd>
</dl>
</div>
<div id="lang_type_ip4addr" class="dlist">
<dl>
<dt class="hdlist1">IPv4 Address</dt>
<dd>
<p>An ip4addr type stores a dotted-quad IPv4 address in an
internal format (integer).</p>
</dd>
</dl>
</div>
<div id="lang_type_ip6addr" class="dlist">
<dl>
<dt class="hdlist1">IPv6 Address</dt>
<dd>
<p>An ip6addr type stores an IPv6 address in an internal
format.</p>
</dd>
</dl>
</div>
<div id="lang_type_regexp" class="dlist">
<dl>
<dt class="hdlist1">Regular expression</dt>
<dd>
<p>A regular expression type can only be used with
the <a href="#lang_binop_regmatch">=~</a> or <a href="#lang_binop_notregmatch">!~</a>
operators.</p>
</dd>
</dl>
</div>
<div id="lang_type_binary" class="dlist">
<dl>
<dt class="hdlist1">Binary</dt>
<dd>
<p>This type can hold an array of bytes.</p>
</dd>
</dl>
</div>
<div id="lang_type_varargs" class="dlist">
<dl>
<dt class="hdlist1">Variadic arguments</dt>
<dd>
<p>This is a special type only used in function and
procedure API declarations to indicate variadic arguments.</p>
</dd>
</dl>
</div>
</div>
<div class="sect2">
<h3 id="lang_expressions"><a class="anchor" href="#lang_expressions"></a>3.2. Expressions</h3>
<div class="sect3">
<h4 id="lang_literals"><a class="anchor" href="#lang_literals"></a>3.2.1. Literals</h4>
<div id="lang_literal_undef" class="dlist">
<dl>
<dt class="hdlist1">Undef</dt>
<dd>
<p>The undef literal has an <a href="#lang_type_unknown">unknown</a>
type. It can be also used in an
<a href="#lang_statement_assignment">assignment</a> to unset the value of a
<a href="#lang_fields">field</a>.</p>
<div class="exampleblock">
<div class="title">Example 12. Un-Setting the Value of a Field</div>
<div class="content">
<div class="paragraph">
<p>This statement unsets the <code>$ProcessID</code> field.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="statement"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
</pre></td>
  <td class="code"><pre>$ProcessID = undef;</pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="lang_literal_boolean" class="dlist">
<dl>
<dt class="hdlist1">Boolean</dt>
<dd>
<p>A boolean literal is either TRUE or FALSE. It is
case-insensitive, so <code>True</code>, <code>False</code>, <code>true</code>, and <code>false</code> are also
valid.</p>
</dd>
</dl>
</div>
<div id="lang_literal_integer" class="dlist">
<dl>
<dt class="hdlist1">Integer</dt>
<dd>
<p>An integer starts with a minus (<code>-</code>) sign if it is
negative. A "0X" or "0x" prepended modifier indicates a hexadecimal
notation. The "K", "M" and "G" modifiers are also supported; these
mean Kilo (1024), Mega (1024^2), or Giga (1024^3) respectively when
appended.</p>
<div class="exampleblock">
<div class="title">Example 13. Setting an Integer Value</div>
<div class="content">
<div class="paragraph">
<p>This statement uses a modifier to set the <code>$Limit</code> field to 44040192
(42×1024^2).</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="statement"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
</pre></td>
  <td class="code"><pre>$Limit = 42M;</pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="lang_literal_string" class="dlist">
<dl>
<dt class="hdlist1">String</dt>
<dd>
<p>String literals are quoted characters using either single or
double quotes. String literals specified with double quotes can
contain the following escape sequences.</p>
<div class="openblock">
<div class="content">
<div class="dlist">
<dl>
<dt class="hdlist1">\\</dt>
<dd>
<p>The backslash (<code>\</code>) character.</p>
</dd>
<dt class="hdlist1">\"</dt>
<dd>
<p>The double quote (<code>"</code>) character.</p>
</dd>
<dt class="hdlist1">\n</dt>
<dd>
<p>Line feed (LF).</p>
</dd>
<dt class="hdlist1">\r</dt>
<dd>
<p>Carriage return (CR).</p>
</dd>
<dt class="hdlist1">\t</dt>
<dd>
<p>Horizontal tab.</p>
</dd>
<dt class="hdlist1">\b</dt>
<dd>
<p>Audible bell.</p>
</dd>
<dt class="hdlist1">\xXX</dt>
<dd>
<p>A single byte in the form of a two digit hexadecimal
number. For example the line-feed character can also be expressed
as <code>\x0A</code>.</p>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
String literals in single quotes do not process the escape
      sequences: <code>"\n"</code> is a single character (LF) while <code>'\n'</code> is two
      characters. The following comparison is FALSE for this reason:
      <code>"\n" == '\n'</code>.
</td>
</tr>
</table>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
Extra care should be taken with the backslash when using double
      quoted string literals to specify file paths on Windows.
      For more information about the possible complications, see
      <a href="#im_file_config_file_note">this note</a> for the <em>im_file</em> <strong>File</strong>
      directive.
</td>
</tr>
</table>
</div>
</dd>
</dl>
</div>
<div class="exampleblock">
<div class="title">Example 14. Setting a String Value</div>
<div class="content">
<div class="paragraph">
<p>This statement sets the <code>$Message</code> field to the specified string.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="statement"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
</pre></td>
  <td class="code"><pre>$Message = &quot;Test message&quot;;</pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="lang_regexp" class="dlist">
<dl>
<dt class="hdlist1">Regular expression</dt>
<dd>
<p>Regular expressions must be quoted with slashes
as in Perl. Captured substrings are accessible through a numeric
reference such as $1. The full subject string is placed into $0.</p>
<div class="exampleblock">
<div class="title">Example 15. A regular expression match operation</div>
<div class="content">
<div class="listingblock">
<div class="content">
<pre>if $Message =~ /^Test (\S+)/ log_info("captured: " + $1);</pre>
</div>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="lang_literal_datetime" class="dlist">
<dl>
<dt class="hdlist1">Datetime</dt>
<dd>
<p>A datetime literal is an unquoted representation of a time
value expressing local time in the format of <code>YYYY-MM-DD hh:mm:ss</code>.</p>
<div class="exampleblock">
<div class="title">Example 16. Setting a Datetime Value</div>
<div class="content">
<div class="paragraph">
<p>This statement sets the <code>$EventTime</code> field to the specified datetime
value.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="statement"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
</pre></td>
  <td class="code"><pre>$EventTime = 2000-01-02 03:04:05;</pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="lang_literal_ip4addr" class="dlist">
<dl>
<dt class="hdlist1">IPv4 Address</dt>
<dd>
<p>An IPv4 literal value is expressed in dotted quad notation
such as <code>192.168.1.1</code>.</p>
</dd>
</dl>
</div>
<div id="lang_literal_ip6addr" class="dlist">
<dl>
<dt class="hdlist1">IPv6 Address</dt>
<dd>
<p>An IPv6 literal value is expressed by 8 groups of
16-bit hexadecimal values separated by colons (<code>:</code>) such as
<code>2001:0db8:85a3:0000:0000:8a2e:0370:7334</code>.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="lang_fields"><a class="anchor" href="#lang_fields"></a>3.2.2. Fields</h4>
<div class="paragraph">
<p>Fields are referenced in the NXLog language by prepending a
dollar sign (<code>$</code>) to the field name.</p>
</div>
<div class="paragraph">
<p>Normally, a field name may contain letters, digits, the period (<code>.</code>), and the
underscore (<code>_</code>). Additionally, field names must begin with a letter or
an underscore. The corresponding regular expression is:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>[a-zA-Z_][a-zA-Z0-9._]*</pre>
</div>
</div>
<div class="paragraph">
<p>However, those restrictions are relaxed if the field name is specified with
curly braces (<code>{}</code>). In this case, the field name may also contain hyphens
(<code>-</code>), parentheses (<code>()</code>), and spaces. The field name may also begin with any
one of the allowed characters. The regular expression in this case is:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>[a-zA-Z0-9._() -]+</pre>
</div>
</div>
<div class="exampleblock">
<div class="title">Example 17. Referencing a Field</div>
<div class="content">
<div class="paragraph">
<p>This statement generates an internal log message indicating the time when the
message was received by NXLog.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="statement"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
</pre></td>
  <td class="code"><pre>log_debug('Message received at ' + $EventReceivedTime);</pre></td>
</tr></table></code></pre>
</div>
</div>
<div class="paragraph">
<p>This statement uses curly braces (<code>{}</code>) to refer to a field with a hyphenated
name.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="statement"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
</pre></td>
  <td class="code"><pre>log_info('The file size is ' + ${file-size});</pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>A field which does not exist has an <a href="#lang_type_unknown">unknown</a>
type.</p>
</div>
</div>
<div class="sect3">
<h4 id="lang_operations"><a class="anchor" href="#lang_operations"></a>3.2.3. Operations</h4>
<div class="sect4">
<h5 id="lang_unary_operations"><a class="anchor" href="#lang_unary_operations"></a>3.2.3.1. Unary Operations</h5>
<div class="paragraph">
<p>The following unary operations are available. It is possible to use
brackets around the operand to make it look like a function call as in
the <a href="#lang_defined_example">"defined" example</a> below.</p>
</div>
<div id="lang_unop_not" class="dlist">
<dl>
<dt class="hdlist1">not</dt>
<dd>
<p>The <strong>not</strong> operator expects a boolean value. It will evaluate to
undef if the value is undefined. If it receives an unknown value
which evaluates to a non-boolean, it will result in a run-time
execution error.</p>
<div class="exampleblock">
<div class="title">Example 18. Using the "not" Operand</div>
<div class="content">
<div class="paragraph">
<p>If the <code>$Success</code> field has a value of false, an error is logged.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="statement"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
</pre></td>
  <td class="code"><pre>if not $Success log_error(&quot;Job failed&quot;);</pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="lang_unop_defined" class="dlist">
<dl>
<dt class="hdlist1">defined</dt>
<dd>
<p>The defined operator will evaluate to TRUE if the operand
is defined, otherwise FALSE.</p>
<div id="lang_defined_example" class="exampleblock">
<div class="title">Example 19. Using the Unary "defined" Operation</div>
<div class="content">
<div class="paragraph">
<p>This statement is a no-op, it does nothing.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="statement"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
</pre></td>
  <td class="code"><pre>if defined undef log_info(&quot;never printed&quot;);</pre></td>
</tr></table></code></pre>
</div>
</div>
<div class="paragraph">
<p>If the <code>$EventTime</code> field has not been set (due perhaps to failed
parsing), it will be set to the current time.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="statement"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
</pre></td>
  <td class="code"><pre>if not defined($EventTime) $EventTime = now();</pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect4">
<h5 id="lang_binary_operations"><a class="anchor" href="#lang_binary_operations"></a>3.2.3.2. Binary Operations</h5>
<div class="paragraph">
<p>The following binary operations are available.</p>
</div>
<div class="paragraph">
<p>The operations are described with the following syntax:</p>
</div>
<div class="paragraph">
<p><code>LEFT_OPERAND_TYPE OPERATION RIGHT_OPERAND_TYPE = EVALUATED_VALUE_TYPE</code></p>
</div>
<div id="lang_binop_regmatch" class="dlist">
<dl>
<dt class="hdlist1">=~</dt>
<dd>
<p>This is the regular expression match operation as in Perl. The
PCRE engine is used to to execute the regular expressions. This
operation takes a string and a regexp operand and evaluates to a
boolean value which will be TRUE if the regular expression matches
the subject string. Captured sub-strings are accessible through
numeric reference, such as <code>$1</code>, and the full subject string is
placed into <code>$0</code>.</p>
<div class="openblock">
<div class="content">
<div class="ulist">
<ul>
<li>
<p><code><a href="#lang_type_string">string</a> =~ <a href="#lang_type_regexp">regexp</a> =
<a href="#lang_type_boolean">boolean</a></code></p>
</li>
<li>
<p><code><a href="#lang_type_regexp">regexp</a> =~ <a href="#lang_type_string">string</a> =
<a href="#lang_type_boolean">boolean</a></code></p>
</li>
</ul>
</div>
</div>
</div>
<div class="exampleblock">
<div class="title">Example 20. Regular Expression Based String Matching</div>
<div class="content">
<div class="paragraph">
<p>A log message will be generated if the <code>$Message</code> field matches the
regular expression.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="statement"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
</pre></td>
  <td class="code"><pre>if $Message =~ /^Test message/ log_info(&quot;matched&quot;);</pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Regular expression based string substitution is also supported with
the <code>s///</code> operator.</p>
</div>
<div class="paragraph">
<p><a id="lang_binop_regmatch_modifiers"></a>The following regular expression
modifiers are supported:</p>
</div>
<div class="openblock">
<div class="content">
<div class="dlist">
<dl>
<dt class="hdlist1">g</dt>
<dd>
<p>The <code>/g</code> modifier can be used for global replacement.</p>
<div class="exampleblock">
<div class="title">Example 21. Replace Whitespace Occurrences</div>
<div class="content">
<div class="listingblock">
<div class="content">
<pre>if $SourceName =~ s/\s/_/g log_info("removed all whitespace in SourceName");</pre>
</div>
</div>
</div>
</div>
</dd>
<dt class="hdlist1">s</dt>
<dd>
<p>The dot (<code>.</code>) normally matches any character except
newline. The <code>/s</code> modifier causes the dot to match all characters
including line terminator characters (LF and CRLF).</p>
<div class="exampleblock">
<div class="title">Example 22. Dot Matches All Characters</div>
<div class="content">
<div class="listingblock">
<div class="content">
<pre>if $Message =~ /^Backtrace.*END$/s drop();</pre>
</div>
</div>
</div>
</div>
</dd>
<dt class="hdlist1">m</dt>
<dd>
<p>The <code>/m</code> modifier can be used to treat the string as multiple
lines (<code>^</code> and <code>$</code> match newlines within data).</p>
</dd>
<dt class="hdlist1">i</dt>
<dd>
<p>The <code>/i</code> modifier does case insensitive matching.</p>
</dd>
</dl>
</div>
</div>
</div>
<div class="paragraph">
<p>Variables and captured sub-string references cannot be used inside the
regular expression or the regexp substitution operator (they will be
treated literally).</p>
</div>
</dd>
</dl>
</div>
<div id="lang_binop_notregmatch" class="dlist">
<dl>
<dt class="hdlist1">!~</dt>
<dd>
<p>This is the opposite of <a href="#lang_binop_regmatch">=~</a>: the
expression will evaluate to TRUE if the regular expression does not
match on the subject string. It can be also written as
<code><a href="#lang_unop_not">not</a> LEFT_OPERAND <a href="#lang_binop_regmatch">=~</a>
RIGHT_OPERAND</code>.</p>
<div class="openblock">
<div class="content">
<div class="ulist">
<ul>
<li>
<p><code><a href="#lang_type_string">string</a> !~ <a href="#lang_type_regexp">regexp</a> =
<a href="#lang_type_boolean">boolean</a></code></p>
</li>
<li>
<p><code><a href="#lang_type_regexp">regexp</a> !~ <a href="#lang_type_string">string</a> =
<a href="#lang_type_boolean">boolean</a></code></p>
</li>
</ul>
</div>
</div>
</div>
<div class="paragraph">
<p>The <code>s///</code> substitution operator is also supported.</p>
</div>
<div class="exampleblock">
<div class="title">Example 23. Regular Expression Based Negative String Matching</div>
<div class="content">
<div class="paragraph">
<p>A log message will be generated if the <code>$Message</code> field does not match
the regular expression.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="statement"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
</pre></td>
  <td class="code"><pre>if $Message !~ /^Test message/ log_info(&quot;didn't match&quot;);</pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="lang_binop_equal" class="dlist">
<dl>
<dt class="hdlist1">==</dt>
<dd>
<p>This operator compares two values for equality. Comparing a
defined value with an undefined results in
<a href="#lang_literal_undef">undef</a>.</p>
<div class="openblock">
<div class="content">
<div class="ulist">
<ul>
<li>
<p><code><a href="#lang_literal_undef">undef</a> == <a href="#lang_literal_undef">undef</a> =
<a href="#lang_literal_boolean">TRUE</a></code></p>
</li>
<li>
<p><code><a href="#lang_type_string">string</a> == <a href="#lang_type_string">string</a> =
<a href="#lang_type_boolean">boolean</a></code></p>
</li>
<li>
<p><code><a href="#lang_type_integer">integer</a> == <a href="#lang_type_integer">integer</a> =
<a href="#lang_type_boolean">boolean</a></code></p>
</li>
<li>
<p><code><a href="#lang_type_boolean">boolean</a> == <a href="#lang_type_boolean">boolean</a> =
<a href="#lang_type_boolean">boolean</a></code></p>
</li>
<li>
<p><code><a href="#lang_type_datetime">datetime</a> == <a href="#lang_type_datetime">datetime</a> =
<a href="#lang_type_boolean">boolean</a></code></p>
</li>
<li>
<p><code><a href="#lang_type_ip4addr">ip4addr</a> == <a href="#lang_type_ip4addr">ip4addr</a> =
<a href="#lang_type_boolean">boolean</a></code></p>
</li>
<li>
<p><code><a href="#lang_type_ip4addr">ip4addr</a> == <a href="#lang_type_string">string</a> =
<a href="#lang_type_boolean">boolean</a></code></p>
</li>
<li>
<p><code><a href="#lang_type_string">string</a> == <a href="#lang_type_ip4addr">ip4addr</a> =
<a href="#lang_type_boolean">boolean</a></code></p>
</li>
</ul>
</div>
</div>
</div>
<div class="exampleblock">
<div class="title">Example 24. Equality</div>
<div class="content">
<div class="paragraph">
<p>A log message will be generated if <code>$SeverityValue</code> is 1.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="statement"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
</pre></td>
  <td class="code"><pre>if $SeverityValue == 1 log_info(&quot;severity is one&quot;);</pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="lang_binop_notequal" class="dlist">
<dl>
<dt class="hdlist1">!=</dt>
<dd>
<p>This operator compares two values for inequality. Comparing a
defined value with an undefined results in
<a href="#lang_literal_undef">undef</a>.</p>
<div class="openblock">
<div class="content">
<div class="ulist">
<ul>
<li>
<p><code><a href="#lang_literal_undef">undef</a> != <a href="#lang_literal_undef">undef</a> =
<a href="#lang_literal_boolean">FALSE</a></code></p>
</li>
<li>
<p><code><a href="#lang_type_string">string</a> != <a href="#lang_type_string">string</a> =
<a href="#lang_type_boolean">boolean</a></code></p>
</li>
<li>
<p><code><a href="#lang_type_integer">integer</a> != <a href="#lang_type_integer">integer</a> =
<a href="#lang_type_boolean">boolean</a></code></p>
</li>
<li>
<p><code><a href="#lang_type_boolean">boolean</a> != <a href="#lang_type_boolean">boolean</a> =
<a href="#lang_type_boolean">boolean</a></code></p>
</li>
<li>
<p><code><a href="#lang_type_datetime">datetime</a> != <a href="#lang_type_datetime">datetime</a> =
<a href="#lang_type_boolean">boolean</a></code></p>
</li>
<li>
<p><code><a href="#lang_type_ip4addr">ip4addr</a> != <a href="#lang_type_ip4addr">ip4addr</a> =
<a href="#lang_type_boolean">boolean</a></code></p>
</li>
<li>
<p><code><a href="#lang_type_ip4addr">ip4addr</a> != <a href="#lang_type_string">string</a> =
<a href="#lang_type_boolean">boolean</a></code></p>
</li>
<li>
<p><code><a href="#lang_type_string">string</a> != <a href="#lang_type_ip4addr">ip4addr</a> =
<a href="#lang_type_boolean">boolean</a></code></p>
</li>
</ul>
</div>
</div>
</div>
<div class="exampleblock">
<div class="title">Example 25. Inequality</div>
<div class="content">
<div class="paragraph">
<p>A log message will be generated if <code>$SeverityValue</code> is not 1.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="statement"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
</pre></td>
  <td class="code"><pre>if $SeverityValue != 1 log_info(&quot;severity is not one&quot;);</pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="lang_binop_less" class="dlist">
<dl>
<dt class="hdlist1">&lt;</dt>
<dd>
<p>This operation will evaluate to TRUE if the left operand is less
than the right operand, and FALSE otherwise. Comparing a defined
value with an undefined results in <a href="#lang_literal_undef">undef</a>.</p>
<div class="openblock">
<div class="content">
<div class="ulist">
<ul>
<li>
<p><code><a href="#lang_type_integer">integer</a> &lt; <a href="#lang_type_integer">integer</a> =
<a href="#lang_type_boolean">boolean</a></code></p>
</li>
<li>
<p><code><a href="#lang_type_datetime">datetime</a> &lt; <a href="#lang_type_datetime">datetime</a> =
<a href="#lang_type_boolean">boolean</a></code></p>
</li>
</ul>
</div>
</div>
</div>
<div class="exampleblock">
<div class="title">Example 26. Less</div>
<div class="content">
<div class="paragraph">
<p>A log message will be generated if <code>$SeverityValue</code> is less than 1.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="statement"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
</pre></td>
  <td class="code"><pre>if $SeverityValue &lt; 1 log_info(&quot;severity is less than one&quot;);</pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="lang_binop_le" class="dlist">
<dl>
<dt class="hdlist1">&lt;=</dt>
<dd>
<p>This operation will evaluate to TRUE if the left operand is less
than or equal to the right operand, and FALSE otherwise. Comparing a
defined value with an undefined results in
<a href="#lang_literal_undef">undef</a>.</p>
<div class="openblock">
<div class="content">
<div class="ulist">
<ul>
<li>
<p><code><a href="#lang_type_integer">integer</a> &lt;= <a href="#lang_type_integer">integer</a> =
<a href="#lang_type_boolean">boolean</a></code></p>
</li>
<li>
<p><code><a href="#lang_type_datetime">datetime</a> &lt;= <a href="#lang_type_datetime">datetime</a> =
<a href="#lang_type_boolean">boolean</a></code></p>
</li>
</ul>
</div>
</div>
</div>
<div class="exampleblock">
<div class="title">Example 27. Less or Equal</div>
<div class="content">
<div class="paragraph">
<p>A log message will be generated if <code>$SeverityValue</code> is less than or
equal to 1.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="statement"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
</pre></td>
  <td class="code"><pre>if $SeverityValue &lt; 1 log_info(&quot;severity is less than or equal to one&quot;);</pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="lang_binop_greater" class="dlist">
<dl>
<dt class="hdlist1">&gt;</dt>
<dd>
<p>This operation will evaluate to TRUE if the left operand is
greater than the right operand, and FALSE otherwise. Comparing a
defined value with an undefined results in
<a href="#lang_literal_undef">undef</a>.</p>
<div class="openblock">
<div class="content">
<div class="ulist">
<ul>
<li>
<p><code><a href="#lang_type_integer">integer</a> &gt; <a href="#lang_type_integer">integer</a> =
<a href="#lang_type_boolean">boolean</a></code></p>
</li>
<li>
<p><code><a href="#lang_type_datetime">datetime</a> &gt; <a href="#lang_type_datetime">datetime</a> =
<a href="#lang_type_boolean">boolean</a></code></p>
</li>
</ul>
</div>
</div>
</div>
<div class="exampleblock">
<div class="title">Example 28. Greater</div>
<div class="content">
<div class="paragraph">
<p>A log message will be generated if <code>$SeverityValue</code> is greater than 1.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="statement"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
</pre></td>
  <td class="code"><pre>if $SeverityValue &gt; 1 log_info(&quot;severity is greater than one&quot;);</pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="lang_binop_ge" class="dlist">
<dl>
<dt class="hdlist1">&gt;=</dt>
<dd>
<p>This operation will evaluate to TRUE if the left operand is
greater than or equal to the right operand, and FALSE
otherwise. Comparing a defined value with an undefined results in
<a href="#lang_literal_undef">undef</a>.</p>
<div class="openblock">
<div class="content">
<div class="ulist">
<ul>
<li>
<p><code><a href="#lang_type_integer">integer</a> &gt;= <a href="#lang_type_integer">integer</a> =
<a href="#lang_type_boolean">boolean</a></code></p>
</li>
<li>
<p><code><a href="#lang_type_datetime">datetime</a> &gt;= <a href="#lang_type_datetime">datetime</a> =
<a href="#lang_type_boolean">boolean</a></code></p>
</li>
</ul>
</div>
</div>
</div>
<div class="exampleblock">
<div class="title">Example 29. Greater or Equal</div>
<div class="content">
<div class="paragraph">
<p>A log message will be generated if <code>$SeverityValue</code> is greater than or
equal to 1.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="statement"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
</pre></td>
  <td class="code"><pre>if $SeverityValue &gt;= 1 log_info(&quot;severity is greater than or equal to one&quot;);</pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="lang_binop_and" class="dlist">
<dl>
<dt class="hdlist1">and</dt>
<dd>
<p>This operation evaluates to TRUE if and only if both operands
are TRUE. The operation will evaluate to
<a href="#lang_literal_undef">undef</a> if either operand is undefined.</p>
<div class="paragraph">
<p><code><a href="#lang_type_boolean">boolean</a> and <a href="#lang_type_boolean">boolean</a> =
 <a href="#lang_type_boolean">boolean</a></code></p>
</div>
<div class="exampleblock">
<div class="title">Example 30. And Operation</div>
<div class="content">
<div class="paragraph">
<p>A log message will be generated only if both <code>$SeverityValue</code> equals 1
<em>and</em> <code>$FacilityValue</code> equals 2.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="statement"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
</pre></td>
  <td class="code"><pre>if $SeverityValue == 1 and $FacilityValue == 2 log_info(&quot;1 and 2&quot;);</pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="lang_binop_or" class="dlist">
<dl>
<dt class="hdlist1">or</dt>
<dd>
<p>This operation evaluates to TRUE if either operand is TRUE. The
operation will evaluate to <a href="#lang_literal_undef">undef</a> if both
operands are undefined.</p>
<div class="paragraph">
<p><code><a href="#lang_type_boolean">boolean</a> or <a href="#lang_type_boolean">boolean</a> =
 <a href="#lang_type_boolean">boolean</a></code></p>
</div>
<div class="exampleblock">
<div class="title">Example 31. Or Operation</div>
<div class="content">
<div class="paragraph">
<p>A log message will be generated if <code>$SeverityValue</code> is equal to either
1 or 2.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="statement"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
</pre></td>
  <td class="code"><pre>if $SeverityValue == 1 or $SeverityValue == 2 log_info(&quot;1 or 2&quot;);</pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="lang_binop_plus" class="dlist">
<dl>
<dt class="hdlist1">+</dt>
<dd>
<p>This operation will result in an integer if both operands are
integers. If either operand is a string, the result will be a string
where non-string typed values are converted to strings. In this case
it acts as a concatenation operator, like the dot (<code>.</code>) operator in
Perl. Adding an undefined value to a non-string will result in
undef.</p>
<div class="openblock">
<div class="content">
<div class="ulist">
<ul>
<li>
<p><code><a href="#lang_type_integer">integer</a> + <a href="#lang_type_integer">integer</a> =
<a href="#lang_type_integer">integer</a></code></p>
</li>
<li>
<p><code><a href="#lang_type_string">string</a> + <a href="#lang_literal_undef">undef</a> =
<a href="#lang_type_string">string</a></code></p>
</li>
<li>
<p><code><a href="#lang_literal_undef">undef</a> + <a href="#lang_type_string">string</a> =
<a href="#lang_type_string">string</a></code></p>
</li>
<li>
<p><code><a href="#lang_literal_undef">undef</a> + <a href="#lang_literal_undef">undef</a> =
<a href="#lang_literal_undef">undef</a></code></p>
</li>
<li>
<p><code><a href="#lang_type_string">string</a> + <a href="#lang_type_string">string</a> =
<a href="#lang_type_string">string</a></code> (Concatenate two strings.)</p>
</li>
<li>
<p><code><a href="#lang_type_datetime">datetime</a> + <a href="#lang_type_integer">integer</a> =
 <a href="#lang_type_datetime">datetime</a></code> (Add the number of seconds in the
right value to the datetime stored in the left value.)</p>
</li>
<li>
<p><code><a href="#lang_type_integer">integer</a> + <a href="#lang_type_datetime">datetime</a> =
 <a href="#lang_type_datetime">datetime</a></code> (Add the number of seconds in the
left value to the datetime stored in the right value.)</p>
</li>
</ul>
</div>
</div>
</div>
<div class="exampleblock">
<div class="title">Example 32. Concatenation</div>
<div class="content">
<div class="paragraph">
<p>This statement will always cause a log message to be generated.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="statement"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
</pre></td>
  <td class="code"><pre>if 1 + &quot;a&quot; == &quot;1a&quot; log_info(&quot;this will be printed&quot;);</pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="lang_binop_minus" class="dlist">
<dl>
<dt class="hdlist1">-</dt>
<dd>
<p>Subtraction. The result will be undef if either operand is
undefined.</p>
<div class="openblock">
<div class="content">
<div class="ulist">
<ul>
<li>
<p><code><a href="#lang_type_integer">integer</a> - <a href="#lang_type_integer">integer</a> =
<a href="#lang_type_integer">integer</a></code> (Subtract two integers.)</p>
</li>
<li>
<p><code><a href="#lang_type_datetime">datetime</a> - <a href="#lang_type_datetime">datetime</a> =
 <a href="#lang_type_integer">integer</a></code> (Subtract two datetime types. The
result is the difference between to two expressed in microseconds.)</p>
</li>
<li>
<p><code><a href="#lang_type_datetime">datetime</a> - <a href="#lang_type_integer">integer</a> =
 <a href="#lang_type_datetime">datetime</a></code> (Subtract the number of seconds from
the datetime stored in the left value.)</p>
</li>
</ul>
</div>
</div>
</div>
<div class="exampleblock">
<div class="title">Example 33. Subtraction</div>
<div class="content">
<div class="paragraph">
<p>This statement will always cause a log message to be generated.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="statement"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
</pre></td>
  <td class="code"><pre>if 4 - 1 == 3 log_info(&quot;four minus one is three&quot;);</pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="lang_binop_mul" class="dlist">
<dl>
<dt class="hdlist1">*</dt>
<dd>
<p>Multiply an integer with another. The result will be undef if
either operand is undefined.</p>
<div class="paragraph">
<p><code><a href="#lang_type_integer">integer</a> * <a href="#lang_type_integer">integer</a> =
 <a href="#lang_type_integer">integer</a></code></p>
</div>
<div class="exampleblock">
<div class="title">Example 34. Multiplication</div>
<div class="content">
<div class="paragraph">
<p>This statement will always cause a log message to be generated.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="statement"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
</pre></td>
  <td class="code"><pre>if 4 * 2 == 8 log_info(&quot;four times two is eight&quot;);</pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="lang_binop_div" class="dlist">
<dl>
<dt class="hdlist1">/</dt>
<dd>
<p>Divide an integer with another. The result will be undef if either
operand is undefined. Since the result is an integer, a fractional
part is lost.</p>
<div class="paragraph">
<p><code><a href="#lang_type_integer">integer</a> / <a href="#lang_type_integer">integer</a> =
 <a href="#lang_type_integer">integer</a></code></p>
</div>
<div class="exampleblock">
<div class="title">Example 35. Division</div>
<div class="content">
<div class="paragraph">
<p>This statement will always cause a log message to be generated.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="statement"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
</pre></td>
  <td class="code"><pre>if 9 / 4 == 2 log_info(&quot;9 divided by 4 is 2&quot;);</pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="lang_binop_mod" class="dlist">
<dl>
<dt class="hdlist1">%</dt>
<dd>
<p>The modulo operation divides an integer with another and returns
the remainder. The result will be undef if either operand is
undefined.</p>
<div class="paragraph">
<p><code><a href="#lang_type_integer">integer</a> % <a href="#lang_type_integer">integer</a> =
 <a href="#lang_type_integer">integer</a></code></p>
</div>
<div class="exampleblock">
<div class="title">Example 36. Modulo</div>
<div class="content">
<div class="paragraph">
<p>This statement will always cause a log message to be generated.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="statement"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
</pre></td>
  <td class="code"><pre>if 3 % 2 == 1 log_info(&quot;three mod two is one&quot;);</pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="lang_binop_in" class="dlist">
<dl>
<dt class="hdlist1">IN</dt>
<dd>
<p>This operation will evaluate to TRUE if the left operand is equal
to any of the expressions in the list on the right, and FALSE
otherwise.  Comparing a undefined value results in
<a href="#lang_literal_undef">undef</a>.</p>
<div class="paragraph">
<p><code><a href="#lang_type_unknown">unknown</a> IN <a href="#lang_type_unknown">unknown</a>,
 <a href="#lang_type_unknown">unknown</a> &#8230;&#8203; = <a href="#lang_type_boolean">boolean</a></code></p>
</div>
<div class="exampleblock">
<div class="title">Example 37. IN</div>
<div class="content">
<div class="paragraph">
<p>A log message will be generated if <code>$EventID</code> is equal to any one of
the values in the list.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="statement"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
</pre></td>
  <td class="code"><pre>if $EventID IN (1000, 1001, 1004, 4001) log_info(&quot;EventID found&quot;);</pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="lang_binop_not_in" class="dlist">
<dl>
<dt class="hdlist1">NOT IN</dt>
<dd>
<p>This operation is equivalent to <code>NOT expr IN expr_list</code>.</p>
<div class="paragraph">
<p><code><a href="#lang_type_unknown">unknown</a> NOT IN <a href="#lang_type_unknown">unknown</a>,
 <a href="#lang_type_unknown">unknown</a> &#8230;&#8203; = <a href="#lang_type_boolean">boolean</a></code></p>
</div>
<div class="exampleblock">
<div class="title">Example 38. NOT IN</div>
<div class="content">
<div class="paragraph">
<p>A log message will be generated if <code>$EventID</code> is not equal to any of
the values in the list.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="statement"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
</pre></td>
  <td class="code"><pre>if $EventID NOT IN (1000, 1001, 1004, 4001) log_info(&quot;EventID not in list&quot;);</pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
</div>
<div class="sect3">
<h4 id="lang_functions"><a class="anchor" href="#lang_functions"></a>3.2.4. Functions</h4>
<div class="paragraph">
<p>See <a href="#core_funcs">Functions</a> for a list of functions provided by the
NXLog core. Additional functions are available through
modules.</p>
</div>
<div class="exampleblock">
<div class="title">Example 39. A Function Call</div>
<div class="content">
<div class="paragraph">
<p>This statement uses the <a href="#core_func_now">now()</a> function to set the
field to the current time.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="statement"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
</pre></td>
  <td class="code"><pre>$EventTime = now();</pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>It is also possible to call a function of a specific module instance.</p>
</div>
<div class="exampleblock">
<div class="title">Example 40. Calling a Function of a Specific Module Instance</div>
<div class="content">
<div class="paragraph">
<p>This statement calls the <a href="#om_file_func_file_name">file_name()</a> and
<a href="#om_file_func_file_size">file_size()</a> functions of a defined <em>om_file</em>
instance named <code>out</code> in order to log the name and size of its currently open
output file.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="statement"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
</pre></td>
  <td class="code"><pre>log_info('Size of output file ' + out-&gt;file_name() + ' is ' + out-&gt;file_size());</pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="lang_statements"><a class="anchor" href="#lang_statements"></a>3.3. Statements</h3>
<div class="paragraph">
<p>The following elements can be used in statements. There is no loop
operation (<em>for</em> or <em>while</em>) in the NXLog language.</p>
</div>
<div class="sect3">
<h4 id="lang_statement_assignment"><a class="anchor" href="#lang_statement_assignment"></a>3.3.1. Assignment</h4>
<div class="paragraph">
<p>The assignment operation is declared with an equal sign (<code>=</code>). It
loads the value from the expression evaluated on the right into a
<a href="#lang_fields">field</a> on the left.</p>
</div>
<div class="exampleblock">
<div class="title">Example 41. Field Assignment</div>
<div class="content">
<div class="paragraph">
<p>This statement sets the <code>$EventReceivedTime</code> field to the value
returned by the <a href="#core_func_now">now()</a> function.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="statement"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
</pre></td>
  <td class="code"><pre>$EventReceivedTime = now();</pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="lang_statement_block"><a class="anchor" href="#lang_statement_block"></a>3.3.2. Block</h4>
<div class="paragraph">
<p>A block consists of one or more statements within curly braces (<code>{}</code>).
This is typically used with <a href="#lang_statement_if">conditional
statements</a> as in the example below.</p>
</div>
<div class="exampleblock">
<div class="title">Example 42. Conditional Statement Block</div>
<div class="content">
<div class="paragraph">
<p>If the expression matches, both log messages will be generated.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="statement"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
</pre></td>
  <td class="code"><pre>if now() &gt; 2000-01-01 00:00:00
{
   log_info(&quot;we are in the&quot;);
   log_info(&quot;21st century&quot;);
}</pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="lang_statement_procedures"><a class="anchor" href="#lang_statement_procedures"></a>3.3.3. Procedures</h4>
<div class="paragraph">
<p>See <a href="#core_procs">Procedures</a> for a list of procedures provided by the
NXLog core. Additional procedures are available through
modules.</p>
</div>
<div class="exampleblock">
<div class="title">Example 43. A Procedure Call</div>
<div class="content">
<div class="paragraph">
<p>The <a href="#core_proc_log_info">log_info()</a> procedure generates an internal
log message.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="statement"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
</pre></td>
  <td class="code"><pre>log_info(&quot;No log source activity detected.&quot;);</pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>It is also possible to call a procedure of a specific module instance.</p>
</div>
<div class="exampleblock">
<div class="title">Example 44. Calling a Procedure of a Specific Module Instance</div>
<div class="content">
<div class="paragraph">
<p>This statement calls the <a href="#xm_csv_proc_parse_csv">parse_csv()</a> procedure of a
defined <em>xm_csv</em> module instance named <code>csv_parser</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="statement"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
</pre></td>
  <td class="code"><pre>csv_parser-&gt;parse_csv();</pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="lang_statement_if"><a class="anchor" href="#lang_statement_if"></a>3.3.4. If-Else</h4>
<div class="paragraph">
<p>A conditional statement starts with the <code>if</code> keyword followed by a
boolean expression and a statement. The <code>else</code> keyword, followed by
another statement, is optional. Brackets around the expression are
also optional.</p>
</div>
<div class="exampleblock">
<div class="title">Example 45. Conditional Statements</div>
<div class="content">
<div class="paragraph">
<p>A log message will be generated if the expression matches.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="statement"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
</pre></td>
  <td class="code"><pre>if now() &gt; 2000-01-01 00:00:00 log_info(&quot;we are in the 21st century&quot;);</pre></td>
</tr></table></code></pre>
</div>
</div>
<div class="paragraph">
<p>This statement is the same as the previous, but uses brackets.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="statement"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
</pre></td>
  <td class="code"><pre>if ( now() &gt; 2000-01-01 00:00:00 ) log_info(&quot;we are in the 21st century&quot;);</pre></td>
</tr></table></code></pre>
</div>
</div>
<div class="paragraph">
<p>This is a conditional statement block.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="statement"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
</pre></td>
  <td class="code"><pre>if now() &gt; 2000-01-01 00:00:00
{
   log_info(&quot;we are in the 21st century&quot;);
}</pre></td>
</tr></table></code></pre>
</div>
</div>
<div class="paragraph">
<p>This conditional statement block includes an else branch.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="statement"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
</pre></td>
  <td class="code"><pre>if now() &gt; 2000-01-01 00:00:00
{
   log_info(&quot;we are in the 21st century&quot;);
}
else log_info(&quot;we are not yet in the 21st century&quot;);</pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Like Perl, the NXLog language does not have a <em>switch</em>
statement. Instead, this can be accomplished by using conditional
<em>if-else</em> statements.</p>
</div>
<div class="exampleblock">
<div class="title">Example 46. Emulating switch with if-else</div>
<div class="content">
<div class="paragraph">
<p>The generated log message various based on the value of the <code>$value</code>
field.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="statement"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
</pre></td>
  <td class="code"><pre>if ( $value == 1 )
   log_info(&quot;1&quot;);
else if ( $value == 2 )
   log_info(&quot;2&quot;);
else if ( $value == 3 )
   log_info(&quot;3&quot;);
else
   log_info(&quot;default&quot;);</pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
The Perl <em>elsif</em> and <em>unless</em> keywords are not supported.
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect2">
<h3 id="lang_variables"><a class="anchor" href="#lang_variables"></a>3.4. Variables</h3>
<div class="paragraph">
<p>A module variable can only be accessed from the same module instance
where it was created. A variable is referenced by a string value and
can store a value of any type.</p>
</div>
<div class="paragraph">
<p>See the <a href="#core_proc_create_var">create_var()</a>,
<a href="#core_proc_delete_var">delete_var()</a>,
<a href="#core_proc_set_var">set_var()</a>, and <a href="#core_func_get_var">get_var()</a>
procedures.</p>
</div>
</div>
<div class="sect2">
<h3 id="lang_stat"><a class="anchor" href="#lang_stat"></a>3.5. Statistical Counters</h3>
<div class="paragraph">
<p>The following types are available for statistical counters:</p>
</div>
<div id="lang_stat_count" class="dlist">
<dl>
<dt class="hdlist1">COUNT</dt>
<dd>
<p>Added values are aggregated, and the value of the counter is
increased if only positive integers are added until the counter is
destroyed or indefinitely if the counter has no expiry.</p>
</dd>
</dl>
</div>
<div id="lang_stat_countmin" class="dlist">
<dl>
<dt class="hdlist1">COUNTMIN</dt>
<dd>
<p>This calculates the minimum value of the counter.</p>
</dd>
</dl>
</div>
<div id="lang_stat_countmax" class="dlist">
<dl>
<dt class="hdlist1">COUNTMAX</dt>
<dd>
<p>This calculates the maximum value of the counter.</p>
</dd>
</dl>
</div>
<div id="lang_stat_avg" class="dlist">
<dl>
<dt class="hdlist1">AVG</dt>
<dd>
<p>This algorithm calculates the average over the specified
interval.</p>
</dd>
</dl>
</div>
<div id="lang_stat_avgmin" class="dlist">
<dl>
<dt class="hdlist1">AVGMIN</dt>
<dd>
<p>This algorithm calculates the average over the specified
interval, and the value of the counter is always the lowest which
was ever calculated during the lifetime of the counter.</p>
</dd>
</dl>
</div>
<div id="lang_stat_avgmax" class="dlist">
<dl>
<dt class="hdlist1">AVGMAX</dt>
<dd>
<p>Like AVGMIN, but this returns the highest value calculated during
the lifetime of the counter.</p>
</dd>
</dl>
</div>
<div id="lang_stat_rate" class="dlist">
<dl>
<dt class="hdlist1">RATE</dt>
<dd>
<p>This calculates the value over the specified interval. It can
be used to calculate events per second (EPS) values.</p>
</dd>
</dl>
</div>
<div id="lang_stat_ratemin" class="dlist">
<dl>
<dt class="hdlist1">RATEMIN</dt>
<dd>
<p>This calculates the value over the specified interval, and
returns the lowest rate calculated during the lifetime of the
counter.</p>
</dd>
</dl>
</div>
<div id="lang_stat_ratemax" class="dlist">
<dl>
<dt class="hdlist1">RATEMAX</dt>
<dd>
<p>Like RATEMIN, but this returns the highest rate calculated
during the lifetime of the counter.</p>
</dd>
</dl>
</div>
<div id="lang_stat_grad" class="dlist">
<dl>
<dt class="hdlist1">GRAD</dt>
<dd>
<p>This calculates the change of the rate of the counter over the
specified interval, which is the gradient.</p>
</dd>
</dl>
</div>
<div id="lang_stat_gradmin" class="dlist">
<dl>
<dt class="hdlist1">GRADMIN</dt>
<dd>
<p>This calculates the gradient and returns the lowest gradient
calculated during the lifetime of the counter.</p>
</dd>
</dl>
</div>
<div id="lang_stat_gradmax" class="dlist">
<dl>
<dt class="hdlist1">GRADMAX</dt>
<dd>
<p>Like GRADMIN, but this returns the highest gradient
calculated during the lifetime of the counter.</p>
</dd>
</dl>
</div>
<div class="exampleblock">
<div class="title">Example 47. Simple Event Correlation Using Statistical Counters</div>
<div class="content">
<div class="paragraph">
<p>If the number of login failures exceeds 3 within 45 seconds, then an
internal log message is generated. This accomplishes the exact same
task as our <a href="#lang_variable_example_corr">previous algorithm</a> did with
module variables, except that it is a lot simpler. In addition, this
method is more precise, because it uses the timestamp from the log
message instead of relying on the current time; consequently it is
also possible to use this for offline log analysis.</p>
</div>
<div class="listingblock">
<div class="content">
<pre>if $Message =~ /login failure/
{
   # create will not do anything if the counter already exists
   create_stat('login_failures', 'RATE', 45, $EventTime);
   add_stat('login_failures', 1, $EventTime);
   if get_stat('login_failures', $EventTime) &gt;= 3
      log_warning("&gt;= 3 login failures detected within 45 seconds");
}</pre>
</div>
</div>
<div class="paragraph">
<p>Note that this is still not perfect because the time window used in
the rate calculation does not shift, so the
<a href="#lang_variable_example_corr_note">problem described in our previous
example</a> also affects this version, and this algorithm may not work
in some situations. For this reason and for better performance, it is
better to use the <a href="#pm_evcorr">event correlation module</a> instead; it
has a Thresholded rule which uses a sliding window to overcome this
problem.</p>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="core_funcs"><a class="anchor" href="#core_funcs"></a>3.6. Functions</h3>
<div class="paragraph">
<p>The following functions are exported by <em>core</em>.</p>
</div>
<div id="core_func_datetime" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_datetime">datetime</a> <code>datetime(<a href="#lang_type_integer">integer</a> arg)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Convert the integer argument, expressing the number of microseconds since epoch, to datetime.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_func_day" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_integer">integer</a> <code>day(<a href="#lang_type_datetime">datetime</a> datetime)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Return the day part of the time value.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_func_dayofweek" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_integer">integer</a> <code>dayofweek(<a href="#lang_type_datetime">datetime</a> datetime)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Return the number of days since Sunday in the range of 0-6.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_func_dayofyear" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_integer">integer</a> <code>dayofyear(<a href="#lang_type_datetime">datetime</a> datetime)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Return the day number of the year in the range of 1-366.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_func_dropped" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_boolean">boolean</a> <code>dropped()</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Return TRUE if the currently processed event has already been
     dropped.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_func_fix_year" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_datetime">datetime</a> <code>fix_year(<a href="#lang_type_datetime">datetime</a> datetime)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Set the year value to the current year in a <em>datetime</em> which was
parsed with a missing year, such as BSD Syslog or Cisco timestamps.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_func_get_stat" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_integer">integer</a> <code>get_stat(<a href="#lang_type_string">string</a> statname)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Return the value of the statistical counter or
   undef if it does not exist.</p>
</div>
</div>
</div>
</dd>
<dt class="hdlist1"><a href="#lang_type_integer">integer</a> <code>get_stat(<a href="#lang_type_string">string</a> statname, <a href="#lang_type_datetime">datetime</a> time)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Return the value of the statistical counter or
   undef if it does not exist. The <em>time</em> argument specifies the
   current time.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_func_get_var" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_unknown">unknown</a> <code>get_var(<a href="#lang_type_string">string</a> varname)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Return the value of the variable or undef if it
   does not exist.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_func_host_ip" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_ip4addr">ip4addr</a> <code>host_ip()</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Return the first non-loopback IP address the hostname resolves to.</p>
</div>
</div>
</div>
</dd>
<dt class="hdlist1"><a href="#lang_type_ip4addr">ip4addr</a> <code>host_ip(<a href="#lang_type_integer">integer</a> nth)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Return the <em>nth</em> non-loopback IP address the
   hostname resolves to. The <em>nth</em> argument starts from
   1.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_func_hostname" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_string">string</a> <code>hostname()</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Return the hostname (short form).</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_func_hostname_fqdn" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_string">string</a> <code>hostname_fqdn()</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Return the FQDN hostname. This function will return the short form if the FQDN hostname cannot be determined.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_func_hour" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_integer">integer</a> <code>hour(<a href="#lang_type_datetime">datetime</a> datetime)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Return the hour part of the time value.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_func_integer" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_integer">integer</a> <code>integer(<a href="#lang_type_unknown">unknown</a> arg)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Parse and convert the string argument to an integer. For datetime type it returns the number of microseconds since epoch.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_func_ip4addr" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_ip4addr">ip4addr</a> <code>ip4addr(<a href="#lang_type_integer">integer</a> arg)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Convert the integer argument to an ip4addr type.</p>
</div>
</div>
</div>
</dd>
<dt class="hdlist1"><a href="#lang_type_ip4addr">ip4addr</a> <code>ip4addr(<a href="#lang_type_integer">integer</a> arg, <a href="#lang_type_boolean">boolean</a> ntoa)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Convert the integer argument to an ip4addr
   type. If <em>ntoa</em> is set to true, the integer is assumed to be in
   network byte order. Instead of <code>1.2.3.4</code> the result will be
   <code>4.3.2.1</code>.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_func_lc" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_string">string</a> <code>lc(<a href="#lang_type_string">string</a> arg)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Convert the string to lower case.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_func_microsecond" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_integer">integer</a> <code>microsecond(<a href="#lang_type_datetime">datetime</a> datetime)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Return the microsecond part of the time value.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_func_minute" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_integer">integer</a> <code>minute(<a href="#lang_type_datetime">datetime</a> datetime)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Return the minute part of the time value.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_func_month" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_integer">integer</a> <code>month(<a href="#lang_type_datetime">datetime</a> datetime)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Return the month part of the <em>datetime</em> value.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_func_now" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_datetime">datetime</a> <code>now()</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Return the current time.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_func_parsedate" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_datetime">datetime</a> <code>parsedate(<a href="#lang_type_string">string</a> arg)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Parse a string containing a timestamp. Dates without timezone
information are treated as local time. The current year is used for
formats that do not include the year. An
<a href="#lang_literal_undef">undefined</a> datetime type is returned
if the argument cannot be parsed, so that the user can fix the error
(for example, <code>$EventTime = parsedate($somestring); if not
defined($EventTime) $EventTime = now();</code>). Supported timestamp formats
are listed below.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">RFC 3164 (legacy Syslog) and variations</dt>
<dd>
<div class="listingblock">
<div class="content">
<pre>Nov 6 08:49:37
Nov  6 08:49:37
Nov 06 08:49:37
Nov 3 14:50:30.403
Nov  3 14:50:30.403
Nov 03 14:50:30.403
Nov 3 2005 14:50:30
Nov  3 2005 14:50:30
Nov 03 2005 14:50:30
Nov 3 2005 14:50:30.403
Nov  3 2005 14:50:30.403
Nov 03 2005 14:50:30.403</pre>
</div>
</div>
</dd>
<dt class="hdlist1">RFC 1123</dt>
<dd>
<p>RFC 1123 compliant dates are also supported, including a
couple others which are similar such as those defined in RFC 822,
RFC 850, and RFC 1036.</p>
<div class="listingblock">
<div class="content">
<pre>Sun, 06 Nov 1994 08:49:37 GMT  ; RFC 822, updated by RFC 1123
Sunday, 06-Nov-94 08:49:37 GMT ; RFC 850, obsoleted by RFC 1036
Sun Nov  6 08:49:37 1994       ; ANSI C's asctime() format
Sun, 6 Nov 1994 08:49:37 GMT   ; RFC 822, updated by RFC 1123
Sun, 06 Nov 94 08:49:37 GMT    ; RFC 822
Sun,  6 Nov 94 08:49:37 GMT    ; RFC 822
Sun, 6 Nov 94 08:49:37 GMT     ; RFC 822
Sun, 06 Nov 94 08:49 GMT       ; Unknown
Sun, 6 Nov 94 08:49 GMT        ; Unknown
Sun, 06 Nov 94 8:49:37 GMT     ; Unknown [Elm 70.85]
Sun, 6 Nov 94 8:49:37 GMT      ; Unknown [Elm 70.85]
Mon,  7 Jan 2002 07:21:22 GMT  ; Unknown [Postfix]
Sun, 06-Nov-1994 08:49:37 GMT  ; RFC 850 with four digit years</pre>
</div>
</div>
<div class="paragraph">
<p>The above formats are also recognized when the leading day of week
and/or the timezone are omitted.</p>
</div>
</dd>
<dt class="hdlist1">Apache/NCSA date</dt>
<dd>
<p>This format can be found in Apache access logs and
other sources.</p>
<div class="listingblock">
<div class="content">
<pre>24/Aug/2009:16:08:57 +0200</pre>
</div>
</div>
</dd>
<dt class="hdlist1">ISO 8601 and RFC 3339</dt>
<dd>
<p>NXLog can parse the ISO format with or
without sub-second resolution, and with or without timezone
information. It accepts either a comma (<code>,</code>) or a dot (<code>.</code>) in case
there is sub-second resolution.</p>
<div class="listingblock">
<div class="content">
<pre>1977-09-06 01:02:03
1977-09-06 01:02:03.004
1977-09-06T01:02:03.004Z
1977-09-06T01:02:03.004+02:00
2011-5-29 0:3:21
2011-5-29 0:3:21+02:00
2011-5-29 0:3:21.004
2011-5-29 0:3:21.004+02:00</pre>
</div>
</div>
</dd>
<dt class="hdlist1">Windows timestamp</dt>
<dd>
<p>This format is <code>YYYYMMDDhhmmss.USEC</code> with
an optional timezone offset.</p>
<div class="listingblock">
<div class="content">
<pre>20100426151354.537875-000
20100426151354.537875000</pre>
</div>
</div>
</dd>
<dt class="hdlist1">Integer timestamp</dt>
<dd>
<p>This format is <code>XXXXXXXXXX.USEC</code>. The
value is expressed as an integer showing the number of seconds
elapsed since the epoch UTC. The fractional microsecond part is
optional.</p>
<div class="listingblock">
<div class="content">
<pre>1258531221.650359
1258531221</pre>
</div>
</div>
</dd>
</dl>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_func_replace" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_string">string</a> <code>replace(<a href="#lang_type_string">string</a> subject, <a href="#lang_type_string">string</a> src, <a href="#lang_type_string">string</a> dst)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Replace all occurrences of <em>src</em> with <em>dst</em> in the <em>subject</em> string.</p>
</div>
</div>
</div>
</dd>
<dt class="hdlist1"><a href="#lang_type_string">string</a> <code>replace(<a href="#lang_type_string">string</a> subject, <a href="#lang_type_string">string</a> src, <a href="#lang_type_string">string</a> dst, <a href="#lang_type_integer">integer</a> count)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Replace <em>count</em> number occurrences of <em>src</em> with <em>dst</em> in the <em>subject</em> string.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_func_second" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_integer">integer</a> <code>second(<a href="#lang_type_datetime">datetime</a> datetime)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Return the second part of the time value.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_func_size" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_integer">integer</a> <code>size(<a href="#lang_type_string">string</a> str)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Return the size of the string <em>str</em> in bytes.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_func_strftime" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_string">string</a> <code>strftime(<a href="#lang_type_datetime">datetime</a> datetime, <a href="#lang_type_string">string</a> fmt)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Convert a datetime to a string with the given format. See the
strftime(3) manual or the Windows
<a href="https://docs.microsoft.com/en-us/cpp/c-runtime-library/reference/strftime-wcsftime-strftime-l-wcsftime-l">strftime</a>
reference for the format specification.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_func_string" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_string">string</a> <code>string(<a href="#lang_type_unknown">unknown</a> arg)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Convert the argument to a string.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_func_strptime" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_datetime">datetime</a> <code>strptime(<a href="#lang_type_string">string</a> input, <a href="#lang_type_string">string</a> fmt)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Convert the string to a datetime with the given format. See the manual of strptime(3) for the format specification.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_func_substr" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_string">string</a> <code>substr(<a href="#lang_type_string">string</a> src, <a href="#lang_type_integer">integer</a> from)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Return the string starting at the byte offset
   specified in <em>from</em>.</p>
</div>
</div>
</div>
</dd>
<dt class="hdlist1"><a href="#lang_type_string">string</a> <code>substr(<a href="#lang_type_string">string</a> src, <a href="#lang_type_integer">integer</a> from, <a href="#lang_type_integer">integer</a> to)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Return a sub-string specified with the starting
   and ending positions as byte offsets from the beginning of the
   string.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_func_type" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_string">string</a> <code>type(<a href="#lang_type_unknown">unknown</a> arg)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Return the type of the variable, which can be <code>boolean</code>,
     <code>integer</code>, <code>string</code>, <code>datetime</code>, <code>ip4addr</code>, <code>ip6addr</code>, <code>regexp</code>,
     or <code>binary</code>. For values with the unknown type, it returns
     undef.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_func_uc" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_string">string</a> <code>uc(<a href="#lang_type_string">string</a> arg)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Convert the string to upper case.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_func_year" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_integer">integer</a> <code>year(<a href="#lang_type_datetime">datetime</a> datetime)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Return the year part of the <em>datetime</em> value.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect2">
<h3 id="core_procs"><a class="anchor" href="#core_procs"></a>3.7. Procedures</h3>
<div class="paragraph">
<p>The following procedures are exported by <em>core</em>.</p>
</div>
<div id="core_proc_add_stat" class="dlist">
<dl>
<dt class="hdlist1"><code>add_stat(<a href="#lang_type_string">string</a> statname, <a href="#lang_type_integer">integer</a> value);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Add <em>value</em> to the statistical counter using the current time.</p>
</div>
</div>
</div>
</dd>
<dt class="hdlist1"><code>add_stat(<a href="#lang_type_string">string</a> statname, <a href="#lang_type_integer">integer</a> value, <a href="#lang_type_datetime">datetime</a> time);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Add <em>value</em> to the statistical counter using the time specified in the argument named <em>time</em>.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_proc_add_to_route" class="dlist">
<dl>
<dt class="hdlist1"><code>add_to_route(<a href="#lang_type_string">string</a> routename);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Copy the currently processed event data to the route specified. This
procedure makes a copy of the data. The original will be processed
normally. Note that flow control is explicitly disabled when moving
data with add_to_route() and the data will not be added if the queue
of the target module(s) is full.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_proc_create_stat" class="dlist">
<dl>
<dt class="hdlist1"><code>create_stat(<a href="#lang_type_string">string</a> statname, <a href="#lang_type_string">string</a> type);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Create a module statistical counter with the specified name using the
current time. The statistical counter will be created with an infinite
lifetime. The <em>type</em> argument must be one of the following to select
the required algorithm for calculating the value of the statistical
counter: <code>COUNT</code>, <code>COUNTMIN</code>, <code>COUNTMAX</code>, <code>AVG</code>, <code>AVGMIN</code>, <code>AVGMAX</code>,
<code>RATE</code>, <code>RATEMIN</code>, <code>RATEMAX</code>, <code>GRAD</code>, <code>GRADMIN</code>, or <code>GRADMAX</code> (see
<a href="#lang_stat">Statistical Counters</a>).</p>
</div>
<div class="paragraph">
<p>This procedure with two parameters can
only be used with <code>COUNT</code>, otherwise the interval parameter must be
specified (see below). This procedure will do nothing if a counter
with the specified name already exists.</p>
</div>
</div>
</div>
</dd>
<dt class="hdlist1"><code>create_stat(<a href="#lang_type_string">string</a> statname, <a href="#lang_type_string">string</a> type, <a href="#lang_type_integer">integer</a> interval);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Create a module statistical counter with the specified name to be calculated over <em>interval</em> seconds and using the current time. The statistical counter will be created with an infinite lifetime.</p>
</div>
</div>
</div>
</dd>
<dt class="hdlist1"><code>create_stat(<a href="#lang_type_string">string</a> statname, <a href="#lang_type_string">string</a> type, <a href="#lang_type_integer">integer</a> interval, <a href="#lang_type_datetime">datetime</a> time);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Create a module statistical counter with the
   specified name to be calculated over <em>interval</em> seconds and the
   time value specified in the <em>time</em> argument. The statistical
   counter will be created with an infinite
   lifetime.</p>
</div>
</div>
</div>
</dd>
<dt class="hdlist1"><code>create_stat(<a href="#lang_type_string">string</a> statname, <a href="#lang_type_string">string</a> type, <a href="#lang_type_integer">integer</a> interval, <a href="#lang_type_datetime">datetime</a> time, <a href="#lang_type_integer">integer</a> lifetime);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Create a module statistical counter with the
   specified name to be calculated over <em>interval</em> seconds and the
   time value specified in the <em>time</em> argument. The statistical
   counter will expire after <em>lifetime</em> seconds.</p>
</div>
</div>
</div>
</dd>
<dt class="hdlist1"><code>create_stat(<a href="#lang_type_string">string</a> statname, <a href="#lang_type_string">string</a> type, <a href="#lang_type_integer">integer</a> interval, <a href="#lang_type_datetime">datetime</a> time, <a href="#lang_type_datetime">datetime</a> expiry);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Create a module statistical counter with the
   specified name to be calculated over <em>interval</em> seconds and the
   time value specified in the <em>time</em> argument. The statistical
   counter will expire at <em>expiry</em>.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_proc_create_var" class="dlist">
<dl>
<dt class="hdlist1"><code>create_var(<a href="#lang_type_string">string</a> varname);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Create a module variable with the specified name. The variable will be created with an infinite lifetime.</p>
</div>
</div>
</div>
</dd>
<dt class="hdlist1"><code>create_var(<a href="#lang_type_string">string</a> varname, <a href="#lang_type_integer">integer</a> lifetime);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Create a module variable with the specified name
   and the <em>lifetime</em> given in seconds.  When the lifetime expires,
   the variable will be deleted automatically and <code>get_var(name)</code> will
   return undef.</p>
</div>
</div>
</div>
</dd>
<dt class="hdlist1"><code>create_var(<a href="#lang_type_string">string</a> varname, <a href="#lang_type_datetime">datetime</a> expiry);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Create a module variable with the specified
   name. The <em>expiry</em> specifies when the variable should be deleted
   automatically.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_proc_debug" class="dlist">
<dl>
<dt class="hdlist1"><code>debug(<a href="#lang_type_unknown">unknown</a> arg, <a href="#lang_type_varargs">varargs</a> args);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Print the argument(s) at DEBUG log level. Same as <a href="#core_proc_log_debug">log_debug()</a>.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_proc_delete" class="dlist">
<dl>
<dt class="hdlist1"><code>delete(<a href="#lang_type_unknown">unknown</a> arg);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Delete the field from the event. For example, <code>delete($field)</code>.
Note that <code>$field = undef</code> is not the same, though after both operations
the field will be undefined.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_proc_delete_var" class="dlist">
<dl>
<dt class="hdlist1"><code>delete_var(<a href="#lang_type_string">string</a> varname);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Delete the module variable with the specified name if it exists.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_proc_drop" class="dlist">
<dl>
<dt class="hdlist1"><code>drop();</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Drop the event record that is currently being processed. Any further
action on the event record will result in a "missing logdata" error.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_proc_log_debug" class="dlist">
<dl>
<dt class="hdlist1"><code>log_debug(<a href="#lang_type_unknown">unknown</a> arg, <a href="#lang_type_varargs">varargs</a> args);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Print the argument(s) at DEBUG log level. Same as
   <a href="#core_proc_debug">debug()</a>.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_proc_log_error" class="dlist">
<dl>
<dt class="hdlist1"><code>log_error(<a href="#lang_type_unknown">unknown</a> arg, <a href="#lang_type_varargs">varargs</a> args);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Print the argument(s) at ERROR log level.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_proc_log_info" class="dlist">
<dl>
<dt class="hdlist1"><code>log_info(<a href="#lang_type_unknown">unknown</a> arg, <a href="#lang_type_varargs">varargs</a> args);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Print the argument(s) at INFO log level.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_proc_log_warning" class="dlist">
<dl>
<dt class="hdlist1"><code>log_warning(<a href="#lang_type_unknown">unknown</a> arg, <a href="#lang_type_varargs">varargs</a> args);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Print the argument(s) at WARNING log level.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_proc_rename_field" class="dlist">
<dl>
<dt class="hdlist1"><code>rename_field(<a href="#lang_type_string">string</a> old, <a href="#lang_type_string">string</a> new);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Rename a field. For example, <code>rename_field("old", "new")</code>.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_proc_reroute" class="dlist">
<dl>
<dt class="hdlist1"><code>reroute(<a href="#lang_type_string">string</a> routename);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Move the currently processed event data to the route specified. The
event data will enter the route as if it was received by an input
module there. Note that flow control is explicitly disabled when
moving data with reroute() and the data will be dropped if the queue
of the target module(s) is full.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_proc_set_var" class="dlist">
<dl>
<dt class="hdlist1"><code>set_var(<a href="#lang_type_string">string</a> varname, <a href="#lang_type_unknown">unknown</a> value);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Set the value of a module variable. If the variable does not exist, it will be created with an infinite lifetime.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_proc_sleep" class="dlist">
<dl>
<dt class="hdlist1"><code>sleep(<a href="#lang_type_integer">integer</a> interval);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Sleep the specified number of microseconds. This procedure is provided
for testing purposes primarily. It can be used as a poor man&#8217;s rate
limiting tool, though this use is not recommended.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="extension-modules"><a class="anchor" href="#extension-modules"></a>4. Extension Modules</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Extension modules do not process log messages directly, and for this
reason their instances cannot be part of a route.
These modules enhance the features of NXLog in various ways,
such as exporting new functions and procedures or registering
additional I/O reader and writer functions (to be used with modules
supporting the <a href="#config_inputtype">InputType</a> and
<a href="#config_outputtype">OutputType</a> directives). There are many ways to
hook an extension module into the NXLog engine, as the
following modules illustrate.</p>
</div>
<div class="sect2">
<h3 id="xm_charconv"><a class="anchor" href="#xm_charconv"></a>4.1. Character Set Conversion (xm_charconv)</h3>
<div class="paragraph">
<p>This module provides tools for converting strings between different character
sets (codepages). All the encodings available to <em>iconv</em> are supported. See
<code>iconv -l</code> for a list of encoding names.</p>
</div>
<div class="sect3">
<h4 id="xm_charconv_config"><a class="anchor" href="#xm_charconv_config"></a>4.1.1. Configuration</h4>
<div class="paragraph">
<p>The <em>xm_charconv</em> module accepts the following directives in addition to
the <a href="#config_module_common">common module directives</a>.</p>
</div>
<div id="xm_charconv_config_autodetectcharsets" class="dlist">
<dl>
<dt class="hdlist1">AutodetectCharsets</dt>
<dd>
<p>This optional directive accepts a comma-separated
list of character set names. When <code>auto</code> is specified as the source
encoding for <a href="#xm_charconv_func_convert">convert()</a> or
<a href="#xm_charconv_proc_convert_fields">convert_fields()</a>, these character sets
will be tried for conversion.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="xm_charconv_funcs"><a class="anchor" href="#xm_charconv_funcs"></a>4.1.2. Functions</h4>
<div class="paragraph">
<p>The following functions are exported by <em>xm_charconv</em>.</p>
</div>
<div id="xm_charconv_func_convert" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_string">string</a> <code>convert(<a href="#lang_type_string">string</a> source, <a href="#lang_type_string">string</a> srcencoding, <a href="#lang_type_string">string</a> dstencoding)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Convert the source string to the encoding specified in <em>dstencoding</em>
from <em>srcencoding</em>. The <em>srcencoding</em> argument can be set to <code>auto</code> to
request auto detection.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="xm_charconv_procs"><a class="anchor" href="#xm_charconv_procs"></a>4.1.3. Procedures</h4>
<div class="paragraph">
<p>The following procedures are exported by <em>xm_charconv</em>.</p>
</div>
<div id="xm_charconv_proc_convert_fields" class="dlist">
<dl>
<dt class="hdlist1"><code>convert_fields(<a href="#lang_type_string">string</a> srcencoding, <a href="#lang_type_string">string</a> dstencoding);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Convert all string type fields of a log message from <em>srcencoding</em> to
<em>dstencoding</em>. The <em>srcencoding</em> argument can be set to <code>auto</code> to
request auto detection.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="xm_charconv_config_examples"><a class="anchor" href="#xm_charconv_config_examples"></a>4.1.4. Examples</h4>
<div id="xm_charconv_example_proc" class="exampleblock">
<div class="title">Example 48. Character set auto-detection of various input encodings</div>
<div class="content">
<div class="paragraph">
<p>This configuration shows an example of character set
auto-detection. The input file can contain differently encoded lines,
and the module normalizes output to UTF-8.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">charconv</span><span class="tag">&gt;</span>
    Module              xm_charconv
    AutodetectCharsets  utf-8, euc-jp, utf-16, utf-32, iso8859-2
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">filein</span><span class="tag">&gt;</span>
    Module              im_file
    File                &quot;tmp/input&quot;
    Exec                convert_fields(&quot;auto&quot;, &quot;utf-8&quot;);
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">fileout</span><span class="tag">&gt;</span>
    Module              om_file
    File                &quot;tmp/output&quot;
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">r</span><span class="tag">&gt;</span>
    Path                filein =<span class="error">&gt;</span> fileout
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="xm_csv"><a class="anchor" href="#xm_csv"></a>4.2. Delimiter-Separated Values (xm_csv)</h3>
<div class="paragraph">
<p>This module provides functions and procedures for working with data
formatted as comma-separated values (CSV). CSV input can be parsed
into <a href="#lang_fields">fields</a> and CSV output can be generated.
Delimiters other than the comma can be used also.</p>
</div>
<div class="paragraph">
<p>The <a href="#pm_transformer">pm_transformer</a> module provides a simple
interface to parse and generate CSV format, but the <em>xm_csv</em> module
exports an API that can be used to solve more complex tasks involving
CSV formatted data.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
It is possible to use more than one <em>xm_csv</em> module instance with
      different options in order to support different CSV formats at
      the same time. For this reason, functions and procedures
      exported by the module are public and must be referenced by the
      module instance name.
</td>
</tr>
</table>
</div>
<div class="sect3">
<h4 id="xm_csv_config"><a class="anchor" href="#xm_csv_config"></a>4.2.1. Configuration</h4>
<div class="paragraph">
<p>The <em>xm_csv</em> module accepts the following directives in addition to the
<a href="#config_module_common">common module directives</a>. The
<a href="#xm_csv_config_fields">Fields</a> directive is required.</p>
</div>
<div id="xm_csv_config_fields" class="dlist">
<dl>
<dt class="hdlist1">Fields</dt>
<dd>
<p>This mandatory directive accepts a comma-separated list of
fields which will be filled from the input parsed. Field names with
or without the dollar sign (<code>$</code>) are accepted. The fields will be
stored as <a href="#lang_type_string">strings</a> unless their types are
explicitly specified with the
<a href="#xm_csv_config_fieldtypes">FieldTypes</a> directive.</p>
</dd>
</dl>
</div>
<hr>
<div id="xm_csv_config_delimiter" class="dlist">
<dl>
<dt class="hdlist1">Delimiter</dt>
<dd>
<p>This optional directive takes a single character (see
<a href="#xm_csv_config_char">below</a>) as argument to specify the
delimiter character used to separate fields. The default delimiter
character is the comma (<code>,</code>). Note that there is no delimiter after
the last field.</p>
</dd>
</dl>
</div>
<div id="xm_csv_config_escapechar" class="dlist">
<dl>
<dt class="hdlist1">EscapeChar</dt>
<dd>
<p>This optional directive takes a single character (see
<a href="#xm_csv_config_char">below</a>) as argument to specify the escape
character used to escape special characters. The escape character is
used to prefix the following characters: the escape character
itself, the <a href="#xm_csv_config_quotechar">quote character</a>, and the
<a href="#xm_csv_config_delimiter">delimiter character</a>. If
<a href="#xm_csv_config_escapecontrol">EscapeControl</a> is TRUE, the newline
(<code>\n</code>), carriage return (<code>\r</code>), tab (<code>\t</code>), and backspace (<code>\b</code>)
control characters are also escaped. The default escape character is
the backslash character (<code>\</code>).</p>
</dd>
</dl>
</div>
<div id="xm_csv_config_escapecontrol" class="dlist">
<dl>
<dt class="hdlist1">EscapeControl</dt>
<dd>
<p>If this optional boolean directive is set to TRUE,
control characters are also escaped. See the
<a href="#xm_csv_config_escapechar">EscapeChar</a> directive for details. The
default is TRUE: control characters are escaped. Note that this is
necessary to allow single line CSV field lists which contain
line-breaks.</p>
</dd>
</dl>
</div>
<div id="xm_csv_config_fieldtypes" class="dlist">
<dl>
<dt class="hdlist1">FieldTypes</dt>
<dd>
<p>This optional directive specifies the list of types
corresponding to the field names defined in
<a href="#xm_csv_config_fields">Fields</a>. If specified, the number of types
must match the number of field names specified with
<a href="#xm_csv_config_fields">Fields</a>. If this directive is omitted, all
fields will be stored as <a href="#lang_type_string">strings</a>. This
directive has no effect on the fields-to-CSV conversion.</p>
</dd>
</dl>
</div>
<div id="xm_csv_config_quotechar" class="dlist">
<dl>
<dt class="hdlist1">QuoteChar</dt>
<dd>
<p>This optional directive takes a single character (see
<a href="#xm_csv_config_char">below</a>) as argument to specify the quote
character used to enclose fields. If
<a href="#xm_csv_config_quoteoptional">QuoteOptional</a> is TRUE, then only
<a href="#lang_type_string">string</a> type fields are quoted. The default is
the double-quote character (<code>"</code>).</p>
</dd>
</dl>
</div>
<div id="xm_csv_config_quotemethod" class="dlist">
<dl>
<dt class="hdlist1">QuoteMethod</dt>
<dd>
<p>This optional directive can take the following values:</p>
<div class="openblock">
<div class="content">
<div class="dlist">
<dl>
<dt class="hdlist1">All</dt>
<dd>
<p>All fields will be quoted.</p>
</dd>
<dt class="hdlist1">None</dt>
<dd>
<p>Nothing will be quoted. This can be problematic if a field
value (typically text that can contain any character) contains the
delimiter character. Make sure that this is escaped or replaced
with something else.</p>
</dd>
<dt class="hdlist1">String</dt>
<dd>
<p>Only <a href="#lang_type_string">string</a> type fields will be
quoted. This has the same effect as
<a href="#xm_csv_config_quoteoptional">QuoteOptional</a> set to TRUE and is
the default behavior if the <strong>QuoteMethod</strong> directive is not
specified.</p>
</dd>
</dl>
</div>
</div>
</div>
<div class="paragraph">
<p>Note that this directive only effects CSV generation when using
<a href="#xm_csv_func_to_csv">to_csv()</a>. The CSV parser can automatically
detect the quotation.</p>
</div>
</dd>
</dl>
</div>
<div id="xm_csv_config_quoteoptional" class="dlist">
<dl>
<dt class="hdlist1">QuoteOptional</dt>
<dd>
<p>This directive has been deprecated in favor of
<a href="#xm_csv_config_quotemethod">QuoteMethod</a>, which should be used
instead.</p>
</dd>
</dl>
</div>
<div id="xm_csv_config_undefvalue" class="dlist">
<dl>
<dt class="hdlist1">UndefValue</dt>
<dd>
<p>This optional directive specifies a string which will be
treated as an undefined value. This is particularly useful when
parsing the W3C format where the dash (<code>-</code>) marks an omitted field.</p>
</dd>
</dl>
</div>
<div class="sect4">
<h5 id="xm_csv_config_char"><a class="anchor" href="#xm_csv_config_char"></a>4.2.1.1. Specifying Quote, Escape, and Delimiter Characters</h5>
<div class="paragraph">
<p>The <a href="#xm_csv_config_quotechar">QuoteChar</a>,
<a href="#xm_csv_config_escapechar">EscapeChar</a>, and
<a href="#xm_csv_config_delimiter">Delimiter</a> directives can be specified in
several ways.</p>
</div>
<div id="xm_csv_config_char_single" class="dlist">
<dl>
<dt class="hdlist1">Unquoted single character</dt>
<dd>
<p>Any printable character can be specified
as an unquoted character, except for the backslash (<code>\</code>):</p>
<div class="listingblock">
<div class="content">
<pre>Delimiter ;</pre>
</div>
</div>
</dd>
</dl>
</div>
<div id="'xm_csv_config_char_control" class="dlist">
<dl>
<dt class="hdlist1">Control characters</dt>
<dd>
<p>The following non-printable characters can be
specified with escape sequences:</p>
<div class="openblock">
<div class="content">
<div class="dlist">
<dl>
<dt class="hdlist1">\a</dt>
<dd>
<p>audible alert (bell)</p>
</dd>
<dt class="hdlist1">\b</dt>
<dd>
<p>backspace</p>
</dd>
<dt class="hdlist1">\t</dt>
<dd>
<p>horizontal tab</p>
</dd>
<dt class="hdlist1">\n</dt>
<dd>
<p>newline</p>
</dd>
<dt class="hdlist1">\v</dt>
<dd>
<p>vertical tab</p>
</dd>
<dt class="hdlist1">\f</dt>
<dd>
<p>formfeed</p>
</dd>
<dt class="hdlist1">\r</dt>
<dd>
<p>carriage return</p>
</dd>
</dl>
</div>
</div>
</div>
<div class="paragraph">
<p>For example, to use TAB delimiting:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Delimiter \t</pre>
</div>
</div>
</dd>
</dl>
</div>
<div id="'xm_csv_config_char_single_quote" class="dlist">
<dl>
<dt class="hdlist1">A character in single quotes</dt>
<dd>
<p>The configuration parser strips
whitespace, so it is not possible to define a space as the delimiter
unless it is enclosed within quotes:</p>
<div class="listingblock">
<div class="content">
<pre>Delimiter ' '</pre>
</div>
</div>
<div class="paragraph">
<p>Printable characters can also be enclosed:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Delimiter ';'</pre>
</div>
</div>
<div class="paragraph">
<p>The backslash can be specified when enclosed within quotes:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Delimiter '\'</pre>
</div>
</div>
</dd>
</dl>
</div>
<div id="'xm_csv_config_char_double_quote" class="dlist">
<dl>
<dt class="hdlist1">A character in double quotes</dt>
<dd>
<p>Double quotes can be used like single
quotes:</p>
<div class="listingblock">
<div class="content">
<pre>Delimiter " "</pre>
</div>
</div>
<div class="paragraph">
<p>The backslash can be specified when enclosed within double quotes:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Delimiter "\"</pre>
</div>
</div>
</dd>
</dl>
</div>
<div id="'xm_csv_config_char_hex_code" class="dlist">
<dl>
<dt class="hdlist1">A hexadecimal ASCII code</dt>
<dd>
<p>Hexadecimal ASCII character codes can also
be used by prepending <code>0x</code>. For example, the space can be specified
as:</p>
<div class="listingblock">
<div class="content">
<pre>Delimiter 0x20</pre>
</div>
</div>
<div class="paragraph">
<p>This is equivalent to:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Delimiter " "</pre>
</div>
</div>
</dd>
</dl>
</div>
</div>
</div>
<div class="sect3">
<h4 id="xm_csv_funcs"><a class="anchor" href="#xm_csv_funcs"></a>4.2.2. Functions</h4>
<div class="paragraph">
<p>The following functions are exported by <em>xm_csv</em>.</p>
</div>
<div id="xm_csv_func_to_csv" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_string">string</a> <code>to_csv()</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Convert the specified fields to a single CSV formatted
     string.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="xm_csv_procs"><a class="anchor" href="#xm_csv_procs"></a>4.2.3. Procedures</h4>
<div class="paragraph">
<p>The following procedures are exported by <em>xm_csv</em>.</p>
</div>
<div id="xm_csv_proc_parse_csv" class="dlist">
<dl>
<dt class="hdlist1"><code>parse_csv();</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Parse the <code>$raw_event</code> field as CSV input.</p>
</div>
</div>
</div>
</dd>
<dt class="hdlist1"><code>parse_csv(<a href="#lang_type_string">string</a> source);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Parse the given string as CSV format.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_csv_proc_to_csv" class="dlist">
<dl>
<dt class="hdlist1"><code>to_csv();</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Format the specified fields as CSV and put this into the
     <code>$raw_event</code> field.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="xm_csv_config_examples"><a class="anchor" href="#xm_csv_config_examples"></a>4.2.4. Examples</h4>
<div id="xm_csv_example1" class="exampleblock">
<div class="title">Example 49. Complex CSV Format Conversion</div>
<div class="content">
<div class="paragraph">
<p>This example shows that the <em>xm_csv</em> module can not only parse and
create CSV formatted input and output, but with multiple <em>xm_csv</em>
modules it is also possible to reorder, add, remove, or modify fields
before outputting to a different CSV format.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">csv1</span><span class="tag">&gt;</span>
    Module      xm_csv
    Fields      $id, $name, $number
    FieldTypes  integer, string, integer
    Delimiter   ,
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Extension</span> <span class="attribute-name">csv2</span><span class="tag">&gt;</span>
    Module      xm_csv
    Fields      $id, $number, $name, $date
    Delimiter   ;
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">in</span><span class="tag">&gt;</span>
    Module      im_file
    File        &quot;tmp/input&quot;
    <span class="tag">&lt;Exec&gt;</span>
        csv1-<span class="error">&gt;</span>parse_csv();
        $date = now();
        if not defined $number $number = 0;
        csv2-<span class="error">&gt;</span>to_csv();
    <span class="tag">&lt;/Exec&gt;</span>
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">out</span><span class="tag">&gt;</span>
    Module      om_file
    File        &quot;tmp/output&quot;
<span class="tag">&lt;/Output&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">Input Sample</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="csv">1, &quot;John K.&quot;, 42
2, &quot;Joe F.&quot;, 43</code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">Output Sample</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="csv">1;42;&quot;John K.&quot;;2011-01-15 23:45:20
2;43;&quot;Joe F.&quot;;2011-01-15 23:45:20</code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="xm_exec"><a class="anchor" href="#xm_exec"></a>4.3. External Programs (xm_exec)</h3>
<div class="paragraph">
<p>This module provides two procedures which make it possible to execute
external scripts or programs. These two procedures are provided
through this extension module in order to keep the NXLog core
small. Also, without this module loaded an administrator is not able
to execute arbitrary scripts.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
The <a href="#im_exec">im_exec</a> and <a href="#om_exec">om_exec</a> modules also
      provide support for running external programs, though the
      purpose of these is to pipe data to and read data from
      programs. The procedures provided by the <em>xm_exec</em> module do not
      pipe log message data, but are intended for multiple invocations
      (though data can be still passed to the executed script/program
      as command line arguments).
</td>
</tr>
</table>
</div>
<div class="sect3">
<h4 id="xm_exec_config"><a class="anchor" href="#xm_exec_config"></a>4.3.1. Configuration</h4>
<div class="paragraph">
<p>The <em>xm_exec</em> module accepts only the <a href="#config_module_common">common module
directives</a>.</p>
</div>
</div>
<div class="sect3">
<h4 id="xm_exec_procs"><a class="anchor" href="#xm_exec_procs"></a>4.3.2. Procedures</h4>
<div class="paragraph">
<p>The following procedures are exported by <em>xm_exec</em>.</p>
</div>
<div id="xm_exec_proc_exec" class="dlist">
<dl>
<dt class="hdlist1"><code>exec(<a href="#lang_type_string">string</a> command, <a href="#lang_type_varargs">varargs</a> args);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Execute <em>command</em>, passing it the supplied arguments, and wait for it
to terminate. The command is executed in the caller module&#8217;s
context. Note that the module calling this procedure will block until
the process terminates. Use the
<a href="#xm_exec_proc_exec_async">exec_async()</a> procedure to
avoid this problem. All output written to standard output and standard
error by the spawned process is discarded.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_exec_proc_exec_async" class="dlist">
<dl>
<dt class="hdlist1"><code>exec_async(<a href="#lang_type_string">string</a> command, <a href="#lang_type_varargs">varargs</a> args);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>This procedure executes the command passing it the supplied arguments
and does not wait for it to terminate.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="xm_exec_config_examples"><a class="anchor" href="#xm_exec_config_examples"></a>4.3.3. Examples</h4>
<div class="exampleblock">
<div class="title">Example 50. NXLog Acting as a Cron Daemon</div>
<div class="content">
<div class="paragraph">
<p>This <em>xm_exec</em> module instance will run the command every second without
waiting for it to terminate.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">exec</span><span class="tag">&gt;</span>
    Module  xm_exec
    <span class="tag">&lt;Schedule&gt;</span>
        Every   1 sec
        Exec    exec_async(&quot;/bin/true&quot;);
    <span class="tag">&lt;/Schedule&gt;</span>
<span class="tag">&lt;/Extension&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
<div class="exampleblock">
<div class="title">Example 51. Sending Email Alerts</div>
<div class="content">
<div class="paragraph">
<p>If the <code>$raw_event</code> field matches the regular expression, an email
will be sent.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">exec</span><span class="tag">&gt;</span>
    Module  xm_exec
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">tcp</span><span class="tag">&gt;</span>
    Module  im_tcp
    Host    0.0.0.0
    Port    1514
    <span class="tag">&lt;Exec&gt;</span>
      if $raw_event =~ /alertcondition/
      {
      exec_async(&quot;/bin/sh&quot;, &quot;-c&quot;, 'echo &quot;' + $Hostname +
        '\n\nRawEvent:\n' + $raw_event +
        '&quot;|/usr/bin/mail -a &quot;Content-Type: text/plain; charset=UTF-8&quot; -s &quot;ALERT&quot; ' +
        'user@domain.com');
      }
    <span class="tag">&lt;/Exec&gt;</span>
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">file</span><span class="tag">&gt;</span>
    Module  om_file
    File    &quot;/var/log/messages&quot;
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">tcp_to_file</span><span class="tag">&gt;</span>
    Path    tcp =<span class="error">&gt;</span> file
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>For another example, see <a href="#om_file_config_example_rotate1">File Rotation Based on Size</a>.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="xm_fileop"><a class="anchor" href="#xm_fileop"></a>4.4. File Operations (xm_fileop)</h3>
<div class="paragraph">
<p>This module provides functions and procedures to manipulate files.
Coupled with a <a href="#config_module_schedule">Schedule</a> block, this module
allows various log rotation and retention policies to be implemented,
including:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>log file retention based on file size,</p>
</li>
<li>
<p>log file retention based on file age, and</p>
</li>
<li>
<p>cyclic log file rotation and retention.</p>
</li>
</ul>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
Rotating, renaming, or removing the file written by
      <a href="#om_file">om_file</a> is also supported with the help of the
      <em>om_file</em> <a href="#om_file_proc_reopen">reopen()</a> procedure.
</td>
</tr>
</table>
</div>
<div class="sect3">
<h4 id="xm_fileop_config"><a class="anchor" href="#xm_fileop_config"></a>4.4.1. Configuration</h4>
<div class="paragraph">
<p>The <em>xm_fileop</em> module accepts only the <a href="#config_module_common">common
module directives</a>.</p>
</div>
</div>
<div class="sect3">
<h4 id="xm_fileop_funcs"><a class="anchor" href="#xm_fileop_funcs"></a>4.4.2. Functions</h4>
<div class="paragraph">
<p>The following functions are exported by <em>xm_fileop</em>.</p>
</div>
<div id="xm_fileop_func_dir_exists" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_boolean">boolean</a> <code>dir_exists(<a href="#lang_type_string">string</a> path)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Return TRUE if <em>path</em> exists and is a directory. On error undef is
returned and an error is logged.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_fileop_func_dir_temp_get" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_string">string</a> <code>dir_temp_get()</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Return the name of a directory suitable as a temporary storage
location.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_fileop_func_file_basename" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_string">string</a> <code>file_basename(<a href="#lang_type_string">string</a> file)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Strip the directory name from the full <em>file</em> path. For example,
<code>basename('/var/log/app.log')</code> will return <code>app.log</code>.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_fileop_func_file_ctime" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_datetime">datetime</a> <code>file_ctime(<a href="#lang_type_string">string</a> file)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Return the creation or inode-changed time of <em>file</em>. On error undef is
returned and an error is logged.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_fileop_func_file_dirname" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_string">string</a> <code>file_dirname(<a href="#lang_type_string">string</a> file)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Return the directory name of the full <em>file</em> path. For example,
<code>basename('/var/log/app.log')</code> will return <code>/var/log</code>. Returns an
empty string if <em>file</em> does not contain any directory separators.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_fileop_func_file_exists" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_boolean">boolean</a> <code>file_exists(<a href="#lang_type_string">string</a> file)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Return TRUE if <em>file</em> exists and is a regular file.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_fileop_func_file_inode" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_integer">integer</a> <code>file_inode(<a href="#lang_type_string">string</a> file)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Return the inode number of <em>file</em>. On error undef is returned and an
error is logged.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_fileop_func_file_mtime" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_datetime">datetime</a> <code>file_mtime(<a href="#lang_type_string">string</a> file)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Return the last modification time of <em>file</em>. On error undef is
returned and an error is logged.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_fileop_func_file_read" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_string">string</a> <code>file_read(<a href="#lang_type_string">string</a> file)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Return the contents of <em>file</em> as a string value. On error undef is
returned and an error is logged.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_fileop_func_file_size" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_integer">integer</a> <code>file_size(<a href="#lang_type_string">string</a> file)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Return the size of <em>file</em>, in bytes. On error undef is returned and an
error is logged.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_fileop_func_file_type" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_string">string</a> <code>file_type(<a href="#lang_type_string">string</a> file)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Return the type of <em>file</em>. The following string values can be
returned: FILE, DIR, CHAR, BLOCK, PIPE, LINK, SOCKET, and UNKNOWN. On
error undef is returned and an error is logged.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="xm_fileop_procs"><a class="anchor" href="#xm_fileop_procs"></a>4.4.3. Procedures</h4>
<div class="paragraph">
<p>The following procedures are exported by <em>xm_fileop</em>.</p>
</div>
<div id="xm_fileop_proc_dir_make" class="dlist">
<dl>
<dt class="hdlist1"><code>dir_make(<a href="#lang_type_string">string</a> path);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Create a directory recursively (like <code>mkdir -p</code>). It succeeds if the
directory already exists. An error is logged if the operation fails.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_fileop_proc_dir_remove" class="dlist">
<dl>
<dt class="hdlist1"><code>dir_remove(<a href="#lang_type_string">string</a> file);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Remove the directory from the filesystem.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_fileop_proc_file_append" class="dlist">
<dl>
<dt class="hdlist1"><code>file_append(<a href="#lang_type_string">string</a> src, <a href="#lang_type_string">string</a> dst);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Append the contents of the file <em>src</em> to <em>dst</em>. The <em>dst</em> file will be
created if it does not exist. An error is logged if the operation
fails.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_fileop_proc_file_chmod" class="dlist">
<dl>
<dt class="hdlist1"><code>file_chmod(<a href="#lang_type_string">string</a> file, <a href="#lang_type_integer">integer</a> mode);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Change the permissions of <em>file</em>. This function is only implemented on
POSIX systems where chmod() is available in the underlying operating
system. An error is logged if the operation fails.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_fileop_proc_file_chown" class="dlist">
<dl>
<dt class="hdlist1"><code>file_chown(<a href="#lang_type_string">string</a> file, <a href="#lang_type_integer">integer</a> uid, <a href="#lang_type_integer">integer</a> gid);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Change the ownership of <em>file</em>. This function is only implemented on
POSIX systems where chown() is available in the underlying operating
system. An error is logged if the operation fails.</p>
</div>
</div>
</div>
</dd>
<dt class="hdlist1"><code>file_chown(<a href="#lang_type_string">string</a> file, <a href="#lang_type_string">string</a> user, <a href="#lang_type_string">string</a> group);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Change the ownership of <em>file</em>. This function is only implemented on
POSIX systems where chown() is available in the underlying operating
system. An error is logged if the operation fails.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_fileop_proc_file_copy" class="dlist">
<dl>
<dt class="hdlist1"><code>file_copy(<a href="#lang_type_string">string</a> src, <a href="#lang_type_string">string</a> dst);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Copy the file <em>src</em> to <em>dst</em>. If file <em>dst</em> already exists, its
contents will be overwritten. An error is logged if the operation
fails.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_fileop_proc_file_cycle" class="dlist">
<dl>
<dt class="hdlist1"><code>file_cycle(<a href="#lang_type_string">string</a> file);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Do a cyclic rotation on <em>file</em>. The <em>file</em> will be moved to
"<em>file</em>.1". If "<em>file</em>.1" already exists it will be moved to
"<em>file</em>.2", and so on. This procedure will reopen the LogFile if it is
cycled. An error is logged if the operation fails.</p>
</div>
</div>
</div>
</dd>
<dt class="hdlist1"><code>file_cycle(<a href="#lang_type_string">string</a> file, <a href="#lang_type_integer">integer</a> max);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Do a cyclic rotation on <em>file</em>. The <em>file</em> will be moved to
"<em>file</em>.1". If "<em>file</em>.1" already exists it will be moved to
"<em>file</em>.2", and so on. The <em>max</em> argument specifies the maximum number
of files to keep. For example, if <em>max</em> is <code>5</code>, "<em>file</em>.6" will be
deleted. This procedure will reopen the LogFile if it is cycled. An
error is logged if the operation fails.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_fileop_proc_file_link" class="dlist">
<dl>
<dt class="hdlist1"><code>file_link(<a href="#lang_type_string">string</a> src, <a href="#lang_type_string">string</a> dst);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Create a hardlink from <em>src</em> to <em>dst</em>. An error is logged if the
operation fails.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_fileop_proc_file_remove" class="dlist">
<dl>
<dt class="hdlist1"><code>file_remove(<a href="#lang_type_string">string</a> file);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Remove <em>file</em>. It is possible to specify a wildcard in the filename
(but not in the path). The backslash (<code>\</code>) must be escaped if used as
the directory separator with wildcards (for example,
<code>C:\\test\\*.log</code>). This procedure will reopen the LogFile if it is
removed. An error is logged if the operation fails.</p>
</div>
</div>
</div>
</dd>
<dt class="hdlist1"><code>file_remove(<a href="#lang_type_string">string</a> file, <a href="#lang_type_datetime">datetime</a> older);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Remove <em>file</em> if its creation time is older than the value specified
in <em>older</em>. It is possible to specify a wildcard in the filename (but
not in the path). The backslash (<code>\</code>) must be escaped if used as the
directory separator with wildcards (for example,
<code>C:\\test\\*.log</code>). This procedure will reopen the LogFile if it is
removed. An error is logged if the operation fails.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_fileop_proc_file_rename" class="dlist">
<dl>
<dt class="hdlist1"><code>file_rename(<a href="#lang_type_string">string</a> old, <a href="#lang_type_string">string</a> new);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Rename the file <em>old</em> to <em>new</em>. If the file <em>new</em> exists, it will be
overwritten. Moving files or directories across devices may not be
possible. This procedure will reopen the LogFile if it is renamed. An
error is logged if the operation fails.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_fileop_proc_file_touch" class="dlist">
<dl>
<dt class="hdlist1"><code>file_touch(<a href="#lang_type_string">string</a> file);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Update the last modification time of <em>file</em> or create the <em>file</em> if it
does not exist. An error is logged if the operation fails.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_fileop_proc_file_truncate" class="dlist">
<dl>
<dt class="hdlist1"><code>file_truncate(<a href="#lang_type_string">string</a> file);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Truncate <em>file</em> to zero length. If the <em>file</em> does not exist, it will
be created. An error is logged if the operation fails.</p>
</div>
</div>
</div>
</dd>
<dt class="hdlist1"><code>file_truncate(<a href="#lang_type_string">string</a> file, <a href="#lang_type_integer">integer</a> offset);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Truncate <em>file</em> to the size specified in <em>offset</em>. If the <em>file</em> does
not exist, it will be created. An error is logged if the operation
fails.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_fileop_proc_file_write" class="dlist">
<dl>
<dt class="hdlist1"><code>file_write(<a href="#lang_type_string">string</a> file, <a href="#lang_type_string">string</a> value);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Write <em>value</em> into <em>file</em>. The <em>file</em> will be created if it does not
exist. An error is logged if the operation fails.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="xm_fileop_config_examples"><a class="anchor" href="#xm_fileop_config_examples"></a>4.4.4. Examples</h4>
<div id="xm_fileop_example1" class="exampleblock">
<div class="title">Example 52. Rotation of the Internal LogFile</div>
<div class="content">
<div class="paragraph">
<p>In this example, the internal log file is rotated based on time and
size.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
</pre></td>
  <td class="code"><pre>#define LOGFILE C:\Program Files (x86)\nxlog\data\nxlog.log
define LOGFILE /var/log/nxlog/nxlog.log

<span class="tag">&lt;Extension</span> <span class="attribute-name">fileop</span><span class="tag">&gt;</span>
    Module      xm_fileop

    # Check the log file size every hour and rotate if larger than 1 MB
    <span class="tag">&lt;Schedule&gt;</span>
        Every   1 hour
        Exec    if (file_size('%LOGFILE%') <span class="error">&gt;</span>= 1M) file_cycle('%LOGFILE%', 2);
    <span class="tag">&lt;/Schedule&gt;</span>

    # Rotate log file every week on Sunday at midnight
    <span class="tag">&lt;Schedule&gt;</span>
        When    @weekly
        Exec    file_cycle('%LOGFILE%', 2);
    <span class="tag">&lt;/Schedule&gt;</span>
<span class="tag">&lt;/Extension&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="xm_gelf"><a class="anchor" href="#xm_gelf"></a>4.5. GELF (xm_gelf)</h3>
<div class="paragraph">
<p>This module provides an output writer function which can be used to
generate output in Graylog Extended Log Format (GELF) for
<a href="http://graylog2.org">Graylog2</a> or GELF compliant tools.</p>
</div>
<div class="paragraph">
<p>Unlike Syslog format (with Snare Agent, for example), the GELF format
contains structured data in JSON so that the fields are available for
analysis. This is especially convenient with sources such as the
Windows EventLog which already generate logs in a structured format.</p>
</div>
<div class="paragraph">
<p>The <em>xm_gelf</em> module provides the following output writer functions:</p>
</div>
<div id="xm_gelf_outputtype_gelf_tcp" class="dlist">
<dl>
<dt class="hdlist1">OutputType GELF_TCP</dt>
<dd>
<p>This output writer generates GELF for use with
TCP (use with the <a href="#om_tcp">om_tcp</a> output module).</p>
</dd>
</dl>
</div>
<div id="xm_gelf_outputtype_gelf_udp" class="dlist">
<dl>
<dt class="hdlist1">OutputType GELF_UDP</dt>
<dd>
<p>This output writer generates GELF for use with
UDP (use with the <a href="#om_udp">om_udp</a> output module).</p>
</dd>
</dl>
</div>
<div id="xm_gelf_outputtype_gelf" class="dlist">
<dl>
<dt class="hdlist1">OutputType GELF</dt>
<dd>
<p>This type is equivalent to <code>GELF_UDP</code>.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>The <a href="http://docs.graylog.org/en/2.1/pages/gelf.html">GELF</a> output
generated by this module includes all fields, except for the
$raw_event field and any field having a leading dot (<code>.</code>) or
underscore (<code>_</code>).</p>
</div>
<div class="paragraph">
<p>Configure NXLog to output GELF formatted data by following
these steps:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Load the <em>xm_gelf</em> module:</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">_gelf</span><span class="tag">&gt;</span>
    Module      xm_gelf
<span class="tag">&lt;/Extension&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</li>
<li>
<p>Set the <a href="#config_outputtype">OutputType</a> to <code>GELF_UDP</code> in the
<a href="#om_udp">om_udp</a> output module:</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Output</span> <span class="attribute-name">out_udp</span><span class="tag">&gt;</span>
    Module      om_udp
    Host        127.0.0.1
    Port        12201
    OutputType  GELF_UDP
<span class="tag">&lt;/Output&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
<div class="paragraph">
<p>Or, for <a href="#om_tcp">om_tcp</a>, use <code>GELF_TCP</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Output</span> <span class="attribute-name">out_tcp</span><span class="tag">&gt;</span>
    Module      om_tcp
    Host        127.0.0.1
    Port        12201
    OutputType  GELF_TCP
<span class="tag">&lt;/Output&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</li>
</ol>
</div>
<div class="sect3">
<h4 id="xm_gelf_config"><a class="anchor" href="#xm_gelf_config"></a>4.5.1. Configuration</h4>
<div class="paragraph">
<p>The <em>xm_gelf</em> module accepts the following directives in addition to the
<a href="#config_module_common">common module directives</a>.</p>
</div>
<div id="xm_gelf_config_shortmessagelength" class="dlist">
<dl>
<dt class="hdlist1">ShortMessageLength</dt>
<dd>
<p>This optional directive can be used to specify
the length of the <em>short_message</em> field. This defaults to 64 if the
directive is not explicitly specified. If the field <em>short_message</em>
or <em>ShortMessage</em> is present, it will not be truncated.</p>
</dd>
</dl>
</div>
<div id="xm_gelf_config_usenulldelimiter" class="dlist">
<dl>
<dt class="hdlist1">UseNullDelimiter</dt>
<dd>
<p>If this optional boolean directive is TRUE,
<code>GELF_TCP</code> will use the NUL delimiter. If this directive is FALSE,
it will use the newline delimiter. The default is TRUE.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="xm_gelf_config_examples"><a class="anchor" href="#xm_gelf_config_examples"></a>4.5.2. Examples</h4>
<div id="xm_gelf_example1" class="exampleblock">
<div class="title">Example 53. Sending Windows EventLog to Graylog2 in GELF</div>
<div class="content">
<div class="paragraph">
<p>The following configuration reads the Windows EventLog and sends it to
a Graylog2 server in GELF format.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">gelf</span><span class="tag">&gt;</span>
    Module      xm_gelf
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">eventlog</span><span class="tag">&gt;</span>
    # Use 'im_mseventlog' for Windows XP, 2000 and 2003
    Module      im_msvistalog
    # Uncomment the following to collect specific event logs only
    #Query  <span class="tag">&lt;QueryList&gt;</span>\
    #           <span class="tag">&lt;Query</span> <span class="attribute-name">Id</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>\
    #               <span class="tag">&lt;Select</span> <span class="attribute-name">Path</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">Application</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>*<span class="tag">&lt;/Select&gt;</span>\
    #               <span class="tag">&lt;Select</span> <span class="attribute-name">Path</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">System</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>*<span class="tag">&lt;/Select&gt;</span>\
    #               <span class="tag">&lt;Select</span> <span class="attribute-name">Path</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">Security</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>*<span class="tag">&lt;/Select&gt;</span>\
    #           <span class="tag">&lt;/Query&gt;</span>\
    #       <span class="tag">&lt;/QueryList&gt;</span>
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">udp</span><span class="tag">&gt;</span>
    Module      om_udp
    Host        192.168.1.1
    Port        12201
    OutputType  GELF
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">eventlog_to_udp</span><span class="tag">&gt;</span>
    Path        eventlog =<span class="error">&gt;</span> udp
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
<div id="xm_gelf_example_file" class="exampleblock">
<div class="title">Example 54. Forwarding Custom Log Files to Graylog2 in GELF</div>
<div class="content">
<div class="paragraph">
<p>In this example, custom application logs are collected and sent out in
GELF, with custom fields set to make the data more useful for the
receiver.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">gelf</span><span class="tag">&gt;</span>
    Module      xm_gelf
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">file</span><span class="tag">&gt;</span>
    Module      im_file
    File        &quot;/var/log/app*.log&quot;

    <span class="tag">&lt;Exec&gt;</span>
        # Set the $EventTime field usually found in the logs by
        # extracting it with a regexp. If this is not set, the current
        # system time will be used which might be a little off.
        if $raw_event =~ /(\d\d\d\d\-\d\d-\d\d \d\d:\d\d:\d\d)/
            $EventTime = parsedate($1);

        # Explicitly set the Hostname. This defaults to the system's
        # hostname if unset.
        $Hostname = 'myhost';

        # Now set the severity level to something custom. This defaults
        # to 'INFO' if unset. We can use the following numeric values
        # here which are the standard Syslog values: ALERT: 1, CRITICAL:
        # 2, ERROR: 3, WARNING: 4, NOTICE: 5, INFO: 6, DEBUG: 7
        if $raw_event =~ /ERROR/ $SyslogSeverityValue = 3;
        else $SyslogSeverityValue = 6;

        # Set a field to contain the name of the source file
        $FileName = file_name();

        # To set a custom message, use the $Message field. The
        # $raw_event field is used if $Message is unset.
        if $raw_event =~ /something important/
            $Message = 'IMPORTANT!! ' + $raw_event;
    <span class="tag">&lt;/Exec&gt;</span>
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">udp</span><span class="tag">&gt;</span>
    Module      om_udp
    Host        192.168.1.1
    Port        12201
    OutputType  GELF
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">file_to_gelf</span><span class="tag">&gt;</span>
    Path        file =<span class="error">&gt;</span> udp
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
<div id="xm_gelf_example_csv" class="exampleblock">
<div class="title">Example 55. Parsing a CSV File and Sending it to Graylog2 in GELF</div>
<div class="content">
<div class="paragraph">
<p>With this configuration, NXLog will read a CSV file containing
three fields and forward the data in GELF so that the fields will be
available on the server.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">gelf</span><span class="tag">&gt;</span>
    Module      xm_gelf
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Extension</span> <span class="attribute-name">csv</span><span class="tag">&gt;</span>
    Module      xm_csv
    Fields      $name, $number, $location
    FieldTypes  string, integer, string
    Delimiter   ,
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">file</span><span class="tag">&gt;</span>
    Module      im_file
    File        &quot;/var/log/app/csv.log&quot;
    Exec        csv-<span class="error">&gt;</span>parse_csv();
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">udp</span><span class="tag">&gt;</span>
    Module      om_udp
    Host        192.168.1.1
    Port        12201
    OutputType  GELF
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">csv_to_gelf</span><span class="tag">&gt;</span>
    Path        file =<span class="error">&gt;</span> udp
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="xm_json"><a class="anchor" href="#xm_json"></a>4.6. JSON (xm_json)</h3>
<div class="paragraph">
<p>This module provides functions and procedures for processing data
formatted as <a href="http://json.org">JSON</a>. JSON can be generated from log
data, or JSON can be parsed into
<a href="#lang_fields">fields</a>. Unfortunately, the JSON specification does not
define a type for datetime values so these are represented as JSON
strings. The JSON parser in <em>xm_json</em> can automatically detect datetime
values, so it is not necessary to explicitly use
<a href="#core_func_parsedate">parsedate()</a>.</p>
</div>
<div class="sect3">
<h4 id="xm_json_config"><a class="anchor" href="#xm_json_config"></a>4.6.1. Configuration</h4>
<div class="paragraph">
<p>The <em>xm_json</em> module accepts only the <a href="#config_module_common">common
module directives</a>.</p>
</div>
</div>
<div class="sect3">
<h4 id="xm_json_funcs"><a class="anchor" href="#xm_json_funcs"></a>4.6.2. Functions</h4>
<div class="paragraph">
<p>The following functions are exported by <em>xm_json</em>.</p>
</div>
<div id="xm_json_func_to_json" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_string">string</a> <code>to_json()</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Convert the fields to JSON and return this as a string value.  The
<code>$raw_event</code> field and any field having a leading dot (<code>.</code>) or
underscore (<code>_</code>) will be automatically excluded.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="xm_json_procs"><a class="anchor" href="#xm_json_procs"></a>4.6.3. Procedures</h4>
<div class="paragraph">
<p>The following procedures are exported by <em>xm_json</em>.</p>
</div>
<div id="xm_json_proc_parse_json" class="dlist">
<dl>
<dt class="hdlist1"><code>parse_json();</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Parse the <code>$raw_event</code> field as JSON input.</p>
</div>
</div>
</div>
</dd>
<dt class="hdlist1"><code>parse_json(<a href="#lang_type_string">string</a> source);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Parse the given string as JSON format.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_json_proc_to_json" class="dlist">
<dl>
<dt class="hdlist1"><code>to_json();</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Convert the fields to JSON and put this into the <code>$raw_event</code>
field. The <code>$raw_event</code> field and any field having a leading dot (<code>.</code>)
or underscore (<code>_</code>) will be automatically excluded.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="xm_json_config_examples"><a class="anchor" href="#xm_json_config_examples"></a>4.6.4. Examples</h4>
<div id="xm_json_example1" class="exampleblock">
<div class="title">Example 56. Syslog to JSON Format Conversion</div>
<div class="content">
<div class="paragraph">
<p>The following configuration accepts Syslog (both BSD and IETF) via TCP
and converts it to JSON.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">syslog</span><span class="tag">&gt;</span>
    Module  xm_syslog
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Extension</span> <span class="attribute-name">json</span><span class="tag">&gt;</span>
    Module  xm_json
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">tcp</span><span class="tag">&gt;</span>
    Module  im_tcp
    Port    1514
    Host    0.0.0.0
    Exec    parse_syslog(); to_json();
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">file</span><span class="tag">&gt;</span>
    Module  om_file
    File    &quot;/var/log/json.txt&quot;
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">tcp_to_file</span><span class="tag">&gt;</span>
    Path    tcp =<span class="error">&gt;</span> file
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">Input Sample</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="log">&lt;30&gt;Sep 30 15:45:43 host44.localdomain.hu acpid: 1 client rule loaded<span class="line-marker"></span></code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">Output Sample</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="json">{
  <span class="key"><span class="delimiter">&quot;</span><span class="content">MessageSourceAddress</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">127.0.0.1</span><span class="delimiter">&quot;</span></span>,
  <span class="key"><span class="delimiter">&quot;</span><span class="content">EventReceivedTime</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">2011-03-08 14:22:41</span><span class="delimiter">&quot;</span></span>,
  <span class="key"><span class="delimiter">&quot;</span><span class="content">SyslogFacilityValue</span><span class="delimiter">&quot;</span></span>:<span class="integer">1</span>,
  <span class="key"><span class="delimiter">&quot;</span><span class="content">SyslogFacility</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">DAEMON</span><span class="delimiter">&quot;</span></span>,
  <span class="key"><span class="delimiter">&quot;</span><span class="content">SyslogSeverityValue</span><span class="delimiter">&quot;</span></span>:<span class="integer">5</span>,
  <span class="key"><span class="delimiter">&quot;</span><span class="content">SyslogSeverity</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">INFO</span><span class="delimiter">&quot;</span></span>,
  <span class="key"><span class="delimiter">&quot;</span><span class="content">SeverityValue</span><span class="delimiter">&quot;</span></span>:<span class="integer">2</span>,
  <span class="key"><span class="delimiter">&quot;</span><span class="content">Severity</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">INFO</span><span class="delimiter">&quot;</span></span>,
  <span class="key"><span class="delimiter">&quot;</span><span class="content">Hostname</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">host44.localdomain.hu</span><span class="delimiter">&quot;</span></span>,
  <span class="key"><span class="delimiter">&quot;</span><span class="content">EventTime</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">2011-09-30 14:45:43</span><span class="delimiter">&quot;</span></span>,
  <span class="key"><span class="delimiter">&quot;</span><span class="content">SourceName</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">acpid</span><span class="delimiter">&quot;</span></span>,
  <span class="key"><span class="delimiter">&quot;</span><span class="content">Message</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">1 client rule loaded </span><span class="delimiter">&quot;</span></span>
}</code></pre>
</div>
</div>
</div>
</div>
<div id="xm_json_example2" class="exampleblock">
<div class="title">Example 57. Converting Windows EventLog to Syslog-Encapsulated JSON</div>
<div class="content">
<div class="paragraph">
<p>The following configuration reads the Windows EventLog and converts it
to the BSD Syslog format, with the message part containing the fields
in JSON.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">syslog</span><span class="tag">&gt;</span>
    Module      xm_syslog
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Extension</span> <span class="attribute-name">json</span><span class="tag">&gt;</span>
    Module      xm_json
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">eventlog</span><span class="tag">&gt;</span>
    Module      im_msvistalog
    Exec        $Message = to_json(); to_syslog_bsd();
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">tcp</span><span class="tag">&gt;</span>
    Module      om_tcp
    Host        192.168.1.1
    Port        1514
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">eventlog_json_tcp</span><span class="tag">&gt;</span>
    Path        eventlog =<span class="error">&gt;</span> tcp
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">Output Sample</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="log">&lt;14&gt;Mar  8 14:40:11 WIN-OUNNPISDHIG Service_Control_Manager: {&quot;EventTime&quot;:&quot;2012-03-08 14:40:11&quot;,&quot;EventTimeWritten&quot;:&quot;2012-03-08 14:40:11&quot;,&quot;Hostname&quot;:&quot;WIN-OUNNPISDHIG&quot;,&quot;EventType&quot;:&quot;INFO&quot;,&quot;SeverityValue&quot;:2,&quot;Severity&quot;:&quot;INFO&quot;,&quot;SourceName&quot;:&quot;Service Control Manager&quot;,&quot;FileName&quot;:&quot;System&quot;,&quot;EventID&quot;:7036,&quot;CategoryNumber&quot;:0,&quot;RecordNumber&quot;:6788,&quot;Message&quot;:&quot;The nxlog service entered the running state. &quot;,&quot;EventReceivedTime&quot;:&quot;2012-03-08 14:40:12&quot;}<span class="line-marker"></span></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="xm_kvp"><a class="anchor" href="#xm_kvp"></a>4.7. Key-Value Pairs (xm_kvp)</h3>
<div class="paragraph">
<p>This module provides functions and procedures for processing data
formatted as key-value pairs (KVPs), also commonly called "name-value
pairs". The module can both parse and generate key-value formatted
data.</p>
</div>
<div class="paragraph">
<p>It is quite common to have a different set of keys in each log line
when accepting key-value formatted input messages. Extracting values
from such logs using regular expressions can be quite cumbersome. The
<em>xm_kvp</em> extension module automates this process.</p>
</div>
<div class="paragraph">
<p>Log messages containing key-value pairs typically look like one the
following:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>key1: value1, key2: value2, key42: value42</code></p>
</li>
<li>
<p><code>key1="value 1"; key2="value 2"</code></p>
</li>
<li>
<p><code>Application=smtp, Event='Protocol Conversation', status='Client
Request', ClientRequest='HELO 1.2.3.4'</code></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Keys are usually separated from the value using an equal sign (<code>=</code>) or
a colon (<code>:</code>); and the key-value pairs are delimited with a comma
(<code>,</code>), a semicolon (<code>;</code>), or a space. In addition, values and keys may
be quoted and may contain escaping. The module will try to guess the
format, or the format can be explicitly specified using the
configuration directives below.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
It is possible to use more than one <em>xm_kvp</em> module instance with
      different options in order to support different KVP formats at
      the same time. For this reason, functions and procedures
      exported by the module are public and must be referenced by the
      module instance name.
</td>
</tr>
</table>
</div>
<div class="sect3">
<h4 id="xm_kvp_config"><a class="anchor" href="#xm_kvp_config"></a>4.7.1. Configuration</h4>
<div class="paragraph">
<p>The <em>xm_kvp</em> module accepts the following directives in addition to the
<a href="#config_module_common">common module directives</a>.</p>
</div>
<div id="xm_kvp_config_escapechar" class="dlist">
<dl>
<dt class="hdlist1">EscapeChar</dt>
<dd>
<p>This optional directive takes a single character (see
<a href="#xm_kvp_config_char">below</a>) as argument. It specifies the
character used for escaping special characters. The escape character
is used to prefix the following characters: the <strong>EscapeChar</strong> itself,
the <a href="#xm_kvp_config_keyquotechar">KeyQuoteChar</a>, and the
<a href="#xm_kvp_config_valuequotechar">ValueQuoteChar</a>. If
<a href="#xm_kvp_config_escapecontrol">EscapeControl</a> is TRUE, the newline
(<code>\n</code>), carriage return (<code>\r</code>), tab (<code>\t</code>), and backspace (<code>\b</code>)
control characters are also escaped. The default escape character is
the backslash (<code>\</code>).</p>
</dd>
</dl>
</div>
<div id="xm_kvp_config_escapecontrol" class="dlist">
<dl>
<dt class="hdlist1">EscapeControl</dt>
<dd>
<p>If this optional boolean directive is set to TRUE,
control characters are also escaped. See the
<a href="#xm_kvp_config_escapechar">EscapeChar</a> directive for details. The
default is TRUE (control characters are escaped). Note that this is
necessary in order to support single-line KVP field lists containing
line-breaks.</p>
</dd>
</dl>
</div>
<div id="xm_kvp_config_keyquotechar" class="dlist">
<dl>
<dt class="hdlist1">KeyQuoteChar</dt>
<dd>
<p>This optional directive takes a single character (see
<a href="#xm_kvp_config_char">below</a>) as argument. It specifies the
quote character for enclosing key names. If this directive is not
specified, the module will accept single-quoted keys, double-quoted
keys, and unquoted keys.</p>
</dd>
</dl>
</div>
<div id="xm_kvp_config_kvdelimiter" class="dlist">
<dl>
<dt class="hdlist1">KVDelimiter</dt>
<dd>
<p>This optional directive takes a single character (see
<a href="#xm_kvp_config_char">below</a>) as argument. It specifies the
delimiter character used to separate the key from the value. If this
directive is not set and the <a href="#xm_kvp_proc_parse_kvp">parse_kvp()</a>
procedure is used, the module will try to guess the delimiter from
the following: the colon (<code>:</code>) or the equal-sign (<code>=</code>).</p>
</dd>
</dl>
</div>
<div id="xm_kvp_config_kvpdelimiter" class="dlist">
<dl>
<dt class="hdlist1">KVPDelimiter</dt>
<dd>
<p>This optional directive takes a single character (see
<a href="#xm_kvp_config_char">below</a>) as argument. It specifies the
delimiter character used to separate the key-value pairs. If this
directive is not set and the <a href="#xm_kvp_proc_parse_kvp">parse_kvp()</a>
procedure is used, the module will try to guess the delimiter from
the following: the comma (<code>,</code>), the semicolon (<code>;</code>), or the space.</p>
</dd>
</dl>
</div>
<div id="xm_kvp_config_valuequotechar" class="dlist">
<dl>
<dt class="hdlist1">ValueQuoteChar</dt>
<dd>
<p>This optional directive takes a single character (see
<a href="#xm_kvp_config_char">below</a>) as argument. It specifies the
quote character for enclosing key values. If this directive is not
specified, the module will accept single-quoted values,
double-quoted values, and unquoted values. Normally, quotation is
used when the value contains a space or the
<a href="#xm_kvp_config_kvdelimiter">KVDelimiter</a> character.</p>
</dd>
</dl>
</div>
<div class="sect4">
<h5 id="xm_kvp_config_char"><a class="anchor" href="#xm_kvp_config_char"></a>4.7.1.1. Specifying Quote, Escape, and Delimiter Characters</h5>
<div class="paragraph">
<p>The <a href="#xm_kvp_config_keyquotechar">KeyQuoteChar</a>,
<a href="#xm_kvp_config_valuequotechar">ValueQuoteChar</a>,
<a href="#xm_kvp_config_escapechar">EscapeChar</a>,
<a href="#xm_kvp_config_kvdelimiter">KVDelimiter</a>, and
<a href="#xm_kvp_config_kvpdelimiter">KVPDelimiter</a> directives can be
specified in several ways.</p>
</div>
<div id="xm_kvp_config_char_single" class="dlist">
<dl>
<dt class="hdlist1">Unquoted single character</dt>
<dd>
<p>Any printable character can be specified
as an unquoted character, except for the backslash (<code>\</code>):</p>
<div class="listingblock">
<div class="content">
<pre>Delimiter ;</pre>
</div>
</div>
</dd>
</dl>
</div>
<div id="'xm_kvp_config_char_control" class="dlist">
<dl>
<dt class="hdlist1">Control characters</dt>
<dd>
<p>The following non-printable characters can be
specified with escape sequences:</p>
<div class="openblock">
<div class="content">
<div class="dlist">
<dl>
<dt class="hdlist1">\a</dt>
<dd>
<p>audible alert (bell)</p>
</dd>
<dt class="hdlist1">\b</dt>
<dd>
<p>backspace</p>
</dd>
<dt class="hdlist1">\t</dt>
<dd>
<p>horizontal tab</p>
</dd>
<dt class="hdlist1">\n</dt>
<dd>
<p>newline</p>
</dd>
<dt class="hdlist1">\v</dt>
<dd>
<p>vertical tab</p>
</dd>
<dt class="hdlist1">\f</dt>
<dd>
<p>formfeed</p>
</dd>
<dt class="hdlist1">\r</dt>
<dd>
<p>carriage return</p>
</dd>
</dl>
</div>
</div>
</div>
<div class="paragraph">
<p>For example, to use TAB delimiting:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Delimiter \t</pre>
</div>
</div>
</dd>
</dl>
</div>
<div id="'xm_kvp_config_char_single_quote" class="dlist">
<dl>
<dt class="hdlist1">A character in single quotes</dt>
<dd>
<p>The configuration parser strips
whitespace, so it is not possible to define a space as the delimiter
unless it is enclosed within quotes:</p>
<div class="listingblock">
<div class="content">
<pre>Delimiter ' '</pre>
</div>
</div>
<div class="paragraph">
<p>Printable characters can also be enclosed:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Delimiter ';'</pre>
</div>
</div>
<div class="paragraph">
<p>The backslash can be specified when enclosed within quotes:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Delimiter '\'</pre>
</div>
</div>
</dd>
</dl>
</div>
<div id="'xm_kvp_config_char_double_quote" class="dlist">
<dl>
<dt class="hdlist1">A character in double quotes</dt>
<dd>
<p>Double quotes can be used like single
quotes:</p>
<div class="listingblock">
<div class="content">
<pre>Delimiter " "</pre>
</div>
</div>
<div class="paragraph">
<p>The backslash can be specified when enclosed within double quotes:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Delimiter "\"</pre>
</div>
</div>
</dd>
</dl>
</div>
<div id="'xm_kvp_config_char_hex_code" class="dlist">
<dl>
<dt class="hdlist1">A hexadecimal ASCII code</dt>
<dd>
<p>Hexadecimal ASCII character codes can also
be used by prepending <code>0x</code>. For example, the space can be specified
as:</p>
<div class="listingblock">
<div class="content">
<pre>Delimiter 0x20</pre>
</div>
</div>
<div class="paragraph">
<p>This is equivalent to:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Delimiter " "</pre>
</div>
</div>
</dd>
</dl>
</div>
</div>
</div>
<div class="sect3">
<h4 id="xm_kvp_funcs"><a class="anchor" href="#xm_kvp_funcs"></a>4.7.2. Functions</h4>
<div class="paragraph">
<p>The following functions are exported by <em>xm_kvp</em>.</p>
</div>
<div id="xm_kvp_func_to_kvp" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_string">string</a> <code>to_kvp()</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Convert the internal fields to a single key-value pair
     formatted string.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="xm_kvp_procs"><a class="anchor" href="#xm_kvp_procs"></a>4.7.3. Procedures</h4>
<div class="paragraph">
<p>The following procedures are exported by <em>xm_kvp</em>.</p>
</div>
<div id="xm_kvp_proc_parse_kvp" class="dlist">
<dl>
<dt class="hdlist1"><code>parse_kvp();</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Parse the <code>$raw_event</code> field as key-value pairs and populate
     the internal fields using the key names.</p>
</div>
</div>
</div>
</dd>
<dt class="hdlist1"><code>parse_kvp(<a href="#lang_type_string">string</a> source);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Parse the given string key-value pairs and populate the
     internal fields using the key names.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_kvp_proc_reset_kvp" class="dlist">
<dl>
<dt class="hdlist1"><code>reset_kvp();</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Reset the KVP parser so that the autodetected
     <a href="#xm_kvp_config_keyquotechar">KeyQuoteChar</a>,
     <a href="#xm_kvp_config_valuequotechar">ValueQuoteChar</a>,
     <a href="#xm_kvp_config_kvdelimiter">KVDelimiter</a>, and
     <a href="#xm_kvp_config_kvpdelimiter">KVPDelimiter</a>
     characters can be detected again.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_kvp_proc_to_kvp" class="dlist">
<dl>
<dt class="hdlist1"><code>to_kvp();</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Format the internal fields as key-value pairs and put this
     into the <code>$raw_event</code> field.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="xm_kvp_config_examples"><a class="anchor" href="#xm_kvp_config_examples"></a>4.7.4. Examples</h4>
<div class="paragraph">
<p>The following examples illustrate various scenarios for parsing KVPs,
whether embedded, encapsulated (in Syslog, for example), or alone. In
each case, the logs are converted from KVP input files to JSON output
files, though obviously there are many other possibilities.</p>
</div>
<div id="xm_kvp_example_simple" class="exampleblock">
<div class="title">Example 58. Simple KVP Parsing</div>
<div class="content">
<div class="paragraph">
<p>The following two lines of input are in a simple KVP format where each
line consists of various keys with values assigned to them.</p>
</div>
<div class="listingblock">
<div class="title">Input Sample</div>
<div class="content">
<pre>Name=John, Age=42, Weight=84, Height=142
Name=Mike, Weight=64, Age=24, Pet=dog, Height=172</pre>
</div>
</div>
<div class="paragraph">
<p>This input can be parsed with the following configuration. The parsed
fields can be used in NXLog expressions: a new field named
<code>$Overweight</code> is added and set to TRUE if the conditions
are met. Finally a few automatically added fields are removed, and the
log is then converted to JSON.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">kvp</span><span class="tag">&gt;</span>
    Module          xm_kvp
    KVPDelimiter    ,
    KVDelimiter     =
    EscapeChar      \\
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Extension</span> <span class="attribute-name">json</span><span class="tag">&gt;</span>
    Module          xm_json
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">filein</span><span class="tag">&gt;</span>
    Module          im_file
    File            &quot;modules/extension/kvp/xm_kvp5.in&quot;
    <span class="tag">&lt;Exec&gt;</span>
        if $raw_event =~ /^#/ drop();
        else
        {
            kvp-<span class="error">&gt;</span>parse_kvp();
            delete($EventReceivedTime);
            delete($SourceModuleName);
            delete($SourceModuleType);
            if ( integer($Weight) <span class="error">&gt;</span> integer($Height) - 100 ) $Overweight = TRUE;
            to_json();
        }
    <span class="tag">&lt;/Exec&gt;</span>
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">fileout</span><span class="tag">&gt;</span>
    Module          om_file
    File            'tmp/output'
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">parse_kvp</span><span class="tag">&gt;</span>
    Path            filein =<span class="error">&gt;</span> fileout
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">Output Sample</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="json">{<span class="key"><span class="delimiter">&quot;</span><span class="content">Name</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">John</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">Age</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">42</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">Weight</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">84</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">Height</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">142</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">Overweight</span><span class="delimiter">&quot;</span></span>:<span class="value">true</span>}
{<span class="key"><span class="delimiter">&quot;</span><span class="content">Name</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">Mike</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">Weight</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">64</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">Age</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">24</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">Pet</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">dog</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">Height</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">172</span><span class="delimiter">&quot;</span></span>}</code></pre>
</div>
</div>
</div>
</div>
<div id="xm_kvp_example_cisco_acs" class="exampleblock">
<div class="title">Example 59. Parsing KVPs in Cisco ACS Syslog</div>
<div class="content">
<div class="paragraph">
<p>The following lines are from a Cisco ACS source.</p>
</div>
<div class="listingblock">
<div class="title">Input Sample</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="log">&lt;38&gt;2010-10-12 21:01:29 10.0.1.1 CisACS_02_FailedAuth 1k1fg93nk 1 0 Message-Type=Authen failed,User-Name=John,NAS-IP-Address=10.0.1.2,AAA Server=acs01<span class="line-marker"></span>
&lt;38&gt;2010-10-12 21:01:31 10.0.1.1 CisACS_02_FailedAuth 2k1fg63nk 1 0 Message-Type=Authen failed,User-Name=Foo,NAS-IP-Address=10.0.1.2,AAA Server=acs01<span class="line-marker"></span></code></pre>
</div>
</div>
<div class="paragraph">
<p>These logs are in Syslog format with a set of values present in each
record and an additional set of KVPs. The following configuration can
be used to process this and convert it to JSON.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">json</span><span class="tag">&gt;</span>
    Module          xm_json
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Extension</span> <span class="attribute-name">syslog</span><span class="tag">&gt;</span>
    Module          xm_syslog
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Extension</span> <span class="attribute-name">kvp</span><span class="tag">&gt;</span>
    Module          xm_kvp
    KVDelimiter     =
    KVPDelimiter    ,
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">cisco</span><span class="tag">&gt;</span>
    Module          im_file
    File            &quot;modules/extension/kvp/cisco_acs.in&quot;
    <span class="tag">&lt;Exec&gt;</span>
        parse_syslog_bsd();
        if ( $Message =~ /^CisACS_(\d\d)_(\S+) (\S+) (\d+) (\d+) (.*)$/ )
        {
            $ACSCategoryNumber = $1;
            $ACSCategoryName = $2;
            $ACSMessageId = $3;
            $ACSTotalSegments = $4;
            $ACSSegmentNumber = $5;
            $Message = $6;
            kvp-<span class="error">&gt;</span>parse_kvp($Message);
        }
        else log_warning(&quot;does not match: &quot; + to_json());
    <span class="tag">&lt;/Exec&gt;</span>
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">file</span><span class="tag">&gt;</span>
    Module          om_file
    File            &quot;tmp/output&quot;
    Exec            delete($EventReceivedTime);
    Exec            to_json();
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">cisco_to_file</span><span class="tag">&gt;</span>
    Path            cisco =<span class="error">&gt;</span> file
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">Output Sample</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="json">{<span class="key"><span class="delimiter">&quot;</span><span class="content">SourceModuleName</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">cisco</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">SourceModuleType</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">im_file</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">SyslogFacilityValue</span><span class="delimiter">&quot;</span></span>:<span class="integer">4</span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">SyslogFacility</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">AUTH</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">SyslogSeverityValue</span><span class="delimiter">&quot;</span></span>:<span class="integer">6</span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">SyslogSeverity</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">INFO</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">SeverityValue</span><span class="delimiter">&quot;</span></span>:<span class="integer">2</span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">Severity</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">INFO</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">Hostname</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">10.0.1.1</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">EventTime</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">2010-10-12 21:01:29</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">Message</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">Message-Type=Authen failed,User-Name=John,NAS-IP-Address=10.0.1.2,AAA Server=acs01</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">ACSCategoryNumber</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">02</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">ACSCategoryName</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">FailedAuth</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">ACSMessageId</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">1k1fg93nk</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">ACSTotalSegments</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">1</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">ACSSegmentNumber</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">0</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">Message-Type</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">Authen failed</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">User-Name</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">John</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">NAS-IP-Address</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">10.0.1.2</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">AAA Server</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">acs01</span><span class="delimiter">&quot;</span></span>}
{<span class="key"><span class="delimiter">&quot;</span><span class="content">SourceModuleName</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">cisco</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">SourceModuleType</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">im_file</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">SyslogFacilityValue</span><span class="delimiter">&quot;</span></span>:<span class="integer">4</span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">SyslogFacility</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">AUTH</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">SyslogSeverityValue</span><span class="delimiter">&quot;</span></span>:<span class="integer">6</span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">SyslogSeverity</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">INFO</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">SeverityValue</span><span class="delimiter">&quot;</span></span>:<span class="integer">2</span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">Severity</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">INFO</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">Hostname</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">10.0.1.1</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">EventTime</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">2010-10-12 21:01:31</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">Message</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">Message-Type=Authen failed,User-Name=Foo,NAS-IP-Address=10.0.1.2,AAA Server=acs01</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">ACSCategoryNumber</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">02</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">ACSCategoryName</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">FailedAuth</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">ACSMessageId</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">2k1fg63nk</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">ACSTotalSegments</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">1</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">ACSSegmentNumber</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">0</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">Message-Type</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">Authen failed</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">User-Name</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">Foo</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">NAS-IP-Address</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">10.0.1.2</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">AAA Server</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">acs01</span><span class="delimiter">&quot;</span></span>}</code></pre>
</div>
</div>
</div>
</div>
<div id="xm_kvp_example_sidewinder" class="exampleblock">
<div class="title">Example 60. Parsing KVPs in Sidewinder Logs</div>
<div class="content">
<div class="paragraph">
<p>The following line is from a Sidewinder log source.</p>
</div>
<div class="listingblock">
<div class="title">Input Sample</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="log">date=&quot;May 5 14:34:40 2009 MDT&quot;,fac=f_mail_filter,area=a_kmvfilter,type=t_mimevirus_reject,pri=p_major,pid=10174,ruid=0,euid=0,pgid=10174,logid=0,cmd=kmvfilter,domain=MMF1,edomain=MMF1,message_id=(null),srcip=66.74.184.9,mail_sender=&lt;habuzeid6@…&gt;,virus_name=W32/Netsky.c@MM!zip,reason=&quot;Message scan detected a Virus in msg Unknown, message being Discarded, and not quarantined&quot;<span class="line-marker"></span></code></pre>
</div>
</div>
<div class="paragraph">
<p>This can be parsed and converted to JSON with the following
configuration.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">kvp</span><span class="tag">&gt;</span>
    Module          xm_kvp
    KVPDelimiter    ,
    KVDelimiter     =
    EscapeChar      \\
    ValueQuoteChar  &quot;
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Extension</span> <span class="attribute-name">json</span><span class="tag">&gt;</span>
    Module          xm_json
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">sidewinder</span><span class="tag">&gt;</span>
    Module          im_file
    File            &quot;modules/extension/kvp/sidewinder.in&quot;
    Exec            kvp-<span class="error">&gt;</span>parse_kvp(); delete($EventReceivedTime); to_json();
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">file</span><span class="tag">&gt;</span>
    Module          om_file
    File            'tmp/output'
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">sidewinder_to_file</span><span class="tag">&gt;</span>
    Path            sidewinder =<span class="error">&gt;</span> file
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">Output Sample</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="json">{<span class="key"><span class="delimiter">&quot;</span><span class="content">SourceModuleName</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">sidewinder</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">SourceModuleType</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">im_file</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">date</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">May 5 14:34:40 2009 MDT</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">fac</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">f_mail_filter</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">area</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">a_kmvfilter</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">type</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">t_mimevirus_reject</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">pri</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">p_major</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">pid</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">10174</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">ruid</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">0</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">euid</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">0</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">pgid</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">10174</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">logid</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">0</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">cmd</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">kmvfilter</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">domain</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">MMF1</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">edomain</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">MMF1</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">message_id</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">(null)</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">srcip</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">66.74.184.9</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">mail_sender</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">&lt;habuzeid6@…&gt;</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">virus_name</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">W32/Netsky.c@MM!zip</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">reason</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">Message scan detected a Virus in msg Unknown, message being Discarded, and not quarantined</span><span class="delimiter">&quot;</span></span>}</code></pre>
</div>
</div>
</div>
</div>
<div id="xm_kvp_example_apache_url" class="exampleblock">
<div class="title">Example 61. Parsing URL Request Parameters in Apache Access Logs</div>
<div class="content">
<div class="paragraph">
<p>URLs in HTTP requests frequently contain URL parameters which are a
special kind of key-value pairs delimited by the ampersand (<code>&amp;</code>). Here
is an example of two HTTP requests logged by the Apache web server in
the Combined Log Format.</p>
</div>
<div class="listingblock">
<div class="title">Input Sample</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="log">192.168.1.1 - foo [11/Jun/2013:15:44:34 +0200] &quot;GET /do?action=view&amp;obj_id=2 HTTP/1.1&quot; 200 1514 &quot;https://localhost&quot; &quot;Mozilla/5.0 (X11; Linux x86_64; rv:17.0) Gecko/17.0 Firefox/17.0&quot;<span class="line-marker"></span>
192.168.1.1 - - [11/Jun/2013:15:44:44 +0200] &quot;GET /do?action=delete&amp;obj_id=42 HTTP/1.1&quot; 401 788 &quot;https://localhost&quot; &quot;Mozilla/5.0 (X11; Linux x86_64; rv:17.0) Gecko/17.0 Firefox/17.0&quot;<span class="line-marker"></span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The following configuration file parses the access log and extracts
all the fields. The request parameters are extracted into the
$HTTPParams field using a regular expression, and then this field is
further parsed using the KVP parser. At the end of the processing all
fields are converted to KVP format using the
<a href="#xm_kvp_proc_to_kvp">to_kvp()</a> procedure of the <em>kvp2</em> instance.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">kvp</span><span class="tag">&gt;</span>
    Module          xm_kvp
    KVPDelimiter    <span class="error">&amp;</span>
    KVDelimiter     =
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Extension</span> <span class="attribute-name">kvp2</span><span class="tag">&gt;</span>
    Module          xm_kvp
    KVPDelimiter    ;
    KVDelimiter     =
    #QuoteMethod    None
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">apache</span><span class="tag">&gt;</span>
    Module          im_file
    File            &quot;modules/extension/kvp/apache_url.in&quot;
    <span class="tag">&lt;Exec&gt;</span>
        if $raw_event =~ /(?x)^(\S+)\ (\S+)\ (\S+)\ \[([^\]]+)\]\ \&quot;(\S+)\ (.+)
                          \ HTTP.\d\.\d\&quot;\ (\d+)\ (\d+)\ \&quot;([^\&quot;]+)\&quot;\ \&quot;([^\&quot;]+)\&quot;/
        {
            $Hostname = $1;
            if $3 != '-' $AccountName = $3;
            $EventTime = parsedate($4);
            $HTTPMethod = $5;
            $HTTPURL = $6;
            $HTTPResponseStatus = $7;
            $FileSize = $8;
            $HTTPReferer = $9;
            $HTTPUserAgent = $10;
            if $HTTPURL =~ /\?(.+)/ { $HTTPParams = $1; }
            kvp-<span class="error">&gt;</span>parse_kvp($HTTPParams);
            delete($EventReceivedTime);
            kvp2-<span class="error">&gt;</span>to_kvp();
        }
    <span class="tag">&lt;/Exec&gt;</span>
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">file</span><span class="tag">&gt;</span>
    Module          om_file
    File            'tmp/output'
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">apache_to_file</span><span class="tag">&gt;</span>
    Path            apache =<span class="error">&gt;</span> file
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
<div class="paragraph">
<p>The two request parameters <em>action</em> and <em>obj_id</em> then appear at the end
of the KVP formatted lines.</p>
</div>
<div class="listingblock">
<div class="title">Output Sample</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="log">SourceModuleName=apache;SourceModuleType=im_file;Hostname=192.168.1.1;AccountName=foo;EventTime=2013-06-11 15:44:34;HTTPMethod=GET;HTTPURL=/do?action=view&amp;obj_id=2;HTTPResponseStatus=200;FileSize=1514;HTTPReferer=https://localhost;HTTPUserAgent='Mozilla/5.0 (X11; Linux x86_64; rv:17.0) Gecko/17.0 Firefox/17.0';HTTPParams=action=view&amp;obj_id=2;action=view;obj_id=2;<span class="line-marker"></span>
SourceModuleName=apache;SourceModuleType=im_file;Hostname=192.168.1.1;EventTime=2013-06-11 15:44:44;HTTPMethod=GET;HTTPURL=/do?action=delete&amp;obj_id=42;HTTPResponseStatus=401;FileSize=788;HTTPReferer=https://localhost;HTTPUserAgent='Mozilla/5.0 (X11; Linux x86_64; rv:17.0) Gecko/17.0 Firefox/17.0';HTTPParams=action=delete&amp;obj_id=42;action=delete;obj_id=42;<span class="line-marker"></span></code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
URL escaping is not handled.
</td>
</tr>
</table>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="xm_multiline"><a class="anchor" href="#xm_multiline"></a>4.8. Multi-Line Parser (xm_multiline)</h3>
<div class="paragraph">
<p>This module can be used for parsing log messages that span multiple lines. All
lines in an event are joined to form a single NXLog event record,
which can be further processed as required. Each multi-line event is detected
through some combination of header lines, footer lines, and fixed line counts,
as configured. The name of the <em>xm_multiline</em> module instance is specified by
the input module&#8217;s <a href="#config_inputtype">InputType</a> directive.</p>
</div>
<div class="paragraph">
<p>The module maintains a separate context for each input source, allowing
multi-line messages to be processed correctly even when coming from multiple
sources (specifically, multiple files or multiple network connections).</p>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<div class="title">Warning</div>
</td>
<td class="content">
UDP is treated as a single source and all logs are processed under
         the same context. It is therefore not recommended to use this module
         with <a href="#im_udp">im_udp</a> if messages will be received by multiple UDP
         senders (such as Syslog).
</td>
</tr>
</table>
</div>
<div class="sect3">
<h4 id="xm_multiline_config"><a class="anchor" href="#xm_multiline_config"></a>4.8.1. Configuration</h4>
<div class="paragraph">
<p>The <em>xm_multiline</em> module accepts the following directives in addition
to the <a href="#config_module_common">common module directives</a>. One of
<a href="#xm_multiline_config_fixedlinecount">FixedLineCount</a> and
<a href="#xm_multiline_config_headerline">HeaderLine</a> must be specified.</p>
</div>
<div id="xm_multiline_config_fixedlinecount" class="dlist">
<dl>
<dt class="hdlist1">FixedLineCount</dt>
<dd>
<p>This directive takes a positive integer number
defining the number of lines to concatenate. This is useful
when receiving log messages spanning a fixed number of lines. When this number
is defined, the module knows where the event message ends and will
not hold a message in the buffers until the next message arrives.</p>
</dd>
</dl>
</div>
<div id="xm_multiline_config_headerline" class="dlist">
<dl>
<dt class="hdlist1">HeaderLine</dt>
<dd>
<p>This directive takes a <a href="#lang_literal_string">string</a> or
a <a href="#lang_regexp">regular expression</a> literal. This will be matched
against each line. When the match is successful, the successive
lines are appended until the next header line is read. This
directive is mandatory unless
<a href="#xm_multiline_config_fixedlinecount">FixedLineCount</a> is used.</p>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
Until a new message arrives with its associated header, the
      previous message is stored in the buffers because the module
      does not know where the message ends. The <a href="#im_file">im_file</a>
      module will forcibly flush this buffer after the configured
      <a href="#im_file_config_pollinterval">PollInterval</a> timeout. If this
      behavior is unacceptable,
      use an end marker with <a href="#xm_multiline_config_endline">EndLine</a>
      or switch to an encapsulation method (such as JSON).
</td>
</tr>
</table>
</div>
</dd>
</dl>
</div>
<hr>
<div id="xm_multiline_config_endline" class="dlist">
<dl>
<dt class="hdlist1">EndLine</dt>
<dd>
<p>This is similar to the
<a href="#xm_multiline_config_headerline">HeaderLine</a> directive. This
optional directive also takes a <a href="#lang_literal_string">string</a> or a
<a href="#lang_regexp">regular expression</a> literal to be matched against
each line. When the match is successful the message is considered
complete.</p>
</dd>
</dl>
</div>
<div id="xm_multiline_config_exec" class="dlist">
<dl>
<dt class="hdlist1">Exec</dt>
<dd>
<p>This directive is almost identical to the behavior of the
<a href="#config_module_exec">Exec</a> directive used by the other modules with
the following differences:</p>
<div class="openblock">
<div class="content">
<div class="ulist">
<ul>
<li>
<p>each line is passed in <code>$raw_event</code> as it is read, and the line
terminator in included; and</p>
</li>
<li>
<p>other fields cannot be used, and captured strings can not be stored
as separate fields.</p>
</li>
</ul>
</div>
</div>
</div>
<div class="paragraph">
<p>This is mostly useful for rewriting lines or filtering out certain
lines with the <a href="#core_proc_drop">drop()</a> procedure.</p>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="xm_multiline_config_examples"><a class="anchor" href="#xm_multiline_config_examples"></a>4.8.2. Examples</h4>
<div id="xm_multiline_example_5" class="exampleblock">
<div class="title">Example 62. Parsing multi-line XML logs and converting to JSON</div>
<div class="content">
<div class="paragraph">
<p>XML is commonly formatted as indented multi-line to make it more
readable. In the following configuration file the
<a href="#xm_multiline_config_headerline">HeaderLine</a> and
<a href="#xm_multiline_config_endline">EndLine</a> directives are used to parse
the events. The events are then converted to JSON after some timestamp
normalization.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">multiline</span><span class="tag">&gt;</span>
    Module          xm_multiline
    HeaderLine      /^<span class="tag">&lt;event&gt;</span>/
    EndLine         /^<span class="tag">&lt;/event&gt;</span>/
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Extension</span> <span class="attribute-name">xmlparser</span><span class="tag">&gt;</span>
    Module          xm_xml
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Extension</span> <span class="attribute-name">json</span><span class="tag">&gt;</span>
    Module          xm_json
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">filein</span><span class="tag">&gt;</span>
    Module          im_file
    File            &quot;modules/extension/multiline/xm_multiline5.in&quot;
    InputType       multiline
    <span class="tag">&lt;Exec&gt;</span>
        # Discard everything that doesn't seem to be an xml event
        if $raw_event !~ /^<span class="tag">&lt;event&gt;</span>/ drop();

        # Parse the xml event
        parse_xml();

        # Rewrite some fields
        $EventTime = parsedate($timestamp);
        delete($timestamp);
        delete($EventReceivedTime);

        # Convert to JSON
        to_json();
    <span class="tag">&lt;/Exec&gt;</span>
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">fileout</span><span class="tag">&gt;</span>
    Module          om_file
    File            'tmp/output'
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">parse_xml</span><span class="tag">&gt;</span>
    Path            filein =<span class="error">&gt;</span> fileout
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">Input Sample</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="xml"><span class="preprocessor">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;&gt;
&lt;event&gt;
  &lt;timestamp&gt;2012-11-23 23:00:00&lt;/timestamp&gt;
  &lt;severity&gt;ERROR&lt;/severity&gt;
  &lt;message&gt;
    Something bad happened.
    Please check the system.
  &lt;/message&gt;
&lt;/event&gt;
&lt;event&gt;
  &lt;timestamp&gt;2012-11-23 23:00:12&lt;/timestamp&gt;
  &lt;severity&gt;INFO&lt;/severity&gt;
  &lt;message&gt;
   System state is now back to normal.
  &lt;/message&gt;
&lt;/event&gt;</span></code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">Output Sample</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="json">{<span class="key"><span class="delimiter">&quot;</span><span class="content">SourceModuleName</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">filein</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">SourceModuleType</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">im_file</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">severity</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">ERROR</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">message</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="char">\n</span><span class="content">    Something bad happened.</span><span class="char">\n</span><span class="content">    Please check the system.</span><span class="char">\n</span><span class="content">  </span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">EventTime</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">2012-11-23 23:00:00</span><span class="delimiter">&quot;</span></span>}
{<span class="key"><span class="delimiter">&quot;</span><span class="content">SourceModuleName</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">filein</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">SourceModuleType</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">im_file</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">severity</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">INFO</span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">message</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="char">\n</span><span class="content">   System state is now back to normal.</span><span class="char">\n</span><span class="content">  </span><span class="delimiter">&quot;</span></span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">EventTime</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">2012-11-23 23:00:12</span><span class="delimiter">&quot;</span></span>}</code></pre>
</div>
</div>
</div>
</div>
<div id="xm_multiline_example_4" class="exampleblock">
<div class="title">Example 63. Parsing DICOM Logs</div>
<div class="content">
<div class="paragraph">
<p>Each log message has a header (TIMESTAMP INTEGER SEVERITY) which is
used as the message boundary. A regular expression is defined for this
with the <a href="#xm_multiline_config_headerline">HeaderLine</a> directive. Each
log message is prepended with an additional line containing dashes and
is written to a file.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">dicom_multi</span><span class="tag">&gt;</span>
    Module          xm_multiline
    HeaderLine      /^\d\d\d\d-\d\d-\d\d\d\d:\d\d:\d\d\.\d+\s+\d+\s+\S+\s+/
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">filein</span><span class="tag">&gt;</span>
    Module          im_file
    File            &quot;modules/extension/multiline/xm_multiline4.in&quot;
    InputType       dicom_multi
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">fileout</span><span class="tag">&gt;</span>
    Module          om_file
    File            'tmp/output'
    Exec    $raw_event = &quot;--------------------------------------\n&quot; + $raw_event;
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">parse_dicom</span><span class="tag">&gt;</span>
    Path            filein =<span class="error">&gt;</span> fileout
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">Input Sample</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="log">2011-12-1512:22:51.000000  4296   INFO   Association Request Parameters:<span class="line-marker"></span>
Our Implementation Class UID:    2.16.124.113543.6021.2<span class="line-marker"></span>
Our Implementation Version Name: RZDCX_2_0_1_8<span class="line-marker"></span>
Their Implementation Class UID:<span class="line-marker"></span>
Their Implementation Version Name:<span class="line-marker"></span>
Application Context Name:    1.2.840.10008.3.1.1.1<span class="line-marker"></span>
Requested Extended Negotiation: none<span class="line-marker"></span>
Accepted Extended Negotiation: none<span class="line-marker"></span>
2011-12-1512:22:51.000000  4296   DEBUG  Constructing Associate RQ PDU<span class="line-marker"></span>
2011-12-1512:22:51.000000  4296   DEBUG  WriteToConnection, length: 310, bytes written: 310, loop no: 1<span class="line-marker"></span>
2011-12-1512:22:51.015000  4296   DEBUG  PDU Type: Associate Accept, PDU Length: 216 + 6 bytes PDU header<span class="line-marker"></span>
  02  00  00  00  00  d8  00  01  00  00  50  41  43  53  20  20<span class="line-marker"></span>
  20  20  20  20  20  20  20  20  20  20  52  5a  44  43  58  20<span class="line-marker"></span>
  20  20  20  20  20  20  20  20  20  20  00  00  00  00  00  00<span class="line-marker"></span>
2011-12-1512:22:51.031000  4296   DEBUG  DIMSE sendDcmDataset: sending 146 bytes<span class="line-marker"></span></code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">Output Sample</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="log">--------------------------------------<span class="line-marker"></span>
2011-12-1512:22:51.000000  4296   INFO   Association Request Parameters:<span class="line-marker"></span>
Our Implementation Class UID:    2.16.124.113543.6021.2<span class="line-marker"></span>
Our Implementation Version Name: RZDCX_2_0_1_8<span class="line-marker"></span>
Their Implementation Class UID:<span class="line-marker"></span>
Their Implementation Version Name:<span class="line-marker"></span>
Application Context Name:    1.2.840.10008.3.1.1.1<span class="line-marker"></span>
Requested Extended Negotiation: none<span class="line-marker"></span>
Accepted Extended Negotiation: none<span class="line-marker"></span>
--------------------------------------<span class="line-marker"></span>
2011-12-1512:22:51.000000  4296   DEBUG  Constructing Associate RQ PDU<span class="line-marker"></span>
--------------------------------------<span class="line-marker"></span>
2011-12-1512:22:51.000000  4296   DEBUG  WriteToConnection, length: 310, bytes written: 310, loop no: 1<span class="line-marker"></span>
--------------------------------------<span class="line-marker"></span>
2011-12-1512:22:51.015000  4296   DEBUG  PDU Type: Associate Accept, PDU Length: 216 + 6 bytes PDU header<span class="line-marker"></span>
  02  00  00  00  00  d8  00  01  00  00  50  41  43  53  20  20<span class="line-marker"></span>
  20  20  20  20  20  20  20  20  20  20  52  5a  44  43  58  20<span class="line-marker"></span>
  20  20  20  20  20  20  20  20  20  20  00  00  00  00  00  00<span class="line-marker"></span>
--------------------------------------<span class="line-marker"></span>
2011-12-1512:22:51.031000  4296   DEBUG  DIMSE sendDcmDataset: sending 146 bytes<span class="line-marker"></span></code></pre>
</div>
</div>
</div>
</div>
<div id="xm_multiline_example_1" class="exampleblock">
<div class="title">Example 64. Multi-line messages with a fixed string header</div>
<div class="content">
<div class="paragraph">
<p>The following configuration will process messages having a fixed
string header containing dashes. Each event is then prepended with a
hash mark (<code>#</code>) and written to a file.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">multiline</span><span class="tag">&gt;</span>
    Module          xm_multiline
    HeaderLine      &quot;---------------&quot;
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">filein</span><span class="tag">&gt;</span>
    Module          im_file
    File            &quot;modules/extension/multiline/xm_multiline1.in&quot;
    InputType       multiline
    Exec            $raw_event = &quot;#&quot; + $raw_event;
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">fileout</span><span class="tag">&gt;</span>
    Module          om_file
    File            'tmp/output'
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">parse_multiline</span><span class="tag">&gt;</span>
    Path            filein =<span class="error">&gt;</span> fileout
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">Input Sample</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="log">---------------<span class="line-marker"></span>
1<span class="line-marker"></span>
---------------<span class="line-marker"></span>
1<span class="line-marker"></span>
2<span class="line-marker"></span>
---------------<span class="line-marker"></span>
aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa<span class="line-marker"></span>
bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb<span class="line-marker"></span>
ccccccccccccccccccccccccccccccccccccc<span class="line-marker"></span>
dddd<span class="line-marker"></span>
---------------<span class="line-marker"></span></code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">Output Sample</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="log">#---------------<span class="line-marker"></span>
1<span class="line-marker"></span>
#---------------<span class="line-marker"></span>
1<span class="line-marker"></span>
2<span class="line-marker"></span>
#---------------<span class="line-marker"></span>
aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa<span class="line-marker"></span>
bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb<span class="line-marker"></span>
ccccccccccccccccccccccccccccccccccccc<span class="line-marker"></span>
dddd<span class="line-marker"></span>
#---------------<span class="line-marker"></span></code></pre>
</div>
</div>
</div>
</div>
<div id="xm_multiline_example_2" class="exampleblock">
<div class="title">Example 65. Multi-line messages with fixed line count</div>
<div class="content">
<div class="paragraph">
<p>The following configuration will process messages having a fixed line
count of four. Lines containing only whitespace are ignored and
removed. Each event is then prepended with a hash mark (<code>#</code>) and
written to a file.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">multiline</span><span class="tag">&gt;</span>
    Module          xm_multiline
    FixedLineCount  4
    Exec            if $raw_event =~ /^\s*$/ drop();
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">filein</span><span class="tag">&gt;</span>
    Module          im_file
    File            &quot;modules/extension/multiline/xm_multiline2.in&quot;
    InputType       multiline
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">fileout</span><span class="tag">&gt;</span>
    Module          om_file
    File            'tmp/output'
    Exec            $raw_event = &quot;#&quot; + $raw_event;
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">parse_multiline</span><span class="tag">&gt;</span>
    Path            filein =<span class="error">&gt;</span> fileout
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">Input Sample</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="log">1<span class="line-marker"></span>
2<span class="line-marker"></span>
3<span class="line-marker"></span>
4<span class="line-marker"></span>
1asd<span class="line-marker"></span>
<span class="line-marker"></span>
2asdassad<span class="line-marker"></span>
3ewrwerew<span class="line-marker"></span>
4xcbccvbc<span class="line-marker"></span>
<span class="line-marker"></span>
1dsfsdfsd<span class="line-marker"></span>
2sfsdfsdrewrwe<span class="line-marker"></span>
<span class="line-marker"></span>
3sdfsdfsew<span class="line-marker"></span>
4werwerwrwe<span class="line-marker"></span></code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">Output Sample</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="log">#1<span class="line-marker"></span>
2<span class="line-marker"></span>
3<span class="line-marker"></span>
4<span class="line-marker"></span>
#1asd<span class="line-marker"></span>
2asdassad<span class="line-marker"></span>
3ewrwerew<span class="line-marker"></span>
4xcbccvbc<span class="line-marker"></span>
#1dsfsdfsd<span class="line-marker"></span>
2sfsdfsdrewrwe<span class="line-marker"></span>
3sdfsdfsew<span class="line-marker"></span>
4werwerwrwe<span class="line-marker"></span></code></pre>
</div>
</div>
</div>
</div>
<div id="xm_multiline_example_3" class="exampleblock">
<div class="title">Example 66. Multi-line messages with a Syslog header</div>
<div class="content">
<div class="paragraph">
<p>Often, multi-line messages are logged over Syslog and each line is
processed as an event, with its own Syslog header. It is commonly
necessary to merge these back into a single event message.</p>
</div>
<div class="listingblock">
<div class="title">Input Sample</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="log">Nov 21 11:40:27 hostname app[26459]: Iface   MTU Met   RX-OK RX-ERR RX-DRP RX-OVR    TX-OK TX-ERR TX-DRP TX-OVR Flg<span class="line-marker"></span>
Nov 21 11:40:27 hostname app[26459]: eth2       1500 0  16936814      0      0 0      30486067      0      8      0 BMRU<span class="line-marker"></span>
Nov 21 11:40:27 hostname app[26459]: lo        16436 0  277217234      0      0 0      277217234      0      0      0 LRU<span class="line-marker"></span>
Nov 21 11:40:27 hostname app[26459]: tun0       1500 0    316943      0      0 0        368642      0      0      0 MOPRU<span class="line-marker"></span>
Nov 21 11:40:28 hostname app[26459]: Iface   MTU Met   RX-OK RX-ERR RX-DRP RX-OVR    TX-OK TX-ERR TX-DRP TX-OVR Flg<span class="line-marker"></span>
Nov 21 11:40:28 hostname app[26459]: eth2       1500 0  16945117      0      0 0      30493583      0      8      0 BMRU<span class="line-marker"></span>
Nov 21 11:40:28 hostname app[26459]: lo        16436 0  277217234      0      0 0      277217234      0      0      0 LRU<span class="line-marker"></span>
Nov 21 11:40:28 hostname app[26459]: tun0       1500 0    316943      0      0 0        368642      0      0      0 MOPRU<span class="line-marker"></span>
Nov 21 11:40:29 hostname app[26459]: Iface   MTU Met   RX-OK RX-ERR RX-DRP RX-OVR    TX-OK TX-ERR TX-DRP TX-OVR Flg<span class="line-marker"></span>
Nov 21 11:40:29 hostname app[26459]: eth2       1500 0  16945270      0      0 0      30493735      0      8      0 BMRU<span class="line-marker"></span>
Nov 21 11:40:29 hostname app[26459]: lo        16436 0  277217234      0      0 0      277217234      0      0      0 LRU<span class="line-marker"></span>
Nov 21 11:40:29 hostname app[26459]: tun0       1500 0    316943      0      0 0        368642      0      0      0 MOPRU<span class="line-marker"></span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The following configuration strips the Syslog header from the netstat
output stored in the traditional Syslog formatted file, and each
message is then printed again with a line of dashes used as a
separator.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">syslog</span><span class="tag">&gt;</span>
    Module          xm_syslog
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Extension</span> <span class="attribute-name">netstat</span><span class="tag">&gt;</span>
    Module          xm_multiline
    FixedLineCount  4
    <span class="tag">&lt;Exec&gt;</span>
        parse_syslog_bsd();
        $raw_event = $Message + &quot;\n&quot;;
    <span class="tag">&lt;/Exec&gt;</span>
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">filein</span><span class="tag">&gt;</span>
    Module          im_file
    File            &quot;modules/extension/multiline/xm_multiline3.in&quot;
    InputType       netstat
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">fileout</span><span class="tag">&gt;</span>
    Module          om_file
    File            'tmp/output'
    <span class="tag">&lt;Exec&gt;</span>
        $raw_event = &quot;-------------------------------------------------------&quot; +
                     &quot;-----------------------------\n&quot; + $raw_event;
    <span class="tag">&lt;/Exec&gt;</span>
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">parse_multiline</span><span class="tag">&gt;</span>
    Path            filein =<span class="error">&gt;</span> fileout
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">Output Sample</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="log">------------------------------------------------------------------------------------<span class="line-marker"></span>
Iface   MTU Met   RX-OK RX-ERR RX-DRP RX-OVR    TX-OK TX-ERR TX-DRP TX-OVR Flg<span class="line-marker"></span>
eth2       1500 0  16936814      0      0 0      30486067      0      8      0 BMRU<span class="line-marker"></span>
lo        16436 0  277217234      0      0 0      277217234      0      0      0 LRU<span class="line-marker"></span>
tun0       1500 0    316943      0      0 0        368642      0      0      0 MOPRU<span class="line-marker"></span>
------------------------------------------------------------------------------------<span class="line-marker"></span>
Iface   MTU Met   RX-OK RX-ERR RX-DRP RX-OVR    TX-OK TX-ERR TX-DRP TX-OVR Flg<span class="line-marker"></span>
eth2       1500 0  16945117      0      0 0      30493583      0      8      0 BMRU<span class="line-marker"></span>
lo        16436 0  277217234      0      0 0      277217234      0      0      0 LRU<span class="line-marker"></span>
tun0       1500 0    316943      0      0 0        368642      0      0      0 MOPRU<span class="line-marker"></span>
------------------------------------------------------------------------------------<span class="line-marker"></span>
Iface   MTU Met   RX-OK RX-ERR RX-DRP RX-OVR    TX-OK TX-ERR TX-DRP TX-OVR Flg<span class="line-marker"></span>
eth2       1500 0  16945270      0      0 0      30493735      0      8      0 BMRU<span class="line-marker"></span>
lo        16436 0  277217234      0      0 0      277217234      0      0      0 LRU<span class="line-marker"></span>
tun0       1500 0    316943      0      0 0        368642      0      0      0 MOPRU<span class="line-marker"></span></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="xm_perl"><a class="anchor" href="#xm_perl"></a>4.9. Perl (xm_perl)</h3>
<div class="paragraph">
<p>The <a href="http://perl.org">Perl programming language</a> is widely used for log
processing and comes with a broad set of modules bundled or available
from <a href="http://cpan.org">CPAN</a>. Code can be written more quickly in Perl
than in C, and code execution is safer because exceptions (croak/die)
are handled properly and will only result in an unfinished attempt at
log processing rather than taking down the whole NXLog
process.</p>
</div>
<div class="paragraph">
<p>While the <a href="#ref-lang">NXLog language</a> is already a powerful
framework, it is not intended to be a fully featured programming
language and does not provide lists, arrays, hashes, and other features
available in many high-level languages. With this module, Perl can be
used to process event data via a built-in Perl interpreter.</p>
</div>
<div class="paragraph">
<p>The Perl interpreter is only loaded if the module is declared in the
configuration. The module will parse the file specified in the
<a href="#xm_perl_config_perlcode">PerlCode</a> directive when NXLog
starts the module. This file should contain one or more methods
which can be called from the <a href="#config_module_exec">Exec</a> directive of
any module that will use Perl for log processing. See the
<a href="#xm_perl_config_examples">example</a> below.</p>
</div>
<div class="paragraph">
<p>To access event data, the Log::Nxlog module must be included, which provides
the following methods.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">log_debug(msg)</dt>
<dd>
<p>Send the message <em>msg</em> to the internal logger on
DEBUG log level. This method does the same as the
<a href="#core_proc_log_debug">log_debug()</a> procedure in NXLog.</p>
</dd>
<dt class="hdlist1">log_info(msg)</dt>
<dd>
<p>Send the message <em>msg</em> to the internal logger on INFO
log level. This method does the same as the
<a href="#core_proc_log_info">log_info()</a> procedure in NXLog.</p>
</dd>
<dt class="hdlist1">log_warning(msg)</dt>
<dd>
<p>Send the message <em>msg</em> to the internal logger on
WARNING log level. This method does the same as the
<a href="#core_proc_log_warning">log_warning()</a> procedure in NXLog.</p>
</dd>
<dt class="hdlist1">log_error(msg)</dt>
<dd>
<p>Send the message <em>msg</em> to the internal logger on
ERROR log level. This method does the same as the
<a href="#core_proc_log_error">log_error()</a> procedure in NXLog.</p>
</dd>
</dl>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">delete_field(event, key)</dt>
<dd>
<p>Delete the value associated with the field
named <em>key</em>.</p>
</dd>
<dt class="hdlist1">field_names(event)</dt>
<dd>
<p>Return a list of the field names contained in the
event data. This method can be used to iterate over all of the
fields.</p>
</dd>
<dt class="hdlist1">field_type(event, key)</dt>
<dd>
<p>Return a string representing the type of the
value associated with the field named <em>key</em>.</p>
</dd>
<dt class="hdlist1">get_field(event, key)</dt>
<dd>
<p>Retrieve the value associated with the field
named <em>key</em>. This method returns a scalar value if the key exists
and the value is defined, otherwise it returns undef.</p>
</dd>
<dt class="hdlist1">set_field_boolean(event, key, value)</dt>
<dd>
<p>Set the boolean value in the
field named <em>key</em>.</p>
</dd>
<dt class="hdlist1">set_field_integer(event, key, value)</dt>
<dd>
<p>Set the integer value in the
field named <em>key</em>.</p>
</dd>
<dt class="hdlist1">set_field_string(event, key, value)</dt>
<dd>
<p>Set the string value in the
field named <em>key</em>.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>For the full NXLog Perl API, see the POD documentation in
<code>Nxlog.pm</code>. The documentation can be read with <code>perldoc Log::Nxlog</code>.</p>
</div>
<div class="sect3">
<h4 id="xm_perl_config"><a class="anchor" href="#xm_perl_config"></a>4.9.1. Configuration</h4>
<div class="paragraph">
<p>The <em>xm_perl</em> module accepts the following directives in addition to the
<a href="#config_module_common">common module directives</a>.</p>
</div>
<div id="xm_perl_config_perlcode" class="dlist">
<dl>
<dt class="hdlist1">PerlCode</dt>
<dd>
<p>This mandatory directive expects a file containing valid
Perl code. This file is read and parsed by the Perl
interpreter. Methods defined in this file can be called with the
<a href="#xm_perl_proc_call">call()</a> procedure.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="xm_perl_procs"><a class="anchor" href="#xm_perl_procs"></a>4.9.2. Procedures</h4>
<div class="paragraph">
<p>The following procedures are exported by <em>xm_perl</em>.</p>
</div>
<div id="xm_perl_proc_call" class="dlist">
<dl>
<dt class="hdlist1"><code>call(<a href="#lang_type_string">string</a> subroutine);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Call the given Perl <em>subroutine</em>.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_perl_proc_perl_call" class="dlist">
<dl>
<dt class="hdlist1"><code>perl_call(<a href="#lang_type_string">string</a> subroutine);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Call the given Perl <em>subroutine</em>.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="xm_perl_config_examples"><a class="anchor" href="#xm_perl_config_examples"></a>4.9.3. Examples</h4>
<div id="xm_perl_example1" class="exampleblock">
<div class="title">Example 67. Using the built-in Perl interpreter</div>
<div class="content">
<div class="paragraph">
<p>In this example, logs are parsed as Syslog and then are passed to
a Perl method which does a GeoIP lookup on the source address of the
incoming message.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">syslog</span><span class="tag">&gt;</span>
    Module      xm_syslog
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Extension</span> <span class="attribute-name">perl</span><span class="tag">&gt;</span>
    Module      xm_perl
    PerlCode    modules/extension/perl/processlogs.pl
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">fileout</span><span class="tag">&gt;</span>
    Module      om_file
    File        'tmp/output'

    # First we parse the input natively from nxlog
    Exec        parse_syslog_bsd();

    # Now call the 'process' subroutine defined in 'processlogs.pl'
    Exec        perl_call(&quot;process&quot;);

    # You can also invoke this public procedure 'call' in case
    # of multiple xm_perl instances like this:
    # Exec      perl-<span class="error">&gt;</span>call(&quot;process&quot;);
<span class="tag">&lt;/Output&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">processlogs.pl</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="perl">use strict;
use warnings;

# Without Log::Nxlog you cannot access (read or modify) the event data
use Log::Nxlog;

use Geo::IP;

my $geoip;

BEGIN
{
    # This will be called once when nxlog starts so you can use this to
    # initialize stuff here
    $geoip = Geo::IP-&gt;new(GEOIP_MEMORY_CACHE);
}

# This is the method which is invoked from 'Exec' for each event
sub process
{
    # The event data is passed here when this method is invoked by the module
    my ( $event ) = @_;

    # We look up the county of the sender of the message
    my $msgsrcaddr = Log::Nxlog::get_field($event, 'MessageSourceAddress');
    if ( defined($msgsrcaddr) )
    {
        my $country = $geoip-&gt;country_code_by_addr($msgsrcaddr);
        $country = &quot;unknown&quot; unless ( defined($country) );
        Log::Nxlog::set_field_string($event, 'MessageSourceCountry', $country);
    }

    # Iterate over the fields
    foreach my $fname ( @{Log::Nxlog::field_names($event)} )
    {
        # Delete all fields except these
        if ( ! (($fname eq 'raw_event') ||
                ($fname eq 'AccountName') ||
                ($fname eq 'MessageSourceCountry')) )
        {
            Log::Nxlog::delete_field($event, $fname);
        }
    }

    # Check a field and rename it if it matches
    my $accountname = Log::Nxlog::get_field($event, 'AccountName');
    if ( defined($accountname) &amp;&amp; ($accountname eq 'John') )
    {
        Log::Nxlog::set_field_string($event, 'AccountName', 'johnny');
        Log::Nxlog::log_info('renamed john');
    }
}</code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="xm_syslog"><a class="anchor" href="#xm_syslog"></a>4.10. Syslog (xm_syslog)</h3>
<div class="paragraph">
<p>This module provides support for the legacy BSD Syslog protocol as
defined in RFC 3164 and the current IETF standard defined by RFCs
5424-5426. This is achieved by exporting functions and procedures
usable from the NXLog language. The transport is handled by
the respective input and output modules (such as <a href="#im_udp">im_udp</a>),
this module only provides a parser and helper functions to create
Syslog messages and handle facility and severity values.</p>
</div>
<div class="paragraph">
<p>The older but still widespread BSD Syslog standard defines both the
format and the transport protocol in RFC 3164. The transport protocol
is UDP, but to provide reliability and security, this line-based
format is also commonly transferred over TCP and SSL. There is a newer
standard defined in RFC 5424, also known as the IETF Syslog format,
which obsoletes the BSD Syslog format. This format overcomes most of
the limitations of BSD Syslog and allows multi-line messages and
proper timestamps. The transport method is defined in RFC 5426 for UDP
and RFC 5425 for TLS/SSL.</p>
</div>
<div class="paragraph">
<p>Because the IETF Syslog format supports multi-line messages, RFC 5425
defines a special format to encapsulate these by prepending the
payload size in ASCII to the IETF Syslog message. Messages transferred
in UDP packets are self-contained and do not need this additional
framing. The following input reader and output writer functions are
provided by the <em>xm_syslog</em> module to support this TLS transport defined
in RFC 5425.  While RFC 5425 explicitly defines that the TLS network
transport protocol is to be used, pure TCP may be used if security is
not a requirement. Syslog messages can also be written to file with
this framing format using these functions.</p>
</div>
<div id="xm_syslog_inputtype_syslog_tls" class="dlist">
<dl>
<dt class="hdlist1">InputType Syslog_TLS</dt>
<dd>
<p>This input reader function parses the payload
size and then reads the message according to this value. It is
required to support Syslog TLS transport defined in RFC 5425.</p>
</dd>
</dl>
</div>
<div id="xm_syslog_outputtype_syslog_tls" class="dlist">
<dl>
<dt class="hdlist1">OutputType Syslog_TLS</dt>
<dd>
<p>This output writer function prepends the
payload size to the message. It is required to support Syslog TLS
transport defined in RFC 5425.</p>
</dd>
</dl>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
The <em>Syslog_TLS</em> InputType/OutputType can work with any
      input/output such as <a href="#im_tcp">im_tcp</a> or <a href="#im_file">im_file</a>
      and does not depend on SSL transport at all. The name
      <em>Syslog_TLS</em> was chosen to refer to the octet-framing method
      described in RFC 5425 used for TLS transport.
</td>
</tr>
</table>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
The <a href="#pm_transformer">pm_transformer</a> module can also parse and
      create BSD and IETF Syslog messages, but the functions and
      procedures provided by this module make it possible to solve
      more complex tasks which <a href="#pm_transformer">pm_transformer</a> is
      not capable of on its own.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Structured data in IETF Syslog messages is parsed and put into
NXLog fields. The SD-ID will be prepended to the field name
with a dot unless it is <code>NXLOG@XXXX</code>. Consider the following Syslog
message:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="log">&lt;30&gt;1 2011-12-04T21:16:10.000000+02:00 host app procid msgid [exampleSDID@32473 eventSource=&quot;Application&quot; eventID=&quot;1011&quot;] Message part<span class="line-marker"></span></code></pre>
</div>
</div>
<div class="paragraph">
<p>After this IETF-formatted Syslog message is parsed with
<a href="#xm_syslog_proc_parse_syslog_ietf">parse_syslog_ietf()</a>, there will
be two additional fields: <code>$exampleSDID.eventID</code> and
<code>$exampleSDID.eventSource</code>. When SD-ID is <code>NXLOG</code>, the field name will
be the same as the SD-PARAM name. The two additional fields extracted
from the structured data part of the following IETF Syslog message are
<code>$eventID</code> and <code>$eventSource</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="log">&lt;30&gt;1 2011-12-04T21:16:10.000000+02:00 host app procid msgid [NXLOG@32473 eventSource=&quot;Application&quot; eventID=&quot;1011&quot;] Message part<span class="line-marker"></span></code></pre>
</div>
</div>
<div class="paragraph">
<p>All fields in the structured data part are parsed as
<a href="#lang_type_string">strings</a>.</p>
</div>
<div class="sect3">
<h4 id="xm_syslog_config"><a class="anchor" href="#xm_syslog_config"></a>4.10.1. Configuration</h4>
<div class="paragraph">
<p>The <em>xm_syslog</em> module accepts the following directives in addition to
the <a href="#config_module_common">common module directives</a>.</p>
</div>
<div id="xm_syslog_config_ietftimestampingmt" class="dlist">
<dl>
<dt class="hdlist1">IETFTimestampInGMT</dt>
<dd>
<p>This optional boolean directive can be used to
format the timestamps produced by
<a href="#xm_syslog_proc_to_syslog_ietf">to_syslog_ietf()</a> in UTC/GMT
instead of local time. The default is FALSE: local time is used with
a timezone indicator.</p>
</dd>
</dl>
</div>
<div id="xm_syslog_config_snaredelimiter" class="dlist">
<dl>
<dt class="hdlist1">SnareDelimiter</dt>
<dd>
<p>This optional directive takes a single character (see
<a href="#xm_syslog_config_char">below</a>) as argument. This character is used
by the <a href="#xm_syslog_proc_to_syslog_snare">to_syslog_snare()</a>
procedure to separate fields. If this directive is not specified,
the default escape character is the tab (<code>\t</code>). In latter versions
of Snare 4 this has changed to the hash mark (<code>#</code>); this directive
can be used to specify the alternative delimiter. Note that there is
no delimiter after the last field.</p>
</dd>
</dl>
</div>
<div id="xm_syslog_config_snarereplacement" class="dlist">
<dl>
<dt class="hdlist1">SnareReplacement</dt>
<dd>
<p>This optional directive takes a single character
(see <a href="#xm_syslog_config_char">below</a>) as argument. This character is
used by the <a href="#xm_syslog_proc_to_syslog_snare">to_syslog_snare()</a>
procedure to replace occurrences of the
<a href="#xm_syslog_config_snaredelimiter">delimiter</a> character inside the
<code>$Message</code> field. If this directive is not specified, the default
replacement character is the space.</p>
</dd>
</dl>
</div>
<div class="sect4">
<h5 id="xm_syslog_config_char"><a class="anchor" href="#xm_syslog_config_char"></a>4.10.1.1. Specifying Quote, Escape, and Delimiter Characters</h5>
<div class="paragraph">
<p>The <a href="#xm_syslog_config_snaredelimiter">SnareDelimiter</a> and
<a href="#xm_syslog_config_snarereplacement">SnareReplacement</a> directives can
be specified in several ways.</p>
</div>
<div id="xm_syslog_config_char_single" class="dlist">
<dl>
<dt class="hdlist1">Unquoted single character</dt>
<dd>
<p>Any printable character can be specified
as an unquoted character, except for the backslash (<code>\</code>):</p>
<div class="listingblock">
<div class="content">
<pre>Delimiter ;</pre>
</div>
</div>
</dd>
</dl>
</div>
<div id="'xm_syslog_config_char_control" class="dlist">
<dl>
<dt class="hdlist1">Control characters</dt>
<dd>
<p>The following non-printable characters can be
specified with escape sequences:</p>
<div class="openblock">
<div class="content">
<div class="dlist">
<dl>
<dt class="hdlist1">\a</dt>
<dd>
<p>audible alert (bell)</p>
</dd>
<dt class="hdlist1">\b</dt>
<dd>
<p>backspace</p>
</dd>
<dt class="hdlist1">\t</dt>
<dd>
<p>horizontal tab</p>
</dd>
<dt class="hdlist1">\n</dt>
<dd>
<p>newline</p>
</dd>
<dt class="hdlist1">\v</dt>
<dd>
<p>vertical tab</p>
</dd>
<dt class="hdlist1">\f</dt>
<dd>
<p>formfeed</p>
</dd>
<dt class="hdlist1">\r</dt>
<dd>
<p>carriage return</p>
</dd>
</dl>
</div>
</div>
</div>
<div class="paragraph">
<p>For example, to use TAB delimiting:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Delimiter \t</pre>
</div>
</div>
</dd>
</dl>
</div>
<div id="'xm_syslog_config_char_single_quote" class="dlist">
<dl>
<dt class="hdlist1">A character in single quotes</dt>
<dd>
<p>The configuration parser strips
whitespace, so it is not possible to define a space as the delimiter
unless it is enclosed within quotes:</p>
<div class="listingblock">
<div class="content">
<pre>Delimiter ' '</pre>
</div>
</div>
<div class="paragraph">
<p>Printable characters can also be enclosed:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Delimiter ';'</pre>
</div>
</div>
<div class="paragraph">
<p>The backslash can be specified when enclosed within quotes:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Delimiter '\'</pre>
</div>
</div>
</dd>
</dl>
</div>
<div id="'xm_syslog_config_char_double_quote" class="dlist">
<dl>
<dt class="hdlist1">A character in double quotes</dt>
<dd>
<p>Double quotes can be used like single
quotes:</p>
<div class="listingblock">
<div class="content">
<pre>Delimiter " "</pre>
</div>
</div>
<div class="paragraph">
<p>The backslash can be specified when enclosed within double quotes:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Delimiter "\"</pre>
</div>
</div>
</dd>
</dl>
</div>
<div id="'xm_syslog_config_char_hex_code" class="dlist">
<dl>
<dt class="hdlist1">A hexadecimal ASCII code</dt>
<dd>
<p>Hexadecimal ASCII character codes can also
be used by prepending <code>0x</code>. For example, the space can be specified
as:</p>
<div class="listingblock">
<div class="content">
<pre>Delimiter 0x20</pre>
</div>
</div>
<div class="paragraph">
<p>This is equivalent to:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Delimiter " "</pre>
</div>
</div>
</dd>
</dl>
</div>
</div>
</div>
<div class="sect3">
<h4 id="xm_syslog_funcs"><a class="anchor" href="#xm_syslog_funcs"></a>4.10.2. Functions</h4>
<div class="paragraph">
<p>The following functions are exported by <em>xm_syslog</em>.</p>
</div>
<div id="xm_syslog_func_syslog_facility_string" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_string">string</a> <code>syslog_facility_string(<a href="#lang_type_integer">integer</a> arg)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Convert a Syslog facility value to a string.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_syslog_func_syslog_facility_value" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_integer">integer</a> <code>syslog_facility_value(<a href="#lang_type_string">string</a> arg)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Convert a Syslog facility string to an integer.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_syslog_func_syslog_severity_string" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_string">string</a> <code>syslog_severity_string(<a href="#lang_type_integer">integer</a> arg)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Convert a Syslog severity value to a string.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_syslog_func_syslog_severity_value" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_integer">integer</a> <code>syslog_severity_value(<a href="#lang_type_string">string</a> arg)</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Convert a Syslog severity string to an integer.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="xm_syslog_procs"><a class="anchor" href="#xm_syslog_procs"></a>4.10.3. Procedures</h4>
<div class="paragraph">
<p>The following procedures are exported by <em>xm_syslog</em>.</p>
</div>
<div id="xm_syslog_proc_parse_syslog" class="dlist">
<dl>
<dt class="hdlist1"><code>parse_syslog();</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Parse the <a href="#xm_syslog_field_raw_event">$raw_event</a> field as either BSD Syslog (RFC 3164)
     or IETF Syslog (RFC 5424) format.</p>
</div>
</div>
</div>
</dd>
<dt class="hdlist1"><code>parse_syslog(<a href="#lang_type_string">string</a> source);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Parse the given string as either BSD Syslog (RFC 3164) or IETF
     Syslog (RFC 5424) format.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_syslog_proc_parse_syslog_bsd" class="dlist">
<dl>
<dt class="hdlist1"><code>parse_syslog_bsd();</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Parse the <a href="#xm_syslog_field_raw_event">$raw_event</a> field as BSD Syslog (RFC 3164)
     format.</p>
</div>
</div>
</div>
</dd>
<dt class="hdlist1"><code>parse_syslog_bsd(<a href="#lang_type_string">string</a> source);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Parse the given string as BSD Syslog (RFC 3164) format.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_syslog_proc_parse_syslog_ietf" class="dlist">
<dl>
<dt class="hdlist1"><code>parse_syslog_ietf();</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Parse the <a href="#xm_syslog_field_raw_event">$raw_event</a> field as IETF Syslog (RFC 5424)
     format.</p>
</div>
</div>
</div>
</dd>
<dt class="hdlist1"><code>parse_syslog_ietf(<a href="#lang_type_string">string</a> source);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Parse the given string as IETF Syslog (RFC 5424) format.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_syslog_proc_to_syslog_bsd" class="dlist">
<dl>
<dt class="hdlist1"><code>to_syslog_bsd();</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Create a BSD Syslog formatted log message in <a href="#xm_syslog_field_raw_event">$raw_event</a>
     from the fields of the event. The following fields are used to
     construct the <a href="#xm_syslog_field_raw_event">$raw_event</a> field: <a href="#xm_syslog_field_EventTime">$EventTime</a>; <a href="#xm_syslog_field_Hostname">$Hostname</a>;
     <a href="#xm_syslog_field_SourceName">$SourceName</a>; <a href="#xm_syslog_field_ProcessID">$ProcessID</a>; <a href="#xm_syslog_field_Message">$Message</a> or <a href="#xm_syslog_field_raw_event">$raw_event</a>;
     <a href="#xm_syslog_field_SyslogSeverity">$SyslogSeverity</a>, <a href="#xm_syslog_field_SyslogSeverityValue">$SyslogSeverityValue</a>, <a href="#xm_syslog_field_Severity">$Severity</a>, or
     <a href="#xm_syslog_field_SeverityValue">$SeverityValue</a>; and <a href="#xm_syslog_field_SyslogFacility">$SyslogFacility</a> or
     <a href="#xm_syslog_field_SyslogFacilityValue">$SyslogFacilityValue</a>. If the fields are not present, a sensible
     default is used.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_syslog_proc_to_syslog_ietf" class="dlist">
<dl>
<dt class="hdlist1"><code>to_syslog_ietf();</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Create an IETF Syslog (RFC 5424) formatted log message in
     <a href="#xm_syslog_field_raw_event">$raw_event</a> from the fields of the event. The following fields
     are used to construct the <a href="#xm_syslog_field_raw_event">$raw_event</a> field: <a href="#xm_syslog_field_EventTime">$EventTime</a>;
     <a href="#xm_syslog_field_Hostname">$Hostname</a>; <a href="#xm_syslog_field_SourceName">$SourceName</a>; <a href="#xm_syslog_field_ProcessID">$ProcessID</a>; <a href="#xm_syslog_field_Message">$Message</a> or
     <a href="#xm_syslog_field_raw_event">$raw_event</a>; <a href="#xm_syslog_field_SyslogSeverity">$SyslogSeverity</a>, <a href="#xm_syslog_field_SyslogSeverityValue">$SyslogSeverityValue</a>,
     <a href="#xm_syslog_field_Severity">$Severity</a>, or <a href="#xm_syslog_field_SeverityValue">$SeverityValue</a>; and <a href="#xm_syslog_field_SyslogFacility">$SyslogFacility</a> or
     <a href="#xm_syslog_field_SyslogFacilityValue">$SyslogFacilityValue</a>. If the fields are not present, a sensible
     default is used.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_syslog_proc_to_syslog_snare" class="dlist">
<dl>
<dt class="hdlist1"><code>to_syslog_snare();</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Create a SNARE Syslog formatted log message in
     <a href="#xm_syslog_field_raw_event">$raw_event</a>. The following fields are used to construct the
     <a href="#xm_syslog_field_raw_event">$raw_event</a> field: <a href="#xm_syslog_field_EventTime">$EventTime</a>, <a href="#xm_syslog_field_Hostname">$Hostname</a>, <a href="#xm_syslog_field_SeverityValue">$SeverityValue</a>,
     <code>$FileName</code>, <code>$EventID</code>, <a href="#xm_syslog_field_SourceName">$SourceName</a>,<code>$AccountName</code>,
     <code>$AccountType</code>, <code>$EventType</code>, <code>$Category</code> and <a href="#xm_syslog_field_Message">$Message</a>.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="xm_syslog_fields"><a class="anchor" href="#xm_syslog_fields"></a>4.10.4. Fields</h4>
<div class="paragraph">
<p>The following fields are used by <em>xm_syslog</em>.</p>
</div>
<div class="paragraph">
<p>In addition to the fields listed below, the
<a href="#xm_syslog_proc_parse_syslog">parse_syslog()</a> and
<a href="#xm_syslog_proc_parse_syslog_ietf">parse_syslog_ietf()</a>
procedures will create fields from the Structured Data part of an IETF
Syslog message. If the SD-ID in this case is not "NXLOG", these fields
will be prefixed by the SD-ID (for example, <code>$mySDID.CustomField</code>).</p>
</div>
<div id="xm_syslog_field_raw_event" class="dlist">
<dl>
<dt class="hdlist1"><code>$raw_event</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>A Syslog formatted string, set after
	<a href="#xm_syslog_proc_to_syslog_bsd">to_syslog_bsd()</a>
	or
	<a href="#xm_syslog_proc_to_syslog_ietf">to_syslog_ietf()</a>
	is called.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_syslog_field_EventTime" class="dlist">
<dl>
<dt class="hdlist1"><code>$EventTime</code> (type: <a href="#lang_type_datetime">datetime</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The timestamp found in the Syslog message, set after
	<a href="#xm_syslog_proc_parse_syslog">parse_syslog()</a>,
	<a href="#xm_syslog_proc_parse_syslog_bsd">parse_syslog_bsd()</a>,
	or
	<a href="#xm_syslog_proc_parse_syslog_ietf">parse_syslog_ietf()</a>
	is called. If the year value is missing, it is set to the
	current year.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_syslog_field_Hostname" class="dlist">
<dl>
<dt class="hdlist1"><code>$Hostname</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The hostname part of the Syslog line, set after
	<a href="#xm_syslog_proc_parse_syslog">parse_syslog()</a>,
	<a href="#xm_syslog_proc_parse_syslog_bsd">parse_syslog_bsd()</a>,
	or
	<a href="#xm_syslog_proc_parse_syslog_ietf">parse_syslog_ietf()</a>
	is called.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_syslog_field_Message" class="dlist">
<dl>
<dt class="hdlist1"><code>$Message</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The message part of the Syslog line, set after
	<a href="#xm_syslog_proc_parse_syslog">parse_syslog()</a>,
	<a href="#xm_syslog_proc_parse_syslog_bsd">parse_syslog_bsd()</a>,
	or
	<a href="#xm_syslog_proc_parse_syslog_ietf">parse_syslog_ietf()</a>
	is called.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_syslog_field_MessageID" class="dlist">
<dl>
<dt class="hdlist1"><code>$MessageID</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The MSGID part of the syslog message, set after
	<a href="#xm_syslog_proc_parse_syslog_ietf">parse_syslog_ietf()</a>
	is called.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_syslog_field_ProcessID" class="dlist">
<dl>
<dt class="hdlist1"><code>$ProcessID</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The process ID in the Syslog line, set after
	<a href="#xm_syslog_proc_parse_syslog">parse_syslog()</a>,
	<a href="#xm_syslog_proc_parse_syslog_bsd">parse_syslog_bsd()</a>,
	or
	<a href="#xm_syslog_proc_parse_syslog_ietf">parse_syslog_ietf()</a>
	is called.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_syslog_field_Severity" class="dlist">
<dl>
<dt class="hdlist1"><code>$Severity</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The normalized severity name of the event. See
<a href="#xm_syslog_field_SeverityValue">$SeverityValue</a>.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_syslog_field_SeverityValue" class="dlist">
<dl>
<dt class="hdlist1"><code>$SeverityValue</code> (type: <a href="#lang_type_integer">integer</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The normalized severity number of the event, mapped as follows.</p>
</div>
<table class="tableblock frame-all grid-all">
<colgroup>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Syslog Severity</th>
<th class="tableblock halign-left valign-top">Normalized Severity</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">0/emerg</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">5/critical</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">1/alert</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">5/critical</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">2/crit</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">5/critical</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">3/err</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">4/error</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">4/warning</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">3/warning</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">5/notice</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">2/info</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">6/info</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">2/info</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">7/debug</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">1/debug</p></td>
</tr>
</tbody>
</table>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_syslog_field_SourceName" class="dlist">
<dl>
<dt class="hdlist1"><code>$SourceName</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The application/program part of the Syslog line, set after
	<a href="#xm_syslog_proc_parse_syslog">parse_syslog()</a>,
	<a href="#xm_syslog_proc_parse_syslog_bsd">parse_syslog_bsd()</a>,
	or
	<a href="#xm_syslog_proc_parse_syslog_ietf">parse_syslog_ietf()</a>
	is called.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_syslog_field_SyslogFacility" class="dlist">
<dl>
<dt class="hdlist1"><code>$SyslogFacility</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The facility name of the Syslog line, set after
	<a href="#xm_syslog_proc_parse_syslog">parse_syslog()</a>,
	<a href="#xm_syslog_proc_parse_syslog_bsd">parse_syslog_bsd()</a>,
	or
	<a href="#xm_syslog_proc_parse_syslog_ietf">parse_syslog_ietf()</a>
	is called. The default facility is <code>user</code>.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_syslog_field_SyslogFacilityValue" class="dlist">
<dl>
<dt class="hdlist1"><code>$SyslogFacilityValue</code> (type: <a href="#lang_type_integer">integer</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The facility code of the Syslog line, set after
	<a href="#xm_syslog_proc_parse_syslog">parse_syslog()</a>,
	<a href="#xm_syslog_proc_parse_syslog_bsd">parse_syslog_bsd()</a>,
	or
	<a href="#xm_syslog_proc_parse_syslog_ietf">parse_syslog_ietf()</a>
	is called. The default facility is <code>1</code> (user).</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_syslog_field_SyslogSeverity" class="dlist">
<dl>
<dt class="hdlist1"><code>$SyslogSeverity</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The severity name of the Syslog line, set after
<a href="#xm_syslog_proc_parse_syslog">parse_syslog()</a>,
<a href="#xm_syslog_proc_parse_syslog_bsd">parse_syslog_bsd()</a>, or
<a href="#xm_syslog_proc_parse_syslog_ietf">parse_syslog_ietf()</a>
is called. The default severity is <code>notice</code>. See
<a href="#xm_syslog_field_SeverityValue">$SeverityValue</a>.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_syslog_field_SyslogSeverityValue" class="dlist">
<dl>
<dt class="hdlist1"><code>$SyslogSeverityValue</code> (type: <a href="#lang_type_integer">integer</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The severity code of the Syslog line, set after
<a href="#xm_syslog_proc_parse_syslog">parse_syslog()</a>,
<a href="#xm_syslog_proc_parse_syslog_bsd">parse_syslog_bsd()</a>, or
<a href="#xm_syslog_proc_parse_syslog_ietf">parse_syslog_ietf()</a>
is called. The default severity is <code>5</code> (notice). See
<a href="#xm_syslog_field_SeverityValue">$SeverityValue</a>.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="xm_syslog_config_examples"><a class="anchor" href="#xm_syslog_config_examples"></a>4.10.5. Examples</h4>
<div id="xm_syslog_example_syslog_bsd_file" class="exampleblock">
<div class="title">Example 68. Sending a File as BSD Syslog over UDP</div>
<div class="content">
<div class="paragraph">
<p>In this example, logs are collected from files, converted to BSD
Syslog format with the
<a href="#xm_syslog_proc_to_syslog_bsd">to_syslog_bsd()</a> procedure, and sent
over UDP with the <a href="#om_udp">om_udp</a> module.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">syslog</span><span class="tag">&gt;</span>
    Module  xm_syslog
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">file</span><span class="tag">&gt;</span>
    Module  im_file

    # We monitor all files matching the wildcard.
    # Every line is read into the $raw_event field.
    File    &quot;/var/log/app*.log&quot;

    <span class="tag">&lt;Exec&gt;</span>
        # Set the $EventTime field usually found in the logs by
        # extracting it with a regexp. If this is not set, the current
        # system time will be used which might be a little off.
        if $raw_event =~ /(\d\d\d\d\-\d\d-\d\d \d\d:\d\d:\d\d)/
        {
            $EventTime = parsedate($1);
        }

        # Now set the severity to something custom. This defaults to
        # 'INFO' if unset.
        if $raw_event =~ /ERROR/ $Severity = 'ERROR';
        else $Severity = 'INFO';

        # The facility can be also set, otherwise the default value is
        # 'USER'.
        $SyslogFacility = 'AUDIT';

        # The SourceName field is called the TAG in RFC 3164
        # terminology and is usually the process name.
        $SourceName = 'my_application';

        # It is also possible to rewrite the Hostname if you do not
        # want to use the system hostname.
        $Hostname = 'myhost';

        # The Message field is used if present, otherwise the current
        # $raw_event is prepended with the Syslog headers. You can do
        # some modifications on the Message if required. Here we add
        # the full path of the source file to the end of message line.
        $Message = $raw_event + ' [' + file_name() + ']';

        # Now create our RFC 3164 compliant Syslog line using the
        # fields set above and/or use sensible defaults where
        # possible. The result will be in $raw_event.
        to_syslog_bsd();
    <span class="tag">&lt;/Exec&gt;</span>
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">udp</span><span class="tag">&gt;</span>
    # This module just sends the contents of the $raw_event field to
    # the destination defined here, one UDP packet per message.
    Module  om_udp
    Host    192.168.1.42
    Port    1514
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">file_to_udp</span><span class="tag">&gt;</span>
    Path    file =<span class="error">&gt;</span> udp
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
<div id="xm_syslog_example_bsd_udp" class="exampleblock">
<div class="title">Example 69. Collecting BSD Style Syslog Messages over UDP</div>
<div class="content">
<div class="paragraph">
<p>To collect BSD Syslog messages over UDP, use the
<a href="#xm_syslog_proc_parse_syslog_bsd">parse_syslog_bsd()</a> procedure
coupled with the <a href="#im_udp">im_udp</a> module as in the following example.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">syslog</span><span class="tag">&gt;</span>
    Module  xm_syslog
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">udp</span><span class="tag">&gt;</span>
    Module  im_udp
    Host    0.0.0.0
    Port    514
    Exec    parse_syslog_bsd();
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">file</span><span class="tag">&gt;</span>
    Module  om_file
    File    &quot;/var/log/logmsg.txt&quot;
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">syslog_to_file</span><span class="tag">&gt;</span>
    Path    udp =<span class="error">&gt;</span> file
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
<div id="xm_syslog_example_ietf_udp" class="exampleblock">
<div class="title">Example 70. Collecting IETF Style Syslog Messages over UDP</div>
<div class="content">
<div class="paragraph">
<p>To collect IETF Syslog messages over UDP as defined by RFC 5424 and
RFC 5426, use the
<a href="#xm_syslog_proc_parse_syslog_ietf">parse_syslog_ietf()</a> procedure
coupled with the <a href="#im_udp">im_udp</a> module as in the following example.
Note that, as for BSD Syslog, the default port is 514 (as defined by
RFC 5426).</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">syslog</span><span class="tag">&gt;</span>
    Module  xm_syslog
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">ietf</span><span class="tag">&gt;</span>
    Module  im_udp
    Host    0.0.0.0
    Port    514
    Exec    parse_syslog_ietf();
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">file</span><span class="tag">&gt;</span>
    Module  om_file
    File    &quot;/var/log/logmsg.txt&quot;
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">ietf_to_file</span><span class="tag">&gt;</span>
    Path    ietf =<span class="error">&gt;</span> file
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
<div id="xm_syslog_example_bsd_ietf_udp" class="exampleblock">
<div class="title">Example 71. Collecting Both IETF and BSD Syslog Messages over the Same UDP Port</div>
<div class="content">
<div class="paragraph">
<p>To collect both IETF and BSD Syslog messages over UDP, use the
<a href="#xm_syslog_proc_parse_syslog">parse_syslog()</a> procedure coupled with
the <a href="#im_udp">im_udp</a> module as in the following example. This
procedure is capable of detecting and parsing both Syslog
formats. Since 514 is the default UDP port number for both BSD and
IETF Syslog, this port can be useful to collect both formats
simultaneously. To accept both formats on different ports, the
appropriate parsers can be used as in the previous two examples.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">syslog</span><span class="tag">&gt;</span>
    Module  xm_syslog
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">udp</span><span class="tag">&gt;</span>
    Module  im_udp
    Host    0.0.0.0
    Port    514
    Exec    parse_syslog();
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">file</span><span class="tag">&gt;</span>
    Module  om_file
    File    &quot;/var/log/logmsg.txt&quot;
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">syslog_to_file</span><span class="tag">&gt;</span>
    Path    udp =<span class="error">&gt;</span> file
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
<div class="exampleblock">
<div class="title">Example 72. Collecting IETF Syslog Messages over TLS/SSL</div>
<div class="content">
<div class="paragraph">
<p>To collect IETF Syslog messages over TLS/SSL as defined by RFC 5424
and RFC 5425, use the
<a href="#xm_syslog_proc_parse_syslog_ietf">parse_syslog_ietf()</a> procedure
coupled with the <a href="#im_ssl">im_ssl</a> module as in this example.  Note
that the default port is 6514 in this case (as defined by RFC
5425). The payload format parser is handled by the
<a href="#xm_syslog_inputtype_syslog_tls">Syslog_TLS</a> input reader.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">syslog</span><span class="tag">&gt;</span>
    Module      xm_syslog
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">ssl</span><span class="tag">&gt;</span>
    Module      im_ssl
    Host        localhost
    Port        6514
    CAFile      %CERTDIR%/ca.pem
    CertFile    %CERTDIR%/client-cert.pem
    CertKeyFile %CERTDIR%/client-key.pem
    KeyPass     secret
    InputType   Syslog_TLS
    Exec        parse_syslog_ietf();
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">file</span><span class="tag">&gt;</span>
    Module      om_file
    File        &quot;/var/log/logmsg.txt&quot;
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">ssl_to_file</span><span class="tag">&gt;</span>
    Path        ssl =<span class="error">&gt;</span> file
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
<div id="xm_syslog_example_ietf_tcpout" class="exampleblock">
<div class="title">Example 73. Forwarding IETF Syslog over TCP</div>
<div class="content">
<div class="paragraph">
<p>The following configuration uses the
<a href="#xm_syslog_proc_to_syslog_ietf">to_syslog_ietf()</a> procedure to
convert input to IETF Syslog and forward it over TCP.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">syslog</span><span class="tag">&gt;</span>
    Module      xm_syslog
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">file</span><span class="tag">&gt;</span>
    Module      im_file
    File        &quot;/var/log/input.txt&quot;
    Exec        $TestField = &quot;test value&quot;; $Message = $raw_event;
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">tcp</span><span class="tag">&gt;</span>
    Module      om_tcp
    Host        127.0.0.1
    Port        1514
    Exec        to_syslog_ietf();
    OutputType  Syslog_TLS
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">file_to_syslog</span><span class="tag">&gt;</span>
    Path        file =<span class="error">&gt;</span> tcp
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
<div class="paragraph">
<p>Because of the Syslog_TLS framing, the raw data sent over TCP will
look like the following.</p>
</div>
<div class="listingblock">
<div class="title">Output Sample</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="log">130 &lt;13&gt;1 2012-01-01T16:15:52.873750Z  - - - [NXLOG@14506 EventReceivedTime=&quot;2012-01-01 17:15:52&quot; TestField=&quot;test value&quot;] test message<span class="line-marker"></span></code></pre>
</div>
</div>
<div class="paragraph">
<p>This example shows that all fields&#8212;&#8203;except those which are filled by
the Syslog parser&#8212;&#8203;are added to the structured data part.</p>
</div>
</div>
</div>
<div id="xm_syslog_example1" class="exampleblock">
<div class="title">Example 74. Conditional Rewrite of the Syslog Facility&#8212;&#8203;Version 1</div>
<div class="content">
<div class="paragraph">
<p>If the message part of the Syslog event matches the regular
expression, the <code>$SeverityValue</code> field will be set to the "error"
Syslog severity integer value (which is provided by the
<a href="#xm_syslog_func_syslog_severity_value">syslog_severity_value()</a>
function).</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">syslog</span><span class="tag">&gt;</span>
    Module  xm_syslog
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">udp</span><span class="tag">&gt;</span>
    Module  im_udp
    Port    514
    Host    0.0.0.0
    Exec    parse_syslog_bsd();
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">file</span><span class="tag">&gt;</span>
    Module  om_file
    File    &quot;/var/log/logmsg.txt&quot;
    Exec    if $Message =~ /error/ $SeverityValue = syslog_severity_value(&quot;error&quot;);
    Exec    to_syslog_bsd();
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">syslog_to_file</span><span class="tag">&gt;</span>
    Path    udp =<span class="error">&gt;</span> file
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
<div id="xm_syslog_example2" class="exampleblock">
<div class="title">Example 75. Conditional Rewrite of the Syslog Facility&#8212;&#8203;Version 2</div>
<div class="content">
<div class="paragraph">
<p>The following example does almost the same thing as the previous
example, except that the Syslog parsing and rewrite is moved to a
processor module and the rewrite only occurs if the facility was
modified.  This can make processing faster on multi-core systems
because the processor module runs in a separate thread. This method
can also minimize UDP packet loss because the input module does not
need to parse Syslog messages and therefore can process UDP packets
faster.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">syslog</span><span class="tag">&gt;</span>
    Module  xm_syslog
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">udp</span><span class="tag">&gt;</span>
    Module  im_udp
    Host    0.0.0.0
    Port    514
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Processor</span> <span class="attribute-name">rewrite</span><span class="tag">&gt;</span>
    Module  pm_null
    <span class="tag">&lt;Exec&gt;</span>
        parse_syslog_bsd();
        if $Message =~ /error/
        {
            $SeverityValue = syslog_severity_value(&quot;error&quot;);
            to_syslog_bsd();
        }
    <span class="tag">&lt;/Exec&gt;</span>
<span class="tag">&lt;/Processor&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">file</span><span class="tag">&gt;</span>
    Module  om_file
    File    &quot;/var/log/logmsg.txt&quot;
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">syslog_to_file</span><span class="tag">&gt;</span>
    Path    udp =<span class="error">&gt;</span> rewrite =<span class="error">&gt;</span> file
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="xm_wtmp"><a class="anchor" href="#xm_wtmp"></a>4.11. WTMP (xm_wtmp)</h3>
<div class="paragraph">
<p>This module provides a parser function to process binary wtmp
files. The module registers a parser function using the name of the
extension module instance. This parser can be used as a parameter for
the <a href="#config_inputtype">InputType</a> directive in input modules such as
<a href="#im_file">im_file</a>.</p>
</div>
<div class="sect3">
<h4 id="xm_wtmp_config"><a class="anchor" href="#xm_wtmp_config"></a>4.11.1. Configuration</h4>
<div class="paragraph">
<p>The <em>xm_wtmp</em> module accepts only the <a href="#config_module_common">common
module directives</a>.</p>
</div>
</div>
<div class="sect3">
<h4 id="xm_wtmp_config_examples"><a class="anchor" href="#xm_wtmp_config_examples"></a>4.11.2. Examples</h4>
<div id="xm_wtmp_example1" class="exampleblock">
<div class="title">Example 76. WTMP to JSON Format Conversion</div>
<div class="content">
<div class="paragraph">
<p>The following configuration accepts WTMP and converts it to JSON.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">wtmp</span><span class="tag">&gt;</span>
    Module      xm_wtmp
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Extension</span> <span class="attribute-name">json</span><span class="tag">&gt;</span>
    Module      xm_json
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">in</span><span class="tag">&gt;</span>
    Module      im_file
    File        '/var/log/wtmp'
    InputType   wtmp
    Exec        to_json();
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">out</span><span class="tag">&gt;</span>
    Module      om_file
    File        '/var/log/wtmp.txt'
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">processwtmp</span><span class="tag">&gt;</span>
    Path        in =<span class="error">&gt;</span> out
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">Output Sample</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="json">{
  <span class="key"><span class="delimiter">&quot;</span><span class="content">EventTime</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">2013-10-01 09:39:59</span><span class="delimiter">&quot;</span></span>,
  <span class="key"><span class="delimiter">&quot;</span><span class="content">AccountName</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">root</span><span class="delimiter">&quot;</span></span>,
  <span class="key"><span class="delimiter">&quot;</span><span class="content">Device</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">pts/1</span><span class="delimiter">&quot;</span></span>,
  <span class="key"><span class="delimiter">&quot;</span><span class="content">LoginType</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">login</span><span class="delimiter">&quot;</span></span>,
  <span class="key"><span class="delimiter">&quot;</span><span class="content">EventReceivedTime</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">2013-10-10 15:40:20</span><span class="delimiter">&quot;</span></span>,
  <span class="key"><span class="delimiter">&quot;</span><span class="content">SourceModuleName</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">input</span><span class="delimiter">&quot;</span></span>,
  <span class="key"><span class="delimiter">&quot;</span><span class="content">SourceModuleType</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">im_file</span><span class="delimiter">&quot;</span></span>
}
{
  <span class="key"><span class="delimiter">&quot;</span><span class="content">EventTime</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">2013-10-01 23:23:38</span><span class="delimiter">&quot;</span></span>,
  <span class="key"><span class="delimiter">&quot;</span><span class="content">AccountName</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">shutdown</span><span class="delimiter">&quot;</span></span>,
  <span class="key"><span class="delimiter">&quot;</span><span class="content">Device</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">no device</span><span class="delimiter">&quot;</span></span>,
  <span class="key"><span class="delimiter">&quot;</span><span class="content">LoginType</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">shutdown</span><span class="delimiter">&quot;</span></span>,
  <span class="key"><span class="delimiter">&quot;</span><span class="content">EventReceivedTime</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">2013-10-11 10:58:00</span><span class="delimiter">&quot;</span></span>,
  <span class="key"><span class="delimiter">&quot;</span><span class="content">SourceModuleName</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">input</span><span class="delimiter">&quot;</span></span>,
  <span class="key"><span class="delimiter">&quot;</span><span class="content">SourceModuleType</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">im_file</span><span class="delimiter">&quot;</span></span>
}</code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="xm_xml"><a class="anchor" href="#xm_xml"></a>4.12. XML (xm_xml)</h3>
<div class="paragraph">
<p>This module provides functions and procedures for working with data
formatted as Extensible Markup Language (XML). It can convert log
messages to XML format and can parse XML into <a href="#lang_fields">fields</a>.</p>
</div>
<div class="sect3">
<h4 id="xm_xml_config"><a class="anchor" href="#xm_xml_config"></a>4.12.1. Configuration</h4>
<div class="paragraph">
<p>The <em>xm_xml</em> module accepts only the <a href="#config_module_common">common
module directives</a>.</p>
</div>
</div>
<div class="sect3">
<h4 id="xm_xml_funcs"><a class="anchor" href="#xm_xml_funcs"></a>4.12.2. Functions</h4>
<div class="paragraph">
<p>The following functions are exported by <em>xm_xml</em>.</p>
</div>
<div id="xm_xml_func_to_xml" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_string">string</a> <code>to_xml()</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Convert the fields to XML and returns this as a string value.
     The <code>$raw_event</code> field and any field having a leading dot (<code>.</code>)
     or underscore (<code>_</code>) will be automatically excluded.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="xm_xml_procs"><a class="anchor" href="#xm_xml_procs"></a>4.12.3. Procedures</h4>
<div class="paragraph">
<p>The following procedures are exported by <em>xm_xml</em>.</p>
</div>
<div id="xm_xml_proc_parse_xml" class="dlist">
<dl>
<dt class="hdlist1"><code>parse_xml();</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Parse the <code>$raw_event</code> field as XML input.</p>
</div>
</div>
</div>
</dd>
<dt class="hdlist1"><code>parse_xml(<a href="#lang_type_string">string</a> source);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Parse the given string as XML format.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="xm_xml_proc_to_xml" class="dlist">
<dl>
<dt class="hdlist1"><code>to_xml();</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Convert the fields to XML and put this into the <code>$raw_event</code>
     field. The <code>$raw_event</code> field and any field having a leading dot
     (<code>.</code>) or underscore (<code>_</code>) will be automatically excluded.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="xm_xml_config_examples"><a class="anchor" href="#xm_xml_config_examples"></a>4.12.4. Examples</h4>
<div id="xm_xml_example1" class="exampleblock">
<div class="title">Example 77. Syslog to XML Format Conversion</div>
<div class="content">
<div class="paragraph">
<p>The following configuration accepts Syslog (both BSD and IETF) and
converts it to XML.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">syslog</span><span class="tag">&gt;</span>
    Module  xm_syslog
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Extension</span> <span class="attribute-name">xml</span><span class="tag">&gt;</span>
    Module  xm_xml
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">tcp</span><span class="tag">&gt;</span>
    Module  im_tcp
    Port    1514
    Host    0.0.0.0
    Exec    parse_syslog(); to_xml();
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">file</span><span class="tag">&gt;</span>
    Module  om_file
    File    &quot;/var/log/log.xml&quot;
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">tcp_to_file</span><span class="tag">&gt;</span>
    Path    tcp =<span class="error">&gt;</span> file
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">Input Sample</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="log">&lt;30&gt;Sep 30 15:45:43 host44.localdomain.hu acpid: 1 client rule loaded<span class="line-marker"></span></code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">Output Sample</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag">&lt;Event&gt;</span>
  <span class="tag">&lt;MessageSourceAddress&gt;</span>127.0.0.1<span class="tag">&lt;/MessageSourceAddress&gt;</span>
  <span class="tag">&lt;EventReceivedTime&gt;</span>2012-03-08 15:05:39<span class="tag">&lt;/EventReceivedTime&gt;</span>
  <span class="tag">&lt;SyslogFacilityValue&gt;</span>3<span class="tag">&lt;/SyslogFacilityValue&gt;</span>
  <span class="tag">&lt;SyslogFacility&gt;</span>DAEMON<span class="tag">&lt;/SyslogFacility&gt;</span>
  <span class="tag">&lt;SyslogSeverityValue&gt;</span>6<span class="tag">&lt;/SyslogSeverityValue&gt;</span>
  <span class="tag">&lt;SyslogSeverity&gt;</span>INFO<span class="tag">&lt;/SyslogSeverity&gt;</span>
  <span class="tag">&lt;SeverityValue&gt;</span>2<span class="tag">&lt;/SeverityValue&gt;</span>
  <span class="tag">&lt;Severity&gt;</span>INFO<span class="tag">&lt;/Severity&gt;</span>
  <span class="tag">&lt;Hostname&gt;</span>host44.localdomain.hu<span class="tag">&lt;/Hostname&gt;</span>
  <span class="tag">&lt;EventTime&gt;</span>2012-09-30 15:45:43<span class="tag">&lt;/EventTime&gt;</span>
  <span class="tag">&lt;SourceName&gt;</span>acpid<span class="tag">&lt;/SourceName&gt;</span>
  <span class="tag">&lt;Message&gt;</span>1 client rule loaded<span class="tag">&lt;/Message&gt;</span>
<span class="tag">&lt;/Event&gt;</span></code></pre>
</div>
</div>
</div>
</div>
<div id="xm_xml_example2" class="exampleblock">
<div class="title">Example 78. Converting Windows EventLog to Syslog-Encapsulated XML</div>
<div class="content">
<div class="paragraph">
<p>The following configuration reads the Windows EventLog and converts it
to the BSD Syslog format where the message part contains the fields
in XML.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">syslog</span><span class="tag">&gt;</span>
    Module  xm_syslog
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Extension</span> <span class="attribute-name">xml</span><span class="tag">&gt;</span>
    Module  xm_xml
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">eventlog</span><span class="tag">&gt;</span>
    Module  im_msvistalog
    Exec    $Message = to_xml(); to_syslog_bsd();
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">tcp</span><span class="tag">&gt;</span>
    Module  om_tcp
    Host    192.168.1.1
    Port    1514
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">eventlog_to_tcp</span><span class="tag">&gt;</span>
    Path    eventlog =<span class="error">&gt;</span> tcp
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">Output Sample</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="log">&lt;14&gt;Mar  8 15:12:12 WIN-OUNNPISDHIG Service_Control_Manager: &lt;Event&gt;&lt;EventTime&gt;2012-03-08 15:12:12&lt;/EventTime&gt;&lt;EventTimeWritten&gt;2012-03-08 15:12:12&lt;/EventTimeWritten&gt;&lt;Hostname&gt;WIN-OUNNPISDHIG&lt;/Hostname&gt;&lt;EventType&gt;INFO&lt;/EventType&gt;&lt;SeverityValue&gt;2&lt;/SeverityValue&gt;&lt;Severity&gt;INFO&lt;/Severity&gt;&lt;SourceName&gt;Service Control Manager&lt;/SourceName&gt;&lt;FileName&gt;System&lt;/FileName&gt;&lt;EventID&gt;7036&lt;/EventID&gt;&lt;CategoryNumber&gt;0&lt;/CategoryNumber&gt;&lt;RecordNumber&gt;6791&lt;/RecordNumber&gt;&lt;Message&gt;The nxlog service entered the running state. &lt;/Message&gt;&lt;EventReceivedTime&gt;2012-03-08 15:12:14&lt;/EventReceivedTime&gt;&lt;/Event&gt;<span class="line-marker"></span></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="input-modules"><a class="anchor" href="#input-modules"></a>5. Input Modules</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Input modules are responsible for collecting event log data from
various sources.</p>
</div>
<div class="paragraph">
<p>Each module provides a set of fields for each log message, these are
documented in the corresponding sections below. The NXLog core
will add to this set the fields listed in the following section.</p>
</div>
<div class="sect2">
<h3 id="core_fields"><a class="anchor" href="#core_fields"></a>5.1. Fields</h3>
<div class="paragraph">
<p>The following fields are used by <em>core</em>.</p>
</div>
<div id="core_field_raw_event" class="dlist">
<dl>
<dt class="hdlist1"><code>$raw_event</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The data received from stream modules (im_file, im_tcp, etc.).</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_field_EventReceivedTime" class="dlist">
<dl>
<dt class="hdlist1"><code>$EventReceivedTime</code> (type: <a href="#lang_type_datetime">datetime</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The time when the event is received. The value is not modified
	if the field already exists.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_field_SourceModuleName" class="dlist">
<dl>
<dt class="hdlist1"><code>$SourceModuleName</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The name of the module instance, for input modules. The value
	is not modified if the field already exists.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="core_field_SourceModuleType" class="dlist">
<dl>
<dt class="hdlist1"><code>$SourceModuleType</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The type of module instance (such as <code>im_file</code>), for input
	modules. The value is not modified if the field already
	exists.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect2">
<h3 id="im_dbi"><a class="anchor" href="#im_dbi"></a>5.2. DBI (im_dbi)</h3>
<div class="paragraph">
<p>The <em>im_dbi</em> module allows NXLog to pull log data from external
databases. This module utilizes the
<a href="http://libdbi.sourceforge.net">libdbi</a> database abstraction library,
which supports various database engines such as MySQL, PostgreSQL,
MSSQL, Sybase, Oracle, SQLite, and Firebird. A SELECT statement can be
specified, which will be executed periodically to check for new
records.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
The <em>im_dbi</em> and <a href="#om_dbi">om_dbi</a> modules support GNU/Linux only
      because of the libdbi library. The <a href="#im_odbc">im_odbc</a> and
      <a href="#om_odbc">om_odbc</a> modules provide native database access on
      Windows.
</td>
</tr>
</table>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
libdbi needs <a href="#im_dbi_config_driver">drivers</a> to access the
      database engines. These are in the libdbd-* packages on Debian
      and Ubuntu. CentOS 5.6 has a libdbi-drivers RPM package, but
      this package does not contain any driver binaries under
      /usr/lib64/dbd. The drivers for both MySQL and PostgreSQL are in
      libdbi-dbd-mysql. If these are not installed, NXLog will
      return a libdbi driver initialization error.
</td>
</tr>
</table>
</div>
<div class="sect3">
<h4 id="im_dbi_config"><a class="anchor" href="#im_dbi_config"></a>5.2.1. Configuration</h4>
<div class="paragraph">
<p>The <em>im_dbi</em> module accepts the following directives in addition to the
<a href="#config_module_common">common module directives</a>.</p>
</div>
<div id="im_dbi_config_driver" class="dlist">
<dl>
<dt class="hdlist1">Driver</dt>
<dd>
<p>This mandatory directive specifies the name of the libdbi
driver which will be used to connect to the database. A DRIVER name
must be provided here for which a loadable driver module exists
under the name <code>libdbdDRIVER.so</code> (usually under <code>/usr/lib/dbd/</code>). The
MySQL driver is in the <code>libdbdmysql.so</code> file.</p>
</dd>
</dl>
</div>
<div id="im_dbi_config_sql" class="dlist">
<dl>
<dt class="hdlist1">SQL</dt>
<dd>
<p>This directive should specify the SELECT statement to be
executed every <a href="#im_dbi_config_pollinterval">PollInterval</a>
seconds. The module automatically appends a <code>WHERE id &gt; ? LIMIT 10</code>
clause to the statement. The result set returned by the SELECT
statement must contain an <em>id</em> column which is then stored and used
for the next query.</p>
</dd>
</dl>
</div>
<hr>
<div id="im_dbi_config_option" class="dlist">
<dl>
<dt class="hdlist1">Option</dt>
<dd>
<p>This directive can be used to specify additional driver
options such as connection parameters. The manual of the libdbi
driver should contain the options available for use here.</p>
</dd>
</dl>
</div>
<div id="im_dbi_config_pollinterval" class="dlist">
<dl>
<dt class="hdlist1">PollInterval</dt>
<dd>
<p>This directive specifies how frequently the module will
check for new records, in seconds. If this directive is not
specified, the default is 1 second. Fractional seconds may be
specified (<code>PollInterval 0.5</code> will check twice every second).</p>
</dd>
</dl>
</div>
<div id="im_dbi_config_savepos" class="dlist">
<dl>
<dt class="hdlist1">SavePos</dt>
<dd>
<p>If this boolean directive is set to TRUE, the position will
be saved when NXLog exits. The position will be read from
the cache file upon startup. The default is TRUE: the position will
be saved if this directive is not specified. Even if <strong>SavePos</strong> is
enabled, it can be explicitly turned off with the global
<a href="#config_global_nocache">NoCache</a> directive.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="im_dbi_config_examples"><a class="anchor" href="#im_dbi_config_examples"></a>5.2.2. Examples</h4>
<div class="exampleblock">
<div class="title">Example 79. Reading From a MySQL Database</div>
<div class="content">
<div class="paragraph">
<p>This example uses libdbi and the MySQL driver to connect to the logdb
database on the local host and execute the provided statement.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Input</span> <span class="attribute-name">dbi</span><span class="tag">&gt;</span>
    Module  im_dbi
    Driver  mysql
    Option  host 127.0.0.1
    Option  username mysql
    Option  password mysql
    Option  dbname logdb
    SQL     SELECT id, facility, severity, hostname, \
                   timestamp, application, message \
            FROM log
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">file</span><span class="tag">&gt;</span>
    Module  om_file
    File    &quot;tmp/output&quot;
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">dbi_to_file</span><span class="tag">&gt;</span>
    Path    dbi =<span class="error">&gt;</span> file
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="im_exec"><a class="anchor" href="#im_exec"></a>5.3. External Programs (im_exec)</h3>
<div class="paragraph">
<p>This module will execute a program or script on startup and read its
standard output. It can be used to easily integrate with exotic log
sources which can be read only with the help of an external script or
program.</p>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<div class="title">Warning</div>
</td>
<td class="content">
If you are using a Perl script, consider
         turning on <em>Autoflush</em> with <code>$| = 1;</code>, otherwise <em>im_exec</em>
         might not receive data immediately due to Perl&#8217;s internal
         buffering. See the <a href="http://perldoc.perl.org/perlvar.html">Perl language
         reference</a> for more information about <code>$|</code>.
</td>
</tr>
</table>
</div>
<div class="sect3">
<h4 id="im_exec_config"><a class="anchor" href="#im_exec_config"></a>5.3.1. Configuration</h4>
<div class="paragraph">
<p>The <em>im_exec</em> module accepts the following directives in addition to the
<a href="#config_module_common">common module directives</a>. The
<a href="#im_exec_config_command">Command</a> directive is required.</p>
</div>
<div id="im_exec_config_command" class="dlist">
<dl>
<dt class="hdlist1">Command</dt>
<dd>
<p>This mandatory directive specifies the name of the program or script
to be executed.</p>
</dd>
</dl>
</div>
<hr>
<div id="im_exec_config_arg" class="dlist">
<dl>
<dt class="hdlist1">Arg</dt>
<dd>
<p>This is an optional parameter. <strong>Arg</strong> can be specified multiple
times, once for each argument that needs to be passed to the
<a href="#im_exec_config_command">Command</a>. Note that specifying multiple
arguments with one <strong>Arg</strong> directive, with arguments separated by
spaces, will not work (the <a href="#im_exec_config_command">Command</a> would
receive it as one argument).</p>
</dd>
</dl>
</div>
<div id="im_exec_config_inputtype" class="dlist">
<dl>
<dt class="hdlist1">InputType</dt>
<dd>
<p>See the <a href="#config_inputtype">InputType</a> description in the
global module configuration section.</p>
</dd>
</dl>
</div>
<div id="im_exec_config_restart" class="dlist">
<dl>
<dt class="hdlist1">Restart</dt>
<dd>
<p>Restart the process if it exits. There is a one second delay
before it is restarted to avoid a denial-of-service when a process
is not behaving. Looping should be implemented in the script itself,
this directive is only to provide some safety against malfunctioning
scripts and programs. This boolean directive defaults to FALSE: the
<a href="#im_exec_config_command">Command</a> will not be restarted if it
exits.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="im_exec_config_examples"><a class="anchor" href="#im_exec_config_examples"></a>5.3.2. Examples</h4>
<div class="exampleblock">
<div class="title">Example 80. Emulating im_file</div>
<div class="content">
<div class="paragraph">
<p>This configuration uses the tail command to read from a file.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
The <a href="#im_file">im_file</a> module should be used to read log
      messages from files. This example only demonstrates the use of
      the <em>im_exec</em> module.
</td>
</tr>
</table>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Input</span> <span class="attribute-name">messages</span><span class="tag">&gt;</span>
    Module  im_exec
    Command /usr/bin/tail
    Arg     -f
    Arg     /var/log/messages
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">file</span><span class="tag">&gt;</span>
    Module  om_file
    File    &quot;tmp/output&quot;
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">messages_to_file</span><span class="tag">&gt;</span>
    Path    messages =<span class="error">&gt;</span> file
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="im_file"><a class="anchor" href="#im_file"></a>5.4. Files (im_file)</h3>
<div class="paragraph">
<p>This module can be used to read log messages from files. The file
position can be persistently saved across restarts in order to avoid
reading from the beginning again when NXLog is
restarted. External rotation tools are also supported. When the module
is not able to read any more data from the file, it checks whether the
opened file descriptor belongs to the same filename it opened
originally. If the inodes differ, the module assumes the file was
moved and reopens its input.</p>
</div>
<div class="paragraph">
<p><em>im_file</em> uses a one second interval to monitor files for new
messages. This method was implemented because polling a regular file
is not supported on all platforms. If there is no more data to read,
the module will sleep for 1 second.</p>
</div>
<div class="paragraph">
<p>By using wildcards, the module can read multiple files simultaneously
and will open new files as they appear. It will also enter newly
created directories if recursion is enabled.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
The module needs to scan the directory content for wildcarded
      file monitoring. This can present a significant load if there
      are many files (hundreds or thousands) in the monitored
      directory. For this reason it is highly recommended to rotate
      files out of the monitored directory either using the built-in
      log rotation capabilities of NXLog or with external
      tools.
</td>
</tr>
</table>
</div>
<div class="sect3">
<h4 id="im_file_config"><a class="anchor" href="#im_file_config"></a>5.4.1. Configuration</h4>
<div class="paragraph">
<p>The <em>im_file</em> module accepts the following directives in addition to the
<a href="#config_module_common">common module directives</a>. The
<a href="#im_file_config_file">File</a> directive is required.</p>
</div>
<div id="im_file_config_file" class="dlist">
<dl>
<dt class="hdlist1">File</dt>
<dd>
<p>This mandatory directive specifies the name of the input file
to open. It must be a <a href="#lang_type_string">string</a> type
<a href="#lang_expressions">expression</a>. For relative filenames you should
be aware that NXLog changes its working directory to "/"
unless the global <a href="#config_global_spooldir">SpoolDir</a> is set to
something else. On Windows systems the directory separator is the
backslash (<code>\</code>). For compatibility reasons the forward slash (<code>/</code>)
character can be also used as the directory separator, but this only
works for filenames not containing wildcards. If the filename is
specified using wildcards, the backslash (<code>\</code>) should be used for
the directory separator.</p>
<div class="paragraph">
<p>Wildcards are supported in filenames only, directory names in the path
cannot be wildcarded. Wildcards are not regular expressions, but are
patterns commonly used by Unix shells to expand filenames (also known
as "globbing").</p>
</div>
<div class="openblock">
<div class="content">
<div class="dlist">
<dl>
<dt class="hdlist1">?</dt>
<dd>
<p>Matches a single character only.</p>
</dd>
<dt class="hdlist1">*</dt>
<dd>
<p>Matches zero or more characters.</p>
</dd>
<dt class="hdlist1">\*</dt>
<dd>
<p>Matches the asterisk (<code>*</code>) character.</p>
</dd>
<dt class="hdlist1">\?</dt>
<dd>
<p>Matches the question mark (<code>?</code>) character.</p>
</dd>
<dt class="hdlist1">[&#8230;&#8203;]</dt>
<dd>
<p>Used to specify a single character. The class description
is a list containing single characters and ranges of characters
separated by the hyphen (<code>-</code>). If the first character of the class
description is <code>^</code> or <code>!</code>, the sense of the description is
reversed (any character <em>not</em> in the list is accepted). Any
character can have a backslash (<code>\</code>) preceding it, which is
ignored, allowing the characters <code>]</code> and <code>-</code> to be used in the
character class, as well as <code>^</code> and <code>!</code> at the beginning.</p>
</dd>
</dl>
</div>
</div>
</div>
<div id="im_file_config_file_note" class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
<div class="paragraph">
<p>The backslash (<code>\</code>) is used to escape the wildcard characters.
Unfortunately this is the same as the directory separator on Windows.
Take this into account when specifying wildcarded filenames on this
platform. Suppose that log files under the directory <code>C:\test</code> need to
be monitored. Specifying the wildcard <code>C:\test\*.log</code> will not match
because <code>\*</code> becomes a literal asterisk and the filename is treated as
non-wildcarded. For this reason the directory separator needs to be
escaped: <code>C:\test\\*.log</code> will match our files. <code>C:\\test\\*.log</code> will
also work. When specifying the filename using double quotes, this
would became <code>C:\\test\\\\*.log</code> because the backslash is also used as
an escape character inside double quoted <a href="#lang_literal_string">string
literals</a>.
Filenames on Windows systems are treated
case-insensitively, but case-sensitively on Unix/Linux.</p>
</div>
</td>
</tr>
</table>
</div>
</dd>
</dl>
</div>
<hr>
<div id="im_file_config_activefiles" class="dlist">
<dl>
<dt class="hdlist1">ActiveFiles</dt>
<dd>
<p>This directive specifies the maximum number of files
NXLog will actively monitor. If there are modifications to
more files in parallel than the value of this directive, then
modifications to files above this limit will only get noticed after
the <a href="#im_file_config_dircheckinterval">DirCheckInterval</a> (all data
should be collected eventually). Typically there are only a few log
sources actively appending data to log files, and the rest of the
files are dormant after being rotated, so the default value of 10
files should be sufficient in most cases. This directive is also only
relevant in case of a wildcarded <a href="#im_file_config_file">File</a> path.</p>
</dd>
</dl>
</div>
<div id="im_file_config_closewhenidle" class="dlist">
<dl>
<dt class="hdlist1">CloseWhenIdle</dt>
<dd>
<p>If set to TRUE, this boolean directive specifies that
open input files should be closed as soon as possible after there is
no more data to read. Some applications request an exclusive lock on
the log file when written or rotated, and this directive can
possibly help if the application tries again to acquire the lock. The
default is FALSE.</p>
</dd>
</dl>
</div>
<div id="im_file_config_dircheckinterval" class="dlist">
<dl>
<dt class="hdlist1">DirCheckInterval</dt>
<dd>
<p>This directive specifies how frequently, in
seconds, the module will check the monitored directory for
modifications to files and new files in case of a wildcarded
<a href="#im_file_config_file">File</a> path. The default is twice the value of
the <a href="#im_file_config_pollinterval">PollInterval</a> directive (if
<a href="#im_file_config_pollinterval">PollInterval</a> is not set, the default
is 2 seconds). Fractional seconds may be specified. It is
recommended to increase the default if there are many files which
cannot be rotated out and the NXLog process is causing high
CPU load.</p>
</dd>
</dl>
</div>
<div id="im_file_config_pollinterval" class="dlist">
<dl>
<dt class="hdlist1">PollInterval</dt>
<dd>
<p>This directive specifies how frequently the module will
check for new files and new log entries, in seconds. If this
directive is not specified, it defaults to 1 second. Fractional
seconds may be specified (<code>PollInterval 0.5</code> will check twice every
second).</p>
</dd>
</dl>
</div>
<div id="im_file_config_readfromlast" class="dlist">
<dl>
<dt class="hdlist1">ReadFromLast</dt>
<dd>
<p>This optional boolean directive instructs the module to
only read logs which arrived after NXLog was started if the
saved position could not be read (for example on first start). When
<a href="#im_file_config_savepos">SavePos</a> is TRUE and a previously saved
position value could be read, the module will resume reading from
this saved position. If <strong>ReadFromLast</strong> is FALSE, the module will
read all logs from the file. This can result in quite a lot of
messages, and is usually not the expected behavior. If this
directive is not specified, it defaults to TRUE.</p>
</dd>
</dl>
</div>
<div id="im_file_config_recursive" class="dlist">
<dl>
<dt class="hdlist1">Recursive</dt>
<dd>
<p>If set to TRUE, this boolean directive specifies that
input files should be searched recursively under
sub-directories. This option takes effect only if wildcards are used
in the filename. For example, if the <a href="#im_file_config_file">File</a>
directive is set to <code>/var/log/*.log</code>, then
<code>/var/log/apache2/access.log</code> will also match. Because directory
wildcards are not supported, this directive only makes it possible
to read multiple files from different sub-directories with a single
im_file module instance. The default is TRUE.</p>
</dd>
</dl>
</div>
<div id="im_file_config_renamecheck" class="dlist">
<dl>
<dt class="hdlist1">RenameCheck</dt>
<dd>
<p>If set to TRUE, this boolean directive specifies that
input files should be monitored for possible file rotation via
renaming in order to avoid re-reading the file contents. A file is
considered to be rotated when NXLog detects a new file whose
inode and size matches that of another watched file which has just
been deleted.  Note that this does not always work correctly and can
yield false positives when a log file is deleted and another is
added with the same size. The file system is likely to reuse to
inode number of the deleted file and thus the module will falsely
detect this as a rename/rotation. For this reason the default value
of <strong>RenameCheck</strong> is FALSE: renamed files are considered to be new
and the file contents will be re-read.</p>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
It is recommended to use a naming scheme for rotated files so
      names of rotated files do not match the wildcard and are not
      monitored anymore after rotation, instead of trying to solve the
      renaming issue with this directive.
</td>
</tr>
</table>
</div>
</dd>
</dl>
</div>
<div id="im_file_config_savepos" class="dlist">
<dl>
<dt class="hdlist1">SavePos</dt>
<dd>
<p>If this boolean directive is set to TRUE, the file position
will be saved when NXLog exits. The file position will be
read from the cache file upon startup. The default is TRUE: the file
position will be saved if this directive is not specified. Even if
<strong>SavePos</strong> is enabled, it can be explicitly turned off with the
global <a href="#config_global_nocache">NoCache</a> directive.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="im_file_funcs"><a class="anchor" href="#im_file_funcs"></a>5.4.2. Functions</h4>
<div class="paragraph">
<p>The following functions are exported by <em>im_file</em>.</p>
</div>
<div id="im_file_func_file_name" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_string">string</a> <code>file_name()</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Return the name of the currently open file which the log was
     read from.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="im_file_config_examples"><a class="anchor" href="#im_file_config_examples"></a>5.4.3. Examples</h4>
<div class="exampleblock">
<div class="title">Example 81. Forwarding Logs From a File to a Remote Host</div>
<div class="content">
<div class="paragraph">
<p>This configuration will read from a file and forward messages
via TCP. No additional processing is done.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Input</span> <span class="attribute-name">messages</span><span class="tag">&gt;</span>
    Module  im_file
    File    &quot;/var/log/messages&quot;
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">tcp</span><span class="tag">&gt;</span>
    Module  om_tcp
    Host    192.168.1.1
    Port    514
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">messages_to_tcp</span><span class="tag">&gt;</span>
    Path    messages =<span class="error">&gt;</span> tcp
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="im_internal"><a class="anchor" href="#im_internal"></a>5.5. Internal (im_internal)</h3>
<div class="paragraph">
<p>NXLog produces its own logs about its operations, including
errors and debug messages. This module makes it possible to insert
those internal log messages into a route. Internal messages can also
be generated from the NXLog language using the
<a href="#core_proc_log_info">log_info()</a>,
<a href="#core_proc_log_warning">log_warning()</a>, and
<a href="#core_proc_log_error">log_error()</a> procedures.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
Only messages with log level INFO and above are supported. Debug
      messages are ignored due to technical reasons. For debugging
      purposes the direct logging facility should be used: see the
      global <a href="#config_global_logfile">LogFile</a> and
      <a href="#config_global_loglevel">LogLevel</a> directives.
</td>
</tr>
</table>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<div class="title">Warning</div>
</td>
<td class="content">
One must be careful about the use of the <em>im_internal</em> module
         because it is easy to cause message loops. For example,
         consider the situation when internal log messages are sent to
         a database. If the database is experiencing errors which
         result in internal error messages, then these are again
         routed to the database and this will trigger further error
         messages, resulting in a loop. In order to avoid a resource
         exhaustion, the <em>im_internal</em> module will drop its messages
         when the queue of the next module in the route is full. It is
         recommended to always put the <em>im_internal</em> module instance in
         a separate route.
</td>
</tr>
</table>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
If internal messages are required in Syslog format, they must be
      explicitly converted with <a href="#pm_transformer">pm_transformer</a> or
      the <a href="#xm_syslog_proc_to_syslog_bsd">to_syslog_bsd()</a> procedure
      of the <a href="#xm_syslog">xm_syslog</a> module, because the
      <a href="#im_internal_field_raw_event">$raw_event</a> field is not
      generated in Syslog format.
</td>
</tr>
</table>
</div>
<div class="sect3">
<h4 id="im_internal_config"><a class="anchor" href="#im_internal_config"></a>5.5.1. Configuration</h4>
<div class="paragraph">
<p>The <em>im_internal</em> module accepts only the <a href="#config_module_common">common
module directives</a>.</p>
</div>
</div>
<div class="sect3">
<h4 id="im_internal_fields"><a class="anchor" href="#im_internal_fields"></a>5.5.2. Fields</h4>
<div class="paragraph">
<p>The following fields are used by <em>im_internal</em>.</p>
</div>
<div id="im_internal_field_raw_event" class="dlist">
<dl>
<dt class="hdlist1"><code>$raw_event</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The string passed to the
	<a href="#core_proc_log_info">log_info()</a> or other log_*
	procedure.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_internal_field_ErrorCode" class="dlist">
<dl>
<dt class="hdlist1"><code>$ErrorCode</code> (type: <a href="#lang_type_integer">integer</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The error number provided by the Apache portable runtime
	library, if an error is logged resulting from an operating
	system error.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_internal_field_EventTime" class="dlist">
<dl>
<dt class="hdlist1"><code>$EventTime</code> (type: <a href="#lang_type_datetime">datetime</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The current time.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_internal_field_Hostname" class="dlist">
<dl>
<dt class="hdlist1"><code>$Hostname</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The hostname where the log was produced.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_internal_field_Message" class="dlist">
<dl>
<dt class="hdlist1"><code>$Message</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The same value as <a href="#im_internal_field_raw_event">$raw_event</a>.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_internal_field_ProcessID" class="dlist">
<dl>
<dt class="hdlist1"><code>$ProcessID</code> (type: <a href="#lang_type_integer">integer</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The process ID of the NXLog process.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_internal_field_Severity" class="dlist">
<dl>
<dt class="hdlist1"><code>$Severity</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The severity name of the event.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_internal_field_SeverityValue" class="dlist">
<dl>
<dt class="hdlist1"><code>$SeverityValue</code> (type: <a href="#lang_type_integer">integer</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Depending on the log level of the internal message, the value
	corresponding to "debug", "info", "warning", "error", or
	"critical".</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_internal_field_SourceName" class="dlist">
<dl>
<dt class="hdlist1"><code>$SourceName</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Set to <code>nxlog</code>.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="im_internal_config_examples"><a class="anchor" href="#im_internal_config_examples"></a>5.5.3. Examples</h4>
<div class="exampleblock">
<div class="title">Example 82. Forwarding Internal Messages over Syslog UDP</div>
<div class="content">
<div class="paragraph">
<p>This configuration collects NXLog internal messages, adds BSD
Syslog headers, and forwards via UDP.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">syslog</span><span class="tag">&gt;</span>
    Module  xm_syslog
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">internal</span><span class="tag">&gt;</span>
    Module  im_internal
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">udp</span><span class="tag">&gt;</span>
    Module  om_udp
    Host    192.168.1.1
    Port    514
    Exec    to_syslog_bsd();
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">internal_to_udp</span><span class="tag">&gt;</span>
    Path    internal =<span class="error">&gt;</span> udp
<span class="tag">&lt;/Route&gt;</span>
</pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="im_kernel"><a class="anchor" href="#im_kernel"></a>5.6. Kernel (im_kernel)</h3>
<div class="paragraph">
<p>This module can collect kernel log messages from the kernel log
buffer. Currently this module works on Linux
only, where the klogctl()
system call is used for this purpose. In order to be able to read
kernel logs, special privileges are required. For this, NXLog
needs to be started as root. Using the <a href="#config_global_user">User</a> and
<a href="#config_global_group">Group</a> global directives NXLog can then
drop its root privileges while keeping the CAP_SYS_ADMIN capability in
order to read the kernel log buffer.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
Unfortunately it is not possible to read from the /proc/kmsg
      pseudo file for an unprivileged process even if the
      CAP_SYS_ADMIN capability is kept. For this reason the /proc/kmsg
      interface is not supported by the <em>im_kernel</em> module. The
      <a href="#im_file">im_file</a> module should work fine with the /proc/kmsg
      pseudo file if one wishes to collect kernel logs this way,
      though this will require NXLog to be running as root.
</td>
</tr>
</table>
</div>
<div class="listingblock">
<div class="title">Log Sample</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="log">&lt;6&gt;Some message from the kernel.<span class="line-marker"></span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Kernel messages are valid BSD Syslog messages, with a priority from 0 (emerg)
to 7 (debug), but do not contain timestamp and hostname fields. These can be
parsed with the <em>xm_syslog</em>
<a href="#xm_syslog_proc_parse_syslog_bsd">parse_syslog_bsd()</a> procedure, and the
timestamp and hostname fields will be added by NXLog.</p>
</div>
<div class="sect3">
<h4 id="im_kernel_config"><a class="anchor" href="#im_kernel_config"></a>5.6.1. Configuration</h4>
<div class="paragraph">
<p>The <em>im_kernel</em> module accepts only the <a href="#config_module_common">common
module directives</a>.</p>
</div>
</div>
<div class="sect3">
<h4 id="im_kernel_config_examples"><a class="anchor" href="#im_kernel_config_examples"></a>5.6.2. Examples</h4>
<div class="exampleblock">
<div class="title">Example 83. Storing Raw Kernel Logs into a File</div>
<div class="content">
<div class="paragraph">
<p>This configuration collects log messages from the kernel and writes
them to file.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
</pre></td>
  <td class="code"><pre># drop privileges after being started as root
User nxlog
Group nxlog

<span class="tag">&lt;Input</span> <span class="attribute-name">kernel</span><span class="tag">&gt;</span>
    Module  im_kernel
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">file</span><span class="tag">&gt;</span>
    Module  om_file
    File    &quot;tmp/output&quot;
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">kernel_to_file</span><span class="tag">&gt;</span>
    Path    kernel =<span class="error">&gt;</span> file
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="im_mark"><a class="anchor" href="#im_mark"></a>5.7. Mark (im_mark)</h3>
<div class="paragraph">
<p>Mark messages are used to indicate periodic activity to assure that
the logger is running when there are no log messages coming in from
other sources.</p>
</div>
<div class="paragraph">
<p>By default, if no module-specific directives are set, a log message
will be generated every 30 minutes containing <code>-- MARK --</code>.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
The <a href="#im_mark_field_raw_event">$raw_event</a> field is not
      generated in Syslog format. If mark messages are required in
      Syslog format, they must be explicitly converted with the
      <a href="#xm_syslog_proc_to_syslog_bsd">to_syslog_bsd()</a> procedure.
</td>
</tr>
</table>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
The functionality of the <em>im_mark</em> module can be also achieved
      using the <a href="#config_module_schedule">Schedule</a> block with a
      <a href="#core_proc_log_info">log_info("--MARK--")</a> Exec statement,
      which would insert the messages via the
      <a href="#im_internal">im_internal</a> module into a route. Using a single
      module for this task can simplify configuration.
</td>
</tr>
</table>
</div>
<div class="sect3">
<h4 id="im_mark_config"><a class="anchor" href="#im_mark_config"></a>5.7.1. Configuration</h4>
<div class="paragraph">
<p>The <em>im_mark</em> module accepts the following directives in addition to the
<a href="#config_module_common">common module directives</a>.</p>
</div>
<div id="im_mark_config_mark" class="dlist">
<dl>
<dt class="hdlist1">Mark</dt>
<dd>
<p>This optional directive sets the string for the mark
message. The default is <code>-- MARK --</code>.</p>
</dd>
</dl>
</div>
<div id="im_mark_config_markinterval" class="dlist">
<dl>
<dt class="hdlist1">MarkInterval</dt>
<dd>
<p>This optional directive sets the interval for mark
messages, in minutes. The default is 30 minutes.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="im_mark_fields"><a class="anchor" href="#im_mark_fields"></a>5.7.2. Fields</h4>
<div class="paragraph">
<p>The following fields are used by <em>im_mark</em>.</p>
</div>
<div id="im_mark_field_raw_event" class="dlist">
<dl>
<dt class="hdlist1"><code>$raw_event</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The value defined by the
	<a href="#im_mark_config_mark">Mark</a> directive, <code>-- MARK
	--</code> by default.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_mark_field_EventTime" class="dlist">
<dl>
<dt class="hdlist1"><code>$EventTime</code> (type: <a href="#lang_type_datetime">datetime</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The current time.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_mark_field_Message" class="dlist">
<dl>
<dt class="hdlist1"><code>$Message</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The same value as <a href="#im_mark_field_raw_event">$raw_event</a>.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_mark_field_ProcessID" class="dlist">
<dl>
<dt class="hdlist1"><code>$ProcessID</code> (type: <a href="#lang_type_integer">integer</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The process ID of the NXLog process.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_mark_field_Severity" class="dlist">
<dl>
<dt class="hdlist1"><code>$Severity</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The severity name: <code>INFO</code>.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_mark_field_SeverityValue" class="dlist">
<dl>
<dt class="hdlist1"><code>$SeverityValue</code> (type: <a href="#lang_type_integer">integer</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The INFO severity level value: <code>2</code>.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_mark_field_SourceName" class="dlist">
<dl>
<dt class="hdlist1"><code>$SourceName</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Set to <code>nxlog</code>.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="im_mark_config_examples"><a class="anchor" href="#im_mark_config_examples"></a>5.7.3. Examples</h4>
<div class="exampleblock">
<div class="title">Example 84. Using the im_mark Module</div>
<div class="content">
<div class="paragraph">
<p>Here, NXLog will write the specified string to file every
minute.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Input</span> <span class="attribute-name">mark</span><span class="tag">&gt;</span>
    Module          im_mark
    MarkInterval    1
    Mark            -=| MARK |=-
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">file</span><span class="tag">&gt;</span>
    Module          om_file
    File            &quot;tmp/output&quot;
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">mark_to_file</span><span class="tag">&gt;</span>
    Path            mark =<span class="error">&gt;</span> file
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="im_mseventlog"><a class="anchor" href="#im_mseventlog"></a>5.8. EventLog for Windows XP/2000/2003 (im_mseventlog)</h3>
<div class="paragraph">
<p>This module can be used to collect EventLog messages on Microsoft
Windows platforms. The module looks up the available EventLog sources
stored under the registry key
<code>SYSTEM\CurrentControlSet\Services\Eventlog</code> and polls logs from
each of these sources or only the sources defined with the
<a href="#im_mseventlog_config_sources">Sources</a> directive.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
<div class="paragraph">
<p>Windows Vista, Windows 2008, and later use a new EventLog API which is
not backward compatible. Messages in some events produced by sources
in this new format cannot be resolved with the old API which is used
by this module. If such an event is encountered, a <code>$Message</code> similar to
the following will be set:
<code>The description for EventID XXXX from source SOURCE cannot be read by
im_mseventlog because this does not support the newer WIN2008/Vista
EventLog API. Consider using the im_msvistalog module instead.</code></p>
</div>
<div class="paragraph">
<p>Though the majority of event messages can be read with this module
even on Windows 2008/Vista and later, it is recommended to use the
<a href="#im_msvistalog">im_msvistalog</a> module instead.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
<div class="paragraph">
<p>Strings are stored in DLL and executable files and need to be read by
the module when reading EventLog messages. If a program (DLL/EXE) is
already uninstalled and is not available for looking up a string, the
following message will appear instead:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>The description for EventID XXXX from source SOURCE cannot be found.</pre>
</div>
</div>
</td>
</tr>
</table>
</div>
<div class="sect3">
<h4 id="im_mseventlog_config"><a class="anchor" href="#im_mseventlog_config"></a>5.8.1. Configuration</h4>
<div class="paragraph">
<p>The <em>im_mseventlog</em> module accepts the following directives in addition
to the <a href="#config_module_common">common module directives</a>.</p>
</div>
<div id="im_mseventlog_config_readfromlast" class="dlist">
<dl>
<dt class="hdlist1">ReadFromLast</dt>
<dd>
<p>This optional boolean directive instructs the module to
only read logs which arrived after NXLog was started if the
saved position could not be read (for example on first start). When
<a href="#im_mseventlog_config_savepos">SavePos</a> is TRUE and a previously
saved position value could be read, the module will resume reading
from this saved position. If <strong>ReadFromLast</strong> is FALSE, the module
will read all logs from the EventLog. This can result in quite a lot
of messages, and is usually not the expected behavior. If this
directive is not specified, it defaults to TRUE.</p>
</dd>
</dl>
</div>
<div id="im_mseventlog_config_savepos" class="dlist">
<dl>
<dt class="hdlist1">SavePos</dt>
<dd>
<p>This boolean directive specifies that the file position
should be saved when NXLog exits. The file position will be
read from the cache file upon startup. The default is TRUE: the file
position will be saved if this directive is not specified. Even if
<strong>SavePos</strong> is enabled, it can be explicitly turned off with the
global <a href="#config_global_nocache">NoCache</a> directive.</p>
</dd>
</dl>
</div>
<div id="im_mseventlog_config_sources" class="dlist">
<dl>
<dt class="hdlist1">Sources</dt>
<dd>
<p>This optional directive takes a comma-separated list of
EventLog filenames, such as <code>Security, Application</code>, to select
specific EventLog sources for reading. If this directive is not
specified, then all available EventLog sources are read (as listed
in the registry). This directive should not be confused with the
<a href="#im_mseventlog_field_SourceName">$SourceName</a> fielded contained
within the EventLog and it is not a list of such names. The value of
this is stored in the <a href="#im_mseventlog_field_FileName">FileName</a>
field.</p>
</dd>
</dl>
</div>
<div id="im_mseventlog_config_utf8" class="dlist">
<dl>
<dt class="hdlist1">UTF8</dt>
<dd>
<p>If this optional boolean directive is set to TRUE, all strings
will be converted to UTF-8 encoding. Internally this calls the
<a href="#xm_charconv_proc_convert_fields">convert_fields</a> procedure. The
<a href="#xm_charconv">xm_charconv</a> module must be loaded for the character
set conversion to work. The default is TRUE, but conversion will
only occur if the <a href="#xm_charconv">xm_charconv</a> module is loaded,
otherwise strings will be in the local codepage.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="im_mseventlog_fields"><a class="anchor" href="#im_mseventlog_fields"></a>5.8.2. Fields</h4>
<div class="paragraph">
<p>The following fields are used by <em>im_mseventlog</em>.</p>
</div>
<div id="im_mseventlog_field_raw_event" class="dlist">
<dl>
<dt class="hdlist1"><code>$raw_event</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>A string containing the timestamp, hostname, severity, and
	message from the event.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_mseventlog_field_AccountName" class="dlist">
<dl>
<dt class="hdlist1"><code>$AccountName</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The username associated with the event.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_mseventlog_field_AccountType" class="dlist">
<dl>
<dt class="hdlist1"><code>$AccountType</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The type of the account. Possible values are: <code>User</code>, <code>Group</code>,
	<code>Domain</code>, <code>Alias</code>, <code>Well Known Group</code>, <code>Deleted Account</code>,
	<code>Invalid</code>, <code>Unknown</code>, and <code>Computer</code>.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_mseventlog_field_Category" class="dlist">
<dl>
<dt class="hdlist1"><code>$Category</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The category name resolved from CategoryNumber.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_mseventlog_field_CategoryNumber" class="dlist">
<dl>
<dt class="hdlist1"><code>$CategoryNumber</code> (type: <a href="#lang_type_integer">integer</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The category number, stored as Category in the EventRecord.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_mseventlog_field_Domain" class="dlist">
<dl>
<dt class="hdlist1"><code>$Domain</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The domain name of the user.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_mseventlog_field_EventID" class="dlist">
<dl>
<dt class="hdlist1"><code>$EventID</code> (type: <a href="#lang_type_integer">integer</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The event ID of the EventRecord.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_mseventlog_field_EventTime" class="dlist">
<dl>
<dt class="hdlist1"><code>$EventTime</code> (type: <a href="#lang_type_datetime">datetime</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The TimeGenerated field of the EventRecord.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_mseventlog_field_EventTimeWritten" class="dlist">
<dl>
<dt class="hdlist1"><code>$EventTimeWritten</code> (type: <a href="#lang_type_datetime">datetime</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The TimeWritten field of the EventRecord.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_mseventlog_field_EventType" class="dlist">
<dl>
<dt class="hdlist1"><code>$EventType</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The type of the event, which is a string describing the
	severity. Possible values are: <code>ERROR</code>, <code>AUDIT_FAILURE</code>,
	<code>AUDIT_SUCCESS</code>, <code>INFO</code>, <code>WARNING</code>, and <code>UNKNOWN</code>.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_mseventlog_field_FileName" class="dlist">
<dl>
<dt class="hdlist1"><code>$FileName</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The logfile source of the event (for example, <code>Security</code> or
	<code>Application</code>).</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_mseventlog_field_Hostname" class="dlist">
<dl>
<dt class="hdlist1"><code>$Hostname</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The host or computer name field of the EventRecord.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_mseventlog_field_Message" class="dlist">
<dl>
<dt class="hdlist1"><code>$Message</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The message from the event.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_mseventlog_field_RecordNumber" class="dlist">
<dl>
<dt class="hdlist1"><code>$RecordNumber</code> (type: <a href="#lang_type_integer">integer</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The number of the event record.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_mseventlog_field_Severity" class="dlist">
<dl>
<dt class="hdlist1"><code>$Severity</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The normalized severity name of the event. See
<a href="#im_mseventlog_field_SeverityValue">$SeverityValue</a>.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_mseventlog_field_SeverityValue" class="dlist">
<dl>
<dt class="hdlist1"><code>$SeverityValue</code> (type: <a href="#lang_type_integer">integer</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The normalized severity number of the event, mapped as follows.</p>
</div>
<table class="tableblock frame-all grid-all">
<colgroup>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Event Log Severity</th>
<th class="tableblock halign-left valign-top">Normalized Severity</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">0/Audit Success</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">2/INFO</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">0/Audit Failure</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">4/ERROR</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">1/Critical</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">5/CRITICAL</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">2/Error</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">4/ERROR</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">3/Warning</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">3/WARNING</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">4/Information</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">2/INFO</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">5/Verbose</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">1/DEBUG</p></td>
</tr>
</tbody>
</table>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_mseventlog_field_SourceName" class="dlist">
<dl>
<dt class="hdlist1"><code>$SourceName</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The event source which produced the event (the subsystem or
	application name).</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="im_mseventlog_config_examples"><a class="anchor" href="#im_mseventlog_config_examples"></a>5.8.3. Examples</h4>
<div class="exampleblock">
<div class="title">Example 85. Forwarding EventLogs from a Windows Machine to a Remote Host</div>
<div class="content">
<div class="paragraph">
<p>This configuration collects Windows EventLog and forwards the messages
to a remote host via TCP.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Input</span> <span class="attribute-name">eventlog</span><span class="tag">&gt;</span>
    Module      im_mseventlog
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">tcp</span><span class="tag">&gt;</span>
    Module      om_tcp
    Host        192.168.1.1
    Port        514
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">eventlog_to_tcp</span><span class="tag">&gt;</span>
    Path        eventlog =<span class="error">&gt;</span> tcp
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="im_msvistalog"><a class="anchor" href="#im_msvistalog"></a>5.9. EventLog for Windows 2008/Vista and Later (im_msvistalog)</h3>
<div class="paragraph">
<p>This module can be used to collect EventLog messages on Microsoft
Windows platforms which support the newer EventLog API (also known as
the Crimson EventLog subsystem), namely Windows 2008/Vista and later.
See the official Microsoft documentation about
<a href="http://technet.microsoft.com/en-us/library/cc722404.aspx">Event Logs</a>.
The module supports reading all System, Application, and Custom
events.  It looks up the available channels and monitors events in
each unless the <a href="#im_msvistalog_config_query">Query</a> and
<a href="#im_msvistalog_config_channel">Channel</a> directives are explicitly
defined.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
This module will not work on Windows 2003 and earlier because
      Windows Vista, Windows 2008, and later use a new EventLog API
      which is not available in earlier Windows versions. EventLog
      messages on these platforms can be collected with the
      <a href="#im_mseventlog">im_mseventlog</a> module.
</td>
</tr>
</table>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
The Windows EventLog subsystem does not support subscriptions to
      Debug and Analytic channels, thus it is not possible to collect
      these types of events with this module.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>In addition to the standard set of <a href="#im_msvistalog_fields">fields</a>
which are listed under the System section, event providers can define
their own additional schema which enables logging additional data
under the EventData section. The Security log makes use of this new
feature and such additional fields can be seen as in the following XML
snippet:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag">&lt;EventData&gt;</span>
  <span class="tag">&lt;Data</span> <span class="attribute-name">Name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">SubjectUserSid</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>S-1-5-18<span class="tag">&lt;/Data&gt;</span>
  <span class="tag">&lt;Data</span> <span class="attribute-name">Name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">SubjectUserName</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>WIN-OUNNPISDHIG$<span class="tag">&lt;/Data&gt;</span>
  <span class="tag">&lt;Data</span> <span class="attribute-name">Name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">SubjectDomainName</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>WORKGROUP<span class="tag">&lt;/Data&gt;</span>
  <span class="tag">&lt;Data</span> <span class="attribute-name">Name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">SubjectLogonId</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>0x3e7<span class="tag">&lt;/Data&gt;</span>
  <span class="tag">&lt;Data</span> <span class="attribute-name">Name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">TargetUserSid</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>S-1-5-18<span class="tag">&lt;/Data&gt;</span>
  <span class="tag">&lt;Data</span> <span class="attribute-name">Name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">TargetUserName</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>SYSTEM<span class="tag">&lt;/Data&gt;</span>
  <span class="tag">&lt;Data</span> <span class="attribute-name">Name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">TargetDomainName</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>NT AUTHORITY<span class="tag">&lt;/Data&gt;</span>
  <span class="tag">&lt;Data</span> <span class="attribute-name">Name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">TargetLogonId</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>0x3e7<span class="tag">&lt;/Data&gt;</span>
  <span class="tag">&lt;Data</span> <span class="attribute-name">Name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">LogonType</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>5<span class="tag">&lt;/Data&gt;</span>
  <span class="tag">&lt;Data</span> <span class="attribute-name">Name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">LogonProcessName</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>Advapi<span class="tag">&lt;/Data&gt;</span>
  <span class="tag">&lt;Data</span> <span class="attribute-name">Name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">AuthenticationPackageName</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>Negotiate<span class="tag">&lt;/Data&gt;</span>
  <span class="tag">&lt;Data</span> <span class="attribute-name">Name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">WorkstationName</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
  <span class="tag">&lt;Data</span> <span class="attribute-name">Name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">LogonGuid</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>{00000000-0000-0000-0000-000000000000}<span class="tag">&lt;/Data&gt;</span>
  <span class="tag">&lt;Data</span> <span class="attribute-name">Name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">TransmittedServices</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>-<span class="tag">&lt;/Data&gt;</span>
  <span class="tag">&lt;Data</span> <span class="attribute-name">Name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">LmPackageName</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>-<span class="tag">&lt;/Data&gt;</span>
  <span class="tag">&lt;Data</span> <span class="attribute-name">Name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">KeyLength</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>0<span class="tag">&lt;/Data&gt;</span>
  <span class="tag">&lt;Data</span> <span class="attribute-name">Name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">ProcessId</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>0x1dc<span class="tag">&lt;/Data&gt;</span>
  <span class="tag">&lt;Data</span> <span class="attribute-name">Name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">ProcessName</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>C:\Windows\System32\services.exe<span class="tag">&lt;/Data&gt;</span>
  <span class="tag">&lt;Data</span> <span class="attribute-name">Name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">IpAddress</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>-<span class="tag">&lt;/Data&gt;</span>
  <span class="tag">&lt;Data</span> <span class="attribute-name">Name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">IpPort</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>-<span class="tag">&lt;/Data&gt;</span>
<span class="tag">&lt;/EventData&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>NXLog can extract this data when fields are logged using this
schema. The values will be available in the fields of the internal
NXLog log structure. This is especially useful because there
is no need to write pattern matching rules to extract this data from
the message. These fields can be used in filtering rules, be written
into SQL tables, or be used to trigger actions. The
<a href="#config_module_exec">Exec</a> directive can be used for filtering:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Input</span> <span class="attribute-name">in</span><span class="tag">&gt;</span>
    Module  im_msvistalog
    Exec    if ($TargetUserName == 'SYSTEM') OR \
               ($EventType == 'VERBOSE') drop();
<span class="tag">&lt;/Input&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
<div class="sect3">
<h4 id="im_msvistalog_config"><a class="anchor" href="#im_msvistalog_config"></a>5.9.1. Configuration</h4>
<div class="paragraph">
<p>The <em>im_msvistalog</em> module accepts the following directives in addition
to the <a href="#config_module_common">common module directives</a>.</p>
</div>
<div id="im_msvistalog_config_batchsize" class="dlist">
<dl>
<dt class="hdlist1">BatchSize</dt>
<dd>
<p>This optional directive can be used to specify the number
of event records the EventLog API will pass to the module for
processing. Larger sizes may increase throughput. Note that there is
a known issue in the Windows EventLog subsystem: when this value is
higher than 31 it may fail to retrieve some events on busy systems,
returning the error "EvtNext failed with error 1734: The array
bounds are invalid." For this reason, increasing this value is not
recommended. The default is <code>31</code>.</p>
</dd>
</dl>
</div>
<div id="im_msvistalog_config_channel" class="dlist">
<dl>
<dt class="hdlist1">Channel</dt>
<dd>
<p>The name of the Channel to query. If not specified, the
module will read from all sources defined in the registry. See the
MSDN documentation about
<a href="http://msdn.microsoft.com/en-us/library/aa385231.aspx">Event
Selection</a>.</p>
</dd>
</dl>
</div>
<div id="im_msvistalog_config_pollinterval" class="dlist">
<dl>
<dt class="hdlist1">PollInterval</dt>
<dd>
<p>This directive specifies how frequently
the module will check for new events, in seconds. If this directive is not
specified, the default is 1 second. Fractional seconds may be
specified (<code>PollInterval 0.5</code> will check twice every second).</p>
</dd>
</dl>
</div>
<div id="im_msvistalog_config_query" class="dlist">
<dl>
<dt class="hdlist1">Query</dt>
<dd>
<p>This directive specifies the query for pulling only specific
EventLog sources. See the MSDN documentation about
<a href="http://msdn.microsoft.com/en-us/library/aa385231.aspx">Event
Selection</a>. Note that this directive requires a single-line
parameter, so multi-line query XML should be specified using line
continuation:</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
</pre></td>
  <td class="code"><pre>Query <span class="tag">&lt;QueryList&gt;</span>                                             \
        <span class="tag">&lt;Query</span> <span class="attribute-name">Id</span>=<span class="string"><span class="delimiter">'</span><span class="content">1</span><span class="delimiter">'</span></span><span class="tag">&gt;</span>                                        \
         <span class="tag">&lt;Select</span> <span class="attribute-name">Path</span>=<span class="string"><span class="delimiter">'</span><span class="content">Security</span><span class="delimiter">'</span></span><span class="tag">&gt;</span>*[System/Level=4]<span class="tag">&lt;/Select&gt;</span>   \
        <span class="tag">&lt;/Query&gt;</span>                                              \
      <span class="tag">&lt;/QueryList&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
<div class="paragraph">
<p>When the <strong>Query</strong> contains an XPath style expression, the
<a href="#im_msvistalog_config_channel">Channel</a> must also be specified.
Otherwise if an XML Query is specified, the
<a href="#im_msvistalog_config_channel">Channel</a> should not be used.</p>
</div>
</dd>
</dl>
</div>
<div id="im_msvistalog_config_queryxml" class="dlist">
<dl>
<dt class="hdlist1">QueryXML</dt>
<dd>
<p>This directive is the same as the
<a href="#im_msvistalog_config_query">Query</a> directive above, except it can
be used as a block. Multi-line XML queries can be used without line
continuation, and the XML Query can be copied directly from Event
Viewer.</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
</pre></td>
  <td class="code"><pre><span class="tag">&lt;QueryXML&gt;</span>
  <span class="tag">&lt;QueryList&gt;</span>
    <span class="tag">&lt;Query</span> <span class="attribute-name">Id</span>=<span class="string"><span class="delimiter">'</span><span class="content">1</span><span class="delimiter">'</span></span><span class="tag">&gt;</span>
      <span class="tag">&lt;Select</span> <span class="attribute-name">Path</span>=<span class="string"><span class="delimiter">'</span><span class="content">Security</span><span class="delimiter">'</span></span><span class="tag">&gt;</span>*[System/Level=4]<span class="tag">&lt;/Select&gt;</span>
    <span class="tag">&lt;/Query&gt;</span>
  <span class="tag">&lt;/QueryList&gt;</span>
<span class="tag">&lt;/QueryXML&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_msvistalog_config_readfromlast" class="dlist">
<dl>
<dt class="hdlist1">ReadFromLast</dt>
<dd>
<p>This optional boolean directive instructs the module to
only read logs which arrived after NXLog was started if the
saved position could not be read (for example on first start). When
<a href="#im_msvistalog_config_savepos">SavePos</a> is TRUE and a previously
saved position value could be read, the module will resume reading
from this saved position. If <strong>ReadFromLast</strong> is FALSE, the module
will read all logs from the EventLog. This can result in quite a lot
of messages, and is usually not the expected behavior. If this
directive is not specified, it defaults to TRUE.</p>
</dd>
</dl>
</div>
<div id="im_msvistalog_config_savepos" class="dlist">
<dl>
<dt class="hdlist1">SavePos</dt>
<dd>
<p>This boolean directive specifies that the file position
should be saved when NXLog exits. The file position will be
read from the cache file upon startup. The default is TRUE: the file
position is saved if this directive is not specified. Even if
<strong>SavePos</strong> is enabled, it can be explicitly turned off with the
global <a href="#config_global_nocache">NoCache</a> directive.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="im_msvistalog_fields"><a class="anchor" href="#im_msvistalog_fields"></a>5.9.2. Fields</h4>
<div class="paragraph">
<p>The following fields are used by <em>im_msvistalog</em>.</p>
</div>
<div id="im_msvistalog_field_raw_event" class="dlist">
<dl>
<dt class="hdlist1"><code>$raw_event</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>A string containing the EventTime, Hostname, Severity,
	EventID, and Message from the event.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_msvistalog_field_AccountName" class="dlist">
<dl>
<dt class="hdlist1"><code>$AccountName</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The username associated with the event.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_msvistalog_field_AccountType" class="dlist">
<dl>
<dt class="hdlist1"><code>$AccountType</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The type of the account. Possible values are: <code>User</code>, <code>Group</code>,
	<code>Domain</code>, <code>Alias</code>, <code>Well Known Group</code>, <code>Deleted Account</code>,
	<code>Invalid</code>, <code>Unknown</code>, and <code>Computer</code>.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_msvistalog_field_ActivityID" class="dlist">
<dl>
<dt class="hdlist1"><code>$ActivityID</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>A globally unique identifier for the current activity, as stored in
EvtSystemActivityID.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_msvistalog_field_Category" class="dlist">
<dl>
<dt class="hdlist1"><code>$Category</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The category name resolved from Task.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_msvistalog_field_Channel" class="dlist">
<dl>
<dt class="hdlist1"><code>$Channel</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The Channel of the event source (for example, <code>Security</code> or
	<code>Application</code>).</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_msvistalog_field_Domain" class="dlist">
<dl>
<dt class="hdlist1"><code>$Domain</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The domain name of the user.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_msvistalog_field_EventID" class="dlist">
<dl>
<dt class="hdlist1"><code>$EventID</code> (type: <a href="#lang_type_integer">integer</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The event ID (specific to the event source) from the EvtSystemEventID
field.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_msvistalog_field_EventTime" class="dlist">
<dl>
<dt class="hdlist1"><code>$EventTime</code> (type: <a href="#lang_type_datetime">datetime</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The EvtSystemTimeCreated field.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_msvistalog_field_EventType" class="dlist">
<dl>
<dt class="hdlist1"><code>$EventType</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The type of the event, which is a string describing the
	severity. This is translated to its string representation from
	EvtSystemLevel. Possible values are: <code>CRITICAL</code>, <code>ERROR</code>,
	<code>AUDIT_FAILURE</code>, <code>AUDIT_SUCCESS</code>, <code>INFO</code>, <code>WARNING</code>, and
	<code>VERBOSE</code>.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_msvistalog_field_Hostname" class="dlist">
<dl>
<dt class="hdlist1"><code>$Hostname</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The EvtSystemComputer field.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_msvistalog_field_Keywords" class="dlist">
<dl>
<dt class="hdlist1"><code>$Keywords</code> (type: <a href="#lang_type_integer">integer</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The value of the Keywords field from EvtSystemKeywords.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_msvistalog_field_Message" class="dlist">
<dl>
<dt class="hdlist1"><code>$Message</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The message from the event.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_msvistalog_field_Opcode" class="dlist">
<dl>
<dt class="hdlist1"><code>$Opcode</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The Opcode string resolved from OpcodeValue.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_msvistalog_field_OpcodeValue" class="dlist">
<dl>
<dt class="hdlist1"><code>$OpcodeValue</code> (type: <a href="#lang_type_integer">integer</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The Opcode number of the event as in EvtSystemOpcode.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_msvistalog_field_ProcessID" class="dlist">
<dl>
<dt class="hdlist1"><code>$ProcessID</code> (type: <a href="#lang_type_integer">integer</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The process identifier of the event producer as in
	EvtSystemProcessID.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_msvistalog_field_ProviderGuid" class="dlist">
<dl>
<dt class="hdlist1"><code>$ProviderGuid</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The globally unique identifier of the event&#8217;s provider as stored in
EvtSystemProviderGuid. This corresponds to the name of the provider in
the <a href="#im_msvistalog_field_SourceName">$SourceName</a> field.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_msvistalog_field_RecordNumber" class="dlist">
<dl>
<dt class="hdlist1"><code>$RecordNumber</code> (type: <a href="#lang_type_integer">integer</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The number of the event record.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_msvistalog_field_RelatedActivityID" class="dlist">
<dl>
<dt class="hdlist1"><code>$RelatedActivityID</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The RelatedActivityID as stored in EvtSystemRelatedActivityID.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_msvistalog_field_Severity" class="dlist">
<dl>
<dt class="hdlist1"><code>$Severity</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The normalized severity name of the event. See
<a href="#im_msvistalog_field_SeverityValue">$SeverityValue</a>.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_msvistalog_field_SeverityValue" class="dlist">
<dl>
<dt class="hdlist1"><code>$SeverityValue</code> (type: <a href="#lang_type_integer">integer</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The normalized severity number of the event, mapped as follows.</p>
</div>
<table class="tableblock frame-all grid-all">
<colgroup>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Event Log Severity</th>
<th class="tableblock halign-left valign-top">Normalized Severity</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">0/Audit Success</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">2/INFO</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">0/Audit Failure</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">4/ERROR</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">1/Critical</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">5/CRITICAL</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">2/Error</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">4/ERROR</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">3/Warning</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">3/WARNING</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">4/Information</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">2/INFO</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">5/Verbose</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">1/DEBUG</p></td>
</tr>
</tbody>
</table>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_msvistalog_field_SourceName" class="dlist">
<dl>
<dt class="hdlist1"><code>$SourceName</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The event source which produced the event, from the
	EvtSystemProviderName field.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_msvistalog_field_Task" class="dlist">
<dl>
<dt class="hdlist1"><code>$Task</code> (type: <a href="#lang_type_integer">integer</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The task number from the EvtSystemTask field.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_msvistalog_field_ThreadID" class="dlist">
<dl>
<dt class="hdlist1"><code>$ThreadID</code> (type: <a href="#lang_type_integer">integer</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The thread identifier of the event producer as in
	EvtSystemThreadID.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_msvistalog_field_UserID" class="dlist">
<dl>
<dt class="hdlist1"><code>$UserID</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The Security Identifier (SID) which resolves to
<a href="#im_msvistalog_field_AccountName">$AccounteName</a>, stored
in EvtSystemUserID.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_msvistalog_field_Version" class="dlist">
<dl>
<dt class="hdlist1"><code>$Version</code> (type: <a href="#lang_type_integer">integer</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The Version number of the event as in EvtSystemVersion.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="im_msvistalog_config_examples"><a class="anchor" href="#im_msvistalog_config_examples"></a>5.9.3. Examples</h4>
<div class="exampleblock">
<div class="title">Example 86. Forwarding Windows EventLog from Windows to a Remote Host in Syslog Format</div>
<div class="content">
<div class="paragraph">
<p>This configuration collects Windows EventLog with the specified
query. BSD Syslog headers are added and the messages are forwarded to
a remote host via TCP.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">syslog</span><span class="tag">&gt;</span>
    Module          xm_syslog
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">eventlog</span><span class="tag">&gt;</span>
    Module          im_msvistalog
    <span class="tag">&lt;QueryXML&gt;</span>
        <span class="tag">&lt;QueryList&gt;</span>
            <span class="tag">&lt;Query</span> <span class="attribute-name">Id</span>=<span class="string"><span class="delimiter">'</span><span class="content">0</span><span class="delimiter">'</span></span><span class="tag">&gt;</span>
                <span class="tag">&lt;Select</span> <span class="attribute-name">Path</span>=<span class="string"><span class="delimiter">'</span><span class="content">Application</span><span class="delimiter">'</span></span><span class="tag">&gt;</span>*<span class="tag">&lt;/Select&gt;</span>
                <span class="tag">&lt;Select</span> <span class="attribute-name">Path</span>=<span class="string"><span class="delimiter">'</span><span class="content">Security</span><span class="delimiter">'</span></span><span class="tag">&gt;</span>*[System/Level<span class="entity">&amp;lt;</span>4]<span class="tag">&lt;/Select&gt;</span>
                <span class="tag">&lt;Select</span> <span class="attribute-name">Path</span>=<span class="string"><span class="delimiter">'</span><span class="content">System</span><span class="delimiter">'</span></span><span class="tag">&gt;</span>*<span class="tag">&lt;/Select&gt;</span>
            <span class="tag">&lt;/Query&gt;</span>
        <span class="tag">&lt;/QueryList&gt;</span>
    <span class="tag">&lt;/QueryXML&gt;</span>
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">tcp</span><span class="tag">&gt;</span>
    Module          om_tcp
    Host            192.168.1.1
    Port            514
    Exec            to_syslog_bsd();
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">eventlog_to_tcp</span><span class="tag">&gt;</span>
    Path            eventlog =<span class="error">&gt;</span> tcp
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="im_null"><a class="anchor" href="#im_null"></a>5.10. Null (im_null)</h3>
<div class="paragraph">
<p>This module does not generate any input, so basically it does nothing.
Yet it can be useful for creating a dummy route, for testing purposes,
or for <a href="#config_module_schedule">Scheduled</a> NXLog code
execution. The <em>im_null</em> module accepts only the
<a href="#config_module_common">common module directives</a>. See
<a href="#config_example_routes">this example</a> for usage.</p>
</div>
</div>
<div class="sect2">
<h3 id="im_ssl"><a class="anchor" href="#im_ssl"></a>5.11. TLS/SSL (im_ssl)</h3>
<div class="paragraph">
<p>The <em>im_ssl</em> module uses the OpenSSL library to provide an SSL/TLS
transport. It behaves like the <a href="#im_tcp">im_tcp</a> module, except that
an SSL handshake is performed at connection time and the data is sent
over a secure channel. Log messages transferred over plain TCP can be
eavesdropped or even altered with a man-in-the-middle attack, while
the <em>im_ssl</em> module provides a secure log message transport.</p>
</div>
<div class="sect3">
<h4 id="im_ssl_config"><a class="anchor" href="#im_ssl_config"></a>5.11.1. Configuration</h4>
<div class="paragraph">
<p>The <em>im_ssl</em> module accepts the following directives in addition to the
<a href="#config_module_common">common module directives</a>.</p>
</div>
<div id="im_ssl_config_host" class="dlist">
<dl>
<dt class="hdlist1">Host</dt>
<dd>
<p>The module will accept connections on this IP address or DNS
hostname. The default is <code>localhost</code>.</p>
</dd>
</dl>
</div>
<div id="im_ssl_config_port" class="dlist">
<dl>
<dt class="hdlist1">Port</dt>
<dd>
<p>The module will listen for incoming connections on this port
number. The default is port 514.</p>
</dd>
</dl>
</div>
<hr>
<div id="im_ssl_config_allowuntrusted" class="dlist">
<dl>
<dt class="hdlist1">AllowUntrusted</dt>
<dd>
<p>This boolean directive specifies that the remote
connection should be allowed without certificate verification. If
set to TRUE the remote will be able to connect with an unknown or
self-signed certificate. The default value is FALSE: all connections
must present a trusted certificate.</p>
</dd>
</dl>
</div>
<div id="im_ssl_config_cadir" class="dlist">
<dl>
<dt class="hdlist1">CADir</dt>
<dd>
<p>This specifies the path to a directory containing certificate
authority (CA) certificates, which will be used to check the
certificate of the remote socket. The certificate filenames in this
directory must be in the OpenSSL hashed format.</p>
</dd>
</dl>
</div>
<div id="im_ssl_config_cafile" class="dlist">
<dl>
<dt class="hdlist1">CAFile</dt>
<dd>
<p>This specifies the path of the certificate authority (CA)
certificate, which will be used to check the certificate of the
remote socket.</p>
</dd>
</dl>
</div>
<div id="im_ssl_config_certfile" class="dlist">
<dl>
<dt class="hdlist1">CertFile</dt>
<dd>
<p>This specifies the path of the certificate file to be used
for the SSL handshake.</p>
</dd>
</dl>
</div>
<div id="im_ssl_config_certkeyfile" class="dlist">
<dl>
<dt class="hdlist1">CertKeyFile</dt>
<dd>
<p>This specifies the path of the certificate key file to
be used for the SSL handshake.</p>
</dd>
</dl>
</div>
<div id="im_ssl_config_keypass" class="dlist">
<dl>
<dt class="hdlist1">KeyPass</dt>
<dd>
<p>With this directive, a password can be supplied for the
certificate key file defined in
<a href="#im_ssl_config_certkeyfile">CertKeyFile</a>. This directive is not
needed for passwordless private keys.</p>
</dd>
</dl>
</div>
<div id="im_ssl_config_crldir" class="dlist">
<dl>
<dt class="hdlist1">CRLDir</dt>
<dd>
<p>This specifies the path to a directory containing certificate
revocation lists (CRLs), which will be consulted when checking the
certificate of the remote socket. The certificate filenames in this
directory must be in the OpenSSL hashed format.</p>
</dd>
</dl>
</div>
<div id="im_ssl_config_crlfile" class="dlist">
<dl>
<dt class="hdlist1">CRLFile</dt>
<dd>
<p>This specifies the path of the certificate revocation list
(CRL) which will be consulted when checking the certificate of the
remote socket.</p>
</dd>
</dl>
</div>
<div id="im_ssl_config_requirecert" class="dlist">
<dl>
<dt class="hdlist1">RequireCert</dt>
<dd>
<p>This boolean value specifies that the remote must
present a certificate. If set to TRUE and there is no certificate
presented during the connection handshake, the connection will be
refused. The default value is TRUE: each connection must use a
certificate.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="im_ssl_fields"><a class="anchor" href="#im_ssl_fields"></a>5.11.2. Fields</h4>
<div class="paragraph">
<p>The following fields are used by <em>im_ssl</em>.</p>
</div>
<div id="im_ssl_field_raw_event" class="dlist">
<dl>
<dt class="hdlist1"><code>$raw_event</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The received string.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_ssl_field_MessageSourceAddress" class="dlist">
<dl>
<dt class="hdlist1"><code>$MessageSourceAddress</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The IP address of the remote host.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="im_ssl_config_examples"><a class="anchor" href="#im_ssl_config_examples"></a>5.11.3. Examples</h4>
<div class="exampleblock">
<div class="title">Example 87. Accepting Binary Logs From Another NXLog Agent</div>
<div class="content">
<div class="paragraph">
<p>This configuration accepts secured log messages in the NXLog
<a href="#config_inputtype_binary">binary</a> format and writes them to file.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Input</span> <span class="attribute-name">ssl</span><span class="tag">&gt;</span>
    Module      im_ssl
    Host        localhost
    Port        23456
    CAFile      %CERTDIR%/ca.pem
    CertFile    %CERTDIR%/client-cert.pem
    CertKeyFile %CERTDIR%/client-key.pem
    KeyPass     secret
    InputType   Binary
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">file</span><span class="tag">&gt;</span>
    Module      om_file
    File        &quot;tmp/output&quot;
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">ssl_to_file</span><span class="tag">&gt;</span>
    Path        ssl =<span class="error">&gt;</span> file
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="im_tcp"><a class="anchor" href="#im_tcp"></a>5.12. TCP (im_tcp)</h3>
<div class="paragraph">
<p>This module accepts TCP connections on the configured address and
port. It can handle multiple simultaneous connections. The TCP
transfer protocol provides more reliable log transmission than UDP.
If security is a concern, consider using the <a href="#im_ssl">im_ssl</a> module
instead.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
This module provides no access control. Firewall rules can be
      used to deny connections from certain hosts.
</td>
</tr>
</table>
</div>
<div class="sect3">
<h4 id="im_tcp_config"><a class="anchor" href="#im_tcp_config"></a>5.12.1. Configuration</h4>
<div class="paragraph">
<p>The <em>im_tcp</em> module accepts the following directives in addition to the
<a href="#config_module_common">common module directives</a>.</p>
</div>
<div id="im_tcp_config_host" class="dlist">
<dl>
<dt class="hdlist1">Host</dt>
<dd>
<p>The module will accept connections on this IP address or DNS
hostname. For security, the default listen address is <code>localhost</code> (the
<em>localhost</em> loopback address is not accessible from the outside). To receive
logs from remote hosts, the address specified here must be accessible. The
<em>any</em> address <code>0.0.0.0</code> is commonly used here.</p>
</dd>
</dl>
</div>
<div id="im_tcp_config_port" class="dlist">
<dl>
<dt class="hdlist1">Port</dt>
<dd>
<p>The module will listen for incoming connections on this port
number. The default port is 514 if this directive is not specified.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="im_tcp_fields"><a class="anchor" href="#im_tcp_fields"></a>5.12.2. Fields</h4>
<div class="paragraph">
<p>The following fields are used by <em>im_tcp</em>.</p>
</div>
<div id="im_tcp_field_raw_event" class="dlist">
<dl>
<dt class="hdlist1"><code>$raw_event</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The received string.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_tcp_field_MessageSourceAddress" class="dlist">
<dl>
<dt class="hdlist1"><code>$MessageSourceAddress</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The IP address of the remote host.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="im_tcp_config_examples"><a class="anchor" href="#im_tcp_config_examples"></a>5.12.3. Examples</h4>
<div class="exampleblock">
<div class="title">Example 88. Using the im_tcp Module</div>
<div class="content">
<div class="paragraph">
<p>With this configuration, NXLog will listen for TCP connections
on port 1514 and write received log messages to file.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Input</span> <span class="attribute-name">tcp</span><span class="tag">&gt;</span>
    Module  im_tcp
    Host    0.0.0.0
    Port    1514
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">file</span><span class="tag">&gt;</span>
    Module  om_file
    File    &quot;tmp/output&quot;
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">tcp_to_file</span><span class="tag">&gt;</span>
    Path    tcp =<span class="error">&gt;</span> file
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="im_udp"><a class="anchor" href="#im_udp"></a>5.13. UDP (im_udp)</h3>
<div class="paragraph">
<p>This module accepts UDP datagrams on the configured address and
port. UDP is the transport protocol of the legacy BSD Syslog as
described in RFC 3164, so this module can be particularly useful to
receive such messages from older devices which do not support other
transports.</p>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<div class="title">Warning</div>
</td>
<td class="content">
UDP is an unreliable transport protocol, and does not guarantee
         delivery. Messages may not be received or may be truncated. It is
         recommended to use the <a href="#im_tcp">TCP</a> or <a href="#im_ssl">SSL</a> transport
         modules instead, if possible.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>To reduce the likelihood of message loss, consider:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>increasing the socket buffer size with <a href="#im_udp_config_sockbufsize">SockBufSize</a>,</p>
</li>
<li>
<p>raising the route priority by setting the <a href="#config_route_priority">Priority</a>
directive (to a low number such as 1), and</p>
</li>
<li>
<p>adding a <a href="#pm_buffer">pm_buffer</a> instance.</p>
</li>
</ul>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
This module provides no access control. Firewall rules can be
      used to drop log events from certain hosts.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>For parsing Syslog messages, see the <a href="#pm_transformer">pm_transformer</a>
module or the <a href="#xm_syslog_proc_to_syslog_bsd">parse_syslog_bsd()</a>
procedure of <a href="#xm_syslog">xm_syslog</a>.</p>
</div>
<div class="sect3">
<h4 id="im_udp_config"><a class="anchor" href="#im_udp_config"></a>5.13.1. Configuration</h4>
<div class="paragraph">
<p>The <em>im_udp</em> module accepts the following directives in addition to the
<a href="#config_module_common">common module directives</a>.</p>
</div>
<div id="im_udp_config_host" class="dlist">
<dl>
<dt class="hdlist1">Host</dt>
<dd>
<p>The module will accept messages on this IP address or DNS
hostname. The default is <code>localhost</code>.</p>
</dd>
</dl>
</div>
<div id="im_udp_config_port" class="dlist">
<dl>
<dt class="hdlist1">Port</dt>
<dd>
<p>The module will listen for incoming connections on this port
number. The default is port 514.</p>
</dd>
</dl>
</div>
<hr>
<div id="im_udp_config_sockbufsize" class="dlist">
<dl>
<dt class="hdlist1">SockBufSize</dt>
<dd>
<p>This optional directive sets the socket buffer size
(SO_RCVBUF) to the value specified. If not set, the operating system
defaults are used. If UDP packet loss is occurring at the kernel
level, setting this to a high value (such as <code>150000000</code>) may
help. On Windows systems the default socket buffer size is extremely
low, and using this option is highly recommended.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="im_udp_fields"><a class="anchor" href="#im_udp_fields"></a>5.13.2. Fields</h4>
<div class="paragraph">
<p>The following fields are used by <em>im_udp</em>.</p>
</div>
<div id="im_udp_field_raw_event" class="dlist">
<dl>
<dt class="hdlist1"><code>$raw_event</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The received string.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="im_udp_field_MessageSourceAddress" class="dlist">
<dl>
<dt class="hdlist1"><code>$MessageSourceAddress</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The IP address of the remote host.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="im_udp_config_examples"><a class="anchor" href="#im_udp_config_examples"></a>5.13.3. Examples</h4>
<div class="exampleblock">
<div class="title">Example 89. Using the im_udp Module</div>
<div class="content">
<div class="paragraph">
<p>This configuration accepts log messages via UDP and writes them to
file.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Input</span> <span class="attribute-name">udp</span><span class="tag">&gt;</span>
    Module  im_udp
    Host    192.168.1.1
    Port    514
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">file</span><span class="tag">&gt;</span>
    Module  om_file
    File    &quot;tmp/output&quot;
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">udp_to_file</span><span class="tag">&gt;</span>
    Path    udp =<span class="error">&gt;</span> file
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="im_uds"><a class="anchor" href="#im_uds"></a>5.14. Unix Domain Sockets (im_uds)</h3>
<div class="paragraph">
<p>This module allows log messages to be received over a Unix domain
socket. Unix systems traditionally have a /dev/log or similar socket
used by the system logger to accept messages. Applications use the
syslog(3) system call to send messages to the system logger.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
This module supports SOCK_DGRAM type sockets only.
</td>
</tr>
</table>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
It is recommended to disable
      <a href="#config_module_flowcontrol">FlowControl</a> when this module is
      used to collect local Syslog messages from the /dev/log Unix
      domain socket. Otherwise, if the corresponding Output queue
      becomes full, the syslog() system call will block in any
      programs trying to write to the system log and an unresponsive
      system may result.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>For parsing Syslog messages, see the <a href="#pm_transformer">pm_transformer</a>
module or the <a href="#xm_syslog_proc_to_syslog_bsd">parse_syslog_bsd()</a>
procedure of <a href="#xm_syslog">xm_syslog</a>.</p>
</div>
<div class="sect3">
<h4 id="im_uds_config"><a class="anchor" href="#im_uds_config"></a>5.14.1. Configuration</h4>
<div class="paragraph">
<p>The <em>im_uds</em> module accepts the following directives in addition to the
<a href="#config_module_common">common module directives</a>.</p>
</div>
<div id="im_uds_config_uds" class="dlist">
<dl>
<dt class="hdlist1">UDS</dt>
<dd>
<p>This specifies the path of the Unix domain socket. The default
is <code>/dev/log</code>.</p>
</dd>
</dl>
</div>
<hr>
<div id="im_uds_config_inputtype" class="dlist">
<dl>
<dt class="hdlist1">InputType</dt>
<dd>
<p>See the <a href="#config_inputtype">InputType</a> directive in the
list of common module directives. This defaults to <code>dgram</code>.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="im_uds_config_examples"><a class="anchor" href="#im_uds_config_examples"></a>5.14.2. Examples</h4>
<div class="exampleblock">
<div class="title">Example 90. Using the im_uds Module</div>
<div class="content">
<div class="paragraph">
<p>This configuration will accept logs via the specified socket and write
them to file.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Input</span> <span class="attribute-name">uds</span><span class="tag">&gt;</span>
    Module      im_uds
    UDS         /dev/log
    FlowControl False
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">file</span><span class="tag">&gt;</span>
    Module      om_file
    File        &quot;/var/log/messages&quot;
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">uds_to_file</span><span class="tag">&gt;</span>
    Path        uds =<span class="error">&gt;</span> file
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="processor-modules"><a class="anchor" href="#processor-modules"></a>6. Processor Modules</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Processor modules can be used to process log messages in the log
message path between configured Input and Output modules.</p>
</div>
<div class="sect2">
<h3 id="pm_blocker"><a class="anchor" href="#pm_blocker"></a>6.1. Blocker (pm_blocker)</h3>
<div class="paragraph">
<p>This module blocks log messages and can be used to simulate a blocked
route. When the module blocks the data flow, log messages are first
accumulated in the buffers, and then the flow control mechanism pauses
the input modules. Using the <a href="#pm_blocker_proc_block">block()</a>
procedure, it is possible to programmatically stop or resume the data
flow. It can be useful for real-world scenarios as well as
testing. See the examples below. When the module starts, the blocking
mode is disabled by default (it operates like <a href="#pm_null">pm_null</a>
would).</p>
</div>
<div class="sect3">
<h4 id="pm_blocker_config"><a class="anchor" href="#pm_blocker_config"></a>6.1.1. Configuration</h4>
<div class="paragraph">
<p>The <em>pm_blocker</em> module accepts only the <a href="#config_module_common">common
module directives</a>.</p>
</div>
</div>
<div class="sect3">
<h4 id="pm_blocker_funcs"><a class="anchor" href="#pm_blocker_funcs"></a>6.1.2. Functions</h4>
<div class="paragraph">
<p>The following functions are exported by <em>pm_blocker</em>.</p>
</div>
<div id="pm_blocker_func_is_blocking" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_boolean">boolean</a> <code>is_blocking()</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Return TRUE if the module is currently blocking the data flow, FALSE
otherwise.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="pm_blocker_procs"><a class="anchor" href="#pm_blocker_procs"></a>6.1.3. Procedures</h4>
<div class="paragraph">
<p>The following procedures are exported by <em>pm_blocker</em>.</p>
</div>
<div id="pm_blocker_proc_block" class="dlist">
<dl>
<dt class="hdlist1"><code>block(<a href="#lang_type_boolean">boolean</a> mode);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>When <em>mode</em> is TRUE, the module will block. A <code>block(FALSE)</code> should be
called from a Schedule block or another module, it might not get
invoked if the queue is already full.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="pm_blocker_config_examples"><a class="anchor" href="#pm_blocker_config_examples"></a>6.1.4. Examples</h4>
<div class="exampleblock">
<div class="title">Example 91. Using the pm_blocker Module</div>
<div class="content">
<div class="paragraph">
<p>In this example messages are received over UDP and forwarded to
another host via TCP. The log data is forwarded during non-working
hours (between 7pm and 8am). During working hours, the data is
buffered on the disk.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Input</span> <span class="attribute-name">udp</span><span class="tag">&gt;</span>
    Module  im_udp
    Host    0.0.0.0
    Port    1514
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Processor</span> <span class="attribute-name">buffer</span><span class="tag">&gt;</span>
    Module  pm_buffer
    # 100 MB disk buffer
    MaxSize 102400
    Type    disk
<span class="tag">&lt;/Processor&gt;</span>

<span class="tag">&lt;Processor</span> <span class="attribute-name">blocker</span><span class="tag">&gt;</span>
    Module  pm_blocker
    <span class="tag">&lt;Schedule&gt;</span>
        When    0 8 * * *
        Exec    blocker-<span class="error">&gt;</span>block(TRUE);
    <span class="tag">&lt;/Schedule&gt;</span>
    <span class="tag">&lt;Schedule&gt;</span>
        When    0 19 * * *
        Exec    blocker-<span class="error">&gt;</span>block(FALSE);
    <span class="tag">&lt;/Schedule&gt;</span>
<span class="tag">&lt;/Processor&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">tcp</span><span class="tag">&gt;</span>
    Module  om_tcp
    Host    192.168.1.1
    Port    1514
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">udp_to_tcp</span><span class="tag">&gt;</span>
    Path    udp =<span class="error">&gt;</span> buffer =<span class="error">&gt;</span> blocker =<span class="error">&gt;</span> tcp
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="pm_buffer"><a class="anchor" href="#pm_buffer"></a>6.2. Buffer (pm_buffer)</h3>
<div class="paragraph">
<p>Messages received over UDP may be dropped by the operating system if
packets are not read from the message buffer fast enough. Some logging
subsystems using a small circular buffer can overwrite old logs in the
buffer if it is not read, also resulting in loss of log
data. Buffering can help in such situations.</p>
</div>
<div class="paragraph">
<p>The <em>pm_buffer</em> module supports disk- and memory-based log message
buffering. If both are required, multiple <em>pm_buffer</em> instances can be
used with different settings. Because a memory buffer can be faster,
though its size is limited, combining memory and disk based buffering
can be a good idea if buffering is frequently used.</p>
</div>
<div class="paragraph">
<p>The disk-based buffering mode stores the log message data in chunks.
When all the data is successfully forwarded from a chunk, it is then
deleted in order to save disk space.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
Using <em>pm_buffer</em> is only recommended when there is a chance of
      message loss. The built-in flow control in NXLog ensures
      that messages will not be read by the input module until the
      output side can send, store, or forward. When reading from files
      (with <a href="#im_file">im_file</a>) or the Windows EventLog (with
      <a href="#im_mseventlog">im_mseventlog</a> or
      <a href="#im_msvistalog">im_msvistalog</a>) it is rarely necessary to use
      the <em>pm_buffer</em> module unless log rotation is used. During a
      rotation, there is a possibility of dropping some data while the
      output module (<a href="#im_tcp">im_tcp</a>, for example) is being blocked.
</td>
</tr>
</table>
</div>
<div class="sect3">
<h4 id="pm_buffer_config"><a class="anchor" href="#pm_buffer_config"></a>6.2.1. Configuration</h4>
<div class="paragraph">
<p>The <em>pm_buffer</em> module accepts the following directives in addition to the
<a href="#config_module_common">common module directives</a>.  The
<a href="#pm_buffer_config_maxsize">MaxSize</a> and <a href="#pm_buffer_config_type">Type</a>
directives are required.</p>
</div>
<div id="pm_buffer_config_maxsize" class="dlist">
<dl>
<dt class="hdlist1">MaxSize</dt>
<dd>
<p>This mandatory directive specifies the size of the buffer in
kilobytes.</p>
</dd>
</dl>
</div>
<div id="pm_buffer_config_type" class="dlist">
<dl>
<dt class="hdlist1">Type</dt>
<dd>
<p>This directive can be set to either <code>Mem</code> or <code>Disk</code> to select
memory- or disk-based buffering.</p>
</dd>
</dl>
</div>
<hr>
<div id="pm_buffer_config_directory" class="dlist">
<dl>
<dt class="hdlist1">Directory</dt>
<dd>
<p>This directory will be used to store the disk buffer file
chunks. This is only valid if <a href="#pm_buffer_config_type">Type</a> is set
to <code>Disk</code>.</p>
</dd>
</dl>
</div>
<div id="pm_buffer_config_warnlimit" class="dlist">
<dl>
<dt class="hdlist1">WarnLimit</dt>
<dd>
<p>This directive specifies an optional limit, smaller than
<a href="#pm_buffer_config_maxsize">MaxSize</a>, which will trigger a warning
message when reached. The log message will not be generated again
until the buffer size drops to half of <strong>WarnLimit</strong> and reaches it
again in order to protect against a warning message flood.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="pm_buffer_funcs"><a class="anchor" href="#pm_buffer_funcs"></a>6.2.2. Functions</h4>
<div class="paragraph">
<p>The following functions are exported by <em>pm_buffer</em>.</p>
</div>
<div id="pm_buffer_func_buffer_count" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_integer">integer</a> <code>buffer_count()</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Return the number of log messages held in the memory buffer.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="pm_buffer_func_buffer_size" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_integer">integer</a> <code>buffer_size()</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Return the size of the memory buffer in bytes.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="pm_buffer_config_examples"><a class="anchor" href="#pm_buffer_config_examples"></a>6.2.3. Examples</h4>
<div class="exampleblock">
<div class="title">Example 92. Using a Memory Buffer to Protect Against UDP Message Loss</div>
<div class="content">
<div class="paragraph">
<p>This configuration accepts log messages via UDP and forwards them
via TCP. An intermediate memory-based buffer allows the
<a href="#im_udp">im_udp</a> module instance to continue accepting messages even
if the <a href="#om_tcp">om_tcp</a> output stops working (caused by downtime of
the remote host or network issues, for example).</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Input</span> <span class="attribute-name">udp</span><span class="tag">&gt;</span>
    Module      im_udp
    Host        0.0.0.0
    Port        514
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Processor</span> <span class="attribute-name">buffer</span><span class="tag">&gt;</span>
    Module      pm_buffer
    # 1 MB buffer
    MaxSize     1024
    Type        Mem
    # warn at 512k
    WarnLimit   512
<span class="tag">&lt;/Processor&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">tcp</span><span class="tag">&gt;</span>
    Module      om_tcp
    Host        192.168.1.1
    Port        1514
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">udp_to_tcp</span><span class="tag">&gt;</span>
    Path        udp =<span class="error">&gt;</span> buffer =<span class="error">&gt;</span> tcp
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="pm_evcorr"><a class="anchor" href="#pm_evcorr"></a>6.3. Event Correlator (pm_evcorr)</h3>
<div class="paragraph">
<p>The <em>pm_evcorr</em> module provides event correlation functionality in
addition to the already available NXLog language features such
as <a href="#lang_variables">variables</a> and <a href="#lang_stat">statistical counters</a>
which can be also used for event correlation purposes.</p>
</div>
<div class="paragraph">
<p>This module was greatly inspired by the Perl based correlation tool
<a href="http://simple-evcorr.github.io/">SEC</a>. Some of the rules of the
<em>pm_evcorr</em> module were designed to mimic those available in SEC. This
module aims to be a better alternative to SEC with the following
advantages:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>The correlation rules in SEC work with the current time. With
<em>pm_evcorr</em> it is possible to specify a time field which is used for
elapsed time calculation making offline event correlation possible.</p>
</li>
<li>
<p>SEC uses regular expressions extensively, which can become quite
slow if there are many correlation rules. In contrast, this module
can correlate pre-processed messages using fields from, for example,
the <a href="#pm_pattern">pattern matcher</a> and <a href="#xm_syslog">Syslog</a> parsers
without requiring the use of regular expressions (though these are
also available for use by correlation rules). Thus testing
conditions can be significantly faster when simple comparison is
used instead of regular expression based pattern matching.</p>
</li>
<li>
<p>This module was designed to operate on fields, making it possible to
correlate structured logs in addition to simple free-form log
messages.</p>
</li>
<li>
<p>Most importantly, this module is written in C, providing performance
benefits (where SEC is written in pure Perl).</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The rulesets of this module can use a context. A context is an
expression which is evaluated during runtime to a value and the
correlation rule is checked in the context of this value. For example,
to count the number of failed logins per user and alert if the failed
logins exceed 3 for the user, the <code>$AccountName</code> would be used as the
context. There is a separate context storage for each correlation rule
instance. For global contexts accessible from all rule instances, see
<a href="#lang_variables">module variables</a> and <a href="#lang_stat">statistical
counters</a>.</p>
</div>
<div class="sect3">
<h4 id="pm_evcorr_config"><a class="anchor" href="#pm_evcorr_config"></a>6.3.1. Configuration</h4>
<div class="paragraph">
<p>The <em>pm_evcorr</em> module accepts the following directives in addition to
the <a href="#config_module_common">common module directives</a>.</p>
</div>
<div class="paragraph">
<p>The <em>pm_evcorr</em> configuration contains correlation rules which are evaluated for
each log message processed by the module. Currently there are five rule types
supported by pm_evcorr: <a href="#pm_evcorr_config_absence">Absence</a>,
<a href="#pm_evcorr_config_pair">Pair</a>, <a href="#pm_evcorr_config_simple">Simple</a>,
<a href="#pm_evcorr_config_suppressed">Suppressed</a>, and
<a href="#pm_evcorr_config_thresholded">Thresholded</a>. These rules are defined in
configuration blocks. The rules are evaluated in the order they are
defined. For example, a correlation rule can change a state, variable, or
field which can be then used by a later rule. <a href="#config_general_include">File
inclusion</a> can be useful to store correlation rules in a separate file.</p>
</div>
<div id="pm_evcorr_config_absence" class="dlist">
<dl>
<dt class="hdlist1">Absence</dt>
<dd>
<p>This rule type does the opposite of
<a href="#pm_evcorr_config_pair">Pair</a>. When
<a href="#pm_evcorr_config_absence_triggercondition">TriggerCondition</a>
evaluates to TRUE, this rule type will wait
<a href="#pm_evcorr_config_absence_interval">Interval</a> seconds for
<a href="#pm_evcorr_config_absence_requiredcondition">RequiredCondition</a> to
become TRUE. If it does not become TRUE, it executes the
statement(s) in the <a href="#pm_evcorr_config_absence_exec">Exec</a>
directive(s).</p>
<div class="openblock">
<div class="content">
<div id="pm_evcorr_config_absence_context" class="dlist">
<dl>
<dt class="hdlist1">Context</dt>
<dd>
<p>This optional directive specifies an expression to be used as the
context. It must evaluate to a value. Usually a field is specified here.</p>
</dd>
</dl>
</div>
<div id="pm_evcorr_config_absence_exec" class="dlist">
<dl>
<dt class="hdlist1">Exec</dt>
<dd>
<p>One or more <strong>Exec</strong> directives must be specified, each taking a
<a href="#lang_statements">statement</a> as argument.</p>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
The evaluation of this Exec is not triggered by a log event; thus it
      does not make sense to use log data related operations such as accessing
      fields.
</td>
</tr>
</table>
</div>
</dd>
</dl>
</div>
<div id="pm_evcorr_config_absence_interval" class="dlist">
<dl>
<dt class="hdlist1">Interval</dt>
<dd>
<p>This mandatory directive takes an integer argument specifying the
number of seconds to wait for
<a href="#pm_evcorr_config_absence_requiredcondition">RequiredCondition</a> to become
TRUE. Its value must be greater than 0. The
<a href="#pm_evcorr_config_timefield">TimeField</a> directive is used to calculate
time.</p>
</dd>
</dl>
</div>
<div id="pm_evcorr_config_absence_requiredcondition" class="dlist">
<dl>
<dt class="hdlist1">RequiredCondition</dt>
<dd>
<p>This mandatory directive takes an expression as argument
which must evaluate to a <a href="#lang_type_boolean">boolean</a> value. When this
evaluates to TRUE after
<a href="#pm_evcorr_config_absence_triggercondition">TriggerCondition</a> evaluated to
TRUE within <a href="#pm_evcorr_config_absence_interval">Interval</a> seconds, the
statement(s) in the <a href="#pm_evcorr_config_absence_exec">Exec</a> directive(s) are
NOT executed.</p>
</dd>
</dl>
</div>
<div id="pm_evcorr_config_absence_triggercondition" class="dlist">
<dl>
<dt class="hdlist1">TriggerCondition</dt>
<dd>
<p>This mandatory directive takes an expression as argument
which must evaluate to a <a href="#lang_type_boolean">boolean</a> value.</p>
</dd>
</dl>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="pm_evcorr_config_pair" class="dlist">
<dl>
<dt class="hdlist1">Pair</dt>
<dd>
<p>When
<a href="#pm_evcorr_config_pair_triggercondition">TriggerCondition</a>
evaluates to TRUE, this rule type will wait
<a href="#pm_evcorr_config_pair_interval">Interval</a> seconds for
<a href="#pm_evcorr_config_pair_requiredcondition">RequiredCondition</a> to
become TRUE. It then executes the statement(s) in the
<a href="#pm_evcorr_config_pair_exec">Exec</a> directive(s).</p>
<div class="openblock">
<div class="content">
<div id="pm_evcorr_config_pair_context" class="dlist">
<dl>
<dt class="hdlist1">Context</dt>
<dd>
<p>This optional directive specifies an expression to be used as the
context. It must evaluate to a value. Usually a field is specified here.</p>
</dd>
</dl>
</div>
<div id="pm_evcorr_config_pair_exec" class="dlist">
<dl>
<dt class="hdlist1">Exec</dt>
<dd>
<p>One or more <strong>Exec</strong> directives must be specified, each taking a
<a href="#lang_statements">statement</a> as argument.</p>
</dd>
</dl>
</div>
<div id="pm_evcorr_config_pair_interval" class="dlist">
<dl>
<dt class="hdlist1">Interval</dt>
<dd>
<p>This directive takes an integer argument specifying the number of
seconds to wait for
<a href="#pm_evcorr_config_pair_requiredcondition">RequiredCondition</a> to become
TRUE. If this directive is <code>0</code> or not specified, the rule will wait
indefinitely for
<a href="#pm_evcorr_config_pair_requiredcondition">RequiredCondition</a> to become
TRUE. The <a href="#pm_evcorr_config_timefield">TimeField</a> directive is used to
calculate time.</p>
</dd>
</dl>
</div>
<div id="pm_evcorr_config_pair_requiredcondition" class="dlist">
<dl>
<dt class="hdlist1">RequiredCondition</dt>
<dd>
<p>This mandatory directive takes an expression as argument
which must evaluate to a <a href="#lang_type_boolean">boolean</a> value. When this
evaluates to TRUE after
<a href="#pm_evcorr_config_pair_triggercondition">TriggerCondition</a> evaluated to
TRUE within <a href="#pm_evcorr_config_pair_interval">Interval</a> seconds, the
statement(s) in the <a href="#pm_evcorr_config_pair_exec">Exec</a> directive(s) are
executed.</p>
</dd>
</dl>
</div>
<div id="pm_evcorr_config_pair_triggercondition" class="dlist">
<dl>
<dt class="hdlist1">TriggerCondition</dt>
<dd>
<p>This mandatory directive takes an expression as argument
which must evaluate to a <a href="#lang_type_boolean">boolean</a> value.</p>
</dd>
</dl>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="pm_evcorr_config_simple" class="dlist">
<dl>
<dt class="hdlist1">Simple</dt>
<dd>
<p>This rule type is essentially the same as the
<a href="#config_module_exec">Exec</a> directive supported by all
modules. Because <a href="#config_module_exec">Exec</a>s are evaluated before
the correlation rules, the <strong>Simple</strong> rule was also needed to be able
to evaluate a statement as the other rules do, following the rule
order. The <strong>Simple</strong> block has one directive also with the same name.</p>
<div id="pm_evcorr_config_simple_exec" class="dlist">
<dl>
<dt class="hdlist1">Exec</dt>
<dd>
<p>One or more <strong>Exec</strong> directives must be specified, with a
<a href="#lang_statements">statement</a> as argument.</p>
</dd>
</dl>
</div>
</dd>
</dl>
</div>
<div id="pm_evcorr_config_stop" class="dlist">
<dl>
<dt class="hdlist1">Stop</dt>
<dd>
<p>This rule will stop evaluating successive rules if the
<a href="#pm_evcorr_config_stop_condition">Condition</a> evaluates to TRUE. The
optional <a href="#pm_evcorr_config_stop_exec">Exec</a> directive will be
evaluated in this case.</p>
<div class="openblock">
<div class="content">
<div id="pm_evcorr_config_stop_condition" class="dlist">
<dl>
<dt class="hdlist1">Condition</dt>
<dd>
<p>This mandatory directive takes an expression as argument which
must evaluate to a <a href="#lang_type_boolean">boolean</a> value. When it evaluates to
TRUE, the correlation rule engine will stop checking any further rules.</p>
</dd>
</dl>
</div>
<div id="pm_evcorr_config_stop_exec" class="dlist">
<dl>
<dt class="hdlist1">Exec</dt>
<dd>
<p>One or more <strong>Exec</strong> directives may be specified, each taking a
<a href="#lang_statements">statement</a> as argument. This will be evaluated when the
specified <a href="#pm_evcorr_config_stop_condition">Condition</a> is satisfied. This
directive is optional.</p>
</dd>
</dl>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="pm_evcorr_config_suppressed" class="dlist">
<dl>
<dt class="hdlist1">Suppressed</dt>
<dd>
<p>This rule type matches the given condition. If the
condition evaluates to TRUE, the statement specified with the
<a href="#pm_evcorr_config_suppressed_exec">Exec</a> directive is
evaluated. The rule will then ignore any log messages for the time
specified with <a href="#pm_evcorr_config_suppressed_interval">Interval</a>
directive. This rule is useful for avoiding creating multiple alerts
in a short period when a condition is satisfied.</p>
<div class="openblock">
<div class="content">
<div id="pm_evcorr_config_suppressed_condition" class="dlist">
<dl>
<dt class="hdlist1">Condition</dt>
<dd>
<p>This mandatory directive takes an expression as argument which
must evaluate to a <a href="#lang_type_boolean">boolean</a> value.</p>
</dd>
</dl>
</div>
<div id="pm_evcorr_config_suppressed_context" class="dlist">
<dl>
<dt class="hdlist1">Context</dt>
<dd>
<p>This optional directive specifies an expression to be used as the
context. It must evaluate to a value. Usually a field is specified here.</p>
</dd>
</dl>
</div>
<div id="pm_evcorr_config_suppressed_exec" class="dlist">
<dl>
<dt class="hdlist1">Exec</dt>
<dd>
<p>One or more <strong>Exec</strong> directives must be specified, each taking
a <a href="#lang_statements">statement</a> as argument.</p>
</dd>
</dl>
</div>
<div id="pm_evcorr_config_suppressed_interval" class="dlist">
<dl>
<dt class="hdlist1">Interval</dt>
<dd>
<p>This mandatory directive takes an integer argument specifying the
number of seconds to ignore the condition. The
<a href="#pm_evcorr_config_timefield">TimeField</a> directive is used to calculate
time.</p>
</dd>
</dl>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="pm_evcorr_config_thresholded" class="dlist">
<dl>
<dt class="hdlist1">Thresholded</dt>
<dd>
<p>This rule type will execute the statement(s) in the
<a href="#pm_evcorr_config_thresholded_exec">Exec</a> directive(s) if the
<a href="#pm_evcorr_config_thresholded_condition">Condition</a> evaluates to
TRUE <a href="#pm_evcorr_config_thresholded_threshold">Threshold</a> or more
times during the <a href="#pm_evcorr_config_thresholded_interval">Interval</a>
specified. The advantage of this rule over the use of
<a href="#lang_stat">statistical counters</a> is that the time window is
dynamic and shifts as log messages are processed.</p>
<div class="openblock">
<div class="content">
<div id="pm_evcorr_config_thresholded_condition" class="dlist">
<dl>
<dt class="hdlist1">Condition</dt>
<dd>
<p>This mandatory directive takes an expression as argument which
must evaluate to a <a href="#lang_type_boolean">boolean</a> value.</p>
</dd>
</dl>
</div>
<div id="pm_evcorr_config_thresholded_context" class="dlist">
<dl>
<dt class="hdlist1">Context</dt>
<dd>
<p>This optional directive specifies an expression to be used as the
context. It must evaluate to a value. Usually a field is specified here.</p>
</dd>
</dl>
</div>
<div id="pm_evcorr_config_thresholded_exec" class="dlist">
<dl>
<dt class="hdlist1">Exec</dt>
<dd>
<p>One or more <strong>Exec</strong> directives must be specified, each taking
a <a href="#lang_statements">statement</a> as argument.</p>
</dd>
</dl>
</div>
<div id="pm_evcorr_config_thresholded_interval" class="dlist">
<dl>
<dt class="hdlist1">Interval</dt>
<dd>
<p>This mandatory directive takes an integer argument specifying a
time window for <a href="#pm_evcorr_config_thresholded_condition">Condition</a> to
become TRUE. Its value must be greater than 0. The
<a href="#pm_evcorr_config_timefield">TimeField</a> directive is used to calculate
time. This time window is dynamic, meaning that it will shift.</p>
</dd>
</dl>
</div>
<div id="pm_evcorr_config_thresholded_threshold" class="dlist">
<dl>
<dt class="hdlist1">Threshold</dt>
<dd>
<p>This mandatory directive takes an integer argument specifying the
number of times <a href="#pm_evcorr_config_thresholded_condition">Condition</a> must
evaluate to TRUE within the given time
<a href="#pm_evcorr_config_thresholded_interval">Interval</a>. When the threshold is
reached, the module executes the statement(s) in the
<a href="#pm_evcorr_config_thresholded_exec">Exec</a> directive(s).</p>
</dd>
</dl>
</div>
</div>
</div>
</dd>
</dl>
</div>
<hr>
<div id="pm_evcorr_config_contextcleantime" class="dlist">
<dl>
<dt class="hdlist1">ContextCleanTime</dt>
<dd>
<p>When a Context is used in the correlation rules,
these must be purged from memory after they are expired, otherwise
using too many context values could result in a high memory
usage. This optional directive specifies the interval between
context cleanups, in seconds. By default a <code>60</code> second cleanup
interval is used if any rules use a Context and this directive is
not specified.</p>
</dd>
</dl>
</div>
<div id="pm_evcorr_config_timefield" class="dlist">
<dl>
<dt class="hdlist1">TimeField</dt>
<dd>
<p>This specifies the name of the <a href="#lang_fields">field</a> to
use for calculating elapsed time, such as <code>EventTime</code>. The name of
the field must be specified without the leading dollar sign
(<code>$</code>). If this parameter is not specified, the current time is
assumed. This directive makes it possible to accurately correlate
events based on the event time recorded in the logs and to do
non-real-time event correlation.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="pm_evcorr_config_examples"><a class="anchor" href="#pm_evcorr_config_examples"></a>6.3.2. Examples</h4>
<div class="exampleblock">
<div class="title">Example 93. Correlation Rules</div>
<div class="content">
<div class="paragraph">
<p>This following configuration sample contains a rule for each type.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Input</span> <span class="attribute-name">filein</span><span class="tag">&gt;</span>
    Module          im_file
    File            &quot;modules/processor/evcorr/testinput_evcorr2.txt&quot;
    Exec    if ($raw_event =~ /^(\d\d\d\d-\d\d-\d\d \d\d:\d\d:\d\d) (.+)/) {  \
                    $EventTime = parsedate($1);                               \
                    $Message = $2;                                            \
                    $raw_event = $Message;                                    \
                }
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">internal</span><span class="tag">&gt;</span>
    Module          im_internal
    Exec            $raw_event = $Message;
    Exec            $EventTime = 2010-01-01 00:01:00;
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">fileout</span><span class="tag">&gt;</span>
    Module          om_file
    File            'tmp/output'
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Processor</span> <span class="attribute-name">evcorr</span><span class="tag">&gt;</span>
    Module          pm_evcorr
    TimeField       EventTime

    <span class="tag">&lt;Simple&gt;</span>
    Exec            if $Message =~ /^simple/ $raw_event = &quot;got simple&quot;;
    <span class="tag">&lt;/Simple&gt;</span>

    <span class="tag">&lt;Suppressed&gt;</span>
    # Match input event and execute an action list, but ignore the
    # following matching events for the next $Interval seconds.
    Condition       $Message =~ /^suppressed/
    Interval        30
    Exec            $raw_event = &quot;suppressing..&quot;;
    <span class="tag">&lt;/Suppressed&gt;</span>

    <span class="tag">&lt;Pair&gt;</span>
    # If TriggerCondition is true, wait Interval seconds for
    # RequiredCondition to be true and then do the Exec. If Interval is
    # 0, there is no window on matching.
    TriggerCondition    $Message =~ /^pair-first/
    RequiredCondition   $Message =~ /^pair-second/
    Interval            30
    Exec                $raw_event = &quot;got pair&quot;;
    <span class="tag">&lt;/Pair&gt;</span>

    <span class="tag">&lt;Absence&gt;</span>
    # If TriggerCondition is true, wait Interval seconds for
    # RequiredCondition to be true. If RequiredCondition does not become
    # true within the specified interval then do the Exec.
    TriggerCondition  $Message =~ /^absence-trigger/
    RequiredCondition $Message =~ /^absence-required/
    Interval    10
    Exec        log_info(&quot;'absence-required' not received within 10 secs&quot;);
    <span class="tag">&lt;/Absence&gt;</span>

    <span class="tag">&lt;Thresholded&gt;</span>
    # If the number of events exceeds the given threshold within the
    # interval do the Exec. Same as SingleWithThreshold in SEC.
    Condition       $Message =~ /^thresholded/
    Threshold       3
    Interval        60
    Exec            $raw_event = &quot;got thresholded&quot;;
    <span class="tag">&lt;/Thresholded&gt;</span>

    <span class="tag">&lt;Stop&gt;</span>
    Condition       $EventTime <span class="error">&lt;</span> 2010-01-02 00:00:00
    Exec            log_debug(&quot;got stop&quot;);
    <span class="tag">&lt;/Stop&gt;</span>

    <span class="tag">&lt;Simple&gt;</span>
    # This will be rewritten only if the previous Stop condition is
    # FALSE.
    Exec            $raw_event = &quot;rewritten&quot;;
    <span class="tag">&lt;/Simple&gt;</span>

<span class="tag">&lt;/Processor&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">corr</span><span class="tag">&gt;</span>
    Path            filein, internal =<span class="error">&gt;</span> evcorr =<span class="error">&gt;</span> fileout
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">Input Sample</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="log">2010-01-01 00:00:00 Not simple<span class="line-marker"></span>
2010-01-01 00:00:01 suppressed1 - Suppress kicks in, will log 'suppressing..'<span class="line-marker"></span>
2010-01-01 00:00:10 simple1<span class="line-marker"></span>
2010-01-01 00:00:12 pair-first - now look for pair-second<span class="line-marker"></span>
2010-01-01 00:00:13 thresholded1<span class="line-marker"></span>
2010-01-01 00:00:15 thresholded2<span class="line-marker"></span>
2010-01-01 00:00:19 simple2<span class="line-marker"></span>
2010-01-01 00:00:20 thresholded3 - will log 'got thresholded'<span class="line-marker"></span>
2010-01-01 00:00:21 suppressed2 - suppressed and logged as is<span class="line-marker"></span>
2010-01-01 00:00:22 pair-second - will log 'got pair'<span class="line-marker"></span>
2010-01-01 00:00:23 suppressed3 - suppressed and logged as is<span class="line-marker"></span>
2010-01-01 00:00:25 pair-first<span class="line-marker"></span>
2010-01-01 00:00:26 absence-trigger<span class="line-marker"></span>
2010-01-01 00:00:29 absence-required - will not log 'got absence'<span class="line-marker"></span>
2010-01-01 00:00:46 absence-trigger<span class="line-marker"></span>
2010-01-01 00:00:56 pair-second - will not log 'got pair' because it is over the interval<span class="line-marker"></span>
2010-01-01 00:00:57 absence-required - will log an additional 'absence-required not received within 10 secs'<span class="line-marker"></span>
2010-01-02 00:00:00 this will be rewritten<span class="line-marker"></span>
2010-01-02 00:00:10 this too<span class="line-marker"></span></code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">Output Sample</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="log">Not simple<span class="line-marker"></span>
suppressing..<span class="line-marker"></span>
got simple<span class="line-marker"></span>
pair-first - now look for pair-second<span class="line-marker"></span>
thresholded1<span class="line-marker"></span>
thresholded2<span class="line-marker"></span>
got simple<span class="line-marker"></span>
got thresholded<span class="line-marker"></span>
suppressed2 - suppressed and logged as is<span class="line-marker"></span>
got pair<span class="line-marker"></span>
suppressed3 - suppressed and logged as is<span class="line-marker"></span>
pair-first<span class="line-marker"></span>
absence-trigger<span class="line-marker"></span>
absence-required - will not log 'got absence'<span class="line-marker"></span>
absence-trigger<span class="line-marker"></span>
pair-second - will not log 'got pair' because it is over the interval<span class="line-marker"></span>
absence-required - will log an additional 'absence-required not received within 10 secs'<span class="line-marker"></span>
rewritten<span class="line-marker"></span>
rewritten<span class="line-marker"></span>
'absence-required' not received within 10 secs<span class="line-marker"></span></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="pm_filter"><a class="anchor" href="#pm_filter"></a>6.4. Filter (pm_filter)</h3>
<div class="paragraph">
<p>This is a simple module which forwards log messages if the specified
condition is TRUE.</p>
</div>
<div class="paragraph">
<p>This module has been obsoleted by the NXLog language. Filtering is now
possible in any module with a conditional <a href="#core_proc_drop">drop()</a> procedure
in an <a href="#config_module_exec">Exec</a> block or directive.</p>
</div>
<div class="exampleblock">
<div class="title">Example 94. Filtering Events With drop()</div>
<div class="content">
<div class="paragraph">
<p>This statement drops the current event if the <code>$raw_event</code> field matches the
specified regular expression.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="statement"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
</pre></td>
  <td class="code"><pre>if $raw_event =~ /^Debug/ drop();</pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="pm_filter_config"><a class="anchor" href="#pm_filter_config"></a>6.4.1. Configuration</h4>
<div class="paragraph">
<p>The <em>pm_filter</em> module accepts the following directives in addition to
the <a href="#config_module_common">common module directives</a>.</p>
</div>
<div id="pm_filter_config_condition" class="dlist">
<dl>
<dt class="hdlist1">Condition</dt>
<dd>
<p>This mandatory directive takes an expression as argument
which must evaluate to a <a href="#lang_type_boolean">boolean</a> value. If the
expression does not evaluate to TRUE, the log message is discarded.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="pm_filter_config_examples"><a class="anchor" href="#pm_filter_config_examples"></a>6.4.2. Examples</h4>
<div class="exampleblock">
<div class="title">Example 95. Filtering Messages</div>
<div class="content">
<div class="paragraph">
<p>This configuration retains only log messages that match one of the
regular expressions, all others are discarded.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Input</span> <span class="attribute-name">uds</span><span class="tag">&gt;</span>
    Module      im_uds
    UDS         /dev/log
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Processor</span> <span class="attribute-name">filter</span><span class="tag">&gt;</span>
    Module      pm_filter
    Condition   $raw_event =~ /failed/ or $raw_event =~ /error/
<span class="tag">&lt;/Processor&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">file</span><span class="tag">&gt;</span>
    Module      om_file
    File        &quot;/var/log/error&quot;
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">uds_to_file</span><span class="tag">&gt;</span>
    Path        uds =<span class="error">&gt;</span> filter =<span class="error">&gt;</span> file
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="pm_norepeat"><a class="anchor" href="#pm_norepeat"></a>6.5. De-Duplicator (pm_norepeat)</h3>
<div class="paragraph">
<p>This module can be used to filter out repeating messages. Like Syslog
daemons, this module checks the previous message against the
current. If they match, the current message is dropped. The module
waits one second for duplicated messages to arrive. If duplicates are
detected, the first message is forwarded, the rest are dropped, and a
message containing "last message repeated n times" is sent instead.</p>
</div>
<div class="sect3">
<h4 id="pm_norepeat_config"><a class="anchor" href="#pm_norepeat_config"></a>6.5.1. Configuration</h4>
<div class="paragraph">
<p>The <em>pm_norepeat</em> module accepts the following directives in addition to
the <a href="#config_module_common">common module directives</a>.</p>
</div>
<div id="pm_norepeat_config_checkfields" class="dlist">
<dl>
<dt class="hdlist1">CheckFields</dt>
<dd>
<p>This optional directive takes a comma-separated list of
field names which are used to compare log messages. Only the fields
listed here are compared, the others are ignored. For example, the
<code>$EventTime</code> field will be different in repeating messages, so this
field should not be used in the comparison. If this directive is not
specified, the default field to be checked is <code>$Message</code>.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="pm_norepeat_fields"><a class="anchor" href="#pm_norepeat_fields"></a>6.5.2. Fields</h4>
<div class="paragraph">
<p>The following fields are used by <em>pm_norepeat</em>.</p>
</div>
<div id="pm_norepeat_field_raw_event" class="dlist">
<dl>
<dt class="hdlist1"><code>$raw_event</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>A string containing the <code>last message repeated n times</code>
	message.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="pm_norepeat_field_EventTime" class="dlist">
<dl>
<dt class="hdlist1"><code>$EventTime</code> (type: <a href="#lang_type_datetime">datetime</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The time of the last event or the current time if EventTime
	was not present in the last event.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="pm_norepeat_field_Message" class="dlist">
<dl>
<dt class="hdlist1"><code>$Message</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The same value as <a href="#pm_norepeat_field_raw_event">$raw_event</a>.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="pm_norepeat_field_ProcessID" class="dlist">
<dl>
<dt class="hdlist1"><code>$ProcessID</code> (type: <a href="#lang_type_integer">integer</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The process ID of the NXLog process.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="pm_norepeat_field_Severity" class="dlist">
<dl>
<dt class="hdlist1"><code>$Severity</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The severity name: <code>INFO</code>.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="pm_norepeat_field_SeverityValue" class="dlist">
<dl>
<dt class="hdlist1"><code>$SeverityValue</code> (type: <a href="#lang_type_integer">integer</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The INFO severity level value: <code>2</code>.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="pm_norepeat_field_SourceName" class="dlist">
<dl>
<dt class="hdlist1"><code>$SourceName</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Set to <code>nxlog</code>.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="pm_norepeat_config_examples"><a class="anchor" href="#pm_norepeat_config_examples"></a>6.5.3. Examples</h4>
<div class="exampleblock">
<div class="title">Example 96. Filtering Out Duplicated Messages</div>
<div class="content">
<div class="paragraph">
<p>This configuration reads log messages from the socket. The
<code>$Hostname</code>, <code>$SourceName</code>, and <code>$Message</code> fields are used to detect
duplicates. Then the messages are written to file.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Input</span> <span class="attribute-name">uds</span><span class="tag">&gt;</span>
    Module      im_uds
    UDS         /dev/log
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Processor</span> <span class="attribute-name">norepeat</span><span class="tag">&gt;</span>
    Module      pm_norepeat
    CheckFields Hostname, SourceName, Message
<span class="tag">&lt;/Processor&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">file</span><span class="tag">&gt;</span>
    Module      om_file
    File        &quot;/var/log/messages&quot;
<span class="tag">&lt;/Output&gt;</span>


<span class="tag">&lt;Route</span> <span class="attribute-name">uds_to_file</span><span class="tag">&gt;</span>
    Path        uds =<span class="error">&gt;</span> norepeat =<span class="error">&gt;</span> file
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="pm_null"><a class="anchor" href="#pm_null"></a>6.6. Null (pm_null)</h3>
<div class="paragraph">
<p>This module does not do any special processing, so basically it does
nothing. Yet it can be used with the <a href="#config_module_exec">Exec</a> and
<a href="#config_module_schedule">Schedule</a> directives, like any other module.</p>
</div>
<div class="paragraph">
<p>The <em>pm_null</em> module accepts only the <a href="#config_module_common">common
module directives</a>.</p>
</div>
<div class="paragraph">
<p>See <a href="#xm_syslog_example2">this example</a> for usage.</p>
</div>
</div>
<div class="sect2">
<h3 id="pm_pattern"><a class="anchor" href="#pm_pattern"></a>6.7. Pattern Matcher (pm_pattern)</h3>
<div class="paragraph">
<p>This module makes it possible to execute pattern matching with a
pattern database file in XML format. Using this module is more
efficient than having NXLog regular expression rules listed in
<a href="#config_module_exec">Exec</a> directives, because the <em>pm_pattern</em> module
was designed in such a way that patterns do not need to be matched
linearly. In addition, the module does an automatic on-the-fly pattern
reordering internally for further speed improvements and has a feature
which can be used to tag messages with additional fields useful for
message classification.</p>
</div>
<div class="paragraph">
<p>There are other techniques such as the radix tree which solve the
linearity problem; the drawback is that usually these require the user
to learn a special syntax for specifying patterns. If the log message
is already parsed and is not treated as single line of message, then
it is possible to process only a subset of the patterns which
partially solves the linearity problem. With other performance
improvements employed within the <em>pm_pattern</em> module, its speed can
compare to the other techniques. Yet the <em>pm_pattern</em> module uses
regular expressions which are familiar to users and can easily be
migrated from other tools.</p>
</div>
<div class="paragraph">
<p>Traditionally, pattern matching on log messages has employed a
technique where the log message was one string and the pattern
(regular expression or radix tree based pattern) was executed
against it. To match patterns against logs which contain structured
data (such as the Windows EventLog), this structured data (the fields
of the log) must be converted to a single string. This is a simple but
inefficient method used by many tools.</p>
</div>
<div class="paragraph">
<p>The NXLog patterns defined in the XML pattern database file
can contain more than one field. This allows multi-dimensional pattern
matching. Thus with NXLog&#8217;s <em>pm_pattern</em> module there is no need
to convert all fields into a single string as it can work with
multiple fields.</p>
</div>
<div class="paragraph">
<p>Patterns can be grouped together under pattern groups. Pattern groups
serve an optimization purpose. The group can have an optional
<em>matchfield</em> block which can check a condition. If the condition (such
as <code>$SourceName</code> matches <code>sshd</code>) is satisfied, the <em>pm_pattern</em> module
will descend into the group and check each pattern against the log. If
the pattern group&#8217;s condition did not match (<code>$SourceName</code> was not
<code>sshd</code>), the module can skip all patterns in the group without having
to check each pattern individually.</p>
</div>
<div class="paragraph">
<p>When the <em>pm_pattern</em> module finds a matching pattern, the <code>$PatternID</code>
and <code>$PatternName</code> fields are set on the log message. These can be
used later in conditional processing and correlation rules of the
<a href="#pm_evcorr">pm_evcorr</a> module, for example.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
<div class="paragraph">
<p>The <em>pm_pattern</em> module does not process all patterns. It exits after
the first matching pattern is found. This means that at most one
pattern can match a log message. Multiple patterns that can match the
same subset of logs should be avoided. For example, with two regular
expression patterns <code>^\d+</code> and <code>^\d\d</code>, the second may never be
matched because of the first. The internal order of patterns and
pattern groups is changed dynamically by <em>pm_pattern</em>. Patterns with the
highest match count are placed and tried first. In addition to
performance optimization, setting the value of <code>$PatternID</code> would be
problematic with multiple values because the language does not support
arrays.</p>
</div>
<div class="paragraph">
<p>For a strictly linearly executing pattern matcher, see the
<a href="#config_module_exec">Exec</a> directive.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="sect3">
<h4 id="pm_pattern_config"><a class="anchor" href="#pm_pattern_config"></a>6.7.1. Configuration</h4>
<div class="paragraph">
<p>The <em>pm_pattern</em> module accepts the following directives in addition to
the <a href="#config_module_common">common module directives</a>.</p>
</div>
<div id="pm_pattern_config_patternfile" class="dlist">
<dl>
<dt class="hdlist1">PatternFile</dt>
<dd>
<p>This mandatory directive specifies the name of the
<a href="#pm_pattern_patterndb">pattern database file</a>.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="pm_pattern_fields"><a class="anchor" href="#pm_pattern_fields"></a>6.7.2. Fields</h4>
<div class="paragraph">
<p>The following fields are used by <em>pm_pattern</em>.</p>
</div>
<div id="pm_pattern_field_PatternID" class="dlist">
<dl>
<dt class="hdlist1"><code>$PatternID</code> (type: <a href="#lang_type_integer">integer</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The ID number of the pattern which matched the message.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="pm_pattern_field_PatternName" class="dlist">
<dl>
<dt class="hdlist1"><code>$PatternName</code> (type: <a href="#lang_type_string">string</a>)</dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The name of the pattern which matched the message.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="pm_pattern_config_examples"><a class="anchor" href="#pm_pattern_config_examples"></a>6.7.3. Examples</h4>
<div class="exampleblock">
<div class="title">Example 97. Using the pm_pattern Module</div>
<div class="content">
<div class="paragraph">
<p>This configuration reads BSD Syslog messages from the socket,
processes the messages with a pattern file, and then writes them to
file in JSON format.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">json</span><span class="tag">&gt;</span>
    Module      xm_json
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Extension</span> <span class="attribute-name">syslog</span><span class="tag">&gt;</span>
    Module      xm_syslog
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">uds</span><span class="tag">&gt;</span>
    Module      im_uds
    UDS         /dev/log
    Exec        parse_syslog_bsd();
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Processor</span> <span class="attribute-name">pattern</span><span class="tag">&gt;</span>
    Module      pm_pattern
    PatternFile /var/lib/nxlog/patterndb.xml
<span class="tag">&lt;/Processor&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">file</span><span class="tag">&gt;</span>
    Module      om_file
    File        &quot;/var/log/out&quot;
    Exec        to_json();
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">uds_to_file</span><span class="tag">&gt;</span>
    Path        uds =<span class="error">&gt;</span> pattern =<span class="error">&gt;</span> file
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
<div class="paragraph">
<p>The following pattern database contains two patterns to match SSH
authentication messages. The patterns are under a group named <em>ssh</em>
which checks whether the <code>$SourceName</code> field is <code>sshd</code> and only tries
to match the patterns if the logs are indeed from sshd. The patterns
both extract <em>AuthMethod</em>, <em>AccountName</em>, and <em>SourceIP4Address</em> from
the log message when the pattern matches the log. Additionally
<em>TaxonomyStatus</em> and <em>TaxonomyAction</em> are set. The second pattern
utilizes the <a href="#config_module_exec">Exec</a> block, which is evaluated
when the pattern matches.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
For this pattern to work, the logs must be parsed with
      <a href="#xm_syslog_proc_parse_syslog">parse_syslog()</a> prior to
      processing by the <em>pm_pattern</em> module (as in the above example),
      because it uses the
      <code>$SourceName</code> and <code>$Message</code> fields.
</td>
</tr>
</table>
</div>
<div id="pm_pattern_patterndb" class="listingblock">
<div class="title">patterndb.xml</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="xml"><span class="preprocessor">&lt;?xml version='1.0' encoding='UTF-8'?&gt;</span>
<span class="tag">&lt;patterndb&gt;</span>
 <span class="tag">&lt;created&gt;</span>2010-01-01 01:02:03<span class="tag">&lt;/created&gt;</span>
 <span class="tag">&lt;version&gt;</span>42<span class="tag">&lt;/version&gt;</span>

 <span class="tag">&lt;group&gt;</span>
   <span class="tag">&lt;name&gt;</span>ssh<span class="tag">&lt;/name&gt;</span>
   <span class="tag">&lt;id&gt;</span>42<span class="tag">&lt;/id&gt;</span>
   <span class="tag">&lt;matchfield&gt;</span>
    <span class="tag">&lt;name&gt;</span>SourceName<span class="tag">&lt;/name&gt;</span>
    <span class="tag">&lt;type&gt;</span>exact<span class="tag">&lt;/type&gt;</span>
    <span class="tag">&lt;value&gt;</span>sshd<span class="tag">&lt;/value&gt;</span>
   <span class="tag">&lt;/matchfield&gt;</span>

   <span class="tag">&lt;pattern&gt;</span>
    <span class="tag">&lt;id&gt;</span>1<span class="tag">&lt;/id&gt;</span>
    <span class="tag">&lt;name&gt;</span>ssh auth success<span class="tag">&lt;/name&gt;</span>

    <span class="tag">&lt;matchfield&gt;</span>
     <span class="tag">&lt;name&gt;</span>Message<span class="tag">&lt;/name&gt;</span>
     <span class="tag">&lt;type&gt;</span>regexp<span class="tag">&lt;/type&gt;</span>
        <span class="comment">&lt;!-- Accepted publickey for nxlogfan from 192.168.1.1 port 4242 ssh2 --&gt;</span>
     <span class="tag">&lt;value&gt;</span>^Accepted (\S+) for (\S+) from (\S+) port \d+ ssh2<span class="tag">&lt;/value&gt;</span>
     <span class="tag">&lt;capturedfield&gt;</span>
        <span class="tag">&lt;name&gt;</span>AuthMethod<span class="tag">&lt;/name&gt;</span>
        <span class="tag">&lt;type&gt;</span>string<span class="tag">&lt;/type&gt;</span>
     <span class="tag">&lt;/capturedfield&gt;</span>
     <span class="tag">&lt;capturedfield&gt;</span>
        <span class="tag">&lt;name&gt;</span>AccountName<span class="tag">&lt;/name&gt;</span>
        <span class="tag">&lt;type&gt;</span>string<span class="tag">&lt;/type&gt;</span>
     <span class="tag">&lt;/capturedfield&gt;</span>
     <span class="tag">&lt;capturedfield&gt;</span>
        <span class="tag">&lt;name&gt;</span>SourceIP4Address<span class="tag">&lt;/name&gt;</span>
        <span class="tag">&lt;type&gt;</span>string<span class="tag">&lt;/type&gt;</span>
     <span class="tag">&lt;/capturedfield&gt;</span>
    <span class="tag">&lt;/matchfield&gt;</span>

    <span class="tag">&lt;set&gt;</span>
     <span class="tag">&lt;field&gt;</span>
       <span class="tag">&lt;name&gt;</span>TaxonomyStatus<span class="tag">&lt;/name&gt;</span>
       <span class="tag">&lt;value&gt;</span>success<span class="tag">&lt;/value&gt;</span>
       <span class="tag">&lt;type&gt;</span>string<span class="tag">&lt;/type&gt;</span>
     <span class="tag">&lt;/field&gt;</span>
     <span class="tag">&lt;field&gt;</span>
       <span class="tag">&lt;name&gt;</span>TaxonomyAction<span class="tag">&lt;/name&gt;</span>
       <span class="tag">&lt;value&gt;</span>authenticate<span class="tag">&lt;/value&gt;</span>
       <span class="tag">&lt;type&gt;</span>string<span class="tag">&lt;/type&gt;</span>
     <span class="tag">&lt;/field&gt;</span>
    <span class="tag">&lt;/set&gt;</span>
   <span class="tag">&lt;/pattern&gt;</span>

   <span class="tag">&lt;pattern&gt;</span>
    <span class="tag">&lt;id&gt;</span>2<span class="tag">&lt;/id&gt;</span>
    <span class="tag">&lt;name&gt;</span>ssh auth failure<span class="tag">&lt;/name&gt;</span>

    <span class="tag">&lt;matchfield&gt;</span>
     <span class="tag">&lt;name&gt;</span>Message<span class="tag">&lt;/name&gt;</span>
     <span class="tag">&lt;type&gt;</span>regexp<span class="tag">&lt;/type&gt;</span>
     <span class="tag">&lt;value&gt;</span>^Failed (\S+) for invalid user (\S+) from (\S+) port \d+ ssh2<span class="tag">&lt;/value&gt;</span>

     <span class="tag">&lt;capturedfield&gt;</span>
        <span class="tag">&lt;name&gt;</span>AuthMethod<span class="tag">&lt;/name&gt;</span>
        <span class="tag">&lt;type&gt;</span>string<span class="tag">&lt;/type&gt;</span>
     <span class="tag">&lt;/capturedfield&gt;</span>
     <span class="tag">&lt;capturedfield&gt;</span>
        <span class="tag">&lt;name&gt;</span>AccountName<span class="tag">&lt;/name&gt;</span>
        <span class="tag">&lt;type&gt;</span>string<span class="tag">&lt;/type&gt;</span>
     <span class="tag">&lt;/capturedfield&gt;</span>
     <span class="tag">&lt;capturedfield&gt;</span>
        <span class="tag">&lt;name&gt;</span>SourceIP4Address<span class="tag">&lt;/name&gt;</span>
        <span class="tag">&lt;type&gt;</span>string<span class="tag">&lt;/type&gt;</span>
     <span class="tag">&lt;/capturedfield&gt;</span>
    <span class="tag">&lt;/matchfield&gt;</span>

    <span class="tag">&lt;set&gt;</span>
     <span class="tag">&lt;field&gt;</span>
       <span class="tag">&lt;name&gt;</span>TaxonomyStatus<span class="tag">&lt;/name&gt;</span>
       <span class="tag">&lt;value&gt;</span>failure<span class="tag">&lt;/value&gt;</span>
       <span class="tag">&lt;type&gt;</span>string<span class="tag">&lt;/type&gt;</span>
     <span class="tag">&lt;/field&gt;</span>
     <span class="tag">&lt;field&gt;</span>
       <span class="tag">&lt;name&gt;</span>TaxonomyAction<span class="tag">&lt;/name&gt;</span>
       <span class="tag">&lt;value&gt;</span>authenticate<span class="tag">&lt;/value&gt;</span>
       <span class="tag">&lt;type&gt;</span>string<span class="tag">&lt;/type&gt;</span>
     <span class="tag">&lt;/field&gt;</span>
    <span class="tag">&lt;/set&gt;</span>

    <span class="tag">&lt;exec&gt;</span>
      $TestField = 'test';
    <span class="tag">&lt;/exec&gt;</span>
    <span class="tag">&lt;exec&gt;</span>
      $TestField = $Testfield + 'value';
    <span class="tag">&lt;/exec&gt;</span>
   <span class="tag">&lt;/pattern&gt;</span>

 <span class="tag">&lt;/group&gt;</span>

<span class="tag">&lt;/patterndb&gt;</span></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="pm_transformer"><a class="anchor" href="#pm_transformer"></a>6.8. Format Converter (pm_transformer)</h3>
<div class="paragraph">
<p>The <em>pm_transformer</em> module provides parsers for BSD Syslog, IETF
Syslog, CSV, JSON, and XML formatted data and can also convert
between. This module is now obsoleted by the functions and procedures
provided by the following modules: <a href="#xm_syslog">xm_syslog</a>,
<a href="#xm_csv">xm_csv</a>, <a href="#xm_json">xm_json</a>, and <a href="#xm_xml">xm_xml</a>. Using
this module can be slightly faster than calling these procedures from
an <a href="#config_module_exec">Exec</a> directive.</p>
</div>
<div class="sect3">
<h4 id="pm_transformer_config"><a class="anchor" href="#pm_transformer_config"></a>6.8.1. Configuration</h4>
<div class="paragraph">
<p>The <em>pm_transformer</em> module accepts the following directives in addition to the
<a href="#config_module_common">common module directives</a>. For conversion to occur,
the <a href="#pm_transformer_config_inputformat">InputFormat</a> and
<a href="#pm_transformer_config_outputformat">OutputFormat</a> directives must be
specified.</p>
</div>
<div id="pm_transformer_config_inputformat" class="dlist">
<dl>
<dt class="hdlist1">InputFormat</dt>
<dd>
<p>This directive specifies the input format of the
<code>$raw_event</code> field so that it is further parsed into fields. If this
directive is not specified, no parsing will be performed.</p>
<div class="openblock">
<div class="content">
<div id="pm_transformer_config_inputformat_csv" class="dlist">
<dl>
<dt class="hdlist1">CSV</dt>
<dd>
<p>Input is parsed as a comma-separated list of values. See
<a href="#xm_csv">xm_csv</a> for similar functionality. The input fields must be
defined by <a href="#pm_transformer_config_csvinputfields">CSVInputFields</a>.</p>
</dd>
</dl>
</div>
<div id="pm_transformer_config_inputformat_json" class="dlist">
<dl>
<dt class="hdlist1">JSON</dt>
<dd>
<p>Input is parsed as JSON. This does the same as the
<a href="#xm_json_proc_parse_json">parse_json()</a> procedure.</p>
</dd>
</dl>
</div>
<div id="pm_transformer_config_inputformat_syslog_bsd" class="dlist">
<dl>
<dt class="hdlist1">syslog_bsd</dt>
<dd>
<p>Same as
<a href="#pm_transformer_config_inputformat_syslog_rfc3164">syslog_rfc3164</a>.</p>
</dd>
</dl>
</div>
<div id="pm_transformer_config_inputformat_syslog_ietf" class="dlist">
<dl>
<dt class="hdlist1">syslog_ietf</dt>
<dd>
<p>Same as
<a href="#pm_transformer_config_inputformat_syslog_rfc5424">syslog_rfc5424</a>.</p>
</dd>
</dl>
</div>
<div id="pm_transformer_config_inputformat_syslog_rfc3164" class="dlist">
<dl>
<dt class="hdlist1">syslog_rfc3164</dt>
<dd>
<p>Input is parsed in the BSD Syslog format as defined by
RFC 3164. This does the same as the
<a href="#xm_syslog_proc_parse_syslog_bsd">parse_syslog_bsd()</a> procedure.</p>
</dd>
</dl>
</div>
<div id="pm_transformer_config_inputformat_syslog_rfc5424" class="dlist">
<dl>
<dt class="hdlist1">syslog_rfc5424</dt>
<dd>
<p>Input is parsed in the IETF Syslog format as defined by
RFC 5424. This does the same as the
<a href="#xm_syslog_proc_parse_syslog_ietf">parse_syslog_ietf()</a> procedure.</p>
</dd>
</dl>
</div>
<div id="pm_transformer_config_inputformat_xml" class="dlist">
<dl>
<dt class="hdlist1">XML</dt>
<dd>
<p>Input is parsed as XML. This does the same as the
<a href="#xm_xml_proc_parse_xml">parse_xml()</a> procedure.</p>
</dd>
</dl>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="pm_transformer_config_outputformat" class="dlist">
<dl>
<dt class="hdlist1">OutputFormat</dt>
<dd>
<p>This directive specifies the output transformation. If
this directive is not specified, fields are not converted and
<code>$raw_event</code> is left unmodified.</p>
<div class="openblock">
<div class="content">
<div id="pm_transformer_config_outputformat_csv" class="dlist">
<dl>
<dt class="hdlist1">CSV</dt>
<dd>
<p>Output in <code>$raw_event</code> is formatted as a comma-separated list of
values. See <a href="#xm_csv">xm_csv</a> for similar functionality.</p>
</dd>
</dl>
</div>
<div id="pm_transformer_config_outputformat_json" class="dlist">
<dl>
<dt class="hdlist1">JSON</dt>
<dd>
<p>Output in <code>$raw_event</code> is formatted as JSON. This does the same as the
<a href="#xm_json_proc_to_json">to_json()</a> procedure.</p>
</dd>
</dl>
</div>
<div id="pm_transformer_config_outputformat_syslog_bsd" class="dlist">
<dl>
<dt class="hdlist1">syslog_bsd</dt>
<dd>
<p>Same as
<a href="#pm_transformer_config_outputformat_syslog_rfc3164">syslog_rfc3164</a>.</p>
</dd>
</dl>
</div>
<div id="pm_transformer_config_outputformat_syslog_ietf" class="dlist">
<dl>
<dt class="hdlist1">syslog_ietf</dt>
<dd>
<p>Same as
<a href="#pm_transformer_config_outputformat_syslog_rfc5424">syslog_rfc5424</a>.</p>
</dd>
</dl>
</div>
<div id="pm_transformer_config_outputformat_syslog_rfc3164" class="dlist">
<dl>
<dt class="hdlist1">syslog_rfc3164</dt>
<dd>
<p>Output in <code>$raw_event</code> is formatted in the BSD Syslog format
as defined by RFC 3164. This does the same as the
<a href="#xm_syslog_proc_to_syslog_bsd">to_syslog_bsd()</a> procedure.</p>
</dd>
</dl>
</div>
<div id="pm_transformer_config_outputformat_syslog_rfc5424" class="dlist">
<dl>
<dt class="hdlist1">syslog_rfc5424</dt>
<dd>
<p>Output in <code>$raw_event</code> is formatted in the IETF Syslog
format as defined by RFC 5424. This does the same as the
<a href="#xm_syslog_proc_to_syslog_ietf">to_syslog_ietf()</a> procedure.</p>
</dd>
</dl>
</div>
<div id="pm_transformer_config_outputformat_syslog_snare" class="dlist">
<dl>
<dt class="hdlist1">syslog_snare</dt>
<dd>
<p>Output in <code>$raw_event</code> is formatted in the SNARE Syslog
format. This does the same as the
<a href="#xm_syslog_proc_to_syslog_snare">to_syslog_snare()</a> procedure. This should
be used in conjunction with the <a href="#im_mseventlog">im_mseventlog</a> or
<a href="#im_msvistalog">im_msvistalog</a> module to produce an output compatible with
<a href="https://www.intersectalliance.com/our-product/snare-agent/operating-system-agents/snare-agent-for-windows/">Snare
Agent for Windows</a>.</p>
</dd>
</dl>
</div>
<div id="pm_transformer_config_outputformat_xml" class="dlist">
<dl>
<dt class="hdlist1">XML</dt>
<dd>
<p>Output in <code>$raw_event</code> is formatted in XML. This does the same as the
<a href="#xm_xml_proc_to_xml">to_xml()</a> procedure.</p>
</dd>
</dl>
</div>
</div>
</div>
</dd>
</dl>
</div>
<hr>
<div id="pm_transformer_config_csvinputfields" class="dlist">
<dl>
<dt class="hdlist1">CSVInputFields</dt>
<dd>
<p>This is a comma-separated list of fields which will
be set from the input parsed. The field names must have the dollar
sign (<code>$</code>) prepended.</p>
</dd>
</dl>
</div>
<div id="pm_transformer_config_csvinputfieldtypes" class="dlist">
<dl>
<dt class="hdlist1">CSVInputFieldTypes</dt>
<dd>
<p>This optional directive specifies the list of
types corresponding to the field names defined in
<a href="#pm_transformer_config_csvinputfields">CSVInputFields</a>. If
specified, the number of types must match the number of field names
specified with
<a href="#pm_transformer_config_csvinputfields">CSVInputFields</a>. If this
directive is omitted, all fields will be stored as
<a href="#lang_type_string">strings</a>. This directive has no effect on the
fields-to-CSV conversion.</p>
</dd>
</dl>
</div>
<div id="pm_transformer_config_csvoutputfields" class="dlist">
<dl>
<dt class="hdlist1">CSVOutputFields</dt>
<dd>
<p>This is a comma-separated list of message fields
which are placed in the CSV lines. The field names must have the
dollar sign (<code>$</code>) prepended.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="pm_transformer_config_examples"><a class="anchor" href="#pm_transformer_config_examples"></a>6.8.2. Examples</h4>
<div class="exampleblock">
<div class="title">Example 98. Using the pm_transformer Module</div>
<div class="content">
<div class="paragraph">
<p>This configuration reads BSD Syslog messages from file and writes them
to another file in CSV format.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">syslog</span><span class="tag">&gt;</span>
    Module          xm_syslog
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">filein</span><span class="tag">&gt;</span>
    Module          im_file
    File            &quot;tmp/input&quot;
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Processor</span> <span class="attribute-name">transformer</span><span class="tag">&gt;</span>
    Module          pm_transformer
    InputFormat     syslog_rfc3164
    OutputFormat    csv
    CSVOutputFields $facility, $severity, $timestamp, $hostname, \
                    $application, $pid, $message
<span class="tag">&lt;/Processor&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">fileout</span><span class="tag">&gt;</span>
    Module          om_file
    File            &quot;tmp/output&quot;
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">filein_to_fileout</span><span class="tag">&gt;</span>
    Path            filein =<span class="error">&gt;</span> transformer =<span class="error">&gt;</span> fileout
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="output-modules"><a class="anchor" href="#output-modules"></a>7. Output Modules</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Output modules are responsible for writing event log data to various
destinations.</p>
</div>
<div class="sect2">
<h3 id="om_blocker"><a class="anchor" href="#om_blocker"></a>7.1. Blocker (om_blocker)</h3>
<div class="paragraph">
<p>This module is mostly for testing purposes. It will block log messages
in order to simulate a blocked route, like when a network transport
output module such as <a href="#om_tcp">om_tcp</a> blocks because of a network
problem.</p>
</div>
<div class="paragraph">
<p>The <a href="#core_proc_sleep">sleep()</a> procedure can also be used for testing
by simulating log message delays.</p>
</div>
<div class="sect3">
<h4 id="om_blocker_config"><a class="anchor" href="#om_blocker_config"></a>7.1.1. Configuration</h4>
<div class="paragraph">
<p>The <em>om_blocker</em> module accepts only the <a href="#config_module_common">common module
directives</a>.</p>
</div>
</div>
<div class="sect3">
<h4 id="om_blocker_config_examples"><a class="anchor" href="#om_blocker_config_examples"></a>7.1.2. Examples</h4>
<div class="exampleblock">
<div class="title">Example 99. Testing Buffering With the om_blocker Module</div>
<div class="content">
<div class="paragraph">
<p>Because the route in this configuration is blocked, this will test the
behavior of the configured memory-based buffer.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Input</span> <span class="attribute-name">uds</span><span class="tag">&gt;</span>
    Module      im_uds
    UDS         /dev/log
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Processor</span> <span class="attribute-name">buffer</span><span class="tag">&gt;</span>
    Module      pm_buffer
    WarnLimit   512
    MaxSize     1024
    Type        Mem
<span class="tag">&lt;/Processor&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">blocker</span><span class="tag">&gt;</span>
    Module      om_blocker
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">uds_to_blocker</span><span class="tag">&gt;</span>
    Path        uds =<span class="error">&gt;</span> buffer =<span class="error">&gt;</span> blocker
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="om_dbi"><a class="anchor" href="#om_dbi"></a>7.2. DBI (om_dbi)</h3>
<div class="paragraph">
<p>The <em>om_dbi</em> module allows NXLog to store log data in external
databases. This module utilizes the
<a href="http://libdbi.sourceforge.net">libdbi</a> database abstraction library,
which supports various database engines such as MySQL, PostgreSQL,
MSSQL, Sybase, Oracle, SQLite, and Firebird. An INSERT statement can
be specified, which will be executed for each log, to insert into any
table schema.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
The <a href="#im_dbi">im_dbi</a> and <em>om_dbi</em> modules support GNU/Linux only
      because of the libdbi library. The <a href="#im_odbc">im_odbc</a> and
      <a href="#om_odbc">om_odbc</a> modules provide native database access on
      Windows (available only in NXLog Enterprise Edition).
</td>
</tr>
</table>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
libdbi needs <a href="#im_dbi_config_driver">drivers</a> to access the
      database engines. These are in the libdbd-* packages on Debian
      and Ubuntu. CentOS 5.6 has a libdbi-drivers RPM package, but
      this package does not contain any driver binaries under
      /usr/lib64/dbd. The drivers for both MySQL and PostgreSQL are in
      libdbi-dbd-mysql. If these are not installed, NXLog will
      return a libdbi driver initialization error.
</td>
</tr>
</table>
</div>
<div class="sect3">
<h4 id="om_dbi_config"><a class="anchor" href="#om_dbi_config"></a>7.2.1. Configuration</h4>
<div class="paragraph">
<p>The <em>om_dbi</em> module accepts the following directives in addition to the
<a href="#config_module_common">common module directives</a>.</p>
</div>
<div id="om_dbi_config_driver" class="dlist">
<dl>
<dt class="hdlist1">Driver</dt>
<dd>
<p>This mandatory directive specifies the name of the libdbi
driver which will be used to connect to the database. A DRIVER name
must be provided here for which a loadable driver module exists
under the name <code>libdbdDRIVER.so</code> (usually under <code>/usr/lib/dbd/</code>). The
MySQL driver is in the <code>libdbdmysql.so</code> file.</p>
</dd>
</dl>
</div>
<div id="om_dbi_config_sql" class="dlist">
<dl>
<dt class="hdlist1">SQL</dt>
<dd>
<p>This directive should specify the INSERT statement to be
executed for each log message. The field names (names beginning with
<code>$</code>) will be replaced with the value they
contain. <a href="#lang_type_string">String</a> types will be quoted.</p>
</dd>
</dl>
</div>
<hr>
<div id="om_dbi_config_option" class="dlist">
<dl>
<dt class="hdlist1">Option</dt>
<dd>
<p>This directive can be used to specify additional driver
options such as connection parameters. The manual of the libdbi
driver should contain the options available for use here.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="om_dbi_config_examples"><a class="anchor" href="#om_dbi_config_examples"></a>7.2.2. Examples</h4>
<div class="paragraph">
<p>These two examples are for the plain Syslog fields. Other fields
generated by parsers, regular expression rules, the
<a href="#pm_pattern">pm_pattern</a> pattern matcher module, or input modules,
can also be used. Notably, the <a href="#im_msvistalog">im_msvistalog</a> and
<a href="#im_mseventlog">im_mseventlog</a> modules generate different fields than
those shown in these examples.</p>
</div>
<div class="exampleblock">
<div class="title">Example 100. Storing Syslog in a PostgreSQL Database</div>
<div class="content">
<div class="paragraph">
<p>Below is a table schema which can be used to store Syslog data:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="sql"><span class="class">CREATE</span> <span class="type">TABLE</span> log (
    id serial,
        <span class="predefined-type">timestamp</span> <span class="predefined-type">timestamp</span>  <span class="keyword">not</span> <span class="predefined-constant">null</span>,
    hostname <span class="predefined-type">varchar</span>(<span class="integer">32</span>) <span class="directive">default</span> <span class="predefined-constant">NULL</span>,
    facility <span class="predefined-type">varchar</span>(<span class="integer">10</span>) <span class="directive">default</span> <span class="predefined-constant">NULL</span>,
    severity <span class="predefined-type">varchar</span>(<span class="integer">10</span>) <span class="directive">default</span> <span class="predefined-constant">NULL</span>,
    application <span class="predefined-type">varchar</span>(<span class="integer">10</span>) <span class="directive">default</span> <span class="predefined-constant">NULL</span>,
    message <span class="predefined-type">text</span>,
    <span class="directive">PRIMARY</span> <span class="type">KEY</span> (id)
);</code></pre>
</div>
</div>
<div class="paragraph">
<p>The following configuration accepts log messages via TCP and uses
libdbi to insert log messages into the database.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">syslog</span><span class="tag">&gt;</span>
    Module  xm_syslog
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">tcp</span><span class="tag">&gt;</span>
    Module  im_tcp
    Port    1234
    Host    0.0.0.0
    Exec    parse_syslog_bsd();
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">dbi</span><span class="tag">&gt;</span>
    Module  om_dbi
    SQL     INSERT INTO log (facility, severity, hostname, timestamp, \
                             application, message) \
            VALUES ($SyslogFacility, $SyslogSeverity, $Hostname, '$EventTime', \
                    $SourceName, $Message)
    Driver  pgsql
    Option  host 127.0.0.1
    Option  username dbuser
    Option  password secret
    Option  dbname logdb
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">tcp_to_dbi</span><span class="tag">&gt;</span>
    Path    tcp =<span class="error">&gt;</span> dbi
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
<div class="exampleblock">
<div class="title">Example 101. Storing Logs in a MySQL Database</div>
<div class="content">
<div class="paragraph">
<p>This configuration reads log messages from the socket and inserts them
into a MySQL database.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">syslog</span><span class="tag">&gt;</span>
    Module      xm_syslog
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">uds</span><span class="tag">&gt;</span>
    Module      im_uds
    UDS         /dev/log
    Exec        parse_syslog_bsd();
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">dbi</span><span class="tag">&gt;</span>
    Module      om_dbi
    SQL         INSERT INTO log (facility, severity, hostname, timestamp, \
                                 application, message) \
                VALUES ($SyslogFacility, $SyslogSeverity, $Hostname, '$EventTime', \
                        $SourceName, $Message)
    Driver      mysql
    Option      host 127.0.0.1
    Option      username mysql
    Option      password mysql
    Option      dbname logdb
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">uds_to_dbi</span><span class="tag">&gt;</span>
    Path        uds =<span class="error">&gt;</span> dbi
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="om_exec"><a class="anchor" href="#om_exec"></a>7.3. Program (om_exec)</h3>
<div class="paragraph">
<p>This module will execute a program or script on startup and write
(pipe) log data to its standard input. Unless
<a href="#config_outputtype">OutputType</a> is set to something else,
only the contents of the <code>$raw_event</code> field are sent over the
pipe. The execution of the program or script will terminate when the
module is stopped, which usually happens when NXLog exits and
the pipe is closed.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
The program or script is started when NXLog starts and
      must not exit until the module is stopped. To invoke a program
      or script for each log message, use <a href="#xm_exec">xm_exec</a> instead.
</td>
</tr>
</table>
</div>
<div class="sect3">
<h4 id="om_exec_config"><a class="anchor" href="#om_exec_config"></a>7.3.1. Configuration</h4>
<div class="paragraph">
<p>The <em>om_exec</em> module accepts the following directives in addition to the
<a href="#config_module_common">common module directives</a>.
The <a href="#om_exec_config_command">Command</a> directive is required.</p>
</div>
<div id="om_exec_config_command" class="dlist">
<dl>
<dt class="hdlist1">Command</dt>
<dd>
<p>This mandatory directive specifies the name of the
program or script to be executed.</p>
</dd>
</dl>
</div>
<hr>
<div id="om_exec_config_arg" class="dlist">
<dl>
<dt class="hdlist1">Arg</dt>
<dd>
<p>This is an optional parameter. <strong>Arg</strong> can be specified
multiple times, once for each argument that needs to be passed to
the <a href="#om_exec_config_command">Command</a>. Note that specifying
multiple arguments with one <strong>Arg</strong> directive, with arguments
separated by spaces, will not work (the
<a href="#om_exec_config_command">Command</a> will receive it as one argument).</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="om_exec_config_examples"><a class="anchor" href="#om_exec_config_examples"></a>7.3.2. Examples</h4>
<div class="exampleblock">
<div class="title">Example 102. Piping Logs to an External Program</div>
<div class="content">
<div class="paragraph">
<p>With this configuration, NXLog will start the specified
command, read logs from socket, and write those logs to the standard
input of the command.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Input</span> <span class="attribute-name">uds</span><span class="tag">&gt;</span>
    Module  im_uds
    UDS     /dev/log
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">someprog</span><span class="tag">&gt;</span>
    Module  om_exec
    Command /usr/bin/someprog
    Arg     -
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">uds_to_someprog</span><span class="tag">&gt;</span>
    Path    uds =<span class="error">&gt;</span> someprog
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="om_file"><a class="anchor" href="#om_file"></a>7.4. Files (om_file)</h3>
<div class="paragraph">
<p>This module can be used to write log messages to a file.</p>
</div>
<div class="sect3">
<h4 id="om_file_config"><a class="anchor" href="#om_file_config"></a>7.4.1. Configuration</h4>
<div class="paragraph">
<p>The <em>om_file</em> module accepts the following directives in addition to the
<a href="#config_module_common">common module directives</a>.
The <a href="#om_file_config_file">File</a> directive is required.</p>
</div>
<div id="om_file_config_file" class="dlist">
<dl>
<dt class="hdlist1">File</dt>
<dd>
<p>This mandatory directive specifies the name of the output file
to open. It must be a <a href="#lang_type_string">string</a> type
<a href="#lang_expressions">expression</a>. If the expression in the <strong>File</strong>
directive is not a constant string (it contains functions, field
names, or operators), it will be evaluated before each event is
written to the file (and after the <a href="#config_module_exec">Exec</a> is
evaluated).  Note that the filename must be quoted to be a valid
string literal, unlike in other directives which take a filename
argument. For relative filenames, note that NXLog changes
its working directory to "/" unless the global
<a href="#config_global_spooldir">SpoolDir</a> is set to something else.</p>
<div class="paragraph">
<p>Below are three variations for specifying the same output file on a
Windows system:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>File 'C:\logs\logmsg.txt'
File "C:\\logs\\logmsg.txt"
File 'C:/logs/logmsg.txt'</pre>
</div>
</div>
</dd>
</dl>
</div>
<hr>
<div id="om_file_config_createdir" class="dlist">
<dl>
<dt class="hdlist1">CreateDir</dt>
<dd>
<p>If set to TRUE, this optional boolean directive instructs
the module to create the output directory before opening the file
for writing if it does not exist. The default is FALSE.</p>
</dd>
</dl>
</div>
<div id="om_file_config_outputtype" class="dlist">
<dl>
<dt class="hdlist1">OutputType</dt>
<dd>
<p>See the <a href="#config_outputtype">OutputType</a> directive in the
list of common module directives. If this directive is not specified
the default is <a href="#config_outputtype_linebased">LineBased</a>.</p>
</dd>
</dl>
</div>
<div id="om_file_config_sync" class="dlist">
<dl>
<dt class="hdlist1">Sync</dt>
<dd>
<p>This optional boolean directive instructs the module to sync
the file after each log message is written, ensuring that it is
really written to disk from the buffers. Because this can hurt
performance, the default is FALSE.</p>
</dd>
</dl>
</div>
<div id="om_file_config_truncate" class="dlist">
<dl>
<dt class="hdlist1">Truncate</dt>
<dd>
<p>This optional boolean directive instructs the module to
truncate the file before each write, causing only the most recent
log message to be saved. The default is FALSE: messages are appended
to the output file.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="om_file_funcs"><a class="anchor" href="#om_file_funcs"></a>7.4.2. Functions</h4>
<div class="paragraph">
<p>The following functions are exported by <em>om_file</em>.</p>
</div>
<div id="om_file_func_file_name" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_string">string</a> <code>file_name()</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Return the name of the currently open file which was specified using
the <a href="#om_file_config_file">File</a> directive.  Note that
this will be the old name if the filename changes dynamically; for the
new name, use the expression specified for the
<a href="#om_file_config_file">File</a> directive instead of using
this function.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="om_file_func_file_size" class="dlist">
<dl>
<dt class="hdlist1"><a href="#lang_type_integer">integer</a> <code>file_size()</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Return the size of the currently open output file in bytes. Returns
undef if the file is not open. This can happen if
<a href="#om_file_config_file">File</a> is not a string literal
expression and there was no log message.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="om_file_procs"><a class="anchor" href="#om_file_procs"></a>7.4.3. Procedures</h4>
<div class="paragraph">
<p>The following procedures are exported by <em>om_file</em>.</p>
</div>
<div id="om_file_proc_reopen" class="dlist">
<dl>
<dt class="hdlist1"><code>reopen();</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Reopen the current file. This procedure should be called if the file
has been removed or renamed, for example with the
<a href="#xm_fileop_proc_file_cycle">file_cycle()</a>,
<a href="#xm_fileop_proc_file_remove">file_remove()</a>, or
<a href="#xm_fileop_proc_file_rename">file_rename()</a> procedures of
the xm_fileop module. This does not need to be called after
<a href="#om_file_proc_rotate_to">rotate_to()</a> because that
procedure reopens the file automatically.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
<div id="om_file_proc_rotate_to" class="dlist">
<dl>
<dt class="hdlist1"><code>rotate_to(<a href="#lang_type_string">string</a> filename);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Rotate the current file to the <em>filename</em> specified. The module will
then open the original file specified with the
<a href="#om_file_config_file">File</a> directive. Note that the
rename(2) system call is used internally which does not support moving
files across different devices on some platforms. If this is a
problem, first rotate the file on the same device. Then use the
xm_exec <a href="#xm_exec_proc_exec_async">exec_async()</a> procedure
to copy it to another device or file system, or use the xm_fileop
<a href="#xm_fileop_proc_file_copy">file_copy()</a> procedure.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="om_file_config_examples"><a class="anchor" href="#om_file_config_examples"></a>7.4.4. Examples</h4>
<div class="exampleblock">
<div class="title">Example 103. Storing Raw Syslog Messages into a File</div>
<div class="content">
<div class="paragraph">
<p>This configuration reads log messages from socket and writes the
messages to file. No additional processing is done.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Input</span> <span class="attribute-name">uds</span><span class="tag">&gt;</span>
    Module  im_uds
    UDS     /dev/log
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">file</span><span class="tag">&gt;</span>
    Module  om_file
    File    &quot;/var/log/messages&quot;
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">uds_to_file</span><span class="tag">&gt;</span>
    Path    uds =<span class="error">&gt;</span> file
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
<div id="om_file_config_example_rotate1" class="exampleblock">
<div class="title">Example 104. File Rotation Based on Size</div>
<div class="content">
<div class="paragraph">
<p>With this configuration, NXLog accepts log messages via TCP
and parses them as BSD Syslog. A separate output file is used for log
messages from each host. When the output file size exceeds 15 MB, it
will be automatically rotated and compressed.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">exec</span><span class="tag">&gt;</span>
    Module  xm_exec
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Extension</span> <span class="attribute-name">syslog</span><span class="tag">&gt;</span>
    Module  xm_syslog
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">tcp</span><span class="tag">&gt;</span>
    Module  im_tcp
    Port    1514
    Host    0.0.0.0
    Exec    parse_syslog_bsd();
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">file</span><span class="tag">&gt;</span>
    Module  om_file
    File    &quot;tmp/output_&quot; + $Hostname + &quot;_&quot; + month(now())
    <span class="tag">&lt;Exec&gt;</span>
        if file-<span class="error">&gt;</span>file_size() <span class="error">&gt;</span> 15M
        {
            $newfile = &quot;tmp/output_&quot; + $Hostname + &quot;_&quot; +
                        strftime(now(), &quot;%Y%m%d%H%M%S&quot;);
            file-<span class="error">&gt;</span>rotate_to($newfile);
            exec_async(&quot;/bin/bzip2&quot;, $newfile);
        }
    <span class="tag">&lt;/Exec&gt;</span>
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">tcp_to_file</span><span class="tag">&gt;</span>
    Path    tcp =<span class="error">&gt;</span> file
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="om_http"><a class="anchor" href="#om_http"></a>7.5. HTTP(s) (om_http)</h3>
<div class="paragraph">
<p>This module will connect to the specified <a href="#om_http_config_url">URL</a>
in either plain HTTP or HTTPS mode. Each event is transferred in a
single POST request. The module then waits for a response containing a
successful status code (200, 201, or 202). It will reconnect and retry
the delivery if the remote has closed the connection or a timeout is
exceeded while waiting for the response. This HTTP-level
acknowledgment ensures that no messages are lost during transfer.</p>
</div>
<div class="sect3">
<h4 id="om_http_config"><a class="anchor" href="#om_http_config"></a>7.5.1. Configuration</h4>
<div class="paragraph">
<p>The <em>om_http</em> module accepts the following directives in addition to the
<a href="#config_module_common">common module directives</a>.
The <a href="#om_http_config_url">URL</a> directive is required.</p>
</div>
<div id="om_http_config_url" class="dlist">
<dl>
<dt class="hdlist1">URL</dt>
<dd>
<p>This mandatory directive specifies the URL where the module
should POST the event data. The module operates in plain HTTP or
HTTPS mode depending on the URL provided, and connects to the
hostname specified in the URL. If the port number is not explicitly
indicated in the URL, it defaults to port 80 for HTTP and port 443 for
HTTPS.</p>
</dd>
</dl>
</div>
<hr>
<div id="om_http_config_contenttype" class="dlist">
<dl>
<dt class="hdlist1">ContentType</dt>
<dd>
<p>This directive sets the <em>Content-Type</em> HTTP header to
the string specified. The <em>Content-Type</em> is set to <code>text/plain</code> by
default.</p>
</dd>
</dl>
</div>
<div id="om_http_config_httpsallowuntrusted" class="dlist">
<dl>
<dt class="hdlist1">HTTPSAllowUntrusted</dt>
<dd>
<p>This boolean directive specifies that the
connection should be allowed without certificate verification. If
set to TRUE, the connection will be allowed even if the remote HTTPS
server presents an unknown or self-signed certificate. The default
value is FALSE: the remote HTTPS server must present a trusted
certificate.</p>
</dd>
</dl>
</div>
<div id="om_http_config_httpscadir" class="dlist">
<dl>
<dt class="hdlist1">HTTPSCADir</dt>
<dd>
<p>This specifies the path to a directory containing
certificate authority (CA) certificates, which will be used to check
the certificate of the remote HTTPS server. The certificate
filenames in this directory must be in the OpenSSL hashed format.</p>
</dd>
</dl>
</div>
<div id="om_http_config_httpscafile" class="dlist">
<dl>
<dt class="hdlist1">HTTPSCAFile</dt>
<dd>
<p>This specifies the path of the certificate authority
(CA) certificate, which will be used to check the certificate of the
remote HTTPS server.</p>
</dd>
</dl>
</div>
<div id="om_http_config_httpscertfile" class="dlist">
<dl>
<dt class="hdlist1">HTTPSCertFile</dt>
<dd>
<p>This specifies the path of the certificate file to be
used for the HTTPS handshake.</p>
</dd>
</dl>
</div>
<div id="om_http_config_httpscertkeyfile" class="dlist">
<dl>
<dt class="hdlist1">HTTPSCertKeyFile</dt>
<dd>
<p>This specifies the path of the certificate key file
to be used for the HTTPS handshake.</p>
</dd>
</dl>
</div>
<div id="om_http_config_httpscrldir" class="dlist">
<dl>
<dt class="hdlist1">HTTPSCRLDir</dt>
<dd>
<p>This specifies the path to a directory containing
certificate revocation lists (CRLs), which will be consulted when
checking the certificate of the remote HTTPS server. The certificate
filenames in this directory must be in the OpenSSL hashed format.</p>
</dd>
</dl>
</div>
<div id="om_http_config_httpscrlfile" class="dlist">
<dl>
<dt class="hdlist1">HTTPSCRLFile</dt>
<dd>
<p>This specifies the path of the certificate revocation
list (CRL) which will be consulted when checking the certificate of
the remote HTTPS server.</p>
</dd>
</dl>
</div>
<div id="om_http_config_httpskeypass" class="dlist">
<dl>
<dt class="hdlist1">HTTPSKeyPass</dt>
<dd>
<p>With this directive, a password can be supplied for the
certificate key file defined in
<a href="#om_http_config_httpscertkeyfile">HTTPSCertKeyFile</a>. This directive
is not needed for passwordless private keys.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="om_http_procs"><a class="anchor" href="#om_http_procs"></a>7.5.2. Procedures</h4>
<div class="paragraph">
<p>The following procedures are exported by <em>om_http</em>.</p>
</div>
<div id="om_http_proc_set_http_request_path" class="dlist">
<dl>
<dt class="hdlist1"><code>set_http_request_path(<a href="#lang_type_string">string</a> path);</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Set the <em>path</em> in the HTTP request to the string specified. This is
useful if the URL is dynamic and parameters such as event ID need to
be included in the URL. Note that the string must be URL encoded if it
contains reserved characters.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="om_http_config_examples"><a class="anchor" href="#om_http_config_examples"></a>7.5.3. Examples</h4>
<div class="exampleblock">
<div class="title">Example 105. Sending Logs over HTTPS</div>
<div class="content">
<div class="paragraph">
<p>This configuration reads log messages from file and forwards them via
HTTPS.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Input</span> <span class="attribute-name">file</span><span class="tag">&gt;</span>
    Module              im_file
    File                'input.log'
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">http</span><span class="tag">&gt;</span>
    Module              om_http
    URL                 https://server:8080/
    HTTPSCertFile       %CERTDIR%/client-cert.pem
    HTTPSCertKeyFile    %CERTDIR%/client-key.pem
    HTTPSCAFile         %CERTDIR%/ca.pem
    HTTPSAllowUntrusted FALSE
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">file_to_http</span><span class="tag">&gt;</span>
    Path                file =<span class="error">&gt;</span> http
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="om_null"><a class="anchor" href="#om_null"></a>7.6. Null (om_null)</h3>
<div class="paragraph">
<p>Log messages sent to the <em>om_null</em> module instance are discarded, this
module does not write its output anywhere. It can be useful for
creating a dummy route, for testing purposes, or for
<a href="#config_module_schedule">Scheduled</a> NXLog code execution. The
<em>om_null</em> module accepts only the <a href="#config_module_common">common module
directives</a>. See <a href="#config_example_routes">this example</a> for usage.</p>
</div>
</div>
<div class="sect2">
<h3 id="om_ssl"><a class="anchor" href="#om_ssl"></a>7.7. TLS/SSL (om_ssl)</h3>
<div class="paragraph">
<p>The <em>om_ssl</em> module uses the OpenSSL library to provide an SSL/TLS
transport. It behaves like the <a href="#om_tcp">om_tcp</a> module, except that
an SSL handshake is performed at connection time and the data is
received over a secure channel. Log messages transferred over plain
TCP can be eavesdropped or even altered with a man-in-the-middle
attack, while the <em>om_ssl</em> module provides a secure log message
transport.</p>
</div>
<div class="sect3">
<h4 id="om_ssl_config"><a class="anchor" href="#om_ssl_config"></a>7.7.1. Configuration</h4>
<div class="paragraph">
<p>The <em>om_ssl</em> module accepts the following directives in addition to the
<a href="#config_module_common">common module directives</a>.
The <a href="#om_ssl_config_host">Host</a> directive is required.</p>
</div>
<div id="om_ssl_config_host" class="dlist">
<dl>
<dt class="hdlist1">Host</dt>
<dd>
<p>The module will connect to this IP address or DNS hostname.</p>
</dd>
</dl>
</div>
<div id="om_ssl_config_port" class="dlist">
<dl>
<dt class="hdlist1">Port</dt>
<dd>
<p>The module will connect to this port number on the remote host.
The default is port 514.</p>
</dd>
</dl>
</div>
<hr>
<div id="om_ssl_config_allowuntrusted" class="dlist">
<dl>
<dt class="hdlist1">AllowUntrusted</dt>
<dd>
<p>This boolean directive specifies that the connection
should be allowed without certificate verification. If set to TRUE
the connection will be allowed even if the remote server presents an
unknown or self-signed certificate. The default value is FALSE: the
remote socket must present a trusted certificate.</p>
</dd>
</dl>
</div>
<div id="om_ssl_config_cadir" class="dlist">
<dl>
<dt class="hdlist1">CADir</dt>
<dd>
<p>This specifies the path to a directory containing certificate
authority (CA) certificates, which will be used to check the
certificate of the remote socket. The certificate filenames in this
directory must be in the OpenSSL hashed format.</p>
</dd>
</dl>
</div>
<div id="om_ssl_config_cafile" class="dlist">
<dl>
<dt class="hdlist1">CAFile</dt>
<dd>
<p>This specifies the path of the certificate authority (CA)
certificate, which will be used to check the certificate of the
remote socket.</p>
</dd>
</dl>
</div>
<div id="om_ssl_config_certfile" class="dlist">
<dl>
<dt class="hdlist1">CertFile</dt>
<dd>
<p>This specifies the path of the certificate file to be used
for the SSL handshake.</p>
</dd>
</dl>
</div>
<div id="om_ssl_config_certkeyfile" class="dlist">
<dl>
<dt class="hdlist1">CertKeyFile</dt>
<dd>
<p>This specifies the path of the certificate key file to
be used for the SSL handshake.</p>
</dd>
</dl>
</div>
<div id="om_ssl_config_crldir" class="dlist">
<dl>
<dt class="hdlist1">CRLDir</dt>
<dd>
<p>This specifies the path to a directory containing certificate
revocation lists (CRLs), which will be consulted when checking the
certificate of the remote socket. The certificate filenames in this
directory must be in the OpenSSL hashed format.</p>
</dd>
</dl>
</div>
<div id="om_ssl_config_crlfile" class="dlist">
<dl>
<dt class="hdlist1">CRLFile</dt>
<dd>
<p>This specifies the path of the certificate revocation list (CRL) which
will be used to check the certificate of the remote socket against.</p>
</dd>
</dl>
</div>
<div id="om_ssl_config_keypass" class="dlist">
<dl>
<dt class="hdlist1">KeyPass</dt>
<dd>
<p>With this directive, a password can be supplied for the
certificate key file defined in
<a href="#om_ssl_config_certkeyfile">CertKeyFile</a>. This directive is not
needed for passwordless private keys.</p>
</dd>
</dl>
</div>
<div id="om_ssl_config_outputtype" class="dlist">
<dl>
<dt class="hdlist1">OutputType</dt>
<dd>
<p>See the <a href="#config_outputtype">OutputType</a> directive in the
list of common module directives.</p>
</dd>
</dl>
</div>
<div id="om_ssl_config_reconnect" class="dlist">
<dl>
<dt class="hdlist1">Reconnect</dt>
<dd>
<p>This directive has been deprecated as of version 2.4. The
module will try to reconnect automatically at increasing intervals
on all errors.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="om_ssl_procs"><a class="anchor" href="#om_ssl_procs"></a>7.7.2. Procedures</h4>
<div class="paragraph">
<p>The following procedures are exported by <em>om_ssl</em>.</p>
</div>
<div id="om_ssl_proc_reconnect" class="dlist">
<dl>
<dt class="hdlist1"><code>reconnect();</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Force a reconnection. This can be used from a Schedule block to
periodically reconnect to the server.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="om_ssl_config_examples"><a class="anchor" href="#om_ssl_config_examples"></a>7.7.3. Examples</h4>
<div class="exampleblock">
<div class="title">Example 106. Sending Binary Data to Another NXLog Agent</div>
<div class="content">
<div class="paragraph">
<p>This configuration reads log messages from socket and sends them in
the NXLog <a href="#config_outputtype_binary">binary</a> format to
another NXLog agent.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Input</span> <span class="attribute-name">uds</span><span class="tag">&gt;</span>
    Module          im_uds
    UDS             tmp/socket
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">ssl</span><span class="tag">&gt;</span>
    Module          om_ssl
    Host            localhost
    Port            23456
    CAFile          %CERTDIR%/ca.pem
    CertFile        %CERTDIR%/client-cert.pem
    CertKeyFile     %CERTDIR%/client-key.pem
    KeyPass         secret
    AllowUntrusted  TRUE
    OutputType      Binary
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">uds_to_ssl</span><span class="tag">&gt;</span>
    Path            uds =<span class="error">&gt;</span> ssl
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="om_tcp"><a class="anchor" href="#om_tcp"></a>7.8. TCP (om_tcp)</h3>
<div class="paragraph">
<p>This module initiates a TCP connection to a remote host and transfers
log messages.
Or, in <a href="#om_tcp_config_listen">Listen</a> mode, this module accepts
client connections and multiplexes data to all connected clients.
The TCP transfer protocol provides more reliable log
transmission than UDP. If security is a concern, consider using the
<a href="#om_ssl">om_ssl</a> module instead.</p>
</div>
<div class="sect3">
<h4 id="om_tcp_config"><a class="anchor" href="#om_tcp_config"></a>7.8.1. Configuration</h4>
<div class="paragraph">
<p>The <em>om_tcp</em> module accepts the following directives in addition to the
<a href="#config_module_common">common module directives</a>.
The <a href="#om_tcp_config_host">Host</a> directive is required.</p>
</div>
<div id="om_tcp_config_host" class="dlist">
<dl>
<dt class="hdlist1">Host</dt>
<dd>
<p>The module will connect to this IP address or DNS hostname.
Or, if <a href="#om_tcp_config_listen">Listen</a> is set to TRUE, the module will
listen for connections on this address.</p>
</dd>
</dl>
</div>
<div id="om_tcp_config_port" class="dlist">
<dl>
<dt class="hdlist1">Port</dt>
<dd>
<p>The module will connect to this port number on the remote
host.
Or, if <a href="#om_tcp_config_listen">Listen</a> is set to TRUE, the module will
listen for connections on this port.
The default is port 514.</p>
</dd>
</dl>
</div>
<hr>
<div id="om_tcp_config_listen" class="dlist">
<dl>
<dt class="hdlist1">Listen</dt>
<dd>
<p>If TRUE, this boolean directive specifies that <em>om_tcp</em> should listen
for connections at the local address specified by the
<a href="#om_tcp_config_host">Host</a> directive rather than opening a connection to
the address. The default is FALSE: <em>om_tcp</em> will connect to the specified
address.</p>
</dd>
</dl>
</div>
<div id="om_tcp_config_outputtype" class="dlist">
<dl>
<dt class="hdlist1">OutputType</dt>
<dd>
<p>See the <a href="#config_outputtype">OutputType</a> directive in the
list of common module directives.</p>
</dd>
</dl>
</div>
<div id="om_tcp_config_queueinlistenmode" class="dlist">
<dl>
<dt class="hdlist1">QueueInListenMode</dt>
<dd>
<p>If set to TRUE, this boolean directive specifies that
events should be queued if no client is connected. If this module&#8217;s buffer
becomes full, the preceding module in the route will be paused or events
will be dropped, depending on whether
<a href="#config_module_flowcontrol">FlowControl</a> is enabled. This directive only
applies if <a href="#om_tcp_config_listen">Listen</a> is set to TRUE. The default is
FALSE: <em>om_tcp</em> will discard events if no client is connected.</p>
</dd>
</dl>
</div>
<div id="om_tcp_config_reconnect" class="dlist">
<dl>
<dt class="hdlist1">Reconnect</dt>
<dd>
<p>This directive has been deprecated as of version 2.4. The
module will try to reconnect automatically at increasing intervals
on all errors.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="om_tcp_procs"><a class="anchor" href="#om_tcp_procs"></a>7.8.2. Procedures</h4>
<div class="paragraph">
<p>The following procedures are exported by <em>om_tcp</em>.</p>
</div>
<div id="om_tcp_proc_reconnect" class="dlist">
<dl>
<dt class="hdlist1"><code>reconnect();</code></dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>Force a reconnection. This can be used from a Schedule block to
periodically reconnect to the server.</p>
</div>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="om_tcp_config_examples"><a class="anchor" href="#om_tcp_config_examples"></a>7.8.3. Examples</h4>
<div class="exampleblock">
<div class="title">Example 107. Transferring Raw Logs over TCP</div>
<div class="content">
<div class="paragraph">
<p>With this configuration, NXLog will read log messages from
socket and forward them via TCP.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Input</span> <span class="attribute-name">uds</span><span class="tag">&gt;</span>
    Module  im_uds
    UDS     /dev/log
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">tcp</span><span class="tag">&gt;</span>
    Module  om_tcp
    Host    192.168.1.1
    Port    1514
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">uds_to_tcp</span><span class="tag">&gt;</span>
    Path    uds =<span class="error">&gt;</span> tcp
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="om_udp"><a class="anchor" href="#om_udp"></a>7.9. UDP (om_udp)</h3>
<div class="paragraph">
<p>This module sends log messages as UDP datagrams to the address and
port specified. UDP is the transport protocol of the legacy BSD Syslog
standard as described in RFC 3164, so this module can be particularly
useful to send messages to devices or Syslog daemons which do not
support other transports.</p>
</div>
<div class="sect3">
<h4 id="om_udp_config"><a class="anchor" href="#om_udp_config"></a>7.9.1. Configuration</h4>
<div class="paragraph">
<p>The <em>om_udp</em> module accepts the following directives in addition to the
<a href="#config_module_common">common module directives</a>.
The <a href="#om_udp_config_host">Host</a> directive is required.</p>
</div>
<div id="om_udp_config_host" class="dlist">
<dl>
<dt class="hdlist1">Host</dt>
<dd>
<p>The module will connect to this IP address or DNS hostname.</p>
</dd>
</dl>
</div>
<div id="om_udp_config_port" class="dlist">
<dl>
<dt class="hdlist1">Port</dt>
<dd>
<p>The module will connect to this port number on the remote
host. The default is port 514.</p>
</dd>
</dl>
</div>
<hr>
<div id="om_udp_config_sockbufsize" class="dlist">
<dl>
<dt class="hdlist1">SockBufSize</dt>
<dd>
<p>This optional directive sets the socket buffer size
(SO_SNDBUF) to the value specified. If this is not set, the
operating system default is used.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="om_udp_config_examples"><a class="anchor" href="#om_udp_config_examples"></a>7.9.2. Examples</h4>
<div class="exampleblock">
<div class="title">Example 108. Sending Raw Syslog over UDP</div>
<div class="content">
<div class="paragraph">
<p>This configuration reads log messages from socket and forwards them
via UDP.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Input</span> <span class="attribute-name">uds</span><span class="tag">&gt;</span>
    Module  im_uds
    UDS     /dev/log
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">udp</span><span class="tag">&gt;</span>
    Module  om_udp
    Host    192.168.1.1
    Port    1514
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">uds_to_udp</span><span class="tag">&gt;</span>
    Path    uds =<span class="error">&gt;</span> udp
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="om_uds"><a class="anchor" href="#om_uds"></a>7.10. Unix Domain Sockets (om_uds)</h3>
<div class="paragraph">
<p>This module allows log messages to be sent to a Unix domain socket.
Unix systems traditionally have a /dev/log or similar socket used by
the system logger to accept messages. Applications use the syslog(3)
system call to send messages to the system logger. NXLog can
use this module to send log messages to another Syslog daemon via the
socket.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
This module supports SOCK_DGRAM type sockets only. SOCK_STREAM
      type sockets may be supported in the future.
</td>
</tr>
</table>
</div>
<div class="sect3">
<h4 id="om_uds_config"><a class="anchor" href="#om_uds_config"></a>7.10.1. Configuration</h4>
<div class="paragraph">
<p>The <em>om_uds</em> module accepts the following directives in addition to the
<a href="#config_module_common">common module directives</a>.</p>
</div>
<div id="om_uds_config_uds" class="dlist">
<dl>
<dt class="hdlist1">UDS</dt>
<dd>
<p>This specifies the path of the Unix domain socket. The default
is <code>/dev/log</code>.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="om_uds_config_examples"><a class="anchor" href="#om_uds_config_examples"></a>7.10.2. Examples</h4>
<div class="exampleblock">
<div class="title">Example 109. Using the om_uds Module</div>
<div class="content">
<div class="paragraph">
<p>This configuration reads log messages from a file, adds BSD Syslog
headers with default fields, and writes the messages to socket.</p>
</div>
<div class="listingblock">
<div class="title">nxlog.conf</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="config"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
</pre></td>
  <td class="code"><pre><span class="tag">&lt;Extension</span> <span class="attribute-name">syslog</span><span class="tag">&gt;</span>
    Module  xm_syslog
<span class="tag">&lt;/Extension&gt;</span>

<span class="tag">&lt;Input</span> <span class="attribute-name">file</span><span class="tag">&gt;</span>
    Module  im_file
    File    &quot;/var/log/custom_app.log&quot;
<span class="tag">&lt;/Input&gt;</span>

<span class="tag">&lt;Output</span> <span class="attribute-name">uds</span><span class="tag">&gt;</span>
    Module  om_uds
    # Defaulting Syslog fields and creating Syslog output
    Exec    parse_syslog_bsd(); to_syslog_bsd();
    UDS     /dev/log
<span class="tag">&lt;/Output&gt;</span>

<span class="tag">&lt;Route</span> <span class="attribute-name">file_to_uds</span><span class="tag">&gt;</span>
    Path    file =<span class="error">&gt;</span> uds
<span class="tag">&lt;/Route&gt;</span></pre></td>
</tr></table></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div id="footer">
<div id="footer-text">
Version 2.10.2150<br>
Last updated 2018-11-16 13:56:32 UTC
</div>
</div>
</body>
</html>
F1l3 Manager
