From: Brian Warner Date: Sat, 11 Aug 2007 01:20:22 +0000 (-0700) Subject: webapi.txt: separate out debug/test commands, indicate that localfile=/localdir=... X-Git-Url: https://git.rkrishnan.org/%5B/%5D%20/uri/reliability?a=commitdiff_plain;h=b4a0effe30c23879d38a1a4641cb8cc36c111ae6;p=tahoe-lafs%2Ftahoe-lafs.git webapi.txt: separate out debug/test commands, indicate that localfile=/localdir= requires special activation --- diff --git a/docs/webapi.txt b/docs/webapi.txt index 999dd609..6135ec99 100644 --- a/docs/webapi.txt +++ b/docs/webapi.txt @@ -51,7 +51,7 @@ Now, what can we do with these URLs? By varying the HTTP method control how what we want to do with the data and how it should be presented. -=== files and directories by name === +=== Manipulating files and directories by name === In the following examples "$URL" is a shorthand for a URL like the ones described above, with "vdrive/" as the top level, followed by a @@ -124,14 +124,6 @@ nothing exists. (Currently all files are immutable so everyone has read-only access to all files.) - GET $URL?t=download&localfile=$LOCALPATH - - This instructs the node to download the given file or directory and write - it into the local filesystem at $LOCALPATH. This request will only be - accepted from an HTTP client connection originating at 127.0.0.1 . This - request is most useful when the client node and the HTTP client are - operated by the same user. $LOCALPATH should be an absolute pathname. - PUT $URL?t=uri This attaches a child (either a file or a directory) to the vdrive at the @@ -140,26 +132,6 @@ nothing exists. vdrive. Intermediate directories are created on-demand just like with the regular PUT command. - PUT $NEWURL?t=upload&localfile=$LOCALPATH - - This uploads a file or directory from the node's local filesystem to the - vdrive. As with "GET $URL?t=download&localfile=$LOCALPATH", this request - will only be accepted from an HTTP connection originating from 127.0.0.1. - - If $LOCALPATH points to a directory on the node's local filesystem, then - the node performs a recursive upload of the directory into the vdrive at - the given location. $NEWURL will be created if necessary. When the - operation is complete, the directory referenced by $NEWURL will contain all - of the files and directories that were present in $LOCALPATH, so this is - equivalent to the unix commands: - - mkdir -p $NEWURL; cp -r $LOCALPATH/* $NEWURL/ - - Note that the "curl" utility can be used to provoke this sort of recursive - upload, since the -T option will make it use an HTTP 'PUT': - - curl -T /dev/null 'http://localhost:8011/vdrive/global/newdir?t=upload&localdir=/home/user/directory-to-upload' - DELETE $URL This deletes the given file or directory from the vdrive. If it is a @@ -169,7 +141,7 @@ nothing exists. may leave some intermediate directory nodes). -=== files by name === +=== Manipulating files by name === PUT $NEWURL @@ -184,11 +156,7 @@ nothing exists. To use this, run 'curl -T localfile http://localhost:8011/vdrive/global/newfile' -=== directories by name === - - GET $URL?t=manifest - - Return an HTML-formatted manifest of the given directory, for debugging. +=== Manipulating directories by name === PUT $NEWURL?t=mkdir @@ -398,3 +366,63 @@ server. etc.. + +== Testing/Debugging Commands == + + GET $URL?t=download&localfile=$LOCALPATH + GET $URL?t=download&localdir=$LOCALPATH + + The localfile= form instructs the node to download the given file and write + it into the local filesystem at $LOCALPATH. The localdir= form instructs + the node to recursively download everything from the given directory and + below into the local filesystem. To avoid surprises, the localfile= form + will signal an error if $URL actually refers to a directory, likewise if + localdir= is used with a $URL that refers to a file. + + This request will only be accepted from an HTTP client connection + originating at 127.0.0.1 . This request is most useful when the client node + and the HTTP client are operated by the same user. $LOCALPATH should be an + absolute pathname. + + This form is only implemented for testing purposes, because of a trivially + easy attack: any web server that the local browser visits could serve an + IMG tag that causes the local node to modify the local filesystem. + Therefore this form is only enabled if you create a file named + 'webport_allow_localfile' in the node's base directory. + + PUT $NEWURL?t=upload&localfile=$LOCALPATH + PUT $NEWURL?t=upload&localdir=$LOCALPATH + + This uploads a file or directory from the node's local filesystem to the + vdrive. As with "GET $URL?t=download&localfile=$LOCALPATH", this request + will only be accepted from an HTTP connection originating from 127.0.0.1 . + + The localfile= form expects that $LOCALPATH will point to a file on the + node's local filesystem, and cause sthe node to upload that one file into + the vdrive at the given location. Any parent directories will be created in + the vdrive as necessary. + + The localdir= form expects that $LOCALPATH will point to a directory on the + node's local filesystem, and it causes the node to perform a recursive + upload of the directory into the vdrive at the given location, creating + parent directories as necessary. When the operation is complete, the + directory referenced by $NEWURL will contain all of the files and + directories that were present in $LOCALPATH, so this is equivalent to the + unix commands: + + mkdir -p $NEWURL; cp -r $LOCALPATH/* $NEWURL/ + + Note that the "curl" utility can be used to provoke this sort of recursive + upload, since the -T option will make it use an HTTP 'PUT': + + curl -T /dev/null 'http://localhost:8011/vdrive/global/newdir?t=upload&localdir=/home/user/directory-to-upload' + + This form is only implemented for testing purposes, because any attacker's + web server that a local browser visits could serve an IMG tag that causes + the local node to modify the local filesystem. Therefore this form is only + enabled if you create a file named 'webport_allow_localfile' in the node's + base directory. + + GET $URL?t=manifest + + Return an HTML-formatted manifest of the given directory, for debugging.