|
| 1 | +--- |
| 2 | +title: Configuration |
| 3 | +layout: default |
| 4 | +nav_order: 3 |
| 5 | +--- |
| 6 | + |
| 7 | +## Table of contents |
| 8 | +{: .no_toc .text-delta } |
| 9 | + |
| 10 | +1. TOC |
| 11 | +{:toc} |
| 12 | + |
| 13 | +## Configuration options |
| 14 | + |
| 15 | +tusd can be configured and customized by passing flags when starting the process. Please consult the output of `tusd -help` for all available flags. |
| 16 | + |
| 17 | +## Network configuration |
| 18 | + |
| 19 | +By default, tusd listens on port 8080 and all available interface. This can be changed by the `-host` and `-port` flags: |
| 20 | + |
| 21 | +```bash |
| 22 | +$ tusd -host 127.0.0.1 -port 1337 |
| 23 | +``` |
| 24 | + |
| 25 | +Once running, tusd accepts HTTP/1.1 requests on the configured port. If [HTTPS/TLS](#httpstls) is configured, tusd will also accept HTTP/2 connection, thanks to [Go's transparent support](https://pkg.go.dev/net/http#hdr-HTTP_2). HTTP/3 and QUIC is currently not supported without the use of an external proxy. |
| 26 | + |
| 27 | +### UNIX socket |
| 28 | + |
| 29 | +Instead of listening on a TCP socket, tusd can also be configured to listen on a UNIX socket: |
| 30 | + |
| 31 | +```bash |
| 32 | +$ tusd -unix-sock /var/my-tusd.sock |
| 33 | +``` |
| 34 | + |
| 35 | +### Base path |
| 36 | + |
| 37 | +Uploads can be created by sending a `POST` request to the upload creation endpoint. This endpoint is, by default, available under the `/files/` path, e.g. `http://localhost:8080/files/`. Other paths cannot be used to create uploads. This path can be customized using the `-base-path` flag: |
| 38 | + |
| 39 | +```bash |
| 40 | +# Upload creation at http://localhost:8080/api/uploads/ |
| 41 | +$ tusd -base-path /api/uploads |
| 42 | +# Upload creation at http://localhost:8080/ |
| 43 | +$ tusd -base-path / |
| 44 | +``` |
| 45 | + |
| 46 | +### Proxies |
| 47 | + |
| 48 | +When tusd is utilized behind a reverse proxy (Nginx, HAProxy etc), tusd and the proxy must be configured appropriate to works together. |
| 49 | + |
| 50 | +Firstly, you must set `-behind-proxy` flag indicating tusd that it a reverse proxy is in use and it should respect the `X-Forwarded-*`/`Forwarded` headers: |
| 51 | + |
| 52 | +```bash |
| 53 | +$ tusd -behind-proxy |
| 54 | +``` |
| 55 | + |
| 56 | +Secondly, some of the reverse proxy's settings should be adjusted, depending on the used software: |
| 57 | + |
| 58 | +- *Disable request buffering.* Nginx, for example, reads the entire incoming HTTP request, including its body, before sending it to the backend, by default. This behavior defeats the purpose of resumability where an upload is processed while it's being transferred. Therefore, such as feature should be disabled. |
| 59 | + |
| 60 | +- *Adjust maximum request size.* Some proxies have default values for how big a request may be in order to protect your services. Be sure to check these settings to match the requirements of your application. |
| 61 | + |
| 62 | +- *Forward hostname and scheme.* If the proxy rewrites the request URL, the tusd server does not know the original URL which was used to reach the proxy. This behavior can lead to situations, where tusd returns a redirect to a URL which can not be reached by the client. To avoid this confusion, you can explicitly tell tusd which hostname and scheme to use by supplying the `X-Forwarded-Host` and `X-Forwarded-Proto` headers. |
| 63 | + |
| 64 | +Explicit examples for the above points can be found in the [Nginx configuration](https://github.com/tus/tusd/blob/main/examples/nginx.conf) which is used to power the [tusd.tusdemo.net](https://tusd.tusdemo.net) instance. |
| 65 | + |
| 66 | +## Protocol extensions |
| 67 | + |
| 68 | +### Maximum upload size |
| 69 | + |
| 70 | +By default, tusd does not restrict the maximum size of a single upload. If you want to apply such a limit, use the `-max-size` flag: |
| 71 | + |
| 72 | +```bash |
| 73 | +# Allow uploads up to 1000000000 bytes (= 1GB) |
| 74 | +$ tusd -max-size 1000000000 |
| 75 | +``` |
| 76 | + |
| 77 | +### Disable downloads |
| 78 | + |
| 79 | +tusd allows any user to retrieve a previously uploaded file by issuing an HTTP GET request to the corresponding upload URL. This is possible as long as the uploaded files have not been deleted or moved to another location in the storage backend. While it is a handy feature for debugging and testing your setup, there are situations where you don't want to allow downloads. To completely disable downloads, use the `-disable-download` flag: |
| 80 | + |
| 81 | +```bash |
| 82 | +$ tusd -disable-download |
| 83 | +``` |
| 84 | + |
| 85 | +### Disable upload termination |
| 86 | + |
| 87 | +The [tus termination extensions](https://tus.io/protocols/resumable-upload#termination) allows clients to terminate uploads (complete or incomplete) they are no longer interested in. In this case, the associated files in the storage backend will be removed. If you don't want to allow users to delete uploads, use the `-disable-termination` flag to disable this extension: |
| 88 | + |
| 89 | +```bash |
| 90 | +$ tusd -disable-termination |
| 91 | +``` |
| 92 | + |
| 93 | +## Storage backend |
| 94 | + |
| 95 | +Tusd has been designed with flexible storage backends in mind and can store the received uploads on local disk or various cloud provides (AWS S3, Azure Cloud Storage, and Google Cloud Storage). By default, tusd will store uploads in the directory specified by the `-upload-dir` flag (which defaults to `./data`). Please consult the dedicated [Storage Backends section](/storage_backends/overview/) for details on how to use different storage backend and configure them. |
| 96 | + |
| 97 | +## Integrations into applications with hooks |
| 98 | + |
| 99 | +When integrating tusd into an application, it is important to establish a communication channel between tusd and your main application. For this purpose, tusd provides a hook system which triggers user-defined actions when certain events happen, for example when an upload is created or finished. This simple-but-powerful system enables many uses, such as logging, validation, authorization, and post-processing of the uploaded files. Please consult the dedicated [Storage Backends section](/advanced_topics/hooks/) for details on how to use the hook system. |
| 100 | + |
| 101 | +## Cross-Origin Resource Sharing (CORS) |
| 102 | + |
| 103 | +When tusd is used in a web application and the tusd server is reachable under a different origin (domain, scheme, or port) than the frontend itself, browsers put restrictions on cross-origin requests for security reasons. Using the [Cross-Origin Resource Sharing (CORS) mechanism](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS), the server can instruct the browser to allow cross-origin requests. |
| 104 | + |
| 105 | +By default, tusd will allow cross-origin requests from any origin. All methods and header fields necessary for the tus protocol are allowed in these requests. |
| 106 | + |
| 107 | +If you want to restrict the origins or add additional header fields to the CORS configuration, utilize the `-cors-*` flags: |
| 108 | + |
| 109 | +```bash |
| 110 | +$ tusd \ |
| 111 | + # Restrict origins to example.com |
| 112 | + -cors-allow-origin 'https?://example.com' \ |
| 113 | + # Include credentials in cross-origin requests |
| 114 | + -cors-allow-credentials \ |
| 115 | + # Allow additional headers in Access-Control-Allow-Headers |
| 116 | + -cors-allow-headers X-My-Token \ |
| 117 | + # Allow additional headers in Access-Control-Expose-Headers |
| 118 | + -cors-expose-headers X-Upload-Location \ |
| 119 | + # Cache duration of preflight requests |
| 120 | + -cors-max-age 3600 |
| 121 | +``` |
| 122 | + |
| 123 | +Alternatively, you can completely disable any CORS-related logic in tusd and handle it on your own with a reverse proxy: |
| 124 | + |
| 125 | +```bash |
| 126 | +$ tusd -disable-cors |
| 127 | +``` |
| 128 | + |
| 129 | +## HTTPS/TLS |
| 130 | + |
| 131 | +If you want tusd to be accessible via HTTPS, there are two options: |
| 132 | + |
| 133 | +1. Use a TLS-terminating reverse proxy, such as Nginx. The proxy is configured to accept HTTPS requests from the clients and forwards unencrypted HTTP requests to tusd. This approach is the most flexible and recommended approach as such proxies provide detailed configuration options for HTTPS and are well tested. Please see the [section on proxies](#proxies) for additional details when using tusd with proxies. |
| 134 | + |
| 135 | +2. Tusd itself provies basic TLS support for HTTPS connections. In contrast to dedicated TLS-terminating proxies, tusd provides less configuration options for tuning the TLS setup. However, the built-in HTTPS support is useful for development, testing and encrypting internal traffic. The HTTPS support which can be enabled by supplying a certificate and private key. Note that the certificate file must include the entire chain of certificates up to the CA certificate. The default configuration supports TLSv1.2 and TLSv1.3. It is possible to use only TLSv1.3 with `-tls-mode=tls13`. Alternately, it is possible to disable TLSv1.3 and use only 256-bit AES ciphersuites with `-tls-mode=tls12-strong`. The following example generates a self-signed certificate for `localhost` and then uses it to serve files on the loopback address. Such a self-signed certificate is not appropriate for production use. Note also that the key file must not be encrypted/require a passphrase. |
| 136 | + |
| 137 | +```bash |
| 138 | +# Generate self-signed certificate |
| 139 | +$ openssl req -x509 -new -newkey rsa:4096 -nodes -sha256 -days 3650 -keyout localhost.key -out localhost.pem -subj "/CN=localhost" |
| 140 | +Generating a 4096 bit RSA private key |
| 141 | +........................++ |
| 142 | +..........................................++ |
| 143 | +writing new private key to 'localhost.key' |
| 144 | + |
| 145 | +# Start tusd |
| 146 | +$ tusd -upload-dir=./data -host=127.0.0.1 -port=8443 -tls-certificate=localhost.pem -tls-key=localhost.key |
| 147 | +[tusd] Using './data' as directory storage. |
| 148 | +[tusd] Using 0.00MB as maximum size. |
| 149 | +[tusd] Using 127.0.0.1:8443 as address to listen. |
| 150 | +[tusd] Using /files/ as the base path. |
| 151 | +[tusd] Using /metrics as the metrics path. |
| 152 | +[tusd] Supported tus extensions: creation,creation-with-upload,termination,concatenation,creation-defer-length |
| 153 | +[tusd] You can now upload files to: https://127.0.0.1:8443/files/ |
| 154 | + |
| 155 | +# tusd is now accessible via HTTPS |
| 156 | +``` |
| 157 | + |
| 158 | +## Graceful shutdown |
| 159 | + |
| 160 | +If tusd receives a SIGINT or SIGTERM signal, it will initiate a graceful shutdown. SIGINT is usually emitted by pressing Ctrl+C inside the terminal that is running tusd. SIGINT and SIGTERM can also be emitted using the [`kill(1)`](https://man7.org/linux/man-pages/man1/kill.1.html) utility on Unix. Signals in that sense do not exist on Windows, so please refer to the [Go documentation](https://pkg.go.dev/os/signal#hdr-Windows) on how different events are translated into signals on Windows. |
| 161 | + |
| 162 | +Once the graceful shutdown is started, tusd will stop listening on its port and won't accept new connections anymore. Idle connections are closed down. Already running requests will be given a grace period to complete before their connections are closed as well. PATCH and POST requests with a request body are interrupted, so that data stores can gracefully finish saving all the received data until that point. If all requests have been completed, tusd will exit. |
| 163 | + |
| 164 | +If not all requests have been completed in the period defined by the `-shutdown-timeout` flag, tusd will exit regardless. By default, tusd will give all requests 10 seconds to complete their processing. If you do not want to wait for requests, use `-shutdown-timeout=0`. |
| 165 | + |
| 166 | +tusd will also immediately exit if it receives a second SIGINT or SIGTERM signal. It will also always exit immediately if a SIGKILL is received. |
0 commit comments