1 = The Tahoe CLI commands =
4 2. CLI Command Overview
6 4. Virtual Drive Manipulation
7 4.1. Starting Directories
8 4.1.1. SECURITY NOTE: For users of shared systems
9 4.2. Command Syntax Summary
11 5. Virtual Drive Maintenance
16 Tahoe provides a single executable named "tahoe", which can be used to create
17 and manage client/server nodes, manipulate the filesystem, and perform
18 several debugging/maintenance tasks.
20 This executable lives in the source tree at "bin/tahoe". Once you've done a
21 build (by running "make"), bin/tahoe can be run in-place: if it discovers
22 that it is being run from within a Tahoe source tree, it will modify sys.path
23 as necessary to use all the source code and dependent libraries contained in
26 If you've installed Tahoe (using "make install", or by installing a binary
27 package), then the tahoe executable will be available somewhere else, perhaps
28 in /usr/bin/tahoe . In this case, it will use your platform's normal
29 PYTHONPATH search paths to find the tahoe code and other libraries.
32 == CLI Command Overview ==
34 The "tahoe" tool provides access to three categories of commands.
36 * node management: create a client/server node, start/stop/restart it
37 * filesystem manipulation: list files, upload, download, delete, rename
38 * debugging: unpack cap-strings, examine share files
40 To get a list of all commands, just run "tahoe" with no additional arguments.
41 "tahoe --help" might also provide something useful.
43 Running "tahoe --version" will display a list of version strings, starting
44 with the "allmydata" module (which contains the majority of the Tahoe
45 functionality) and including versions for a number of dependent libraries,
46 like Twisted, Foolscap, pycryptopp, and zfec.
51 "tahoe create-node [NODEDIR]" is the basic make-a-new-node command. It
52 creates a new directory and populates it with files that will allow the
53 "tahoe start" command to use it later on. This command creates nodes that
54 have client functionality (upload/download files), web API services
55 (controlled by the 'webport' file), and storage services (unless
56 "--no-storage" is specified).
58 NODEDIR defaults to ~/.tahoe/ , and newly-created nodes default to
59 publishing a web server on port 3456 (limited to the loopback interface, at
60 127.0.0.1, to restrict access to other programs on the same host). All of the
61 other "tahoe" subcommands use corresponding defaults.
63 "tahoe create-client [NODEDIR]" creates a node with no storage service.
64 That is, it behaves like "tahoe create-node --no-storage [NODEDIR]".
65 (This is a change from versions prior to 1.6.0.)
67 "tahoe create-introducer [NODEDIR]" is used to create the Introducer node.
68 This node provides introduction services and nothing else. When started, this
69 node will produce an introducer.furl, which should be published to all
72 "tahoe create-key-generator [NODEDIR]" is used to create a special
73 "key-generation" service, which allows a client to offload their RSA key
74 generation to a separate process. Since RSA key generation takes several
75 seconds, and must be done each time a directory is created, moving it to a
76 separate process allows the first process (perhaps a busy wapi server) to
77 continue servicing other requests. The key generator exports a FURL that can
78 be copied into a node to enable this functionality.
80 "tahoe run [NODEDIR]" will start a previously-created node in the foreground.
82 "tahoe start [NODEDIR]" will launch a previously-created node. It will launch
83 the node into the background, using the standard Twisted "twistd"
84 daemon-launching tool. On some platforms (including Windows) this command is
85 unable to run a daemon in the background; in that case it behaves in the
86 same way as "tahoe run".
88 "tahoe stop [NODEDIR]" will shut down a running node.
90 "tahoe restart [NODEDIR]" will stop and then restart a running node. This is
91 most often used by developers who have just modified the code and want to
92 start using their changes.
95 == Virtual Drive Manipulation ==
97 These commands let you exmaine a Tahoe filesystem, providing basic
98 list/upload/download/delete/rename/mkdir functionality. They can be used as
99 primitives by other scripts. Most of these commands are fairly thin wrappers
102 By default, all filesystem-manipulation commands look in ~/.tahoe/ to figure
103 out which Tahoe node they should use. When the CLI command uses wapi calls,
104 it will use ~/.tahoe/node.url for this purpose: a running Tahoe node that
105 provides a wapi port will write its URL into this file. If you want to use
106 a node on some other host, just create ~/.tahoe/ and copy that node's wapi
107 URL into this file, and the CLI commands will contact that node instead of a
110 These commands also use a table of "aliases" to figure out which directory
111 they ought to use a starting point. This is explained in more detail below.
113 In Tahoe up to v1.6.0, passing non-ASCII characters to the CLI is not guaranteed
114 to work, although it might work on your platform, especially if your platform
117 === Starting Directories ===
119 As described in architecture.txt, the Tahoe distributed filesystem consists
120 of a collection of directories and files, each of which has a "read-cap" or a
121 "write-cap" (also known as a URI). Each directory is simply a table that maps
122 a name to a child file or directory, and this table is turned into a string
123 and stored in a mutable file. The whole set of directory and file "nodes" are
124 connected together into a directed graph.
126 To use this collection of files and directories, you need to choose a
127 starting point: some specific directory that we will refer to as a
128 "starting directory". For a given starting directory, the "ls
129 [STARTING_DIR]:" command would list the contents of this directory,
130 the "ls [STARTING_DIR]:dir1" command would look inside this directory
131 for a child named "dir1" and list its contents, "ls
132 [STARTING_DIR]:dir1/subdir2" would look two levels deep, etc.
134 Note that there is no real global "root" directory, but instead each
135 starting directory provides a different, possibly overlapping
136 perspective on the graph of files and directories.
138 Each tahoe node remembers a list of starting points, named "aliases",
139 in a file named ~/.tahoe/private/aliases . These aliases are short UTF-8
140 encoded strings that stand in for a directory read- or write- cap. If
141 you use the command line "ls" without any "[STARTING_DIR]:" argument,
142 then it will use the default alias, which is "tahoe", therefore "tahoe
143 ls" has the same effect as "tahoe ls tahoe:". The same goes for the
144 other commands which can reasonably use a default alias: get, put,
147 For backwards compatibility with Tahoe-1.0, if the "tahoe": alias is not
148 found in ~/.tahoe/private/aliases, the CLI will use the contents of
149 ~/.tahoe/private/root_dir.cap instead. Tahoe-1.0 had only a single starting
150 point, and stored it in this root_dir.cap file, so Tahoe-1.1 will use it if
151 necessary. However, once you've set a "tahoe:" alias with "tahoe set-alias",
152 that will override anything in the old root_dir.cap file.
154 The Tahoe CLI commands use the same filename syntax as scp and rsync
155 -- an optional "alias:" prefix, followed by the pathname or filename.
156 Some commands (like "tahoe cp") use the lack of an alias to mean that
157 you want to refer to a local file, instead of something from the tahoe
158 virtual filesystem. [TODO] Another way to indicate this is to start
159 the pathname with a dot, slash, or tilde.
161 When you're dealing a single starting directory, the "tahoe:" alias is
162 all you need. But when you want to refer to something that isn't yet
163 attached to the graph rooted at that starting directory, you need to
164 refer to it by its capability. The way to do that is either to use its
165 capability directory as an argument on the command line, or to add an
166 alias to it, with the "tahoe add-alias" command. Once you've added an
167 alias, you can use that alias as an argument to commands.
169 The best way to get started with Tahoe is to create a node, start it, then
170 use the following command to create a new directory and set it as your
173 tahoe add-alias tahoe `tahoe mkdir`
175 After that you can use "tahoe ls tahoe:" and "tahoe cp local.txt tahoe:",
176 and both will refer to the directory that you've just created.
178 ==== SECURITY NOTE: For users of shared systems ====
180 Remember that command-line arguments are visible to other users (through the
181 'ps' command, or the Windows Process Explorer tool), so if you are using a
182 tahoe node on a shared host, your login neighbors will be able to see (and
183 capture) any directory caps that you set up with the "tahoe add-alias"
184 command. To avoid this, bypass add-alias and edit the NODEDIR/private/aliases
185 file directly, by adding a line like this:
187 fun: URI:DIR2:ovjy4yhylqlfoqg2vcze36dhde:4d4f47qko2xm5g7osgo2yyidi5m4muyo2vjjy53q4vjju2u55mfa
189 By entering the dircap through the editor, the command-line arguments are
190 bypassed, and other users will not be able to see them. Once you've added the
191 alias, no other secrets are passed through the command line, so this
192 vulnerability becomes less significant: they can still see your filenames and
193 other arguments you type there, but not the caps that Tahoe uses to permit
194 access to your files and directories.
196 The new "tahoe create-alias" command creates a new directory and puts the cap
197 into your aliases file for you, thus avoiding this problem.
200 === Command Syntax Summary ===
202 tahoe add-alias alias cap
205 tahoe mkdir [alias:]path
206 tahoe ls [alias:][path]
207 tahoe webopen [alias:][path]
208 tahoe put [--mutable] [localfrom:-]
209 tahoe put [--mutable] [localfrom:-] [alias:]to
210 tahoe put [--mutable] [localfrom:-] [alias:]subdir/to
211 tahoe put [--mutable] [localfrom:-] dircap:to
212 tahoe put [--mutable] [localfrom:-] dircap:./subdir/to
213 tahoe put [localfrom:-] mutable-file-writecap
214 tahoe get [alias:]from [localto:-]
215 tahoe cp [-r] [alias:]frompath [alias:]topath
216 tahoe rm [alias:]what
217 tahoe mv [alias:]from [alias:]to
218 tahoe ln [alias:]from [alias:]to
219 tahoe backup localfrom [alias:]to
221 === Command Examples ===
225 This creates a new empty unlinked directory, and prints its write-cap to
226 stdout. The new directory is not attached to anything else.
228 tahoe add-alias fun DIRCAP
232 tahoe add-alias fun URI:DIR2:ovjy4yhylqlfoqg2vcze36dhde:4d4f47qko2xm5g7osgo2yyidi5m4muyo2vjjy53q4vjju2u55mfa
234 This creates an alias "fun:" and configures it to use the given directory
235 cap. Once this is done, "tahoe ls fun:" will list the contents of this
236 directory. Use "tahoe add-alias tahoe DIRCAP" to set the contents of the
237 default "tahoe:" alias.
239 tahoe create-alias fun
241 This combines 'tahoe mkdir' and 'tahoe add-alias' into a single step.
245 This displays a table of all configured aliases.
250 This both create a new empty directory and attaches it to your root with the
258 All four list the root directory of your personal virtual filesystem.
262 This lists a subdirectory of your filesystem.
266 tahoe webopen tahoe:subdir/
267 tahoe webopen subdir/
269 This uses the python 'webbrowser' module to cause a local web browser to
270 open to the web page for the given directory. This page offers interfaces to
271 add, dowlonad, rename, and delete files in the directory. If not given an
272 alias or path, opens "tahoe:", the root dir of the default alias.
276 tahoe put /tmp/file.txt
279 These upload the local file into the grid, and prints the new read-cap to
280 stdout. The uploaded file is not attached to any directory. All one-argument
281 forms of "tahoe put" perform an unlinked upload.
286 These also perform an unlinked upload, but the data to be uploaded is taken
289 tahoe put file.txt uploaded.txt
290 tahoe put file.txt tahoe:uploaded.txt
292 These upload the local file and add it to your root with the name
295 tahoe put file.txt subdir/foo.txt
296 tahoe put - subdir/foo.txt
297 tahoe put file.txt tahoe:subdir/foo.txt
298 tahoe put file.txt DIRCAP:./foo.txt
299 tahoe put file.txt DIRCAP:./subdir/foo.txt
301 These upload the named file and attach them to a subdirectory of the given
302 root directory, under the name "foo.txt". Note that to use a directory
303 write-cap instead of an alias, you must use ":./" as a separator, rather
304 than ":", to help the CLI parser figure out where the dircap ends. When the
305 source file is named "-", the contents are taken from stdin.
307 tahoe put file.txt --mutable
309 Create a new mutable file, fill it with the contents of file.txt, and print
310 the new write-cap to stdout.
312 tahoe put file.txt MUTABLE-FILE-WRITECAP
314 Replace the contents of the given mutable file with the contents of file.txt
315 and prints the same write-cap to stdout.
317 tahoe cp file.txt tahoe:uploaded.txt
318 tahoe cp file.txt tahoe:
319 tahoe cp file.txt tahoe:/
320 tahoe cp ./file.txt tahoe:
322 These upload the local file and add it to your root with the name
325 tahoe cp tahoe:uploaded.txt downloaded.txt
326 tahoe cp tahoe:uploaded.txt ./downloaded.txt
327 tahoe cp tahoe:uploaded.txt /tmp/downloaded.txt
328 tahoe cp tahoe:uploaded.txt ~/downloaded.txt
330 This downloads the named file from your tahoe root, and puts the result on
331 your local filesystem.
333 tahoe cp tahoe:uploaded.txt fun:stuff.txt
335 This copies a file from your tahoe root to a different virtual directory,
336 set up earlier with "tahoe add-alias fun DIRCAP".
338 tahoe rm uploaded.txt
339 tahoe rm tahoe:uploaded.txt
341 This deletes a file from your tahoe root.
343 tahoe mv uploaded.txt renamed.txt
344 tahoe mv tahoe:uploaded.txt tahoe:renamed.txt
346 These rename a file within your tahoe root directory.
348 tahoe mv uploaded.txt fun:
349 tahoe mv tahoe:uploaded.txt fun:
350 tahoe mv tahoe:uploaded.txt fun:uploaded.txt
352 These move a file from your tahoe root directory to the virtual directory
353 set up earlier with "tahoe add-alias fun DIRCAP"
355 tahoe backup ~ work:backups
357 This command performs a full versioned backup of every file and directory
358 underneath your "~" home directory, placing an immutable timestamped
359 snapshot in e.g. work:backups/Archives/2009-02-06_04:00:05Z/ (note that the
360 timestamp is in UTC, hence the "Z" suffix), and a link to the latest
361 snapshot in work:backups/Latest/ . This command uses a small SQLite database
362 known as the "backupdb", stored in ~/.tahoe/private/backupdb.sqlite, to
363 remember which local files have been backed up already, and will avoid
364 uploading files that have already been backed up. It compares timestamps and
365 filesizes when making this comparison. It also re-uses existing directories
366 which have identical contents. This lets it run faster and reduces the
367 number of directories created.
369 If you reconfigure your client node to switch to a different grid, you
370 should delete the stale backupdb.sqlite file, to force "tahoe backup" to
371 upload all files to the new grid.
373 tahoe backup --exclude=*~ ~ work:backups
375 Same as above, but this time the backup process will ignore any
376 filename that will end with '~'. '--exclude' will accept any standard
377 unix shell-style wildcards, have a look at
378 http://docs.python.org/library/fnmatch.html for a more detailed
379 reference. You may give multiple '--exclude' options. Please pay
380 attention that the pattern will be matched against any level of the
381 directory tree, it's still impossible to specify absolute path exclusions.
383 tahoe backup --exclude-from=/path/to/filename ~ work:backups
385 '--exclude-from' is similar to '--exclude', but reads exclusion
386 patterns from '/path/to/filename', one per line.
388 tahoe backup --exclude-vcs ~ work:backups
390 This command will ignore any known file or directory that's used by
391 version control systems to store metadata. The list of the exluded
413 == Virtual Drive Maintenance ==
415 tahoe manifest tahoe:
416 tahoe manifest --storage-index tahoe:
417 tahoe manifest --verify-cap tahoe:
418 tahoe manifest --repair-cap tahoe:
419 tahoe manifest --raw tahoe:
421 This performs a recursive walk of the given directory, visiting every file
422 and directory that can be reached from that point. It then emits one line to
423 stdout for each object it encounters.
425 The default behavior is to print the access cap string (like URI:CHK:.. or
426 URI:DIR2:..), followed by a space, followed by the full path name.
428 If --storage-index is added, each line will instead contain the object's
429 storage index. This (string) value is useful to determine which share files
430 (on the server) are associated with this directory tree. The --verify-cap
431 and --repair-cap options are similar, but emit a verify-cap and repair-cap,
432 respectively. If --raw is provided instead, the output will be a
433 JSON-encoded dictionary that includes keys for pathnames, storage index
434 strings, and cap strings. The last line of the --raw output will be a JSON
435 encoded deep-stats dictionary.
439 This performs a recursive walk of the given directory, visiting every file
440 and directory that can be reached from that point. It gathers statistics on
441 the sizes of the objects it encounters, and prints a summary to stdout.
446 For a list of all debugging commands, use "tahoe debug".
448 "tahoe debug find-shares STORAGEINDEX NODEDIRS.." will look through one or
449 more storage nodes for the share files that are providing storage for the
452 "tahoe debug catalog-shares NODEDIRS.." will look through one or more storage
453 nodes and locate every single share they contain. It produces a report on
454 stdout with one line per share, describing what kind of share it is, the
455 storage index, the size of the file is used for, etc. It may be useful to
456 concatenate these reports from all storage hosts and use it to look for
459 "tahoe debug dump-share SHAREFILE" will take the name of a single share file
460 (as found by "tahoe find-shares") and print a summary of its contents to
461 stdout. This includes a list of leases, summaries of the hash tree, and
462 information from the UEB (URI Extension Block). For mutable file shares, it
463 will describe which version (seqnum and root-hash) is being stored in this
466 "tahoe debug dump-cap CAP" will take a URI (a file read-cap, or a directory
467 read- or write- cap) and unpack it into separate pieces. The most useful
468 aspect of this command is to reveal the storage index for any given URI. This
469 can be used to locate the share files that are holding the encoded+encrypted
472 "tahoe debug repl" will launch an interactive python interpreter in which the
473 Tahoe packages and modules are available on sys.path (e.g. by using 'import
474 allmydata'). This is most useful from a source tree: it simply sets the
475 PYTHONPATH correctly and runs the 'python' executable.
477 "tahoe debug corrupt-share SHAREFILE" will flip a bit in the given sharefile.
478 This can be used to test the client-side verification/repair code. Obviously
479 this command should not be used during normal operation.