Ticket #1227: html-rst-conversion.patch
| File html-rst-conversion.patch, 17.3 KB (added by p-static, at 2010-12-04T08:36:19Z) |
|---|
-
new file docs/about.rst
diff --git a/docs/about.rst b/docs/about.rst new file mode 100644 index 0000000..a278e3b
- + 1 ====================== 2 Welcome to Tahoe-LAFS! 3 ====================== 4 5 Welcome to `Tahoe-LAFS <http://tahoe-lafs.org>`_, the first 6 decentralized storage system with *provider-independent security*. 7 8 What is "provider-independent security"? 9 ======================================== 10 11 Every seller of cloud storage services will tell you that their service 12 is "secure". But what they mean by that is something fundamentally 13 different from what we mean. What they mean by "secure" is that after 14 you've given them the power to read and modify your data, they try 15 really hard not to let this power be abused. This turns out to be 16 difficult! Bugs, misconfigurations, or operator error can accidentally 17 expose your data to another customer or to the public, or can corrupt 18 your data. Criminals routinely gain illicit access to corporate 19 servers. Even more insidious is the fact that the employees themselves 20 sometimes violate customer privacy out of carelessness, avarice, or 21 mere curiousity. The most conscientious of these service providers 22 spend considerable effort and expense trying to mitigate these risks. 23 24 What we mean by "security" is something different. *The service 25 provider never has the ability to read or modify your data in the first 26 place -- never.* If you use Tahoe-LAFS, then all of the threats 27 described above are non-issues to you. Not only is it easy and 28 inexpensive for the service provider to maintain the security of your 29 data, but in fact they couldn't violate its security if they tried. 30 This is what we call *provider-independent security*. 31 32 This guarantee is integrated naturally into the Tahoe-LAFS storage 33 system and doesn't require you to perform a manual pre-encryption step 34 or cumbersome key management. (After all, having to do cumbersome 35 manual operations when storing or accessing your data would nullify one 36 of the primary benefits of using cloud storage in the first place -- 37 convenience.) 38 39 Here's how it works: 40 41 .. image:: http://tahoe-lafs.org/~zooko/network-and-reliance-topology.png 42 43 A "storage grid" is made up of a number of storage servers. A storage 44 server has direct attached storage (typically one or more hard disks). 45 A "gateway" uses the storage servers and provides access to the 46 filesystem over HTTP(S) or (S)FTP. 47 48 Users do not rely on storage servers to provide *confidentiality* nor 49 *integrity* for their data -- instead all of the data is encrypted and 50 integrity-checked by the gateway, so that the servers can neither read 51 nor modify the contents of the files. 52 53 Users do rely on storage servers for *availability*. The ciphertext is 54 erasure-coded and distributed across ``N`` storage servers (the default 55 value for ``N`` is 10) so that it can be recovered from any ``K`` of 56 these servers (the default value of ``K`` is 3). Therefore only the 57 simultaneous failure of ``N-K+1`` (with the defaults, 8) servers can 58 make the data unavailable. 59 60 In the typical deployment mode each user runs her own gateway on her 61 own machine. This way she relies on her own machine for the 62 confidentiality and integrity of the data. 63 64 An alternate deployment mode is that the gateway runs on a remote 65 machine and the user connects to it over HTTPS or SFTP. This means 66 that the operator of the gateway can view and modify the user's data 67 (the user *relies on* the gateway for confidentiality and integrity), 68 but the advantage is that the user can access the filesystem with a 69 client that doesn't have the gateway software installed, such as an 70 Internet kiosk or cell phone. 71 72 Access Control 73 ============== 74 75 There are two kinds of files: immutable and mutable. Immutable files 76 have the property that once they have been uploaded to the storage grid 77 they can't be modified. Mutable ones can be modified. A user can have 78 read-write access to a mutable file or read-only access to it (or no 79 access to it at all). 80 81 A user who has read-write access to a mutable file or directory can 82 give another user read-write access to that file or directory, or they 83 can give read-only access to that file or directory. A user who has 84 read-only access to a file or directory can give another user read-only 85 access to it. 86 87 When linking a file or directory into a parent directory, you can use a 88 read-write link or a read-only link. If you use a read-write link, 89 then anyone who has read-write access to the parent directory can gain 90 read-write access to the child, and anyone who has read-only access to 91 the parent directory can gain read-only access to the child. If you 92 use a read-only link, then anyone who has either read-write or 93 read-only access to the parent directory can gain read-only access to 94 the child. 95 96 For more technical detail, please see the `the doc page 97 <http://tahoe-lafs.org/trac/tahoe-lafs/wiki/Doc>`_ on the Wiki. 98 99 Get Started 100 =========== 101 102 To use Tahoe-LAFS, please see `quickstart.rst <quickstart.rst>`_. 103 104 License 105 ======= 106 107 You may use this package under the GNU General Public License, version 108 2 or, at your option, any later version. See the file `COPYING.GPL 109 <../COPYING.GPL>`_ for the terms of the GNU General Public License, 110 version 2. 111 112 You may use this package under the Transitive Grace Period Public 113 Licence, version 1 or, at your option, any later version. The 114 Transitive Grace Period Public Licence has requirements similar to the 115 GPL except that it allows you to wait for up to twelve months after you 116 redistribute a derived work before releasing the source code of your 117 derived work. See the file `COPYING.TGGPL <../COPYING.TGPPL.html>`_ for 118 the terms of the Transitive Grace Period Public Licence, version 1. 119 120 (You may choose to use this package under the terms of either licence, 121 at your option.) 122 -
deleted file docs/install.html
diff --git a/docs/install.html b/docs/install.html deleted file mode 100644 index 33b6064..0000000
+ - 1 <!DOCtype HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">2 <html lang="en">3 <head>4 <title>Getting Tahoe-LAFS</title>5 <link rev="made" class="mailto" href="mailto:zooko[at]zooko[dot]com">6 <meta name="description" content="how to get Tahoe-LAFS">7 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">8 <meta name="keywords" content="tahoe-lafs secure decentralized filesystem installation">9 <meta http-equiv="refresh" content="0;url=quickstart.html" />10 </head>11 12 <body>13 <p>This page has moved to <a href="quickstart.html">quickstart.html</a>.</p>14 </body>15 </html> -
new file docs/quickstart.rst
diff --git a/docs/quickstart.rst b/docs/quickstart.rst new file mode 100644 index 0000000..efbedb9
- + 1 ================== 2 Getting Tahoe-LAFS 3 ================== 4 5 Welcome to `the Tahoe-LAFS project <http://tahoe-lafs.org>`_, a secure, 6 decentralized, fault-tolerant storage system. `About Tahoe-LAFS 7 <about.rst>`_. 8 9 How To Get Tahoe-LAFS 10 ===================== 11 12 This procedure has been verified to work on Windows, Mac, OpenSolaris, 13 and too many flavors of Linux and of BSD to list. It's likely to work 14 on other platforms. 15 16 In Case Of Trouble 17 ------------------ 18 19 There are a few 3rd party libraries that Tahoe-LAFS depends on that 20 might not be easy to set up on your platform. If the following 21 instructions don't Just Work without any further effort on your part, 22 then please write to `the tahoe-dev mailing list 23 <http://tahoe-lafs.org/cgi-bin/mailman/listinfo/tahoe-dev>`_ where 24 friendly hackers will help you out. You might also find clues in the 25 `Advanced Installation`_ section described below. 26 27 Install Python 28 -------------- 29 30 Check if you already have an adequate version of Python installed by 31 running ``python -V``. Python v2.4 (v2.4.4 or greater), Python v2.5, 32 Python v2.6, or Python v2.7 will work. Python v3 does not work. On 33 Windows, we recommend the use of Python v2.6 (native, not Cygwin). If 34 you don't have one of these versions of Python installed, then follow 35 the instructions on `the Python download page 36 <http://www.python.org/download/releases/2.6.6/>`_ to download and 37 install Python v2.6. Make sure that the path to the installation 38 directory has no spaces in it (e.g. on Windows, do not install Python 39 in the "Program Files" directory). 40 41 If you are on Windows, you now must manually install the pywin32 42 package from `the pywin32 site 43 <http://sourceforge.net/projects/pywin32/files/>`_ before getting 44 Tahoe-LAFS. Make sure to get the correct file for the version of Python 45 you are using -- e.g. ending in "py2.6.exe" for Python v2.6. If using 46 64-bit Windows, the file should have "win-amd64" in its name. 47 48 Get Tahoe-LAFS 49 -------------- 50 51 `Download the latest stable release, v1.8.1 52 <http://tahoe-lafs.org/source/tahoe-lafs/releases/allmydata-tahoe-1.8.1.zip>`_ 53 54 Set Up Tahoe-LAFS 55 ----------------- 56 57 Unpack the zip file and cd into the top-level directory. 58 59 Run ``python setup.py build`` to generate the ``tahoe`` executable in a 60 subdirectory of the current directory named ``bin``. This will download 61 and build anything you need from various websites. 62 63 On Windows, the ``build`` step might tell you to open a new Command 64 Prompt (or, on XP and earlier, to log out and back in again). This is 65 needed the first time you set up Tahoe-LAFS on a particular 66 installation of Windows. 67 68 Optionally run ``python setup.py test`` to verify that it passes all 69 of its self-tests. 70 71 Run ``bin/tahoe --version`` (on Windows, ``bin\tahoe --version``) to 72 verify that the executable tool prints out the right version number. 73 74 Run Tahoe-LAFS 75 -------------- 76 77 Now you are ready to deploy a decentralized filesystem. The ``tahoe`` 78 executable in the ``bin`` directory can configure and launch your 79 Tahoe-LAFS nodes. See `running.rst <running.rst>`_ for instructions on 80 how to do that. 81 82 Advanced Installation 83 --------------------- 84 85 For optional features such as tighter integration with your operating 86 system's package manager, you can see the `AdvancedInstall 87 <http://tahoe-lafs.org/trac/tahoe/wiki/AdvancedInstall>`_ wiki page. 88 The options on that page are not necessary to use Tahoe-LAFS and can be 89 complicated, so we do not recommend following that page unless you have 90 unusual requirements for advanced optional features. For most people, 91 you should first follow the instructions on this page, and if that 92 doesn't work then ask for help by writing to `the tahoe-dev mailing 93 list <http://tahoe-lafs.org/cgi-bin/mailman/listinfo/tahoe-dev>`_. 94 -
new file docs/running.rst
diff --git a/docs/running.rst b/docs/running.rst new file mode 100644 index 0000000..8424ab0
- + 1 ===================== 2 How To Run Tahoe-LAFS 3 ===================== 4 5 Intro 6 ===== 7 8 This is how to run a Tahoe-LAFS client or a complete Tahoe-LAFS grid. 9 First you have to install the Tahoe-LAFS software, as documented in 10 `quickstart.rst <quickstart.rst>`_. 11 12 The ``tahoe`` program in the ``bin`` directory is used to create, 13 start, and stop nodes. Each node lives in a separate base directory, in 14 which there is a configuration file named ``tahoe.cfg``. Nodes read and 15 write files within this base directory. 16 17 A grid consists of a set of *storage nodes* and *client nodes* running 18 the Tahoe-LAFS code. There is also an *introducer node* that is 19 responsible for getting the other nodes talking to each other. 20 21 If you're getting started we recommend you try connecting to 22 the `the public test grid 23 <http://tahoe-lafs.org/trac/tahoe-lafs/wiki/TestGrid>`_ as you only 24 need to create a client node. When you want to create your own grid 25 you'll need to create the introducer and several initial storage nodes 26 (see the note about small grids below). 27 28 If the Tahoe-LAFS ``bin`` directory is not on your PATH, then in all 29 the command lines below, specify the full path to ``bin/tahoe``. 30 31 To construct a client node, run "``tahoe create-client``", which will 32 create ``~/.tahoe`` to be the node's base directory. Acquire a copy of 33 the ``introducer.furl`` from the introducer and put it into this 34 directory, then use "``tahoe run``". After that, the node should be off 35 and running. The first thing it will do is connect to the introducer 36 and get itself connected to all other nodes on the grid. By default, 37 "``tahoe create-client``" creates a client-only node, that does not 38 offer its disk space to other nodes. To configure other behavior, use 39 "``tahoe create-node``" or see `configuration.rst <configuration.rst>`_. 40 41 To construct an introducer, create a new base directory for it (the 42 name of the directory is up to you), ``cd`` into it, and run 43 "``tahoe create-introducer .``". Now run the introducer using 44 "``tahoe start .``". After it starts, it will write a file named 45 ``introducer.furl`` in that base directory. This file contains the URL 46 the other nodes must use in order to connect to this introducer. (Note 47 that "``tahoe run .``" doesn't work for introducers, this is a known 48 issue: `#937 <http://allmydata.org/trac/tahoe-lafs/ticket/937>`_.) 49 50 The "``tahoe run``" command above will run the node in the foreground. 51 On Unix, you can run it in the background instead by using the 52 "``tahoe start``" command. To stop a node started in this way, use 53 "``tahoe stop``". ``tahoe --help`` gives a summary of all commands. 54 55 See `configuration.rst <configuration.rst>`_ for more details about how 56 to configure Tahoe-LAFS, including how to get other clients to connect 57 to your node if it is behind a firewall or NAT device. 58 59 A note about small grids 60 ------------------------ 61 62 By default, Tahoe-LAFS ships with the configuration parameter 63 ``shares.happy`` set to 7. If you are using Tahoe-LAFS on a 64 grid with fewer than 7 storage nodes, this won't work well for you 65 — none of your uploads will succeed. To fix this, see <a 66 href='configuration.rst'>configuration.rst</a> to learn how to set 67 ``shares.happy`` to a more suitable value for your 68 grid. 69 70 Do Stuff With It 71 ================ 72 73 This is how to use your Tahoe-LAFS node. 74 75 The WUI 76 ------- 77 78 Point your web browser to `http://127.0.0.1:3456 79 <http://127.0.0.1:3456>`_ -- which is the URL of the gateway running on 80 your own local computer -- to use your newly created node. 81 82 Create a new directory (with the button labelled "create a directory"). 83 Your web browser will load the new directory. Now if you want to be 84 able to come back to this directory later, you have to bookmark it, or 85 otherwise save a copy of the URL. If you lose URL to this directory, 86 then you can never again come back to this directory. 87 88 You can do more or less everything you want to do with a decentralized 89 filesystem through the WUI. 90 91 The CLI 92 ------- 93 94 Prefer the command-line? Run "``tahoe --help``" (the same command-line 95 tool that is used to start and stop nodes serves to navigate and use 96 the decentralized filesystem). To get started, create a new directory 97 and mark it as the 'tahoe:' alias by running 98 "``tahoe create-alias tahoe``". Once you've done that, you can do 99 "``tahoe ls tahoe:``" and "``tahoe cp LOCALFILE tahoe:foo.txt``" to 100 work with your filesystem. The Tahoe-LAFS CLI uses similar syntax to 101 the well-known scp and rsync tools. See `CLI.rst <frontends/CLI.rst>`_ 102 for more details. 103 104 As with the WUI (and with all current interfaces to Tahoe-LAFS), you 105 are responsible for remembering directory capabilities yourself. If you 106 create a new directory and lose the capability to it, then you cannot 107 access that directory ever again. 108 109 The SFTP and FTP frontends 110 -------------------------- 111 112 You can access your Tahoe-LAFS grid via any `SFTP 113 <http://en.wikipedia.org/wiki/SSH_file_transfer_protocol>`_ or `FTP 114 <http://en.wikipedia.org/wiki/File_Transfer_Protocol>`_ client. 115 See `FTP-and-SFTP.rst <frontends/FTP-and-SFTP.rst>`_ for how to set 116 this up. On most Unix platforms, you can also use SFTP to plug 117 Tahoe-LAFS into your computer's local filesystem via ``sshfs``. 118 119 The `SftpFrontend 120 <http://tahoe-lafs.org/trac/tahoe-lafs/wiki/SftpFrontend>`_ page on the 121 wiki has more information about using SFTP with Tahoe-LAFS. 122 123 The WAPI 124 -------- 125 126 Want to program your Tahoe-LAFS node to do your bidding? Easy! See 127 `webapi.rst <frontends/webapi.rst>`_. 128 129 Socialize 130 ========= 131 132 You can chat with other users of and hackers of this software on the 133 #tahoe-lafs IRC channel at ``irc.freenode.net``, or on the `tahoe-dev 134 mailing list 135 <http://tahoe-lafs.org/cgi-bin/mailman/listinfo/tahoe-dev>`_. -
new file docs/write_coordination.rst
diff --git a/docs/write_coordination.rst b/docs/write_coordination.rst new file mode 100644 index 0000000..eebb0dd
- + 1 ================================== 2 Avoiding Write Collisions in Tahoe 3 ================================== 4 5 Tahoe does not provide locking of the mutable files and directories. 6 If there is more than one simultaneous attempt to change a mutable file 7 or directory, then an <cite>UncoordinatedWriteError</p> will result. 8 This might, in rare cases, cause the file or directory contents to be 9 accidentally deleted. The user is expected to ensure that there is at 10 most one outstanding write or update request for a given file or 11 directory at a time. One convenient way to accomplish this is to make 12 a different file or directory for each person or process which wants to 13 write.
