6 2. `CLI Command Overview`_
8 4. `Filesystem Manipulation`_
10 1. `Starting Directories`_
11 2. `Command Syntax Summary`_
12 3. `Command Examples`_
14 5. `Storage Grid Maintenance`_
21 Tahoe provides a single executable named "``tahoe``", which can be used to
22 create and manage client/server nodes, manipulate the filesystem, and perform
23 several debugging/maintenance tasks.
25 This executable lives in the source tree at "``bin/tahoe``". Once you've done a
26 build (by running "make"), ``bin/tahoe`` can be run in-place: if it discovers
27 that it is being run from within a Tahoe source tree, it will modify sys.path
28 as necessary to use all the source code and dependent libraries contained in
31 If you've installed Tahoe (using "``make install``", or by installing a binary
32 package), then the tahoe executable will be available somewhere else, perhaps
33 in ``/usr/bin/tahoe``. In this case, it will use your platform's normal
34 PYTHONPATH search paths to find the tahoe code and other libraries.
40 The "``tahoe``" tool provides access to three categories of commands.
42 * node management: create a client/server node, start/stop/restart it
43 * filesystem manipulation: list files, upload, download, delete, rename
44 * debugging: unpack cap-strings, examine share files
46 To get a list of all commands, just run "``tahoe``" with no additional
47 arguments. "``tahoe --help``" might also provide something useful.
49 Running "``tahoe --version``" will display a list of version strings, starting
50 with the "allmydata" module (which contains the majority of the Tahoe
51 functionality) and including versions for a number of dependent libraries,
52 like Twisted, Foolscap, pycryptopp, and zfec.
58 "``tahoe create-node [NODEDIR]``" is the basic make-a-new-node command. It
59 creates a new directory and populates it with files that will allow the
60 "``tahoe start``" command to use it later on. This command creates nodes that
61 have client functionality (upload/download files), web API services
62 (controlled by the 'webport' file), and storage services (unless
63 "--no-storage" is specified).
65 NODEDIR defaults to ~/.tahoe/ , and newly-created nodes default to
66 publishing a web server on port 3456 (limited to the loopback interface, at
67 127.0.0.1, to restrict access to other programs on the same host). All of the
68 other "``tahoe``" subcommands use corresponding defaults.
70 "``tahoe create-client [NODEDIR]``" creates a node with no storage service.
71 That is, it behaves like "``tahoe create-node --no-storage [NODEDIR]``".
72 (This is a change from versions prior to 1.6.0.)
74 "``tahoe create-introducer [NODEDIR]``" is used to create the Introducer node.
75 This node provides introduction services and nothing else. When started, this
76 node will produce an introducer.furl, which should be published to all
79 "``tahoe create-key-generator [NODEDIR]``" is used to create a special
80 "key-generation" service, which allows a client to offload their RSA key
81 generation to a separate process. Since RSA key generation takes several
82 seconds, and must be done each time a directory is created, moving it to a
83 separate process allows the first process (perhaps a busy wapi server) to
84 continue servicing other requests. The key generator exports a FURL that can
85 be copied into a node to enable this functionality.
87 "``tahoe run [NODEDIR]``" will start a previously-created node in the foreground.
89 "``tahoe start [NODEDIR]``" will launch a previously-created node. It will launch
90 the node into the background, using the standard Twisted "twistd"
91 daemon-launching tool. On some platforms (including Windows) this command is
92 unable to run a daemon in the background; in that case it behaves in the
93 same way as "``tahoe run``".
95 "``tahoe stop [NODEDIR]``" will shut down a running node.
97 "``tahoe restart [NODEDIR]``" will stop and then restart a running node. This is
98 most often used by developers who have just modified the code and want to
99 start using their changes.
102 Filesystem Manipulation
103 =======================
105 These commands let you exmaine a Tahoe filesystem, providing basic
106 list/upload/download/delete/rename/mkdir functionality. They can be used as
107 primitives by other scripts. Most of these commands are fairly thin wrappers
110 By default, all filesystem-manipulation commands look in ~/.tahoe/ to figure
111 out which Tahoe node they should use. When the CLI command uses wapi calls,
112 it will use ~/.tahoe/node.url for this purpose: a running Tahoe node that
113 provides a wapi port will write its URL into this file. If you want to use
114 a node on some other host, just create ~/.tahoe/ and copy that node's wapi
115 URL into this file, and the CLI commands will contact that node instead of a
118 These commands also use a table of "aliases" to figure out which directory
119 they ought to use a starting point. This is explained in more detail below.
121 As of Tahoe v1.7 (v1.7.1 on Windows), passing non-ASCII characters to the
122 CLI should work. On Unix, the command-line arguments are assumed to use the
123 character encoding specified by the current locale.
128 As described in `docs/architecture.rst <../architecture.rst>`_, the
129 Tahoe-LAFS distributed filesystem consists of a collection of directories
130 and files, each of which has a "read-cap" or a "write-cap" (also known as
131 a URI). Each directory is simply a table that maps a name to a child file
132 or directory, and this table is turned into a string and stored in a
133 mutable file. The whole set of directory and file "nodes" are connected
134 together into a directed graph.
136 To use this collection of files and directories, you need to choose a
137 starting point: some specific directory that we will refer to as a
138 "starting directory". For a given starting directory, the "``ls
139 [STARTING_DIR]:``" command would list the contents of this directory,
140 the "``ls [STARTING_DIR]:dir1``" command would look inside this directory
141 for a child named "dir1" and list its contents, "``ls
142 [STARTING_DIR]:dir1/subdir2``" would look two levels deep, etc.
144 Note that there is no real global "root" directory, but instead each
145 starting directory provides a different, possibly overlapping
146 perspective on the graph of files and directories.
148 Each tahoe node remembers a list of starting points, named "aliases",
149 in a file named ~/.tahoe/private/aliases . These aliases are short UTF-8
150 encoded strings that stand in for a directory read- or write- cap. If
151 you use the command line "``ls``" without any "[STARTING_DIR]:" argument,
152 then it will use the default alias, which is "tahoe", therefore "``tahoe
153 ls``" has the same effect as "``tahoe ls tahoe:``". The same goes for the
154 other commands which can reasonably use a default alias: get, put,
157 For backwards compatibility with Tahoe-1.0, if the "tahoe": alias is not
158 found in ~/.tahoe/private/aliases, the CLI will use the contents of
159 ~/.tahoe/private/root_dir.cap instead. Tahoe-1.0 had only a single starting
160 point, and stored it in this root_dir.cap file, so Tahoe-1.1 will use it if
161 necessary. However, once you've set a "tahoe:" alias with "``tahoe set-alias``",
162 that will override anything in the old root_dir.cap file.
164 The Tahoe CLI commands use the same filename syntax as scp and rsync
165 -- an optional "alias:" prefix, followed by the pathname or filename.
166 Some commands (like "tahoe cp") use the lack of an alias to mean that
167 you want to refer to a local file, instead of something from the tahoe
168 virtual filesystem. [TODO] Another way to indicate this is to start
169 the pathname with a dot, slash, or tilde.
171 When you're dealing a single starting directory, the "tahoe:" alias is
172 all you need. But when you want to refer to something that isn't yet
173 attached to the graph rooted at that starting directory, you need to
174 refer to it by its capability. The way to do that is either to use its
175 capability directory as an argument on the command line, or to add an
176 alias to it, with the "tahoe add-alias" command. Once you've added an
177 alias, you can use that alias as an argument to commands.
179 The best way to get started with Tahoe is to create a node, start it, then
180 use the following command to create a new directory and set it as your
183 tahoe create-alias tahoe
185 After that you can use "``tahoe ls tahoe:``" and
186 "``tahoe cp local.txt tahoe:``", and both will refer to the directory that
189 SECURITY NOTE: For users of shared systems
190 ``````````````````````````````````````````
192 Another way to achieve the same effect as the above "tahoe create-alias"
195 tahoe add-alias tahoe `tahoe mkdir`
197 However, command-line arguments are visible to other users (through the
198 'ps' command, or the Windows Process Explorer tool), so if you are using a
199 tahoe node on a shared host, your login neighbors will be able to see (and
200 capture) any directory caps that you set up with the "``tahoe add-alias``"
203 The "``tahoe create-alias``" command avoids this problem by creating a new
204 directory and putting the cap into your aliases file for you. Alternatively,
205 you can edit the NODEDIR/private/aliases file directly, by adding a line like
208 fun: URI:DIR2:ovjy4yhylqlfoqg2vcze36dhde:4d4f47qko2xm5g7osgo2yyidi5m4muyo2vjjy53q4vjju2u55mfa
210 By entering the dircap through the editor, the command-line arguments are
211 bypassed, and other users will not be able to see them. Once you've added the
212 alias, no other secrets are passed through the command line, so this
213 vulnerability becomes less significant: they can still see your filenames and
214 other arguments you type there, but not the caps that Tahoe uses to permit
215 access to your files and directories.
218 Command Syntax Summary
219 ----------------------
221 tahoe add-alias alias cap
223 tahoe create-alias alias
229 tahoe mkdir [alias:]path
231 tahoe ls [alias:][path]
233 tahoe webopen [alias:][path]
235 tahoe put [--mutable] [localfrom:-]
237 tahoe put [--mutable] [localfrom:-] [alias:]to
239 tahoe put [--mutable] [localfrom:-] [alias:]subdir/to
241 tahoe put [--mutable] [localfrom:-] dircap:to
243 tahoe put [--mutable] [localfrom:-] dircap:./subdir/to
245 tahoe put [localfrom:-] mutable-file-writecap
247 tahoe get [alias:]from [localto:-]
249 tahoe cp [-r] [alias:]frompath [alias:]topath
251 tahoe rm [alias:]what
253 tahoe mv [alias:]from [alias:]to
255 tahoe ln [alias:]from [alias:]to
257 tahoe backup localfrom [alias:]to
264 This creates a new empty unlinked directory, and prints its write-cap to
265 stdout. The new directory is not attached to anything else.
267 ``tahoe add-alias fun DIRCAP``
269 An example would be::
271 tahoe add-alias fun URI:DIR2:ovjy4yhylqlfoqg2vcze36dhde:4d4f47qko2xm5g7osgo2yyidi5m4muyo2vjjy53q4vjju2u55mfa
273 This creates an alias "fun:" and configures it to use the given directory
274 cap. Once this is done, "tahoe ls fun:" will list the contents of this
275 directory. Use "tahoe add-alias tahoe DIRCAP" to set the contents of the
276 default "tahoe:" alias.
278 ``tahoe create-alias fun``
280 This combines "``tahoe mkdir``" and "``tahoe add-alias``" into a single step.
282 ``tahoe list-aliases``
284 This displays a table of all configured aliases.
286 ``tahoe mkdir subdir``
288 ``tahoe mkdir /subdir``
290 This both create a new empty directory and attaches it to your root with the
301 All four list the root directory of your personal virtual filesystem.
305 This lists a subdirectory of your filesystem.
309 ``tahoe webopen tahoe:``
311 ``tahoe webopen tahoe:subdir/``
313 ``tahoe webopen subdir/``
315 This uses the python 'webbrowser' module to cause a local web browser to
316 open to the web page for the given directory. This page offers interfaces to
317 add, dowlonad, rename, and delete files in the directory. If not given an
318 alias or path, opens "tahoe:", the root dir of the default alias.
320 ``tahoe put file.txt``
322 ``tahoe put ./file.txt``
324 ``tahoe put /tmp/file.txt``
326 ``tahoe put ~/file.txt``
328 These upload the local file into the grid, and prints the new read-cap to
329 stdout. The uploaded file is not attached to any directory. All one-argument
330 forms of "``tahoe put``" perform an unlinked upload.
336 These also perform an unlinked upload, but the data to be uploaded is taken
339 ``tahoe put file.txt uploaded.txt``
341 ``tahoe put file.txt tahoe:uploaded.txt``
343 These upload the local file and add it to your root with the name
346 ``tahoe put file.txt subdir/foo.txt``
348 ``tahoe put - subdir/foo.txt``
350 ``tahoe put file.txt tahoe:subdir/foo.txt``
352 ``tahoe put file.txt DIRCAP:./foo.txt``
354 ``tahoe put file.txt DIRCAP:./subdir/foo.txt``
356 These upload the named file and attach them to a subdirectory of the given
357 root directory, under the name "foo.txt". Note that to use a directory
358 write-cap instead of an alias, you must use ":./" as a separator, rather
359 than ":", to help the CLI parser figure out where the dircap ends. When the
360 source file is named "-", the contents are taken from stdin.
362 ``tahoe put file.txt --mutable``
364 Create a new mutable file, fill it with the contents of file.txt, and print
365 the new write-cap to stdout.
367 ``tahoe put file.txt MUTABLE-FILE-WRITECAP``
369 Replace the contents of the given mutable file with the contents of file.txt
370 and prints the same write-cap to stdout.
372 ``tahoe cp file.txt tahoe:uploaded.txt``
374 ``tahoe cp file.txt tahoe:``
376 ``tahoe cp file.txt tahoe:/``
378 ``tahoe cp ./file.txt tahoe:``
380 These upload the local file and add it to your root with the name
383 ``tahoe cp tahoe:uploaded.txt downloaded.txt``
385 ``tahoe cp tahoe:uploaded.txt ./downloaded.txt``
387 ``tahoe cp tahoe:uploaded.txt /tmp/downloaded.txt``
389 ``tahoe cp tahoe:uploaded.txt ~/downloaded.txt``
391 This downloads the named file from your tahoe root, and puts the result on
392 your local filesystem.
394 ``tahoe cp tahoe:uploaded.txt fun:stuff.txt``
396 This copies a file from your tahoe root to a different virtual directory,
397 set up earlier with "tahoe add-alias fun DIRCAP".
399 ``tahoe rm uploaded.txt``
401 ``tahoe rm tahoe:uploaded.txt``
403 This deletes a file from your tahoe root.
405 ``tahoe mv uploaded.txt renamed.txt``
407 ``tahoe mv tahoe:uploaded.txt tahoe:renamed.txt``
409 These rename a file within your tahoe root directory.
411 ``tahoe mv uploaded.txt fun:``
413 ``tahoe mv tahoe:uploaded.txt fun:``
415 ``tahoe mv tahoe:uploaded.txt fun:uploaded.txt``
417 These move a file from your tahoe root directory to the virtual directory
418 set up earlier with "tahoe add-alias fun DIRCAP"
420 ``tahoe backup ~ work:backups``
422 This command performs a full versioned backup of every file and directory
423 underneath your "~" home directory, placing an immutable timestamped
424 snapshot in e.g. work:backups/Archives/2009-02-06_04:00:05Z/ (note that the
425 timestamp is in UTC, hence the "Z" suffix), and a link to the latest
426 snapshot in work:backups/Latest/ . This command uses a small SQLite database
427 known as the "backupdb", stored in ~/.tahoe/private/backupdb.sqlite, to
428 remember which local files have been backed up already, and will avoid
429 uploading files that have already been backed up. It compares timestamps and
430 filesizes when making this comparison. It also re-uses existing directories
431 which have identical contents. This lets it run faster and reduces the
432 number of directories created.
434 If you reconfigure your client node to switch to a different grid, you
435 should delete the stale backupdb.sqlite file, to force "tahoe backup" to
436 upload all files to the new grid.
438 ``tahoe backup --exclude=*~ ~ work:backups``
440 Same as above, but this time the backup process will ignore any
441 filename that will end with '~'. '--exclude' will accept any standard
442 unix shell-style wildcards, have a look at
443 http://docs.python.org/library/fnmatch.html for a more detailed
444 reference. You may give multiple '--exclude' options. Please pay
445 attention that the pattern will be matched against any level of the
446 directory tree, it's still impossible to specify absolute path exclusions.
448 ``tahoe backup --exclude-from=/path/to/filename ~ work:backups``
450 '--exclude-from' is similar to '--exclude', but reads exclusion
451 patterns from '/path/to/filename', one per line.
453 ``tahoe backup --exclude-vcs ~ work:backups``
455 This command will ignore any known file or directory that's used by
456 version control systems to store metadata. The excluded names are:
477 Storage Grid Maintenance
478 ========================
480 ``tahoe manifest tahoe:``
482 ``tahoe manifest --storage-index tahoe:``
484 ``tahoe manifest --verify-cap tahoe:``
486 ``tahoe manifest --repair-cap tahoe:``
488 ``tahoe manifest --raw tahoe:``
490 This performs a recursive walk of the given directory, visiting every file
491 and directory that can be reached from that point. It then emits one line to
492 stdout for each object it encounters.
494 The default behavior is to print the access cap string (like URI:CHK:.. or
495 URI:DIR2:..), followed by a space, followed by the full path name.
497 If --storage-index is added, each line will instead contain the object's
498 storage index. This (string) value is useful to determine which share files
499 (on the server) are associated with this directory tree. The --verify-cap
500 and --repair-cap options are similar, but emit a verify-cap and repair-cap,
501 respectively. If --raw is provided instead, the output will be a
502 JSON-encoded dictionary that includes keys for pathnames, storage index
503 strings, and cap strings. The last line of the --raw output will be a JSON
504 encoded deep-stats dictionary.
506 ``tahoe stats tahoe:``
508 This performs a recursive walk of the given directory, visiting every file
509 and directory that can be reached from that point. It gathers statistics on
510 the sizes of the objects it encounters, and prints a summary to stdout.
516 For a list of all debugging commands, use "tahoe debug".
518 "``tahoe debug find-shares STORAGEINDEX NODEDIRS..``" will look through one or
519 more storage nodes for the share files that are providing storage for the
522 "``tahoe debug catalog-shares NODEDIRS..``" will look through one or more
523 storage nodes and locate every single share they contain. It produces a report
524 on stdout with one line per share, describing what kind of share it is, the
525 storage index, the size of the file is used for, etc. It may be useful to
526 concatenate these reports from all storage hosts and use it to look for
529 "``tahoe debug dump-share SHAREFILE``" will take the name of a single share file
530 (as found by "tahoe find-shares") and print a summary of its contents to
531 stdout. This includes a list of leases, summaries of the hash tree, and
532 information from the UEB (URI Extension Block). For mutable file shares, it
533 will describe which version (seqnum and root-hash) is being stored in this
536 "``tahoe debug dump-cap CAP``" will take a URI (a file read-cap, or a directory
537 read- or write- cap) and unpack it into separate pieces. The most useful
538 aspect of this command is to reveal the storage index for any given URI. This
539 can be used to locate the share files that are holding the encoded+encrypted
542 "``tahoe debug repl``" will launch an interactive python interpreter in which
543 the Tahoe packages and modules are available on sys.path (e.g. by using 'import
544 allmydata'). This is most useful from a source tree: it simply sets the
545 PYTHONPATH correctly and runs the 'python' executable.
547 "``tahoe debug corrupt-share SHAREFILE``" will flip a bit in the given
548 sharefile. This can be used to test the client-side verification/repair code.
549 Obviously, this command should not be used during normal operation.