Skip to main content

TFTP

Synopsis​

Creates a server that accepts file uploads using the TFTP protocol. Supports IP-based device mapping 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>

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
max_buffer_sizeN128MBIngest buffer admission cap. Also sizes this listener's ingest buffers: 3/8 of this value at start, growing to at most 3x
note

This device does not apply reuse or workers. It receives uploads on one UDP socket with one listener, whatever they are set to, and both keys are still accepted rather than refused. When workers is set to anything other than 1, a Verbose log line says The listener reads requests from one socket, so it runs 1 worker instead of the N configured., with N the configured count. Throughput is not capped by this: uploads are handled concurrently, each transfer on its own socket.

In Director versions before v2.4.0, a device whose workers resolved above 1 started one listener per worker. That included every device left at the default on a Director with more than 16 CPUs, and any device configured with workers: 2 or more. Every listener after the first failed to bind the port already taken, logged Server is failed to accept requests. and held its buffers until the device stopped. Uploads still arrived on the first listener. Such a device now runs one listener, with no change to its configuration. A device created in the web interface sends workers: 1 with reuse off, so it runs one listener on those versions as well.

If the listener cannot bind its port, because another process holds it, the device stops and the Director restarts it, rather than reporting it connected while nothing listens.

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, whose buffers take 48 MiB of heap per listener worker at start and grow to at most 384 MiB as bursts need the room — 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.

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

Multiple Devices​

Handling concurrent uploads from multiple devices:

Configuring server for multiple devices...

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

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

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.