diff --git a/docs/about.rst b/docs/about.rst new file mode 100644 index 0000000..a278e3b --- /dev/null +++ b/docs/about.rst @@ -0,0 +1,122 @@ +====================== +Welcome to Tahoe-LAFS! +====================== + +Welcome to `Tahoe-LAFS `_, the first +decentralized storage system with *provider-independent security*. + +What is "provider-independent security"? +======================================== + +Every seller of cloud storage services will tell you that their service +is "secure". But what they mean by that is something fundamentally +different from what we mean. What they mean by "secure" is that after +you've given them the power to read and modify your data, they try +really hard not to let this power be abused. This turns out to be +difficult! Bugs, misconfigurations, or operator error can accidentally +expose your data to another customer or to the public, or can corrupt +your data. Criminals routinely gain illicit access to corporate +servers. Even more insidious is the fact that the employees themselves +sometimes violate customer privacy out of carelessness, avarice, or +mere curiousity. The most conscientious of these service providers +spend considerable effort and expense trying to mitigate these risks. + +What we mean by "security" is something different. *The service +provider never has the ability to read or modify your data in the first +place -- never.* If you use Tahoe-LAFS, then all of the threats +described above are non-issues to you. Not only is it easy and +inexpensive for the service provider to maintain the security of your +data, but in fact they couldn't violate its security if they tried. +This is what we call *provider-independent security*. + +This guarantee is integrated naturally into the Tahoe-LAFS storage +system and doesn't require you to perform a manual pre-encryption step +or cumbersome key management. (After all, having to do cumbersome +manual operations when storing or accessing your data would nullify one +of the primary benefits of using cloud storage in the first place -- +convenience.) + +Here's how it works: + +.. image:: http://tahoe-lafs.org/~zooko/network-and-reliance-topology.png + +A "storage grid" is made up of a number of storage servers. A storage +server has direct attached storage (typically one or more hard disks). +A "gateway" uses the storage servers and provides access to the +filesystem over HTTP(S) or (S)FTP. + +Users do not rely on storage servers to provide *confidentiality* nor +*integrity* for their data -- instead all of the data is encrypted and +integrity-checked by the gateway, so that the servers can neither read +nor modify the contents of the files. + +Users do rely on storage servers for *availability*. The ciphertext is +erasure-coded and distributed across ``N`` storage servers (the default +value for ``N`` is 10) so that it can be recovered from any ``K`` of +these servers (the default value of ``K`` is 3). Therefore only the +simultaneous failure of ``N-K+1`` (with the defaults, 8) servers can +make the data unavailable. + +In the typical deployment mode each user runs her own gateway on her +own machine. This way she relies on her own machine for the +confidentiality and integrity of the data. + +An alternate deployment mode is that the gateway runs on a remote +machine and the user connects to it over HTTPS or SFTP. This means +that the operator of the gateway can view and modify the user's data +(the user *relies on* the gateway for confidentiality and integrity), +but the advantage is that the user can access the filesystem with a +client that doesn't have the gateway software installed, such as an +Internet kiosk or cell phone. + +Access Control +============== + +There are two kinds of files: immutable and mutable. Immutable files +have the property that once they have been uploaded to the storage grid +they can't be modified. Mutable ones can be modified. A user can have +read-write access to a mutable file or read-only access to it (or no +access to it at all). + +A user who has read-write access to a mutable file or directory can +give another user read-write access to that file or directory, or they +can give read-only access to that file or directory. A user who has +read-only access to a file or directory can give another user read-only +access to it. + +When linking a file or directory into a parent directory, you can use a +read-write link or a read-only link. If you use a read-write link, +then anyone who has read-write access to the parent directory can gain +read-write access to the child, and anyone who has read-only access to +the parent directory can gain read-only access to the child. If you +use a read-only link, then anyone who has either read-write or +read-only access to the parent directory can gain read-only access to +the child. + +For more technical detail, please see the `the doc page +`_ on the Wiki. + +Get Started +=========== + +To use Tahoe-LAFS, please see `quickstart.rst `_. + +License +======= + +You may use this package under the GNU General Public License, version +2 or, at your option, any later version. See the file `COPYING.GPL +<../COPYING.GPL>`_ for the terms of the GNU General Public License, +version 2. + +You may use this package under the Transitive Grace Period Public +Licence, version 1 or, at your option, any later version. The +Transitive Grace Period Public Licence has requirements similar to the +GPL except that it allows you to wait for up to twelve months after you +redistribute a derived work before releasing the source code of your +derived work. See the file `COPYING.TGGPL <../COPYING.TGPPL.html>`_ for +the terms of the Transitive Grace Period Public Licence, version 1. + +(You may choose to use this package under the terms of either licence, +at your option.) + diff --git a/docs/install.html b/docs/install.html deleted file mode 100644 index 33b6064..0000000 --- a/docs/install.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - Getting Tahoe-LAFS - - - - - - - - -

