Introduction to Bellatrix commands

Bellatrix automates the interaction with EC2 Amazon Web Services. It uses the boto library and others. The goal of Bellatrix is to wrap the underlying libraries in easy to use utilities that are both simple and consistent.

Installing Bellatrix

If you already have pip installed, just execute:

pip install bellatrix

Another option is to go to: download the .tar.gz package and then:

tar xvzf bellatrix-[version].tar.gz
cd belatrix-[version]
python   #this will require admin access

Setting your AWS credentials

Bellatrix only needs three single files in order to help you access your AWS EC2 resources. Not all the tools need all the files. If they are not present Bellatrix will show a nice message explaining what file (and where) you need to provide.

  • Access key id
    • Location <your_home>/.bellatrix/key:

      Your 'access key id' will be something like AKIAIU**************) and is part of your AWS security credentials.
      If you don't remember it please sign into:
  • Secret file
    • Location <your_home>/.bellatrix/secret:

      The file should contain your 'secret access key' (a string with an approximate length of 50 characters).
      It is part of your AWS security credentials.
      In order to get your secret file please sign into:
  • Private key
    • Location <your_home>/.bellatrix/

      This file is the private key to use in order to connect to your instance.
      You need to specify before a key-pair in your AWS account. For more details, please refer to:
      The private key file is only used by the 'provision' and 'bewitch' commands.

Displaying your EC2 instances

Since running EC2 instances cost you money, this command will print information about your instances (running or not) and a useful summary at the very end. You only need to execute:

bellatrix list

The command will display an output similar to this:

adrian@adrian-packard-bell:~/b$ bellatrix list
2012-04-01 12:26:02,891 INFO listing...
2012-04-01 12:26:02,913 INFO Getting instances information... (this operation usually takes some seconds)
Instance:i-d67a61b2 | architecture:x86_64 | dns_name: | hypervisor:xen | image_id:ami-6fa27506 | instance_type:t1.micro | kernel:aki-825ea7eb | key_name:key | launch_time:2012-04-01T02:13:55.000Z | private_dns_name: | public_dns_name: | root_device_name:/dev/sda1 | root_device_type:ebs | state:terminated | virtualizationType:paravirtual

Instance:i-dc756eb8 | architecture:x86_64 | | hypervisor:xen | image_id:ami-6fa27506 | instance_type:t1.micro | ip_address: | kernel:aki-825ea7eb | key_name:key | launch_time:2012-04-01T02:25:23.000Z | private_dns_name:ip-10-202-17-35.ec2.internal | private_ip_address: | | root_device_name:/dev/sda1 | root_device_type:ebs | state:running | virtualizationType:paravirtual

Running instances (you pay for them):1
Total instances:2

Please remember that you only pay for your running instances. Your stopped instances will generate a very small cost due to the use of an EBS disk. So far the cost is equal to $0.10 per allocated GB per month (

Starting an EC2 instance

In order to start an instance, just type:

bellatrix start ami key_name

The complete usage, with optional parameters is:

bellatrix start [--security_groups [SECURITY_GROUPS]] [--type [type]] [--new_size [NEW_SIZE]] ami key_name

Once this command has finished, it will generate an output file called start_instance_out with the instance code and the dns name so you can access it in a browser or through ssh. The format will be similar to this line:


This file can be used to “chain” commands together.

Parameters list

  • ami - Amazon Machine Image. A pre-configured operating system with its applications.
  • key_name - Name of the ssh key-pair name that will be applied to your instance.
    • The key name is the name of the two files (public and private keys) that you can use to connect to your EC2 instance.

    • AWS will put the public key file in the instance while you need to use the private key file to connect to your instance:

      ssh -i private_key_file user@public_dns
    • In order to generate your ‘key name’, please refer to:

    • If you are starting a Windows AMI then you would normally use RDP instead of this ssh key.

  • [optional] –security_groups [SECURITY_GROUPS]
    • Comma separated list (with no spaces) of the security groups that will be applied to the new instance.
    • It can be only one. By default it will be “default”
  • [optional] –type type.
    • Instance type. The same AMI can be launched with different ‘hardware’ options.

    • You can choose between:
      • m1.small,m1.medium,m1.large,m1.xlarge,t1.micro,m2.xlarge,m2.2xlarge,m2.4xlarge,c1.medium,c1.xlarge,cc1.4xlarge,cc2.8xlarge
      • By default you will get t1.micro.
    • Please take a look at: for more information.

  • [optional] –new_size NEW_SIZE (in giga bytes).
    • An EBS AMI can be started with a larger size just by using this option. If you then save the instance into a new AMI then this will be the disk size of the AMI.

    • Providing a larger size doesn’t mean you will be able to access it straight away. If the file system is ext4, then you are done. If not, you will need to execute one of this commands:

      # ext3 root file system (most common)
      sudo resize2fs /dev/sda1
      sudo resize2fs /dev/xvda1
      # XFS root file system (less common):
      sudo apt-get update && sudo apt-get install -y xfsprogs
      sudo xfs_growfs /
      # In the case of Windows, you can use the graphical administration tools.

Provisioning an EC2 instance or any host

Provision an instance means you will execute a set of commands on it. Typically in order to apply some configuration. Your set of commands can be anything you want, even the execution of a Puppet script ;) Bellatrix provides a large set of ready to use commands but it is very easy to use your own. As a suggestion if you are adding a new command, you may want to make it idempotent, which means executing it once should have the same effect that multiple executions, for example using ‘mkdir -p dir’ instead of ‘mkdir dir’.

