2.1 Includes

The include keyword allows other snort config files to be included within the snort.conf indicated on the Snort command line. It works much like an #include from the C programming language, reading the contents of the named file and adding the contents in the place where the include statement appears in the file.

2.1.1 Format

    include <include file path/name>

Note:  

Note that there is no semicolon at the end of this line.

Included files will substitute any predefined variable values into their own variable references. See Section for more information on defining and using variables in Snort config files.

2.1.2 Variables

Three types of variables may be defined in Snort:

• var
• portvar
• ipvar

These are simple substitution variables set with the var, ipvar, or portvar keywords as follows:

    var RULES_PATH rules/
    portvar MY_PORTS [22,80,1024:1050]
    ipvar MY_NET [192.168.1.0/24,10.1.1.0/24]
    alert tcp any any -> $MY_NET $MY_PORTS (flags:S; msg:"SYN packet";)
    include $RULE_PATH/example.rule

2.1.2.1 IP Variables and IP Lists

IPs may be specified individually, in a list, as a CIDR block, or any combination of the three. IP variables should be specified using 'ipvar' instead of 'var'. Using 'var' for an IP variable is still allowed for backward compatibility, but it will be deprecated in a future release.

IP variable name can begin with an alphanumeric character [A-Za-z0-9] or '_' and should be followed by characters and numbers. Only numbers are not accepted as variable names.

IPs, IP lists, and CIDR blocks may be negated with '!'. Negation is handled differently compared with Snort versions 2.7.x and earlier. Previously, each element in a list was logically OR'ed together. IP lists now OR non-negated elements and AND the result with the OR'ed negated elements.

The following example list will match the IP 1.1.1.1 and IP from 2.2.2.0 to 2.2.2.255, with the exception of IPs 2.2.2.2 and 2.2.2.3.

    [1.1.1.1,2.2.2.0/24,![2.2.2.2,2.2.2.3]]

The order of the elements in the list does not matter. The element 'any' can be used to match all IPs, although '!any' is not allowed. Also, negated IP ranges that are more general than non-negated IP ranges are not allowed.

See below for some valid examples if IP variables and IP lists.

    ipvar EXAMPLE [1.1.1.1,2.2.2.0/24,![2.2.2.2,2.2.2.3]] 
    
    alert tcp $EXAMPLE any -> any any (msg:"Example"; sid:1;)

    alert tcp [1.0.0.0/8,!1.1.1.0/24] any -> any any (msg:"Example";sid:2;)

The following examples demonstrate some invalid uses of IP variables and IP lists.

Use of !any:

    ipvar EXAMPLE any
    alert tcp !$EXAMPLE any -> any any (msg:"Example";sid:3;)

Different use of !any:

    ipvar EXAMPLE !any
    alert tcp $EXAMPLE any -> any any (msg:"Example";sid:3;)

Logical contradictions:

    ipvar EXAMPLE [1.1.1.1,!1.1.1.1]

Nonsensical negations:

    ipvar EXAMPLE [1.1.1.0/24,!1.1.0.0/16]

2.1.2.2 Port Variables and Port Lists

Portlists supports the declaration and lookup of ports and the representation of lists and ranges of ports. Variables, ranges, or lists may all be negated with '!'. Also, 'any' will specify any ports, but '!any' is not allowed. Valid port ranges are from 0 to 65535.

Lists of ports must be enclosed in brackets and port ranges may be specified with a ':', such as in:

     
    [10:50,888:900]

Port variables should be specified using 'portvar'. The use of 'var' to declare a port variable will be deprecated in a future release. For backwards compatibility, a 'var' can still be used to declare a port variable, provided the variable name either ends with '_PORT' or begins with 'PORT_'.

The following examples demonstrate several valid usages of both port variables and port lists.

     
    portvar EXAMPLE1 80

    var EXAMPLE2_PORT [80:90]

    var PORT_EXAMPLE2 [1]

    portvar EXAMPLE3 any

    portvar EXAMPLE4 [!70:90]

    portvar EXAMPLE5 [80,91:95,100:200]

    alert tcp any $EXAMPLE1 -> any $EXAMPLE2_PORT (msg:"Example"; sid:1;)

    alert tcp any $PORT_EXAMPLE2 -> any any (msg:"Example"; sid:2;)

    alert tcp any 90 -> any [100:1000,9999:20000] (msg:"Example"; sid:3;)

