mr.awsome 1.0rc7

A script allowing to setup Amazon EC2 instances through configuration files.

Contents

• Overview

• Installation

• Configuration

• Plugins

  • Plain

    • Options

• SSH integration

• Macro expansion

• Massaging of config values

• Changelog

  • 1.0rc7 - 2014-06-11

  • 1.0rc6 - 2014-06-10

  • 1.0rc5 - 2014-06-09

  • 1.0rc4 - 2014-05-21

  • 1.0rc3 - 2014-05-15

  • 1.0rc2 - 2014-05-14

  • 1.0rc1 - 2014-03-23

  • 0.13 - 2013-09-20

  • 0.12 - 2013-09-11

  • 0.11 - 2012-11-08

  • 0.10 - 2012-06-04

  • 0.9 - 2010-12-09

  • 0.8 - 2010-04-21

  • 0.7 - 2010-03-22

  • 0.6 - 2010-03-18

  • 0.5 - 2010-03-11

  • 0.4 - 2010-02-18

  • 0.3 - 2010-02-08

  • 0.2 - 2010-02-02

  • 0.1 - 2010-01-21

Overview

mr.awsome is a commandline-tool (aws) to provision, manage and control server instances. What kind of server instances these are depends on the used plugins. There are plugins for EC2 (mr.awsome.ec2), FreeBSD Jails (mr.awsome.ezjail) and more. You can create, delete, monitor and ssh into instances while mr.awsome handles the details like ssh fingerprint checking. Additional plugins provide advanced functionality like integrating Fabric (mr.awsome.fabric) and Ansible (mr.awsome.ansible).

Installation

mr.awsome is best installed with easy_install, pip or with zc.recipe.egg in a buildout. It installs two scripts, aws and assh.

With zc.recipe.egg you can set a custom configfile location like this:

[aws]
recipe = zc.recipe.egg
eggs = mr.awsome
arguments = configpath="${buildout:directory}/etc/", configname="servers.cfg"

As of this writing the pycrypto package is throwing some deprecation warnings, you might want to disable them by adding an initialization option to the aws part like this:

initialization =
    import warnings
    warnings.filterwarnings("ignore", ".*", DeprecationWarning, "Crypto\.Hash\.MD5", 6)
    warnings.filterwarnings("ignore", ".*", DeprecationWarning, "Crypto\.Hash\.SHA", 6)
    warnings.filterwarnings("ignore", ".*", DeprecationWarning, "Crypto\.Util\.randpool", 40)

Configuration

All information about server instances is located in aws.conf, which by default is looked up in etc/aws.conf.

Plugins

Support for backends and further functionality is implemented by plugins. One plugin is included with mr.awsome.

plain

For regular servers accessible via ssh.

Plain

With plain instances you can put infos about servers into the configuration to benefit from some mr.awsome features like ssh fingerprint checking and plugins like the Fabric integration.

Options

host or ip

(required) The host name or address for the server.

user

The default user for ssh connections. If it’s set to * then the current local user name is used.

port

The ssh port number.

fingerprint

(required) The ssh fingerprint of the server. If set to ask then manual interactive verification is enabled. If set to ignore then no verification is performed at all!

password-fallback

If this boolean is true, then using a password as fallback is enabled if the ssh key doesn’t work. This is off by default.

password

Never use this directly! If password-fallback is enabled this password is used. This is mainly meant for Fabric scripts which have other ways to get the password. On use case is bootstrapping FreeBSD from an mfsBSD distribution where the password is fixed.

proxyhost

The id of another instance declared in aws.conf which is used to create a tunnel to the ssh port of this instance.

proxycommand

The command to use in the ProxyCommand option for ssh when using the assh command. There are some variables which can be used:

path

The directory of the aws.conf file. Useful if you want to use the assh command itself for the proxy.

known_hosts

The absolute path to the known_hosts file managed by mr.awsome.

instances

The variables of other instances. For example: instances.foo.ip

In addition to these the variables of the instance itself are available.

A full example for a proxycommand:

proxycommand = {path}/../bin/assh vm-master -W {ip}:22

SSH integration

mr.awsome provides an additional tool assh to easily perform SSH based operations against named instances. Particularly, it encapsulates the entire SSH fingerprint mechanism. For example EC2 instances are often short-lived and normally trigger warnings, especially, if you are using elastic IPs.

Note:: it does so not by simply turning off these checks, but by transparently updating its own fingerprint list using mechanisms provided by the backend plugins.