The provision command is generic and can be used with any host, EC2 instances or not. Windows machines with an SSH server can be used too.

Usage example:

bellatrix provision [--private_key [PRIVATE_KEY]] configuration user hostname

Parameters list

  • configuration - Python configuration file. E.g. This is how a configuration command looks like:

    Simple example of a configuration file for the provisioning command.
    #commands library from Bellatrix
    #The source file can be found here:
    # and the documentation here:
    from bellatrix.lib import cmds
    commands = cmds.apt_get_update()
    commands = cmds.install_pip()
    commands += cmds.pip_install("virtualenv")
    commands += ['echo "Adding my own command :)" > test', 'cat test']

The previous example can be found here: Another, more complex example of a configuration file can be found here: Here is the commands documentation:

  • user - User used to connect to the host. E.g. ubuntu
  • hostname - Hostname or simply the ip of the machine.
  • [optional] –private_key PRIVATE_KEY - In case we need to specify a private key to connect to the host. This is empty by default. If you are using an EC2 instance you will typically use the default private key located in ~/.bellatrix/

Saving the state of an instance into a new Amazon AMI

If you want to capture the current state of your EC2 instance into a new AMI, you just need to call this command:

bellatrix burn [--wait [{true,false}] instance image_name

Parameters list

  • instance - Instance name. Something like: “i-b63c98d4”. The instance should be running when you invoke this command.

  • image_name - This will be the name of your AMI. A time stamp will be added, so you can apply the same name and more importantly, identify when each version was generated.

  • –wait [true, false]
    • This is false by default.
    • Burning a new image usually takes some minutes. If you don’t use this option (or you set it to false) this command will show you the AMI code being burned and then finish immediately, but if you use “–wait=true” the burn command will finish only when the AMI is ready to be used.

Copying files to a S3 bucket

This command will copy a file or directory to a S3 bucket. You can imagine S3 as an encripted ‘infinite’ disk in the AWS cloud. Your files and directory structure will be put into a bucket that you need to create first. After you copy your files you can access them in: This is how you use this command:

bellatrix copy2s3 source bucket [key_prefix] [{private,public-read,public-read-write,authenticated-read}]

Paramaters list

  • source - Source file or directory in your computer.

  • bucket - S3 bucket destination. Please remember to create it first. A bucket needs to be unique.

  • key_prefix - This prefix will be added to the source path we copy. It is blank by default.

  • {private,public-read,public-read-write,authenticated-read}
    • With this option you control who can access your files in the S3 bucket. If you don’t specify anything the policy will be private by default.

Setting launch permissions to an AMI

If you choose your AMI to be private (option by default) you can still give permissions to other accounts so they can access it. In order to do so, just execute this command:

bellatrix perm2ami ami permissions_file

Paramaters list

  • ami - AMI name. Something like ami-6ba27502
  • permissions_file. Text file with an account number (12 digits number without dashes) on each line.

Stopping an EC2 instance

With this command, you can stop a given instance or all of them if you pass the “all” argument. Stopping an instance will shut-down the instance but will preserve data on the EBS volume. You won’t pay for the more expensive computing capacity. The only charge after you stop an instance is $0.10 per allocated GB per month ( After you stop an instance, you can start it and access to the same data:

bellatrix stop [-h] instance

Paramaters list

  • instance - Instance id. Something like i-39e2075d. If you pass all then all instances will be stopped.

Terminating an EC2 instance

Terminate a given instance or all of them if you pass the all parameter. Terminating an instance will shut it down and delete the data on the EBS volume. Your instance/s won’t produce any cost after you terminate them.:

bellatrix terminate [-h] instance

Paramaters list

  • instance - Instance id. Something like i-39e2075d. If you pass all then all running instances will be terminated (unless they are explicitly protected by the “disable termination” flag.)

Bewitching an AMI or how to start, provision and burn with a single command

This is a macro-command, that will:
  • Start a new instance,
  • apply a configuration (provision command) to it
  • and if all the commands were successful, it will save the instance into a new ami (burn command).

This is how you use it:

bellatrix bewitch [-h] configuration

Paramaters list

  • configuration - Python configuration file. E.g. It is just a simple Python file with some attributes on it like:
    • amis - This is the list of ami’s that will be executed.
      • Something like:

        amis = [
               ["ami-fd589594",  "ubuntu1104-ff36-mysql51-x64"],
      • As you can see we define in the sub-list the code, and the configuration name of the new AMI.

    • user - This is the user that is going to be used in order to connect to the instance. In the case of Ubuntu AMIs it will be ubuntu while Fedora ones use ec2-user.
      • Example:

        user = "ubuntu"
    • key_name - Name of the key-pair name that Bellatrix will specify when launching the new instance:

      key_name = "key"
    • security_groups - Comma separated list (with no spaces) of the security groups that will be applied to the new instance:

      security_groups = "default"
    • instance_type - Type of instance that Bellatrix will request to AWS. Usually t1.micro is enough (not to mention cheap) just for applying some commands. If you need more power, you can find the one that suits you better here:

      instance_type = "t1.micro"
    • cmds - The list of command that are going to be executed in order to provision the new instance.

Here is an example of a complete configuration file that manages to provision Django, GUnicorn, NGnix and Upstart into a blank Ubuntu AMI.