Several invalid examples of port variables and port lists are demonstrated below:

Use of !any:

     
    portvar EXAMPLE5 !any
    var EXAMPLE5 !any

Logical contradictions:

     
    portvar EXAMPLE6 [80,!80]

Ports out of range:

     
    portvar EXAMPLE7 [65536]

Incorrect declaration and use of a port variable:

     
    var EXAMPLE8 80 
    alert tcp any $EXAMPLE8 -> any any (msg:"Example"; sid:4;)

Port variable used as an IP:

     
    alert tcp $EXAMPLE1 any -> any any (msg:"Example"; sid:5;)

2.1.2.3 Variable Modifiers

Rule variable names can be modified in several ways. You can define meta-variables using the $ operator. These can be used with the variable modifier operators ? and -, as described in the following table:

Variable Syntax	Description
var	Defines a meta-variable.
$(var) or $var	Replaces with the contents of variable var.
$(var:-default)	Replaces the contents of the variable var with “default” if var is undefined.
$(var:?message)	Replaces with the contents of variable var or prints out the error message and exits.

Here is an example of advanced variable usage in action:

    ipvar MY_NET 192.168.1.0/24
    log tcp any any -> $(MY_NET:?MY_NET is undefined!) 23

2.1.2.4 Limitations

When embedding variables, types can not be mixed. For instance, port variables can be defined in terms of other port variables, but old-style variables (with the 'var' keyword) can not be embedded inside a 'portvar'.

Valid embedded variable:

    portvar pvar1 80
    portvar pvar2 [$pvar1,90]

Invalid embedded variable:

    var pvar1 80
    portvar pvar2 [$pvar1,90]

Likewise, variables can not be redefined if they were previously defined as a different type. They should be renamed instead:

Invalid redefinition:

    var pvar 80
    portvar pvar 90

2.1.3 Config

Many configuration and command line options of Snort can be specified in the configuration file.

2.1.3.1 Format

    config <directive> [: <value>]

