docs/CLI.txt

   1 = The Tahoe CLI commands =
   2
   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.
   6
   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
  11 that tree.
  12
  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.
  17
  18 == CLI Command Overview ==
  19
  20 The "tahoe" tool provides access to three categories of commands.
  21
  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
  25
  26 To get a list of all commands, just run "tahoe" with no additional arguments.
  27 "tahoe --help" might also provide something useful.
  28
  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.
  33
  34 == Node Management ==
  35
  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).
  42
  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.
  47
  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
  51 clients.
  52
  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.
  60
  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.
  64
  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.
  68
  69 "tahoe stop [NODEDIR]" will shut down a running node.
  70
  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.
  74
  75
  76 == Virtual Drive Manipulation ==
  77
  78 [NOTE: This is a work-in-progress: none of this actually works yet].
  79
  80
  81 These commands let you exmaine a Tahoe virtual drive, providing basic
  82 list/upload/download/delete/rename/mkdir functionality. They can be used as
  83 primitives by other scripts. Most of these commands are fairly thin wrappers
  84 around webapi calls.
  85
  86 By default, all vdrive-manipulation commands look in ~/.tahoe/ to figure out
  87 which Tahoe node they should use. When the CLI command uses webapi calls, it
  88 will use ~/.tahoe/node.url for this purpose: a running Tahoe node that
  89 provides a webapi port will write its URL into this file. If you want to use
  90 a node on some other host, just create ~/.tahoe/ and copy that node's webapi
  91 URL into this file, and the CLI commands will contact that node instead of a
  92 local one.
  93
  94 These commands also use ~/.tahoe/private/root_dir.cap to figure out which
  95 directory they ought to use a starting point. This is explained in more
  96 detail below.
  97
  98 === Root Directories ===
  99
 100 As described in architecture.txt, the Tahoe distributed filesystem consists
 101 of a collection of directories and files, each of which has a "read-cap" or a
 102 "write-cap" (also known as a URI). Each directory is simply a table that maps
 103 a name to a child file or directory, and this table is turned into a string
 104 and stored in a mutable file. The whole set of directory and file "nodes" are
 105 connected together into a directed graph.
 106
 107 To treat this collection of dirnodes as a regular filesystem, you just need
 108 to choose a starting point: some specific directory that you refer to as your
 109 "root directory". We then refer to everything that can be reached from this
 110 starting point as your "personal filesystem". The "ls" command would list the
 111 contents of this root directory, the "ls dir1" command would look inside the
 112 root for a child named "dir1" and list its contents, "ls dir1/subdir2" would
 113 look two levels deep, etc. Note that there is no real global "root"
 114 directory, but instead each user's personal filesystem has a root that they
 115 use as a starting point for all their operations.
 116
 117 In fact, each tahoe node remembers a list of starting points, named
 118 "aliases", in a file named ~/.tahoe/private/aliases . These are short strings
 119 that stand for a directory read- or write- cap. The default starting point
 120 uses an alias named "tahoe:", and for backwards compatibility can be stored
 121 in a file named ~/.tahoe/private/root_dir.cap .
 122
 123 The Tahoe CLI commands use the same filename syntax as scp and rsync, an
 124 optional "alias:" prefix, followed by the pathname or filename. Many commands
 125 have arguments which supply a default tahoe: alias if you don't provide one
 126 yourself, but it is always safe to supply the alias. Some commands (like
 127 "tahoe cp") use the lack of an alias to mean that you want to refer to a
 128 local file, instead of something from the tahoe virtual filesystem. Another
 129 way to indicate this is to start the pathname with a dot, slash, or tilde.
 130
 131 When you're dealing with your own personal filesystem, the "tahoe:" alias is
 132 all you need. But when you want to refer to something that isn't yet in your
 133 virtual drive, you need to refer to it by its URI. The way to do that is to
 134 add an alias to it, with the "tahoe add-alias" command. Once you've added an
 135 alias, you can use that alias as a prefix to the other commands.
 136
 137 The best way to get started with Tahoe is to create a node, start it, then
 138 use the following command to create a new directory and set it as your
 139 "tahoe:" alias:
 140
 141  tahoe add-alias tahoe `tahoe mkdir`
 142
 143 After that you can use "tahoe ls tahoe:" and "tahoe cp local.txt tahoe:",
 144 and both will refer to the directory that you've just created.
 145
 146 === Command Syntax Summary ===
 147
 148 tahoe add-alias alias cap
 149 tahoe list-aliases
 150 tahoe mkdir
 151 tahoe mkdir [alias:]path
 152 tahoe ls [alias:][path]
 153 tahoe put [localfrom:-]
 154 tahoe put [localfrom:-] [alias:]to
 155 tahoe get [alias:]from [localto:-]
 156 tahoe cp [-r] [alias:]frompath [alias:]topath
 157 tahoe rm [alias:]what
 158 tahoe mv [alias:]from [alias:]to
 159 tahoe ln [alias:]from [alias:]to
 160
 161 === Command Examples ===
 162
 163 tahoe mkdir
 164
 165  This creates a new empty unlinked directory, and prints its write-cap to
 166  stdout. The new directory is not attached to anything else.
 167
 168 tahoe add-alias work DIRCAP
 169
 170  This create an alias "work:" and configures it to use the given directory
 171  cap. Once this is done, "tahoe ls work:" will list the contents of this
 172  directory. Use "tahoe add-alias tahoe DIRCAP" to set the contents of the
 173  default "tahoe:" alias.
 174
 175 tahoe list-aliases
 176
 177  This displays a table of all configured aliases.
 178
 179 tahoe mkdir subdir
 180 tahoe mkdir /subdir
 181
 182  This both create a new empty directory and attaches it to your root with the
 183  name "subdir".
 184
 185 tahoe ls
 186 tahoe ls /
 187 tahoe ls tahoe:
 188 tahoe ls tahoe:/
 189
 190  All four list the root directory of your personal virtual filesystem.
 191
 192 tahoe ls subdir
 193
 194  This lists a subdirectory of your filesystem.
 195
 196 tahoe put file.txt
 197 tahoe put ./file.txt
 198 tahoe put /tmp/file.txt
 199 tahoe put ~/file.txt
 200
 201  These upload the local file into the grid, and prints the new read-cap to
 202  stdout. The uploaded file is not attached to any directory.
 203
 204 tahoe put file.txt uploaded.txt
 205 tahoe put file.txt tahoe:uploaded.txt
 206
 207  These upload the local file and add it to your root with the name
 208  "uploaded.txt"
 209
 210 tahoe cp file.txt tahoe:uploaded.txt
 211 tahoe cp file.txt tahoe:
 212 tahoe cp file.txt tahoe:/
 213 tahoe cp ./file.txt tahoe:
 214
 215  These upload the local file and add it to your root with the name
 216  "uploaded.txt".
 217
 218 tahoe cp tahoe:uploaded.txt downloaded.txt
 219 tahoe cp tahoe:uploaded.txt ./downloaded.txt
 220 tahoe cp tahoe:uploaded.txt /tmp/downloaded.txt
 221 tahoe cp tahoe:uploaded.txt ~/downloaded.txt
 222
 223  This downloads the named file from your tahoe root, and puts the result on
 224  your local filesystem.
 225
 226 tahoe cp tahoe:uploaded.txt work:stuff.txt
 227
 228  This copies a file from your tahoe root to a different virtual directory,
 229  set up earlier with "tahoe add-alias work DIRCAP".
 230
 231 tahoe rm uploaded.txt
 232 tahoe rm tahoe:uploaded.txt
 233
 234  This deletes a file from your tahoe root.
 235
 236 tahoe mv uploaded.txt renamed.txt
 237 tahoe mv tahoe:uploaded.txt tahoe:renamed.txt
 238
 239  These rename a file within your tahoe root directory.
 240
 241 tahoe mv uploaded.txt work:
 242 tahoe mv tahoe:uploaded.txt work:
 243 tahoe mv tahoe:uploaded.txt work:uploaded.txt
 244
 245  These move a file from your tahoe root directory to the virtual directory
 246  set up earlier with "tahoe add-alias work DIRCAP"
 247
 248
 249
 250 == Debugging ==
 251
 252 "tahoe find-shares STORAGEINDEX NODEDIRS.." will look through one or more
 253 storage nodes for the share files that are providing storage for the given
 254 storage index.
 255
 256 "tahoe catalog-shares NODEDIRS.." will look through one or more storage nodes
 257 and locate every single share they contain. It produces a report on stdout
 258 with one line per share, describing what kind of share it is, the storage
 259 index, the size of the file is used for, etc. It may be useful to concatenate
 260 these reports from all storage hosts and use it to look for anomalies.
 261
 262 "tahoe dump-share SHAREFILE" will take the name of a single share file (as
 263 found by "tahoe find-shares") and print a summary of its contents to stdout.
 264 This includes a list of leases, summaries of the hash tree, and information
 265 from the UEB (URI Extension Block). For mutable file shares, it will describe
 266 which version (seqnum and root-hash) is being stored in this share.
 267
 268 "tahoe dump-cap CAP" will take a URI (a file read-cap, or a directory read-
 269 or write- cap) and unpack it into separate pieces. The most useful aspect of
 270 this command is to reveal the storage index for any given URI. This can be
 271 used to locate the share files that are holding the encoded+encrypted data
 272 for this file.