From: Zooko O'Whielacronx Date: Tue, 10 May 2011 19:16:50 +0000 (-0700) Subject: replace remaining .html docs with .rst docs X-Git-Url: https://git.rkrishnan.org/components/com_hotproperty/flags/nxhtml.html?a=commitdiff_plain;h=299e8ad5795d3c22ae3b84a0b91847fd4f438cc3;p=tahoe-lafs%2Ftahoe-lafs.git replace remaining .html docs with .rst docs Remove install.html (long since deprecated). Also replace some obsolete references to install.html with references to quickstart.rst. Fix some broken internal references within docs/historical/historical_known_issues.txt. Thanks to Ravi Pinjala and Patrick McDonald. refs #1227 --- diff --git a/CREDITS b/CREDITS index d4554505..4c96f3ac 100644 --- a/CREDITS +++ b/CREDITS @@ -94,7 +94,7 @@ P: 0xD5A7EE69911DF5CF D: port to NetBSD, help debugging Crypto++ bug N: Sam Mason -D: edited docs/running.html +D: edited docs/running.rst N: David-Sarah Hopwood E: david-sarah@jacaranda.org diff --git a/Makefile b/Makefile index 11ca942f..0917f5fd 100644 --- a/Makefile +++ b/Makefile @@ -77,7 +77,7 @@ endif signal-error-deps: @echo @echo - @echo "ERROR: Not all of Tahoe's dependencies are in place. Please see docs/install.html for help on installing dependencies." + @echo "ERROR: Not all of Tahoe's dependencies are in place. Please see docs/quickstart.rst for help on installing dependencies." @echo @echo exit 1 diff --git a/NEWS b/NEWS index 03962442..3e08bb16 100644 --- a/NEWS +++ b/NEWS @@ -428,7 +428,7 @@ Several DeprecationWarnings for python2.6 were silenced. (#859) The checker --add-lease option would sometimes fail for shares stored on old (Tahoe v1.2.0) servers. (#875) -The documentation for installing on Windows (docs/install.html) has been +The documentation for installing on Windows (docs/quickstart.rst) has been improved. (#773) For other changes not mentioned here, see diff --git a/README.txt b/README.txt index 56016193..1127c059 100644 --- a/README.txt +++ b/README.txt @@ -7,7 +7,7 @@ distributes your filesystem across multiple servers, and even if some of the servers fail or are taken over by an attacker, the entire filesystem continues to work correctly and to preserve your privacy and security. -To get started please see `quickstart.html`_. +To get started please see `quickstart.rst`_. LICENCE ======= @@ -22,7 +22,7 @@ the Transitive Grace Period Public Licence, version 1.0. See `TGPPL.PDF`_ for why the TGPPL exists, graphically illustrated on three slides. -.. _quickstart.html: http://tahoe-lafs.org/source/tahoe-lafs/trunk/docs/quickstart.html +.. _quickstart.rst: http://tahoe-lafs.org/source/tahoe-lafs/trunk/docs/quickstart.rst .. _COPYING.GPL: http://tahoe-lafs.org/trac/dupfilefind/browser/COPYING.GPL .. _COPYING.TGPPL.html: http://tahoe-lafs.org/source/dupfilefind/trunk/COPYING.TGPPL.html .. _TGPPL.PDF: http://tahoe-lafs.org/~zooko/tgppl.pdf diff --git a/docs/about.html b/docs/about.html deleted file mode 100644 index ae5a38ab..00000000 --- a/docs/about.html +++ /dev/null @@ -1,45 +0,0 @@ - - - Welcome To Tahoe-LAFS - - - - - - - -

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.

- - - - - -

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.html.

- -

Licence

