diff --git a/package/etc/conf.d/local/config/log_paths/example.conf.tmpl b/package/etc/conf.d/local/config/log_paths/example.conf.tmpl index 6eae6a3..516f954 100644 --- a/package/etc/conf.d/local/config/log_paths/example.conf.tmpl +++ b/package/etc/conf.d/local/config/log_paths/example.conf.tmpl @@ -1,76 +1,101 @@ # LOCAL_EXAMPLE - -# When creating a real plugin, replace the upper case text "LOCAL_EXAMPLE" throughout this file with a unique -# string to identify the vendor product. The string should be of the form "VENDOR_PRODUCT" to signify the -# manufacturer and product type, and must contain only characters matching this regex: [A-Z\_]+ - -# If any of the "LOCAL_EXAMPLE" variables passed into the environment are set (e.g. TLS, UDP, or TLS), -# the template generator will build a custom source based on the value of one or more of the set variables. - -{{- if (ne (getenv (print "SC4S_LISTEN_LOCAL_EXAMPLE_TCP_PORT") "no") "no") or (ne (getenv (print "SC4S_LISTEN_LOCAL_EXAMPLE_UDP_PORT") "no") "no") or (ne (getenv (print "SC4S_LISTEN_LOCAL_EXAMPLE_TLS_PORT") "no") "no") }} - -# "port_id" is used to generate the port variable to be used. It should match the "core" of the variable name -# set in the line above. For example, the "port_id" of "SC4S_LISTEN_LOCAL_EXAMPLE_TCP_PORT" is "LOCAL_EXAMPLE". -# "parser" can be customized on dedicated ports only -# "common" uses the same parser sequence as the default ports and is the most commonly used - -{{ $context := dict "port_id" "LOCAL_EXAMPLE" "parser" "common"}} - -# The following template execution creates a syslog-ng source with one or more dedicated ports for use with this log_path -# The ports used are based on the values of one or more of the environment variables set above. - -{{ tmpl.Exec "t/source_network.t" $context }} -{{- end -}} -{{ define "log_path" }} +# DO NOT MODIFY THIS EXAMPLE DIRECTLY! It will get overwritten with the shipping example +# version each time SC4S starts. Copy this file to another name for development work. + +{{- /* To start, gomplate comments use the C++ style comment syntax you see here, enclosed by */}} +{{- /* curly braces. They will _not_ appear in the final syslog-ng config files. */}} +{{- /* Comments using this format will be specific to the templating process */}} + +# This comment, on the other hand, _will_ appear in the final syslog-ng config. +# Comments using this style will be relevant to the actual syslog-ng config files, +# independent of the templating process. + +{{- /* When creating a real plugin, replace the upper case text "LOCAL_EXAMPLE" throughout */}} +{{- /* this file with a unique string to identify the vendor product. The string should be */}} +{{- /* of the form "VENDOR_PRODUCT" to signify the manufacturer and product type, and must */}} +{{- /* contain only characters matching this regex: [A-Z\_]+ */}} + +{{- /* If any of the "LOCAL_EXAMPLE" variables passed into the environment are set */}} +{{- /* (e.g. TLS, UDP, or TLS), the template generator will build a custom source based */}} +{{- /* on the value of one or more of the set variables. */}} + +{{- /* "port_id" is used to generate the port variable to be used. It should match the */}} +{{- /* "core" of the variable name set in the line above. For example, the "port_id" of */}} +{{- /* "SC4S_LISTEN_LOCAL_EXAMPLE_TCP_PORT" is "LOCAL_EXAMPLE". "parser" can be customized */}} +{{- /* on dedicated ports only. "common" uses the same parser sequence as the default ports */}} +{{- /* and is the most commonly used */}} + +{{- /* The following provides a unique port source configuration if env var(s) are set */}} +{{- $context := dict "port_id" "LOCAL_EXAMPLE" "parser" "common" }} +{{- tmpl.Exec "t/source_network.t" $context }} + +{{- /* The following is an inline template to generate the actual log path */}} +{{- define "log_path"}} log { -# The first time this template is used the log_path will be linked to the default port +{{- /* The first time this template is used the log_path will be linked to the default port */}} {{- if eq (.) "yes"}} source(s_DEFAULT); - -# Filters should be updated to use the simplest and most effecient logic possible to discard -# the message from this path - filter(f_is_rfc3164); filter(f_local_example); {{- end}} -{{- if eq (.) "no"}} -# In the second pass through the template a link to the dedicated port is used. This -# normally does not require additional filters +{{- /* In the second pass through the template a link to the dedicated port is used. This */}} +{{- /* normally does not require additional filters */}} -source (s_LOCAL_EXAMPLE); +{{- if eq (.) "no"}} + source (s_LOCAL_EXAMPLE); {{- end}} -#Set a default sourcetype and index - - rewrite { r_set_splunk_dest_default(sourcetype("sc4s:local_example"), index("main"))}; - -#using the key "local_example" find any cutomized index,source or sourcetype meta values - - parser {p_add_context_splunk(key("local_example")); }; +# Set a default sourcetype and index, as well as an appropriate value for the field +# "sc4s_vendor_product". This field is sent as an indexed field to Splunk, +# and is useful for downstream analysis. -# Any additional logic needed to process the event before sending to Splunk goes here + rewrite { + set("local_example", value("fields.sc4s_vendor_product")); + r_set_splunk_dest_default(sourcetype("sc4s:local_example"), index("main")); + }; -# Send it to Splunk +# using the key "local_example" find any customized index,source or sourcetype meta values + parser { p_add_context_splunk(key("local_example")); }; +# using any user-supplied filters, override Splunk metadata based on further hostname +# or CIDR block filters. + parser (compliance_meta_by_source); + +# Prepare the payload for sending to Splunk. This step is done here rather than in the +# destination(s) to ensure that it is performed only once. If the template value is not overridden, +# the default value (2nd argument) is used. + rewrite { set("$(template ${.splunk.sc4s_template} $(template t_hdr_msg))" value("MSG")); }; + +{{- /* Check environment variables (and defaults if unset) for sending to the HEC */}} +{{- /* destination. When more destination options are offered in SC4S, this is where */}} +{{- /* output to them will be configured */}} + +{{- if or (conv.ToBool (getenv "SC4S_DEST_SPLUNK_HEC_GLOBAL" "yes")) (conv.ToBool (getenv "SC4S_DEST_LOCAL_EXAMPLE_HEC" "no")) }} destination(d_hec); +{{- end}} -# Note: We normally do not use the "final" flag; this will allow another plugin to be created that will -# forward events to another system +{{- /* Check environment variables (and defaults if unset) for sending to the local EWMM-format */}} +{{- /* disk archive */}} - flags(flow-control); +{{- if or (conv.ToBool (getenv "SC4S_ARCHIVE_GLOBAL" "no")) (conv.ToBool (getenv "SC4S_ARCHIVE_LOCAL_EXAMPLE" "no")) }} + destination(d_archive); +{{- end}} +# All passes through any matching log path will be final + flags(flow-control,final); }; {{- end}} -{{- if (ne (getenv (print "SC4S_LISTEN_LOCAL_EXAMPLE_TCP_PORT") "no") "no") or (ne (getenv (print "SC4S_LISTEN_LOCAL_EXAMPLE_UDP_PORT") "no") "no") or (ne (getenv (print "SC4S_LISTEN_MICROFOCUS_ARCSIGHT_TLS_PORT") "no") "no") }} -# Listen on the specified dedicated port(s) for LOCAL_EXAMPLE traffic +{{- /* Prepare to run two passes through this template, one for default traffic and another for */}} +{{- /* "unique ports" if they are configured. */}} - {{tmpl.Exec "log_path" "no" }} -{{- end}} +{{- if or (or (getenv (print "SC4S_LISTEN_LOCAL_EXAMPLE_TCP_PORT")) (getenv (print "SC4S_LISTEN_LOCAL_EXAMPLE_UDP_PORT"))) (getenv (print "SC4S_LISTEN_LOCAL_EXAMPLE_TLS_PORT")) }} +# Listen on the specified dedicated port(s) for LOCAL_EXAMPLE traffic +{{ tmpl.Exec "log_path" "no" }} +{{- end }} # Listen on the default port (typically 514) for LOCAL_EXAMPLE traffic - -{{tmpl.Exec "log_path" "yes" }} +{{ tmpl.Exec "log_path" "yes" }} \ No newline at end of file diff --git a/package/etc/local_config/log_paths/example.conf.tmpl b/package/etc/local_config/log_paths/example.conf.tmpl index 6f75c8e..516f954 100644 --- a/package/etc/local_config/log_paths/example.conf.tmpl +++ b/package/etc/local_config/log_paths/example.conf.tmpl @@ -1,74 +1,101 @@ # LOCAL_EXAMPLE +# DO NOT MODIFY THIS EXAMPLE DIRECTLY! It will get overwritten with the shipping example +# version each time SC4S starts. Copy this file to another name for development work. + +{{- /* To start, gomplate comments use the C++ style comment syntax you see here, enclosed by */}} +{{- /* curly braces. They will _not_ appear in the final syslog-ng config files. */}} +{{- /* Comments using this format will be specific to the templating process */}} + +# This comment, on the other hand, _will_ appear in the final syslog-ng config. +# Comments using this style will be relevant to the actual syslog-ng config files, +# independent of the templating process. + +{{- /* When creating a real plugin, replace the upper case text "LOCAL_EXAMPLE" throughout */}} +{{- /* this file with a unique string to identify the vendor product. The string should be */}} +{{- /* of the form "VENDOR_PRODUCT" to signify the manufacturer and product type, and must */}} +{{- /* contain only characters matching this regex: [A-Z\_]+ */}} + +{{- /* If any of the "LOCAL_EXAMPLE" variables passed into the environment are set */}} +{{- /* (e.g. TLS, UDP, or TLS), the template generator will build a custom source based */}} +{{- /* on the value of one or more of the set variables. */}} + +{{- /* "port_id" is used to generate the port variable to be used. It should match the */}} +{{- /* "core" of the variable name set in the line above. For example, the "port_id" of */}} +{{- /* "SC4S_LISTEN_LOCAL_EXAMPLE_TCP_PORT" is "LOCAL_EXAMPLE". "parser" can be customized */}} +{{- /* on dedicated ports only. "common" uses the same parser sequence as the default ports */}} +{{- /* and is the most commonly used */}} + +{{- /* The following provides a unique port source configuration if env var(s) are set */}} +{{- $context := dict "port_id" "LOCAL_EXAMPLE" "parser" "common" }} +{{- tmpl.Exec "t/source_network.t" $context }} + +{{- /* The following is an inline template to generate the actual log path */}} +{{- define "log_path"}} +log { -# When creating a real plugin, replace the upper case text "LOCAL_EXAMPLE" throughout this file with a unique -# string to identify the vendor product. The string should be of the form "VENDOR_PRODUCT" to signify the -# manufacturer and product type, and must contain only characters matching this regex: [A-Z\_]+ - -# If any of the "LOCAL_EXAMPLE" variables passed into the environment are set (e.g. TLS, UDP, or TLS), -# the template generator will build a custom source based on the value of one or more of the set variables. - - -# "port_id" is used to generate the port variable to be used. It should match the "core" of the variable name -# set in the line above. For example, the "port_id" of "SC4S_LISTEN_LOCAL_EXAMPLE_TCP_PORT" is "LOCAL_EXAMPLE". -# "parser" can be customized on dedicated ports only -# "common" uses the same parser sequence as the default ports and is the most commonly used - - -# The following template execution creates a syslog-ng source with one or more dedicated ports for use with this log_path -# The ports used are based on the values of one or more of the environment variables set above. +{{- /* The first time this template is used the log_path will be linked to the default port */}} -{{ $context := dict "port_id" "LOCAL_EXAMPLE" "parser" "common" }} -{{ tmpl.Exec "t/source_network.t" $context }} -# The following is an inline template; we will use this to generate the actual log path -{{ define "log_path" }} -log { {{- if eq (.) "yes"}} source(s_DEFAULT); filter(f_is_rfc3164); filter(f_local_example); {{- end}} + +{{- /* In the second pass through the template a link to the dedicated port is used. This */}} +{{- /* normally does not require additional filters */}} + {{- if eq (.) "no"}} source (s_LOCAL_EXAMPLE); {{- end}} +# Set a default sourcetype and index, as well as an appropriate value for the field +# "sc4s_vendor_product". This field is sent as an indexed field to Splunk, +# and is useful for downstream analysis. -# The first time this template is used the log_path will be linked to the default port + rewrite { + set("local_example", value("fields.sc4s_vendor_product")); + r_set_splunk_dest_default(sourcetype("sc4s:local_example"), index("main")); + }; -# Filters should be updated to use the simplest and most effecient logic possible to discard -# the message from this path +# using the key "local_example" find any customized index,source or sourcetype meta values + parser { p_add_context_splunk(key("local_example")); }; -# In the second pass through the template a link to the dedicated port is used. This -# normally does not require additional filters +# using any user-supplied filters, override Splunk metadata based on further hostname +# or CIDR block filters. + parser (compliance_meta_by_source); +# Prepare the payload for sending to Splunk. This step is done here rather than in the +# destination(s) to ensure that it is performed only once. If the template value is not overridden, +# the default value (2nd argument) is used. + rewrite { set("$(template ${.splunk.sc4s_template} $(template t_hdr_msg))" value("MSG")); }; -#Set a default sourcetype and index - - rewrite { r_set_splunk_dest_default(sourcetype("sc4s:local_example"), index("main"))}; - -#using the key "local_example" find any cutomized index,source or sourcetype meta values - - parser {p_add_context_splunk(key("local_example")); }; - -# Any additional logic needed to process the event before sending to Splunk goes here - -# Send it to Splunk +{{- /* Check environment variables (and defaults if unset) for sending to the HEC */}} +{{- /* destination. When more destination options are offered in SC4S, this is where */}} +{{- /* output to them will be configured */}} +{{- if or (conv.ToBool (getenv "SC4S_DEST_SPLUNK_HEC_GLOBAL" "yes")) (conv.ToBool (getenv "SC4S_DEST_LOCAL_EXAMPLE_HEC" "no")) }} destination(d_hec); +{{- end}} -# Note: We normally do not use the "final" flag; this will allow another plugin to be created that will -# forward events to another system +{{- /* Check environment variables (and defaults if unset) for sending to the local EWMM-format */}} +{{- /* disk archive */}} - flags(flow-control); +{{- if or (conv.ToBool (getenv "SC4S_ARCHIVE_GLOBAL" "no")) (conv.ToBool (getenv "SC4S_ARCHIVE_LOCAL_EXAMPLE" "no")) }} + destination(d_archive); +{{- end}} +# All passes through any matching log path will be final + flags(flow-control,final); }; {{- end}} +{{- /* Prepare to run two passes through this template, one for default traffic and another for */}} +{{- /* "unique ports" if they are configured. */}} + {{- if or (or (getenv (print "SC4S_LISTEN_LOCAL_EXAMPLE_TCP_PORT")) (getenv (print "SC4S_LISTEN_LOCAL_EXAMPLE_UDP_PORT"))) (getenv (print "SC4S_LISTEN_LOCAL_EXAMPLE_TLS_PORT")) }} # Listen on the specified dedicated port(s) for LOCAL_EXAMPLE traffic - -{{tmpl.Exec "log_path" "no" }} -{{- end}} +{{ tmpl.Exec "log_path" "no" }} +{{- end }} # Listen on the default port (typically 514) for LOCAL_EXAMPLE traffic - -{{tmpl.Exec "log_path" "yes" }} +{{ tmpl.Exec "log_path" "yes" }} \ No newline at end of file