Update provisioning internals docs

 - Placement directives
 - Availability zone spread

Also, changed to use Markdown format.
Add Restore Mode to stop api calls while restoring

The main goal of this PR is to prevent data loss
during the different steps of the restore process.
This will be used by restore once it lands.
This is the basic required functionality for this
API server mode.
Following a feaure implemented for Upgrade, an
api root server that can selectively allow API
commands depending on the Restore step we are
running.
When we are preparing a restore: that includes
uploading files if required for instance, the
API will only accept Client.Restore to be
triggered in order to avoid data loss when the
restore runs.
When Restore is running no calls will be allowed
since state server will be down.
use the mgo built in remove rather than a custom one
UnShareEnvirionment

Add a new client-side API function: UnShareEnvironment which denies
the given environment user access to the environment.
Merge pull request #679 from voidspace/waitfor-replicaset

Remove the Remove

replicaset/replicaset_test : get rid of extraneous calls to Remove

Remove is a slow operation, and we're seeing spurious failures in CI here. We create a bunch of mongo instances and defer removing them from the replicaset. We destroy them immediately after removal, and then destroy the root, so the Remove is extraneous. This should improve test reliability.
Add a DB dumper abstraction for mongo.
Clean up the legacy backup tests.
Test root.tar as well.
Refactor the legacy Backup function to be more suited toward use in a backups API.
Get rid of the legacy Backup function.
Remove dead code.
Move the DB-related code into its own package.
Move the files-related code into its own package.
Add a backup archive abstraction.
Fix some typos.
Increment using the ++ operator.
Add a missing doc.
NewRootedArchive -> NewArchive.
buildArchiveRaw -> buildArchive.
Drop the extraneous "expected" parameter.