You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@brooklyn.apache.org by ri...@apache.org on 2016/04/20 17:19:21 UTC
svn commit: r1740156 [3/4] - in /brooklyn/site/v: 0.9.0/ops/locations/
0.9.0/style/js/catalog/ latest/ops/locations/ latest/style/js/catalog/
Modified: brooklyn/site/v/latest/ops/locations/index.html
URL: http://svn.apache.org/viewvc/brooklyn/site/v/latest/ops/locations/index.html?rev=1740156&r1=1740155&r2=1740156&view=diff
==============================================================================
--- brooklyn/site/v/latest/ops/locations/index.html (original)
+++ brooklyn/site/v/latest/ops/locations/index.html Wed Apr 20 15:19:21 2016
@@ -395,6 +395,895 @@ or directly in YAML when specifying a lo
On some entities, config keys determining maching selection and provisioning behavior
can also be set <code>in </code>provisioning.properties`. </p>
+<h3 id="clouds">Clouds</h3>
+
+<p>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 <a href="http://jclouds.apache.org/reference/providers/">see the full list</a>):</p>
+
+<ul>
+ <li><code>jclouds:aws-ec2:<region></code>: Amazon EC2, where <code>:<region></code> might be <code>us-east-1</code> or <code>eu-west-1</code> (or omitted)</li>
+ <li><code>jclouds:softlayer:<region></code>: IBM Softlayer, where <code>:<region></code> might be <code>dal05</code> or <code>ams01</code> (or omitted)</li>
+ <li><code>jclouds:google-compute-engine</code>: Google Compute Engine</li>
+ <li><code>jclouds:openstack-nova:<endpoint></code>: OpenStack, where <code>:<endpoint></code> is the access URL (required)</li>
+ <li><code>jclouds:cloudstack:<endpoint></code>: Apache CloudStack, where <code>:<endpoint></code> is the access URL (required)</li>
+</ul>
+
+<p>For any of these, of course, Brooklyn needs to be configured with an <code>identity</code> and a <code>credential</code>:</p>
+
+<div class="highlight"><pre><code class="language-yaml" data-lang="yaml"><span class="l-Scalar-Plain">location</span><span class="p-Indicator">:</span>
+ <span class="l-Scalar-Plain">jclouds:aws-ec2</span><span class="p-Indicator">:</span>
+ <span class="l-Scalar-Plain">identity</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">ABCDEFGHIJKLMNOPQRST</span>
+ <span class="l-Scalar-Plain">credential</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l</span></code></pre></div>
+
+<p>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 <a href="/v/latest/ops/catalog/index.html#locations-in-catalog">catalog entry</a> or set them in <code>brooklyn.properties</code>
+in the <code>jclouds.<provider></code> namespace:</p>
+
+<div class="highlight"><pre><code class="language-bash" data-lang="bash">brooklyn.location.jclouds.aws-ec2.identity<span class="o">=</span>ABCDEFGHIJKLMNOPQRST
+brooklyn.location.jclouds.aws-ec2.credential<span class="o">=</span>s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l</code></pre></div>
+
+<p>And in this case you can reference the location in YAML with <code>location: jclouds:aws-ec2</code>.</p>
+
+<p>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 <a href="/v/latest/ops/catalog/index.html#locations-in-catalog">catalog entry</a> for easy reusability.</p>
+
+<p>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.</p>
+
+<p>In some cases, cloud providers have special features or unusual requirements.
+These are outlined in <strong><a href="more-clouds.html">More Details for Specific Clouds</a></strong>.</p>
+
+<h4 id="os-initial-login-and-setup">OS Initial Login and Setup</h4>
+
+<p>Once a machine is provisioned, Brooklyn will normally attempt to log in via SSH and configure the machine sensibly.</p>
+
+<p>The credentials for the initial OS log on are typically discovered from the cloud,
+but in some environments this is not possible.
+The keys <code>loginUser</code> and either <code>loginUser.password</code> or <code>loginUser.privateKeyFile</code> can be used to force
+Brooklyn to use specific credentials for the initial login to a cloud-provisioned machine.</p>
+
+<p>(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 <code>useJcloudsSshInit=false</code>.)</p>
+
+<p>Following a successful logon, Brooklyn performs the following steps to configure the machine:</p>
+
+<ol>
+ <li>
+ <p>creates a new user with the same name as the user <code>brooklyn</code> is running as locally
+ (this can be overridden with <code>user</code>, below).</p>
+ </li>
+ <li>
+ <p>install the local userâs <code>~/.ssh/id_rsa.pub</code> as an <code>authorized_keys</code> on the new machine,
+to make it easy for the operator to <code>ssh</code> in
+(override with <code>privateKeyFile</code>; or if there is no <code>id_{r,d}sa{,.pub}</code> an ad hoc keypair will be generated
+for the regular Brooklyn user;
+if there is a passphrase on the key, this must be supplied) </p>
+ </li>
+ <li>
+ <p>give <code>sudo</code> access to the newly created user (override with <code>grantUserSudo: false</code>)</p>
+ </li>
+ <li>
+ <p>disable direct <code>root</code> login to the machine</p>
+ </li>
+</ol>
+
+<p>These steps can be skipped or customized as described below.</p>
+
+<h4 id="jclouds-config-keys">jclouds Config Keys</h4>
+
+<p>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
+<code>JcloudsLocationConfig</code>
+ (<a href="/v/latest/misc/javadoc/org/apache/brooklyn/location/jclouds/JcloudsLocationConfig.html">javadoc</a>,
+ <a href="https://github.com/apache/brooklyn/tree/0.9.0/locations/jclouds/src/main/java/org/apache/brooklyn/location/jclouds/JcloudsLocationConfig.java">src</a>)
+.</p>
+
+<h6 id="vm-creation">VM Creation</h6>
+
+<ul>
+ <li>
+ <p>Most providers require exactly one of either <code>region</code> (e.g. <code>us-east-1</code>) or <code>endpoint</code> (the URL, usually for private cloud deployments)</p>
+ </li>
+ <li>
+ <p>Hardware requirements can be specified, including
+<code>minRam</code>, <code>minCores</code>, and <code>os64Bit</code>; or as a specific <code>hardwareId</code></p>
+ </li>
+ <li>
+ <p>VM image constraints can be set using <code>osFamily</code> (e.g. <code>Ubuntu</code>, <code>CentOS</code>, <code>Debian</code>, <code>RHEL</code>)
+and <code>osVersionRegex</code>, or specific VM images can be specified using <code>imageId</code> or <code>imageNameRegex</code></p>
+ </li>
+ <li>
+ <p>Specific VM images can be specified using <code>imageId</code> or <code>imageNameRegex</code></p>
+ </li>
+ <li>
+ <p>Specific Security Groups can be specified using <code>securityGroups</code>, as a list of strings (the existing security group names),
+or <code>inboundPorts</code> can be set, as a list of numeric ports (selected clouds only)</p>
+ </li>
+ <li>
+ <p>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 <code>keyPair</code> (selected clouds only).
+Note that if this <code>keyPair</code> does not correspond your default <code>~/.ssh/id_rsa</code>, you must typically
+also specify the corresponding <code>loginUser.privateKeyFile</code> as a file or URL accessible from Brooklyn.</p>
+ </li>
+ <li>
+ <p>A specific VM name (often the hostname) base to be used can be specified by setting <code>groupId</code>.
+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
+<code>CloudMachineNamer</code>
+(<a href="/v/latest/misc/javadoc/org/apache/brooklyn/core/location/cloud/names/CloudMachineNamer.html">javadoc</a>,
+ <a href="https://github.com/apache/brooklyn/tree/0.9.0/core/src/main/java/org/apache/brooklyn/core/location/cloud/names/CloudMachineNamer.java">src</a>)
+,
+for example
+<code>cloudMachineNamer: CustomMachineNamer</code>.
+<code>CustomMachineNamer</code>
+(<a href="/v/latest/misc/javadoc/org/apache/brooklyn/core/location/cloud/names/CustomMachineNamer.html">javadoc</a>,
+ <a href="https://github.com/apache/brooklyn/tree/0.9.0/core/src/main/java/org/apache/brooklyn/core/location/cloud/names/CustomMachineNamer.java">src</a>)</p>
+
+ <p>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 <code>vmNameSaltLength: 0</code> (selected clouds only).
+<!-- TODO jclouds softlayer includes a 3-char hex suffix --></p>
+ </li>
+ <li>
+ <p>A DNS domain name where this host should be placed can be specified with <code>domainName</code>
+(in selected clouds only)</p>
+ </li>
+ <li>
+ <p>User metadata can be attached using the syntax <code>userMetadata: { key: value, key2: "value 2" }</code>
+(or <code>userMetadata=key=value,key2="value 2"</code> in a properties file)</p>
+ </li>
+ <li>
+ <p>By default, several pieces of user metadata are set to correlate VMs with Brooklyn entities,
+prefixed with <code>brooklyn-</code>.
+This user metadata can be omitted by setting <code>includeBrooklynUserMetadata: false</code>.</p>
+ </li>
+ <li>
+ <p>You can specify the number of attempts Brooklyn should make to create
+machines with <code>machineCreateAttempts</code> (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
+<code>ServiceRestarter</code>
+(<a href="/v/latest/misc/javadoc/org/apache/brooklyn/policy/ha/ServiceRestarter.html">javadoc</a>,
+ <a href="https://github.com/apache/brooklyn/tree/0.9.0/policy/src/main/java/org/apache/brooklyn/policy/ha/ServiceRestarter.java">src</a>)
+.</p>
+ </li>
+ <li>
+ <p>If you want to investigate failures, set <code>destroyOnFailure: false</code>
+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.</p>
+
+ <h6 id="os-setup">OS Setup</h6>
+ </li>
+ <li>
+ <p><code>user</code> and <code>password</code> can be used to configure the operating user created on cloud-provisioned machines</p>
+ </li>
+ <li>
+ <p>The <code>loginUser</code> config key (and subkeys) control the initial user to log in as,
+in cases where this cannot be discovered from the cloud provider</p>
+ </li>
+ <li>
+ <p>Private keys can be specified using <code>privateKeyFile</code>;
+these are not copied to provisioned machines, but are required if using a local public key
+or a pre-defined <code>authorized_keys</code> on the server.
+(For more information on SSH keys, see <a href="ssh-keys.html">here</a>.) </p>
+ </li>
+ <li>
+ <p>If there is a passphrase on the key file being used, you must supply it to Brooklyn for it to work, of course!
+<code>privateKeyPassphrase</code> does the trick (as in <code>brooklyn.location.jclouds.privateKeyPassphrase</code>, or other places
+where <code>privateKeyFile</code> is valid). If you donât like keys, you can just use a plain old <code>password</code>.</p>
+ </li>
+ <li>
+ <p>Public keys can be specified using <code>publicKeyFile</code>,
+although these can usually be omitted if they follow the common pattern of being
+the private key file with the suffix <code>.pub</code> appended.
+(It is useful in the case of <code>loginUser.publicKeyFile</code>, where you shouldnât need,
+or might not even have, the private key of the <code>root</code> user when you log in.)</p>
+ </li>
+ <li>
+ <p>Provide a list of URLs to public keys in <code>extraSshPublicKeyUrls</code>,
+or the data of one key in <code>extraSshPublicKeyData</code>,
+to have additional public keys added to the <code>authorized_keys</code> file for logging in.
+(This is supported in most but not all locations.)</p>
+ </li>
+ <li>
+ <p>Use <code>dontCreateUser</code> to have Brooklyn run as the initial <code>loginUser</code> (usually <code>root</code>),
+without creating any other user.</p>
+ </li>
+ <li>
+ <p>A post-provisioning <code>setup.script</code> can be specified (as a URL) to run an additional script,
+before making the <code>Location</code> available to entities,
+optionally also using <code>setup.script.vars</code> (set as <code>key1:value1,key2:value2</code>)</p>
+ </li>
+ <li>
+ <p>Use <code>openIptables: true</code> to automatically configure <code>iptables</code>, to open the TCP ports required by
+the software process. One can alternatively use <code>stopIptables: true</code> to entirely stop the
+iptables service.</p>
+ </li>
+ <li>
+ <p>Use <code>installDevUrandom: true</code> to fall back to using <code>/dev/urandom</code> rather than <code>/dev/random</code>. This setting
+is useful for cloud VMs where there is not enough random entropy, which can cause <code>/dev/random</code> to be
+extremely slow (causing <code>ssh</code> to be extremely slow to respond).</p>
+ </li>
+ <li>
+ <p>Use <code>useJcloudsSshInit: false</code> 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).</p>
+ </li>
+ <li>
+ <p>Use <code>brooklyn.ssh.config.noDeleteAfterExec: true</code> 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. </p>
+ </li>
+</ul>
+
+<h6 id="custom-template-options">Custom Template Options</h6>
+
+<p>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.</p>
+
+<p>Part of the process for creating a virtual machine is the creation of a jclouds <code>TemplateOptions</code> object. jclouds
+providers extends this with extra options for each cloud - so when using the AWS provider, the object will be of
+type <code>AWSEC2TemplateOptions</code>. By <a href="https://github.com/jclouds/jclouds/blob/jclouds-1.9.0/providers/aws-ec2/src/main/java/org/jclouds/aws/ec2/compute/AWSEC2TemplateOptions.java">examining the source code</a>,
+you can see all of the options available to you.</p>
+
+<p>The <code>templateOptions</code> config key takes a map. The keys to the map are method names, and Brooklyn will find the method on
+the <code>TemplateOptions</code> 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.</p>
+
+<p>For example, here is a complete blueprint that sets some AWS EC2 specific options:</p>
+
+<pre><code>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']
+</code></pre>
+
+<p>Here you can see that we set three template options:</p>
+
+<ul>
+ <li><code>subnetId</code> is an example of a single parameter method. Brooklyn will effectively try to run the statement
+<code>templateOptions.subnetId("subnet-041c88373");</code></li>
+ <li><code>mapNewVolumeToDeviceName</code> 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 <code>templateOptions.mapNewVolumeToDeviceName("/dev/sda1", 100, true);</code></li>
+ <li><code>securityGroupIds</code> 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 <code>List</code>; such a method does exist so
+the operation will succeed.</li>
+</ul>
+
+<p>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.</p>
+
+<p>See the following resources for more information:</p>
+
+<ul>
+ <li><a href="vpc-issues.html">AWS VPC issues which may affect users with older AWS accounts</a></li>
+ <li><a href="http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-vpc.html#vpc-only-instance-types">Amazon EC2 and Amazon Virtual Private Cloud</a></li>
+ <li><a href="http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/default-vpc.html">Your Default VPC and Subnets</a></li>
+ <li><a href="http://aws.amazon.com/vpc/faqs/#Default_VPCs">Amazon VPC FAQs</a></li>
+</ul>
+
+<h3 id="more-details-on-specific-clouds">More Details on Specific Clouds</h3>
+
+<p>To connect to a Cloud, Brooklyn requires appropriate credentials. These comprise the <code>identity</code> and
+<code>credential</code> in Brooklyn terminology. </p>
+
+<p>For private clouds (and for some clouds being targeted using a standard API), the <code>endpoint</code>
+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 <code>region</code> where you might want to deploy. </p>
+
+<p>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:</p>
+
+<ul>
+ <li>The <strong><a href="/v/latest/start/brooklyn.properties">template brooklyn.properties</a></strong> 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.</li>
+ <li>The <strong><a href="https://jclouds.apache.org/guides">jclouds guides</a></strong> describes low-level configuration
+sometimes required for various clouds.</li>
+</ul>
+
+<h2 id="amazon-web-services-aws">Amazon Web Services (AWS)</h2>
+
+<h3 id="credentials">Credentials</h3>
+
+<p>AWS has an âaccess keyâ and a âsecret keyâ, which correspond to Brooklynâs identity and credential
+respectively.</p>
+
+<p>These keys are the way for any programmatic mechanism to access the AWS API.</p>
+
+<p>To generate an access key and a secret key, see <a href="http://jclouds.apache.org/guides/aws">jclouds instructions</a>
+and <a href="http://docs.aws.amazon.com/IAM/latest/UserGuide/ManagingCredentials.html">AWS IAM instructions</a>.</p>
+
+<p>An example of the expected format is shown below:</p>
+
+<pre><code>brooklyn.location.jclouds.aws-ec2.identity=ABCDEFGHIJKLMNOPQRST
+brooklyn.location.jclouds.aws-ec2.credential=abcdefghijklmnopqrstu+vwxyzabcdefghijklm
+</code></pre>
+
+<h3 id="tidying-up-after-jclouds">Tidying up after jclouds</h3>
+
+<p>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.</p>
+
+<p>There is utility written by Cloudsoft for deleting these unused resources:
+http://www.cloudsoftcorp.com/blog/2013/03/tidying-up-after-jclouds.</p>
+
+<h3 id="using-subnets-and-security-groups">Using Subnets and Security Groups</h3>
+
+<p>Apache Brooklyn can run with AWS VPC and both public and private subnets.
+Simply provide the <code>subnet-a1b2c3d4</code> as the <code>networkName</code> when deploying:</p>
+
+<pre><code>location:
+ jclouds:aws-ec2:
+ region: us-west-1
+ networkName: subnet-a1b2c3d4 # use your subnet ID
+</code></pre>
+
+<p>Subnets are typically used in conjunction with security groups.
+Brooklyn does <em>not</em> 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 <code>securityGroups</code> on the location
+or as <code>provisioning.properties</code> on the entities.</p>
+
+<p>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.</p>
+
+<h3 id="ec2-classic-problems-with-vpc-only-hardware-instance-types">EC2 âClassicâ Problems with VPC-only Hardware Instance Types</h3>
+
+<p>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 <code>minRam: 8gb</code>, Brooklyn may opt for an <code>m4.large</code>,
+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:</p>
+
+<pre><code>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.
+</code></pre>
+
+<p>This is a limitation of âlegacyâ accounts. The easiest fixes are either:</p>
+
+<ul>
+ <li>specify an instance type which is supported in classic, such as <code>m3.xlarge</code> (see below)</li>
+ <li>move to a different region where VPC is the default
+(<code>eu-central-1</code> should work as it <em>only</em> offers VPC mode,
+irrespective of the age of your AWS account)</li>
+ <li>get a new AWS account â âVPCâ will be the default mode
+(Amazon recommend this and if you want to migrate existing deployments
+they provide <a href="http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/vpc-migrate.html">detailed instructions</a>) </li>
+</ul>
+
+<p>To understand the situation, the following resources may be useful:</p>
+
+<ul>
+ <li>Background on VPC vs Classic: <a href="http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-vpc.html">http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-vpc.html</a></li>
+ <li>Good succinct answers to FAQs: <a href="">http://aws.amazon.com/vpc/faqs/#Default_VPCs</a></li>
+ <li>Check if a region in your account is âVPCâ or âClassicâ: <a href="">http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/default-vpc.html#default-vpc-availability</a> </li>
+ <li>Regarding instance types:
+ <ul>
+ <li>All instance types: <a href="">https://aws.amazon.com/ec2/instance-types</a></li>
+ <li>Those which require VPC: <a href="">http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-vpc.html#vpc-only-instance-types</a></li>
+ </ul>
+ </li>
+</ul>
+
+<p>If you want to solve this problem with your existing account,
+you can create a VPC and instruct Brooklyn to use it:</p>
+
+<ol>
+ <li>Use the âStart VPC Wizardâ option in <a href="https://console.aws.amazon.com/vpc">the VPC dashboard</a>,
+ making sure it is for the right region, and selecting a âSingle Public Subnetâ.
+ (More information is in <a href="http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/get-set-up-for-amazon-ec2.html#create-a-vpc">these AWS instructions</a>.)</li>
+ <li>Once the VPC is created, open the âSubnetsâ view and modify the âPublic subnetâ
+so that it will âAuto-assign Public IPâ.</li>
+ <li>Next click on the âSecurity Groupsâ and find the <code>default</code> 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â.)</li>
+ <li>Finally make a note of the subnet ID (e.g. <code>subnet-a1b2c3d4</code>) for use in Brooklyn.</li>
+</ol>
+
+<p>You can then deploy blueprints to the subnet, allowing VPC hardware instance types,
+by specifying the subnet ID as the <code>networkName</code> in your YAML blueprint.
+This is covered in the previous section, âUsing Subnetsâ.</p>
+
+<h2 id="google-compute-engine-gce">Google Compute Engine (GCE)</h2>
+
+<h3 id="credentials-1">Credentials</h3>
+
+<p>GCE uses a service account e-mail address for the identity and a private key as the credential.</p>
+
+<p>To obtain these from GCE, see the <a href="https://jclouds.apache.org/guides/google">jclouds instructions</a>.</p>
+
+<p>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 <code>\n</code> representing the new line characters:</p>
+
+<pre><code>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-----
+</code></pre>
+
+<h3 id="quotas">Quotas</h3>
+
+<p>GCE accounts can have low default <a href="https://cloud.google.com/compute/docs/resource-quotas">quotas</a>.</p>
+
+<p>It is easy to requesta quota increase by submitting a <a href="https://support.google.com/cloud/answer/6075746?hl=en">quota increase form</a>.</p>
+
+<h3 id="networks">Networks</h3>
+
+<p>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.</p>
+
+<p>To create a network, see <a href="https://cloud.google.com/compute/docs/networking#networks_1">GCE network instructions</a>.</p>
+
+<p>For example, for dev/demo purposes an âeverythingâ network could be created that opens all ports.</p>
+
+<table>
+ <tbody>
+ <tr>
+ <td>Â </td>
+ <td>Name</td>
+ <td>Â </td>
+ <td>everything</td>
+ </tr>
+ <tr>
+ <td>Â </td>
+ <td>Description</td>
+ <td>Â </td>
+ <td>opens all tcp ports</td>
+ </tr>
+ <tr>
+ <td>Â </td>
+ <td>Source IP Ranges</td>
+ <td>Â </td>
+ <td>0.0.0.0/0</td>
+ </tr>
+ <tr>
+ <td>Â </td>
+ <td>Allowed protocols and ports</td>
+ <td>Â </td>
+ <td>tcp:0-65535 and udp:0-65535</td>
+ </tr>
+ </tbody>
+</table>
+
+<h2 id="ibm-softlayer">IBM SoftLayer</h2>
+
+<h3 id="vlan-selection">VLAN Selection</h3>
+
+<p>SoftLayer may provision VMs in different VLANs, even within the same region.
+Some applications require VMs to be on the <em>same</em> internal subnet; blueprints
+for these can specify this behaviour in SoftLayer in one of two ways.</p>
+
+<p>The VLAN ID can be set explicitly using the fields
+<code>primaryNetworkComponentNetworkVlanId</code> and
+<code>primaryBackendNetworkComponentNetworkVlanId</code> of <code>SoftLayerTemplateOptions</code>
+when specifying the location being used in the blueprint, as follows:</p>
+
+<p><code>YAML
+location:
+ jclouds:softlayer:
+ region: ams01
+ templateOptions:
+ # Enter your preferred network IDs
+ primaryNetworkComponentNetworkVlanId: 1153481
+ primaryBackendNetworkComponentNetworkVlanId: 1153483
+</code></p>
+
+<p>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</p>
+
+<p>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.</p>
+
+<p>To use this method, we tell brooklyn to use <code>SoftLayerSameVlanLocationCustomizer</code>
+as a location customizer. This can be done on a location as follows:</p>
+
+<p><code>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
+</code></p>
+
+<p>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.</p>
+
+<p>It is also possible with many blueprints to specify this as one of the
+<code>provisioning.properties</code> on an <em>application</em>:</p>
+
+<p><code>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
+</code></p>
+
+<p>If you are writing an entity in Java, you can also use the helper
+method <code>forScope(String)</code> to create the customizer. Configure the
+provisioning flags as follows:</p>
+
+<p><code>Java
+JcloudsLocationCustomizer vlans = SoftLayerSameVlanLocationCustomizer.forScope("my-custom-scope");
+flags.put(JcloudsLocationConfig.JCLOUDS_LOCATION_CUSTOMIZERS.getName(), ImmutableList.of(vlans));
+</code></p>
+
+<h3 id="configuration-options">Configuration Options</h3>
+
+<p>The allowed configuration keys for the <code>SoftLayerSameVlanLocationCustomizer</code>
+are:</p>
+
+<ul>
+ <li>
+ <p><strong>softlayer.vlan.scopeUid</strong> The scope identifier for locations whose
+VMs will have the same VLAN.</p>
+ </li>
+ <li>
+ <p><strong>softlayer.vlan.timeout</strong> The amount of time to wait for a VM to
+be configured before timing out without setting the VLAN ids.</p>
+ </li>
+ <li>
+ <p><strong>softlayer.vlan.publicId</strong> A specific public VLAN ID to use for
+the specified scope.</p>
+ </li>
+ <li>
+ <p><strong>softlayer.vlan.privateId</strong> A specific private VLAN ID to use for
+the specified scope.</p>
+ </li>
+</ul>
+
+<p>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.</p>
+
+<p><strong><em>NOTE</em></strong> If the SoftLayer location is already configured with specific VLANs
+then this customizer will have no effect.</p>
+
+<h3 id="inheritance-and-named-locations">Inheritance and Named Locations</h3>
+
+<p>Named locations can be defined for commonly used groups of properties,
+with the syntax <code>brooklyn.location.named.your-group-name.</code>
+followed by the relevant properties.
+These can be accessed at runtime using the syntax <code>named:your-group-name</code> as the deployment location.</p>
+
+<p>Some illustrative examples using named locations and
+showing the syntax and properties above are as follows:</p>
+
+<div class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="c"># Production pool of machines for my application (deploy to named:prod1)</span>
+brooklyn.location.named.prod1<span class="o">=</span>byon:<span class="o">(</span><span class="nv">hosts</span><span class="o">=</span><span class="s2">"10.9.1.1,10.9.1.2,produser2@10.9.2.{10,11,20-29}"</span><span class="o">)</span>
+brooklyn.location.named.prod1.user<span class="o">=</span>produser1
+brooklyn.location.named.prod1.privateKeyFile<span class="o">=</span>~/.ssh/produser_id_rsa
+brooklyn.location.named.prod1.privateKeyPassphrase<span class="o">=</span>s3cr3tCOMPANYpassphrase
+
+<span class="c"># AWS using my company's credentials and image standard, then labelling images so others know they're mine</span>
+brooklyn.location.named.company-jungle<span class="o">=</span>jclouds:aws-ec2:us-west-1
+brooklyn.location.named.company-jungle.identity<span class="o">=</span>BCDEFGHIJKLMNOPQRSTU
+brooklyn.location.named.company-jungle.privateKeyFile<span class="o">=</span>~/.ssh/public_clouds/company_aws_id_rsa
+brooklyn.location.named.company-jungle.imageId<span class="o">=</span>ami-12345
+brooklyn.location.named.company-jungle.minRam<span class="o">=</span>2048
+brooklyn.location.named.company-jungle.userMetadata<span class="o">=</span><span class="nv">application</span><span class="o">=</span>my-jungle-app,owner<span class="o">=</span><span class="s2">"Bob Johnson"</span>
+brooklyn.location.named.company-jungle.machineCreateAttempts<span class="o">=</span>2
+
+brooklyn.location.named.AWS<span class="se">\ </span>Virginia<span class="se">\ </span>Large<span class="se">\ </span><span class="nv">Centos</span> <span class="o">=</span> jclouds:aws-ec2
+brooklyn.location.named.AWS<span class="se">\ </span>Virginia<span class="se">\ </span>Large<span class="se">\ </span>Centos.region <span class="o">=</span> us-east-1
+brooklyn.location.named.AWS<span class="se">\ </span>Virginia<span class="se">\ </span>Large<span class="se">\ </span>Centos.imageId<span class="o">=</span>us-east-1/ami-7d7bfc14
+brooklyn.location.named.AWS<span class="se">\ </span>Virginia<span class="se">\ </span>Large<span class="se">\ </span>Centos.user<span class="o">=</span>root
+brooklyn.location.named.AWS<span class="se">\ </span>Virginia<span class="se">\ </span>Large<span class="se">\ </span>Centos.minRam<span class="o">=</span>4096</code></pre></div>
+
+<p>Named locations can refer to other named locations using <code>named:xxx</code> as their value.
+These will inherit the configuration and can override selected keys.
+Properties set in the namespace of the provider (e.g. <code>b.l.jclouds.aws-ec2.KEY=VALUE</code>)
+will be inherited by everything which extends AWS
+Sub-prefix strings are also inherited up to <code>brooklyn.location.*</code>,
+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.</p>
+
+<p>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 <code>prod1</code>: </p>
+
+<!-- tested in JcloudsLocationResolverTest -->
+<div class="highlight"><pre><code class="language-bash" data-lang="bash">brooklyn.location.extraSshPublicKeyUrls<span class="o">=</span>http://me.com/public_key
+brooklyn.location.jclouds.aws-ec2.extraSshPublicKeyUrls<span class="o">=</span><span class="s2">"[ \"http://me.com/public_key\", \"http://me.com/aws_public_key\" ]"</span>
+brooklyn.location.named.prod1.extraSshPublicKeyUrls<span class="o">=</span></code></pre></div>
+
+<p>And in the example below, a config key is repeatedly overridden.
+Deploying <code>location: named:my-extended-aws</code> will result in an <code>aws-ec2</code> machine in <code>us-west-1</code> (by inheritance)
+with <code>VAL6</code> for <code>KEY</code>:</p>
+
+<div class="highlight"><pre><code class="language-bash" data-lang="bash">brooklyn.location.KEY<span class="o">=</span>VAL1
+brooklyn.location.jclouds.KEY<span class="o">=</span>VAL2
+brooklyn.location.jclouds.aws-ec2.KEY<span class="o">=</span>VAL3
+brooklyn.location.jclouds.aws-ec2@us-west-1.KEY<span class="o">=</span>VAL4
+brooklyn.location.named.my-aws<span class="o">=</span>jclouds:aws-ec2:us-west-1
+brooklyn.location.named.my-aws.KEY<span class="o">=</span>VAL5
+brooklyn.location.named.my-extended-aws<span class="o">=</span>named:my-aws
+brooklyn.location.named.my-extended-aws.KEY<span class="o">=</span>VAL6</code></pre></div>
+
+<h3 id="byon">BYON</h3>
+
+<p>â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.</p>
+
+<p>Your nodes must meet the following prerequisites:</p>
+
+<ul>
+ <li>A suitable OS must have been installed on all nodes</li>
+ <li>The node must be running sshd (or similar)</li>
+ <li>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 <a href="ssh-keys.html">here</a>.) </li>
+</ul>
+
+<p>To deploy to machines with known IPâs in a blueprint, use the following syntax:</p>
+
+<div class="highlight"><pre><code class="language-yaml" data-lang="yaml"><span class="l-Scalar-Plain">location</span><span class="p-Indicator">:</span>
+ <span class="l-Scalar-Plain">byon</span><span class="p-Indicator">:</span>
+ <span class="l-Scalar-Plain">user</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">brooklyn</span>
+ <span class="l-Scalar-Plain">privateKeyFile</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">~/.ssh/brooklyn.pem</span>
+ <span class="l-Scalar-Plain">hosts</span><span class="p-Indicator">:</span>
+ <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">192.168.0.18</span>
+ <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">192.168.0.19</span></code></pre></div>
+
+<p>Some of the login properties as described above for jclouds are supported,
+but not <code>loginUser</code> (as no users are created), and not any of the
+VM creation parameters such as <code>minRam</code> and <code>imageId</code>.
+(These clearly do not apply in the same way, and they are <em>not</em>
+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.</p>
+
+<p>Named locations can also be configured in your <code>brooklyn.properties</code>,
+using the format <code>byon:(key=value,key2=value2)</code>.
+For convenience, for hosts wildcard globs are supported.</p>
+
+<div class="highlight"><pre><code class="language-bash" data-lang="bash">brooklyn.location.named.On-Prem<span class="se">\ </span>Iron<span class="se">\ </span><span class="nv">Example</span><span class="o">=</span>byon:<span class="o">(</span><span class="nv">hosts</span><span class="o">=</span><span class="s2">"10.9.1.1,10.9.1.2,produser2@10.9.2.{10,11,20-29}"</span><span class="o">)</span>
+brooklyn.location.named.On-Prem<span class="se">\ </span>Iron<span class="se">\ </span>Example.user<span class="o">=</span>produser1
+brooklyn.location.named.On-Prem<span class="se">\ </span>Iron<span class="se">\ </span>Example.privateKeyFile<span class="o">=</span>~/.ssh/produser_id_rsa
+brooklyn.location.named.On-Prem<span class="se">\ </span>Iron<span class="se">\ </span>Example.privateKeyPassphrase<span class="o">=</span>s3cr3tpassphrase</code></pre></div>
+
+<p>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 <a href="/v/latest/ops/catalog/index.html#locations-in-catalog">catalog entry</a> for easy reusability.</p>
+
+<p>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
+<code>ssh -i ~/.ssh/brooklyn.pem -p 8022 myuser@50.51.52.53</code>. The second is a windows machine, reachable
+over WinRM. Each machine has also has a private address (e.g. for within a private network).</p>
+
+<div class="highlight"><pre><code class="language-yaml" data-lang="yaml"><span class="l-Scalar-Plain">location</span><span class="p-Indicator">:</span>
+ <span class="l-Scalar-Plain">byon</span><span class="p-Indicator">:</span>
+ <span class="l-Scalar-Plain">hosts</span><span class="p-Indicator">:</span>
+ <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">ssh</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">50.51.52.53:8022</span>
+ <span class="l-Scalar-Plain">privateAddresses</span><span class="p-Indicator">:</span> <span class="p-Indicator">[</span><span class="nv">10.0.0.1</span><span class="p-Indicator">]</span>
+ <span class="l-Scalar-Plain">privateKeyFile</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">~/.ssh/brooklyn.pem</span>
+ <span class="l-Scalar-Plain">user</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">myuser</span>
+ <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">winrm</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">50.51.52.54:8985</span>
+ <span class="l-Scalar-Plain">privateAddresses</span><span class="p-Indicator">:</span> <span class="p-Indicator">[</span><span class="nv">10.0.0.2</span><span class="p-Indicator">]</span>
+ <span class="l-Scalar-Plain">password</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">mypassword</span>
+ <span class="l-Scalar-Plain">user</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">myuser</span>
+ <span class="l-Scalar-Plain">osFamily</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">windows</span></code></pre></div>
+
+<p>The BYON location also supports a machine chooser, using the config key <code>byon.machineChooser</code>.
+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 <code>location.obtain()</code>) to find the config that matches the requirements of the entity being
+provisioned. See <code>FixedListMachineProvisioningLocation.MACHINE_CHOOSER</code>.</p>
+
+<h3 id="ssh-keys">SSH Keys</h3>
+
+<p>SSH keys are one of the simplest and most secure ways to access remote servers.
+They consist of two parts:</p>
+
+<ul>
+ <li>
+ <p>A private key (e.g. <code>id_rsa</code>) which is known only to one party or group</p>
+ </li>
+ <li>
+ <p>A public key (e.g. <code>id_rsa.pub</code>) 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)</p>
+ </li>
+</ul>
+
+<p>In this way, someone â such as you â can have a private key,
+and can install a public key on a remote machine (in an <code>authorized_keys</code> file)
+for secure automated access.
+Commands such as <code>ssh</code> (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.</p>
+
+<h4 id="creating-an-ssh-key">Creating an SSH Key</h4>
+
+<p>If you donât have an SSH key, create one with:</p>
+
+<div class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="nv">$ </span>ssh-keygen -t rsa -N <span class="s2">""</span> -f ~/.ssh/id_rsa</code></pre></div>
+
+<h4 id="localhost-setup">Localhost Setup</h4>
+
+<p>If you want to deploy to <code>localhost</code>, ensure that you have a public and private key,
+and that your key is authorized for ssh access:</p>
+
+<div class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="c"># _Appends_ id_rsa.pub to authorized_keys. Other keys are unaffected.</span>
+<span class="nv">$ </span>cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys</code></pre></div>
+
+<p>Now verify that your setup by running the command: <code>ssh localhost echo hello world</code></p>
+
+<p>If your setup is correct, you should see <code>hello world</code> printed back at you.</p>
+
+<p>On the first connection, you may see a message similar to this:</p>
+
+<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>
+
+<p>Simply answer âyesâ and then repeat the command again.</p>
+
+<p>If this isnât the case, see below. </p>
+
+<h4 id="potential-problems">Potential Problems</h4>
+
+<ul>
+ <li>
+ <p><strong>MacOS user?</strong> In addition to the above, enable âRemote Loginâ in âSystem Preferences > Sharingâ.</p>
+ </li>
+ <li>
+ <p><strong>Got a passphrase?</strong> Set <code>brooklyn.location.localhost.privateKeyPassphrase</code>
+as described <a href="index.html#os-setup">here</a>.
+If youâre not sure, or you donât know what a passphrase is, you can test this by executing <code>ssh-keygen -y</code>.
+If it does <em>not</em> ask for a passphrase, then your key has no passphrase.
+If your key does have a passphrase, you can remove it by running <code>ssh-keygen -p</code>.</p>
+ </li>
+ <li>
+ <p>Check that you have an <code>~/.ssh/id_rsa</code> file (or <code>id_dsa</code>) and a corresponding public key with a <code>.pub</code> extension;
+if not, create one as described above</p>
+ </li>
+ <li>
+ <p><code>~/.ssh/</code> 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 <code>ls -l ~/.ssh/</code>: lines should start with <code>-rw-------</code> or <code>-r--------</code> (or <code>-rwx------</code> for directories).
+If it does not, execute <code>chmod go-rwx ~/.ssh ~/.ssh/*</code>.</p>
+ </li>
+ <li>
+ <p>Sometimes machines are configured with different sets of support SSL/TLS versions and ciphers;
+if command-line <code>ssh</code> and <code>scp</code> work, but Brooklyn/java does not, check the versions enabled in Java and on both servers.</p>
+ </li>
+ <li>
+ <p>Missing entropy: creating and using ssh keys requires randomness available on the servers,
+usually in <code>/dev/random</code>; see <a href="/documentation/increase-entropy.html">here</a> for more information</p>
+ </li>
+</ul>
+
+<h3 id="localhost">Localhost</h3>
+
+<p>If passwordless ssh login to <code>localhost</code> and passwordless <code>sudo</code> is enabled on your
+machine, you should be able to deploy blueprints with no special configuration,
+just by specifying <code>location: localhost</code> in YAML.</p>
+
+<p>If you use a passpharse or prefer a different key, these can be configured as follows: </p>
+
+<div class="highlight"><pre><code class="language-bash" data-lang="bash">brooklyn.location.localhost.privateKeyFile<span class="o">=</span>~/.ssh/brooklyn_key
+brooklyn.location.localhost.privateKeyPassphrase<span class="o">=</span>s3cr3tPASSPHRASE</code></pre></div>
+
+<p>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 <a href="/v/latest/ops/catalog/index.html#locations-in-catalog">catalog entry</a> for easy reusability.</p>
+
+<p>If you encounter issues or for more information, see <a href="ssh-keys.html#localhost-setup">SSH Keys Localhost Setup</a>. </p>
+
+<p>If you are normally prompted for a password when executing <code>sudo</code> commands, passwordless <code>sudo</code> must also be enabled. To enable passwordless <code>sudo</code> for your account, a line must be added to the system <code>/etc/sudoers</code> file. To edit the file, use the <code>visudo</code> command:
+<div class="highlight"><pre><code class="language-bash" data-lang="bash">sudo visudo</code></pre></div>
+Add this line at the bottom of the file, replacing <code>username</code> with your own user:
+<div class="highlight"><pre><code class="language-bash" data-lang="bash">username <span class="nv">ALL</span><span class="o">=(</span>ALL<span class="o">)</span> NOPASSWD: ALL</code></pre></div>
+If executing the following command does not ask for your password, then <code>sudo</code> should be setup correctly:
+<div class="highlight"><pre><code class="language-bash" data-lang="bash">sudo ls</code></pre></div></p>
+
+<h3 id="specialized-locations">Specialized Locations</h3>
+
+<p>Some additional location types are supported for specialized situations:</p>
+
+<h4 id="single-host">Single Host</h4>
+
+<p>The spec <code>host</code>, taking a string argument (the address) or a map (<code>host</code>, <code>user</code>, <code>password</code>, etc.),
+provides a convenient syntax when specifying a single host.
+For example:</p>
+
+<div class="highlight"><pre><code class="language-yaml" data-lang="yaml"><span class="l-Scalar-Plain">services</span><span class="p-Indicator">:</span>
+<span class="p-Indicator">-</span> <span class="l-Scalar-Plain">type</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">org.apache.brooklyn.entity.webapp.jboss.JBoss7Server</span>
+ <span class="l-Scalar-Plain">location</span><span class="p-Indicator">:</span>
+ <span class="l-Scalar-Plain">host</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">192.168.0.1</span></code></pre></div>
+
+<p>Or, in <code>brooklyn.properties</code>, set <code>brooklyn.location.named.host1=host:(192.168.0.1)</code>.</p>
+
+<h4 id="the-multi-location">The Multi Location</h4>
+
+<p>The spec <code>multi</code> allows multiple locations, specified as <code>targets</code>,
+to be combined and treated as one location.
+When the first target is full, the next is tried, and so on:</p>
+
+<div class="highlight"><pre><code class="language-yaml" data-lang="yaml"><span class="l-Scalar-Plain">location</span><span class="p-Indicator">:</span>
+ <span class="l-Scalar-Plain">multi</span><span class="p-Indicator">:</span>
+ <span class="l-Scalar-Plain">targets</span><span class="p-Indicator">:</span>
+ <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">byon:(hosts=192.168.0.1)</span>
+ <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">jclouds:aws-ec2</span><span class="p-Indicator">:</span>
+ <span class="l-Scalar-Plain">identity</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">acct1</span>
+ <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">jclouds:aws-ec2</span><span class="p-Indicator">:</span>
+ <span class="l-Scalar-Plain">identity</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">acct2</span></code></pre></div>
+
+<p>The example above provisions the first node to <code>192.168.0.1</code>,
+then it provisions into <code>acct1</code> at Amazon if possible,
+and then to <code>acct2</code>.</p>
+
+<h4 id="the-server-pool">The Server Pool</h4>
+
+<p>The <code>ServerPool</code>
+ (<a href="/v/latest/misc/javadoc/org/apache/brooklyn/entity/machine/pool/ServerPool.html">javadoc</a>,
+ <a href="https://github.com/apache/brooklyn/tree/0.9.0/software/base/src/main/java/org/apache/brooklyn/entity/machine/pool/ServerPool.java">src</a>)</p>
+
+<p>entity type allows defining an entity which becomes available as a location.</p>
+
</div>
@@ -453,6 +1342,41 @@ can also be set <code>in </code>provisio
<div class="sub-item">
+ <a href="/v/latest/ops/locations/index.html#clouds" class="list-group-item sub-item section" section-target="#clouds">
+ Clouds
+ </a>
+
+
+ <a href="/v/latest/ops/locations/index.html#more-details-on-specific-clouds" class="list-group-item sub-item section" section-target="#more-details-on-specific-clouds">
+ More on Clouds
+ </a>
+
+
+ <a href="/v/latest/ops/locations/index.html#inheritance-and-named-locations" class="list-group-item sub-item section" section-target="#inheritance-and-named-locations">
+ Named Locations
+ </a>
+
+
+ <a href="/v/latest/ops/locations/index.html#byon" class="list-group-item sub-item section" section-target="#byon">
+ BYON
+ </a>
+
+
+ <a href="/v/latest/ops/locations/index.html#ssh-keys" class="list-group-item sub-item section" section-target="#ssh-keys">
+ SSH Keys
+ </a>
+
+
+ <a href="/v/latest/ops/locations/index.html#localhost" class="list-group-item sub-item section" section-target="#localhost">
+ Localhost
+ </a>
+
+
+ <a href="/v/latest/ops/locations/index.html#specialized-locations" class="list-group-item sub-item section" section-target="#specialized-locations">
+ Specialized Locations
+ </a>
+
+
<a href="/v/latest/ops/locations/location-customizers.html" class="list-group-item sub-item " >
Location Customizers
</a>
Modified: brooklyn/site/v/latest/ops/locations/location-customizers.html
URL: http://svn.apache.org/viewvc/brooklyn/site/v/latest/ops/locations/location-customizers.html?rev=1740156&r1=1740155&r2=1740156&view=diff
==============================================================================
--- brooklyn/site/v/latest/ops/locations/location-customizers.html (original)
+++ brooklyn/site/v/latest/ops/locations/location-customizers.html Wed Apr 20 15:19:21 2016
@@ -566,6 +566,55 @@ config option when calling <code>locatio
+ <a href="/v/latest/ops/locations/index.html#clouds" class="list-group-item">Clouds
+ </a>
+
+
+
+
+
+ <a href="/v/latest/ops/locations/index.html#more-details-on-specific-clouds" class="list-group-item">More on Clouds
+ </a>
+
+
+
+
+
+ <a href="/v/latest/ops/locations/index.html#inheritance-and-named-locations" class="list-group-item">Named Locations
+ </a>
+
+
+
+
+
+ <a href="/v/latest/ops/locations/index.html#byon" class="list-group-item">BYON
+ </a>
+
+
+
+
+
+ <a href="/v/latest/ops/locations/index.html#ssh-keys" class="list-group-item">SSH Keys
+ </a>
+
+
+
+
+
+ <a href="/v/latest/ops/locations/index.html#localhost" class="list-group-item">Localhost
+ </a>
+
+
+
+
+
+ <a href="/v/latest/ops/locations/index.html#specialized-locations" class="list-group-item">Specialized Locations
+ </a>
+
+
+
+
+
<a href="/v/latest/ops/locations/location-customizers.html" class="list-group-item active">Location Customizers
</a>