The Redirects File MUST be named
_redirects and stored underneath the root CID of the website.
The Redirects File MUST be a text file containing one or more lines with the following format (brackets indication optionality).
from to [status]
The path to redirect from.
The URL or path to redirect to.
An optional integer specifying the HTTP status code to return from the request. Supported values are:
200 - OK
301 - Permanent Redirect (default)
302 - Found (commonly used for Temporary Redirect)
303 - See Other (replacing PUT and POST with GET)
307 - Temporary Redirect (explicitly preserving body and HTTP method of original request)
308 - Permanent Redirect (explicitly preserving body and HTTP method of original request)
404 - Not Found
410 - Gone
451 - Unavailable For Legal Reasons
Placeholders are named variables that can be used to match path segments in the
from path and inject them into the
This rule will redirect a URL like
Implementation MUST error when the same placeholder name is used more than once in
Implementation MUST allow the same placeholder name to be used more than once in
from path ends with an asterisk (i.e.
*), the remainder of the
from path is slurped up into the special
:splat placeholder, which can then be injected into the
This rule will redirect a URL like
Splat logic MUST only apply to a single trailing asterisk, as this is a greedy match, consuming the remainder of the path.
Lines MUST be separated from each other by either
Termination of the last line in the file is optional.
Blank lines, leading and trailing whitespace characters like
\x20 (space) or
\t (tab) MUST be ignored, aside from the line termination mentioned above.
The file size MUST NOT exceed 64 KiB.
Rules MUST only be evaluated in contexts where Same-Origin isolation per root CID is possible.
This requirement is fulfilled on a Subdomain or DNSLink HTTP Gateway,
and also applies to a web browser with native
ipns:// scheme handler.
Rules MUST be evaluated in order, redirecting or rewriting using the first matching rule.
All redirect logic MUST only be evaluated if the requested path is not present in the DAG. This means that any performance impact associated with checking for the existence of a
_redirects file or evaluating redirect rules will only be incurred for non-existent paths.
_redirects file exists but there is an error reading or parsing it, the errors MUST be returned to the user with a 500 HTTP status code.
This functionality will only be evaluated for Subdomain or DNSLink Gateways, to ensure that redirect paths are relative to the root CID hosted at the specified domain name.
Parsing of the
_redirects file should be done safely to prevent any sort of injection vector or daemon crash.
The max file size helps to prevent an additional denial of service attack vector.
Sample files for various test cases can be found in
Implementations SHOULD use it for internal testing.
$ ipfs ls QmQyqMY5vUBSbSxyitJqthgwZunCQjDVtNd8ggVCxzuPQ4
QmcBcFnKKqgpCVMxxGsriw9ByTVF6uDdKDMuEBq3m6f1bm - bad-codes/
QmYBhLYDwVFvxos9h8CGU2ibaY66QNgv8hpfewxaQrPiZj - examples/
QmU7ysGXwAtiV7aBarZASJsxKoKyKmd9Xrz2FFamSCbg8S - forced/
QmWHn2TunA1g7gQ7q9rwAoWuot2hMpojZ6cZ9ERsNKm5gE - good-codes/
QmRgpzYQESidTtTojN8zRWjiNs9Cy6o7KHRxh7kDpJm3KH - invalid/
QmYzMrtPyBv7LKiEAGLLRPtvqm3SjQYLWxwWQ2vnpxQwRd - newlines/
QmQTfvjGmvTfxFpUcZNLdTLuKV227KJkGiN6xooHVeVZAS - too-large/
For example, the "examples" site can be found in
$ ipfs ls /ipfs/QmYBhLYDwVFvxos9h8CGU2ibaY66QNgv8hpfewxaQrPiZj
Qmd9GD7Bauh6N2ZLfNnYS3b7QVAijbud83b8GE8LPMNBBP 7 404.html
QmSmR9NShZ89VEBrn9SBy7Xxvjw8Qe6XArD5GqtHvbtBM3 7 410.html
QmVQqj9oZig9tH3ENHo4bxV5pNgssUwFCXUjAJAVcZVbJG 7 451.html
QmZU3kboiyi9jV59D8Mw8wzuvsr3HmvskqhYRRhdFA8wRq 317 _redirects
QmaWDLb4gnJcJbT1Df5X3j91ysiwkkyxw6329NLiC1KMDR - articles/
QmS6ZNKE9s8fsHoEnArsZXnzMWijKddhXXDsAev8LdTT5z 9 index.html
QmNwEgMrExwSsE8DCjZjahYfHUfkSWRhtqSkQUh4Fk3udD 7 one.html
QmVe2GcTbEPZkMbjVoQ9YieVGKCHmuHMcJ2kbSCzuBKh2s - redirected-splat/
QmUGVnZaofnd5nEDvT2bxcFck7rHyJRbpXkh9znjrJNV92 7 two.html
_redirects file is as follows.
$ ipfs cat /ipfs/QmYBhLYDwVFvxos9h8CGU2ibaY66QNgv8hpfewxaQrPiZj/_redirects
/301-redirect-one /one.html 301
/302-redirect-two /two.html 302
/200-index /index.html 200
/posts/:year/:month/:day/:title /articles/:year/:month/:day/:title 301
/splat/* /redirected-splat/:splat 301
/not-found/* /404.html 404
/gone/* /410.html 410
/unavail/* /451.html 451
/* /index.html 200
The non-existent paths that are being requested should be intercepted and redirected to the destination path and the specified HTTP status code returned. The rules are evaluated in the order they appear in the file.
Any request for an existing file should be returned as is, and not intercepted by the last catch all rule.