Config Directive	Description
config alert_with_interface_name	Appends interface name to alert (snort -I).
config alertfile: <filename>	Sets the alerts output file.
config asn1: <max-nodes>	Specifies the maximum number of nodes to track when doing ASN1 decoding. See Section for more information and examples.
config autogenerate_preprocessor _decoder_rules	If Snort was configured to enable decoder and preprocessor rules, this option will cause Snort to revert back to its original behavior of alerting if the decoder or preprocessor generates an event.
config bpf_file: <filename>	Specifies BPF filters (snort -F).
config checksum_drop: <types>	Types of packets to drop if invalid checksums. Values: none, noip, notcp, noicmp, noudp, ip, tcp, udp, icmp or all (only applicable in inline mode and for packets checked per checksum_mode config option).
config checksum_mode: <types>	Types of packets to calculate checksums. Values: none, noip, notcp, noicmp, noudp, ip, tcp, udp, icmp or all.
config chroot: <dir>	Chroots to specified dir (snort -t).
config classification: <class>	See Table for a list of classifications.
config cs_dir: <path>	configure snort to provide a Unix socket in the path that can be used to issue commands to the running process. See Section for more details.
config daemon	Forks as a daemon (snort -D).
config decode_data_link	Decodes Layer2 headers (snort -e).
config default_rule_state: <state>	Global configuration directive to enable or disable the loading of rules into the detection engine. Default (with or without directive) is enabled. Specify disabled to disable loading rules.
config daq: <type>	Selects the type of DAQ to instantiate. The DAQ with the highest version of the given type is selected if there are multiple of the same type (this includes any built-in DAQs).
config daq_mode: <mode>	Select the DAQ mode: passive, inline, or read-file. Not all DAQs support modes. See the DAQ distro README for possible DAQ modes or list DAQ capabilities for a brief summary.
config daq_var: <name=value>	Set a DAQ specific variable. Snort just passes this information down to the DAQ. See the DAQ distro README for possible DAQ variables.
config daq_dir: <dir>	Tell Snort where to look for available dynamic DAQ modules. This can be repeated. The selected DAQ will be the one with the latest version.
config daq_list: [<dir>]	Tell Snort to dump basic DAQ capabilities and exit. You can optionally specify a directory to include any dynamic DAQs from that directory. You can also precede this option with extra DAQ directory options to look in multiple directories.
config decode_esp: [enable | disable]	Enable or disable the decoding of Encapsulated Security Protocol (ESP). This is disabled by default. Some networks use ESP for authentication without encryption, allowing their content to be inspected. Encrypted ESP may cause some false positives if this option is enabled.
config detection: [search-method <method>]	Select type of fast pattern matcher algorithm to use. search-method <method> Queued match search methods - Matches are queued until the fast pattern matcher is finished with the payload, then evaluated. This was found to generally increase performance through fewer cache misses (evaluating each rule would generally blow away the fast pattern matcher state in the cache). ac and ac-q - Aho-Corasick Full (high memory, best performance). ac-bnfa and ac-bnfa-q - Aho-Corasick Binary NFA (low memory, high performance) lowmem and lowmem-q - Low Memory Keyword Trie (low memory, moderate performance) ac-split - Aho-Corasick Full with ANY-ANY port group evaluated separately (low memory, high performance). Note this is shorthand for search-method ac, split-any-any intel-cpm - Intel CPM library (must have compiled Snort with location of libraries to enable this) No queue search methods - The "nq" option specifies that matches should not be queued and evaluated as they are found. ac-nq - Aho-Corasick Full (high memory, best performance). ac-bnfa-nq - Aho-Corasick Binary NFA (low memory, high performance). This is the default search method if none is specified. lowmem-nq - Low Memory Keyword Trie (low memory, moderate performance) Other search methods (the above are considered superior to these) ac-std - Aho-Corasick Standard (high memory, high performance) acs - Aho-Corasick Sparse (high memory, moderate performance) ac-banded - Aho-Corasick Banded (high memory, moderate performance) ac-sparsebands - Aho-Corasick Sparse-Banded (high memory, moderate performance)
config detection: [split-any-any] [search-optimize] [max-pattern-len <int>]	Other options that affect fast pattern matching. split-any-any A memory/performance tradeoff. By default, ANY-ANY port rules are added to every non ANY-ANY port group so that only one port group rule evaluation needs to be done per packet. Not putting the ANY-ANY port rule group into every other port group can significantly reduce the memory footprint of the fast pattern matchers if there are many ANY-ANY port rules. But doing so may require two port group evaluations per packet - one for the specific port group and one for the ANY-ANY port group, thus potentially reducing performance. This option is generic and can be used with any search-method but was specifically intended for use with the ac search-method where the memory footprint is significantly reduced though overall fast pattern performance is better than ac-bnfa. Of note is that the lower memory footprint can also increase performance through fewer cache misses. Default is not to split the ANY-ANY port group. search-optimize Optimizes fast pattern memory when used with search-method ac or ac-split by dynamically determining the size of a state based on the total number of states. When used with ac-bnfa, some fail-state resolution will be attempted, potentially increasing performance. Default is not to optimize. max-pattern-len <integer> This is a memory optimization that specifies the maximum length of a pattern that will be put in the fast pattern matcher. Patterns longer than this length will be truncated to this length before inserting into the pattern matcher. Useful when there are very long contents being used and truncating the pattern won't diminish the uniqueness of the patterns. Note that this may cause more false positive rule evaluations, i.e. rules that will be evaluated because a fast pattern was matched, but eventually fail, however CPU cache can play a part in performance so a smaller memory footprint of the fast pattern matcher can potentially increase performance. Default is to not set a maximum pattern length.
config detection: [no_stream_inserts] [max_queue_events <int>] [enable-single-rule-group] [bleedover-port-limit]	Other detection engine options. no_stream_inserts Specifies that stream inserted packets should not be evaluated against the detection engine. This is a potential performance improvement with the idea that the stream rebuilt packet will contain the payload in the inserted one so the stream inserted packet doesn't need to be evaluated. Default is to inspect stream inserts. max_queue_events <integer> Specifies the maximum number of matching fast-pattern states to queue per packet. Default is 5 events. enable-single-rule-group Put all rules into one port group. Not recommended. Default is not to do this. bleedover-port-limit The maximum number of source or destination ports designated in a rule before the rule is considered an ANY-ANY port group rule. Default is 1024.
config detection: [debug] [debug-print-nocontent-rule-tests] [debug-print-rule-group-build-details] [debug-print-rule-groups-uncompiled] [debug-print-rule-groups-compiled] [debug-print-fast-pattern] [bleedover-warnings-enabled]	Options for detection engine debugging. debug Prints fast pattern information for a particular port group. debug-print-nocontent-rule-tests Prints port group information during packet evaluation. debug-print-rule-group-build-details Prints port group information during port group compilation. debug-print-rule-groups-uncompiled Prints uncompiled port group information. debug-print-rule-groups-compiled Prints compiled port group information. debug-print-fast-pattern For each rule with fast pattern content, prints information about the content being used for the fast pattern matcher. bleedover-warnings-enabled Prints a warning if the number of source or destination ports used in a rule exceed the bleedover-port-limit forcing the rule to be moved into the ANY-ANY port group.
config disable_decode_alerts	Turns off the alerts generated by the decode phase of Snort.
config disable_inline_init_failopen	Disables failopen thread that allows inline traffic to pass while Snort is starting up. Only useful if Snort was configured with -enable-inline-init-failopen. (snort -disable-inline-init-failopen)
config disable_ipopt_alerts	Disables IP option length validation alerts.
config disable_tcpopt_alerts	Disables option length validation alerts.
config disable_tcpopt_experimental_alerts	Turns off alerts generated by experimental TCP options.
config disable_tcpopt_obsolete_alerts	Turns off alerts generated by obsolete TCP options.
config disable_tcpopt_ttcp_alerts	Turns off alerts generated by T/TCP options.
config disable_ttcp_alerts	Turns off alerts generated by T/TCP options.
config dump_chars_only	Turns on character dumps (snort -C).
config dump_payload	Dumps application layer (snort -d).
config dump_payload_verbose	Dumps raw packet starting at link layer (snort -X).
config enable_decode_drops	Enables the dropping of bad packets identified by decoder (only applicable in inline mode).
config enable_decode_oversized_alerts	Enable alerting on packets that have headers containing length fields for which the value is greater than the length of the packet.
config enable_decode_oversized_drops	Enable dropping packets that have headers containing length fields for which the value is greater than the length of the packet. enable_decode_oversized_alerts must also be enabled for this to be effective (only applicable in inline mode).
config enable_deep_teredo_inspection	Snort's packet decoder only decodes Teredo (IPv6 over UDP over IPv4) traffic on UDP port 3544. This option makes Snort decode Teredo traffic on all UDP ports.
config enable_ipopt_drops	Enables the dropping of bad packets with bad/truncated IP options (only applicable in inline mode).
config enable_mpls_multicast	Enables support for MPLS multicast. This option is needed when the network allows MPLS multicast traffic. When this option is off and MPLS multicast traffic is detected, Snort will generate an alert. By default, it is off.
config enable_mpls_overlapping_ip	Enables support for overlapping IP addresses in an MPLS network. In a normal situation, where there are no overlapping IP addresses, this configuration option should not be turned on. However, there could be situations where two private networks share the same IP space and different MPLS labels are used to differentiate traffic from the two VPNs. In such a situation, this configuration option should be turned on. By default, it is off.
config enable_tcpopt_drops	Enables the dropping of bad packets with bad/truncated TCP option (only applicable in inline mode).
config enable_tcpopt_experimental_drops	Enables the dropping of bad packets with experimental TCP option. (only applicable in inline mode).
config enable_tcpopt_obsolete_drops	Enables the dropping of bad packets with obsolete TCP option. (only applicable in inline mode).
config enable_tcpopt_ttcp_drops	Enables the dropping of bad packets with T/TCP option. (only applicable in inline mode).
config enable_ttcp_drops	Enables the dropping of bad packets with T/TCP option. (only applicable in inline mode).
config event_filter: memcap <bytes>	Set global memcap in bytes for thresholding. Default is 1048576 bytes (1 megabyte).
config event_queue: [max_queue <num>] [log <num>] [order_events <order>]	Specifies conditions about Snort's event queue. You can use the following options: max_queue $<$integer$>$ (max events supported) log $<$integer$>$ (number of events to log) order_events [priority$\vert$content_length] (how to order events within the queue) See Section for more information and examples.
config flowbits_size: <num-bits>	Specifies the maximum number of flowbit tags that can be used within a rule set. The default is 1024 bits and maximum is 2048.
config ignore_ports: <proto> <port-list>	Specifies ports to ignore (useful for ignoring noisy NFS traffic). Specify the protocol (TCP, UDP, IP, or ICMP), followed by a list of ports. Port ranges are supported.
config interface: <iface>	Sets the network interface (snort -i).
config ipv6_frag: [bsd_icmp_frag_alert on|off] [, bad_ipv6_frag_alert on|off] [, frag_timeout <secs>] [, max_frag_sessions <max-track>]	The following options can be used: bsd_icmp_frag_alert on|off (Specify whether or not to alert. Default is on) bad_ipv6_frag_alert on|off (Specify whether or not to alert. Default is on) frag_timeout $<$integer$>$ (Specify amount of time in seconds to timeout first frag in hash table) max_frag_sessions $<$integer$>$ (Specify the number of fragments to track in the hash table)
config logdir: <dir>	Sets the logdir (snort -l).
config log_ipv6_extra_data	Set Snort to log IPv6 source and destination addresses as unified2 extra data events.
config max_attribute_hosts: <hosts>	Sets a limit on the maximum number of hosts to read from the attribute table. Minimum value is 32 and the maximum is 524288 (512k). The default is 10000. If the number of hosts in the attribute table exceeds this value, an error is logged and the remainder of the hosts are ignored. This option is only supported with a Host Attribute Table (see section ).
config max_attribute_services_per_host: <hosts>	Sets a per host limit on the maximum number of services to read from the attribute table. Minimum value is 1 and the maximum is 65535. The default is 100. For a given host, if the number of services in the attribute table exceeds this value, an error is logged and the remainder of the services for that host are ignored. This option is only supported with a Host Attribute Table (see section ).
config max_mpls_labelchain_len: <num-hdrs>	Sets a Snort-wide limit on the number of MPLS headers a packet can have. Its default value is -1, which means that there is no limit on label chain length.
config max_ip6_extensions: <num-extensions>	Sets the maximum number of IPv6 extension headers that Snort will decode. Default is 8.
config min_ttl: <ttl>	Sets a Snort-wide minimum ttl to ignore all traffic.
config mpls_payload_type: ipv4|ipv6|ethernet	Sets a Snort-wide MPLS payload type. In addition to ipv4, ipv6 and ethernet are also valid options. The default MPLS payload type is ipv4
config no_promisc	Disables promiscuous mode (snort -p).
config nolog	Disables logging. Note: Alerts will still occur. (snort -N).
config nopcre	Disables pcre pattern matching.
config obfuscate	Obfuscates IP Addresses (snort -O).
config order: <order>	Changes the order that rules are evaluated, e.g.: pass alert log activation.
config pcre_match_limit: $<$integer$>$	Restricts the amount of backtracking a given PCRE option. For example, it will limit the number of nested repeats within a pattern. A value of -1 allows for unlimited PCRE, up to the PCRE library compiled limit (around 10 million). A value of 0 results in no PCRE evaluation. The snort default value is 1500.
config pcre_match_limit_recursion: $<$integer$>$	Restricts the amount of stack used by a given PCRE option. A value of -1 allows for unlimited PCRE, up to the PCRE library compiled limit (around 10 million). A value of 0 results in no PCRE evaluation. The snort default value is 1500. This option is only useful if the value is less than the pcre_match_limit
config pkt_count: <N>	Exits after N packets (snort -n).
config policy_version: $<$base-version-string$>$ [$<$binding-version-string$>$]	Supply versioning information to configuration files. Base version should be a string in all configuration files including included ones. In addition, binding version must be in any file configured with config binding. This option is used to avoid race conditions when modifying and loading a configuration within a short time span - before Snort has had a chance to load a previous configuration.
config profile_preprocs	Print statistics on preprocessor performance. See Section for more details.
config profile_rules	Print statistics on rule performance. See Section for more details.
config protected_content: md5|sha256|sha512	Specifies a default algorithm to use for protected_content rules.
config quiet	Disables banner and status reports (snort -q). NOTE: The command line switch -q takes effect immediately after processing the command line parameters, whereas using config quiet in snort.conf takes effect when the configuration line in snort.conf is parsed. That may occur after other configuration settings that result in output to console or syslog.
config reference: <ref>	Adds a new reference system to Snort, e.g.: myref http://myurl.com/?id=
config reference_net <cidr>	For IP obfuscation, the obfuscated net will be used if the packet contains an IP address in the reference net. Also used to determine how to set up the logging directory structure for the session post detection rule option and ASCII output plugin - an attempt is made to name the log directories after the IP address that is not in the reference net.
config response: [attempts <count>] [, device <dev>]	Set the number of strafing attempts per injected response and/or the device, such as eth0, from which to send responses. These options may appear in any order but must be comma separated. The are intended for passive mode.
config set_gid: <gid>	Changes GID to specified GID (snort -g).
config set_uid: <uid>	Sets UID to $<$id$>$ (snort -u).
config show_year	Shows year in timestamps (snort -y).
config snaplen: <bytes>	Set the snaplength of packet, same effect as -P $<$snaplen$>$ or -snaplen $<$snaplen$>$ options.
config so_rule_memcap: <bytes>	Set global memcap in bytes for so rules that dynamically allocate memory for storing session data in the stream preprocessor. A value of 0 disables the memcap. Default is 0. Maximum value is the maximum value an unsigned 32 bit integer can hold which is 4294967295 or 4GB.
config stateful	Sets assurance mode for stream (stream is established).
config tagged_packet_limit: <max-tag>	When a metric other than packets is used in a tag option in a rule, this option sets the maximum number of packets to be tagged regardless of the amount defined by the other metric. See Section on using the tag option when writing rules for more details. The default value when this option is not configured is 256 packets. Setting this option to a value of 0 will disable the packet limit.
config threshold: memcap <bytes>	Set global memcap in bytes for thresholding. Default is 1048576 bytes (1 megabyte). (This is deprecated. Use config event_filter instead.)
config umask: <umask>	Sets umask when running (snort -m).
config utc	Uses UTC instead of local time for timestamps (snort -U).
config verbose	Uses verbose logging to STDOUT (snort -v).
config vlan_agnostic	Causes Snort to ignore vlan headers for the purposes of connection and frag tracking. This option is only valid in the base configuration when using multiple configurations, and the default is off.
config address_space_agnostic	Causes Snort to ignore DAQ address space ID for the purposes of connection and frag tracking. This option is only valid in the base configuration when using multiple configurations, and the default is off.
config policy_mode: tap|inline|inline_test	Sets the policy mode to either passive, inline or inline_test.
config disable_replace	Disables content replace option. Default behaviour is to replace content.
config tunnel_verdicts: gtp|teredo|6in4|4in6	By default, whitelist and blacklist verdicts are handled internally by Snort for GTP, Teredo, 6in4 and 4in6 encapsulated traffic. This means Snort actually gives the DAQ a pass or block verdict instead. This is to workaround cases where the DAQ would apply the verdict to the whole tunnel instead of the individual session within the tunnel. If your DAQ decodes GTP, Teredo, 6in4 or 4in6 correctly, setting this config will allow the whitelist or blacklist verdict to go to the DAQ. There is a modest performance boost by doing this where possible since Snort won't see the remaining packets on the session.