Skip to content

4. NTPL Filter Syntax

Jump to bottom
Mark Bednarczyk edited this page Nov 12, 2024 · 1 revision

Napatech NTPL Filter Syntax Overview

Overview

Napatech's NTPL (Napatech Programming Language) filter expressions provide a robust and flexible framework for defining criteria to select and process network packets. Designed to leverage Napatech's high-performance network processing capabilities, NTPL enables users to create precise and efficient filters tailored to specific monitoring and data analysis needs. Understanding the comprehensive syntax and its applications is essential for maximizing the effectiveness of NTPL in various network environments.

Syntax Fundamentals

NTPL filter expressions are constructed using a combination of field specifiers, comparison operators, and logical operators. This structure allows for both simple and complex filtering logic, accommodating a wide range of network scenarios.

  • Filter Expressions:

    • Components:
      • Field Specifiers: Identify specific attributes of network packets (e.g., src_ip, dst_port, Layer3Protocol).
      • Comparison Operators: Define how field values are compared (e.g., ==, !=, <, >, <=, >=).
      • Logical Operators: Combine multiple conditions to form compound expressions (AND, OR).
    • Purpose: Determine whether a packet matches the specified criteria based on its attributes.

  • Filter Structure:

    • Basic Format: 
      <Condition1> AND <Condition2> OR <Condition3>
    • Use of Parentheses:
      • Enhance readability and ensure correct evaluation order.
      • Example: 
        (src_ip == 10.0.0.1 OR src_ip == 10.0.0.2) AND protocol == TCP

  • Operator Precedence:

    • AND has higher precedence than OR.
    • Parentheses can be used to override default precedence and group conditions logically.

Filter Types

NTPL encompasses a variety of filter types, each designed to evaluate specific aspects of network packets. These filters can be used individually or in combination to create comprehensive filtering rules.

  • Protocol Tests:

    • Purpose: Filter packets based on protocol-related attributes.
    • Components:
      • Encapsulation Type: e.g., Encapsulation == VLAN, MPLS
      • Layer Protocols: e.g., Layer3Protocol == IP, Layer4Protocol != UDP
      • Tunnel Type: e.g., TunnelType == GREv0, GREv1
    • Usage: Target specific protocols or exclude unwanted ones to streamline traffic analysis.

  • Data and Length Tests:

    • Data Tests:
      • Purpose: Filter based on specific data patterns within the packet payload.
      • Components:
        • DataType: Defines the type of data being inspected (e.g., MacAddr, IPv4Addr).
        • ProtOffset: Specifies the position within the packet for the data test.
        • DataMask: Applies a mask for partial comparisons.
    • Length Tests:
      • Purpose: Filter packets based on their size or specific segments within them.
      • Components:
        • Length Constraints: Define minimum, maximum, or exact packet sizes.
        • Dynamic/Static Offsets: Apply tests to specific parts of the frame.
    • Usage: Ensure packets meet size requirements or contain specific data patterns essential for analysis.

  • Key and Match Tests:

    • Purpose: Enable advanced filtering based on predefined key sets, facilitating flow matching and subscriber identification.
    • Components:
      • Key Definitions: Combine multiple packet fields into keys.
      • Key Sets: Groups of keys used to categorize packets.
      • Options: Customize matching behavior with parameters like ColorInfo, KeyID, CounterSet, and FieldAction.
    • Usage: Implement stateful inspections, dynamic filtering, and complex traffic categorization based on multiple packet attributes.

  • Error and Port Tests:

    • Error Tests:
      • Purpose: Filter packets based on detected errors such as CRC errors, code violations, or truncated frames.
      • Components:
        • Error Flags: Indicators like CrcError, CvError, Truncated.
    • Port Tests:
      • Purpose: Filter based on specific source or destination port numbers.
      • Components:
        • Port Numbers: Single ports, multiple ports, or ranges (e.g., Port == 2,3, Port < 4).
    • Usage: Maintain network integrity by isolating erroneous traffic and manage application-level protocols through port-based filtering.

Depth of Syntax