-

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 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.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/about.rst b/docs/about.rst new file mode 100644 index 00000000..a278e3b1 --- /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/historical/historical_known_issues.txt b/docs/historical/historical_known_issues.txt index 69809ef5..88e1fccd 100644 --- a/docs/historical/historical_known_issues.txt +++ b/docs/historical/historical_known_issues.txt @@ -112,6 +112,7 @@ please ignore ERROR "Reactor was unclean" in test_system and test_introducer. Upgrading to a newer version of Twisted or pyOpenSSL will cause those false alarms to stop happening (as will downgrading to an older version of either of those packages). + == issues in Tahoe v1.0.0, released 2008-03-25 == (Tahoe v1.0 was superceded by v1.1 which was released 2008-06-11.) @@ -127,7 +128,8 @@ write succeeded, when it in fact failed. This can cause data loss. Upgrade client to v1.1, or make sure that servers are always able to write to their local filesystem (including that there is space -available) as described in "issue 1" above. +available) as described in "server out of space when writing mutable +file" above. === server out of space when writing immutable file === @@ -144,7 +146,8 @@ data loss. Upgrading either or both of the client and the server to v1.1 will fix this issue. Also it can be avoided by ensuring that the servers are always able to write to their local filesystem (including that there -is space available) as described in "issue 1" above. +is space available) as described in "server out of space when writing +mutable file" above. === large directories or mutable files of certain sizes === diff --git a/docs/how_to_make_a_tahoe-lafs_release.rst b/docs/how_to_make_a_tahoe-lafs_release.rst index a5593be3..c8f54b25 100644 --- a/docs/how_to_make_a_tahoe-lafs_release.rst +++ b/docs/how_to_make_a_tahoe-lafs_release.rst @@ -1,6 +1,6 @@ [ ] 1 update doc files: `<../relnotes.txt>`_, `<../CREDITS>`_, ``_, `<../NEWS>`_. Add release name and date to top-most item in NEWS. -[ ] 2 change ``_ to point to just the current allmydata-tahoe-X.Y.Z.zip source code file, or else to point to a directory which contains only allmydata-tahoe-X.Y.Z.* source code files +[ ] 2 change ``_ to point to just the current allmydata-tahoe-X.Y.Z.zip source code file, or else to point to a directory which contains only allmydata-tahoe-X.Y.Z.* source code files [ ] 3 darcs pull diff --git a/docs/install.html b/docs/install.html deleted file mode 100644 index 33b60648..00000000 --- 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.html b/docs/quickstart.html deleted file mode 100644 index 781eed5f..00000000 --- a/docs/quickstart.html +++ /dev/null @@ -1,98 +0,0 @@ - - - - - Getting Tahoe-LAFS - - - - - - - -

About Tahoe-LAFS

-

The homepage of Tahoe-LAFS is - http://tahoe-lafs.org. There is a one-page overview at - About Tahoe-LAFS. - -

How To Get Tahoe-LAFS

- -

This 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.

- -

WARNING! There are a few third-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, please write - to the - tahoe-dev mailing list where fun, friendly, hackers will help you out! - You might also find clues in the Advanced Installation section below.

- -

Install Python

- -

Check if you already have an adequate version of Python installed by - running python --version. 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). -

- -

Get Tahoe-LAFS

- -

Download the latest stable release, v1.8.2:

- 
http://tahoe-lafs.org/source/tahoe-lafs/releases/allmydata-tahoe-1.8.2.zip
- -

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.html 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/quickstart.rst b/docs/quickstart.rst new file mode 100644 index 00000000..efbedb90 --- /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.html b/docs/running.html deleted file mode 100644 index 81c6280d..00000000 --- a/docs/running.html +++ /dev/null @@ -1,150 +0,0 @@ - - - - Running Tahoe-LAFS - - - - - - - -

How To Run Tahoe-LAFS

- -

This is how to run a Tahoe-LAFS client to connect to an - existing grid, or how to set up a complete Tahoe-LAFS grid. First - you have to install the Tahoe-LAFS software, as documented - in install.html.

- -

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 (also known as gateway nodes) - running the Tahoe-LAFS code. There is also an introducer - node that is responsible for getting the other nodes talking - to each other. Which grid of storage servers your client will - connect to is determined solely by the introducer—if you configure - your node to connect to a certain introducer then your node will - only use those storage servers provided by that introducer. If you - configure your node to connect to a new introducer of your own - creation (see below), then your node will not connect to any - storage servers until you've created some storage servers and told them - to register themselves with that introducer.

