+.. -*- coding: utf-8-with-signature -*-
+
===========================
The Tahoe-LAFS CLI commands
===========================
1. `Overview`_
2. `CLI Command Overview`_
+
+ 1. `Unicode Support`_
+
3. `Node Management`_
4. `Filesystem Manipulation`_
The "``tahoe``" tool provides access to three categories of commands.
* node management: create a client/server node, start/stop/restart it
-* filesystem manipulation: list files, upload, download, delete, rename
+* filesystem manipulation: list files, upload, download, unlink, rename
* debugging: unpack cap-strings, examine share files
To get a list of all commands, just run "``tahoe``" with no additional
Running "``tahoe --version``" will display a list of version strings, starting
with the "allmydata" module (which contains the majority of the Tahoe-LAFS
functionality) and including versions for a number of dependent libraries,
-like Twisted, Foolscap, pycryptopp, and zfec.
+like Twisted, Foolscap, pycryptopp, and zfec. "``tahoe --version-and-path``"
+will also show the path from which each library was imported.
+
+On Unix systems, the shell expands filename wildcards (``'*'`` and ``'?'``)
+before the program is able to read them, which may produce unexpected results
+for many ``tahoe`` comands. We recommend, if you use wildcards, to start the
+path with "``./``", for example "``tahoe cp -r ./* somewhere:``". This
+prevents the expanded filename from being interpreted as an option or as an
+alias, allowing filenames that start with a dash or contain colons to be
+handled correctly.
+
+On Windows, a single letter followed by a colon is treated as a drive
+specification rather than an alias (and is invalid unless a local path is
+allowed in that context). Wildcards cannot be used to specify multiple
+filenames to ``tahoe`` on Windows.
+
+Unicode Support
+---------------
+
+As of Tahoe-LAFS v1.7.0 (v1.8.0 on Windows), the ``tahoe`` tool supports
+non-ASCII characters in command lines and output. On Unix, the command-line
+arguments are assumed to use the character encoding specified by the
+current locale (usually given by the ``LANG`` environment variable).
+
+If a name to be output contains control characters or characters that
+cannot be represented in the encoding used on your terminal, it will be
+quoted. The quoting scheme used is similar to `POSIX shell quoting`_: in
+a "double-quoted" string, backslashes introduce escape sequences (like
+those in Python strings), but in a 'single-quoted' string all characters
+stand for themselves. This quoting is only used for output, on all
+operating systems. Your shell interprets any quoting or escapes used on
+the command line.
+
+.. _`POSIX shell quoting`: http://pubs.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html
Node Management
creates a new directory and populates it with files that will allow the
"``tahoe start``" command to use it later on. This command creates nodes that
have client functionality (upload/download files), web API services
-(controlled by the 'webport' file), and storage services (unless
-``--no-storage`` is specified).
+(controlled by the '[node]web.port' configuration), and storage services
+(unless ``--no-storage`` is specified).
NODEDIR defaults to ``~/.tahoe/`` , and newly-created nodes default to
publishing a web server on port 3456 (limited to the loopback interface, at
"``tahoe create-introducer [NODEDIR]``" is used to create the Introducer node.
This node provides introduction services and nothing else. When started, this
-node will produce an ``introducer.furl`` file, which should be published to all
-clients.
+node will produce a ``private/introducer.furl`` file, which should be
+published to all clients.
"``tahoe create-key-generator [NODEDIR]``" is used to create a special
"key-generation" service, which allows a client to offload their RSA key
generation to a separate process. Since RSA key generation takes several
seconds, and must be done each time a directory is created, moving it to a
-separate process allows the first process (perhaps a busy webapi server) to
+separate process allows the first process (perhaps a busy web-API server) to
continue servicing other requests. The key generator exports a FURL that can
be copied into a node to enable this functionality.
"``tahoe stop [NODEDIR]``" will shut down a running node.
-"``tahoe restart [NODEDIR]``" will stop and then restart a running node. This is
-most often used by developers who have just modified the code and want to
+"``tahoe restart [NODEDIR]``" will stop and then restart a running node. This
+is most often used by developers who have just modified the code and want to
start using their changes.
=======================
These commands let you exmaine a Tahoe-LAFS filesystem, providing basic
-list/upload/download/delete/rename/mkdir functionality. They can be used as
+list/upload/download/unlink/rename/mkdir functionality. They can be used as
primitives by other scripts. Most of these commands are fairly thin wrappers
-around webapi calls, which are described in `<webapi.rst>`_.
+around web-API calls, which are described in `<webapi.rst>`__.
-By default, all filesystem-manipulation commands look in ``~/.tahoe/`` to figure
-out which Tahoe-LAFS node they should use. When the CLI command makes webapi
-calls, it will use ``~/.tahoe/node.url`` for this purpose: a running Tahoe-LAFS
-node that provides a webapi port will write its URL into this file. If you want
-to use a node on some other host, just create ``~/.tahoe/`` and copy that node's
-webapi URL into this file, and the CLI commands will contact that node instead
-of a local one.
+By default, all filesystem-manipulation commands look in ``~/.tahoe/`` to
+figure out which Tahoe-LAFS node they should use. When the CLI command makes
+web-API calls, it will use ``~/.tahoe/node.url`` for this purpose: a running
+Tahoe-LAFS node that provides a web-API port will write its URL into this
+file. If you want to use a node on some other host, just create ``~/.tahoe/``
+and copy that node's web-API URL into this file, and the CLI commands will
+contact that node instead of a local one.
These commands also use a table of "aliases" to figure out which directory
they ought to use a starting point. This is explained in more detail below.
-As of Tahoe-LAFS v1.7 (v1.7.1 on Windows), passing non-ASCII characters to the
-CLI should work. On Unix, the command-line arguments are assumed to use the
-character encoding specified by the current locale.
-
Starting Directories
--------------------
-As described in `docs/architecture.rst <../architecture.rst>`_, the
+As described in `docs/architecture.rst <../architecture.rst>`__, the
Tahoe-LAFS distributed filesystem consists of a collection of directories
and files, each of which has a "read-cap" or a "write-cap" (also known as
a URI). Each directory is simply a table that maps a name to a child file
``rsync`` -- an optional ``ALIAS:`` prefix, followed by the pathname or
filename. Some commands (like "``tahoe cp``") use the lack of an alias to
mean that you want to refer to a local file, instead of something from the
-Tahoe-LAFS filesystem. [TODO] Another way to indicate this is to start
-the pathname with a dot, slash, or tilde.
+Tahoe-LAFS filesystem. Another way to indicate this is to start the
+pathname with a dot, slash, or tilde.
When you're dealing a single starting directory, the ``tahoe:`` alias is
all you need. But when you want to refer to something that isn't yet
Command Syntax Summary
----------------------
-``tahoe add-alias ALIAS DIRCAP``
+``tahoe add-alias ALIAS[:] DIRCAP``
-``tahoe create-alias ALIAS``
+``tahoe create-alias ALIAS[:]``
``tahoe list-aliases``
``tahoe backup FROMLOCAL TOPATH``
-In these summaries, ``PATH``, ``TOPATH`` or ``FROMPATH`` can be one of::
+In these summaries, ``PATH``, ``TOPATH`` or ``FROMPATH`` can be one of:
* ``[SUBDIRS/]FILENAME`` for a path relative to the default ``tahoe:`` alias;
* ``ALIAS:[SUBDIRS/]FILENAME`` for a path relative to another alias;
-* ``DIRCAP/[SUBDIRS/]FILENAME`` or ``DIRCAP:./[SUBDIRS/]FILENAME`` for a path relative to a directory cap.
+* ``DIRCAP/[SUBDIRS/]FILENAME`` or ``DIRCAP:./[SUBDIRS/]FILENAME`` for a path
+ relative to a directory cap.
+
+See `CLI Command Overview`_ above for information on using wildcards with
+local paths, and different treatment of colons between Unix and Windows.
+
+``FROMLOCAL`` or ``TOLOCAL`` is a path in the local filesystem.
Command Examples
----------------
-``tahoe add-alias ALIAS DIRCAP``
+``tahoe add-alias ALIAS[:] DIRCAP``
An example would be::
directory. Use "``tahoe add-alias tahoe DIRCAP``" to set the contents of the
default ``tahoe:`` alias.
+ Since Tahoe-LAFS v1.8.2, the alias name can be given with or without the
+ trailing colon.
+
+ On Windows, the alias should not be a single character, because it would be
+ confused with the drive letter of a local path.
+
``tahoe create-alias fun``
This combines "``tahoe mkdir``" and "``tahoe add-alias``" into a single step.
This uses the python 'webbrowser' module to cause a local web browser to
open to the web page for the given directory. This page offers interfaces to
- add, download, rename, and delete files in the directory. If no alias or
- path is given, this command opens the root directory of the default
- ``tahoe:`` alias.
+ add, download, rename, and unlink files and subdirectories in that directory.
+ If no alias or path is given, this command opens the root directory of the
+ default ``tahoe:`` alias.
``tahoe put file.txt``
``tahoe put file.txt --mutable``
- Create a new mutable file, fill it with the contents of ``file.txt``, and
- print the new write-cap to stdout.
+ Create a new (SDMF) mutable file, fill it with the contents of ``file.txt``,
+ and print the new write-cap to stdout.
``tahoe put file.txt MUTABLE-FILE-WRITECAP``
- Replace the contents of the given mutable file with the contents of ``file.txt``
- and prints the same write-cap to stdout.
+ Replace the contents of the given mutable file with the contents of
+ ``file.txt`` and print the same write-cap to stdout.
``tahoe cp file.txt tahoe:uploaded.txt``
This copies a file from your ``tahoe:`` root to a different directory, set up
earlier with "``tahoe add-alias fun DIRCAP``" or "``tahoe create-alias fun``".
-``tahoe rm uploaded.txt``
+ ``tahoe cp -r ~/my_dir/ tahoe:``
+
+ This copies the folder ``~/my_dir/`` and all its children to the grid, creating
+ the new folder ``tahoe:my_dir``. Note that the trailing slash is not required:
+ all source arguments which are directories will be copied into new
+ subdirectories of the target.
+
+ The behavior of ``tahoe cp``, like the regular UNIX ``/bin/cp``, is subtly
+ different depending upon the exact form of the arguments. In particular:
+
+* Trailing slashes indicate directories, but are not required.
+* If the target object does not already exist:
+ * and if the source is a single file, it will be copied into the target;
+ * otherwise, the target will be created as a directory.
+* If there are multiple sources, the target must be a directory.
+* If the target is a pre-existing file, the source must be a single file.
+* If the target is a directory, each source must be a named file, a named
+ directory, or an unnamed directory. It is not possible to copy an unnamed
+ file (e.g. a raw filecap) into a directory, as there is no way to know what
+ the new file should be named.
-``tahoe rm tahoe:uploaded.txt``
- This deletes a file from your ``tahoe:`` root.
+``tahoe unlink uploaded.txt``
+
+``tahoe unlink tahoe:uploaded.txt``
+
+ This unlinks a file from your ``tahoe:`` root (that is, causes there to no
+ longer be an entry ``uploaded.txt`` in the root directory that points to it).
+ Note that this does not delete the file from the grid.
+ For backward compatibility, ``tahoe rm`` is accepted as a synonym for
+ ``tahoe unlink``.
``tahoe mv uploaded.txt renamed.txt``
``tahoe backup ~ work:backups``
- This command performs a full versioned backup of every file and directory
+ This command performs a versioned backup of every file and directory
underneath your "``~``" home directory, placing an immutable timestamped
snapshot in e.g. ``work:backups/Archives/2009-02-06_04:00:05Z/`` (note that
the timestamp is in UTC, hence the "Z" suffix), and a link to the latest
snapshot in work:backups/Latest/ . This command uses a small SQLite database
known as the "backupdb", stored in ``~/.tahoe/private/backupdb.sqlite``, to
remember which local files have been backed up already, and will avoid
- uploading files that have already been backed up. It compares timestamps and
- filesizes when making this comparison. It also re-uses existing directories
- which have identical contents. This lets it run faster and reduces the
- number of directories created.
+ uploading files that have already been backed up (except occasionally that
+ will randomly upload them again if it has been awhile since had last been
+ uploaded, just to make sure that the copy of it on the server is still good).
+ It compares timestamps and filesizes when making this comparison. It also
+ re-uses existing directories which have identical contents. This lets it
+ run faster and reduces the number of directories created.
If you reconfigure your client node to switch to a different grid, you
should delete the stale backupdb.sqlite file, to force "``tahoe backup``"
to upload all files to the new grid.
+ The fact that "tahoe backup" checks timestamps on your local files and
+ skips ones that don't appear to have been changed is one of the major
+ differences between "tahoe backup" and "tahoe cp -r". The other major
+ difference is that "tahoe backup" keeps links to all of the versions that
+ have been uploaded to the grid, so you can navigate among old versions
+ stored in the grid. In contrast, "tahoe cp -r" unlinks the previous
+ version from the grid directory and links the new version into place,
+ so unless you have a link to the older version stored somewhere else,
+ you'll never be able to get back to it.
+
``tahoe backup --exclude=*~ ~ work:backups``
Same as above, but this time the backup process will ignore any
filename that will end with '~'. ``--exclude`` will accept any standard
Unix shell-style wildcards, as implemented by the
- `Python fnmatch module <http://docs.python.org/library/fnmatch.html>`_.
+ `Python fnmatch module <http://docs.python.org/library/fnmatch.html>`__.
You may give multiple ``--exclude`` options. Please pay attention that
the pattern will be matched against any level of the directory tree;
it's still impossible to specify absolute path exclusions.
Debugging
=========
-For a list of all debugging commands, use "``tahoe debug``".
+For a list of all debugging commands, use "``tahoe debug``". For more detailed
+help on any of these commands, use "``tahoe debug COMMAND --help``".
"``tahoe debug find-shares STORAGEINDEX NODEDIRS..``" will look through one or
more storage nodes for the share files that are providing storage for the
"``tahoe debug corrupt-share SHAREFILE``" will flip a bit in the given
sharefile. This can be used to test the client-side verification/repair code.
Obviously, this command should not be used during normal operation.
+
+"``tahoe debug trial [OPTIONS] [TESTSUITE]``" will run the tests specified by
+TESTSUITE (defaulting to the whole Tahoe test suite), using Twisted Trial.
projects / tahoe-lafs / tahoe-lafs.git / blobdiff