Update provisioning internals docs

 - Placement directives
 - Availability zone spread

Also, changed to use Markdown format.
Add API func ShareEnvironment to client and server API:

ShareEnvironment shares the current environment with the given user.
Under the hood, it adds an environment user to state.
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
juju/testing: don't remove admin user in JujuConnSuite

We no longer enable mongo auth in our tests, so there's
no need for the "soft resetting" anymore.
Merge branch 'master' of https://github.com/juju/juju into share-env-take2
Merge branch 'master' of https://github.com/juju/juju into share-env-take2
Merge pull request #645 from waigani/share-env-take2

New client & server API func ShareEnvironment

ShareEnvironment shares the current environment with the given user.
Under the hood, it adds an environment user to state.
move the tests inline
Remove the user checking for the keymanager.
Merge pull request #688 from axw/jujuconnsuite-dont-remove-admin

juju/testing: don't remove admin user in JujuConnSuite

We no longer enable mongo auth in our tests, so there's
no need for the "soft resetting" anymore.
Update names dependency.
Core changes to store tools in state
Search, download and cache tools from public/configured tools sources

FindTools will now search simplestreams unless an exact match is
being performed and that is found in toolstorage. Tools found in
toolstorage will take precedence over those in simplestreams.

If a tools version is requested for download and it is not in
toolstorage already, the API server will search for it in simplestreams,
download it, and cache it in toolstorage before returning it to
the client.

Also, we now once again (as in 1.20) only clone tools on upload if
requested. We will drop the "AddToolsAlias" function from toolstorage.
cmd/jujud: clone tools, don't alias metadata
Fix apiserver tools serving
Fix tests
Merge pull request #692 from howbazaar/refactor-perm-test

Move the tests inline

Refactoring the test to allow for a smaller diff later when we change the user tags.

This change just moves the tests and the variables to be in the test function.
Merge pull request #694 from howbazaar/update-names

Update names dependency.

Just bring in the latest names changes.
Remove DisplayName option

Remove the option to set an environ user's display name from the
AddEnvirionmentUser function. Update call sites and expected test
results.