The easiest scenario is simply to create an SSH session with an instance. You can either use the ssh subcommand of the aws tool like so:

aws ssh SERVERNAME

Alternatively you can use the assh command directly, like so:

assh SERVERNAME

The latter has been provided to support scp and rsync. Here are some examples, you get the idea:

scp -S `pwd`/bin/assh some.file demo-server:/some/path/
rsync -e "bin/assh" some/path fschulze@demo-server:/some/path

Macro expansion

In the aws.conf you can use macro expansion for cleaner configuration files. That looks like this:

[ec2-instance:demo-server2]
<= demo-server
securitygroups = demo-server2

[ec2-securitygroup:demo-server2]
<= demo-server

All the options from the specified macro are copied with some important exceptions depending on the backend:

• For instances the ip and volumes options aren’t copied.

If you want to copy data from some other kind of options, you can add a colon in the macro name. This is useful if you want to have a base for instances like this:

[macro:base-instance]
keypair = default
region = eu-west-1
placement = eu-west-1a

[ec2-instance:server]
<= macro:base-instance
...

Massaging of config values

Plugins and mr.awsome massage certain string values from the config to convert them to other types and do formatting or expansion.

You can use that yourself, which is useful for the Fabric integration and other things.

Here is a simple example:

[section]
massagers =
  intvalue=mr.awsome.config.IntegerMassager
  boolvalue=mr.awsome.config.BooleanMassager
intvalue = 1
boolvalue = yes

If you now access those values from for example a fabric task, you get the correct type instead of strings.

The above syntax registers the massagers only for that section. You can register massagers for other sections or even section groups with this syntax:

massagers =
  [option]=[sectiongroup]:import.path.to.massager
  [option]=[sectiongroup]:[section]:import.path.to.massager

The parts have the following meaning:

[option]

This is the name of the option which should be massaged

[sectiongroup]

The name of the section group. That’s the part before the optional colon in a section. To match sections without a colon, use global. To match every section, use *.

[section]

The name of the section to which this massager is applied. If empty, the current section is used.

Changelog

1.0rc7 - 2014-06-11

• Expose some test fixtures for reuse in plugins. [fschulze]

• Add before_terminate and after_start hooks and make it simple for plugins to add their own hooks. [fschulze]

1.0rc6 - 2014-06-10

• Add get_path method to ConfigSection class. [fschulze]

1.0rc5 - 2014-06-09

• Provide helper method ssh_args_from_info on BaseInstance to get the arguments for running the ssh executable from the info provided by init_ssh_key. [fschulze]

• Allow overwriting the command name in help messages for bsdploy. [fschulze]

• Make debug command usable for instances that don’t have a startup script. [fschulze]

• Instances can provide a get_port method to return a default port. [fschulze]

• Catch socket errors in init_ssh_key of plain instances to print additional info for debugging. [fschulze]

• Delay setting of config file path to expose too early use of config in plugins. Refs #29 [fschulze]

1.0rc4 - 2014-05-21

• Fix massagers for [instance:...] sections. [fschulze]

• Copy massagers in ConfigSection.copy, so overrides in startup script work correctly. [fschulze]

1.0rc3 - 2014-05-15

• Fetch fingerprints only when necessary. This speeds up connections when the fingerprint in known_hosts is still valid. [fschulze]

1.0rc2 - 2014-05-14

• Moved setuptools-git from setup.py to .travis.yml, it’s only needed for releases and testing. [fschulze]

• More tests. [fschulze]

1.0rc1 - 2014-03-23

• Test, enhance and document adding massagers via config. [fschulze]

• Moved ec2 and fabric integration into separate plugins. [fschulze]

• You can now have instances with the same name if the belong to different masters, they will then get the name of the master as a prefix to their name. [fschulze]

• Add possibility to overwrite the default config name. [tomster]

• Improved proxycommand and documented it. [fschulze]

• Make the AWS instance available in masters. This changes the get_masters plugin interface. [fschulze]

• Use os.execvp instead of subprocess.call. This allows the use of assh in the proxycommand option, which greatly simplifies it’s use. [fschulze]

• Added command plugin hooks. [fschulze]

• The variable substitution for the proxycommand option now makes the other instances available in a dict under instances. And adds known_hosts. [fschulze]

• Load plugins via entry points instead of the plugin section in the config. [fschulze]

• Allow fallback to password for ssh to plain instances. [fschulze]

• Add option to ask for manual fingerprint validation for plain instances. [fschulze]

0.13 - 2013-09-20

• Use os.path.expanduser on all paths, so that one can use ~ in config values like the aws keys. [fschulze]

