| 1 | .TH TAHOE 1 "May 2025" "Tahoe-LAFS \[em] tahoe command" "User Commands" |
|---|
| 2 | .SH NAME |
|---|
| 3 | tahoe \- Secure distributed file store. |
|---|
| 4 | .SH SYNOPSIS |
|---|
| 5 | .B tahoe |
|---|
| 6 | [\fI\,global-options\/\fR] \fI\,<command> \/\fR[\fI\,command-options\/\fR] |
|---|
| 7 | .SH DESCRIPTION |
|---|
| 8 | Tahoe-LAFS is a Free and Open decentralized cloud |
|---|
| 9 | storage system. |
|---|
| 10 | It distributes your data across multiple servers. |
|---|
| 11 | Even if some of the servers fail or are taken over |
|---|
| 12 | by an attacker, the entire file store continues to |
|---|
| 13 | function correctly, preserving your privacy and |
|---|
| 14 | security. |
|---|
| 15 | .sp |
|---|
| 16 | The "tahoe" executable can be used to create and |
|---|
| 17 | manage client/server nodes, manipulate the file |
|---|
| 18 | store, and perform several debugging/maintenance |
|---|
| 19 | tasks. |
|---|
| 20 | .sp |
|---|
| 21 | Please have a look at the 'SEE ALSO' section at |
|---|
| 22 | the end of this manual page for pointers to |
|---|
| 23 | further instructions. |
|---|
| 24 | . |
|---|
| 25 | .SH GLOBAL OPTIONS |
|---|
| 26 | .TP |
|---|
| 27 | \fB\-d\fR, \fB\-\-node\-directory=\fR |
|---|
| 28 | Specify which Tahoe node directory should be |
|---|
| 29 | used. The directory should either contain a |
|---|
| 30 | full Tahoe node, or a file named node.url that |
|---|
| 31 | points to some other Tahoe node. It should also |
|---|
| 32 | contain a file named 'private/aliases' which |
|---|
| 33 | contains the mapping from alias name to root |
|---|
| 34 | dirnode URI. [default for most commands: |
|---|
| 35 | \&'$HOME/.tahoe'] |
|---|
| 36 | .TP |
|---|
| 37 | \fB\-\-eliot\-destination=\fR |
|---|
| 38 | Add an Eliot logging destination. May be given |
|---|
| 39 | more than once. |
|---|
| 40 | .TP |
|---|
| 41 | \fB\-\-help\fR |
|---|
| 42 | Display help and exit. |
|---|
| 43 | .TP |
|---|
| 44 | \fB\-\-help\-eliot\-destinations\fR |
|---|
| 45 | Emit usage information for \fB\-\-eliot\-destination\fR. |
|---|
| 46 | .TP |
|---|
| 47 | .B \f[B]-q,\ --quiet\f[] |
|---|
| 48 | Operate silently. |
|---|
| 49 | .TP |
|---|
| 50 | .B \f[B]-V,\ --version\f[] |
|---|
| 51 | Display version numbers. |
|---|
| 52 | .TP |
|---|
| 53 | \fB\-\-wormhole\-invite\-appid=\fR |
|---|
| 54 | The appid to use on the wormhole server. |
|---|
| 55 | [default: tahoe\-lafs.org/invite] |
|---|
| 56 | .TP |
|---|
| 57 | \fB\-\-wormhole\-server=\fR |
|---|
| 58 | The magic wormhole server to use. [default: |
|---|
| 59 | ws://wormhole.tahoe\-lafs.org:4000/v1] |
|---|
| 60 | .SH COMMANDS |
|---|
| 61 | .PP |
|---|
| 62 | The \f[B]tahoe\f[] runner can be used for various |
|---|
| 63 | tasks depending on the command used: |
|---|
| 64 | .PP |
|---|
| 65 | tahoe \f[I]COMMAND\f[] [\f[I]OPTION\f[]]... [\f[I]NODEDIR\f[]] |
|---|
| 66 | .SH ADMINISTRATION |
|---|
| 67 | .PP |
|---|
| 68 | Create node configurations and securely invite |
|---|
| 69 | clients to a grid. |
|---|
| 70 | .SS COMMANDS |
|---|
| 71 | .TP |
|---|
| 72 | .B \f[B]create-node\f[] |
|---|
| 73 | Create a node that acts as a client, server or |
|---|
| 74 | both. |
|---|
| 75 | .TP |
|---|
| 76 | .B \f[B]create-client\f[] |
|---|
| 77 | Create a client node (providing storage to others |
|---|
| 78 | initially disabled). |
|---|
| 79 | .TP |
|---|
| 80 | .B \f[B]create-introducer\f[] |
|---|
| 81 | Create an introducer node. |
|---|
| 82 | When the grid is large or very dynamic, |
|---|
| 83 | introducers make it easier for clients to connect. |
|---|
| 84 | See "Static Server Definitions" in the |
|---|
| 85 | documentation on how to configure clients to |
|---|
| 86 | connect to one or more storage servers without |
|---|
| 87 | using an introducer. |
|---|
| 88 | .TP |
|---|
| 89 | .B \f[B]invite\f[] |
|---|
| 90 | Invite a new node to a grid. |
|---|
| 91 | See "Magic Wormhole Invites" in the documentation. |
|---|
| 92 | .SS OPTIONS |
|---|
| 93 | .TP |
|---|
| 94 | .B \f[B]-C,\ --basedir=\f[] |
|---|
| 95 | Same as the global --node-directory option. |
|---|
| 96 | .TP |
|---|
| 97 | .B \f[B]-n,\ --nickname=\f[] |
|---|
| 98 | Specify the nickname for this node (\f[B]create-node\f[] and |
|---|
| 99 | \f[B]create-client\f[] only). |
|---|
| 100 | .TP |
|---|
| 101 | .B \f[B]-i,\ --introducer=\f[] |
|---|
| 102 | Specify the introducer FURL to use (\f[B]create-node\f[] and |
|---|
| 103 | \f[B]create-client\f[] only). |
|---|
| 104 | .TP |
|---|
| 105 | .B \f[B]--hostname=\f[] |
|---|
| 106 | Hostname to automatically set --location/--port when |
|---|
| 107 | --listen=tcp (the default). |
|---|
| 108 | .TP |
|---|
| 109 | .B \f[B]-p,\ --webport=\f[] |
|---|
| 110 | Specify which TCP port to run the HTTP interface on. |
|---|
| 111 | Use 'none' to disable. |
|---|
| 112 | Default: 'tcp:3456:interface=127.0.0.1' (\f[B]create-node\f[] and |
|---|
| 113 | \f[B]create-client\f[] only). |
|---|
| 114 | .TP |
|---|
| 115 | .B \f[B]--no-storage\f[] |
|---|
| 116 | Do not offer storage service to other nodes (\f[B]create-node\f[] |
|---|
| 117 | only). |
|---|
| 118 | .SH CONTROLLING NODES |
|---|
| 119 | .PP |
|---|
| 120 | In the past, the 'tahoe' command offered service |
|---|
| 121 | watching (with start, restart, stop commands), but |
|---|
| 122 | this was not very portable and has been |
|---|
| 123 | deprecated. |
|---|
| 124 | .SS COMMANDS |
|---|
| 125 | .TP |
|---|
| 126 | .B \f[B]run\f[] |
|---|
| 127 | Run a node without daemonizing. |
|---|
| 128 | This is the only command for running nodes. |
|---|
| 129 | .SS OPTIONS |
|---|
| 130 | .TP |
|---|
| 131 | .B \f[B]--allow-stdin-close\f[] |
|---|
| 132 | Do not exit when stdin closes ("tahoe run" |
|---|
| 133 | otherwise will exit). |
|---|
| 134 | This is required for some service runners (like |
|---|
| 135 | systemd, for example). |
|---|
| 136 | .TP |
|---|
| 137 | .B \f[B]-C,\ --basedir=\f[] |
|---|
| 138 | Same as the global --node-directory option. |
|---|
| 139 | .TP |
|---|
| 140 | .B \f[B]--help\f[] |
|---|
| 141 | Display help and exit. |
|---|
| 142 | This includes lots of 'twistd-options' for |
|---|
| 143 | debugging, logging, profiling, et cetera that are |
|---|
| 144 | left out of this manual page for brevity. |
|---|
| 145 | .SH USING THE FILE STORE |
|---|
| 146 | .PP |
|---|
| 147 | All the following commands require pointing tahoe |
|---|
| 148 | to a running client node with the '--node-directory' |
|---|
| 149 | ('-d') option (or, alternatively, using the default |
|---|
| 150 | location). |
|---|
| 151 | .sp |
|---|
| 152 | Please run 'tahoe \f[I]COMMAND\f[] --help' for |
|---|
| 153 | more details on each command. |
|---|
| 154 | .SS COMMANDS |
|---|
| 155 | .TP |
|---|
| 156 | .B \f[B]mkdir\f[] |
|---|
| 157 | Create a directory and return its capability |
|---|
| 158 | ("dircap"). |
|---|
| 159 | .TP |
|---|
| 160 | .B \f[B]add-alias\f[] |
|---|
| 161 | Add an alias for an existing cap. |
|---|
| 162 | .TP |
|---|
| 163 | .B \f[B]create-alias\f[] |
|---|
| 164 | Create an alias pointing to a new cap. |
|---|
| 165 | .TP |
|---|
| 166 | .B \f[B]list-aliases\f[] |
|---|
| 167 | List all alias caps. |
|---|
| 168 | .TP |
|---|
| 169 | .B \f[B]ls\f[] |
|---|
| 170 | List a directory. |
|---|
| 171 | .TP |
|---|
| 172 | .B \f[B]get\f[] |
|---|
| 173 | Retrieve a file from the grid. |
|---|
| 174 | .TP |
|---|
| 175 | .B \f[B]put\f[] |
|---|
| 176 | Upload a file into the grid. |
|---|
| 177 | .TP |
|---|
| 178 | .B \f[B]cp\f[] |
|---|
| 179 | Copy one or more files or directories. |
|---|
| 180 | .TP |
|---|
| 181 | .B \f[B]unlink\f[] |
|---|
| 182 | Unlink a file or directory on the grid. |
|---|
| 183 | .TP |
|---|
| 184 | .B \f[B]rm\f[] |
|---|
| 185 | Same as \f[B]unlink\f[]. |
|---|
| 186 | .TP |
|---|
| 187 | .B \f[B]mv\f[] |
|---|
| 188 | Move a file within the grid. |
|---|
| 189 | .TP |
|---|
| 190 | .B \f[B]ln\f[] |
|---|
| 191 | Make an additional link to an existing file or directory. |
|---|
| 192 | .TP |
|---|
| 193 | .B \f[B]backup\f[] |
|---|
| 194 | Make target dir look like local dir. |
|---|
| 195 | .TP |
|---|
| 196 | .B \f[B]webopen\f[] |
|---|
| 197 | Open a web browser to a grid file or directory. |
|---|
| 198 | .TP |
|---|
| 199 | .B \f[B]manifest\f[] |
|---|
| 200 | List all files/directories in a subtree. |
|---|
| 201 | .TP |
|---|
| 202 | .B \f[B]stats\f[] |
|---|
| 203 | Print statistics about all files/directories in a |
|---|
| 204 | subtree. |
|---|
| 205 | .TP |
|---|
| 206 | .B \f[B]check\f[] |
|---|
| 207 | Check a single file or directory. |
|---|
| 208 | .TP |
|---|
| 209 | .B \f[B]deep-check\f[] |
|---|
| 210 | Check all files/directories reachable from a |
|---|
| 211 | starting point. |
|---|
| 212 | .SH DEBUGGING |
|---|
| 213 | .PP |
|---|
| 214 | The following commands are useful for developers |
|---|
| 215 | and for troubleshooting. |
|---|
| 216 | .PP |
|---|
| 217 | tahoe debug \f[I]SUBCOMMAND\f[] [\f[I]OPTION\f[]]... [\f[I]PARAMETER\f[]]... |
|---|
| 218 | .sp |
|---|
| 219 | Please run e.g.\ 'tahoe debug dump-share --help' |
|---|
| 220 | for more details on each subcommand. |
|---|
| 221 | .SS SUBCOMMANDS |
|---|
| 222 | .TP |
|---|
| 223 | .B \f[B]dump-share\f[] |
|---|
| 224 | Unpack and display the contents of a share. |
|---|
| 225 | .TP |
|---|
| 226 | .B \f[B]dump-cap\f[] |
|---|
| 227 | Unpack a read-cap or write-cap. |
|---|
| 228 | .TP |
|---|
| 229 | .B \f[B]find-shares\f[] |
|---|
| 230 | Locate sharefiles in node directories. |
|---|
| 231 | .TP |
|---|
| 232 | .B \f[B]catalog-shares\f[] |
|---|
| 233 | Describe all shares in node dirs. |
|---|
| 234 | .TP |
|---|
| 235 | .B \f[B]corrupt-share\f[] |
|---|
| 236 | Corrupt a share by flipping a bit. |
|---|
| 237 | .TP |
|---|
| 238 | .B \f[B]flogtool\f[] |
|---|
| 239 | Utilities to access log files. |
|---|
| 240 | .SH AUTHORS |
|---|
| 241 | .PP |
|---|
| 242 | Tahoe-LAFS has been written by Brian Warner, Zooko |
|---|
| 243 | Wilcox-O'Hearn and dozens of others. |
|---|
| 244 | This manpage was originally written by bertagaz. |
|---|
| 245 | .SH REPORTING BUGS |
|---|
| 246 | .PP |
|---|
| 247 | Please see |
|---|
| 248 | .UR https://tahoe-lafs.org/trac/tahoe-lafs/wiki/HowToReportABug |
|---|
| 249 | .UE . |
|---|
| 250 | .PP |
|---|
| 251 | Tahoe-LAFS home page: <https://tahoe-lafs.org/> |
|---|
| 252 | .PP |
|---|
| 253 | tahoe-dev mailing list: |
|---|
| 254 | .UR https://lists.tahoe-lafs.org/mailman/listinfo/tahoe-dev |
|---|
| 255 | .UE |
|---|
| 256 | .SH COPYRIGHT |
|---|
| 257 | .PP |
|---|
| 258 | Copyright \(co 2006\(en2025 The Tahoe-LAFS Software Foundation. |
|---|
| 259 | .SH "SEE ALSO" |
|---|
| 260 | Run 'tahoe \fB\-\-help\fR' for an overview of |
|---|
| 261 | commands and 'tahoe <command> \fB\-\-help\fR' for |
|---|
| 262 | more details on each command. |
|---|
| 263 | .sp |
|---|
| 264 | See |
|---|
| 265 | .UR https://tahoe-lafs.readthedocs.io/en/tahoe-lafs-1.20.0/frontends/CLI.html |
|---|
| 266 | .UE |
|---|
| 267 | for user documentation specific to the 'tahoe' |
|---|
| 268 | command. |
|---|
| 269 | .sp |
|---|
| 270 | See |
|---|
| 271 | .UR https://tahoe-lafs.readthedocs.io/ |
|---|
| 272 | .UE |
|---|
| 273 | for "the documentation" - in-depth, longer-form |
|---|
| 274 | explanations, specifications and step-by-step |
|---|
| 275 | tutorials. |
|---|
| 276 | .sp |
|---|
