1 = The Tahoe CLI commands =
3 Tahoe provides a single executable named "tahoe", which can be used to create
4 and manage client/server nodes, manipulate the virtual drive, and perform
5 several debugging/maintenance tasks.
7 This executable lives in the source tree at "bin/tahoe". Once you've done a
8 build (by running "make"), bin/tahoe can be run in-place: if it discovers
9 that it is being run from within a Tahoe source tree, it will modify sys.path
10 as necessary to use all the source code and dependent libraries contained in
13 If you've installed Tahoe (using "make install", or by installing a binary
14 package), then the tahoe executable will be available somewhere else, perhaps
15 in /usr/bin/tahoe . In this case, it will use your platform's normal
16 PYTHONPATH search paths to find the tahoe code and other libraries.
18 == CLI Command Overview ==
20 The "tahoe" tool provides access to three categories of commands.
22 * node management: create a client/server node, start/stop/restart it
23 * vdrive manipulation: list files, upload, download, delete, rename
24 * debugging: unpack cap-strings, examine share files
26 To get a list of all commands, just run "tahoe" with no additional arguments.
27 "tahoe --help" might also provide something useful.
29 Running "tahoe --version" will display a list of version strings, starting
30 with the "allmydata" module (which contains the majority of the Tahoe
31 functionality) and including versions for a number of dependent libraries,
32 like Twisted, Foolscap, pycryptopp, and zfec.
36 "tahoe create-client [NODEDIR]" is the basic make-a-new-node command. It
37 creates a new directory and populates it with files that will allow the
38 "tahoe start" command to use it later on. This command creates nodes that
39 have client functionality (upload/download files), web API services
40 (controlled by the 'webport' file), and storage services (controlled by
41 "no_storage" and the like).
43 NODEDIR defaults to ~/.tahoe/ , and newly-created clients default to
44 publishing a web server on port 8123 (limited to the loopback interface, at
45 127.0.0.1, to restrict access to other programs on the same host). All of the
46 other "tahoe" subcommands use corresponding defaults.
48 "tahoe create-introducer [NODEDIR]" is used to create the Introducer node.
49 This node provides introduction services and nothing else. When started, this
50 node will produce an introducer.furl, which should be published to all
53 "tahoe create-key-generator [NODEDIR]" is used to create a special
54 "key-generation" service, which allows a client to offload their RSA key
55 generation to a separate process. Since RSA key generation takes several
56 seconds, and must be done each time a directory is created, moving it to a
57 separate process allows the first process (perhaps a busy webapi server) to
58 continue servicing other requests. The key generator exports a FURL that can
59 be copied into a client node to enable this functionality.
61 "tahoe start [NODEDIR]" will launch a previously-created node. It will launch
62 the node into the background, using the standard Twisted "twistd"
63 daemon-launching tool.
65 "tahoe run [NODEDIR]" will start a previous-created node in the foreground.
66 Some platforms are unable to run a daemon in the background: this command
67 provides a way to use a tahoe node on such platforms.
69 "tahoe stop [NODEDIR]" will shut down a running node.
71 "tahoe restart [NODEDIR]" will stop and then restart a running node. This is
72 most often used by developers who have just modified the code and want to
73 start using their changes.
76 == Virtual Drive Manipulation ==
78 These commands let you exmaine a Tahoe virtual drive, providing basic
79 list/upload/download/delete/rename/mkdir functionality. They can be used as
80 primitives by other scripts. Most of these commands are fairly thin wrappers
83 By default, all vdrive-manipulation commands look in ~/.tahoe/ to figure out
84 which Tahoe node they should use. When the CLI command uses webapi calls, it
85 will use ~/.tahoe/node.url for this purpose: a running Tahoe node that
86 provides a webapi port will write its URL into this file. If you want to use
87 a node on some other host, just create ~/.tahoe/ and copy that node's webapi
88 URL into this file, and the CLI commands will contact that node instead of a
91 These commands also use a table of "aliases" to figure out which directory
92 they ought to use a starting point. This is explained in more detail below.
94 === Starting Directories ===
96 As described in architecture.txt, the Tahoe distributed filesystem consists
97 of a collection of directories and files, each of which has a "read-cap" or a
98 "write-cap" (also known as a URI). Each directory is simply a table that maps
99 a name to a child file or directory, and this table is turned into a string
100 and stored in a mutable file. The whole set of directory and file "nodes" are
101 connected together into a directed graph.
103 To use this collection of files and directories, you need to choose a
104 starting point: some specific directory that we will refer to as a
105 "starting directory". For a given starting directory, the "ls
106 [STARTING_DIR]:" command would list the contents of this directory,
107 the "ls [STARTING_DIR]:dir1" command would look inside this directory
108 for a child named "dir1" and list its contents, "ls
109 [STARTING_DIR]:dir1/subdir2" would look two levels deep, etc.
111 Note that there is no real global "root" directory, but instead each
112 starting directory provides a different, possibly overlapping
113 perspective on the graph of files and directories.
115 Each tahoe node remembers a list of starting points, named "aliases",
116 in a file named ~/.tahoe/private/aliases . These aliases are short
117 strings that stand in for a directory read- or write- cap. If you use
118 the command line "ls" without any "[STARTING_DIR]:" argument, then it
119 will use the default alias, which is "tahoe", therefore "tahoe ls" has
120 the same effect as "tahoe ls tahoe:". The same goes for the other
121 commands which can reasonably use a default alias: get, put, mkdir,
124 For backwards compatibility with Tahoe-1.0, if the "tahoe": alias is not
125 found in ~/.tahoe/private/aliases, the CLI will use the contents of
126 ~/.tahoe/private/root_dir.cap instead. Tahoe-1.0 had only a single starting
127 point, and stored it in this root_dir.cap file, so Tahoe-1.1 will use it if
128 necessary. However, once you've set a "tahoe:" alias with "tahoe set-alias",
129 that will override anything in the old root_dir.cap file.
131 The Tahoe CLI commands use the same filename syntax as scp and rsync
132 -- an optional "alias:" prefix, followed by the pathname or filename.
133 Some commands (like "tahoe cp") use the lack of an alias to mean that
134 you want to refer to a local file, instead of something from the tahoe
135 virtual filesystem. [TODO] Another way to indicate this is to start
136 the pathname with a dot, slash, or tilde.
138 When you're dealing a single starting directory, the "tahoe:" alias is
139 all you need. But when you want to refer to something that isn't yet
140 attached to the graph rooted at that starting directory, you need to
141 refer to it by its capability. The way to do that is either to use its
142 capability directory as an argument on the command line, or to add an
143 alias to it, with the "tahoe add-alias" command. Once you've added an
144 alias, you can use that alias as an argument to commands.
146 The best way to get started with Tahoe is to create a node, start it, then
147 use the following command to create a new directory and set it as your
150 tahoe add-alias tahoe `tahoe mkdir`
152 After that you can use "tahoe ls tahoe:" and "tahoe cp local.txt tahoe:",
153 and both will refer to the directory that you've just created.
155 ==== SECURITY NOTE: For users of shared systems ====
157 Remember that command-line arguments are visible to other users (through the
158 'ps' command, or the windows Process Explorer tool), so if you are using a
159 tahoe node on a shared host, your login neighbors will be able to see (and
160 capture) any directory caps that you set up with the "tahoe add-alias"
161 command. To avoid this, bypass add-alias and edit the NODEDIR/private/aliases
162 file directly, by adding a line like this:
164 fun: URI:DIR2:ovjy4yhylqlfoqg2vcze36dhde:4d4f47qko2xm5g7osgo2yyidi5m4muyo2vjjy53q4vjju2u55mfa
166 By entering the dircap through the editor, the command-line arguments are
167 bypassed, and other users will not be able to see them. Once you've added the
168 alias, no other secrets are passed through the command line, so this
169 vulnerability becomes less significant: they can still see your filenames and
170 other arguments you type there, but not the caps that Tahoe uses to permit
171 access to your files and directories.
174 === Command Syntax Summary ===
176 tahoe add-alias alias cap
179 tahoe mkdir [alias:]path
180 tahoe ls [alias:][path]
181 tahoe webopen [alias:]path
182 tahoe put [--mutable] [localfrom:-]
183 tahoe put [--mutable] [localfrom:-] [alias:]to
184 tahoe put [--mutable] [localfrom:-] [alias:]subdir/to
185 tahoe put [--mutable] [localfrom:-] dircap:to
186 tahoe put [--mutable] [localfrom:-] dircap:./subdir/to
187 tahoe put [localfrom:-] mutable-file-writecap
188 tahoe get [alias:]from [localto:-]
189 tahoe cp [-r] [alias:]frompath [alias:]topath
190 tahoe rm [alias:]what
191 tahoe mv [alias:]from [alias:]to
192 tahoe ln [alias:]from [alias:]to
194 === Command Examples ===
198 This creates a new empty unlinked directory, and prints its write-cap to
199 stdout. The new directory is not attached to anything else.
201 tahoe add-alias fun DIRCAP
205 tahoe add-alias fun URI:DIR2:ovjy4yhylqlfoqg2vcze36dhde:4d4f47qko2xm5g7osgo2yyidi5m4muyo2vjjy53q4vjju2u55mfa
207 This creates an alias "fun:" and configures it to use the given directory
208 cap. Once this is done, "tahoe ls fun:" will list the contents of this
209 directory. Use "tahoe add-alias tahoe DIRCAP" to set the contents of the
210 default "tahoe:" alias.
212 tahoe create-alias fun
214 This combines 'tahoe mkdir' and 'tahoe add-alias' into a single step.
218 This displays a table of all configured aliases.
223 This both create a new empty directory and attaches it to your root with the
231 All four list the root directory of your personal virtual filesystem.
235 This lists a subdirectory of your filesystem.
238 tahoe webopen tahoe:subdir/
240 This uses the python 'webbrowser' module to cause a local web browser to
241 open to the web page for the given directory. This page offers interfaces to
242 add, dowlonad, rename, and delete files in the directory.
246 tahoe put /tmp/file.txt
249 These upload the local file into the grid, and prints the new read-cap to
250 stdout. The uploaded file is not attached to any directory. All one-argument
251 forms of "tahoe put" perform an unlinked upload.
256 These also perform an unlinked upload, but the data to be uploaded is taken
259 tahoe put file.txt uploaded.txt
260 tahoe put file.txt tahoe:uploaded.txt
262 These upload the local file and add it to your root with the name
265 tahoe put file.txt subdir/foo.txt
266 tahoe put - subdir/foo.txt
267 tahoe put file.txt tahoe:subdir/foo.txt
268 tahoe put file.txt DIRCAP:./foo.txt
269 tahoe put file.txt DIRCAP:./subdir/foo.txt
271 These upload the named file and attach them to a subdirectory of the given
272 root directory, under the name "foo.txt". Note that to use a directory
273 write-cap instead of an alias, you must use ":./" as a separator, rather
274 than ":", to help the CLI parser figure out where the dircap ends. When the
275 source file is named "-", the contents are taken from stdin.
277 tahoe put file.txt --mutable
279 Create a new mutable file, fill it with the contents of file.txt, and print
280 the new write-cap to stdout.
282 tahoe put file.txt MUTABLE-FILE-WRITECAP
284 Replace the contents of the given mutable file with the contents of file.txt
285 and prints the same write-cap to stdout.
287 tahoe cp file.txt tahoe:uploaded.txt
288 tahoe cp file.txt tahoe:
289 tahoe cp file.txt tahoe:/
290 tahoe cp ./file.txt tahoe:
292 These upload the local file and add it to your root with the name
295 tahoe cp tahoe:uploaded.txt downloaded.txt
296 tahoe cp tahoe:uploaded.txt ./downloaded.txt
297 tahoe cp tahoe:uploaded.txt /tmp/downloaded.txt
298 tahoe cp tahoe:uploaded.txt ~/downloaded.txt
300 This downloads the named file from your tahoe root, and puts the result on
301 your local filesystem.
303 tahoe cp tahoe:uploaded.txt fun:stuff.txt
305 This copies a file from your tahoe root to a different virtual directory,
306 set up earlier with "tahoe add-alias fun DIRCAP".
308 tahoe rm uploaded.txt
309 tahoe rm tahoe:uploaded.txt
311 This deletes a file from your tahoe root.
313 tahoe mv uploaded.txt renamed.txt
314 tahoe mv tahoe:uploaded.txt tahoe:renamed.txt
316 These rename a file within your tahoe root directory.
318 tahoe mv uploaded.txt fun:
319 tahoe mv tahoe:uploaded.txt fun:
320 tahoe mv tahoe:uploaded.txt fun:uploaded.txt
322 These move a file from your tahoe root directory to the virtual directory
323 set up earlier with "tahoe add-alias fun DIRCAP"
329 For a list of all debugging commands, use "tahoe debug".
331 "tahoe debug find-shares STORAGEINDEX NODEDIRS.." will look through one or
332 more storage nodes for the share files that are providing storage for the
335 "tahoe debug catalog-shares NODEDIRS.." will look through one or more storage
336 nodes and locate every single share they contain. It produces a report on
337 stdout with one line per share, describing what kind of share it is, the
338 storage index, the size of the file is used for, etc. It may be useful to
339 concatenate these reports from all storage hosts and use it to look for
342 "tahoe debug dump-share SHAREFILE" will take the name of a single share file
343 (as found by "tahoe find-shares") and print a summary of its contents to
344 stdout. This includes a list of leases, summaries of the hash tree, and
345 information from the UEB (URI Extension Block). For mutable file shares, it
346 will describe which version (seqnum and root-hash) is being stored in this
349 "tahoe debug dump-cap CAP" will take a URI (a file read-cap, or a directory
350 read- or write- cap) and unpack it into separate pieces. The most useful
351 aspect of this command is to reveal the storage index for any given URI. This
352 can be used to locate the share files that are holding the encoded+encrypted
355 "tahoe debug repl" will launch an interactive python interpreter in which the
356 Tahoe packages and modules are available on sys.path (e.g. by using 'import
357 allmydata'). This is most useful from a source tree: it simply sets the
358 PYTHONPATH correctly and runs the 'python' executable.
360 "tahoe debug corrupt-share SHAREFILE" will flip a bit in the given sharefile.
361 This can be used to test the client-side verification/repair code. Obviously
362 this command should not be used during normal operation.