Skip to main content

TFTP

Synopsis​

Creates a server that accepts file uploads using the TFTP protocol. Supports IP-based device mapping, multiple workers, and automatic file content processing.

For details, see Appendix.

Schema​

- id: <numeric>
  name: <string>
  description: <string>
  type: tftp
  tags: <string[]>
  pipelines: <pipeline[]>
  status: <boolean>
  properties:
    address: <string>
    port: <numeric>
    reuse: <boolean>
    workers: <numeric>

Configuration​

The following fields are used to define the device:

Device​

FieldRequiredDefaultDescription
idYUnique identifier
nameYDevice name
descriptionN-Optional description
typeYMust be tftp
tagsN-Optional tags
pipelinesN-Optional pre-processor pipelines
statusNtrueEnable/disable the device

Connection​

FieldRequiredDefaultDescription
addressN"0.0.0.0"Listen address
portYListen port (typically 69)

Performance​

FieldRequiredDefaultDescription
reuseNfalseEnable multi-worker mode
workersNScales with CPU countNumber of worker processes: 1 up to 16 cores, 2 up to 32, 3 up to 64, 4 beyond. Never more than 4 — an explicit higher value is clamped — and reduced further on memory-constrained hosts.
max_buffer_sizeN128MBIngest buffer admission cap. Also sets this listener's eager heap reservation
note

max_buffer_size is the ingest-buffer admission cap, and is distinct from any buffer_size field above, which sizes the network read buffer. Left unset it is 128MB, which commits 384 MiB of heap per listener worker before any data arrives — and with reuse: true a device runs one worker per listener. Size strings are binary, and 32MB and 32MiB are exact synonyms.

See Listener Memory Sizing for the arithmetic, the sizing table, and what happens when the cap is exhausted.

warning

TFTP protocol does not support authentication. Deploy only on trusted networks.

Details​

IP-Based Device Mapping​

The server supports automatic device mapping based on client IP addresses: it maps incoming client IPs to device IDs, and automatically associates uploads with devices. It also supports dynamic device discovery and maintains an IP-to-device mapping cache.

Files​

The server processes uploaded files by reading the file contents into memory, recording upload metadata (filename, timestamp, etc.), capturing the client information, and converting the content to consumable format.

Multiple Workers​

When reuse is enabled, the server uses multiple workers which maintain their own TFTP listeners and process files independently so that the files are automatically distributed.

note

The worker count is never more than 4, including an explicit setting above that, and is reduced further on memory-constrained hosts.

Upload​

The device upload operations observe the following procedure:

  • The client initiates a TFTP upload

  • The server accepts the connection

  • The client transfers the file

  • Finally, the server maps the client IP to the device, reads the file contents, applies the pipelines, and saves the processed data to a store.

tip

Configure clients to use binary mode for file transfers to avoid data corruption.

Examples​

The following are commonly used configuration types.

Basic​

Minimal TFTP server listening on port 69:

Creating a simple TFTP server...

devices:
  - id: 1
    name: basic_tftp
    type: tftp
    properties:
      address: "0.0.0.0"
      port: 69

Device Mapping​

Configuring IP-based automatic device association:

Configuring IP-based device mapping...

devices:
  - id: 2
    name: mapped_tftp
    type: tftp
    properties:
      address: "0.0.0.0"
      port: 69
      reuse: false

Multiple Devices​

Handling concurrent uploads from multiple devices with multiple workers:

Configuring server for multiple devices...

devices:
  - id: 4
    name: multi_device_tftp
    type: tftp
    properties:
      address: "0.0.0.0"
      port: 69
      reuse: true
      workers: 2
warning

Ensure all devices are configured to use the same TFTP server port.

High-Volume​

Tuning for high file upload volumes:

Optimizing for high volumes...

devices:
  - id: 3
    name: performant_tftp
    type: tftp
    properties:
      address: "0.0.0.0"
      port: 69
      reuse: true
      workers: 4

Pipelines​

Applying preprocessing pipelines to uploaded file contents:

Applying custom processing to uploaded files...

devices:
  - id: 5
    name: pipeline_tftp
    type: tftp
    pipelines:
      - config_parser
      - field_extractor
    properties:
      address: "0.0.0.0"
      port: 69
note

Pipelines are processed sequentially, and can modify or drop content before ingestion.