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.
include <include file path/name>
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.
Three types of variables may be defined in Snort:
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
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 126.96.36.199 and IP from 188.8.131.52 to 184.108.40.206, with the exception of IPs 220.127.116.11 and 18.104.22.168.
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 [22.214.171.124,126.96.36.199/24,![188.8.131.52,184.108.40.206]] alert tcp $EXAMPLE any -> any any (msg:"Example"; sid:1;) alert tcp [220.127.116.11/8,!18.104.22.168/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;)
ipvar EXAMPLE [22.214.171.124,!126.96.36.199]
ipvar EXAMPLE [188.8.131.52/24,!184.108.40.206/16]
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:
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  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
portvar EXAMPLE6 [80,!80]
Ports out of range:
portvar EXAMPLE7 
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;)
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:
Defines a meta-variable.
|$(var) or $var||
Replaces with the contents of variable var.
Replaces the contents of the variable var with “default” if var is undefined.
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
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:
var pvar 80 portvar pvar 90
Many configuration and command line options of Snort can be specified in the configuration file.
config <directive> [: <value>]
|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.|
|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.
|config detection: [split-any-any] [search-optimize] [max-pattern-len <int>]||Other options
that affect fast pattern matching.
|config detection: [no_stream_inserts] [max_queue_events <int>] [enable-single-rule-group] [bleedover-port-limit]||Other detection engine options.
|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.
|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.|
|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).|
|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
|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:
|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.|