s3tftpd(8) Manual Page

Name

s3tftpd - TFTP server with Amazon S3 as backing storage

Synopsis

s3tftpd [OPTION]…​ s3://BUCKET[/PREFIX]

Description

s3tftpd serves files on Amazon S3 via TFTP protocol, supporting both RRQ and WRQ.

s3tftpd expects to receive a file descriptor for a UDP socket from the system manager (e.g. systemd). If you are not using a compatible system manager, you can use systemd-socket-activate(1) to pass a file descriptor to s3tftpd.

systemd-socket-activate -d -l 69 s3tftpd s3://bucket/prefix/

Options

--region

Specifies the AWS region where the S3 bucket resides. Instead of this flag, the environment variable AWS_REGION can be used to specify the region.

-r, --retries=COUNT

Number of retransmissions before the server disconnect the session. Default: 5

-t, --timeout=MSECS

Timeout in milliseconds before the server retransmits a packet. Default: 5000

-b, --blocksize=OCTETS

Specifies maximum permitted block size in octets. Actual block size is negotiated with the client by blksize extension (RFC 2348). Limitation: Maximum block size is clamped to the interface MTU minus header size. Default: 512

--anticipate=WINDOW-SIZE

[experimental] Enables sender anticipation feature, in which the server sends at most WINDOW-SIZE data blocks before waiting ACK packets from the client. It can improve download speed. Set 0 to disable the feature. Default: 0 (disabled).

--no-dualstack

Disables S3 dualstack endpoint. s3tftpd, by default, uses the S3 dualstack endpoint so that it can communicate with S3 in either IPv4 or IPv6. Setting this flag forces s3tftpd to use IPv4 for the communication.

--accelerate

Tells s3tftpd to use S3 Transfer Acceleration. The bucket must be enabled for acceleration.

--endpoint-url=URL

Tells s3tftpd to use the given URL instead of the default S3 endpoint. Used when accessing S3 thourgh interface endpoints or connecting to S3-compatible object storage.

--force-path-style

Tells s3tftpd to use the path-style URLs when accessing objects. Useful when connecting to S3-compatible object storage.

--single-port

[experimantal] Tells s3tftpd to use a single port for all the connections. By default, s3tftpd responds each request with a random source port as defined by the protocol standard. But packets from random port is often blocked by firewalls or NAT gateways between the client and the server. When this flag is set, s3tftpd responds back with the same port as it listens for the incoming requests, so that the response packet is likely allowed by the firewalls.

-v, --verbosity=0-8

Sets the verbosity level. 0 logs nothing, 8 logs everything. Default: 7 (suppresses debug logging)

--debug-api

Enables logging AWS API calls. The output may contain sensitive information. Setting the environment variable AWS_DEBUG to true has the same effect as this flag.

-h, --help

Prints help message.

Security

s3tftpd tries to retrieve AWS credentials from the AWS_* environment variables (static access key or web identity token), shared credentials file or ECS/EC2 metadata service in this order (Refer to AWS SDK for Go V2 document for more details). Because of the nature of TFTP, s3tftpd has no mechanisms of client authentication. Access controls on the objects should be enforced using IAM Policies and/or S3 Bucket Policies, and appropriate network-level access control should be implemented.

S3-compatible object storage

s3tftpd may work with some object storage with S3-compliant interface, such as MinIO. To use other object storage than Amazon S3, pass the custom endpoint URL to --endpoint-url option and, depending on the set up, specify --force-path-style to turn off virtual hosted-style requests.

Container images

Prebuilt Linux container images are available at GitHub Container Registry for amd64 and arm64 architectures. Available tags are latest (the latest release), testing (master branch), and each versioned release.

Example invocation:

export AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_REGION
docker run -p 69:69/udp -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e AWS_REGION ghcr.io/hanazuki/s3tftpd:latest s3://bucket/prefix/