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 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.
use lumberjack for log rolling
Merge pull request #512 from natefinch/lumberjack

use lumberjack for log rolling

This is very similar to the last PR, except I didn't change out the upstart config stuff... since the output redirect doesn't hurt anything, and we need the rest of the code to properly set permissions and owner on the logfile.
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