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. The environment variable AWS_REGION can also be used to specify AWS 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 the maximum permitted block size in octets (513..65464). Actual block size is negotiated with the client via the blksize extension (RFC 2348). Set to 0 (default) to impose no server-side limit. Note that even when set to 0, the negotiated block size may still be capped to the interface MTU minus protocol overhead unless --ignore-mtu is specified.

-M, --ignore-mtu

Honors the client-requested block size without clamping to the interface MTU. By default, s3tftpd clamps the negotiated block size to the interface MTU minus protocol overhead to avoid UDP fragmentation.

-a, --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).

-s, --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.

--expected-bucket-owner=ACCOUNT-ID

Rejects requests if the bucket is not owned by the specified AWS account ID. Helps prevent accidentally accessing a bucket in a different account when bucket names are similar.

--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.

--no-sign-request

Makes requests without signing. Suitable for accessing publicly accessible buckets without AWS credentials.

--requester-pays

Indicates that the requester will pay for requests and data transfer costs. Use this when accessing S3 buckets that have Requester Pays enabled.

-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, arm64 and armv7 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/