NTPL's syntax is designed to offer extensive flexibility and precision, allowing users to craft highly specific filter expressions tailored to complex networking requirements.

  • Nested Conditions:

    • Enable the creation of multi-layered logical groupings within filters.
    • Example: 
      ((src_ip == 10.0.0.1 AND dst_port == 80) OR (src_ip == 10.0.0.2 AND dst_port == 443)) AND protocol == TCP

  • Dynamic and Static Offsets:

    • Dynamic Offsets: Adjust filter conditions based on protocol-specific locations within packets.
    • Static Offsets: Apply filters to fixed positions within the frame.
    • Usage: Target specific sections of packets for data or length tests, especially in encapsulated or tunneled traffic.

  • Masked Comparisons:

    • Allow partial comparisons by applying masks to data fields.
    • Example: 
      Data [ProtOffset=Layer4Header[0]; DataType=ByteStr4; DataMask=[31:16]] == 80

  • Options and Modifiers:

    • Enhance filter behavior with additional parameters.
    • Examples:
      • ColorInfo: Integrates color information for matched packets.
      • FieldAction: Defines actions like Swap to alter field processing during key matching.
      • CounterSet: Selects which counter set to increment upon a match.

This depth ensures that NTPL can accommodate a wide range of filtering scenarios, from simple packet selection to intricate flow-based traffic management.

Best Practices

To maximize the effectiveness and maintainability of NTPL filter expressions, consider the following best practices:

  • Maintain Readability:

    • Use clear and consistent formatting.
    • Employ indentation and spacing to separate logical sections within filters.
    • Example: 
      (src_ip == 192.168.1.* OR src_ip == 10.0.0.*) AND protocol == TCP AND NOT src_ip == 10.0.0.5

  • Use Meaningful Field Specifiers:

    • Select fields that accurately represent the criteria you intend to filter.
    • Focus on relevant packet attributes to avoid unnecessary complexity.

  • Leverage Parentheses for Clarity:

    • Group related conditions to ensure correct evaluation order and enhance readability.
    • Prevent logical errors by explicitly defining condition precedence.

  • Optimize Wildcard Usage:

    • Use wildcards judiciously to balance flexibility with specificity.
    • Avoid overly broad wildcards that may capture unintended traffic.

  • Employ Regular Expressions for Complex Patterns:

    • Utilize regex for advanced matching scenarios where simple wildcards are insufficient.
    • Ensure regex patterns are optimized to prevent performance degradation.

  • Prioritize Conditions:

    • Place the most restrictive or frequently matched conditions first to enhance performance.
    • Reduce the processing load by minimizing unnecessary evaluations.

  • Test Expressions Incrementally:

    • Validate each condition step-by-step to ensure accurate behavior before combining them.
    • Simplify troubleshooting by isolating and testing individual components.

  • Document Complex Expressions:

    • Add comments or documentation to explain the purpose and logic of intricate filter expressions for future reference.
    • Enhance maintainability by providing context and rationale for complex logic.

  • Avoid Redundancy:

    • Eliminate unnecessary conditions that may overlap or contradict each other to streamline the expression.
    • Simplify filters to reduce processing overhead and improve clarity.

  • Consider Performance Implications:

    • Be mindful of the computational cost of complex expressions, especially those involving regex, to maintain optimal performance.
    • Balance filter complexity with the need for real-time processing efficiency.

By adhering to these best practices, users can develop robust, maintainable, and high-performance filter expressions that effectively meet their network monitoring and data processing objectives.

Disclaimer

Trademark and Copyright Notice:

  • Napatech®, NTPL, and NTAPI are trademarks or registered trademarks of Napatech A/S in the United States and/or other countries.
  • All rights reserved. No part of this documentation may be reproduced, distributed, or transmitted in any form or by any means without the prior written permission of Napatech A/S, except as noted below.
  • Use of NTPL and NTAPI names is subject to Napatech's trademark policies. Unauthorized use of these names is strictly prohibited.

Usage Disclaimer:

This documentation is provided for informational purposes only. Napatech A/S makes no warranties, expressed or implied, regarding the accuracy, completeness, or performance of the NTPL filter syntax. Users are responsible for ensuring that their filter expressions comply with applicable laws and regulations. Napatech A/S shall not be liable for any damages arising from the use or inability to use NTPL filter expressions.

For detailed information and support, please refer to the official Napatech documentation or contact Napatech A/S directly.

Clone this wiki locally