0.12 - 2013-09-11

• There is no need to add the AWS account id to security group names anymore. [fschulze]

• Rules are removed from security groups if they aren’t defined in the config. [fschulze]

• Allow adding of custom config massagers from inside the config. [fschulze]

• Support block device maps to enable use of more than one ephemeral disk. [fschulze]

• Added do method on ec2 and plain instances which allows to call fabric commands. [fschulze]

• Use PathMassager for access-key-id and secret-access-key in the ec2-master section. This might break existing relative paths for these options. [fschulze]

• Added support for EBS boot instances. [fschulze]

• Add option ssh-key-filename to point to a private ssh key for ec2 and plain instances. [fschulze]

• Fix Fabric integration for newer versions of Fabric. [fschulze]

• Support proxycommand option for plain instances. This also caused a change in the init_ssh_key API for plugins. [fschulze]

• Support ProxyCommand from ~/.ssh/config for plain instances. Requires Fabric 1.5.0 and Paramiko 1.9.0 or newer. [fschulze]

0.11 - 2012-11-08

• Support both the ssh and paramiko libraries depending on which Fabric version is used. [fschulze]

0.10 - 2012-06-04

• Added ec2-connection which helps in writing Fabric scripts which don’t connect to a server but need access to the config and AWS (like uploading something to S3). [fschulze]

• Fix several problems with using a user name other than root for the do and ssh commands. [fschulze]

• Require Fabric >= 1.3.0. [fschulze]

• Require boto >= 2.0. [fschulze]

• Added hook for startup script options. [fschulze]

• Added possibility to configure hooks. [fschulze]

• Refactored to enable plugins for different virtualization or cloud providers. [fschulze]

• Added lots of tests. [fschulze]

0.9 - 2010-12-09

• Overwrites now also affect server creation, not just the startup script. [fschulze]

• Added list command which supports just listing snapshots for now. [fschulze]

• Added delete-volumes-on-terminate option to delete volumes created from snapshots on instance termination. [fschulze]

• Added support for creating volumes from snapshots on instance start. [natea, fschulze]

• Added support for ~/.ssh/config. This is a bit limited, because the paramiko config parser isn’t very good. [fschulze]

• Added help command which provides some info for zsh autocompletion. [fschulze]

0.8 - 2010-04-21

• For the do command the Fabric options reject_unknown_hosts and disable_known_hosts now default to true. [fschulze]

• Allow adding normal servers to use with ssh and do commands. [fschulze]

• Refactored ssh connection handling to only open network connections when needed. Any fabric option which doesn’t need a connection runs right away now (like -h and -l). [fschulze]

• Fix status output after start. [fschulze]

0.7 - 2010-03-22

• Added snapshot method to Server class for easy access from fabfiles. [fschulze]

0.6 - 2010-03-18

• It’s now possible to specify files which contain the aws keys in the [aws] section with the access-key-id and secret-access-key options. [fschulze]

• Added -c/--config option to specify the config file to use. [fschulze]

• Added -v/--version option. [tomster (Tom Lazar), fschulze]

• Comment lines in the startup script are now removed before any variables in it are expanded, not afterwards. [fschulze]

• Use argparse library instead of optparse for more powerful command line parsing. [fschulze]

0.5 - 2010-03-11

• Added gzipping of startup script by looking for gzip: prefix in the filename. [fschulze]

• Added macro expansion similar to zc.buildout 1.4. [fschulze]

0.4 - 2010-02-18

• Check console output in status and tell user about it. [fschulze]

• Friendly message instead of traceback when trying to ssh into an unavailable server. [fschulze]

• Remove comment lines from startup script if it’s starting with #!/bin/sh or #!/bin/bash. [fschulze]

• Removed -r option for start and debug commands and replaced it with more general -o option. [fschulze]

• Made startup script optional (not all AMIs support it, especially Windows ones). [fschulze]

• The stop command actually only stops an instance now (only works with instances booted from an EBS volume) and the new terminate command now does what stop did before. [fschulze]

• Better error message when no console output is available for ssh finger print validation. [fschulze]

• Fixed indentation in documentation. [natea (Nate Aune), fschulze]

0.3 - 2010-02-08

• Removed the [host_string] prefix of the do command output. [fschulze]

0.2 - 2010-02-02

• Snapshots automatically get a description with date and volume id. [fschulze]

• The ssh command can now be used with scp and rsync. [fschulze]

0.1 - 2010-01-21

• Initial release [fschulze]