<!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 or 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>
    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.</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> 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).</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, a node will serve as a storage
    node, meaning that it offers its disk space to other nodes.  To configure
    other behavior, see <a href="configuration.txt">configuration.txt</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.txt">configuration.txt</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
    &mdash; none of your uploads will succeed. To fix this, see <a
    href='configuration.txt'>configuration.txt</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> &mdash; which is the URL
    of the gateway running on your own local computer &mdash; 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.txt">CLI.txt</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.txt">FTP-and-SFTP.txt</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 WAPI</h3>

    <p>Want to program your Tahoe-LAFS node to do your bidding?  Easy!  See <a
    href="frontends/webapi.txt">webapi.txt</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>