DOCSEARCHbyAlgolia
Submit Docs

F5 NGINX Agent Documentation

repository·main·Indexed 18 days ago

https://github.com/nginx/agent

A companion application for remote management of NGINX instances and real-time performance monitoring of NGINX and the underlying operating system. Includes documentation on configuring receivers for NGINX Plus, NGINX, and container metrics, as well as log processors for gzip compression and security violation filtering for NGINX App Protect.

Tokens
20.2K
Snippets
59
Records
80
Agent score
63%

What's inside F5 NGINX Agent

  1. Overview of F5 NGINX Agent

    main

    F5 NGINX Agent is a companion application designed to manage NGINX instances. It provides two primary capabilities:

    • Remote management: Allows for the remote control and configuration of NGINX instances.
    • Real-time metrics: Enables monitoring and analysis of performance data for both the NGINX service and the host operating system.

  2. Understand the NGINX Agent project structure

    main

    The NGINX Agent project follows standard Go project layout patterns to separate application entry points, public libraries, and private implementation details. Understanding this layout helps in locating executable entry points, public APIs, and testing utilities.

    Key Directories

    • /cmd: Contains the main applications. Each subdirectory name corresponds to the name of the resulting executable (e.g., /cmd/agent produces the agent binary).
    • /pkg: Contains public library code intended to be imported by external applications (e.g., /pkg/files, /pkg/uuid).
    • /internal: Contains private application and library code. Code in this directory is not exported and cannot be imported by external projects.
    • /api: Contains API definitions using Protocol Buffers (protobuf) and generated gRPC code for client/server communication.
    • /test: Contains test-specific configurations and helper libraries. It also includes a mock management server located at /mock/grpc/cmd/main.go used to simulate a management server for testing purposes.
    • /vendor: Contains application dependencies. If using Go versions older than 1.14, you may need to use the -mod=vendor flag during builds.
    • /scripts: Contains scripts for Docker, packaging, and testing operations, as well as helper configurations like logrotate settings.
    • /build: A location for transient packaging and build artifacts (not under source control).
    • /docs: Project documentation.

  3. What the Logs gzip processor does

    main

    The Logs gzip processor compresses the body of input log records in-place using gzip.

    Note on Data Types:

    • Logs: The processor actively gzips the record body.
    • Metrics and Traces: The processor acts as a pass-through and does not perform any compression, as it does not implement the required interfaces for these types.

  4. Understand the CommandService RPC flow

    main

    The CommandService defines the command and control interface for a Data Plane Client. Most operations follow a Client $\rightarrow$ Server pattern, with the exception of Subscribe, which is a bidirectional stream.

    Communication Rules for Subscribe:

    • The Subscribe stream provides a decoupled mechanism between the data plane and management plane.
    • Messages from the Management Plane must be a FIFO ordered queue.
    • Messages must have a monotonically-increasing 64-bit signed integer index.
    • The index must not reset for the entire lifetime of a unique Agent (even after disconnections).
    • Messages must not be removed from the Management Plane queue until they are Ack'd by the Agent.
    • Sent but un-Ack'd messages must be kept in an "in-flight" buffer for potential retries.
    | Method Name | Request Type | Response Type | Description |
