Index: rest-config-examples-curl.rst
===================================================================
--- rest-config-examples-curl.rst	(revision 14383)
+++ rest-config-examples-curl.rst	(working copy)
@@ -102,6 +102,74 @@
      ...
    </featureType>
 
+Uploading a GeoTIFF
+------------------------
+
+This example will demonstrate how to create a new coverage and coveragestore 
+for a GeoTIFF.  The process should work for other georeferenced image (JPGs, 
+PNGs), and for image mosaics.
+
+The first step is to create a coveragestore.  The following command creates a
+coveragestore called ``radar_sample`` in the ``acme`` workspace::
+
+  curl -u admin:geoserver -v -XPOST -H 'Content-Type: application/xml' \
+    -d '<coverageStore><name>radar_sample</name><workspace>acme</workspace><enabled>true</enabled></coverageStore>' \
+    http://localhost:8080/geoserver/rest/workspaces/acme/coveragestores
+
+Creating a coveragestore creates an associated coverage, but at this point the
+coverage has no data.  The next step is to supply an image.  In this case,
+``radar_sample.tiff`` will be used.  A layer is automatically created for the
+coverage when it is updated in this way::
+
+  curl -u admin:geoserver -v -XPUT -H 'Content-type: image/tiff' --data-binary @radar_sample.tiff \
+  http://localhost:8080/geoserver/rest/workspaces/acme/coveragestores/radar_sample/file.geotiff?configure=first\&coverageName=radar_sample
+
+The response from GeoServer will contain XML describing the newly update coverage.
+
+.. code-block:: xml
+  <coverageStore>
+    <name>radar_sample</name>
+    <type>GeoTIFF</type>
+    <enabled>true</enabled>
+    <workspace>
+      <name>acme</name>
+      <href>http://localhost:8080/geoserver/rest/workspaces/WorkspaceInfoImpl--36fdf639:128a78f14db:-8000.xml</href>
+    </workspace>
+    <url>file:data/radar_sample/radar_sample.geotiff</url>
+    <coverages>
+      <atom:link xmlns:atom="http://www.w3.org/2005/Atom" rel="alternate" href="http://localhost:8080/geoserver/rest/workspaces/acme/coveragestores/radar_sample/file/coverages.xml" type="application/xml"/>
+    </coverages>
+  </coverageStore>
+
+If the image file is on a filesystem accessible to GeoServer, it is possible 
+to upload only a reference to the file rather than the file itself::
+
+  curl -u admin:geoserver -v -XPUT -H 'Content-type: text/plain' -d 'file:/Users/alex/radar_sample.tiff' \
+  http://localhost:8080/geoserver/rest/workspaces/acme/coveragestores/radar_sample/url.geotiff?configure=first\&coverageName=radar_sample
+
+A copy of ``/Users/alex/radar_sample.tiff`` will be added to GeoServer's data 
+directory.  The original file is no longer needed.
+
+GeoServer can also be configured to reference a file which is not in its data 
+directory::
+
+  curl -u admin:geoserver -v -XPUT -H 'Content-type: text/plain' -d 'file:/Users/alex/radar_sample.tiff' \
+  http://localhost:8080/geoserver/rest/workspaces/acme/coveragestores/radar_sample/external.geotiff?configure=first\&coverageName=radar_sample
+
+GeoServer's configuration will now reference ``/Users/alex/radar_sample.tiff`` 
+directly.  No copy of the file is made.  If this file is removed, GeoServer
+will raise errors when requests are made for the layer.
+
+Notice the absolute path in the XML returned by GeoServer in response to an 
+``external.geotiff`` PUT.
+
+.. code-block:: xml
+  <coverageStore>
+    ...
+    <url>file:/Users/alex/radar_sample.tiff</url>
+    ...
+  </coverageStore>
+
 Changing a feature type style
 -----------------------------
 
Index: rest-config-api.rst
===================================================================
--- rest-config-api.rst	(revision 14383)
+++ rest-config-api.rst	(working copy)
@@ -770,6 +770,23 @@
    one. However there is currently work underway to support multi-dimensional
    coverages, so in the future this parameter is likely to change.
 
+
+``/workspaces/<ws>/coveragestores/<cs>/url[.<extension>]``
+The ``extension`` parameter specifies the type of coverage store, in the same 
+manner as ``file.extension`` above.  Rather than containing the file itself, the
+upload body should be a plain-text 'file:/local/file' string referencing a 
+file on the local filesystem.  The file resource is copied into GeoServer's 
+DATA_DIR just as if you had uploaded it with ``file.extension``.
+
+
+``/workspaces/<ws>/coveragestores/<cs>/external[.<extension>]``
+The ``extension`` parameter specifies the type of coverage store, in the same 
+manner as ``file.extension`` above.  Rather than containing the file itself, the
+upload body should be a plain-text 'file:/local/file' string referencing a 
+file on the local filesystem.  The file resource is not copied into GeoServer's 
+DATA_DIR.
+
+
 Coverages
 ---------