- -

If you're getting started we recommend you try connecting to - the the - public test grid—you will need to create only a gateway node - to do that. 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 Web-API

- -

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/running.rst b/docs/running.rst new file mode 100644 index 00000000..8424ab09 --- /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.html b/docs/write_coordination.html deleted file mode 100644 index 8844ecde..00000000 --- a/docs/write_coordination.html +++ /dev/null @@ -1,16 +0,0 @@ - - - - Avoiding Write Collisions in Tahoe - - - - - - - -

Write Collisions

-

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.

- - - diff --git a/docs/write_coordination.rst b/docs/write_coordination.rst new file mode 100644 index 00000000..eebb0dd9 --- /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. diff --git a/relnotes.txt b/relnotes.txt index f4994471..93ba04fb 100644 --- a/relnotes.txt +++ b/relnotes.txt @@ -4,7 +4,7 @@ The Tahoe-LAFS team is pleased to announce the immediate availability of version 1.8.2 of Tahoe-LAFS, an extremely reliable distributed storage system. Get it here: -http://tahoe-lafs.org/source/tahoe/trunk/docs/quickstart.html +http://tahoe-lafs.org/source/tahoe/trunk/docs/quickstart.rst Tahoe-LAFS is the first distributed storage system to offer "provider-independent security" — meaning that not even the @@ -12,7 +12,7 @@ operators of your storage servers can read or alter your data without your consent. Here is the one-page explanation of its unique security and fault-tolerance properties: -http://tahoe-lafs.org/source/tahoe/trunk/docs/about.html +http://tahoe-lafs.org/source/tahoe/trunk/docs/about.rst The previous stable release of Tahoe-LAFS was v1.8.1, which was released October 28, 2010 [1]. @@ -92,7 +92,7 @@ INSTALLATION Tahoe-LAFS works on Linux, Mac OS X, Windows, Cygwin, Solaris, *BSD, and probably most other systems. Start with -"docs/quickstart.html" [7]. +"docs/quickstart.rst" [7]. HACKING AND COMMUNITY @@ -150,7 +150,7 @@ San Francisco, California, USA [4] http://tahoe-lafs.org/trac/tahoe/browser/docs/known_issues.rst [5] http://tahoe-lafs.org/trac/tahoe/browser/COPYING.GPL [6] http://tahoe-lafs.org/source/tahoe/trunk/COPYING.TGPPL.html -[7] http://tahoe-lafs.org/source/tahoe/trunk/docs/quickstart.html +[7] http://tahoe-lafs.org/source/tahoe/trunk/docs/quickstart.rst [8] http://tahoe-lafs.org/cgi-bin/mailman/listinfo/tahoe-dev [9] http://tahoe-lafs.org/trac/tahoe/roadmap [10] http://tahoe-lafs.org/trac/tahoe/browser/CREDITS?rev=5000 diff --git a/setup.py b/setup.py index cbdc4d2b..1c51e854 100644 --- a/setup.py +++ b/setup.py @@ -7,7 +7,7 @@ # # This file is part of Tahoe-LAFS. # -# See the docs/about.html file for licensing information. +# See the docs/about.rst file for licensing information. import glob, os, stat, subprocess, sys, re diff --git a/src/allmydata/mutable/common.py b/src/allmydata/mutable/common.py index 29656be4..9d5ab641 100644 --- a/src/allmydata/mutable/common.py +++ b/src/allmydata/mutable/common.py @@ -25,7 +25,7 @@ class UncoordinatedWriteError(Exception): return ("<%s -- You, oh user, tried to change a file or directory " "at the same time as another process was trying to change it. " " To avoid data loss, don't do this. Please see " - "docs/write_coordination.html for details.>" % + "docs/write_coordination.rst for details.>" % (self.__class__.__name__,)) class UnrecoverableFileError(Exception):