brooklyn-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From henev...@apache.org
Subject [09/23] brooklyn-docs git commit: Removed child pages from locations
Date Fri, 13 May 2016 12:04:43 GMT
Removed child pages from locations


Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/33bca1b9
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/33bca1b9
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/33bca1b9

Branch: refs/heads/0.9.x
Commit: 33bca1b9e4340154f0b6278dc19acda47c926591
Parents: e7ef680
Author: Duncan Godwin <duncan.godwin@cloudsoftcorp.com>
Authored: Tue May 10 16:26:28 2016 +0100
Committer: Duncan Godwin <duncan.godwin@cloudsoftcorp.com>
Committed: Thu May 12 12:10:55 2016 +0100

----------------------------------------------------------------------
 guide/ops/locations/_byon.md                    |  77 ++++++
 guide/ops/locations/_clouds.md                  | 252 +++++++++++++++++
 .../_inheritance-and-named-locations.md         |  80 ++++++
 guide/ops/locations/_localhost.md               |  36 +++
 guide/ops/locations/_more-clouds.md             | 274 +++++++++++++++++++
 guide/ops/locations/_special-locations.md       |  54 ++++
 guide/ops/locations/_ssh-keys.md                |  88 ++++++
 guide/ops/locations/byon.md                     |  77 ------
 guide/ops/locations/cloud-credentials.md        |   2 +-
 guide/ops/locations/clouds.md                   | 252 -----------------
 .../inheritance-and-named-locations.md          |  80 ------
 guide/ops/locations/localhost.md                |  36 ---
 guide/ops/locations/more-clouds.md              | 274 -------------------
 guide/ops/locations/special-locations.md        |  54 ----
 guide/ops/locations/ssh-keys.md                 |  88 ------
 15 files changed, 862 insertions(+), 862 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/33bca1b9/guide/ops/locations/_byon.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/_byon.md b/guide/ops/locations/_byon.md
