From: Daira Hopwood Date: Tue, 11 Aug 2015 17:22:48 +0000 (+0100) Subject: Documentation changes to make MDMF the default mutable format, and X-Git-Url: https://git.rkrishnan.org/?a=commitdiff_plain;h=bf42b7ad9c61b479b57cee067cc6ba6b07344c8e;p=tahoe-lafs%2Ftahoe-lafs.git Documentation changes to make MDMF the default mutable format, and undeprecate "mutable=true". refs ticket:2227 Signed-off-by: Daira Hopwood --- diff --git a/docs/frontends/webapi.rst b/docs/frontends/webapi.rst index 6b04429a..c1bfb654 100644 --- a/docs/frontends/webapi.rst +++ b/docs/frontends/webapi.rst @@ -396,27 +396,27 @@ Writing/Uploading a File specifying a format= argument in the query string. format=MDMF creates an MDMF mutable file. format=SDMF creates an SDMF mutable file. format=CHK creates an immutable file. The value of the format argument is - case-insensitive. If no format is specified, the newly-created file will be - immutable (but see below). - - For compatibility with previous versions of Tahoe-LAFS, the web-API will - also accept a mutable=true argument in the query string. If mutable=true is - given, then the new file will be mutable, and its format will be the default - mutable file format, as configured by the [client]mutable.format option of - tahoe.cfg on the Tahoe-LAFS node hosting the webapi server. Use of - mutable=true is discouraged; new code should use format= instead of - mutable=true (unless it needs to be compatible with web-API servers older - than v1.9.0). If neither format= nor mutable=true are given, the - newly-created file will be immutable. - - This returns the file-cap of the resulting file. If a new file was created - by this method, the HTTP response code (as dictated by rfc2616) will be set - to 201 CREATED. If an existing file was replaced or modified, the response - code will be 200 OK. + case-insensitive. + + The web-API also accepts a mutable=true argument in the query string. + If mutable=true is given, then the new file will be mutable, and its + format will be the default mutable file format, as configured by the + [client]mutable.format option of tahoe.cfg on the Tahoe-LAFS node hosting + the webapi server. + + If neither format= nor mutable=true are given, the newly-created file + will be immutable. + + This method returns the file-cap of the resulting file. If a new file + was created, the HTTP response code (as dictated by `RFC2616`_) will be + set to 201 CREATED. If an existing file was replaced or modified, the + response code will be 200 OK. Note that the 'curl -T localfile http://127.0.0.1:3456/uri/$DIRCAP/foo.txt' command can be used to invoke this operation. +.. _RFC2616: https://tools.ietf.org/html/rfc2616 + ``PUT /uri`` This uploads a file, and produces a file-cap for the contents, but does not diff --git a/docs/specifications/mutable.rst b/docs/specifications/mutable.rst index 09e25f32..0c8943c1 100644 --- a/docs/specifications/mutable.rst +++ b/docs/specifications/mutable.rst @@ -78,7 +78,8 @@ the share format for SDMF could not be used for MDMF, resulting in a larger gap between the two implementations (my original intention had been to make SDMF a clean subset of MDMF, where any single-segment MDMF file could be handled by the old SDMF code). In the fall of 2011, Kevan's code was finally -integrated, and first made available in the Tahoe-1.9.0 release. +integrated, and first made available in the Tahoe-LAFS v1.9.0 release. + SDMF vs. MDMF ------------- @@ -92,20 +93,19 @@ the first segment of data should be delivered faster from a large MDMF file than from an SDMF file, although the overall download will then proceed at the same rate. -We've decided to make it opt-in for now: mutable files default to -SDMF format unless explicitly configured to use MDMF, either in ``tahoe.cfg`` +Starting from Tahoe-LAFS v1.11.0, mutable files default to MDMF format +unless explicitly configured to use SDMF, either in ``tahoe.cfg`` (see ``__) or in the WUI or CLI command that created a -new mutable file. +new mutable file. In previous releases, the default was SDMF. The code can read and modify existing files of either format without user -intervention. We expect to make MDMF the default in a subsequent release, -perhaps 2.0. +intervention. Which format should you use? SDMF works well for files up to a few MB, and -can be handled by older versions (Tahoe-1.8.3 and earlier). If you do not -need to support older clients, want to efficiently work with mutable files, -and have code which will use Range: headers that make partial reads and -writes, then MDMF is for you. +can be handled by older versions (Tahoe-LAFS v1.8.3 and earlier). If you do +not need to support older clients, want to efficiently work with mutable +files, and have code which will use Range: headers that make partial reads +and writes, then MDMF is for you. Consistency vs. Availability diff --git a/docs/specifications/uri.rst b/docs/specifications/uri.rst index 9e6d2336..cfe97f3b 100644 --- a/docs/specifications/uri.rst +++ b/docs/specifications/uri.rst @@ -139,18 +139,21 @@ hash of the public key in the URI. As a result, the data validation is limited to confirming that the data retrieved matches *some* data that was uploaded in the past, but not _which_ version of that data. -The format of the write-cap for mutable files is:: +The format of the write-cap for mutable files, for SDMF and MDMF files +respectively, is:: URI:SSK:(writekey):(fingerprint) + URI:MDMF:(writekey):(fingerprint) Where (writekey) is the base32 encoding of the 16-byte AES encryption key that is used to encrypt the RSA private key, and (fingerprint) is the base32 encoded 32-byte SHA-256 hash of the RSA public key. For more details about the way these keys are used, please see mutable.rst_. -The format for mutable read-caps is:: +The format for mutable read-caps, for SDMF and MDMF files respectively, is:: URI:SSK-RO:(readkey):(fingerprint) + URI:MDMF-RO:(readkey):(fingerprint) The read-cap is just like the write-cap except it contains the other AES encryption key: the one used for encrypting the mutable file's contents. This @@ -178,11 +181,13 @@ way to interpret the contents of these files. As a result, a directory write-cap looks a lot like a mutable-file write-cap:: URI:DIR2:(writekey):(fingerprint) + URI:DIR2-MDMF:(writekey):(fingerprint) Likewise directory read-caps (which provide read-only access to the directory) look much like mutable-file read-caps:: URI:DIR2-RO:(readkey):(fingerprint) + URI:DIR2-MDMF-RO:(readkey):(fingerprint) Historical note: the "DIR2" prefix is used because the non-distributed dirnodes in earlier Tahoe releases had already claimed the "DIR" prefix.