matchport

Filters input records using a port group. Records where the port or protocol value is null or the type does not match are discarded.

Command properties

Syntax

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

Options

guid=STR

GUID of the port group to use for matching. 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 port group to use for matching (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.

port=STR

Name of the field containing the port number. (Default: port)

protocol=STR

Name of the field containing the protocol. Recognizes tcp, udp, and icmp values. (Default: protocol) Any other string is treated the same as omitting the protocol, matching against both TCP and UDP.

invert=BOOL

When set to t, discards records that match the port group and outputs only non-matching records. (Default: f)

verify=BOOL

When set to f, skips port group validation at the parse stage. (Default: t)

Input fields

Error codes

Parse errors

Runtime errors

None

Description

The matchport command checks whether the port number and protocol value of input records are included in the specified port group, and outputs only matching records. When invert=t is specified, only non-matching records are output.

Use the guid option to specify the port group to use for matching. 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.

If the port field value is not a numeric type or the protocol field value is not a string, the record is discarded regardless of the invert option.

In a distributed environment, filtering runs on the Data Node.

Examples

1. Filter using a port group

   json "[{'port': 80, 'protocol': 'tcp'}, {'port': 53, 'protocol': 'udp'}, {'port': 8080, 'protocol': 'tcp'}]"
   | matchport guid=550e8400-e29b-41d4-a716-446655440000
   

   Outputs only records included in the specified port group.

2. Extract records not matching a port group

   json "[{'port': 80, 'protocol': 'tcp'}, {'port': 53, 'protocol': 'udp'}, {'port': 8080, 'protocol': 'tcp'}]"
   | matchport guid=550e8400-e29b-41d4-a716-446655440000 invert=t
   

   Uses the invert=t option to output only records not included in the port group.

3. Specify custom field names

   json "[{'dst_port': 443, 'proto': 'tcp'}, {'dst_port': 53, 'proto': 'udp'}]"
   | matchport guid=550e8400-e29b-41d4-a716-446655440000 port=dst_port protocol=proto
   

   Specifies the port number field and protocol field names using the port and protocol options.

4. Specifying a port group by name (4.0 series, 4.0.2609.0 and later)

   json "[{'port': 80, 'protocol': 'tcp'}, {'port': 53, 'protocol': 'udp'}]"
   | matchport name=web_ports
   

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

Change history