Configuration File Contents

There are three section types in a euca2ools configuration file: global, region, and user.

The user and region sections are named sections - you must specify a name for each of these sections. For example:

[user myusername]

[region ecc]

You can have as many named region and user sections as you need.

The region sections contain service URLs for the named region, as well as a reference to a named user section that contains the user's account ID and credentials. Once you've defined regions and users in the configuration file, you can specify the named region using the --region command line option or the EUCA_REGION environment variable. When you supply a region name it will use the URLs defined in the configuration file for that named region, and (unless overridden) the credentials from the user that region refers to (as defined by the user named in that region's definition).

The --region parameter lets you choose specific combinations of the users and regions defined in the configuration file with the format "user@region". For example:

This example will use the ecc region:

euca-describe-instances --region ecc

The following example will use the user defined in the [user jdoe] section of the configuration file with the region defined in the [region us-west-2] section of the configuration file:

euca-describe-instances --region jdoe@us-west-2

In this example, the user defined in the [user jdoe] section of the configuration file will be used with the default region specified in the global section of the configuration file:

euca-describe-instances --region jdoe@

If you don't supply a region you get the global default region (as defined in the global section of the configuration file).

If you don't supply a user at the command line, your command will use the region's default user.

Region Naming Rules for AWS

When naming region sections for use with AWS, the region name has to agree with the name assigned to the region by AWS if the AWS service uses signature version 4. You can add a "name" option to a region definition in the configuration file to explicitly tell euca2ools what name to send the server.

Reusing Options

You can re-use an option from another region in your region definition by using the 'use' keyword.

In the following example, the us-west-1 region is using the iam-url value defined in the us-east-1 section:

[region us-east-1]
iam-url = https://iam.amazonaws.com/
[region us-west-1]
iam-url = use us-east-1

Wildcard and Grouped Names

You can use "[region *]" or "[user *]" to refer to all regions or users. This is not the same as putting something in the "[global]" section. The more specific the user or region section's name is, the higher precedence it has, so options under "[user jdoe]" take precedence over those under "[user *]".

You can organize regions and users in the config files into groups, separated by : characters. For example:

 [region aws:us-east-1]
  ...
 [region aws:us-west-1]
  ...
 [region aws:*]
  ...

When section names contain wildcards, the most specific name takes precedence; for example, aws:us-east-1 takes precedence over aws:*.

When you refer to a region or user by a name like "us-east-1" and there isn't any configuration that exactly matches that name, euca2ools will attempt to find the closest match. For example, with only the configuration above, if you supply "--region us-east-1" at the command line it will use the configuration under "aws:us-east-1", but if you were to add "foo:us-east-1" then this would become ambiguous and result in an error.