| ----------- | ------------ | ------------- | ------------ |
| CreateConnection | [CreateConnectionRequest](#mpi-v1-CreateConnectionRequest) | [CreateConnectionResponse](#mpi-v1-CreateConnectionResponse) | Connects NGINX Agent to the Management Plane agnostic of instance data |
| UpdateDataPlaneStatus | [UpdateDataPlaneStatusRequest](#mpi-v1-UpdateDataPlaneStatusRequest) | [UpdateDataPlaneStatusResponse](#mpi-v1-UpdateDataPlaneStatusResponse) | Reports on instances and their configurations |
| UpdateDataPlaneHealth | [UpdateDataPlaneHealthRequest](#mpi-v1-UpdateDataPlaneHealthRequest) | [UpdateDataPlaneHealthResponse](#mpi-v1-UpdateDataPlaneHealthResponse) | Reports on instance health |
| Subscribe | [DataPlaneResponse](#mpi-v1-DataPlaneResponse) stream | [ManagementPlaneRequest](#mpi-v1-ManagementPlaneRequest) stream | A decoupled communication mechanism between the data plane and management plane. |

  5. Understand the Config Apply and Rollback lifecycle

    main

    The NGINX Agent follows a strict sequence when applying new configurations to ensure system stability. If any step in the process fails, the agent initiates a rollback to the previous known good state.

    The Config Apply Flow

    1. File Operations: The agent performs file actions (Write, Add, or Delete) to stage the new configuration.
    2. Validation: The agent runs a configuration validation command. If validation fails, the process stops and triggers a failure response.
    3. Reload: The agent attempts to reload NGINX with the new configuration.
    4. Log Monitoring: After a reload, the agent monitors the NGINX logs for errors. If errors are detected during this monitoring period, the application is considered failed.

    Error Responses

    When a failure occurs at any stage, the agent communicates the status via the Data Plane:

    • COMMAND_STATUS_ERROR: Indicates a specific error occurred during the execution of a step (e.g., a file operation failed or validation failed).
    • COMMAND_STATUS_FAILURE: Indicates the overall configuration application process has failed and the system is reverting or has reverted to the previous state.

  6. Understand Config Apply States

    main

    When applying configurations, the NGINX Agent tracks the progress and outcome using two distinct types of status: Internal Agent Status and Data Plane Response Status.

    Understanding these states is critical for troubleshooting whether a configuration failure originated within the agent's execution logic or within the data plane (e.g., NGINX itself) responding to the new configuration.

    Status Types

    • Internal Agent Status: Indicates the state of the agent's command execution (e.g., whether the agent is currently processing a command or has reached a terminal state like OK or FAILURE).
    • Data Plane Response Status: Indicates how the data plane (the service being configured) responded to the configuration change.

    State Transitions

    • COMMAND_STATUS_IN_PROGRESS: The agent is currently attempting to apply the configuration.
    • COMMAND_STATUS_OK: The configuration was applied successfully.
    • COMMAND_STATUS_FAILURE: The configuration application failed.
    • COMMAND_STATUS_ERROR: An error occurred during the process, which may lead to further retries or a final FAILURE state depending on the specific error type and flow.

  7. Implement chunked file streaming with FileDataChunk

    main

    For large file transfers, use the streaming methods GetFileStream or UpdateFileStream with the FileDataChunk message.

    Streaming Assumptions & Constraints:

    • A stream must contain exactly one FileDataChunkHeader.
    • FileDataChunkContents must follow the header.
    • The number of FileDataChunkContents must match the chunks count in the header.
    • Each chunk_id must be unique and zero-indexed.
    • FileDataChunkContent.data cannot be zero-length.
    • The combined hash of all chunks must match FileDataChunkHeader.file_meta.hash.
    • The total size of combined contents must match FileDataChunkHeader.file_meta.size.
    • chunk_size must be less than the gRPC max message size.
    ### FileDataChunk

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| meta | [MessageMeta](#mpi-v1-MessageMeta) |  | meta regarding the transfer request |
| header | [FileDataChunkHeader](#mpi-v1-FileDataChunkHeader) |  | Chunk header |
| content | [FileDataChunkContent](#mpi-v1-FileDataChunkContent) |  | Chunk data |

  8. What the SecurityViolations Processor does

    main

    The SecurityViolations Processor is an internal component of the NGINX Agent's log collection pipeline. Its purpose is to process security violation syslog messages by parsing RFC3164 formatted syslog entries from log records.

    When a message is successfully parsed, the processor extracts structured attributes and replaces the original log body with the clean, extracted message content.

  9. Understand the Config Apply lifecycle and error responses

    main

    When a configuration change is requested, the NGINX Agent follows a specific lifecycle to ensure stability. Understanding the possible outcomes and response codes is critical for troubleshooting deployment failures.

    Config Apply Outcomes

    1. Success (COMMAND_STATUS_OK): The files were written, the NGINX configuration was validated, the NGINX service was reloaded successfully, and no errors were detected in the logs during the monitoring phase.
    2. Failure (COMMAND_STATUS_FAILURE): This occurs when the agent cannot proceed with the request. Common causes include:
      • Files are not in the allowed directory list.
      • An error occurred while determining or performing file actions (Write, Add, Delete).
      • A rollback was triggered after a validation or reload error, and the rollback itself resulted in a failure.
    3. Error (COMMAND_STATUS_ERROR): This indicates a problem during the application process that triggers a rollback attempt. This typically happens when:
      • The NGINX configuration validation fails.
      • The NGINX reload command fails.
      • Errors are detected in the logs immediately following a reload.

    Rollback Mechanism

    If a validation error or a reload error occurs, the agent attempts to perform a Rollback to restore the previous known-good configuration state. If the rollback fails, the agent returns COMMAND_STATUS_FAILURE.

  10. Understand the Security Violations Filter Processor gate behavior

    main

    The processor uses a one-time "gate" mechanism to prevent mixed or unexpected logging formats from being processed. This gate is determined by the very first log record the processor encounters.

    Gate Lifecycle:

    1. Initial State: pending.
    2. Opening the Gate: The gate opens when the processor receives its first valid string body (a string with exactly 28 pipe-delimited fields).
    3. Closing the Gate: The gate closes if the first inspected record is either:
      • Not a string body.
      • A string body that does not have exactly 28 fields.

    CRITICAL: Once the gate is closed, all subsequent security violation log records are dropped until the OpenTelemetry collector is restarted. Because the decision is made based on the first record, startup ordering is critical. If the first record received is malformed, valid records will be dropped until a restart occurs.

  11. How the Security Violations Filter Processor works

    main

    The Security Violations Filter Processor is an internal component in the NGINX Agent collector pipeline designed for NGINX App Protect security violation logs.

    Its primary function is to validate that incoming log bodies match the expected secops-dashboard-log pipe-delimited format before they are forwarded downstream. It does not parse or transform the log body; it only verifies the structure and adds schema metadata.

    Key Behaviors:

    • Validation: It checks that the log body is a string and contains exactly 28 pipe-delimited (|) fields.
    • Metadata Injection: Upon successful validation, it adds the following resource attributes to the record:
      • csv.schema.name=secops-dashboard-log
      • csv.schema.version=1.0
    • Passthrough: The original log body is passed through unchanged. Parsing and field extraction are handled by downstream components.

  12. Configure the NGINX Plus Receiver

    main

    The NGINX Plus Receiver fetches metrics from a NGINX Plus instance using the ngx_http_api_module's api endpoint.

    To use this receiver, you must first ensure your NGINX Plus instance is configured to expose API information via the ngx_http_api_module.

    In the agent configuration, you must provide the api_details object. The receiver also supports tuning the collection frequency and startup delay.

    receivers:
  nginxplus:
    api_details:
      url: "http://localhost:80/api"
      listen: "localhost:80"
      location: "/api"
    collection_interval: 10s