2015/03/18 - Apache Whirr has been retired.

For more information, please explore the Attic.

Whirr™ Configuration Guide

Whirr is configured using a properties file, and optionally using command line arguments when using the CLI. Command line arguments take precedence over properties specified in a properties file.

For example working configurations, please see the recipes in the recipes directory of the distribution.

General Options

Name Command line option Default Description
whirr.config --config none A filename of a properties file containing properties in this table. Note that Whirr properties specified in this file all have a whirr.prefix.
whirr.service-name --service-name The default service for launching clusters The name of the service to use. You only need to set this if you want to use a non-standard service launcher.
whirr.cluster-name --cluster-name none The name of the cluster to operate on. E.g. hadoopcluster. The cluster name is used to tag the instances in some cloud-specific way. For example, in Amazon it is used to form the security group name.
whirr.terminate-all-on-launch-failure --terminate-all-on-launch-failure true Whether or not to automatically terminate all nodes when cluster launch fails for some reason.

Instance Templates Options

Name Command line option Default Description
whirr.instance-templates --instance-templates none The number of instances to launch for each set of roles in a service. E.g. 1 nn+jt,10 dn+ttmeans one instance with the roles nn(namenode) and jt(jobtracker), and ten instances each with the roles dn(datanode) and tt(tasktracker). Note that currently a role may only be specified in a single group.
whirr.instance-templates-max-percent-failures --instance-templates-max-percent-failures none The percentage of successfully started instances for each set of roles. E.g. 100 nn+jt,60 dn+ttmeans all instances with the roles nn(namenode) and jt(jobtracker) has to be successfully started, and 60% of instances has to be successfully started each with the roles dn(datanode) and tt(tasktracker), otherwise a retry step is initiated with the number of nodes equal with the missing nodes per role compared to instance-templatesvalue. If after the retry the percentage of successfully started instances is still behind the limit, then the cluster startup is considered invalid. In a valid cluster startup, with or without retry mechanism, all the failed nodes will be cleaned up immediately. Only the completely failed cluster may leave unterminated failed nodes. Default value is 100 for each roles, in that case we don't need to use this parameter at all. In case we would like to lower the limit from 100% to 60% for only the dd(datanode) and tt(tasktracker), then we can specify 60 dn+ttfor the parameter and we may left the 100 nn+jt,from the beginning of the value.
whirr.instance-templates-minimum-number-of-instances --instance-templates-minimum-number-of-instances none The minimum number of successfully started instances for each set of roles. E.g. 1 nn+jt,6 dn+ttmeans 1 instance with the roles nn(namenode) and jt(jobtracker) has to be successfully started, and 6 instances has to be successfully started each with the roles dn(datanode) and tt(tasktracker), otherwise a retry step is initiated with the number of nodes equal with the missing nodes per role compared to instance-templatesvalue. If after the retry the number of successfully started instances i still behind the limit, then the cluster startup is considered invalid. In a valid cluster startup, with or without retry mechanism, all the failed nodes will be cleaned up immediately. Only the completely failed cluster may leave unterminated failed nodes. Note that we may specify only 6 dd+tt, in that case the limit will be applied only to the specified role. Default value is 100 for each roles, in that case we don't need to use this parameter at all. In case we would like to lower the limit for only the dd(datanode) and tt(tasktracker), then we can specify 60 dn+ttfor the parameter, skipping the 100 nn+jt.
whirr.max-startup-retries --max-startup-retries 1 The number of retries in case of insufficient successfully started instances.
whirr.aws-ec2-spot-price --aws-ec2-spot-price none Spot instance price. If the price isn't fulfilled it times out after 20 minutes (jclouds.compute.timeout.node-running). We recommended that you set the spot price to current real price so that you will always save money while keeping the instances running because you will still pay the spot price and not the max value you put in. Keep in mind that price spikes can still take out some instances, or prevent requests being filled, but it works well most of the time. Note: this is an EC2 specific option.

Cloud Provider Options

Name Command line option Default Description
whirr.provider --provider aws-ec2 The name of the cloud provider. See the table below for possible provider names.
whirr.location-id --location-id none The location to launch instances in. If not specified then an arbitrary location will be chosen.
whirr.endpoint --endpoint none Specifies the url of the compute provider. For example, for openstack-nova, it is the keystone url, like: http://localhost:5000/v2.0/. If not specified, it is the default for the provider
whirr.identity --identity none The cloud identity. See the table below for how this maps to the credentials for your provider.
whirr.credential --credential none The cloud credential. See the table below for how this maps to the credentials for your provider.
whirr.bootstrap-user --bootstrap-user none Override the default login user used to bootstrap whirr. E.g. ubuntu or myuser:mypass

You can see a list of all the available compute providers by running:

$ whirr list-providers compute

Note: we are testing only on aws-ec2 and cloudserver-us.

