diff --git a/dist/api_data.py b/dist/api_data.py
index 5a07440912f..1623c315710 100644
--- a/dist/api_data.py
+++ b/dist/api_data.py
@@ -480,7 +480,8 @@ connection_runtime_config = [
             ]),
     Config('readonly', 'false', r'''
         open connection in read-only mode.  The database must exist.  All
-        methods that may modify a database are disabled.''',
+        methods that may modify a database are disabled.  See @ref readonly
+        for more information''',
         type='boolean'),
     Config('shared_cache', '', r'''
         shared cache configuration options. A database should configure
diff --git a/src/docs/programming.dox b/src/docs/programming.dox
index 5d79edd660b..f717f4ed1fe 100644
--- a/src/docs/programming.dox
+++ b/src/docs/programming.dox
@@ -30,6 +30,7 @@ each of which is ordered by one or more columns.
 <h2>Programming notes</h2>
 - @subpage threads
 - @subpage namespace
+- @subpage readonly
 @m_if{c}
 - @subpage signals
 @m_endif
diff --git a/src/docs/readonly.dox b/src/docs/readonly.dox
new file mode 100644
index 00000000000..1da103085bf
--- /dev/null
+++ b/src/docs/readonly.dox
@@ -0,0 +1,62 @@
+/*! @m_page{{c,java},readonly,Database read-only mode}
+
+WiredTiger supports opening a database in read-only mode.  When a database
+is opened in read-only mode, all modifications are disabled on the WT_CONNECTION
+handle, any sessions opened in that connection and any cursors opened on any
+of those sessions.  Any session handle method that modifies any part of the
+database will return an error.  Similarly, any WiredTiger internal threads
+that perform modifications will not perform that work.
+
+When a database is opened in read-only mode, WiredTiger assumes the database
+directory and content already exist and that it was a clean shutdown,
+particularly if logging and recovery are used.
+
+@section readonly_config Database readonly configuration considerations
+
+Use of the \c readonly configuration may affect other configuration settings.
+Where the default setting contradicts read-only operation, WiredTiger
+overrides those defaults to perform in a non-modifying mode.  For example,
+merges are turned off if LSM trees are in use, and log file archiving is
+disabled if logging is configured.
+
+Other settings where the user must explicitly turn them on return an error
+if that setting contradicts read-only mode.  For example, statistics logging
+or zero filling log files are not allowed during read-only mode and trying
+to set those will result in an error.
+
+@section readonly_logging Readonly configuration and logging
+
+If logging is enabled on the database when it is opened with the \c readonly
+configuration, log file archiving and log file pre-allocation are disabled.
+The log files will not be modified any way.   Any pre-allocated or temporary
+log files that exist from an earlier run that would normally be removed will
+remain.
+
+@section readonly_recovery Readonly configuration and recovery
+
+Since recovery only reapplies modifications, clearly no recovery actions can
+occur during read-only mode.  The system will detect if recovery is necessary
+or if it was a clean shutdown.  Attempting to open the database via
+::wiredtiger_open will only proceed from a clean shutdown and return an error
+if any recovery is required.
+
+@section readonly_lsm Readonly configuration and LSM trees
+
+If LSM trees are in use, starting up in read-only mode turns off all
+modification.  Internal LSM operations such as merging, creating new chunks,
+creating bloom filters and dropping old chunks are disabled.
+
+@section readonly_handles Readonly configuration and multiple database handles
+
+One unusual affect of read-only operations is the potential for multiple
+read-only database handles open to the same database at the same time, in
+limited circumstances.  WiredTiger prevents multiple connection handles
+by writing to a lock file.  Even in read-only mode, creating and writing
+to the lock file is attempted.  In the case where the database directory or
+the lock file does not exist or cannot be created or written to, a read-only
+handle is allowed to proceed.  So in the case where the database directory
+and its files are read-only, multiple read-only connection handles could
+be open at the same time.  In the case where the database directory is
+writable the normal file locking occurs preventing multiple connections.
+
+*/
diff --git a/src/docs/wtperf.dox b/src/docs/wtperf.dox
index 1f0d1533ac4..6f3d2f87ee0 100644
--- a/src/docs/wtperf.dox
+++ b/src/docs/wtperf.dox
@@ -212,6 +212,10 @@ insert operations
 generate random content for the value
 @par read_range (unsigned int, default=0)
 scan a range of keys after each search
+@par readonly (boolean, default=false)
+reopen the connection between populate and workload phases in readonly
+mode.  Requires reopen_connection turned on (default).  Requires that
+read be the only workload specified
 @par reopen_connection (boolean, default=true)
 close and reopen the connection between populate and workload phases
 @par report_interval (unsigned int, default=2)
diff --git a/src/include/wiredtiger.in b/src/include/wiredtiger.in
index 93eb2d4be8f..6c09983fead 100644
--- a/src/include/wiredtiger.in
+++ b/src/include/wiredtiger.in
@@ -1854,8 +1854,9 @@ struct __wt_connection {
 	 * integer between 3 and 20; default \c 4.}
 	 * @config{ ),,}
 	 * @config{readonly, open connection in read-only mode.  The database
-	 * must exist.  All methods that may modify a database are disabled., a
-	 * boolean flag; default \c false.}
+	 * must exist.  All methods that may modify a database are disabled.
+	 * See @ref readonly for more information., a boolean flag; default \c
+	 * false.}
 	 * @config{shared_cache = (, shared cache configuration options.  A
 	 * database should configure either a cache_size or a shared_cache not
 	 * both.  Enabling a shared cache uses a session from the configured
@@ -2330,8 +2331,8 @@ struct __wt_connection {
  * processes). <b>Not yet supported in WiredTiger</b>., a boolean flag; default
  * \c false.}
  * @config{readonly, open connection in read-only mode.  The database must
- * exist.  All methods that may modify a database are disabled., a boolean flag;
- * default \c false.}
+ * exist.  All methods that may modify a database are disabled.  See @ref
+ * readonly for more information., a boolean flag; default \c false.}
  * @config{session_max, maximum expected number of sessions (including server
  * threads)., an integer greater than or equal to 1; default \c 100.}
  * @config{shared_cache = (, shared cache configuration options.  A database