2. `Basic Concepts: GET, PUT, DELETE, POST`_
3. `URLs`_
- 1. `Child Lookup`_
+ 1. `Child Lookup`_
4. `Slow Operations, Progress, and Cancelling`_
5. `Programmatic Operations`_
1. `Reading a file`_
2. `Writing/Uploading a File`_
3. `Creating a New Directory`_
- 4. `Getting Information About A File Or Directory (as JSON)`_
+ 4. `Getting Information About a File Or Directory (as JSON)`_
5. `Attaching an Existing File or Directory by its read- or write-cap`_
6. `Adding Multiple Files or Directories to a Parent Directory at Once`_
7. `Unlinking a File or Directory`_
6. `Browser Operations: Human-Oriented Interfaces`_
- 1. `Viewing A Directory (as HTML)`_
+ 1. `Viewing a Directory (as HTML)`_
2. `Viewing/Downloading a File`_
- 3. `Getting Information About A File Or Directory (as HTML)`_
+ 3. `Getting Information About a File Or Directory (as HTML)`_
4. `Creating a Directory`_
5. `Uploading a File`_
- 6. `Attaching An Existing File Or Directory (by URI)`_
- 7. `Unlinking A Child`_
- 8. `Renaming A Child`_
- 9. `Other Utilities`_
- 10. `Debugging and Testing Features`_
+ 6. `Attaching an Existing File Or Directory (by URI)`_
+ 7. `Unlinking a Child`_
+ 8. `Renaming a Child`_
+ 9. `Relinking ("Moving") a Child`_
+ 10. `Other Utilities`_
+ 11. `Debugging and Testing Features`_
7. `Other Useful Pages`_
8. `Static Files in /public_html`_
get more control over the interface to which the server binds by supplying
additional arguments. For more details, see the documentation on
`twisted.application.strports
-<http://twistedmatrix.com/documents/current/api/twisted.application.strports.html>`_.
+<https://twistedmatrix.com/documents/current/api/twisted.application.strports.html>`_.
Writing "tcp:3456:interface=127.0.0.1" into the web.port line does the same
but binds to the loopback interface, ensuring that only the programs on the
"read-cap" or "write-cap", depending upon whether it enables read-only or
read-write access. These "caps" are also referred to as URIs (which may be
confusing because they are not currently `RFC3986
-<http://tools.ietf.org/html/rfc3986>`_-compliant URIs).
+<https://tools.ietf.org/html/rfc3986>`_-compliant URIs).
The Tahoe web-based API is "REST-ful", meaning it implements the concepts of
"REpresentational State Transfer": the original scheme by which the World
/uri/$DIRCAP/
/uri/$FILECAP
+/cap can be used as a synonym for /uri. If interoperability with older web-API
+servers is required, /uri should be used.
Child Lookup
------------
operations that are intended for web browsers.
-Reading A File
+Reading a File
--------------
``GET /uri/$FILECAP``
purpose.
-Writing/Uploading A File
+Writing/Uploading a File
------------------------
``PUT /uri/$FILECAP``
interprets those arguments in the same way as the linked forms of PUT
described immediately above.
-Creating A New Directory
+Creating a New Directory
------------------------
``POST /uri?t=mkdir``
{
"Fran\u00e7ais": [ "filenode", {
"ro_uri": "URI:CHK:...",
- "size": bytes,
"metadata": {
"ctime": 1202777696.7564139,
"mtime": 1202777696.7564139,
or already has a child named NAME.
-Getting Information About A File Or Directory (as JSON)
+Getting Information About a File Or Directory (as JSON)
-------------------------------------------------------
``GET /uri/$FILECAP?t=json``
existing "tahoe" metadata is preserved. The metadata["tahoe"] value is
reserved for metadata generated by the tahoe node itself. The only two keys
currently placed here are "linkcrtime" and "linkmotime". For details, see
- the section above entitled "Get Information About A File Or Directory (as
+ the section above entitled "Getting Information About a File Or Directory (as
JSON)", in the "About the metadata" subsection.
Note that this command was introduced with the name "set_children", which
descriptions below display the most significant arguments as URL query args.
-Viewing A Directory (as HTML)
+Viewing a Directory (as HTML)
-----------------------------
``GET /uri/$DIRCAP/[SUBDIRS../]``
this form can *only* be used with file caps; it is an error to use a
directory cap after the /named/ prefix.
+ URLs may also use /file/$FILECAP/FILENAME as a synonym for
+ /named/$FILECAP/FILENAME.
-Getting Information About A File Or Directory (as HTML)
+Getting Information About a File Or Directory (as HTML)
-------------------------------------------------------
``GET /uri/$FILECAP?t=info``
This accepts a format= argument in the query string. Refer to the
documentation of POST /uri/$DIRCAP/[SUBDIRS../]?t=mkdir&name=CHILDNAME in
- `Creating A New Directory`_ for information on the behavior of the format=
+ `Creating a New Directory`_ for information on the behavior of the format=
argument.
If a "when_done=URL" argument is provided, the HTTP response will cause the
operation took, etc.
This accepts format= and mutable=true query string arguments. Refer to
- `Writing/Uploading A File`_ for information on the behavior of format= and
+ `Writing/Uploading a File`_ for information on the behavior of format= and
mutable=true.
``POST /uri/$DIRCAP/[SUBDIRS../]?t=upload``
already exist.
This accepts format= and mutable=true query string arguments. Refer to
- `Writing/Uploading A File`_ for information on the behavior of format= and
+ `Writing/Uploading a File`_ for information on the behavior of format= and
mutable=true.
If a "when_done=URL" argument is provided, the HTTP response will cause the
This accepts the same replace= argument as POST t=upload.
-Unlinking A Child
+Unlinking a Child
-----------------
``POST /uri/$DIRCAP/[SUBDIRS../]?t=delete&name=CHILDNAME``
be used.
-Renaming A Child
+Renaming a Child
----------------
``POST /uri/$DIRCAP/[SUBDIRS../]?t=rename&from_name=OLD&to_name=NEW``
same child-cap under the new name, except that it preserves metadata. This
operation cannot move the child to a different directory.
- This operation will replace any existing child of the new name, making it
- behave like the UNIX "``mv -f``" command.
+ The default behavior is to overwrite any existing link at the destination
+ (replace=true). To prevent this (and make the operation return an error
+ instead of overwriting), add a "replace=false" argument. With replace=false,
+ this operation will return an HTTP 409 "Conflict" error if the destination
+ is not the same link as the source and there is already a link at the
+ destination, rather than overwriting the existing link. To allow the
+ operation to overwrite a link to a file, but return an HTTP 409 error when
+ trying to overwrite a link to a directory, use "replace=only-files" (this
+ behavior is closer to the traditional UNIX "mv" command). Note that "true",
+ "t", and "1" are all synonyms for "True"; "false", "f", and "0" are synonyms
+ for "False"; and the parameter is case-insensitive.
+
+
+Relinking ("Moving") a Child
+----------------------------
+
+``POST /uri/$DIRCAP/[SUBDIRS../]?t=relink&from_name=OLD&to_dir=$NEWDIRCAP/[NEWSUBDIRS../]&to_name=NEW``
+ ``[&replace=true|false|only-files]`` (Tahoe >= v1.10)
+
+ This instructs the node to move a child of the given source directory, into
+ a different directory and/or to a different name. The command is named
+ ``relink`` because what it does is add a new link to the child from the new
+ location, then remove the old link. Nothing is actually "moved" — the child
+ is still reachable through any path from which it was formerly reachable,
+ and the storage space occupied by its ciphertext is not affected.
+
+ The source and destination directories must be writeable. If {{{to_dir}}} is
+ not present, the child link is renamed within the same directory. If
+ {{{to_name}}} is not present then it defaults to {{{from_name}}}. If the
+ destination link (directory and name) is the same as the source link, the
+ operation has no effect.
+
+ Metadata from the source directory entry is preserved. Multiple levels of
+ descent in the source and destination paths are supported.
+
+ This operation will return an HTTP 404 "Not Found" error if
+ ``$DIRCAP/[SUBDIRS../]``, the child being moved, or the destination
+ directory does not exist. It will return an HTTP 400 "Bad Request" error
+ if any entry in the source or destination paths is not a directory.
+
+ The default behavior is to overwrite any existing link at the destination
+ (replace=true). To prevent this (and make the operation return an error
+ instead of overwriting), add a "replace=false" argument. With replace=false,
+ this operation will return an HTTP 409 "Conflict" error if the destination
+ is not the same link as the source and there is already a link at the
+ destination, rather than overwriting the existing link. To allow the
+ operation to overwrite a link to a file, but return an HTTP 409 error when
+ trying to overwrite a link to a directory, use "replace=only-files" (this
+ behavior is closer to the traditional UNIX "mv" command). Note that "true",
+ "t", and "1" are all synonyms for "True"; "false", "f", and "0" are synonyms
+ for "False"; and the parameter is case-insensitive.
+
+ When relinking into a different directory, for safety, the child link is
+ not removed from the old directory until it has been successfully added to
+ the new directory. This implies that in case of a crash or failure, the
+ link to the child will not be lost, but it could be linked at both the old
+ and new locations.
+
+ The source link should not be the same as any link (directory and child name)
+ in the ``to_dir`` path. This restriction is not enforced, but it may be
+ enforced in a future version. If it were violated then the result would be
+ to create a cycle in the directory structure that is not necessarily reachable
+ from the root of the destination path (``$NEWDIRCAP``), which could result in
+ data loss, as described in ticket `#943`_.
+
+.. _`#943`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/943
+
Other Utilities
---------------
functionality described above, with the provided $CHILDNAME present in the
'from_name' field of that form. I.e. this presents a form offering to
rename $CHILDNAME, requesting the new name, and submitting POST rename.
+ This same URL format can also be used with "move-form" with the expected
+ results.
``GET /uri/$DIRCAP/[SUBDIRS../]CHILDNAME?t=uri``
dictionary with the following keys::
storage-index: a base32-encoded string with the objects's storage index,
- or an empty string for LIT files
+ or an empty string for LIT files
summary: a string, with a one-line summary of the stats of the file
results: a dictionary that describes the state of the file. For LIT files,
- this dictionary has only the 'healthy' key, which will always be
- True. For distributed files, this dictionary has the following
- keys:
- count-shares-good: the number of good shares that were found
- count-shares-needed: 'k', the number of shares required for recovery
- count-shares-expected: 'N', the number of total shares generated
- count-good-share-hosts: this was intended to be the number of distinct
- storage servers with good shares. It is currently
- (as of Tahoe-LAFS v1.8.0) computed incorrectly;
- see ticket #1115.
- count-wrong-shares: for mutable files, the number of shares for
- versions other than the 'best' one (highest
- sequence number, highest roothash). These are
- either old ...
- count-recoverable-versions: for mutable files, the number of
- recoverable versions of the file. For
- a healthy file, this will equal 1.
- count-unrecoverable-versions: for mutable files, the number of
- unrecoverable versions of the file.
- For a healthy file, this will be 0.
- count-corrupt-shares: the number of shares with integrity failures
- list-corrupt-shares: a list of "share locators", one for each share
- that was found to be corrupt. Each share locator
- is a list of (serverid, storage_index, sharenum).
- needs-rebalancing: (bool) True if there are multiple shares on a single
- storage server, indicating a reduction in reliability
- that could be resolved by moving shares to new
- servers.
- servers-responding: list of base32-encoded storage server identifiers,
- one for each server which responded to the share
- query.
- healthy: (bool) True if the file is completely healthy, False otherwise.
- Healthy files have at least N good shares. Overlapping shares
- do not currently cause a file to be marked unhealthy. If there
- are at least N good shares, then corrupt shares do not cause the
- file to be marked unhealthy, although the corrupt shares will be
- listed in the results (list-corrupt-shares) and should be manually
- removed to wasting time in subsequent downloads (as the
- downloader rediscovers the corruption and uses alternate shares).
- Future compatibility: the meaning of this field may change to
- reflect whether the servers-of-happiness criterion is met
- (see ticket #614).
- sharemap: dict mapping share identifier to list of serverids
- (base32-encoded strings). This indicates which servers are
- holding which shares. For immutable files, the shareid is
- an integer (the share number, from 0 to N-1). For
- immutable files, it is a string of the form
- 'seq%d-%s-sh%d', containing the sequence number, the
- roothash, and the share number.
+ this dictionary has only the 'healthy' key, which will always be
+ True. For distributed files, this dictionary has the following
+ keys:
+ count-shares-good: the number of good shares that were found
+ count-shares-needed: 'k', the number of shares required for recovery
+ count-shares-expected: 'N', the number of total shares generated
+ count-good-share-hosts: the number of distinct storage servers with good
+ shares
+ count-wrong-shares: for mutable files, the number of shares for
+ versions other than the 'best' one (highest
+ sequence number, highest roothash). These are
+ either old ...
+ count-recoverable-versions: for mutable files, the number of
+ recoverable versions of the file. For
+ a healthy file, this will equal 1.
+ count-unrecoverable-versions: for mutable files, the number of
+ unrecoverable versions of the file.
+ For a healthy file, this will be 0.
+ count-corrupt-shares: the number of shares with integrity failures
+ list-corrupt-shares: a list of "share locators", one for each share
+ that was found to be corrupt. Each share locator
+ is a list of (serverid, storage_index, sharenum).
+ needs-rebalancing: (bool) True if there are multiple shares on a single
+ storage server, indicating a reduction in reliability
+ that could be resolved by moving shares to new
+ servers.
+ servers-responding: list of base32-encoded storage server identifiers,
+ one for each server which responded to the share
+ query.
+ healthy: (bool) True if the file is completely healthy, False otherwise.
+ Healthy files have at least N good shares. Overlapping shares
+ do not currently cause a file to be marked unhealthy. If there
+ are at least N good shares, then corrupt shares do not cause the
+ file to be marked unhealthy, although the corrupt shares will be
+ listed in the results (list-corrupt-shares) and should be manually
+ removed to wasting time in subsequent downloads (as the
+ downloader rediscovers the corruption and uses alternate shares).
+ Future compatibility: the meaning of this field may change to
+ reflect whether the servers-of-happiness criterion is met
+ (see ticket #614).
+ sharemap: dict mapping share identifier to list of serverids
+ (base32-encoded strings). This indicates which servers are
+ holding which shares. For immutable files, the shareid is
+ an integer (the share number, from 0 to N-1). For
+ immutable files, it is a string of the form
+ 'seq%d-%s-sh%d', containing the sequence number, the
+ roothash, and the share number.
``POST $URL?t=start-deep-check`` (must add &ophandle=XYZ)
machine-readable JSON dictionary with the following keys::
finished: a boolean, True if the operation is complete, else False. Some
- of the remaining keys may not be present until the operation
- is complete.
+ of the remaining keys may not be present until the operation
+ is complete.
root-storage-index: a base32-encoded string with the storage index of the
- starting point of the deep-check operation
+ starting point of the deep-check operation
count-objects-checked: count of how many objects were checked. Note that
- non-distributed objects (i.e. small immutable LIT
- files) are not checked, since for these objects,
- the data is contained entirely in the URI.
+ non-distributed objects (i.e. small immutable LIT
+ files) are not checked, since for these objects,
+ the data is contained entirely in the URI.
count-objects-healthy: how many of those objects were completely healthy
count-objects-unhealthy: how many were damaged in some way
count-corrupt-shares: how many shares were found to have corruption,
- summed over all objects examined
+ summed over all objects examined
list-corrupt-shares: a list of "share identifiers", one for each share
- that was found to be corrupt. Each share identifier
- is a list of (serverid, storage_index, sharenum).
+ that was found to be corrupt. Each share identifier
+ is a list of (serverid, storage_index, sharenum).
list-unhealthy-files: a list of (pathname, check-results) tuples, for
- each file that was not fully healthy. 'pathname' is
- a list of strings (which can be joined by "/"
- characters to turn it into a single string),
- relative to the directory on which deep-check was
- invoked. The 'check-results' field is the same as
- that returned by t=check&output=JSON, described
- above.
+ each file that was not fully healthy. 'pathname' is
+ a list of strings (which can be joined by "/"
+ characters to turn it into a single string),
+ relative to the directory on which deep-check was
+ invoked. The 'check-results' field is the same as
+ that returned by t=check&output=JSON, described
+ above.
stats: a dictionary with the same keys as the t=start-deep-stats command
- (described below)
+ (described below)
``POST $URL?t=stream-deep-check``
will contain the following keys::
storage-index: a base32-encoded string with the objects's storage index,
- or an empty string for LIT files
+ or an empty string for LIT files
repair-attempted: (bool) True if repair was attempted
repair-successful: (bool) True if repair was attempted and the file was
- fully healthy afterwards. False if no repair was
- attempted, or if a repair attempt failed.
+ fully healthy afterwards. False if no repair was
+ attempted, or if a repair attempt failed.
pre-repair-results: a dictionary that describes the state of the file
- before any repair was performed. This contains exactly
- the same keys as the 'results' value of the t=check
- response, described above.
+ before any repair was performed. This contains exactly
+ the same keys as the 'results' value of the t=check
+ response, described above.
post-repair-results: a dictionary that describes the state of the file
- after any repair was performed. If no repair was
- performed, post-repair-results and pre-repair-results
- will be the same. This contains exactly the same keys
- as the 'results' value of the t=check response,
- described above.
+ after any repair was performed. If no repair was
+ performed, post-repair-results and pre-repair-results
+ will be the same. This contains exactly the same keys
+ as the 'results' value of the t=check response,
+ described above.
``POST $URL?t=start-deep-check&repair=true`` (must add &ophandle=XYZ)
finished: (bool) True if the operation has completed, else False
root-storage-index: a base32-encoded string with the storage index of the
- starting point of the deep-check operation
+ starting point of the deep-check operation
count-objects-checked: count of how many objects were checked
count-objects-healthy-pre-repair: how many of those objects were completely
- healthy, before any repair
+ healthy, before any repair
count-objects-unhealthy-pre-repair: how many were damaged in some way
count-objects-healthy-post-repair: how many of those objects were completely
- healthy, after any repair
+ healthy, after any repair
count-objects-unhealthy-post-repair: how many were damaged in some way
count-repairs-attempted: repairs were attempted on this many objects.
count-repairs-successful: how many repairs resulted in healthy objects
count-repairs-unsuccessful: how many repairs resulted did not results in
- completely healthy objects
+ completely healthy objects
count-corrupt-shares-pre-repair: how many shares were found to have
- corruption, summed over all objects
- examined, before any repair
+ corruption, summed over all objects
+ examined, before any repair
count-corrupt-shares-post-repair: how many shares were found to have
- corruption, summed over all objects
- examined, after any repair
+ corruption, summed over all objects
+ examined, after any repair
list-corrupt-shares: a list of "share identifiers", one for each share
- that was found to be corrupt (before any repair).
- Each share identifier is a list of (serverid,
- storage_index, sharenum).
+ that was found to be corrupt (before any repair).
+ Each share identifier is a list of (serverid,
+ storage_index, sharenum).
list-remaining-corrupt-shares: like list-corrupt-shares, but mutable shares
- that were successfully repaired are not
- included. These are shares that need
- manual processing. Since immutable shares
- cannot be modified by clients, all corruption
- in immutable shares will be listed here.
+ that were successfully repaired are not
+ included. These are shares that need
+ manual processing. Since immutable shares
+ cannot be modified by clients, all corruption
+ in immutable shares will be listed here.
list-unhealthy-files: a list of (pathname, check-results) tuples, for
- each file that was not fully healthy. 'pathname' is
- relative to the directory on which deep-check was
- invoked. The 'check-results' field is the same as
- that returned by t=check&repair=true&output=JSON,
- described above.
+ each file that was not fully healthy. 'pathname' is
+ relative to the directory on which deep-check was
+ invoked. The 'check-results' field is the same as
+ that returned by t=check&repair=true&output=JSON,
+ described above.
stats: a dictionary with the same keys as the t=start-deep-stats command
- (described below)
+ (described below)
``POST $URL?t=stream-deep-check&repair=true``
verifycaps: list of (printable) verify cap strings
storage-index: list of (base32) storage index strings
stats: a dictionary with the same keys as the t=start-deep-stats command
- (described below)
+ (described below)
``POST $DIRURL?t=start-deep-size`` (must add &ophandle=XYZ)
size-literal-files: same, for LIT files
size-directories: size of directories (includes size-literal-files)
size-files-histogram: list of (minsize, maxsize, count) buckets,
- with a histogram of filesizes, 5dB/bucket,
- for both literal and immutable files
+ with a histogram of filesizes, 5dB/bucket,
+ for both literal and immutable files
largest-directory: number of children in the largest directory
largest-immutable-file: number of bytes in the largest CHK file
progress-hash (float): 1.0 when the file has been hashed
progress-ciphertext (float): 1.0 when the file has been encrypted.
progress-encode-push (float): 1.0 when the file has been encoded and
- pushed to the storage servers. For helper
- uploads, the ciphertext value climbs to 1.0
- first, then encoding starts. For unassisted
- uploads, ciphertext and encode-push progress
- will climb at the same pace.
+ pushed to the storage servers. For helper
+ uploads, the ciphertext value climbs to 1.0
+ first, then encoding starts. For unassisted
+ uploads, ciphertext and encode-push progress
+ will climb at the same pace.
The "download" op-dict will contain the following keys::
implementation hashes synchronously, so clients will probably never see
progress-hash!=1.0).
-``GET /provisioning/``
-
- This page provides a basic tool to predict the likely storage and bandwidth
- requirements of a large Tahoe grid. It provides forms to input things like
- total number of users, number of files per user, average file size, number
- of servers, expansion ratio, hard drive failure rate, etc. It then provides
- numbers like how many disks per server will be needed, how many read
- operations per second should be expected, and the likely MTBF for files in
- the grid. This information is very preliminary, and the model upon which it
- is based still needs a lot of work.
-
``GET /helper_status/``
If the node is running a helper (i.e. if [helper]enabled is set to True in
and serve it from a configurable directory which defaults to
$BASEDIR/public_html . This is configured by setting the "[node]web.static"
value in $BASEDIR/tahoe.cfg . If this is left at the default value of
-"public_html", then http://localhost:3456/static/subdir/foo.html will be
+"public_html", then http://127.0.0.1:3456/static/subdir/foo.html will be
served with the contents of the file $BASEDIR/public_html/subdir/foo.html .
This can be useful to serve a javascript application which provides a
request may arrive while the file is only halfway written, and the partial
file may be incorrectly parsed.
-The blacklist is applied to all access paths (including FTP, SFTP, and CLI
+The blacklist is applied to all access paths (including SFTP, FTP, and CLI
operations), not just the web-API. The blacklist also applies to directories.
If a directory is blacklisted, the gateway will refuse access to both that
directory and any child files/directories underneath it, when accessed via
HTTP does not provide a mechanism to specify the character set used to
encode non-ASCII names in URLs
- (`RFC3986#2.1 <http://tools.ietf.org/html/rfc3986#section-2.1>`_).
+ (`RFC3986#2.1 <https://tools.ietf.org/html/rfc3986#section-2.1>`_).
We prefer the convention that the ``filename=`` argument shall be a
URL-escaped UTF-8 encoded Unicode string.
For example, suppose we want to provoke the server into using a filename of
(note, the last four bytes of that line, not including the newline, are
0xC3 0xA9 0x65 0x22)
- `RFC2231#4 <http://tools.ietf.org/html/rfc2231#section-4>`_
+ `RFC2231#4 <https://tools.ietf.org/html/rfc2231#section-4>`_
(dated 1997): suggests that the following might work, and
`some developers have reported <http://markmail.org/message/dsjyokgl7hv64ig3>`_
that it is supported by Firefox (but not IE7)::
#2: Content-Disposition: attachment; filename*=utf-8''fianc%C3%A9e
- My reading of `RFC2616#19.5.1 <http://tools.ietf.org/html/rfc2616#section-19.5.1>`_
+ My reading of `RFC2616#19.5.1 <https://tools.ietf.org/html/rfc2616#section-19.5.1>`_
(which defines Content-Disposition) says that the filename= parameter is
defined to be wrapped in quotes (presumably to allow spaces without breaking
the parsing of subsequent parameters), which would give us::
projects / tahoe-lafs / tahoe-lafs.git / blobdiff