This page has moved to quickstart.html.

- - diff --git a/docs/quickstart.rst b/docs/quickstart.rst new file mode 100644 index 0000000..efbedb9 --- /dev/null +++ b/docs/quickstart.rst @@ -0,0 +1,94 @@ +================== +Getting Tahoe-LAFS +================== + +Welcome to `the Tahoe-LAFS project `_, a secure, +decentralized, fault-tolerant storage system. `About Tahoe-LAFS +`_. + +How To Get Tahoe-LAFS +===================== + +This procedure has been verified to work on Windows, Mac, OpenSolaris, +and too many flavors of Linux and of BSD to list. It's likely to work +on other platforms. + +In Case Of Trouble +------------------ + +There are a few 3rd party libraries that Tahoe-LAFS depends on that +might not be easy to set up on your platform. If the following +instructions don't Just Work without any further effort on your part, +then please write to `the tahoe-dev mailing list +`_ where +friendly hackers will help you out. You might also find clues in the +`Advanced Installation`_ section described below. + +Install Python +-------------- + +Check if you already have an adequate version of Python installed by +running ``python -V``. Python v2.4 (v2.4.4 or greater), Python v2.5, +Python v2.6, or Python v2.7 will work. Python v3 does not work. On +Windows, we recommend the use of Python v2.6 (native, not Cygwin). If +you don't have one of these versions of Python installed, then follow +the instructions on `the Python download page +`_ to download and +install Python v2.6. Make sure that the path to the installation +directory has no spaces in it (e.g. on Windows, do not install Python +in the "Program Files" directory). + +If you are on Windows, you now must manually install the pywin32 +package from `the pywin32 site +`_ before getting +Tahoe-LAFS. Make sure to get the correct file for the version of Python +you are using -- e.g. ending in "py2.6.exe" for Python v2.6. If using +64-bit Windows, the file should have "win-amd64" in its name. + +Get Tahoe-LAFS +-------------- + +`Download the latest stable release, v1.8.1 +`_ + +Set Up Tahoe-LAFS +----------------- + +Unpack the zip file and cd into the top-level directory. + +Run ``python setup.py build`` to generate the ``tahoe`` executable in a +subdirectory of the current directory named ``bin``. This will download +and build anything you need from various websites. + +On Windows, the ``build`` step might tell you to open a new Command +Prompt (or, on XP and earlier, to log out and back in again). This is +needed the first time you set up Tahoe-LAFS on a particular +installation of Windows. + +Optionally run ``python setup.py test`` to verify that it passes all +of its self-tests. + +Run ``bin/tahoe --version`` (on Windows, ``bin\tahoe --version``) to +verify that the executable tool prints out the right version number. + +Run Tahoe-LAFS +-------------- + +Now you are ready to deploy a decentralized filesystem. The ``tahoe`` +executable in the ``bin`` directory can configure and launch your +Tahoe-LAFS nodes. See `running.rst `_ for instructions on +how to do that. + +Advanced Installation +--------------------- + +For optional features such as tighter integration with your operating +system's package manager, you can see the `AdvancedInstall +`_ wiki page. +The options on that page are not necessary to use Tahoe-LAFS and can be +complicated, so we do not recommend following that page unless you have +unusual requirements for advanced optional features. For most people, +you should first follow the instructions on this page, and if that +doesn't work then ask for help by writing to `the tahoe-dev mailing +list `_. + diff --git a/docs/running.rst b/docs/running.rst new file mode 100644 index 0000000..8424ab0 --- /dev/null +++ b/docs/running.rst @@ -0,0 +1,135 @@ +===================== +How To Run Tahoe-LAFS +===================== + +Intro +===== + +This is how to run a Tahoe-LAFS client or a complete Tahoe-LAFS grid. +First you have to install the Tahoe-LAFS software, as documented in +`quickstart.rst `_. + +The ``tahoe`` program in the ``bin`` directory is used to create, +start, and stop nodes. Each node lives in a separate base directory, in +which there is a configuration file named ``tahoe.cfg``. Nodes read and +write files within this base directory. + +A grid consists of a set of *storage nodes* and *client nodes* running +the Tahoe-LAFS code. There is also an *introducer node* that is +responsible for getting the other nodes talking to each other. + +If you're getting started we recommend you try connecting to +the `the public test grid +`_ as you only +need to create a client node. When you want to create your own grid +you'll need to create the introducer and several initial storage nodes +(see the note about small grids below). + +If the Tahoe-LAFS ``bin`` directory is not on your PATH, then in all +the command lines below, specify the full path to ``bin/tahoe``. + +To construct a client node, run "``tahoe create-client``", which will +create ``~/.tahoe`` to be the node's base directory. Acquire a copy of +the ``introducer.furl`` from the introducer and put it into this +directory, then use "``tahoe run``". After that, the node should be off +and running. The first thing it will do is connect to the introducer +and get itself connected to all other nodes on the grid. By default, +"``tahoe create-client``" creates a client-only node, that does not +offer its disk space to other nodes. To configure other behavior, use +"``tahoe create-node``" or see `configuration.rst `_. + +To construct an introducer, create a new base directory for it (the +name of the directory is up to you), ``cd`` into it, and run +"``tahoe create-introducer .``". Now run the introducer using +"``tahoe start .``". After it starts, it will write a file named +``introducer.furl`` in that base directory. This file contains the URL +the other nodes must use in order to connect to this introducer. (Note +that "``tahoe run .``" doesn't work for introducers, this is a known +issue: `#937 `_.) + +The "``tahoe run``" command above will run the node in the foreground. +On Unix, you can run it in the background instead by using the +"``tahoe start``" command. To stop a node started in this way, use +"``tahoe stop``". ``tahoe --help`` gives a summary of all commands. + +See `configuration.rst `_ for more details about how +to configure Tahoe-LAFS, including how to get other clients to connect +to your node if it is behind a firewall or NAT device. + +A note about small grids +------------------------ + +By default, Tahoe-LAFS ships with the configuration parameter +``shares.happy`` set to 7. If you are using Tahoe-LAFS on a +grid with fewer than 7 storage nodes, this won't work well for you +— none of your uploads will succeed. To fix this, see configuration.rst to learn how to set +``shares.happy`` to a more suitable value for your +grid. + +Do Stuff With It +================ + +This is how to use your Tahoe-LAFS node. + +The WUI +------- + +Point your web browser to `http://127.0.0.1:3456 +`_ -- which is the URL of the gateway running on +your own local computer -- to use your newly created node. + +Create a new directory (with the button labelled "create a directory"). +Your web browser will load the new directory. Now if you want to be +able to come back to this directory later, you have to bookmark it, or +otherwise save a copy of the URL. If you lose URL to this directory, +then you can never again come back to this directory. + +You can do more or less everything you want to do with a decentralized +filesystem through the WUI. + +The CLI +------- + +Prefer the command-line? Run "``tahoe --help``" (the same command-line +tool that is used to start and stop nodes serves to navigate and use +the decentralized filesystem). To get started, create a new directory +and mark it as the 'tahoe:' alias by running +"``tahoe create-alias tahoe``". Once you've done that, you can do +"``tahoe ls tahoe:``" and "``tahoe cp LOCALFILE tahoe:foo.txt``" to +work with your filesystem. The Tahoe-LAFS CLI uses similar syntax to +the well-known scp and rsync tools. See `CLI.rst `_ +for more details. + +As with the WUI (and with all current interfaces to Tahoe-LAFS), you +are responsible for remembering directory capabilities yourself. If you +create a new directory and lose the capability to it, then you cannot +access that directory ever again. + +The SFTP and FTP frontends +-------------------------- + +You can access your Tahoe-LAFS grid via any `SFTP +`_ or `FTP +`_ client. +See `FTP-and-SFTP.rst `_ for how to set +this up. On most Unix platforms, you can also use SFTP to plug +Tahoe-LAFS into your computer's local filesystem via ``sshfs``. + +The `SftpFrontend +`_ page on the +wiki has more information about using SFTP with Tahoe-LAFS. + +The WAPI +-------- + +Want to program your Tahoe-LAFS node to do your bidding? Easy! See +`webapi.rst `_. + +Socialize +========= + +You can chat with other users of and hackers of this software on the +#tahoe-lafs IRC channel at ``irc.freenode.net``, or on the `tahoe-dev +mailing list +`_. diff --git a/docs/write_coordination.rst b/docs/write_coordination.rst new file mode 100644 index 0000000..eebb0dd --- /dev/null +++ b/docs/write_coordination.rst @@ -0,0 +1,13 @@ +================================== +Avoiding Write Collisions in Tahoe +================================== + +Tahoe does not provide locking of the mutable files and directories. +If there is more than one simultaneous attempt to change a mutable file +or directory, then an UncoordinatedWriteError

will result. +This might, in rare cases, cause the file or directory contents to be +accidentally deleted. The user is expected to ensure that there is at +most one outstanding write or update request for a given file or +directory at a time. One convenient way to accomplish this is to make +a different file or directory for each person or process which wants to +write.