s3tftpd

README

= s3tftpd(8)
Kasumi Hanazuki
:doctype: manpage
:mansource: github.com/hanazuki/s3tftpd

== 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 https://www.freedesktop.org/software/systemd/man/systemd-socket-activate.html[`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 https://aws.github.io/aws-sdk-go-v2/docs/configuring-sdk/#specifying-credentials[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 https://min.io/[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 https://github.com/users/hanazuki/packages/container/package/s3tftpd[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/
```