new file mode 100644
index 0000000..38f6595
--- /dev/null
+++ b/guide/ops/locations/_byon.md
@@ -0,0 +1,77 @@
+---
+section: BYON
+section_position: 4
+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.html).) 
+
+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 }}/ops/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/33bca1b9/guide/ops/locations/_clouds.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/_clouds.md b/guide/ops/locations/_clouds.md
new file mode 100644
index 0000000..22afd69
--- /dev/null
+++ b/guide/ops/locations/_clouds.md
@@ -0,0 +1,252 @@
+---
+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 }}/ops/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 }}/ops/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 AMP 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.
+  
+  ###### 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.html).) 
+
+- 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 (as a URL) to run an additional script,
+  before making the `Location` available to entities,
+  optionally also using `setup.script.vars` (set as `key1:value1,key2:value2`)
+
+- 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://github.com/jclouds/jclouds/blob/jclouds-1.9.0/providers/aws-ec2/src/main/java/org/jclouds/aws/ec2/compute/AWSEC2TemplateOptions.java),
+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.
+
+
+
+  
+See the following resources for more information:
+
+- [AWS VPC issues which may affect users with older AWS accounts](vpc-issues.html)
+- [Amazon EC2 and Amazon Virtual Private Cloud](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-vpc.html#vpc-only-instance-types)
+- [Your Default VPC and Subnets](http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/default-vpc.html)
+- [Amazon VPC FAQs](http://aws.amazon.com/vpc/faqs/#Default_VPCs)
+  
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/33bca1b9/guide/ops/locations/_inheritance-and-named-locations.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/_inheritance-and-named-locations.md b/guide/ops/locations/_inheritance-and-named-locations.md
new file mode 100644
index 0000000..53fe904
--- /dev/null
+++ b/guide/ops/locations/_inheritance-and-named-locations.md
@@ -0,0 +1,80 @@
+---
+section: Inheritance and Named Locations
+title: Named Locations
+section_type: inline
+section_position: 3
+---
+
+### 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/33bca1b9/guide/ops/locations/_localhost.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/_localhost.md b/guide/ops/locations/_localhost.md
new file mode 100644
index 0000000..7ac906a
--- /dev/null
+++ b/guide/ops/locations/_localhost.md
@@ -0,0 +1,36 @@
+---
+section: Localhost
+section_position: 6
+section_type: inline
+---
+
+### Localhost
+
+If passwordless ssh login to `localhost` and passwordless `sudo` is enabled on your 
+machine, you should be able to deploy blueprints with no special configuration,
+just by specifying `location: localhost` in YAML.
+
+If you use a passpharse or prefer a different key, these can be configured as follows: 
+
+{% highlight bash %}
+brooklyn.location.localhost.privateKeyFile=~/.ssh/brooklyn_key
+brooklyn.location.localhost.privateKeyPassphrase=s3cr3tPASSPHRASE
+{% endhighlight %}
+
+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 }}/ops/catalog/index.html#locations-in-catalog) for easy reusability.
+
+If you encounter issues or for more information, see [SSH Keys Localhost Setup](ssh-keys.html#localhost-setup). 
+
+If you are normally prompted for a password when executing `sudo` commands, passwordless `sudo` must also be enabled.  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` should be setup correctly:
+{% highlight bash %}
+sudo ls
+{% endhighlight %}
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/33bca1b9/guide/ops/locations/_more-clouds.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/_more-clouds.md b/guide/ops/locations/_more-clouds.md
new file mode 100644
index 0000000..acfd274
--- /dev/null
+++ b/guide/ops/locations/_more-clouds.md
@@ -0,0 +1,274 @@
+---
+section: More Details on Specific Clouds
+title: More on Clouds
+section_type: inline
+section_position: 2
+---
+
+### More Details on Specific Clouds
+
+To connect to a Cloud, Brooklyn requires appropriate credentials. These comprise the `identity` and 
+`credential` in Brooklyn terminology. 
+
+For private clouds (and for some clouds being targeted using a standard API), the `endpoint`
+must also be specified, which is the cloud's URL.  For public clouds, Brooklyn comes preconfigured 
+with the endpoints, but many offer different choices of the `region` where you might want to deploy.  
+
+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.
+ 
+
+
+## Amazon Web Services (AWS)
+
+### Credentials
+
+AWS has an "access key" and a "secret key", which correspond to Brooklyn's identity and credential 
+respectively.
+
+These keys are the way for any programmatic mechanism to access the AWS API.
+
+To generate an access key and a secret key, see [jclouds instructions](http://jclouds.apache.org/guides/aws) 
+and [AWS IAM instructions](http://docs.aws.amazon.com/IAM/latest/UserGuide/ManagingCredentials.html).
+
+An example of the expected format is shown below:
+
+    brooklyn.location.jclouds.aws-ec2.identity=ABCDEFGHIJKLMNOPQRST
+    brooklyn.location.jclouds.aws-ec2.credential=abcdefghijklmnopqrstu+vwxyzabcdefghijklm
+
+
+### Tidying up after jclouds
+
+Security groups are not always deleted by jclouds. This is due to a limitation in AWS (see
+https://issues.apache.org/jira/browse/JCLOUDS-207). In brief, AWS prevents the security group
+being deleted until there are no VMs using it. However, there is eventual consistency for
+recording which VMs still reference those security groups: after deleting the VM, it can sometimes
+take several minutes before the security group can be deleted. jclouds retries for 3 seconds, but 
+does not block for longer.
+
+There is utility written by Cloudsoft for deleting these unused resources:
+http://www.cloudsoftcorp.com/blog/2013/03/tidying-up-after-jclouds.
+
+
+### Using Subnets and Security Groups
+
+Apache Brooklyn can run with AWS VPC and both public and private subnets.
+Simply provide the `subnet-a1b2c3d4` as the `networkName` when deploying:
+
+    location:
+      jclouds:aws-ec2:
+        region: us-west-1
+        networkName: subnet-a1b2c3d4   # use your subnet ID
+
+Subnets are typically used in conjunction with security groups.
+Brooklyn does *not* attempt to open additional ports
+when private subnets or security groups are supplied, 
+so the subnet and ports must be configured appropriately for the blueprints being deployed.
+You can configure a default security group with appropriate (or all) ports opened for
+access from the appropriate (or all) CIDRs and security groups,
+or you can define specific `securityGroups` on the location
+or as `provisioning.properties` on the entities.
+
+Make sure that Brooklyn has access to the machines under management.
+This includes SSH, which might be done with a public IP created with inbound access 
+on port 22 permitted for a CIDR range including the IP from which Brooklyn contacts it. 
+Alternatively you can run Brooklyn on a machine in that same subnet, or 
+set up a VPN or jumphost which Brooklyn will use.
+
+
+### EC2 "Classic" Problems with VPC-only Hardware Instance Types
+
+If you have a pre-2014 Amazon account, it is likely configured in some regions to run in "EC2 Classic" mode
+by default, instead of the more modern "VPC" default mode.  This can cause failures when requesting certain hardware
+configurations because many of the more recent hardware "instance types" only run in "VPC" mode.
+For instance when requesting an instance with `minRam: 8gb`, Brooklyn may opt for an `m4.large`,
+which is a VPC-only instance type. If you are in a region configured to use "EC2 Classic" mode,
+you may see a message such as this:
+
+    400 VPCResourceNotSpecified: The specified instance type can only be used in a VPC. 
+    A subnet ID or network interface ID is required to carry out the request.
+
+This is a limitation of "legacy" accounts.  The easiest fixes are either:
+
+* specify an instance type which is supported in classic, such as `m3.xlarge` (see below)
+* move to a different region where VPC is the default
+  (`eu-central-1` should work as it *only* offers VPC mode,
+  irrespective of the age of your AWS account)
+* get a new AWS account -- "VPC" will be the default mode
+  (Amazon recommend this and if you want to migrate existing deployments
+  they provide [detailed instructions](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/vpc-migrate.html)) 
+
+To understand the situation, the following resources may be useful:
+ 
+* Background on VPC vs Classic:  [http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-vpc.html](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-vpc.html)
+* Good succinct answers to FAQs: [http://aws.amazon.com/vpc/faqs/#Default_VPCs]()
+* Check if a region in your account is "VPC" or "Classic": [http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/default-vpc.html#default-vpc-availability]()     
+* Regarding instance types:
+  * All instance types: [https://aws.amazon.com/ec2/instance-types]()
+  * Those which require VPC: [http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-vpc.html#vpc-only-instance-types]()
+
+If you want to solve this problem with your existing account,
+you can create a VPC and instruct Brooklyn to use it:
+
+1. Use the "Start VPC Wizard" option in [the VPC dashboard](https://console.aws.amazon.com/vpc),
+  making sure it is for the right region, and selecting a "Single Public Subnet".
+  (More information is in [these AWS instructions](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/get-set-up-for-amazon-ec2.html#create-a-vpc).)
+2. Once the VPC is created, open the "Subnets" view and modify the "Public subnet"
+   so that it will "Auto-assign Public IP".
+3. Next click on the "Security Groups" and find the `default` security group for that VPC.
+   Modify its "Inbound Rules" to allow "All traffic" from "Anywhere".
+   (Or for more secure options, see the instructions in the previous section, 
+   "Using Subnets".)
+4. Finally make a note of the subnet ID (e.g. `subnet-a1b2c3d4`) for use in Brooklyn.
+
+You can then deploy blueprints to the subnet, allowing VPC hardware instance types, 
+by specifying the subnet ID as the `networkName` in your YAML blueprint.
+This is covered in the previous section, "Using Subnets".
+
+
+## Google Compute Engine (GCE)
+
+### Credentials
+
+GCE uses a service account e-mail address for the identity and a private key as the credential.
+
+To obtain these from GCE, see the [jclouds instructions](https://jclouds.apache.org/guides/google).
+
+An example of the expected format is shown below.
+Note that when supplying the credential in a properties file, it should be one long line 
+with `\n` representing the new line characters:
+
+    brooklyn.location.jclouds.google-compute-engine.identity=123456789012@developer.gserviceaccount.com
+    brooklyn.location.jclouds.google-compute-engine.credential=-----BEGIN RSA PRIVATE KEY-----\nabcdefghijklmnopqrstuvwxyznabcdefghijk/lmnopqrstuvwxyzabcdefghij\nabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghij+lm\nnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklm\nnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxy\nzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijk\nlmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvw\nxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghi\njklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstu\nvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefg\nhijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrs\ntuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcde\nfghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvw\n-----END RSA PRIVATE KEY-----
+
+
+### Quotas
+
+GCE accounts can have low default [quotas](https://cloud.google.com/compute/docs/resource-quotas).
+
+It is easy to requesta quota increase by submitting a [quota increase form](https://support.google.com/cloud/answer/6075746?hl=en).
+ 
+
+### Networks
+
+GCE accounts often have a limit to the number of networks that can be created. One work around 
+is to manually create a network with the required open ports, and to refer to that named network
+in Brooklyn's location configuration.
+
+To create a network, see [GCE network instructions](https://cloud.google.com/compute/docs/networking#networks_1).
+
+For example, for dev/demo purposes an "everything" network could be created that opens all ports.
+
+|| Name                        || everything                  |
+|| Description                 || opens all tcp ports         |
+|| Source IP Ranges            || 0.0.0.0/0                   |
+|| Allowed protocols and ports || tcp:0-65535 and udp:0-65535 |
+
+## IBM SoftLayer
+
+### 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:
+
+```YAML
+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:
+
+```YAML
+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*:
+
+```YAML
+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:
+
+```Java
+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/33bca1b9/guide/ops/locations/_special-locations.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/_special-locations.md b/guide/ops/locations/_special-locations.md
new file mode 100644
index 0000000..8f19fa4
--- /dev/null
+++ b/guide/ops/locations/_special-locations.md
@@ -0,0 +1,54 @@
+---
+section: Specialized Locations
+section_position: 7
+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 %}
+services:
+- type: org.apache.brooklyn.entity.webapp.jboss.JBoss7Server 
+  location:
+    host: 192.168.0.1
+{% 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.
+When the first target is full, the next is tried, and so on:
+
+{% highlight yaml %}
+location:
+  multi:
+    targets:
+    - byon:(hosts=192.168.0.1)
+    - jclouds:aws-ec2:
+      identity: acct1
+    - jclouds:aws-ec2:
+      identity: acct2      
+{% endhighlight %}
+
+The example above provisions the first node to `192.168.0.1`,
+then it provisions into `acct1` at Amazon if possible,
+and then to `acct2`.
+
+
+
+#### 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/33bca1b9/guide/ops/locations/_ssh-keys.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/_ssh-keys.md b/guide/ops/locations/_ssh-keys.md
new file mode 100644
index 0000000..03ee84e
--- /dev/null
+++ b/guide/ops/locations/_ssh-keys.md
@@ -0,0 +1,88 @@
+---
+section: SSH Keys
+section_position: 5
+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.website }}/documentation/increase-entropy.html) for more information

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/33bca1b9/guide/ops/locations/byon.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/byon.md b/guide/ops/locations/byon.md
deleted file mode 100644
index 38f6595..0000000
--- a/guide/ops/locations/byon.md
+++ /dev/null
@@ -1,77 +0,0 @@
----
-section: BYON
-section_position: 4
-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.html).) 
-
-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 }}/ops/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/33bca1b9/guide/ops/locations/cloud-credentials.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/cloud-credentials.md b/guide/ops/locations/cloud-credentials.md
index 1594012..36041e0 100644
--- a/guide/ops/locations/cloud-credentials.md
+++ b/guide/ops/locations/cloud-credentials.md
@@ -3,4 +3,4 @@ title: More Clouds
 layout: website-normal
 ---
 
-This page has moved. See [More Clouds](more-clouds.html) instead.
+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/33bca1b9/guide/ops/locations/clouds.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/clouds.md b/guide/ops/locations/clouds.md
deleted file mode 100644
index 08109e0..0000000
--- a/guide/ops/locations/clouds.md
+++ /dev/null
@@ -1,252 +0,0 @@
----
-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 }}/ops/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 }}/ops/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-clouds.html)**.
-
-#### 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 AMP 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.
-  
-  ###### 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.html).) 
-
-- 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 (as a URL) to run an additional script,
-  before making the `Location` available to entities,
-  optionally also using `setup.script.vars` (set as `key1:value1,key2:value2`)
-
-- 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://github.com/jclouds/jclouds/blob/jclouds-1.9.0/providers/aws-ec2/src/main/java/org/jclouds/aws/ec2/compute/AWSEC2TemplateOptions.java),
-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.
-
-
-
-  
-See the following resources for more information:
-
-- [AWS VPC issues which may affect users with older AWS accounts](vpc-issues.html)
-- [Amazon EC2 and Amazon Virtual Private Cloud](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-vpc.html#vpc-only-instance-types)
-- [Your Default VPC and Subnets](http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/default-vpc.html)
-- [Amazon VPC FAQs](http://aws.amazon.com/vpc/faqs/#Default_VPCs)
-  
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/33bca1b9/guide/ops/locations/inheritance-and-named-locations.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/inheritance-and-named-locations.md b/guide/ops/locations/inheritance-and-named-locations.md
deleted file mode 100644
index 53fe904..0000000
--- a/guide/ops/locations/inheritance-and-named-locations.md
+++ /dev/null
@@ -1,80 +0,0 @@
----
-section: Inheritance and Named Locations
-title: Named Locations
-section_type: inline
-section_position: 3
----
-
-### 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/33bca1b9/guide/ops/locations/localhost.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/localhost.md b/guide/ops/locations/localhost.md
deleted file mode 100644
index 7ac906a..0000000
--- a/guide/ops/locations/localhost.md
+++ /dev/null
@@ -1,36 +0,0 @@
----
-section: Localhost
-section_position: 6
-section_type: inline
----
-
-### Localhost
-
-If passwordless ssh login to `localhost` and passwordless `sudo` is enabled on your 
-machine, you should be able to deploy blueprints with no special configuration,
-just by specifying `location: localhost` in YAML.
-
-If you use a passpharse or prefer a different key, these can be configured as follows: 
-
-{% highlight bash %}
-brooklyn.location.localhost.privateKeyFile=~/.ssh/brooklyn_key
-brooklyn.location.localhost.privateKeyPassphrase=s3cr3tPASSPHRASE
-{% endhighlight %}
-
-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 }}/ops/catalog/index.html#locations-in-catalog) for easy reusability.
-
-If you encounter issues or for more information, see [SSH Keys Localhost Setup](ssh-keys.html#localhost-setup). 
-
-If you are normally prompted for a password when executing `sudo` commands, passwordless `sudo` must also be enabled.  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` should be setup correctly:
-{% highlight bash %}
-sudo ls
-{% endhighlight %}
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/33bca1b9/guide/ops/locations/more-clouds.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/more-clouds.md b/guide/ops/locations/more-clouds.md
deleted file mode 100644
index acfd274..0000000
--- a/guide/ops/locations/more-clouds.md
+++ /dev/null
@@ -1,274 +0,0 @@
----
-section: More Details on Specific Clouds
-title: More on Clouds
-section_type: inline
-section_position: 2
----
-
-### More Details on Specific Clouds
-
-To connect to a Cloud, Brooklyn requires appropriate credentials. These comprise the `identity` and 
-`credential` in Brooklyn terminology. 
-
-For private clouds (and for some clouds being targeted using a standard API), the `endpoint`
-must also be specified, which is the cloud's URL.  For public clouds, Brooklyn comes preconfigured 
-with the endpoints, but many offer different choices of the `region` where you might want to deploy.  
-
-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.
- 
-
-
-## Amazon Web Services (AWS)
-
-### Credentials
-
-AWS has an "access key" and a "secret key", which correspond to Brooklyn's identity and credential 
-respectively.
-
-These keys are the way for any programmatic mechanism to access the AWS API.
-
-To generate an access key and a secret key, see [jclouds instructions](http://jclouds.apache.org/guides/aws) 
-and [AWS IAM instructions](http://docs.aws.amazon.com/IAM/latest/UserGuide/ManagingCredentials.html).
-
-An example of the expected format is shown below:
-
-    brooklyn.location.jclouds.aws-ec2.identity=ABCDEFGHIJKLMNOPQRST
-    brooklyn.location.jclouds.aws-ec2.credential=abcdefghijklmnopqrstu+vwxyzabcdefghijklm
-
-
-### Tidying up after jclouds
-
-Security groups are not always deleted by jclouds. This is due to a limitation in AWS (see
-https://issues.apache.org/jira/browse/JCLOUDS-207). In brief, AWS prevents the security group
-being deleted until there are no VMs using it. However, there is eventual consistency for
-recording which VMs still reference those security groups: after deleting the VM, it can sometimes
-take several minutes before the security group can be deleted. jclouds retries for 3 seconds, but 
-does not block for longer.
-
-There is utility written by Cloudsoft for deleting these unused resources:
-http://www.cloudsoftcorp.com/blog/2013/03/tidying-up-after-jclouds.
-
-
-### Using Subnets and Security Groups
-
-Apache Brooklyn can run with AWS VPC and both public and private subnets.
-Simply provide the `subnet-a1b2c3d4` as the `networkName` when deploying:
-
-    location:
-      jclouds:aws-ec2:
-        region: us-west-1
-        networkName: subnet-a1b2c3d4   # use your subnet ID
-
-Subnets are typically used in conjunction with security groups.
-Brooklyn does *not* attempt to open additional ports
-when private subnets or security groups are supplied, 
-so the subnet and ports must be configured appropriately for the blueprints being deployed.
-You can configure a default security group with appropriate (or all) ports opened for
-access from the appropriate (or all) CIDRs and security groups,
-or you can define specific `securityGroups` on the location
-or as `provisioning.properties` on the entities.
-
-Make sure that Brooklyn has access to the machines under management.
-This includes SSH, which might be done with a public IP created with inbound access 
-on port 22 permitted for a CIDR range including the IP from which Brooklyn contacts it. 
-Alternatively you can run Brooklyn on a machine in that same subnet, or 
-set up a VPN or jumphost which Brooklyn will use.
-
-
-### EC2 "Classic" Problems with VPC-only Hardware Instance Types
-
-If you have a pre-2014 Amazon account, it is likely configured in some regions to run in "EC2 Classic" mode
-by default, instead of the more modern "VPC" default mode.  This can cause failures when requesting certain hardware
-configurations because many of the more recent hardware "instance types" only run in "VPC" mode.
-For instance when requesting an instance with `minRam: 8gb`, Brooklyn may opt for an `m4.large`,
-which is a VPC-only instance type. If you are in a region configured to use "EC2 Classic" mode,
-you may see a message such as this:
-
-    400 VPCResourceNotSpecified: The specified instance type can only be used in a VPC. 
-    A subnet ID or network interface ID is required to carry out the request.
-
-This is a limitation of "legacy" accounts.  The easiest fixes are either:
-
-* specify an instance type which is supported in classic, such as `m3.xlarge` (see below)
-* move to a different region where VPC is the default
-  (`eu-central-1` should work as it *only* offers VPC mode,
-  irrespective of the age of your AWS account)
-* get a new AWS account -- "VPC" will be the default mode
-  (Amazon recommend this and if you want to migrate existing deployments
-  they provide [detailed instructions](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/vpc-migrate.html)) 
-
-To understand the situation, the following resources may be useful:
- 
-* Background on VPC vs Classic:  [http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-vpc.html](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-vpc.html)
-* Good succinct answers to FAQs: [http://aws.amazon.com/vpc/faqs/#Default_VPCs]()
-* Check if a region in your account is "VPC" or "Classic": [http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/default-vpc.html#default-vpc-availability]()     
-* Regarding instance types:
-  * All instance types: [https://aws.amazon.com/ec2/instance-types]()
-  * Those which require VPC: [http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-vpc.html#vpc-only-instance-types]()
-
-If you want to solve this problem with your existing account,
-you can create a VPC and instruct Brooklyn to use it:
-
-1. Use the "Start VPC Wizard" option in [the VPC dashboard](https://console.aws.amazon.com/vpc),
-  making sure it is for the right region, and selecting a "Single Public Subnet".
-  (More information is in [these AWS instructions](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/get-set-up-for-amazon-ec2.html#create-a-vpc).)
-2. Once the VPC is created, open the "Subnets" view and modify the "Public subnet"
-   so that it will "Auto-assign Public IP".
-3. Next click on the "Security Groups" and find the `default` security group for that VPC.
-   Modify its "Inbound Rules" to allow "All traffic" from "Anywhere".
-   (Or for more secure options, see the instructions in the previous section, 
-   "Using Subnets".)
-4. Finally make a note of the subnet ID (e.g. `subnet-a1b2c3d4`) for use in Brooklyn.
-
-You can then deploy blueprints to the subnet, allowing VPC hardware instance types, 
-by specifying the subnet ID as the `networkName` in your YAML blueprint.
-This is covered in the previous section, "Using Subnets".
-
-
-## Google Compute Engine (GCE)
-
-### Credentials
-
-GCE uses a service account e-mail address for the identity and a private key as the credential.
-
-To obtain these from GCE, see the [jclouds instructions](https://jclouds.apache.org/guides/google).
-
-An example of the expected format is shown below.
-Note that when supplying the credential in a properties file, it should be one long line 
-with `\n` representing the new line characters:
-
-    brooklyn.location.jclouds.google-compute-engine.identity=123456789012@developer.gserviceaccount.com
-    brooklyn.location.jclouds.google-compute-engine.credential=-----BEGIN RSA PRIVATE KEY-----\nabcdefghijklmnopqrstuvwxyznabcdefghijk/lmnopqrstuvwxyzabcdefghij\nabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghij+lm\nnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklm\nnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxy\nzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijk\nlmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvw\nxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghi\njklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstu\nvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefg\nhijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrs\ntuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcde\nfghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvw\n-----END RSA PRIVATE KEY-----
-
-
-### Quotas
-
-GCE accounts can have low default [quotas](https://cloud.google.com/compute/docs/resource-quotas).
-
-It is easy to requesta quota increase by submitting a [quota increase form](https://support.google.com/cloud/answer/6075746?hl=en).
- 
-
-### Networks
-
-GCE accounts often have a limit to the number of networks that can be created. One work around 
-is to manually create a network with the required open ports, and to refer to that named network
-in Brooklyn's location configuration.
-
-To create a network, see [GCE network instructions](https://cloud.google.com/compute/docs/networking#networks_1).
-
-For example, for dev/demo purposes an "everything" network could be created that opens all ports.
-
-|| Name                        || everything                  |
-|| Description                 || opens all tcp ports         |
-|| Source IP Ranges            || 0.0.0.0/0                   |
-|| Allowed protocols and ports || tcp:0-65535 and udp:0-65535 |
-
-## IBM SoftLayer
-
-### 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:
-
-```YAML
-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:
-
-```YAML
-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*:
-
-```YAML
-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:
-
-```Java
-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/33bca1b9/guide/ops/locations/special-locations.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/special-locations.md b/guide/ops/locations/special-locations.md
deleted file mode 100644
index 8f19fa4..0000000
--- a/guide/ops/locations/special-locations.md
+++ /dev/null
@@ -1,54 +0,0 @@
----
-section: Specialized Locations
-section_position: 7
-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 %}
-services:
-- type: org.apache.brooklyn.entity.webapp.jboss.JBoss7Server 
-  location:
-    host: 192.168.0.1
-{% 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.
-When the first target is full, the next is tried, and so on:
-
-{% highlight yaml %}
-location:
-  multi:
-    targets:
-    - byon:(hosts=192.168.0.1)
-    - jclouds:aws-ec2:
-      identity: acct1
-    - jclouds:aws-ec2:
-      identity: acct2      
-{% endhighlight %}
-
-The example above provisions the first node to `192.168.0.1`,
-then it provisions into `acct1` at Amazon if possible,
-and then to `acct2`.
-
-
-
-#### 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.
-


Mime
View raw message