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
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
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
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
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
=======
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
+++ /dev/null
-<!DOCtype HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html lang="en">
- <head>
- <title>Welcome To Tahoe-LAFS</title>
- <link rev="made" class="mailto" href="mailto:zooko[at]zooko[dot]com">
- <meta name="description" content="welcome to Tahoe-LAFS">
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
- <meta name="keywords" content="tahoe-lafs secure decentralized filesystem cloud storage">
- </head>
-
- <body>
- <h1>Welcome to Tahoe-LAFS</h1>
- <p>Welcome to <a href="http://tahoe-lafs.org">Tahoe-LAFS</a>, the first decentralized storage system with <cite>provider-independent security</cite>.</p>
-
- <h2>what is "provider-independent security"?</h2>
- <p>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.</p>
- <p>What we mean by "security" is something different. <em>The service provider never has the ability to read or modify your data in the first place -- never.</em> 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 <em>provider-independent security</em>.</p>
- <p>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.)</p>
- <p>Here's how it works.</p>
-
- <img src="http://tahoe-lafs.org/~zooko/network-and-reliance-topology.png"></img>
-
-<!-- <p>(See also <a href="http://testgrid.allmydata.org:3567/file/URI:CHK:4rd7ous7b5xgbmpan6mmdbx3za:2jywqfnobreondkanwnekugmxv3cyuzdv34fpyazkb5htjmokdta:3:10:102761/@@named=/network-and-reliance-topology-paranoid.png">Tahoe-LAFS for Paranoids</a> and <a href="http://testgrid.allmydata.org:3567/file/URI:CHK:mpa737uu7suao7lva2axhbtgw4:5rpemho4d3cqsgvgsqmg3hbn2mzeibsbdpthmpyo5jwnj7f2fqfa:3:10:114022/@@named=/network-and-reliance-topology-corporate.png">Tahoe-LAFS for Corporates</a>.)</p> -->
-
- <p>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.</p>
- <p>Users do not rely on storage servers to provide <i>confidentiality</i> nor <i>integrity</i> 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.</p>
- <p>Users do rely on storage servers for <i>availability</i>. The ciphertext is erasure-coded and distributed across <cite>N</cite> storage servers (the default value for <cite>N</cite> is 10) so that it can be recovered from any <cite>K</cite> of these servers (the default value of <cite>K</cite> is 3). Therefore only the simultaneous failure of <cite>N-K+1</cite> (with the defaults, 8) servers can make the data unavailable.</p>
- <p>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.</p>
- <p>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 <i>relies on</i> 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.</p>
-
- <h2>Access control</h2>
- <p>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).</p>
- <p>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.</p>
- <p>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.</p>
- <p>For more technical detail, please see the <a href="http://tahoe-lafs.org/trac/tahoe-lafs/wiki/Doc">The Doc Page</a> on the Wiki.</p>
-
- <h2>Get Started</h2>
- <p>To use Tahoe-LAFS, please see <a href="quickstart.html">quickstart.html</a>.</p>
-
- <h2>Licence</h2>
- <p>You may use this package under the GNU General Public License, version 2 or, at your option, any later version. See the file <a href="../COPYING.GPL">COPYING.GPL</a> for the terms of the GNU General Public License, version 2.</p>
- <p>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 <a href="../COPYING.TGPPL.html">COPYING.TGPPL.html</a> for the terms of the Transitive Grace Period Public Licence, version 1.</p>
- <p>(You may choose to use this package under the terms of either licence, at your option.)</p>
-
- </body>
-</html>
--- /dev/null
+======================
+Welcome to Tahoe-LAFS!
+======================
+
+Welcome to `Tahoe-LAFS <http://tahoe-lafs.org>`_, 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
+<http://tahoe-lafs.org/trac/tahoe-lafs/wiki/Doc>`_ on the Wiki.
+
+Get Started
+===========
+
+To use Tahoe-LAFS, please see `quickstart.rst <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.)
+
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.)
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 ===
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 ===
[ ] 1 update doc files: `<../relnotes.txt>`_, `<../CREDITS>`_, `<known_issues.rst>`_, `<../NEWS>`_. Add release name and date to top-most item in NEWS.
-[ ] 2 change `<quickstart.html>`_ 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 `<quickstart.rst>`_ 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
+++ /dev/null
-<!DOCtype HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-<html lang="en">
- <head>
- <title>Getting Tahoe-LAFS</title>
- <link rev="made" class="mailto" href="mailto:zooko[at]zooko[dot]com">
- <meta name="description" content="how to get Tahoe-LAFS">
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
- <meta name="keywords" content="tahoe-lafs secure decentralized filesystem installation">
- <meta http-equiv="refresh" content="0;url=quickstart.html" />
- </head>
-
- <body>
- <p>This page has moved to <a href="quickstart.html">quickstart.html</a>.</p>
- </body>
-</html>
+++ /dev/null
-<!DOCtype HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-<html lang="en">
- <head>
- <style type="text/css">
- p.p1 {font-size:85%;}
- p.p1 {font-style:italic;}
- </style>
- <title>Getting Tahoe-LAFS</title>
- <link rev="made" class="mailto" href="mailto:zooko[at]zooko[dot]com">
- <meta name="description" content="how to get Tahoe-LAFS">
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
- <meta name="keywords" content="tahoe-lafs secure decentralized filesystem installation">
- </head>
-
- <body>
- <h1>About Tahoe-LAFS</h1>
- <p> The homepage of Tahoe-LAFS is <a href="http://tahoe-lafs.org">
- http://tahoe-lafs.org</a>. There is a one-page overview at <a href="about.html">
- About Tahoe-LAFS</a>.
-
- <h1>How To Get Tahoe-LAFS</h1>
-
- <p class=p1>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.</p>
-
- <p class=p1><strong>WARNING!</strong> 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 <a href="http://tahoe-lafs.org/cgi-bin/mailman/listinfo/tahoe-dev">the
- tahoe-dev mailing list</a> where fun, friendly, hackers will help you out!
- You might also find clues in the Advanced Installation section below.</p>
-
- <h2>Install Python</h2>
-
- <p>Check if you already have an adequate version of Python installed by
- running <cite>python --version</cite>. 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).</p>
-
- <p>If you don't have one of these versions of Python installed, then
- follow the instructions on
- <a href="http://www.python.org/download/releases/2.6.6/">the Python
- download page</a> 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 "<tt>Program Files</tt>" directory).
- </p>
-
- <h2>Get Tahoe-LAFS</h2>
-
- <p>Download the latest stable release, v1.8.2:</p>
- <pre><a
- href="http://tahoe-lafs.org/source/tahoe-lafs/releases/allmydata-tahoe-1.8.2.zip">http://tahoe-lafs.org/source/tahoe-lafs/releases/allmydata-tahoe-1.8.2.zip</a></pre>
-
- <h2>Set Up Tahoe-LAFS</h2>
-
- <p>Unpack the zip file and cd into the top-level directory.</p>
-
- <p>Run <cite>python setup.py build</cite> to generate the <cite>tahoe</cite>
- executable in a subdirectory of the current directory named <cite>bin</cite>.
- This will download and build anything you need from various websites.</p>
-
- <p>On Windows, the <cite>build</cite> 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.</p>
-
- <p>Optionally run <cite>python setup.py test</cite> to verify that it
- passes all of its self-tests.</p>
-
- <p>Run <cite>bin/tahoe --version</cite> (on Windows,
- <cite>bin\tahoe --version</cite>) to verify that the executable tool prints
- out the right version number.</p>
-
- <h2>Run Tahoe-LAFS</h2>
-
- <p>Now you are ready to deploy a decentralized filesystem. The
- <cite>tahoe</cite> executable in the <cite>bin</cite> directory can
- configure and launch your Tahoe-LAFS nodes.
- See <a href="running.html">running.html</a> for instructions on how to do
- that.</p>
-
-
- <h2>Advanced Installation</h2>
-
- <p>For optional features such as tighter integration with your operating
- system's package manager, you can see the
- <a href="http://tahoe-lafs.org/trac/tahoe/wiki/AdvancedInstall">AdvancedInstall</a>
- 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
- <a href="http://tahoe-lafs.org/cgi-bin/mailman/listinfo/tahoe-dev">the
- tahoe-dev mailing list</a>.</p>
- </body>
-</html>
--- /dev/null
+==================
+Getting Tahoe-LAFS
+==================
+
+Welcome to `the Tahoe-LAFS project <http://tahoe-lafs.org>`_, a secure,
+decentralized, fault-tolerant storage system. `About Tahoe-LAFS
+<about.rst>`_.
+
+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
+<http://tahoe-lafs.org/cgi-bin/mailman/listinfo/tahoe-dev>`_ 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
+<http://www.python.org/download/releases/2.6.6/>`_ 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
+<http://sourceforge.net/projects/pywin32/files/>`_ 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
+<http://tahoe-lafs.org/source/tahoe-lafs/releases/allmydata-tahoe-1.8.1.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.rst <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
+<http://tahoe-lafs.org/trac/tahoe/wiki/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 <http://tahoe-lafs.org/cgi-bin/mailman/listinfo/tahoe-dev>`_.
+
+++ /dev/null
-<!DOCtype HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-<html lang="en">
- <head>
- <title>Running Tahoe-LAFS</title>
- <link rev="made" class="mailto" href="mailto:zooko[at]zooko[dot]com">
- <meta name="description" content="how to run Tahoe-LAFS">
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
- <meta name="keywords" content="tahoe Tahoe-LAFS secure decentralized filesystem operation">
- </head>
-
- <body>
- <h1>How To Run Tahoe-LAFS</h1>
-
- <p>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 <a href="install.html">install.html</a>.</p>
-
- <p>The <code>tahoe</code> program in the <code>bin</code> 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 <code>tahoe.cfg</code>. Nodes
- read and write files within this base directory.</p>
-
- <p>A grid consists of a set of <em>storage nodes</em>
- and <em>client nodes</em> (also known as <em>gateway nodes</em>)
- running the Tahoe-LAFS code. There is also an <em>introducer
- node</em> 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.</p>
-
- <p>If you're getting started we recommend you try connecting to
- the <a href="http://tahoe-lafs.org/trac/tahoe-lafs/wiki/TestGrid">the
- public test grid</a>—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).</p>
-
- <p>If the Tahoe-LAFS <code>bin</code> directory is not on your PATH, then
- in all the command lines below, specify the full path to <code>bin/tahoe</code>.</p>
-
- <p>To construct a client node, run
- "<code>tahoe create-client</code>", which will create <code>~/.tahoe</code> to be the
- node's base directory. Acquire a copy of the <code>introducer.furl</code>
- from the introducer and put it into this directory, then use
- "<code>tahoe run</code>". 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, "<code>tahoe create-client</code>"
- creates a client-only node, that does not offer its disk space to other nodes.
- To configure other behavior, use "<code>tahoe create-node</code>" or see
- <a href="configuration.rst">configuration.rst</a>.</p>
-
- <p>To construct an introducer, create a new base directory for it (the name
- of the directory is up to you), <code>cd</code> into it, and run
- "<code>tahoe create-introducer .</code>". Now run the introducer using
- "<code>tahoe start .</code>". After it starts, it will write a file named
- <code>introducer.furl</code> in that base directory. This file contains the
- URL the other nodes must use in order to connect to this introducer.
- (Note that "<code>tahoe run .</code>" doesn't work for introducers, this is a known
- issue: <a href="http://allmydata.org/trac/tahoe-lafs/ticket/937">#937</a>.)</p>
-
- <p>The "<code>tahoe run</code>" command above
- will run the node in the foreground. On Unix, you can run it in the background
- instead by using the "<code>tahoe start</code>" command.
- To stop a node started in this way, use "<code>tahoe stop</code>".
- <code>tahoe --help</code> gives a summary of all commands.</p>
-
- <p>See <a href="configuration.rst">configuration.rst</a> 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.
-
-
- <h3>A note about small grids</h3>
-
- <p>By default, Tahoe-LAFS ships with the configuration parameter
- <code>shares.happy</code> 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 <a
- href='configuration.rst'>configuration.rst</a> to learn how to set
- <code>shares.happy</code> to a more suitable value for your
- grid.</p>
-
-
- <h2>Do Stuff With It</h2>
-
- <p>This is how to use your Tahoe-LAFS node.</p>
-
- <h3>The WUI</h3>
-
- <p>Point your web browser to <a
- href="http://127.0.0.1:3456">http://127.0.0.1:3456</a> — which is the URL
- of the gateway running on your own local computer — to use your newly
- created node.</p>
-
- <p>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.</p>
-
- <p>You can do more or less everything you want to do with a decentralized
- filesystem through the WUI.</p>
-
- <h3>The CLI</h3>
-
- <p>Prefer the command-line? Run "<code>tahoe --help</code>" (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 "<code>tahoe
- create-alias tahoe</code>". Once you've done that, you can do
- "<code>tahoe ls tahoe:</code>" and "<code>tahoe cp LOCALFILE
- tahoe:foo.txt</code>" to work with your filesystem. The Tahoe-LAFS CLI uses
- similar syntax to the well-known scp and rsync tools. See <a
- href="frontends/CLI.rst">CLI.rst</a> for more details.</p>
-
- <p>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.</p>
-
- <h3>The SFTP and FTP frontends</h3>
-
- <p>You can access your Tahoe-LAFS grid via any <a href="http://en.wikipedia.org/wiki/SSH_file_transfer_protocol">SFTP</a> or
- <a href="http://en.wikipedia.org/wiki/File_Transfer_Protocol">FTP</a> client.
- See <a href="frontends/FTP-and-SFTP.rst">FTP-and-SFTP.rst</a> 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 <code>sshfs</code>.
-
- <p>The <a href="http://tahoe-lafs.org/trac/tahoe-lafs/wiki/SftpFrontend">SftpFrontend</a> page
- on the wiki has more information about using SFTP with Tahoe-LAFS.</p>
-
- <h3>The Web-API</h3>
-
- <p>Want to program your Tahoe-LAFS node to do your bidding? Easy! See <a
- href="frontends/webapi.rst">webapi.rst</a>.</p>
-
- <h2>Socialize</h2>
-
- <p>You can chat with other users of and hackers of this software on the
- #tahoe-lafs IRC channel at <code>irc.freenode.net</code>, or on the <a
- href="http://tahoe-lafs.org/cgi-bin/mailman/listinfo/tahoe-dev">tahoe-dev mailing list</a>.</p>
-
- </body>
-
-</html>
--- /dev/null
+=====================
+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 <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
+<http://tahoe-lafs.org/trac/tahoe-lafs/wiki/TestGrid>`_ 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 <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 <http://allmydata.org/trac/tahoe-lafs/ticket/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 <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 <a
+href='configuration.rst'>configuration.rst</a> 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
+<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 <frontends/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
+<http://en.wikipedia.org/wiki/SSH_file_transfer_protocol>`_ or `FTP
+<http://en.wikipedia.org/wiki/File_Transfer_Protocol>`_ client.
+See `FTP-and-SFTP.rst <frontends/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
+<http://tahoe-lafs.org/trac/tahoe-lafs/wiki/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 <frontends/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
+<http://tahoe-lafs.org/cgi-bin/mailman/listinfo/tahoe-dev>`_.
+++ /dev/null
-<!DOCtype HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-<html lang="en">
- <head>
- <title>Avoiding Write Collisions in Tahoe</title>
- <link rev="made" class="mailto" href="mailto:zooko[at]zooko[dot]com">
- <meta name="description" content="how to avoid write collisions in Tahoe">
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
- <meta name="keywords" content="tahoe secure decentralized filesystem installation">
- </head>
-
- <body>
- <h1>Write Collisions</h1>
- <p>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 <cite>UncoordinatedWriteError</p> 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.</p>
-
- </body>
-</html>
--- /dev/null
+==================================
+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 <cite>UncoordinatedWriteError</p> 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.
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
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].
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
[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
#
# 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
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):
projects / tahoe-lafs / tahoe-lafs.git / commitdiff