Mailing-List: contact commits-help@brooklyn.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@brooklyn.apache.org
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
From: drigodwin@apache.org
To: commits@brooklyn.apache.org
Date: Fri, 16 Jun 2017 15:21:46 -0000
Message-Id: <6a5cb932f16f481980b9fd8055efa455@git.apache.org>
In-Reply-To: <ded7266c75aa4a32872f2346b7a7c24e@git.apache.org>
References: <ded7266c75aa4a32872f2346b7a7c24e@git.apache.org>
Subject: [06/28] brooklyn-docs git commit: Refactor Blueprinting
archived-at: Fri, 16 Jun 2017 15:21:49 -0000

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/1330dcd3/guide/locations/_byon.md
----------------------------------------------------------------------
diff --git a/guide/locations/_byon.md b/guide/locations/_byon.md
new file mode 100644
index 0000000..948994d
--- /dev/null
+++ b/guide/locations/_byon.md
@@ -0,0 +1,77 @@
+---
+section: BYON
+section_position: 8
+section_type: inline
+---
+
+### BYON
+
+"Bring-your-own-nodes" mode is useful in production, where machines have been provisioned by someone else,
+and during testing, to cut down provisioning time.
+
+Your nodes must meet the following prerequisites:
+
+- A suitable OS must have been installed on all nodes
+- The node must be running sshd (or similar)
+- the brooklyn user must be able to ssh to each node as root or as a user with passwordless sudo permission. (For more information on SSH keys, see [here](#ssh-keys).) 
+
+To deploy to machines with known IP's in a blueprint, use the following syntax:
+
+{% highlight yaml %}
+location:
+  byon:
+    user: brooklyn
+    privateKeyFile: ~/.ssh/brooklyn.pem
+    hosts:
+    - 192.168.0.18
+    - 192.168.0.19
+{% endhighlight %}
+
+Some of the login properties as described above for jclouds are supported,
+but not `loginUser` (as no users are created), and not any of the
+VM creation parameters such as `minRam` and `imageId`.
+(These clearly do not apply in the same way, and they are *not* 
+by default treated as constraints, although an entity can confirm these
+where needed.)
+As before, if the brooklyn user and its default key are authorized for the hosts,
+those fields can be omitted.
+
+Named locations can also be configured in your `brooklyn.properties`,
+using the format `byon:(key=value,key2=value2)`.
+For convenience, for hosts wildcard globs are supported.
+
+{% highlight bash %}
+brooklyn.location.named.On-Prem\ Iron\ Example=byon:(hosts="10.9.1.1,10.9.1.2,produser2@10.9.2.{10,11,20-29}")
+brooklyn.location.named.On-Prem\ Iron\ Example.user=produser1
+brooklyn.location.named.On-Prem\ Iron\ Example.privateKeyFile=~/.ssh/produser_id_rsa
+brooklyn.location.named.On-Prem\ Iron\ Example.privateKeyPassphrase=s3cr3tpassphrase
+{% endhighlight %}
+
+Alternatively, you can create a specific BYON location through the location wizard tool available within the web console.
+This location will be saved as a [catalog entry]({{ site.path.guide }}/blueprints/catalog/index.html#locations-in-catalog) for easy reusability.
+
+For more complex host configuration, one can define custom config values per machine. In the example 
+below, there will be two machines. The first will be a machine reachable on
+`ssh -i ~/.ssh/brooklyn.pem -p 8022 myuser@50.51.52.53`. The second is a windows machine, reachable 
+over WinRM. Each machine has also has a private address (e.g. for within a private network).
+
+{% highlight yaml %}
+location:
+  byon:
+    hosts:
+    - ssh: 50.51.52.53:8022
+      privateAddresses: [10.0.0.1]
+      privateKeyFile: ~/.ssh/brooklyn.pem
+      user: myuser
+    - winrm: 50.51.52.54:8985
+      privateAddresses: [10.0.0.2]
+      password: mypassword
+      user: myuser
+      osFamily: windows
+{% endhighlight %}
+
+The BYON location also supports a machine chooser, using the config key `byon.machineChooser`. 
+This allows one to plugin logic to choose from the set of available machines in the pool. For
+example, additional config could be supplied for each machine. This could be used (during the call
+to `location.obtain()`) to find the config that matches the requirements of the entity being
+provisioned. See `FixedListMachineProvisioningLocation.MACHINE_CHOOSER`.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/1330dcd3/guide/locations/_clouds.md
----------------------------------------------------------------------
diff --git a/guide/locations/_clouds.md b/guide/locations/_clouds.md
new file mode 100644
index 0000000..f1c3024
--- /dev/null
+++ b/guide/locations/_clouds.md
@@ -0,0 +1,302 @@
+---
+section: Clouds
+section_type: inline
+section_position: 1
+---
+
+### Clouds
+
+For most cloud provisioning tasks, Brooklyn uses
+<a href="http://jclouds.org">Apache jclouds</a>.
+The identifiers for some of the most commonly used jclouds-supported clouds are
+(or [see the full list](http://jclouds.apache.org/reference/providers/)):
+
+* `jclouds:aws-ec2:<region>`: Amazon EC2, where `:<region>` might be `us-east-1` or `eu-west-1` (or omitted)
+* `jclouds:softlayer:<region>`: IBM Softlayer, where `:<region>` might be `dal05` or `ams01` (or omitted)
+* `jclouds:google-compute-engine`: Google Compute Engine
+* `jclouds:openstack-nova:<endpoint>`: OpenStack, where `:<endpoint>` is the access URL (required)
+* `jclouds:cloudstack:<endpoint>`: Apache CloudStack, where `:<endpoint>` is the access URL (required)
+
+For any of these, of course, Brooklyn needs to be configured with an `identity` and a `credential`:
+
+{% highlight yaml %}
+location:
+  jclouds:aws-ec2:
+    identity: ABCDEFGHIJKLMNOPQRST
+    credential: s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l
+{% endhighlight %} 
+
+The above YAML can be embedded directly in blueprints, either at the root or on individual services.
+If you prefer to keep the credentials separate, you can instead store them as a [catalog entry]({{ site.path.guide }}/blueprints/catalog/index.html#locations-in-catalog) or set them in `brooklyn.properties` 
+in the `jclouds.<provider>` namespace:
+
+{% highlight bash %}
+brooklyn.location.jclouds.aws-ec2.identity=ABCDEFGHIJKLMNOPQRST  
+brooklyn.location.jclouds.aws-ec2.credential=s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l
+{% endhighlight %}
+
+And in this case you can reference the location in YAML with `location: jclouds:aws-ec2`.
+
+Alternatively, you can use the location wizard tool available within the web console
+to create any cloud location supported by <a href="http://jclouds.org">Apache jclouds</a>.
+This location will be saved as a [catalog entry]({{ site.path.guide }}/blueprints/catalog/index.html#locations-in-catalog) for easy reusability.
+
+Brooklyn irons out many of the differences between clouds so that blueprints run similarly
+in a wide range of locations, including setting up access and configuring images and machine specs.
+The configuration options are described in more detail below.
+
+In some cases, cloud providers have special features or unusual requirements. 
+These are outlined in **[More Details for Specific Clouds](#more-details-on-specific-clouds)**.
+
+#### OS Initial Login and Setup
+
+Once a machine is provisioned, Brooklyn will normally attempt to log in via SSH and configure the machine sensibly.
+
+The credentials for the initial OS log on are typically discovered from the cloud, 
+but in some environments this is not possible.
+The keys `loginUser` and either `loginUser.password` or `loginUser.privateKeyFile` can be used to force
+Brooklyn to use specific credentials for the initial login to a cloud-provisioned machine.
+
+(This custom login is particularly useful when using a custom image templates where the cloud-side account 
+management logic is not enabled. For example, a vCloud (vCD) template can have guest customization that will change
+the root password. This setting tells Apache Brooklyn to only use the given password, rather than the initial 
+randomly generated password that vCD returns. Without this property, there is a race for such templates:
+does Brooklyn manage to create the admin user before the guest customization changes the login and reboots,
+or is the password reset first (the latter means Brooklyn can never ssh to the VM). With this property, 
+Brooklyn will always wait for guest customization to complete before it is able to ssh at all. In such
+cases, it is also recommended to use `useJcloudsSshInit=false`.)
+
+Following a successful logon, Brooklyn performs the following steps to configure the machine:
+
+1. creates a new user with the same name as the user `brooklyn` is running as locally
+  (this can be overridden with `user`, below).
+
+1. install the local user's `~/.ssh/id_rsa.pub` as an `authorized_keys` on the new machine,
+   to make it easy for the operator to `ssh` in
+   (override with `privateKeyFile`; or if there is no `id_{r,d}sa{,.pub}` an ad hoc keypair will be generated
+   for the regular Brooklyn user;
+   if there is a passphrase on the key, this must be supplied)  
+
+1. give `sudo` access to the newly created user (override with `grantUserSudo: false`)
+
+1. disable direct `root` login to the machine
+
+These steps can be skipped or customized as described below.
+
+#### jclouds Config Keys
+
+The following is a subset of the most commonly used configuration keys used to customize 
+cloud provisioning.
+For more keys and more detail on the keys below, see 
+{% include java_link.html class_name="JcloudsLocationConfig" package_path="org/apache/brooklyn/location/jclouds" project_subpath="locations/jclouds" %}.
+
+###### VM Creation
+    
+- Most providers require exactly one of either `region` (e.g. `us-east-1`) or `endpoint` (the URL, usually for private cloud deployments)
+
+- Hardware requirements can be specified, including 
+  `minRam`, `minCores`, and `os64Bit`; or as a specific `hardwareId`
+
+- VM image constraints can be set using `osFamily` (e.g. `Ubuntu`, `CentOS`, `Debian`, `RHEL`)
+  and `osVersionRegex`, or specific VM images can be specified using `imageId` or `imageNameRegex`
+
+- Specific VM images can be specified using `imageId` or `imageNameRegex`
+
+- Specific Security Groups can be specified using `securityGroups`, as a list of strings (the existing security group names),
+  or `inboundPorts` can be set, as a list of numeric ports (selected clouds only)
+
+- Where a key pair is registered with a target cloud for logging in to machines,
+  Brooklyn can be configured to request this when provisioning VMs by setting `keyPair` (selected clouds only). 
+  Note that if this `keyPair` does not correspond your default `~/.ssh/id_rsa`, you must typically 
+  also specify the corresponding `loginUser.privateKeyFile` as a file or URL accessible from Brooklyn.
+
+- A specific VM name (often the hostname) base to be used can be specified by setting `groupId`.
+  By default, this name is constructed based on the entity which is creating it,
+  including the ID of the app and of the entity.
+  (As many cloud portals let you filter views, this can help find a specific entity or all machines for a given application.)
+  For more sophisticated control over host naming, you can supply a custom 
+  {% include java_link.html class_name="CloudMachineNamer" package_path="org/apache/brooklyn/core/location/cloud/names" project_subpath="core" %},
+  for example
+  `cloudMachineNamer: CustomMachineNamer`.
+  {% include java_link.html class_name="CustomMachineNamer" package_path="org/apache/brooklyn/core/location/cloud/names" project_subpath="core" %}
+  will use the entity's name or following a template you supply.
+  On many clouds, a random suffix will be appended to help guarantee uniqueness;
+  this can be removed by setting `vmNameSaltLength: 0` (selected clouds only).
+  <!-- TODO jclouds softlayer includes a 3-char hex suffix -->
+  
+- A DNS domain name where this host should be placed can be specified with `domainName`
+  (in selected clouds only)
+
+- User metadata can be attached using the syntax `userMetadata: { key: value, key2: "value 2" }` 
+  (or `userMetadata=key=value,key2="value 2"` in a properties file)
+
+- By default, several pieces of user metadata are set to correlate VMs with Brooklyn entities,
+  prefixed with `brooklyn-`.
+  This user metadata can be omitted by setting `includeBrooklynUserMetadata: false`.
+
+- You can specify the number of attempts Brooklyn should make to create
+  machines with `machineCreateAttempts` (jclouds only). This is useful as an efficient low-level fix
+  for those occasions when cloud providers give machines that are dead on arrival.
+  You can of course also resolve it at a higher level with a policy such as 
+  {% include java_link.html class_name="ServiceRestarter" package_path="org/apache/brooklyn/policy/ha" project_subpath="policy" %}.
+
+- If you want to investigate failures, set `destroyOnFailure: false`
+  to keep failed VM's around. (You'll have to manually clean them up.)
+  The default is false: if a VM fails to start, or is never ssh'able, then the VM will be terminated.
+  
+- You can set `useMachinePublicAddressAsPrivateAddress` to true to overwrite the VMs private IP with its public IP. This is useful as it can be difficult to get VMs communicating via the private IPs they are assigned in some clouds.  Using this config, blueprints which use private IPs can still be deployed to these clouds.
+  
+  ###### OS Setup
+
+- `user` and `password` can be used to configure the operating user created on cloud-provisioned machines
+
+- The `loginUser` config key (and subkeys) control the initial user to log in as,
+  in cases where this cannot be discovered from the cloud provider
+ 
+- Private keys can be specified using `privateKeyFile`; 
+  these are not copied to provisioned machines, but are required if using a local public key
+  or a pre-defined `authorized_keys` on the server.
+  (For more information on SSH keys, see [here](#ssh-keys).) 
+
+- If there is a passphrase on the key file being used, you must supply it to Brooklyn for it to work, of course!
+  `privateKeyPassphrase` does the trick (as in `brooklyn.location.jclouds.privateKeyPassphrase`, or other places
+  where `privateKeyFile` is valid).  If you don't like keys, you can just use a plain old `password`.
+
+- Public keys can be specified using `publicKeyFile`, 
+  although these can usually be omitted if they follow the common pattern of being
+  the private key file with the suffix `.pub` appended.
+  (It is useful in the case of `loginUser.publicKeyFile`, where you shouldn't need,
+  or might not even have, the private key of the `root` user when you log in.)
+
+- Provide a list of URLs to public keys in `extraSshPublicKeyUrls`,
+  or the data of one key in `extraSshPublicKeyData`,
+  to have additional public keys added to the `authorized_keys` file for logging in.
+  (This is supported in most but not all locations.)
+  
+- Use `dontCreateUser` to have Brooklyn run as the initial `loginUser` (usually `root`),
+  without creating any other user.
+
+- A post-provisioning `setup.script` can be specified to run an additional script, before making the `Location` 
+  available to entities. This may take the form of a URL of a script or a [data URI](https://en.wikipedia.org/wiki/Data_URI_scheme).
+  Note that if using a data URI it is usually a good idea to [base64](https://en.wikipedia.org/wiki/Base64) this string to escape problem characters
+  in more complex scripts. The base64 encoded script should then be prefixed with `data:text/plain;base64,` to denote this. 
+  For example if you wanted to disable a yum repository called `reponame` prior to using the machine, you could use the following command:
+  
+  `sudo yum-config-manager --disable reponame`
+    
+  Base64 encoding can be done with a with a tool such as [this](https://www.base64encode.org/) or a linux command such as:
+  
+  `echo "sudo yum-config-manager --disable reponame" | base64`
+  
+  With the base64 prefix this would then look like this:
+
+  `setup.script: data:text/plain;base64,c3VkbyB5dW0tY29uZmlnLW1hbmFnZXIgLS1kaXNhYmxlIHJlcG9uYW1l`
+
+  The `setup.script` can also take [FreeMarker](http://freemarker.org/) variables in a `setup.script.vars`
+  property. Variables are set in the format `key1:value1,key2:value2` and used in the form `${key1}`. So for the above example:
+  
+  `setup.script.vars: repository:reponame`
+  
+  then
+  
+  `setup.script: data:sudo yum-config-manager --disable ${repository}`
+  
+  or encoded in base64:
+  
+  `setup.script: data:text/plain;base64,c3VkbyB5dW0tY29uZmlnLW1hbmFnZXIgLS1kaXNhYmxlICR7cmVwb3NpdG9yeX0=`
+  
+  This enables the name of the repository to be passed in to the script.
+
+- Use `openIptables: true` to automatically configure `iptables`, to open the TCP ports required by
+  the software process. One can alternatively use `stopIptables: true` to entirely stop the
+  iptables service.
+
+- Use `installDevUrandom: true` to fall back to using `/dev/urandom` rather than `/dev/random`. This setting
+  is useful for cloud VMs where there is not enough random entropy, which can cause `/dev/random` to be
+  extremely slow (causing `ssh` to be extremely slow to respond).
+
+- Use `useJcloudsSshInit: false` to disable the use of the native jclouds support for initial commands executed 
+  on the VM (e.g. for creating new users, setting root passwords, etc.). Instead, Brooklyn's ssh support will
+  be used. Timeouts and retries are more configurable within Brooklyn itself. Therefore this option is particularly 
+  recommended when the VM startup is unusual (for example, if guest customizations will cause reboots and/or will 
+  change login credentials).
+
+- Use `brooklyn.ssh.config.noDeleteAfterExec: true` to keep scripts on the server after execution.
+  The contents of the scripts and the stdout/stderr of their execution are available in the Brooklyn web console,
+  but sometimes it can also be useful to have them on the box.
+  This setting prevents scripts executed on the VMs from being deleted on completion.
+  Note that some scripts run periodically so this can eventually fill a disk; it should only be used for dev/test. 
+
+###### Custom Template Options
+
+jclouds supports many additional options for configuring how a virtual machine is created and deployed, many of which
+are for cloud-specific features and enhancements. Brooklyn supports some of these, but if what you are looking for is
+not supported directly by Brooklyn, we instead offer a mechanism to set any parameter that is supported by the jclouds
+template options for your cloud.
+
+Part of the process for creating a virtual machine is the creation of a jclouds `TemplateOptions` object. jclouds
+providers extends this with extra options for each cloud - so when using the AWS provider, the object will be of
+type `AWSEC2TemplateOptions`. By [examining the source code](https://jclouds.apache.org/reference/javadoc/2.0.x/org/jclouds/aws/ec2/compute/AWSEC2TemplateOptions.html),
+you can see all of the options available to you.
+
+The `templateOptions` config key takes a map. The keys to the map are method names, and Brooklyn will find the method on
+the `TemplateOptions` instance; it then invokes the method with arguments taken from the map value. If a method takes a
+single parameter, then simply give the argument as the value of the key; if the method takes multiple parameters, the
+value of the key should be an array, containing the argument for each parameter.
+
+For example, here is a complete blueprint that sets some AWS EC2 specific options:
+
+    location: AWS_eu-west-1
+    services:
+    - type: org.apache.brooklyn.entity.software.base.EmptySoftwareProcess
+      provisioningProperties:
+        templateOptions:
+          subnetId: subnet-041c8373
+          mapNewVolumeToDeviceName: ["/dev/sda1", 100, true]
+          securityGroupIds: ['sg-4db68928']
+
+Here you can see that we set three template options:
+
+- `subnetId` is an example of a single parameter method. Brooklyn will effectively try to run the statement
+  `templateOptions.subnetId("subnet-041c88373");`
+- `mapNewVolumeToDeviceName` is an example of a multiple parameter method, so the value of the key is an array.
+  Brooklyn will effectively true to run the statement `templateOptions.mapNewVolumeToDeviceName("/dev/sda1", 100, true);`
+- `securityGroupIds` demonstrates an ambiguity between the two types; Brooklyn will first try to parse the value as
+  a multiple parameter method, but there is no method that matches this parameter. In this case, Brooklyn will next try
+  to parse the value as a single parameter method which takes a parameter of type `List`; such a method does exist so
+  the operation will succeed.
+
+If the method call cannot be matched to the template options available - for example if you are trying to set an AWS EC2
+specific option but your location is an OpenStack cloud - then a warning is logged and the option is ignored.
+
+###### Cloud Machine Naming
+
+The name that Apache Brooklyn generates for your virtual machine will, by default, be based on your Apache Brooklyn server name and the IDs of the entities involved. This is the name you see in places such as the AWS console and will look something like:
+
+    brooklyn-o8jql4-machinename-rkix-tomcat-wi-nca6-14b
+
+If you have created a lot of virtual machines, this kind of naming may not be helpful. This can be changed using the following YAML in your location's `brooklyn.config`:
+
+    cloudMachineNamer: org.apache.brooklyn.core.location.cloud.names.CustomMachineNamer
+    custom.machine.namer.machine: My-Custom-Name-${entity.displayName}
+
+A [FreeMarker](http://freemarker.org/) format is used in `custom.machine.namer.machine` which can take values from places such as the launching entity or location.
+
+The above example will create a name such as:
+
+    My-Custom-Name-Tomcat
+    
+Allowing you to more easily identify your virtual machines.
+
+### More Details on Specific Clouds
+
+Clouds vary in the format of the identity, credential, endpoint, and region.
+Some also have their own idiosyncracies.  More details for configuring some common clouds
+is included below. You may also find these sources helpful:
+
+* The **[template brooklyn.properties]({{ site.path.guide }}/start/brooklyn.properties)** file
+  in the Getting Started guide
+  contains numerous examples of configuring specific clouds,
+  including the format of credentials and options for sometimes-fiddly private clouds.
+* The **[jclouds guides](https://jclouds.apache.org/guides)** describes low-level configuration
+  sometimes required for various clouds.

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/1330dcd3/guide/locations/_cloudstack.md
----------------------------------------------------------------------
diff --git a/guide/locations/_cloudstack.md b/guide/locations/_cloudstack.md
new file mode 100644
index 0000000..50a7e0c
--- /dev/null
+++ b/guide/locations/_cloudstack.md
@@ -0,0 +1,143 @@
+---
+section: CloudStack
+title: Apache CloudStack
+section_type: inline
+section_position: 4
+---
+
+## Apache CloudStack
+
+### Connection Details
+
+The endpoint URI will normally have the suffix `/client/api/`.
+
+The identity is the "api key" and the credential is the "secret key". These can be generated in 
+the CloudStack gui: under accounts, select "view users", then "generate key".
+
+    location:
+      jclouds:cloudstack:
+        endpoint: https://cloud.acme.com/client/api
+        identity: abcdefghijklmnopqrstuvwxyz01234567890-abcdefghijklmnopqrstuvwxyz01234567890-abcdefghij
+        credential: mycred-abcdefghijklmnopqrstuvwxyz01234567890-abcdefghijklmnopqrstuvwxyz01234567890-abc
+
+Users are strongly recommended to use 
+[externalized configuration]({{ site.path.guide }}/ops/externalized-configuration.html) for better
+credential management, for example using [Vault](https://www.vaultproject.io/).
+
+
+### Common Configuration Options
+
+Below are examples of configuration options that use values specific to CloudStack environments:
+
+* The `imageId` is the template id. For example,
+  `imageId: db0bcce3-9e9e-4a87-a953-2f46b603498f`.
+
+* The `region` is CloudStack zone id.
+  For example `region: 84539b9c-078e-458a-ae26-c3ffc5bb1ec9`..
+
+* `networkName` is the network id (within the given zone) to be used. For example, 
+  `networkName: 961c03d4-9828-4037-9f4d-3dd597f60c4f`.
+
+For further configuration options, consult 
+[jclouds CloudStack template options](https://jclouds.apache.org/reference/javadoc/1.9.x/org/jclouds/cloudstack/compute/options/CloudStackTemplateOptions.html).
+These can be used with the **[templateOptions](#custom-template-options)** configuration option.
+
+
+### Using a Pre-existing Key Pair
+
+The configuration below uses a pre-existing key pair:
+
+    location:
+      jclouds:cloudstack:
+        ...
+        loginUser: root
+        loginUser.privateKeyFile: /path/to/keypair.pem
+        keyPair: my-keypair
+
+
+### Using Pre-existing Security Groups
+
+To specify existing security groups, their IDs must be used rather than their names (note this
+differs from the configuration on other clouds!).
+ 
+The configuration below uses a pre-existing security group:
+
+    location:
+      jclouds:cloudstack:
+        ...
+        templateOptions:
+          generateSecurityGroup: false
+          securityGroupIds:
+          - 12345678-90ab-def0-1234-567890abcdef
+
+
+### Using Static NAT
+
+Assigning a public IP to a VM at provision-time is referred to as "static NAT" in CloudStack
+parlance. To give some consistency across different clouds, the configuration option is named
+`autoAssignFloatingIp`. For example, `autoAssignFloatingIp: false`.
+
+
+### CloudMonkey CLI
+
+The [CloudStack CloudMonkey CLI](https://cwiki.apache.org/confluence/display/CLOUDSTACK/CloudStack+cloudmonkey+CLI)
+is a very useful tool. It gives is an easy way to validate that credentials are correct, and to query  
+the API to find the correct zone IDs etc.
+
+Useful commands include:
+
+    # for finding the ids of the zones:
+    cloudmonkey api listZones
+
+    # for finding the ids of the networks.
+    cloudmonkey api listNetworks | grep -E "id =|name =|========="
+
+
+### CloudStack Troubleshooting
+
+These troubleshooting tips are more geared towards problems encountered in old test/dev 
+CloudStack environment.
+
+
+#### Resource Garbage Collection Issues
+
+The environment may run out of resources, due to GC issues, preventing the user from creating new 
+VMs or allocating IP addresses (May respond with this error message: 
+`errorCode=INTERNAL_ERROR, errorText=Job failed due to exception Unable to create a deployment for VM`). 
+There are two options worth checking it to enforce clearing up the zombie resources:
+
+* Go to the Accounts tab in the webconsole and tap on the Update Resource Count button.
+* Restart the VPC in question from the Network tab.
+
+
+#### Releasing Allocated Public IP Addresses
+
+Releasing an allocated Public IP from the web console did not free up the resources. Instead 
+CloudMonkey can be used to dissociate IPs and expunge VMs.
+
+Here is a CloudMonkey script to dissociate any zombie IPs:
+
+    cloudmonkey set display json;
+    cloudmonkey api listPublicIpAddresses | grep '"id":' > ips.txt; 
+    sed -i -e s/'      "id": "'/''/g ips.txt;
+    sed -i -e s/'",'/''/g ips.txt
+    for line in $(cat ips.txt); do cloudmonkey api disassociateIpAddress id="$line"; done
+    rm ips.txt;
+    cloudmonkey set display default;
+
+
+#### Restarting VPCs
+
+Errors have been encountered when a zone failed to provision new VMs, with messages like:
+
+    Job failed due to exception Resource [Host:15] is unreachable: Host 15: Unable to start instance due to null
+
+The workaround was to restart the VPC networks:
+
+* Log into the CloudStack web-console.
+* Go to Network -> VPC (from the "select view")
+* For each of the VPCs, click on the "+" in the "quickview" column, and invoke "restart VPC".
+
+Other symptoms of this issue were that: 1) an administrator could still provision VMs using 
+the admin account, which used a different network; and 2) the host number was very low, so it 
+was likely to be a system host/VM that was faulty.

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/1330dcd3/guide/locations/_ibm-softlayer.md
----------------------------------------------------------------------
diff --git a/guide/locations/_ibm-softlayer.md b/guide/locations/_ibm-softlayer.md
new file mode 100644
index 0000000..e1a5d40
--- /dev/null
+++ b/guide/locations/_ibm-softlayer.md
@@ -0,0 +1,135 @@
+---
+section: IBM Softlayer
+title: IBM Softlayer
+section_type: inline
+section_position: 6
+---
+
+## IBM SoftLayer
+
+### Credentials
+
+Credentials can be obtained from the Softlayer API, under "administrative -> user administration -> api-access".
+
+For example:
+
+    location:
+      jclouds:softlayer:
+        region: ams01
+        identity: my-user-name
+        credential: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
+
+Users are strongly recommended to use 
+[externalized configuration]({{ site.path.guide }}/ops/externalized-configuration.html) for better
+credential management, for example using [Vault](https://www.vaultproject.io/).
+
+
+### Common Configuration Options
+
+Below are examples of configuration options that use values specific to Softlayer:
+
+* The `region` is the [Softlayer datacenter](http://www.softlayer.com/data-centers).
+  For example, `region: dal05`.
+
+* The `hardwareId` is an auto-generated combination of the hardware configuration options.
+  This is because there is no concept of hardwareId or hardware profile names in Softlayer. 
+  An example value is `hardwareId: "cpu=1,memory=1024,disk=25,type=LOCAL"`.
+
+* The `imageId` is the [Image template](https://knowledgelayer.softlayer.com/learning/introduction-image-templates).
+  For example, `imageId: CENTOS_6_64`.
+
+
+### VLAN Selection
+
+SoftLayer may provision VMs in different VLANs, even within the same region.
+Some applications require VMs to be on the *same* internal subnet; blueprints
+for these can specify this behaviour in SoftLayer in one of two ways.
+
+The VLAN ID can be set explicitly using the fields
+`primaryNetworkComponentNetworkVlanId` and
+`primaryBackendNetworkComponentNetworkVlanId` of `SoftLayerTemplateOptions`
+when specifying the location being used in the blueprint, as follows:
+
+    location:
+      jclouds:softlayer:
+        region: ams01
+        templateOptions:
+          # Enter your preferred network IDs
+          primaryNetworkComponentNetworkVlanId: 1153481
+          primaryBackendNetworkComponentNetworkVlanId: 1153483
+
+This method requires that a VM already exist and you look up the IDs of its
+VLANs, for example in the SoftLayer console UI, and that subsequently at least
+one VM in that VLAN is kept around.  If all VMs on a VLAN are destroyed
+SoftLayer may destroy the VLAN.  Creating VLANs directly and then specifying
+them as IDs here may not work.  Add a line note
+
+The second method tells Brooklyn to discover VLAN information automatically: it
+will provision one VM first, and use the VLAN information from it when
+provisioning subsequent machines. This ensures that all VMs are on the same
+subnet without requiring any manual VLAN referencing, making it very easy for
+end-users.
+
+To use this method, we tell brooklyn to use `SoftLayerSameVlanLocationCustomizer`
+as a location customizer.  This can be done on a location as follows:
+
+    location:
+      jclouds:softlayer:
+        region: lon02
+        customizers:
+        - $brooklyn:object:
+            type: org.apache.brooklyn.location.jclouds.softlayer.SoftLayerSameVlanLocationCustomizer
+        softlayer.vlan.scopeUid: "my-custom-scope"
+        softlayer.vlan.timeout: 10m
+
+Usually you will want the scope to be unique to a single application, but if you
+need multiple applications to share the same VLAN, simply configure them with
+the same scope identifier.
+
+It is also possible with many blueprints to specify this as one of the
+`provisioning.properties` on an *application*:
+
+    services:
+    - type: org.apache.brooklyn.entity.stock.BasicApplication
+      id: same-vlan-application
+      brooklyn.config:
+        provisioning.properties:
+          customizers:
+          - $brooklyn:object:
+              type: org.apache.brooklyn.location.jclouds.softlayer.SoftLayerSameVlanLocationCustomizer
+        softlayer.vlan.scopeUid: "my-custom-scope"
+        softlayer.vlan.timeout: 10m
+
+If you are writing an entity in Java, you can also use the helper
+method `forScope(String)` to create the customizer. Configure the
+provisioning flags as follows:
+
+    JcloudsLocationCustomizer vlans = SoftLayerSameVlanLocationCustomizer.forScope("my-custom-scope");
+    flags.put(JcloudsLocationConfig.JCLOUDS_LOCATION_CUSTOMIZERS.getName(), ImmutableList.of(vlans));
+
+
+### Configuration Options
+
+The allowed configuration keys for the `SoftLayerSameVlanLocationCustomizer`
+are:
+
+-   **softlayer.vlan.scopeUid** The scope identifier for locations whose
+    VMs will have the same VLAN.
+
+-   **softlayer.vlan.timeout** The amount of time to wait for a VM to
+    be configured before timing out without setting the VLAN ids.
+
+-   **softlayer.vlan.publicId** A specific public VLAN ID to use for
+    the specified scope.
+
+-   **softlayer.vlan.privateId** A specific private VLAN ID to use for
+    the specified scope.
+
+An entity being deployed to a customized location will have the VLAN ids set as
+sensors, with the same names as the last two configuration keys.
+
+***NOTE*** If the SoftLayer location is already configured with specific VLANs
+then this customizer will have no effect.
+
+
+

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/1330dcd3/guide/locations/_inheritance-and-named-locations.md
----------------------------------------------------------------------
diff --git a/guide/locations/_inheritance-and-named-locations.md b/guide/locations/_inheritance-and-named-locations.md
new file mode 100644
index 0000000..bf237f3
--- /dev/null
+++ b/guide/locations/_inheritance-and-named-locations.md
@@ -0,0 +1,80 @@
+---
+section: Inheritance and Named Locations
+title: Named Locations
+section_type: inline
+section_position: 7
+---
+
+### Inheritance and Named Locations
+
+Named locations can be defined for commonly used groups of properties, 
+with the syntax `brooklyn.location.named.your-group-name.`
+followed by the relevant properties.
+These can be accessed at runtime using the syntax `named:your-group-name` as the deployment location.
+
+Some illustrative examples using named locations and
+showing the syntax and properties above are as follows:
+
+{% highlight bash %}
+# Production pool of machines for my application (deploy to named:prod1)
+brooklyn.location.named.prod1=byon:(hosts="10.9.1.1,10.9.1.2,produser2@10.9.2.{10,11,20-29}")
+brooklyn.location.named.prod1.user=produser1
+brooklyn.location.named.prod1.privateKeyFile=~/.ssh/produser_id_rsa
+brooklyn.location.named.prod1.privateKeyPassphrase=s3cr3tCOMPANYpassphrase
+
+# AWS using my company's credentials and image standard, then labelling images so others know they're mine
+brooklyn.location.named.company-jungle=jclouds:aws-ec2:us-west-1
+brooklyn.location.named.company-jungle.identity=BCDEFGHIJKLMNOPQRSTU  
+brooklyn.location.named.company-jungle.privateKeyFile=~/.ssh/public_clouds/company_aws_id_rsa
+brooklyn.location.named.company-jungle.imageId=ami-12345
+brooklyn.location.named.company-jungle.minRam=2048
+brooklyn.location.named.company-jungle.userMetadata=application=my-jungle-app,owner="Bob Johnson"
+brooklyn.location.named.company-jungle.machineCreateAttempts=2
+
+brooklyn.location.named.AWS\ Virginia\ Large\ Centos = jclouds:aws-ec2
+brooklyn.location.named.AWS\ Virginia\ Large\ Centos.region = us-east-1
+brooklyn.location.named.AWS\ Virginia\ Large\ Centos.imageId=us-east-1/ami-7d7bfc14
+brooklyn.location.named.AWS\ Virginia\ Large\ Centos.user=root
+brooklyn.location.named.AWS\ Virginia\ Large\ Centos.minRam=4096
+{% endhighlight %}
+
+Named locations can refer to other named locations using `named:xxx` as their value.
+These will inherit the configuration and can override selected keys.
+Properties set in the namespace of the provider (e.g. `b.l.jclouds.aws-ec2.KEY=VALUE`)
+will be inherited by everything which extends AWS
+Sub-prefix strings are also inherited up to `brooklyn.location.*`, 
+except that they are filtered for single-word and other
+known keys 
+(so that we exclude provider-scoped properties when looking at sub-prefix keys).
+The precedence for configuration defined at different levels is that the value
+defined in the most specific context will apply.
+
+This is rather straightforward and powerful to use,
+although it sounds rather more complicated than it is!
+The examples below should make it clear.
+You could use the following to install
+a public key on all provisioned machines,
+an additional public key in all AWS machines, 
+and no extra public key in `prod1`: 
+
+<!-- tested in JcloudsLocationResolverTest -->
+{% highlight bash %}
+brooklyn.location.extraSshPublicKeyUrls=http://me.com/public_key
+brooklyn.location.jclouds.aws-ec2.extraSshPublicKeyUrls="[ \"http://me.com/public_key\", \"http://me.com/aws_public_key\" ]"
+brooklyn.location.named.prod1.extraSshPublicKeyUrls=
+{% endhighlight %}
+
+And in the example below, a config key is repeatedly overridden. 
+Deploying `location: named:my-extended-aws` will result in an `aws-ec2` machine in `us-west-1` (by inheritance)
+with `VAL6` for `KEY`:
+  
+{% highlight bash %}
+brooklyn.location.KEY=VAL1
+brooklyn.location.jclouds.KEY=VAL2
+brooklyn.location.jclouds.aws-ec2.KEY=VAL3
+brooklyn.location.jclouds.aws-ec2@us-west-1.KEY=VAL4
+brooklyn.location.named.my-aws=jclouds:aws-ec2:us-west-1
+brooklyn.location.named.my-aws.KEY=VAL5
+brooklyn.location.named.my-extended-aws=named:my-aws
+brooklyn.location.named.my-extended-aws.KEY=VAL6
+{% endhighlight %}
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/1330dcd3/guide/locations/_localhost.md
----------------------------------------------------------------------
diff --git a/guide/locations/_localhost.md b/guide/locations/_localhost.md
new file mode 100644
index 0000000..d2daf33
--- /dev/null
+++ b/guide/locations/_localhost.md
@@ -0,0 +1,48 @@
+---
+section: Localhost
+section_position: 10
+section_type: inline
+---
+
+### Localhost
+
+If passwordless ssh login to `localhost` and passwordless `sudo` is enabled on your 
+machine, you should be able to deploy some blueprints with no special configuration,
+just by specifying `location: localhost` in YAML.
+
+If you use a passphrase or prefer a different key, these can be configured as follows:
+
+    location:
+      localhost:
+        privateKeyFile=~/.ssh/brooklyn_key
+        privateKeyPassphrase=s3cr3tPASSPHRASE
+
+
+Alternatively, you can create a specific localhost location through the location wizard tool available within the web console.
+This location will be saved as a [catalog entry]({{ site.path.guide }}/blueprints/catalog/index.html#locations-in-the-catalog) 
+for easy reusability.
+
+
+#### Passwordless Sudo
+
+If you encounter issues or for more information, see [SSH Keys Localhost Setup](#localhost-setup). 
+
+For some blueprints, passwordless sudo is required. (Try executing `sudo whoami` to see if it prompts for a password. 
+To enable passwordless `sudo` for your account, a line must be added to the system `/etc/sudoers` file.  
+To edit the file, use the `visudo` command:
+
+{% highlight bash %}
+sudo visudo
+{% endhighlight %}
+
+Add this line at the bottom of the file, replacing `username` with your own user:
+
+{% highlight bash %}
+username ALL=(ALL) NOPASSWD: ALL
+{% endhighlight %}
+
+If executing the following command does not ask for your password, then `sudo` has been setup correctly:
+
+{% highlight bash %}
+sudo whoami
+{% endhighlight %}

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/1330dcd3/guide/locations/_openstack.md
----------------------------------------------------------------------
diff --git a/guide/locations/_openstack.md b/guide/locations/_openstack.md
new file mode 100644
index 0000000..942eaa5
--- /dev/null
+++ b/guide/locations/_openstack.md
@@ -0,0 +1,269 @@
+---
+section: OpenStack
+title: OpenStack
+section_type: inline
+section_position: 7
+---
+
+## OpenStack
+
+### Apache jclouds
+
+Support for OpenStack is provided by Apache jclouds. For more information, see their guide
+[here](https://jclouds.apache.org/guides/openstack/).
+
+
+### Connection Details
+
+The endpoint URI is that of keystone (normally on port 5000).
+
+The identity normally consists of a colon-separated tenant and username. The credential is 
+the password. For example:
+
+    location:
+      jclouds:openstack-nova:
+        endpoint: http://x.x.x.x:5000/v2.0/
+        identity: "your-tenant:your-username"
+        credential: your-password
+
+OpenStack Nova access information can be downloaded from the openstack web interface, for example 
+as an openrc.sh file. It is usually available from API Access tab in "Access & Security" section.
+This file will normally contain the identity and credential.
+
+Users are strongly recommended to use 
+[externalized configuration]({{ site.path.guide }}/ops/externalized-configuration.html) for better
+credential management, for example using [Vault](https://www.vaultproject.io/).
+
+
+### Common Configuration Options
+
+Below are examples of configuration options that use values specific to OpenStack environments:
+
+* The `imageId` is the id of an image. For example,
+  `imageId: RegionOne/08086159-8b0b-4970-b332-a7a929ee601f`.
+  These ids can be found from the the CLI or the web-console, for example in IBM Blue Box London, 
+  the URL is https://tenant-region.openstack.blueboxgrid.com/project/images/.
+
+* The `hardwareId` is the [flavor id](http://docs.openstack.org/admin-guide/compute-flavors.html).
+  For example `hardwareId: RegionOne/1`. These ids can be found from the the CLI or the web-console,
+  for example in IBM Blue Box, the URL is https://tenant-region.openstack.blueboxgrid.com/admin/flavors/.
+
+The default flavors are shown below (though the set of flavors can be 
+[managed by the admin](http://docs.openstack.org/admin-guide/cli_manage_flavors.html)):
+
+    +-----+-----------+-----------+------+
+    | ID  | Name      | Memory_MB | Disk |
+    +-----+-----------+-----------+------+
+    | 1   | m1.tiny   | 512       | 1    |
+    | 2   | m1.small  | 2048      | 20   |
+    | 3   | m1.medium | 4096      | 40   |
+    | 4   | m1.large  | 8192      | 80   |
+    | 5   | m1.xlarge | 16384     | 160  |
+    +-----+-----------+-----------+------+
+
+For further configuration options, consult 
+[jclouds Nova template options](https://jclouds.apache.org/reference/javadoc/2.0.x/org/jclouds/openstack/nova/v2_0/compute/options/NovaTemplateOptions.html).
+These can be used with the **[templateOptions](#custom-template-options)** configuration option.
+
+
+### Networks
+
+When multiple networks are available you should indicate which ones machines should join.
+Do this by setting the desired values id as an option in the
+**[templateOptions](#custom-template-options)** configuration:
+
+    location:
+      jclouds:openstack-nova:
+        ...
+        templateOptions:
+          # Assign the node to all networks in the list.
+          networks:
+          - network-one-id
+          - network-two-id
+          - ...
+
+
+### Floating IPs
+
+The `autoAssignFloatingIp` option means that a [floating ip](https://www.mirantis.com/blog/configuring-floating-ip-addresses-networking-openstack-public-private-clouds/)
+will be assigned to the VM at provision-time.
+
+A floating IP pool name can also be specified. If not set, a floating IP from any available pool will be chosen.
+This is set using the [template option](#custom-template-options). For example:
+
+    location:
+      jclouds:openstack-nova:
+        ...
+        autoAssignFloatingIp: true
+        templateOptions:
+          # Pool names to use when allocating a floating IP
+          floatingIpPoolNames:
+          - "pool name"
+
+
+### Basic Location Structure
+
+This is a basic inline YAML template for an OpenStack location:
+
+    location:
+        jclouds:openstack-nova:
+            endpoint: http://x.x.x.x:5000/v2.0/
+            identity: "your-tenant:your-username"
+            credential: your-password
+
+            # imageId, hardwareId, and loginUser* are optional
+            imageId: your-region-name/your-image-id
+            hardwareId: your-region-name/your-flavor-id
+            loginUser: 'ubuntu'
+            loginUser.privateKeyFile: /path/to/your/privatekey
+
+            jclouds.openstack-nova.auto-generate-keypairs: false
+            jclouds.openstack-nova.auto-create-floating-ips: true
+
+            templateOptions:
+                networks: [ "your-network-id" ]
+                floatingIpPoolNames: [ "your-floatingIp-pool" ]
+                securityGroups: ['your-security-group']
+
+                # Optional if 'jclouds.openstack-nova.auto-generate-keypairs' is assigned to 'true'
+                keyPairName: "your-keypair"
+
+This is the same OpenStack location in a format that can be added to your
+`brooklyn.properties` file:
+
+    brooklyn.location.named.My\ OpenStack=jclouds:openstack-nova:http://x.x.x.x:5000/v2.0/
+    brooklyn.location.named.My\ OpenStack.identity=your-tenant:your-username
+    brooklyn.location.named.My\ OpenStack.credential=your-password
+    brooklyn.location.named.My\ OpenStack.endpoint=http://x.x.x.x:5000/v2.0/
+
+    brooklyn.location.named.My\ OpenStack.imageId=your-region-name/your-image-id
+    brooklyn.location.named.My\ OpenStack.hardwareId=your-region-name/your-flavor-id
+    brooklyn.location.named.My\ OpenStack.loginUser=ubuntu
+    brooklyn.location.named.My\ OpenStack.loginUser.privateKeyFile=/path/to/your/privatekey
+    brooklyn.location.named.My\ OpenStack.openstack-nova.auto-generate-keypairs=false
+    brooklyn.location.named.My\ OpenStack.openstack-nova.auto-create-floating-ips=true
+
+    brooklyn.location.named.My\ OpenStack.networks=your-network-id
+    brooklyn.location.named.My\ OpenStack.floatingIpPoolNames=your-floatingIp-pool
+    brooklyn.location.named.My\ OpenStack.securityGroups=your-security-group
+    brooklyn.location.named.My\ OpenStack.keyPair=your-keypair
+
+
+### Troubleshooting
+
+#### Cloud Credentials Failing
+
+If the cloud API calls return `401 Unauthorized` (e.g. in a `org.jclouds.rest.AuthorizationException`),
+then this could be because the credentials are incorrect.
+
+A good way to check this is to try the same credentials with the 
+[OpenStack nova command line client](http://docs.openstack.org/user-guide/common/cli_install_openstack_command_line_clients.html).
+
+
+#### Unable to SSH: Wrong User
+
+If SSH authentication fails, it could be that the login user is incorrect. For most clouds, this 
+is inferred from the image metadata, but if no (or the wrong) login user is specified then it will  
+default to root. The correct login user can be specified using the configuration option `loginUser`.
+For example, `loginUser: ubuntu`.
+
+The use of the wrong login user can also result in the obscure message, caused by 
+an unexpected response saying to use a different user. For more technical information, see 
+this [sshj github issue](https://github.com/hierynomus/sshj/issues/75). The message is:
+
+    Received message too long 1349281121
+
+
+#### I Want to Use My Own KeyPair
+
+By default, jclouds will auto-generate a new [key pair](http://docs.openstack.org/user-guide/cli_nova_configure_access_security_for_instances.html)
+for the VM. This key pair will be deleted automatically when the VM is deleted.
+
+Alternatively, you can use a pre-existing key pair. If so, you must also specify the corresponding
+private key (pem file, or data) to be used for the initial login. The name used in the `keyPair` 
+configuration must match the name of a key pair that has already been added in OpenStack.
+For example:
+   
+    location:
+      jclouds:clouds:openstack-nova:
+        ...
+        jclouds.openstack-nova.auto-generate-keypairs: false
+        keyPair: "my-keypair"
+        loginUser: ubuntu
+        loginUser.privateKeyFile: /path/to/my/privatekey.pem
+
+
+#### Error "doesn't contain ... -----BEGIN"
+
+If using `loginUser.privateKeyFile` (or `loginUser.privateKeyData`), this is expected to be a .pem
+file. If a different format is used (e.g. a .ppk file), it will give an error like that below:
+
+    Error invoking start at EmptySoftwareProcessImpl{id=TrmhitVc}: chars
+    PuTTY-User-Key-File-2: ssh-rsa
+    ...
+    doesn't contain % line [-----BEGIN ]
+
+
+#### Warning Message: "Ignoring request to set..."
+
+If you see a warning log message like that below:
+
+    2016-06-23 06:05:12,297 WARN  o.a.b.l.j.JcloudsLocation [brooklyn-execmanager-XlwkWB3k-312]: 
+    Ignoring request to set template option loginUser because this is not supported by 
+    org.jclouds.openstack.nova.v2_0.compute.options.NovaTemplateOptions
+
+It can mean that the location configuration option is in the wrong place. The configuration under 
+`templateOptions` must correspond to those options on the
+[jclouds Nova template options](https://jclouds.apache.org/reference/javadoc/1.9.x/org/jclouds/openstack/nova/v2_0/compute/options/NovaTemplateOptions.html).
+However, template options such as `loginUser` are top-level configuration options that should not
+be inside the `templateOptions` section.
+
+
+#### HttpResponseException Accessing Compute Endpoint
+
+The Keystone endpoint is first queried to get the API access endpoints for the appropriate services.
+
+Some private OpenStack installs are (mis)configured such that the returned addresses are not always 
+directly accessible. It could be that the service is behind a VPN, or that they rely on hostnames
+that are only in a private DNS.
+
+You can find the service endpoints in OpenStack, either using the CLI or the web-console. For 
+example, in Blue Box the URL is https://tenant-region.openstack.blueboxgrid.com/project/access_and_security/.
+You can then check if the Compute service endpoint is directly reachable.
+
+
+#### VM Failing to Provision
+
+It can be useful to drop down to the OpenStack nova CLI, or to jclouds, to confirm that VM
+provisioning is working and to check which options are required.
+
+For example, try following [these jclouds instructions](https://github.com/jclouds/jclouds-examples/tree/master/compute-basics#your-own-openstack-nova).
+
+
+#### jclouds Namespace Issue
+
+A change to Nova's API (in the Mitaka release) resulted in all extensions having the same "fake" 
+namespace which the current version of jclouds does not yet support.
+
+If you are having problems deploying to OpenStack, consult your Brooklyn debug log and
+look for the following:
+
+    "namespace": "http://docs.openstack.org/compute/ext/fake_xml"
+
+If you already have `jclouds:openstack-mitaka-nova`, then try using this instead of the vanilla
+`jclouds:openstack-nova`. For example:
+
+    location:
+        jclouds:openstack-mitaka-nova:
+            endpoint: http://x.x.x.x:5000/v2.0/
+            identity: "your-tenant:your-username"
+            credential: your-password
+            templateOptions:
+                networks: [ "your-network-id" ]
+                floatingIpPoolNames: [ "your-floatingIp-pool" ]
+
+Note that the following values will be set by default when omitted above:
+
+    jclouds.keystone.credential-type=passwordCredentials
+    jclouds.openstack-nova.auto-generate-keypairs: true
+    jclouds.openstack-nova.auto-create-floating-ips: true

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/1330dcd3/guide/locations/_special-locations.md
----------------------------------------------------------------------
diff --git a/guide/locations/_special-locations.md b/guide/locations/_special-locations.md
new file mode 100644
index 0000000..32f628b
--- /dev/null
+++ b/guide/locations/_special-locations.md
@@ -0,0 +1,117 @@
+---
+section: Specialized Locations
+section_position: 11
+section_type: inline
+---
+
+### Specialized Locations
+
+Some additional location types are supported for specialized situations:
+
+#### Single Host
+
+The spec `host`, taking a string argument (the address) or a map (`host`, `user`, `password`, etc.),
+provides a convenient syntax when specifying a single host.
+For example:
+
+{% highlight yaml %}
+location: host:(192.168.0.1)
+services:
+- type: org.apache.brooklyn.entity.webapp.jboss.JBoss7Server
+{% endhighlight %}
+
+Or, in `brooklyn.properties`, set `brooklyn.location.named.host1=host:(192.168.0.1)`.
+
+
+#### The Multi Location
+
+The spec `multi` allows multiple locations, specified as `targets`,
+to be combined and treated as one location.
+
+##### Sequential Consumption
+
+In its simplest form, this will use the first target location where possible,
+and will then switch to the second and subsequent locations when there are no
+machines available.
+
+In the example below, it provisions the first node to `192.168.0.1`, then it provisions into AWS
+us-east-1 region (because the bring-your-own-nodes region will have run out of nodes).
+
+{% highlight yaml %}
+location:
+  multi:
+    targets:
+    - byon:(hosts=192.168.0.1)
+    - jclouds:aws-ec2:us-east-1
+services:
+- type: org.apache.brooklyn.entity.group.DynamicCluster
+  brooklyn.config:
+    cluster.initial.size: 3
+    dynamiccluster.memberspec:
+      $brooklyn:entitySpec:
+        type: org.apache.brooklyn.entity.machine.MachineEntity
+{% endhighlight %}
+
+##### Round-Robin Consumption and Availability Zones for Clustered Applications
+
+A `DynamicCluster` can be configured to cycle through its deployment targets round-robin when
+provided with a location that supports the `AvailabilityZoneExtension` -- the `multi` location
+supports this extension.
+
+The configuration option `dynamiccluster.zone.enable` on `DynamicCluster` tells it to query the
+given location for `AvailabilityZoneExtension` support. If the location supports it, then the
+cluster will query for the list of availability zones (which in this case is simply the list of
+targets) and deploy to them round-robin.
+
+In the example below, the cluster will request VMs round-robin across three different
+locations (in this case, the locations were already added to the catalog, or defined in
+`brooklyn.properties`).
+
+{% highlight yaml %}
+location:
+  multi:
+    targets:
+    - my-location-1
+    - my-location-2
+    - my-location-3
+services:
+- type: org.apache.brooklyn.entity.group.DynamicCluster
+  brooklyn.config:
+    dynamiccluster.zone.enable: true
+    cluster.initial.size: 3
+    dynamiccluster.memberspec:
+      $brooklyn:entitySpec:
+        type: org.apache.brooklyn.entity.machine.MachineEntity
+{% endhighlight %}
+
+Of course, clusters can also be deployed round-robin to real availability zones offered by
+cloud providers, as long as their locations support `AvailabilityZoneExtension`. Currently, only
+AWS EC2 locations support this feature.
+
+In the example below, the cluster will request VMs round-robin across the availability zones
+provided by AWS EC2 in the "us-east-1" region.
+
+{% highlight yaml %}
+location: jclouds:aws-ec2:us-east-1
+services:
+- type: org.apache.brooklyn.entity.group.DynamicCluster
+  brooklyn.config:
+    dynamiccluster.zone.enable: true
+    cluster.initial.size: 3
+    dynamiccluster.memberspec:
+      $brooklyn:entitySpec:
+        type: org.apache.brooklyn.entity.machine.MachineEntity
+{% endhighlight %}
+
+For more information about AWS EC2 availability zones, see
+[this guide](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html).
+
+Custom alternatives to round-robin are also possible using the configuration option
+`dynamiccluster.zone.placementStrategy` on `DynamicCluster`.
+
+
+#### The Server Pool
+
+The {% include java_link.html class_name="ServerPool" package_path="org/apache/brooklyn/entity/machine/pool" project_subpath="software/base" %}
+entity type allows defining an entity which becomes available as a location.
+

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/1330dcd3/guide/locations/_ssh-keys.md
----------------------------------------------------------------------
diff --git a/guide/locations/_ssh-keys.md b/guide/locations/_ssh-keys.md
new file mode 100644
index 0000000..acf30d7
--- /dev/null
+++ b/guide/locations/_ssh-keys.md
@@ -0,0 +1,88 @@
+---
+section: SSH Keys
+section_position: 9
+section_type: inline
+---
+
+### SSH Keys
+
+SSH keys are one of the simplest and most secure ways to access remote servers.
+They consist of two parts:
+
+* A private key (e.g. `id_rsa`) which is known only to one party or group
+  
+* A public key (e.g. `id_rsa.pub`) which can be given to anyone and everyone,
+  and which can be used to confirm that a party has a private key
+  (or has signed a communication with the private key)
+  
+In this way, someone -- such as you -- can have a private key,
+and can install a public key on a remote machine (in an `authorized_keys` file)
+for secure automated access.
+Commands such as `ssh` (and Brooklyn) can log in without
+revealing the private key to the remote machine,
+the remote machine can confirm it is you accessing it (if no one else has the private key),
+and no one snooping on the network can decrypt of any of the traffic.
+ 
+
+#### Creating an SSH Key
+
+If you don't have an SSH key, create one with:
+
+{% highlight bash %}
+$ ssh-keygen -t rsa -N "" -f ~/.ssh/id_rsa
+{% endhighlight %}
+
+
+#### Localhost Setup
+
+If you want to deploy to `localhost`, ensure that you have a public and private key,
+and that your key is authorized for ssh access:
+
+{% highlight bash %}
+# _Appends_ id_rsa.pub to authorized_keys. Other keys are unaffected.
+$ cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys
+{% endhighlight %}
+
+Now verify that your setup by running the command: `ssh localhost echo hello world`
+
+If your setup is correct, you should see `hello world` printed back at you.
+
+On the first connection, you may see a message similar to this:
+
+<pre>
+The authenticity of host 'localhost (::1)' can't be established.
+RSA key fingerprint is 7b:e3:8e:c6:5b:2a:05:a1:7c:8a:cf:d1:6a:83:c2:ad.
+Are you sure you want to continue connecting (yes/no)?
+</pre>
+
+Simply answer 'yes' and then repeat the command again.
+
+If this isn't the case, see below. 
+
+
+
+
+#### Potential Problems
+
+* **MacOS user?** In addition to the above, enable "Remote Login" in "System Preferences > Sharing".
+
+* **Got a passphrase?** Set `brooklyn.location.localhost.privateKeyPassphrase`
+  as described [here](index.html#os-setup).
+  If you're not sure, or you don't know what a passphrase is, you can test this by executing `ssh-keygen -y`.
+  If it does *not* ask for a passphrase, then your key has no passphrase.
+  If your key does have a passphrase, you can remove it by running `ssh-keygen -p`.
+
+* Check that you have an `~/.ssh/id_rsa` file (or `id_dsa`) and a corresponding public key with a `.pub` extension;
+  if not, create one as described above
+  
+* `~/.ssh/` or files in that directory may have permissions they shouldn't: 
+  they should be visible only to the user (apart from public keys),
+  both on the source machine and the target machine.
+  You can verify this with `ls -l ~/.ssh/`:  lines should start with `-rw-------` or `-r--------` (or `-rwx------` for directories). 
+  If it does not, execute `chmod go-rwx ~/.ssh ~/.ssh/*`.
+ 
+* Sometimes machines are configured with different sets of support SSL/TLS versions and ciphers;
+  if command-line `ssh` and `scp` work, but Brooklyn/java does not, check the versions enabled in Java and on both servers.
+
+* Missing entropy: creating and using ssh keys requires randomness available on the servers,
+  usually in `/dev/random`; see [here]({{ site.path.guide }}/ops/troubleshooting/increase-entropy.html) for more information

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/1330dcd3/guide/locations/cloud-credentials.md
----------------------------------------------------------------------
diff --git a/guide/locations/cloud-credentials.md b/guide/locations/cloud-credentials.md
new file mode 100644
index 0000000..36041e0
--- /dev/null
+++ b/guide/locations/cloud-credentials.md
@@ -0,0 +1,6 @@
+---
+title: More Clouds
+layout: website-normal
+---
+
+This page has moved. See [More Clouds](index.html#more-details-on-specific-clouds) instead.

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/1330dcd3/guide/locations/index.md
----------------------------------------------------------------------
diff --git a/guide/locations/index.md b/guide/locations/index.md
new file mode 100644
index 0000000..328eed2
--- /dev/null
+++ b/guide/locations/index.md
@@ -0,0 +1,21 @@
+---
+title: Locations
+layout: website-normal
+children:
+- { path: location-customizers.md, section_position: 8 }
+check_directory_for_children: true
+---
+
+Locations are the environments to which Brooklyn deploys applications. Most commonly these 
+are cloud services such as AWS, GCE, and IBM Softlayer. Brooklyn also supports deploying 
+to a pre-provisioned network or to localhost (primarily useful for testing blueprints).
+
+See also:
+
+* The [Locations yaml guide]({{ site.path.guide }}/blueprints/setting-locations.html)
+* Use within an entity of the configuration option 
+  [provisioning.properties]({{ site.path.guide }}/blueprints/entity-configuration.html#entity-provisioningproperties-overriding-and-merging)
+* How to add location definitions to the [Catalog]({{ site.path.guide }}/blueprints/catalog/); and 
+* How to use [Externalized Configuration]({{ site.path.guide }}/ops/externalized-configuration.html).
+
+{% child_content %}

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/1330dcd3/guide/locations/location-customizers.md
----------------------------------------------------------------------
diff --git a/guide/locations/location-customizers.md b/guide/locations/location-customizers.md
new file mode 100644
index 0000000..405bb14
--- /dev/null
+++ b/guide/locations/location-customizers.md
@@ -0,0 +1,169 @@
+---
+title: Location Customizers
+layout: website-normal
+---
+
+Apache Brooklyn supports a number of ways to configure and customize locations. These include
+the `JcloudsLocationCustomizer`, which is for advanced customization of VM provisioning through jclouds.
+There is also a `MachineLocationCustomizer`, which allows customization of machines being obtained 
+from any kind of location (including [Bring Your Own Nodes](index.html#byon)).
+
+
+## Usage Guidelines
+
+Clearly there is an overlap for where things can be done. This section describes the recommended  
+separation of responsibilities.
+
+These are guidelines only - users are obviously free to make alternative usage decisions based on 
+their particular use-cases.
+
+### Responsibilities of Entity versus Location
+
+From an entity's perspective, it calls `location.obtain(options)` and gets back a usable 
+`MachineLocation` that has a standard base operating system that gives remote access
+(e.g. for Linux it expects credentials for a user with `sudo` rights, and ssh access).
+
+However, there are special cases - for example the `location.obtain(options)` could return
+a Docker container with the software pre-installed, and no remote access (see the 
+[Clocker project](http://clocker.io) for more information on use of Docker with Brooklyn).
+
+The entity is then responsible for configuring that machine according to the needs of the software 
+to be installed.
+
+For example, the entity may install software packages, upload/update configuration files, launch
+processes, etc.
+
+The entity may also configure `iptables`. This is also possible through the `JcloudsLocation` 
+configuration. However, it is preferable to do this in the entity because it is part of 
+configuring the machine in the way required for the given software component.
+
+The entity may also perform custom OS setup, such as installing security patches. However, whether 
+this is appropriate depends on the nature of the security patch: if the security patch is specific 
+to the entity type, then it should be done within the entity; but if it is to harden the base OS 
+to make it comply with an organisation's standards (e.g. to overcome shortcomings of the base 
+image, or to install security patches) then a `MachineLocationCustomizer` is more appropriate.
+
+### Location Configuration Options
+
+This refers to standard location configuration: explicit config keys, and explicit jclouds template 
+configuration that can be passed through.
+
+This kind of configuration is simplest to use. It is the favoured mechanism when it comes to VM 
+provisioning, and should be used wherever possible.
+
+Note that a jclouds `TemplateBuilder` and cloud-specific `TemplateOptions` are the generic mechanisms 
+within jclouds for specifying the details of the compute resource to be provisioned.
+
+### Jclouds Location Customizer 
+A `JcloudsLocationCustomizer` has customization hooks to execute code at the various points of building 
+up the jclouds template and provisioning the machine. Where jclouds is being used and where the required 
+use of jclouds goes beyond simple configuration, this is an appropriate solution.
+
+For example, there is a `org.apache.brooklyn.location.jclouds.networking.JcloudsLocationSecurityGroupCustomizer`
+which gives more advanced support for setting up security groups (e.g. in AWS-EC2).
+
+### Machine Customizer
+
+The `MachineLocationCustomizer` allows customization of machines being obtained from any kind of location.
+For example, this includes for jclouds and for Bring Your Own Nodes (BYON).
+
+It provides customization hooks for when the machine has been provisioned (before it is returned by the location)
+and when the machine is about to be released by the location.
+
+An example use would be to register (and de-register) the machine in a CMDB.
+
+
+## Jclouds Location Customizers
+
+*Warning: additional methods (i.e. customization hooks) may be added to the `JcloudsLocationCustomizer` 
+interface in future releases. Users are therefore strongly encouraged to sub-class 
+`BasicJcloudsLocationCustomizer`, rather than implementing JcloudsLocationCustomizer directly.*
+
+The `JcloudsLocationCustomizer` provides customization hooks at various points of the Brooklyn's
+use of jclouds. These can be used to adjust the configuration, to do additional setup, to do
+custom logging, etc.
+
+* Customize the `org.jclouds.compute.domain.TemplateBuilder`, before it is used to build the template.
+  This is used to influence the choice of VM image, hardware profile, etc. This hook is not normally
+  required as the location configuration options can be used in instead.
+
+* Customize the `org.jclouds.compute.domain.Template`, to be used when creating the machine. This  
+  hook is most often used for performing custom actions - for example to create or modify a security 
+  group or volume, and to update the template's options to use that.
+
+* Customize the `org.jclouds.compute.options.TemplateOptions` to be used when creating the machine.
+  The `TemplateOptions` could be cast to a cloud-specific sub-type (if this does not have to work
+  across different clouds). Where the use-case is to just set simple configuration on the 
+  `TemplateOptions`, consider instead using the config key `templateOptions`, which takes a map
+  of type String to Object - the strings should match the method names in the `TemplateOptions`.
+
+* Customize the `org.apache.brooklyn.location.jclouds.JcloudsMachineLocation` that has been 
+  created. For Linux-based VMs, if the config `waitForSshable` was not false, then this machine
+  is guaranteed to be ssh'able. Similarly for WinRM access to Windows machines, if 
+  `waitForWinRmAvailable` was not false.
+
+* Pre-release of the machine. If the actions required are specific to jclouds (e.g. using jclouds 
+  to make calls to the cloud provider) then this should be used; otherwise one should use the more
+  generic `MachineLocationCustomizer`.
+
+* Post-release of the machine (i.e. after asking jclouds to destroying the machine).
+
+To register a `JcloudsLocationCustomizer` in YAML, the config key `customizers` can be used to 
+provide a list of instances. Each instance can be defined using `$brooklyn:object` to indicate 
+the type and its configuration. For example:
+
+    location:
+      jclouds:aws-ec2:us-east-1:
+        customizers:
+        - $brooklyn:object:
+            type: com.acme.brooklyn.MyJcloudsLocationCustomizer
+
+To register `JcloudsLocationCustomizer` instances programmatically, set the config key
+`JcloudsLocationConfig.JCLOUDS_LOCATION_CUSTOMIZERS` on the location, or pass this 
+config option when calling `location.obtain(options)`.
+
+
+The `SharedLocationSecurityGroupCustomizer` configures a shared security group on Jclouds locations.
+It only works on AWS and Azure ARM.
+
+To register a `SharedLocationSecurityGroupCustomizer` in YAML, you can use the config key `customizers`
+and configure it with `$brooklyn:object` and `object.fields`. For example:
+
+    location:
+      jclouds:aws-ec2:us-east-1:
+        customizers:
+        - $brooklyn:object:
+            type: org.apache.brooklyn.location.jclouds.networking.SharedLocationSecurityGroupCustomizer
+            object.fields: {locationName: "myloc", tcpPortRanges: ["22", "8080", "9443"], udpPortRanges: ["2001", "4013"], cidr: "82.40.153.101/24"}
+
+where `cidr` can be optionally set to restrict the range that the ports that are to be opened can be accessed from.
+
+
+
+## Machine Location Customizers
+
+*Warning: additional methods (i.e. customization hooks) may be added to the `MachineLocationCustomizer` 
+interface in future releases. Users are therefore strongly encouraged to sub-class 
+`BasicMachineLocationCustomizer`, rather than implementing `MachineLocationCustomizer` directly.*
+
+The `MachineLocationCustomizer` provides customization hooks for when a machine is obtained/released 
+from a `MachineProvisioningLocation`. The following hooks are supported: 
+
+* After the machine has been provisioned/allocated, but before it has been returned.
+
+* When the machine is about to be released, but prior to actually destroying/unallocating the
+  machine.
+
+To register a `MachineLocationCustomizer` in YAML, the config key `machineCustomizers` can be used  
+to provide a list of instances. Each instance can be defined using `$brooklyn:object` to indicate 
+the type and its configuration. For example:
+
+    location:
+      jclouds:aws-ec2:us-east-1:
+        machineCustomizers:
+        - $brooklyn:object:
+            type: com.acme.brooklyn.MyMachineLocationCustomizer
+
+To register `MachineLocationCustomizer` instances programmatically, set the config key
+`CloudLocationConfig.MACHINE_LOCATION_CUSTOMIZERS` on the location, or pass this 
+config option when calling `location.obtain(options)`.

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/1330dcd3/guide/ops/brooklyn_properties.md
----------------------------------------------------------------------
diff --git a/guide/ops/brooklyn_properties.md b/guide/ops/brooklyn_properties.md
index 87ce641..9d849b7 100644
--- a/guide/ops/brooklyn_properties.md
+++ b/guide/ops/brooklyn_properties.md
@@ -74,7 +74,7 @@ example.property=$brooklyn:literal("$brooklyn:myexample")
 
 ## Locations
 
-Information on defining locations in the `brooklyn.properties` file is available [here]({{ site.path.guide }}/ops/locations/).
+Information on defining locations in the `brooklyn.properties` file is available [here]({{ site.path.guide }}/locations/).
 
 
 ## Java
@@ -204,7 +204,7 @@ brooklyn.entitlements.perUser.metrics=minimal
 {% endhighlight %}
 
 For more information, see 
-[Java: Entitlements]({{ site.path.guide }}/java/entitlements.html).
+[Java: Entitlements]({{ site.path.guide }}/blueprints/java/entitlements.html).
 or
 {% include java_link.html class_name="EntitlementManager" package_path="org/apache/brooklyn/api/mgmt/entitlement" project_subpath="api" %}.
 

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/1330dcd3/guide/ops/catalog/images/add-to-catalog.png
----------------------------------------------------------------------
diff --git a/guide/ops/catalog/images/add-to-catalog.png b/guide/ops/catalog/images/add-to-catalog.png
deleted file mode 100644
index 0565e7e..0000000
Binary files a/guide/ops/catalog/images/add-to-catalog.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/1330dcd3/guide/ops/catalog/index.md
----------------------------------------------------------------------
diff --git a/guide/ops/catalog/index.md b/guide/ops/catalog/index.md
deleted file mode 100644
index 355e84b..0000000
--- a/guide/ops/catalog/index.md
+++ /dev/null
@@ -1,400 +0,0 @@
----
-title: Catalog
-layout: website-normal
-children:
-- { section: General YAML Schema }
-- { section: Catalog Metadata }
-- { section: Catalog YAML Examples }
-- { section: Templates and the Add-Application Wizard, title: Templates }
-- { section: Adding to the Catalog, title: Adding and Deleting } 
-- { section: Versioning } 
-- { section: CLI Options }
- 
----
-
-Apache Brooklyn provides a **catalog**, which is a persisted collection of versioned blueprints 
-and other resources. A set of blueprints is loaded from the `default.catalog.bom` in the Brooklyn 
-folder by default and additional ones can be added through the web console or CLI.  Blueprints in 
-the catalog can be deployed directly, via the Brooklyn CLI or the web console, or referenced in 
-other blueprints using their `id`.
-
- 
-### Catalog Items YAML Syntax
-
-An item or items to be added to the catalog is defined by a YAML file,
-specifying the catalog metadata for the items and the actual blueprint or resource definition.
-
-
-#### General YAML Schema
-
-Catalog items can be defined using the general structure below:
-
-~~~ yaml
-brooklyn.catalog:
-  <catalog-metadata>
-  items:
-  - <additional-catalog-metadata>
-    item:
-      <blueprint-or-resource-definition>
-  - <additional-catalog-metadata>
-    item:
-      <blueprint-or-resource-definition>
-~~~ 
- 
-Alternatively, a single catalog item can be defined using the following general structure:
-
-~~~ yaml
-brooklyn.catalog:
-  <catalog-metadata>
-  item:
-    <blueprint-or-resource-definition>
-~~~ 
-
-For example, the YAML below adds to the catalog a Tomcat entity with some additional default 
-configuration:
-
-~~~ yaml
-brooklyn.catalog:
-  items:
-  - id: tomcat-server
-    version: "1.0.0"
-    itemType: entity
-    item:
-      type: org.apache.brooklyn.entity.webapp.tomcat.Tomcat8Server
-      brooklyn.config:
-        webapp.enabledProtocols: https
-        httpsSsl:
-          url: classpath://org/apache/brooklyn/entity/webapp/sample-java-keystore.jks
-          alias: myname
-          password: mypass
-~~~ 
-
-
-#### Catalog Metadata
-
-Catalog metadata fields supply the additional information required in order to register an item in the catalog. 
-These fields can be supplied as `key: value` entries 
-where either the `<catalog-metadata>` or `<additional-catalog-metadata>` placeholders are,
-with the latter overriding the former unless otherwise specified below.
-
-The following metadata is *required* for all items:
-
-- `id`: a human-friendly unique identifier for how this catalog item will be referenced from blueprints
-- `version`: multiple versions of a blueprint can be installed and used simultaneously;
-  this field disambiguates between blueprints of the same `id`.
-  Note that this is typically *not* the version of the software being installed,
-  but rather the version of the blueprint. For more information on versioning, see below.
-  (Also note YAML treats numbers differently to Strings. Explicit quotes are recommended, to avoid 
-  `1.10` being interpretted as the number `1.1`.)
-- `itemType`: the type of the item being defined. The supported item types are:
-  - `entity`
-  - `template`
-  - `policy`
-  - `location`
-
-To reference a catalog item in another blueprint, simply reference its ID and optionally its version number.
-For instance, if we've added an item with metadata `{ id: datastore, version: "1.0" }` (such as the example below),
-we could refer to it in another blueprint with: 
-
-~~~ yaml
-services:
-- type: datastore:1.0
-~~~ 
-
-In addition to the above fields, exactly **one** of the following is also required:
-
-- `item`: the YAML for an entity, or policy, or location specification 
-  (a map containing `type` and optional `brooklyn.config`). For a "template" item, it
-  should be a map containing `services` (i.e. the usual YAML format for a full application
-  blueprint). **Or**
-- `items`: a list of catalog items, where each entry in the map follows the same schema as
-  the `brooklyn.catalog` value, and the keys in these map override any metadata specified as
-  a sibling of this `items` key (or, in the case of `brooklyn.libraries` they add to the list);
-  if there are references between items, then order is important:
-  `items` are processed in order, depth-first, and forward references are not supported. Entries
-  can be URL to another catalog file to include, inheriting the metadata from the current hierarchy.
-  Libraries defined so far in the metadata will be used to load classpath entries. For example:
-
-~~~ yaml
-brooklyn.catalog:
-  brooklyn.libraries:
-  - http://some.server.or.other/path/my.jar
-  items:
-  - classpath://my-catalog-entries-inside-jar.bom
-  - some-property: value
-    include: classpath://more-catalog-entries-inside-jar.bom
-  - id: use-from-my-catalog
-    version: "1.0.0"
-    itemType: entity
-    item:
-      type: some-type-defined-in-my-catalog-entries
-      brooklyn.config:
-        some.config: "some value"
-~~~
-
-The following optional catalog metadata is supported:
-  
-- `name`: a nicely formatted display name for the item, used when presenting it in a GUI.
-- `description`: supplies an extended textual description for the item.
-- `iconUrl`: points to an icon for the item, used when presenting it in a GUI.
-  The URL prefix `classpath` is supported but these URLs may *not* refer to resources in any OSGi 
-  bundle in the `brooklyn.libraries` section (to prevent requiring all OSGi bundles to be loaded 
-  at launch). Icons are instead typically installed either at the web server from which the OSGi 
-  bundles or catalog items are supplied or in the `conf` folder of the Brooklyn distro.
-- `scanJavaAnnotations` [experimental; deprecated]: if provided (as `true`), this will scan any 
-  locally provided library URLs for types annotated `@Catalog` and extract metadata to include 
-  them as catalog items. If no libraries are specified this will scan the default classpath.
-  This feature will likely be removed.
-  Also note that external OSGi dependencies are not supported 
-  and other metadata (such as versions, etc) may not be applied.
-- `brooklyn.libraries`: a list of pointers to OSGi bundles required for the catalog item.
-  This can be omitted if blueprints are pure YAML and everything required is included in the classpath and catalog.
-  Where custom Java code or bundled resources is needed, however, OSGi JARs supply
-  a convenient packaging format and a very powerful versioning format.
-  Libraries should be supplied in the form 
-  `brooklyn.libraries: [ "http://...", "http://..." ]`, 
-  or as
-  `brooklyn.libraries: [ { name: symbolic-name, version: "1.0", url: http://... }, ... ]` if `symbolic-name:1.0` 
-  might already be installed from a different URL and you want to skip the download.
-  Note that these URLs should point at immutable OSGi bundles;
-  if the contents at any of these URLs changes, the behaviour of the blueprint may change 
-  whenever a bundle is reloaded in a Brooklyn server,
-  and if entities have been deployed against that version, their behavior may change in subtle or potentially incompatible ways.
-  To avoid this situation, it is highly recommended to use OSGi version stamps as part of the URL.
-- `include`: A URL to another catalog file to include, inheriting the meta from the current hierarchy.
-  Libraries defined so far in the meta will be used to load classpath entries. `include` must be used
-  when you have sibling properties. If it's the only property it may be skipped by having the URL as the
-  value - see `items` example above.
-
-
-#### Catalog YAML Examples
-
-##### A Simple Example
-
-The following example installs the `RiakNode` entity, making it also available as an application template,
-with a nice display name, description, and icon.
-It can be referred in other blueprints to as `datastore:1.0`,
-and its implementation will be the Java class `org.apache.brooklyn.entity.nosql.riak.RiakNode` included with Brooklyn.
-
-~~~ yaml
-brooklyn.catalog:
-  id: datastore
-  version: "1.0"
-  itemType: template
-  iconUrl: classpath://org/apache/brooklyn/entity/nosql/riak/riak.png
-  name: Datastore (Riak)
-  description: Riak is an open-source NoSQL key-value data store.
-  item:
-    services:
-    - type: org.apache.brooklyn.entity.nosql.riak.RiakNode
-      name: Riak Node
-~~~ 
-
-
-##### Multiple Items
-
-This YAML will install three items:
-
-~~~ yaml
-brooklyn.catalog:
-  version: "1.1"
-  iconUrl: classpath://org/apache/brooklyn/entity/nosql/riak/riak.png
-  description: Riak is an open-source NoSQL key-value data store.
-  items:
-    - id: riak-node
-      itemType: entity
-      item:
-        type: org.apache.brooklyn.entity.nosql.riak.RiakNode
-        name: Riak Node
-    - id: riak-cluster
-      itemType: entity
-      item:
-        type: org.apache.brooklyn.entity.nosql.riak.RiakCluster
-        name: Riak Cluster
-    - id: datastore
-      name: Datastore (Riak Cluster)
-      itemType: template
-      item:
-        services:
-        - type: riak-cluster
-          brooklyn.config:
-            # the default size is 3 but this can be changed to suit your requirements
-            initial.size: 3
-            provisioning.properties:
-              # you can also define machine specs
-              minRam: 8gb
-~~~ 
-
-The items this will add to the catalog are:
-
-- `riak-node`, as before, but with a different name
-- `riak-cluster` as a convenience short name for the `org.apache.brooklyn.entity.nosql.riak.RiakCluster` class
-- `datastore`, now pointing at the `riak-cluster` blueprint, in SoftLayer and with the given size and machine spec, 
-  as the default implementation for anyone
-  requesting a `datastore` (and if installed atop the previous example, new references to `datastore` 
-  will access this version because it is a higher number);
-  because it is a template, users will have the opportunity to edit the YAML (see below).
-  (This must be supplied after `riak-cluster`, because it refers to `riak-cluster`.)
-
-
-#### Locations in the Catalog
-
-In addition to blueprints, locations can be added to the Apache Brooklyn catalog. The example below shows a location for the vagrant configuration used in the [getting started guide]({{ site.path.guide }}/start/blueprints.html), formatted as a catalog entry.
-
-~~~ yaml
-brooklyn.catalog:
-  id: vagrant
-  version: "1.0"
-  itemType: location
-  name: Vagrant getting started location
-  item:
-    type: byon
-    brooklyn.config:
-      user: vagrant
-      password: vagrant
-      hosts:
-        - 10.10.10.101
-        - 10.10.10.102
-        - 10.10.10.103
-        - 10.10.10.104
-~~~
-
-Once this has been added to the catalog it can be used as a named location in yaml blueprints using:
-
-~~~ yaml
-location: vagrant
-~~~
-
-
-#### Legacy Syntax
-
-The following legacy and experimental syntax is also supported, but deprecated:
-
-~~~ yaml
-<blueprint-definition>
-brooklyn.catalog:
-  <catalog-metadata>
-~~~ 
-
-In this format, the `brooklyn.catalog` block is optional;
-and an `id` in the `<blueprint-definition>` will be used to determine the catalog ID. 
-This is primarily supplied for OASIS CAMP 1.1 compatibility,
-where the same YAML blueprint can be POSTed to the catalog endpoint to add to a catalog
-or POSTed to the applications endpoint to deploy an instance.
-(This syntax is discouraged as the latter usage, 
-POSTing to the applications endpoint,
-will ignored the `brooklyn.catalog` information;
-this means references to any `item` blocks in the `<catalog-metadata>` will not be resolved,
-and any OSGi `brooklyn.libraries` defined there will not be loaded.)
-
-
-
-### Templates and the Add-Application Wizard
-
-A `template` is a full application. It consists of one or more entities inside an application 
-(though this is also composable: it can be used as part of another application).
-When a `template` is added to the catalog, the blueprint will appear in the 'Create Application' dialog
-as shown here:
-
-[![MySQL in Brooklyn Catalog](mysql-in-catalog-w700.png "MySQL in Brooklyn Catalog")](mysql-in-catalog.png) 
-
-
-
-### Catalog Management
-
-The Catalog tab in the web console will show all versions of catalog items,
-and allow you to add new items.
-
-
-#### Adding to the Catalog
-
-On the UI the "add" button <img src="images/add-to-catalog.png" width="24" alt="add-to-catalog" /> at the top of the menu panel allows the
-addition of new Applications to the catalog, via YAML, and of new Locations.
-
-In addition to the GUI, items can be added to the catalog via the REST API
-with a `POST` of the YAML file to `/v1/catalog` endpoint.
-To do this using `curl`:
-
-~~~ bash
-curl -u admin:password http://127.0.0.1:8081/v1/catalog --data-binary @/path/to/riak.catalog.bom
-~~~ 
-
-Or using the CLI:
-
-~~~ bash
-br catalog add /path/to/riak.catalog.bom
-~~~ 
-
-
-
-#### Deleting from the Catalog
-
-On the UI, if an item is selected, a 'Delete' button in the detail panel can be used to delete it from the catalog.
-
-Using the REST API, you can delete a versioned item from the catalog using the corresponding endpoint. 
-For example, to delete the item with id `datastore` and version `1.0` with `curl`:
-
-~~~ bash
-curl -u admin:password -X DELETE http://127.0.0.1:8081/v1/catalog/applications/datastore/1.0
-~~~ 
-
-
-**Note:** Catalog items should not be deleted if there are running apps which were created using the same item. 
-During rebinding the catalog item is used to reconstruct the entity.
-
-If you have running apps which were created using the item you wish to delete, you should instead deprecate the catalog item.
-Deprecated catalog items will not appear in the add application wizard, or in the catalog list but will still
-be available to Brooklyn for rebinding. The option to display deprecated catalog items in the catalog list will be added
-in a future release.
-
-Deprecation applies to a specific version of a catalog item, so the full
-id including the version number is passed to the REST API as follows:
-
-~~~ bash
-curl -u admin:password -X POST http://127.0.0.1:8081/v1/catalog/entities/MySQL:1.0/deprecated/true
-~~~ 
-
-
-### Versioning
-
-Version numbers follow the OSGi convention. This can have a major, minor, micro and qualifier part.
-For example, `1.0`. `1.0.1` or `1.0.1-20150101`.
-
-The combination of `id:version` strings must be unique across the catalog.
-It is an error to deploy the same version of an existing item:
-to update a blueprint, it is recommended to increase its version number;
-alternatively in some cases it is permitted to delete an `id:version` instance
-and then re-deploy.
-If no version is specified, re-deploying will automatically
-increment an internal version number for the catalog item.
-
-When referencing a blueprint, if a version number is not specified 
-the latest non-snapshot version will be loaded when an entity is instantiated.
-
-
-### Brooklyn Server Command Line Arguments
-
-The command line arguments when launching `brooklyn` include several commands for working with the catalog.
-
-* `--catalogAdd <file.bom>` will add the catalog items in the `bom` file
-* `--catalogReset` will reset the catalog to the initial state 
-  (based on `brooklyn/default.catalog.bom` on the classpath, by default in a dist in the `conf/` directory)
-* `--catalogInitial <file.bom>` will set the catalog items to use on first run,
-  on a catalog reset, or if persistence is off
-
-If `--catalogInitial` is not specified, the default initial catalog at `brooklyn/default.catalog.bom` will be used.
-As `scanJavaAnnotations: true` is set in `default.catalog.bom`, Brooklyn will scan the classpath for catalog items,
-which will be added to the catalog.
-To launch Brooklyn without initializing the catalog, use `--catalogInitial classpath://brooklyn/empty.catalog.bom`
-
-If [persistence](../persistence/) is enabled, catalog additions will remain between runs. If items that were
-previously added based on items in `brooklyn/default.catalog.bom` or `--catalogInitial` are 
-deleted, they will not be re-added on subsequent restarts of brooklyn. I.e. `--catalogInitial` is ignored
-if persistence is enabled and persistent state has already been created.
-
-For more information on these commands, run `brooklyn help launch`.
-
-
-<!--
-TODO: make test cases from the code snippets here, and when building the docs assert that they match test cases
--->

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/1330dcd3/guide/ops/catalog/mysql-in-catalog-w700.png
----------------------------------------------------------------------
diff --git a/guide/ops/catalog/mysql-in-catalog-w700.png b/guide/ops/catalog/mysql-in-catalog-w700.png
deleted file mode 100644
index f370249..0000000
Binary files a/guide/ops/catalog/mysql-in-catalog-w700.png and /dev/null differ