matchnet

Checks whether the IP address field value of input records is included in the specified subnet group, and filters matching records.

Command properties

Syntax

In the syntax above, name is available starting with 4.0.2609.0.

Options

guid=STR

GUID of the subnet group to match against. In the 5.0 series (through 5.0.2605.2), this is the only way to specify the target. In the 4.0 series (4.0.2609.0 and later), this option cannot be used together with name, and you must specify either guid or name.

name=STR

Name of the subnet group to match against (cannot be used together with guid). You must specify either the guid or name option. This option is available starting with 4.0.2609.0.

field=FIELD

Name of the IP address field to match. You must specify either the field or fields option.

fields=FIELD, ...

List of IP address field names to match, separated by commas (,). If specified together with field, both sets of fields are used. You must specify either the field or fields option.

invert=BOOL

Whether to invert the match result. (Default: f)

• t: Outputs records not included in the subnet group.
• f: Outputs records included in the subnet group.

verify=BOOL

Whether to verify that the subnet group exists. (Default: t)

• t: Verifies that the subnet group exists at parse time.
• f: Skips subnet group validation.

tag=BOOL

Whether to output matched subnet information. (Default: f)

• t: Assigns matched subnet information as a map to the _matchnet_result field.
• f: Does not output subnet information.

Input fields

Output fields

When tag=t is specified, the output record includes subnet_field, subnet_value, and subnet_invert, and _matchnet_result is added only when the record matches a subnet.

Keys in the _matchnet_result map:

Error codes

Parse errors

Runtime errors

None

Description

The matchnet command checks whether the IP address value of the field specified by the field or fields option is included in the subnets defined in the subnet group. Only IPv4 addresses are supported. If the field value is null, an IPv6 address, or an unsupported type, the record is treated as non-matching.

Use the guid option to specify the subnet group to match against. In the 4.0 series (4.0.2609.0 and later), you can also use the name option; the command looks up the group by that name to resolve its GUID, and specifying both guid and name, or omitting both, causes an error, as does specifying a name that does not exist or that matches more than one group.

When tag=t is specified, detailed information about the matched subnet (start IP, end IP, CIDR, description) is assigned as a map to the _matchnet_result field.

When invert=t is specified, only records not included in the subnet group are output. When multiple fields are specified, invert=f (default) determines the output as soon as it finds a matching field, but invert=t conversely determines the output as soon as it finds a non-matching field — meaning a record is excluded from the result only if every field is included in the subnet group.

When verify=f is specified, the existence of the subnet group is not verified at parse time. Use this when the subnet group is synchronized later in a real-time stream query.

If the subnet group is updated during execution, the new subnet information is automatically reflected. In a distributed environment, filtering runs on the Data Node.

Examples

1. Filter records included in a subnet group

   json "[{'src_ip': '192.0.2.1'}, {'src_ip': '198.51.100.5'}, {'src_ip': '203.0.113.10'}]"
   | matchnet guid=550e8400-e29b-41d4-a716-446655440000 field=src_ip
   

   Outputs only records where the src_ip field value is included in the specified subnet group.

2. Filter records not included in a subnet group

   json "[{'src_ip': '192.0.2.1'}, {'src_ip': '198.51.100.5'}]"
   | matchnet guid=550e8400-e29b-41d4-a716-446655440000 field=src_ip invert=t
   

   Outputs only records where the src_ip field value is not included in the subnet group.

3. Include matched subnet information

   json "[{'src_ip': '192.0.2.1'}, {'src_ip': '198.51.100.5'}]"
   | matchnet guid=550e8400-e29b-41d4-a716-446655440000 field=src_ip tag=t
   

   Adds a _matchnet_result field to matching records, outputting the start IP, end IP, CIDR, and description of the matched subnet as a map.

4. Skip subnet group validation

   json "[{'src_ip': '192.0.2.1'}]"
   | matchnet guid=550e8400-e29b-41d4-a716-446655440000 field=src_ip verify=f
   

   Runs without verifying the existence of the subnet group at parse time.

5. Specifying a subnet group by name (4.0 series, 4.0.2609.0 and later)

   table limit=1000 WEB_APACHE_SAMPLE
   | matchnet name=internal_subnets field=src_ip
   

   Matches using a subnet group specified by name instead of GUID.

Change history