From c5a5b22c17a81680ac756bb15ba8e940cf0e6770 Mon Sep 17 00:00:00 2001
From: "toby.murray" <toby.murray>
Date: Mon, 19 Jan 2009 22:38:35 -0700
Subject: [PATCH] doc: describe web.ambient_upload_authority

---
 docs/configuration.txt    | 14 ++++++++++++++
 docs/frontends/webapi.txt | 11 +++++++++++
 2 files changed, 25 insertions(+)

diff --git a/docs/configuration.txt b/docs/configuration.txt
index 6df08624..8642ffa1 100644
--- a/docs/configuration.txt
+++ b/docs/configuration.txt
@@ -70,6 +70,20 @@ web.static = (string, optional)
  With the default settings, http://127.0.0.1:3456/static/foo.html will serve
  the contents of $BASEDIR/public_html/foo.html .
 
+web.ambient_upload_authority = (boolean, optional)
+
+ This controls whether a node's web server should provide "ambient"
+ upload/create authority by controlling whether it responds to PUT and
+ POST requests that do not contain a cap -- i.e. those for uploading
+ new unlinked files and creating new unlinked directories. If set to
+ True, a node will respond to these requests as usual.  If set to
+ False, a node will instead refuse these requests, returning an HTTP
+ status of 'Bad Request'.  The default value is True.
+
+ Note that setting this to False does not prevent performing operations
+ on files and directories that already exist, since all of these operations
+ require the presentation of a cap.
+
 tub.port = (integer, optional)
 
  This controls which port the node uses to accept Foolscap connections from
diff --git a/docs/frontends/webapi.txt b/docs/frontends/webapi.txt
index 8cc9288f..5f7dc384 100644
--- a/docs/frontends/webapi.txt
+++ b/docs/frontends/webapi.txt
@@ -320,6 +320,9 @@ PUT /uri
  mutable file, and return its write-cap in the HTTP respose. The default is
  to create an immutable file, returning the read-cap as a response.
 
+ Note that this operation is available only when the configuration setting
+ 'web.ambient_upload_authority' is not False (see configuration.txt).
+
 === Creating A New Directory ===
 
 POST /uri?t=mkdir
@@ -330,6 +333,9 @@ PUT /uri?t=mkdir
  virtual drive. The "PUT" operation is provided for backwards compatibility:
  new code should use POST.
 
+ Note that these operations are available only when the configuration setting
+ 'web.ambient_upload_authority' is not False (see configuration.txt).
+
 POST /uri/$DIRCAP/[SUBDIRS../]SUBDIR?t=mkdir
 PUT /uri/$DIRCAP/[SUBDIRS../]SUBDIR?t=mkdir
 
@@ -572,6 +578,9 @@ POST /uri?t=mkdir
  "false"), then the HTTP response body will simply be the write-cap of the
  new directory.
 
+ Note that this operation is available only when the configuration setting
+ 'web.ambient_upload_authority' is not False (see configuration.txt).
+
 POST /uri/$DIRCAP/[SUBDIRS../]?t=mkdir&name=CHILDNAME
 
  This creates a new directory as a child of the designated SUBDIR. This will
@@ -616,6 +625,8 @@ POST /uri?t=upload
  the upload results page. The default is to create an immutable file,
  returning the upload results page as a response.
 
+ Note that this operation is available only when the configuration setting
+ 'web.ambient_upload_authority' is not False (see configuration.txt).
 
 POST /uri/$DIRCAP/[SUBDIRS../]?t=upload
 
-- 
2.45.2