BlobStore Provider Options

Name Command line option Default Description
whirr.blobstore-provider --blobstore-provider Computed from whirr.provider The name of the blobstore provider. All jclouds blobstore providers are supported
whirr.blobstore-endpoint --blobstore-endpoint none Specifies the url of the blobstore provider. For example, for swift-keystone, it is the keystone url, like: http://localhost:5000/v2.0/. If not specified, it is the default for the provider
whirr.blobstore-identity --blobstore-identity whirr.identity The blobstore identity. See the table below for how this maps to the credentials for your provider.
whirr.blobstore-credential --blobstore-credential whirr.credential The blobstore credential. See the table below for how this maps to the credentials for your provider.
whirr.blobstore-location-id --blobstore-location-id As close as possible to the compute nodes The blobstore location ID
whirr.blobstore-cache-container --blobstore-cache-container Random container automatically removed at the end of the session The name of the container that Whirr should use to cache local files

You can see a list of all the available blobstore providers by running

$ whirr list-providers blobstore

Note: we are testing only on aws-s3 and cloudfiles-us.

Cluster State Store Options

Name Command line option Default Description
whirr.state-store --state-store local What kind of store to use for cluster state (local, blob or none).
whirr.state-store-container --state-store-container none Container where to store state. Valid only for the blob state store.
whirr.state-store-blob --state-store-blob whirr-< whirr.cluster-name> Blob name for state storage. Valid only for the blob state store.

Instance Login Options

Name Command line option Default Description
whirr.cluster-user --cluster-user Current local user The name of the user that Whirr will create on all instances. This is the user you should use to access the cluster.
whirr.private-key-file --private-key-file ~/.ssh/id_rsa The filename of the private RSA SSH key used to connect to instances. Note: the public/private key must be set together, and must be passwordless.
whirr.public-key-file --public-key-file ~/.ssh/id_rsa.pub The filename of the public RSA SSH key used to connect to instances. Note: the public/private key must be set together, and must be passwordless.

Image and Hardware Selection Options

Name Command line option Default Description
whirr.template --template osFamily=UBUNTU,osVersionMatches=10.04,minRam=1024 The specification of requirements for instances in jclouds TemplateBuilderSpec format. For example, this can control the ram, cores, os, and login user details.
whirr.image-id --image-id none The ID of the image to use for instances. If not specified then a vanilla Linux image is chosen.
whirr.hardware-id --hardware-id none The type of hardware to use for the instance. This must be compatible with the image ID.
whirr.hardware-min-ram --hardware-min-ram 1024 The minimum amount of RAM each instance should have

Firewall and DNS-Related Options

Name Command line option Default Description
whirr.client-cidrs --client-cidrs none A comma-separated list of CIDRblocks. E.g. 208.128.0.0/11,108.128.0.0/11
whirr.firewall-rules --firewall-rules none A comma-separated list of port numbers to open. E.g. 8080,8181.
whirr.firewall-rules.{role} --firewall-rules.{role} none A comma-separated list of port numbers to open on instances with a specific role. Replace {role} the actual role name. E.g. whirr.firewall-rules.hbase-master=10101.
whirr.store-cluster-in-etc-hosts --store-cluster-in-etc-hosts false Whether to store all cluster IPs and hostnames in /etc/hosts on each node.

Cloud provider specific configuration

Compute Service Provider whirr.provider whirr.identity whirr.credential Notes
Amazon EC2 aws-ec2 Access Key ID Secret Access Key Used to form security Group (via jclouds tag)
Rackspace Cloud Servers cloudservers-us Username API Key Warning: clusters do not run behind a firewall.

Relevant jclouds configuration options

Name Default Unit Description
jclouds.compute.timeout.node-terminated 30000 (30 sec.) msec The max. time to wait for nodes to be terminated
jclouds.compute.timeout.node-running 120000 (2 min.) msec The max. time to wait for nodes to be in running state
jclouds.compute.timeout.script-complete 600000 (10 min.) msec The max. time to wait for a script to complete execution
jclouds.compute.timeout.port-open 30000 (30 sec.) msec The max. time to wait for nodes to wait for the ssh port to open on newly lauched nodes
jclouds.ssh.retryable-messages failed to send channel request, channel is not opened, invalid data, End of IO Stream Read, Connection reset, connection is closed by foreign host, socket is not established -- Comma-separated list of error messages upon receiving which jclouds retries the ssh action.
jclouds.ssh.max-retries 7 times The max. number of retries jclouds will attempt a failed ssh action. The period between tries increases from 200ms -> 2 seconds per math.pow(attempt, 2)
jclouds.ssh.retry-auth true boolean Whether jclouds should retry ssh actions on authentication failed errors.
jclouds.compute.blacklist-nodes -- Comma-separated list of nodes that we shouldn't attempt to list as they are dead in the provider for some reason.