ToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 8.1
New since 8.1 release.

The Allegro CL interface to the Amazon Elastic Compute Cloud (EC2)

This document contains the following sections:

1.0 EC2 introduction
   1.1 The EC2 module, package, and supported platforms
   1.2 Example requirements
   1.3 General comments on the EC2 interface
2.0 EC2 setup and requirements
3.0 EC2 classes
4.0 Functions for image manipulation
5.0 Functions for instance manipulation
6.0 Functions for key pair manipulation
7.0 Functions for security manipulation
8.0 Functions for Elastic IP address manipulation
9.0 Functions for EBS manipulation
10.0 High-level EC2 functions
11.0 Miscellaneous functions
Appendix A. EC2 variables
Appendix B. EC2 classes
   Appendix B.1. The ec2-instance class
   Appendix B.2. The ec2-image class
   Appendix B.3. The ec2-key class
   Appendix B.4. The ec2-security-group class
   Appendix B.5. The ec2-ip-permissions class
   Appendix B.6. The ec2-volume class
   Appendix B.7. The ec2-attachment class
   Appendix B.8. The ec2-snapshot class
Appendix C. EC2 operators
   Appendix C.1. Image manipulation operators
   Appendix C.2. Instance manipulation operators
   Appendix C.3. Key pair manipulation operators
   Appendix C.4. Security manipulation operators
   Appendix C.5. Elastic IP address manipulation operators
   Appendix C.6. Functionality for EBS manipulation
   Appendix C.7. High-level operators
   Appendix C.8. Miscellaneous operators
Appendix D. EC2 other functionality


1.0 EC2 introduction

The EC2 module was added to Allegro CL in an updated released in December, 2008. You must have this update to use the functionality described in this document. See sys:update-allegro for information on getting updates.

An update in late July, 2009, moved to Signature Version 2, which should continue to work past September of 2009. The API version in the update is "2009-04-04". We do yet not implement the new "reserved instances" or "monitor instances" APIs. The update added the valiable *ec2-signature-method*. Other changes made by earlier patches but not previously documented are now documented. terminate-instances has a new argument list and ec2-volume-zone is now named ec2-volume-availability-zone.

Allegro CL provides an interface to the API for the Amazon Elastic Compute Cloud (EC2). Amazon has different versions of their API and we use version 2008-12-01. The Getting Started Guide for this version is described here: http://docs.amazonwebservices.com/AWSEC2/2008-12-01/GettingStartedGuide/. The API documentation for this version is here: http://developer.amazonwebservices.com/connect/entry.jspa?externalID=1665&categoryID=118.

To use Amazon's EC2, you must have an Amazon Web Services account. You can sign up for that here: http://aws.amazon.com/. This document is specific to the version of the API given above. When a new version of the API is released by Amazon, we will need to port the current interface to EC2 to that new API version.

The Allegro CL interface to EC2 uses the Amazon Query API. The other choices were the command line tools and SOAP API. We use neither, however we do believe the command line tools are useful as there are some things you can do with the CLI that you cannot do with the Query or SOAP APIs. We also find the Elasticfox add-on for FireFox very useful. You can download it here: http://developer.amazonwebservices.com/connect/entry.jspa?externalID=609.

Almost all of the Lisp API has a direct mapping to the EC2 Query API, but there are a few things in the Lisp API that assume `ssh' access to the running instances being managed from Lisp. Specifically, the queries of load average and memory usages have no mirror in the Amazon API. These Lisp constructs use `ssh' and standard Linux commands to operate, so they will only be useful with Linux guests. There is a section below about the extra information needed to use these Lisp API entries.


1.1 The EC2 module, package, and supported platforms

The module for the Lisp API is named ec2. Load the module with a form like:

(require :ec2)

It is not an error to evaluate that form when the module is already loaded.

Symbols naming functionality in the module are in the net.ec2 package. We assume in this document that the net.ec2 package is used so we do not qualify exported symbols in that package. Use the package by evaluating (use-package :ec2) after the module is loaded.

SSL moduled is needed

The Amazon Query API requires the use of SSL, so the EC2 module only works on those systems where SSL is supported--at the time of this writing, all but 64-bit Mac OS X. You can tell if your implementation supports SSL if the feature :ssl-support is on the *features* list. If the form (featurep :ssl-support) returns a non-nil value, SSL is supported on your platform.


1.2 Example requirements

The example in this document assume the following forms, or equivalents, have been evaluated:

  (require :ec2)
  (use-package :net.ec2)
  :ld ~/src/aws.cl

The last form, using the :ld top-level command, loads the file that sets the value of various special variables as described in Section 2.0 EC2 setup and requirements. See the information in that section under the heading Using a file to set the keys and identity.


1.3 General comments on the EC2 interface



2.0 EC2 setup and requirements

To use the Allegro CL EC2 API you need to have an AWS access key and secret access key. You obtain these from Amazon's website and we will assume you have them. You also need an SSH keypair name, since ssh is the sole method of interacting with your running instances.

The following three special symbols are essential to using EC2 and must be set before using any functions in the API. The values of each variable should be a string.

Once you have set the access key, the secret access key, and the keypair name, you can create your EC2 identity for use by the API by evaluating this form which creates an ec2-identity instance suitable as the value for *ec2-identity*:

(setq *ec2-identity* (make-instance 'ec2-identity))

The slots in the class ec2-identity take their initforms from the values of the three variables above.

Using a file to set the keys and identity

Once set, your EC2 identity is implicitly used by various API functions. It's probably a good idea to put the setting of *aws-access-key*, *aws-secret-access-key*, *aws-keypair-name*, and *ec2-identity* in a file that is appropriately protected. The examples below will use ~/src/aws.cl. It should contain something like this:

  (in-package :net.ec2)

  (setq *aws-access-key* "...")
  (setq *aws-secret-access-key* "...")
  (setq *aws-keypair-name* "aws")
  (setq *ec2-identity* (make-instance 'ec2-identity))

Other variables

The values of the following special variables should be considered read-only:

The variable *ec2-signature-method* specifies the encoding method.

The value of the following two special variables are used by anything in the Lisp API that needs to SSH into running instances:

The following are used to name a default AMI (Amazon Machine Image) and instance type (these terms are defined on http://aws.amazon.com/).

EC2 errors

Errors signaled by the Allegro CL EC2 API are of type ec2-error.



3.0 EC2 classes

The EC2 functionality uses CLOS classes. Each class typically has a large number of slots. A complete list of the slots of each class is given in an appendix, along with definitions of associated functions. Here we just give brief introductions.

The ec2-instance class

ec2-instance is the name of the class for which many API functions return an instance. This represents a running AMI in the cloud. The functions defined for this class.

The ec2-image class

ec2-image is the name of the class for which many API functions return an instance. This represents images which can be run on the cloud.

The ec2-key class

ec2-key is the name of the class for which some API functions return an instance. This represents the SSH keyname used to access a remotely running instance.

The ec2-security-group class

ec2-security-group is the name of the class for which some API functions return an instance. This represents a security group definition. See Appendix B.4 The ec2-security-group class for information on slots, the predicate function, and accessors.

The ec2-ip-permissions class

ec2-ip-permissions is the name of the class for which some API functions return an instance. This represents the permissions which can be set for access to an instance. See Appendix B.5 The ec2-ip-permissions class for information on slots, the predicate function, and accessors.

The ec2-volume class

ec2-volume is the name of the class for which some API functions return an instance. This represents the volume definition, or unit of storage. See Appendix B.6 The ec2-volume class for information on slots, the predicate function, and accessors.

The ec2-attachment class

ec2-attachment is the name of the class for which some API functions return an instance. This represents an attached volume on an instance. See Appendix B.7 The ec2-attachment class for information on slots, the predicate function, and accessors.

The ec2-snapshot class

ec2-snapshot is the name of the class for which some API functions return an instance. This represents a snapshot of a volume. See Appendix B.8 The ec2-snapshot class for information on slots, the predicate function, and accessors.



4.0 Functions for image manipulation

This section deals with registering, querying and deregistering images. The functions discussed are listed below. Follow the links for the complete definitions.

describe-images example

cl-user(5): (describe-images :image-id *default-ami-name*)
(#<ec2-image
    id="ami-2a5fba43"
    location="ec2-public-images/fedora-8-x86_64-base-v1.07.manifest.xml"
    state=:available
    owner-id="amazon"
    is-public=t
    architecture="x86_64"
    type="machine"
    kernel-id="aki-b51cf9dc"
    ramdisk-id="ari-b31cf9da"
    @ #x1001867df2>)
cl-user(6): (describe-images :owner "self")
(#<ec2-image
    id="ami-871df9ee"
    location="/bms/bms.manifest.xml"
    state=:available
    owner-id="210979525344"
    architecture="x86_64"
    type="machine"
    @ #x100188dca2#gt;)
cl-user(7): (length (describe-images))
1265


5.0 Functions for instance manipulation

This section deals with running, querying and terminating instances. See Appendix C.2 Instance manipulation operators for formal definitions of the functions mentioned in this section.

Instance manipulation functionality example

cl-user(8): (setq instances1
	       (run-instances "ami-2b5fba42" 2 2 :wait t :verbose t))
; waiting for instance i-e51aa58c to enter :running state.
; waiting for instance i-e51aa58c to enter :running state.
[repeated similar lines deleted for space]
; waiting for instance i-e21aa58b to enter :running state.
; waiting for instance i-e21aa58b to enter :running state.
(#<ec2-instance
    id="i-e21aa58b"
    image-id="ami-2b5fba42"
    state-name=:running
    state-code=16
    private-dns-name="domU-12-31-39-00-ED-D7.compute-1.internal"
    dns-name="ec2-75-101-197-132.compute-1.amazonaws.com"
    key-name="aws"
    ami-launch-index=0
    instance-type="m1.small"
    launch-time=3437965484
    availability-zone="us-east-1c"
    kernel-id="aki-a71cf9ce"
    ramdisk-id="ari-a51cf9cc"
    reservation-id="r-113c9e78"
    owner-id="210979525344"
    identity=#<ec2-identity
                ssh-identity-file="~/.ssh/id_rsa-aws"
                ssh-user="root"
                keypair-name="aws"
                @ #x10017de392>
    @ #x1001977c92>
 #<ec2-instance
    id="i-e51aa58c"
    image-id="ami-2b5fba42"
    state-name=:running
    state-code=16
    private-dns-name="domU-12-31-39-00-C4-E3.compute-1.internal"
    dns-name="ec2-75-101-236-186.compute-1.amazonaws.com"
    key-name="aws"
    ami-launch-index=1
    instance-type="m1.small"
    launch-time=3437965484
    availability-zone="us-east-1c"
    kernel-id="aki-a71cf9ce"
    ramdisk-id="ari-a51cf9cc"
    reservation-id="r-113c9e78"
    owner-id="210979525344"
    identity=#<ec2-identity
                ssh-identity-file="~/.ssh/id_rsa-aws"
                ssh-user="root"
                keypair-name="aws"
                @ #x10017de392>
    @ #x1001900c52>)


;; Get the status of just the instances in the list `instances1'
;;
cl-user(9): (describe-instances :instances instances1)
(#<ec2-instance
    id="i-e51aa58c"
    image-id="ami-2b5fba42"
    state-name=:running
    state-code=16
    private-dns-name="domU-12-31-39-00-C4-E3.compute-1.internal"
    dns-name="ec2-75-101-236-186.compute-1.amazonaws.com"
    key-name="aws"
    ami-launch-index=1
    instance-type="m1.small"
    launch-time=3437965484
    availability-zone="us-east-1c"
    kernel-id="aki-a71cf9ce"
    ramdisk-id="ari-a51cf9cc"
    reservation-id="r-113c9e78"
    owner-id="210979525344"
    identity=#<ec2-identity
                ssh-identity-file="~/.ssh/id_rsa-aws"
                ssh-user="root"
                keypair-name="aws"
                @ #x10017de392>
    @ #x10019c92a2>
 #<ec2-instance
    id="i-e21aa58b"
    image-id="ami-2b5fba42"
    state-name=:running
    state-code=16
    private-dns-name="domU-12-31-39-00-ED-D7.compute-1.internal"
    dns-name="ec2-75-101-197-132.compute-1.amazonaws.com"
    key-name="aws"
    ami-launch-index=0
    instance-type="m1.small"
    launch-time=3437965484
    availability-zone="us-east-1c"
    kernel-id="aki-a71cf9ce"
    ramdisk-id="ari-a51cf9cc"
    reservation-id="r-113c9e78"
    owner-id="210979525344"
    identity=#<ec2-identity
                ssh-identity-file="~/.ssh/id_rsa-aws"
                ssh-user="root"
                keypair-name="aws"
                @ #x10017de392>
    @ #x10019c8d72>)
cl-user(10): (terminate-instances instances1)
((:instanceId "i-e21aa58b" :shutdownState-code "32" :shutdownState-name
  "shutting-down" :previousState-code "16" :previousState-name "running")
 (:instanceId "i-e51aa58c" :shutdownState-code "32" :shutdownState-name
  "shutting-down" :previousState-code "16" :previousState-name "running"))
cl-user(11): 


6.0 Functions for key pair manipulation

This section deals with creation, querying and deleting key pair. See Appendix C.3 Key pair manipulation operators for formal descriptions of the functions listed in this section.

Key pair manipulation examples

cl-user(11): (describe-key-pairs)
(#<ec2-key
    name="aws"
    fingerprint="22:f9:ce:8e:ee:09:ce:54:61:80:6a:32:e6:70:d3:27:22:e0:5d:bf"
    @ #x1001a3e6a2>)
cl-user(12): (create-key-pair "test-key")
("test-key" "37:08:00:46:d1:01:ba:81:4b:f7:69:ea:23:00:31:28:20:fe:36:32"
 "-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEApheBcjqYIza2Bs71xLciKZP+QoXpn+Gg8ODRHwxQ4x67UXZrjBJ+LiBIHvvX
Tk6mV0dcgEVK9JayjdWFl8QEH2uQVISpwN8yAryyL9WlqhqK8PKumjEXFhwkRDY6Th7Affrt66rc
kDWF5oeR34SDS1hyVhs4bHV35ti4OMG352LsID9nuX/KUIpozXh8hUs/ZNpEKppsGlG0qcrCLuUX
[text deleted to save space]
mFgxEHBoDSi7EenJFm78iwIXJBvhT3IHxETZTXCcFvx/cQKBgQCAZ9A3CWBUbqIovJAGiRgfH/6r
A41m7GpYpg0hL9T0h0glNqGeeeH3MsMOeYnNyxKlJQdwCihSrm8t0X9ZG5YEThqdyrC6hoSvi006
/O/ua7m8nDDbppEdTh7tmYCSpt269HMDGxc6wIbc1FIJWBLKVox3chFA+aATADOqecYzLg==
-----END RSA PRIVATE KEY-----")
cl-user(13): (describe-key-pairs)
(#<ec2-key
    name="aws"
    fingerprint="22:f9:ce:8e:ee:09:ce:54:61:80:6a:32:e6:70:d3:27:22:e0:5d:bf"
    @ #x1001aabd82>
 #<ec2-key
    name="test-key"
    fingerprint="37:08:00:46:d1:01:ba:81:4b:f7:69:ea:23:00:31:28:20:fe:36:32"
    @ #x1001aabd22>)
cl-user(14): (delete-key-pair "test-key")
t
cl-user(15): (describe-key-pairs)
(#<ec2-key
    name="aws"
    fingerprint="22:f9:ce:8e:ee:09:ce:54:61:80:6a:32:e6:70:d3:27:22:e0:5d:bf"
    @ #x1001adb922>)
cl-user(16): 


7.0 Functions for security manipulation

This section deals with creation, querying, deleting, authorizing and revoking authorization for security groups. See Appendix C.4 Security manipulation operators for formal definitions of the functions mentioned in this section.

Security group examples

cl-user(16): (describe-security-groups)
(#<ec2-security-group
    owner-id="210979525344"
    name="default"
    description="default group"
    ip-permissions=(#<ec2-ip-permissions tcp: 0=>65535>
                    #<ec2-ip-permissions udp: 0=>65535>
                    #<ec2-ip-permissions icmp: -1=>-1>
                    #<ec2-ip-permissions tcp: 22=>22: 0.0.0.0/0>
                    #<ec2-ip-permissions tcp: 80=>80: 0.0.0.0/0>
                    #<ec2-ip-permissions tcp: 3666=>3666: 0.0.0.0/0>
                    #<ec2-ip-permissions tcp: 3667=>3667: 0.0.0.0/0>
                    #<ec2-ip-permissions tcp: 8080=>8080: 0.0.0.0/0>)
    @ #x1001b08232>)
cl-user(17): (create-security-group "testgroup" "my test group")
t
cl-user(18): (authorize-security-group-ingress
	      "testgroup" :to-port 22 :from-port 22)
t
cl-user(19): (authorize-security-group-ingress
	      "testgroup" :to-port 80 :from-port 80)
t
cl-user(20): (describe-security-groups :group-names "testgroup")
(#<ec2-security-group
    owner-id="210979525344"
    name="testgroup"
    description="my test group"
    ip-permissions=(#<ec2-ip-permissions tcp: 22=>22: 0.0.0.0/0>
                    #<ec2-ip-permissions tcp: 80=>80: 0.0.0.0/0>)
    @ #x1001b87ee2>)
cl-user(21): (revoke-security-group-ingress
	      "testgroup" :to-port 80 :from-port 80)
t
cl-user(22): (describe-security-groups :group-names "testgroup")
(#<ec2-security-group
    owner-id="210979525344"
    name="testgroup"
    description="my test group"
    ip-permissions=(#<ec2-ip-permissions tcp: 22=>22: 0.0.0.0/0>)
    @ #x1001bc7252>)
cl-user(23): (delete-security-group "testgroup")
t
cl-user(24): (describe-security-groups)
(#<ec2-security-group
    owner-id="210979525344"
    name="default"
    description="default group"
    ip-permissions=(#<ec2-ip-permissions tcp: 0=>65535>
                    #<ec2-ip-permissions udp: 0=>65535>
                    #<ec2-ip-permissions icmp: -1=>-1>
                    #<ec2-ip-permissions tcp: 22=>22: 0.0.0.0/0>
                    #<ec2-ip-permissions tcp: 80=>80: 0.0.0.0/0>
                    #<ec2-ip-permissions tcp: 3666=>3666: 0.0.0.0/0>
                    #<ec2-ip-permissions tcp: 3667=>3667: 0.0.0.0/0>
                    #<ec2-ip-permissions tcp: 8080=>8080: 0.0.0.0/0>)
    @ #x1001bff662>)
cl-user(25): 


8.0 Functions for Elastic IP address manipulation

This section deals with allocating, querying, releasing, associating and disassociating Elastic IP address. See Appendix C.5 Elastic IP address manipulation operators for formal definitions of the functions mentioned in this section.

Elastic address examples

cl-user(25): (setq ip (allocate-address))
"174.129.252.59"
cl-user(26): (describe-addresses)
(("174.129.252.59"))
cl-user(27): (setq instances (run-instances "ami-2b5fba42" 1 1 :wait t))
(#<ec2-instance
    id="i-c71aa5ae"
    image-id="ami-2b5fba42"
    state-name=:running
    state-code=16
    private-dns-name="domU-12-31-39-00-EC-35.compute-1.internal"
    dns-name="ec2-67-202-33-184.compute-1.amazonaws.com"
    key-name="aws"
    ami-launch-index=0
    instance-type="m1.small"
    launch-time=3437965713
    availability-zone="us-east-1c"
    kernel-id="aki-a71cf9ce"
    ramdisk-id="ari-a51cf9cc"
    reservation-id="r-f33c9e9a"
    owner-id="210979525344"
    identity=#<ec2-identity
                ssh-identity-file="~/.ssh/id_rsa-aws"
                ssh-user="root"
                keypair-name="aws"
                @ #x1001de94e2>
    @ #x1002012732>)
cl-user(28): (describe-instances :instances (car instances))
(#<ec2-instance
    id="i-c71aa5ae"
    image-id="ami-2b5fba42"
    state-name=:running
    state-code=16
    private-dns-name="domU-12-31-39-00-EC-35.compute-1.internal"
    dns-name="ec2-67-202-33-184.compute-1.amazonaws.com"
    key-name="aws"
    ami-launch-index=0
    instance-type="m1.small"
    launch-time=3437965713
    availability-zone="us-east-1c"
    kernel-id="aki-a71cf9ce"
    ramdisk-id="ari-a51cf9cc"
    reservation-id="r-f33c9e9a"
    owner-id="210979525344"
    identity=#<ec2-identity
                ssh-identity-file="~/.ssh/id_rsa-aws"
                ssh-user="root"
                keypair-name="aws"
                @ #x1001de94e2>
    @ #x1002046df2>)
cl-user(29): (associate-address (car instances) ip)
t
cl-user(30): (describe-addresses)
(("174.129.252.59" . "i-c71aa5ae"))
cl-user(31): (describe-instances :instances (car instances))
(#<ec2-instance
    id="i-c71aa5ae"
    image-id="ami-2b5fba42"
    state-name=:running
    state-code=16
    private-dns-name="domU-12-31-39-00-EC-35.compute-1.internal"
    dns-name="ec2-174-129-252-59.compute-1.amazonaws.com"
    key-name="aws"
    ami-launch-index=0
    instance-type="m1.small"
    launch-time=3437965713
    availability-zone="us-east-1c"
    kernel-id="aki-a71cf9ce"
    ramdisk-id="ari-a51cf9cc"
    reservation-id="r-f33c9e9a"
    owner-id="210979525344"
    identity=#<ec2-identity
                ssh-identity-file="~/.ssh/id_rsa-aws"
                ssh-user="root"
                keypair-name="aws"
                @ #x1001de94e2>
    @ #x10020a6722>)
cl-user(32): (disassociate-address ip)
t
cl-user(33): (describe-addresses)
(("174.129.252.59"))
cl-user(34): (release-address ip)
t
cl-user(35): (describe-addresses)
nil
cl-user(36): (describe-instances :instances (car instances))
(#<ec2-instance
    id="i-c71aa5ae"
    image-id="ami-2b5fba42"
    state-name=:running
    state-code=16
    private-dns-name="domU-12-31-39-00-EC-35.compute-1.internal"
    key-name="aws"
    ami-launch-index=0
    instance-type="m1.small"
    launch-time=3437965713
    availability-zone="us-east-1c"
    kernel-id="aki-a71cf9ce"
    ramdisk-id="ari-a51cf9cc"
    reservation-id="r-f33c9e9a"
    owner-id="210979525344"
    identity=#<ec2-identity
                ssh-identity-file="~/.ssh/id_rsa-aws"
                ssh-user="root"
                keypair-name="aws"
                @ #x1001de94e2>
    @ #x10021260e2>)
cl-user(37): (terminate-instances instances)
((:instanceId "i-c71aa5ae" :shutdownState-code "32" :shutdownState-name
  "shutting-down" :previousState-code "16" :previousState-name "running"))
cl-user(38): 

In the above the DNS name changes from "ec2-75-101-222-252.compute-1.amazonaws.com" to "ec2-174-129-251-53.compute-1.amazonaws.com". The former was the default assigned DNS name and the latter the one from the allocated IP address. Note: it is unclear why the :dns-name slot of the instance returned after disassociating the IP is unset in values returned by the EC2 API.



9.0 Functions for EBS manipulation

This section deals with EBS volumes and snapshots. See Appendix C.6 Functionality for EBS manipulation for the formal descriptions of the functions mentioned.

Example with volumes and snapshots

cl-user(38): (setq i (car (run-instances "ami-2b5fba42" 1 1 :wait t)))
#<ec2-instance
   id="i-b41aa5dd"
   image-id="ami-2b5fba42"
   state-name=:running
   state-code=16
   private-dns-name="domU-12-31-39-00-ED-54.compute-1.internal"
   dns-name="ec2-75-101-174-18.compute-1.amazonaws.com"
   key-name="aws"
   ami-launch-index=0
   instance-type="m1.small"
   launch-time=3437965855
   availability-zone="us-east-1c"
   kernel-id="aki-a71cf9ce"
   ramdisk-id="ari-a51cf9cc"
   reservation-id="r-d23c9ebb"
   owner-id="210979525344"
   identity=#<ec2-identity
               ssh-identity-file="~/.ssh/id_rsa-aws"
               ssh-user="root"
               keypair-name="aws"
               @ #x10017dd802>
   @ #x1001a7dd72>
cl-user(39): (setq v1 (create-volume "us-east-1c" :size 1))
#<ec2-volume
   id="vol-4593772c"
   size="1"
   status="creating"
   create-time="2008-12-11T06:32:02.000Z"
   @ #x1001ab7bf2>
cl-user(40): (describe-volumes)
(#<ec2-volume
    id="vol-4593772c"
    size="1"
    status="available"
    create-time="2008-12-11T06:32:02.000Z"
    @ #x1001ad19a2>
 #<ec2-volume
    id="vol-9b8d69f2"
    size="200"
    status="in-use"
    create-time="2008-12-05T22:07:41.000Z"
    attachments=(#<ec2-attachment # # # # @ #x1001ada132>)
    @ #x1001ada1c2>)
cl-user(41): (attach-volume v1 i "/dev/sdh")
#<ec2-attachment
   volume-id="vol-4593772c"
   instance-id="i-b41aa5dd"
   status="attaching"
   attach-time="2008-12-11T06:32:13.000Z"
   device="/dev/sdh"
   @ #x1001afbf32>
cl-user(42): (describe-volumes)
(#<ec2-volume
    id="vol-4593772c"
    size="1"
    status="in-use"
    create-time="2008-12-11T06:32:02.000Z"
    attachments=(#<ec2-attachment # # # # @ #x1001b183d2>)
    @ #x1001b18462>
 #<ec2-volume
    id="vol-9b8d69f2"
    size="200"
    status="in-use"
    create-time="2008-12-05T22:07:41.000Z"
    attachments=(#<ec2-attachment # # # # @ #x1001b184e2>)
    @ #x1001b18572>)
cl-user(43): 

Now, on the instance itself, I initialize the new attached device (we are showing the shell interaction, with the # prompt indicating the user is root):

# fdisk /dev/sdh
...

Command (m for help): p

Disk /dev/sdh: 1073 MB, 1073741824 bytes
255 heads, 63 sectors/track, 130 cylinders
Units = cylinders of 16065 * 512 = 8225280 bytes
Disk identifier: 0x5f4d21ed

   Device Boot      Start         End      Blocks   Id  System

Command (m for help): n
Command action
   e   extended
   p   primary partition (1-4)
p
Partition number (1-4): 1
First cylinder (1-130, default 1): 

Using default value 1
Last cylinder or +size or +sizeM or +sizeK (1-130, default 130): 
Using default value 130

Command (m for help): p

Disk /dev/sdh: 1073 MB, 1073741824 bytes
255 heads, 63 sectors/track, 130 cylinders
Units = cylinders of 16065 * 512 = 8225280 bytes
Disk identifier: 0x5f4d21ed

   Device Boot      Start         End      Blocks   Id  System
/dev/sdh1               1         130     1044193+  83  Linux

Command (m for help): w
The partition table has been altered!

Calling ioctl() to re-read partition table.
Syncing disks.
# mkfs /dev/sdh1
mke2fs 1.40.4 (31-Dec-2007)
Filesystem label=
OS type: Linux
Block size=4096 (log=2)
Fragment size=4096 (log=2)
130560 inodes, 261048 blocks
13052 blocks (5.00%) reserved for the super user
First data block=0
Maximum filesystem blocks=268435456
8 block groups
32768 blocks per group, 32768 fragments per group
16320 inodes per group
Superblock backups stored on blocks: 
	32768, 98304, 163840, 229376

Writing inode tables: done                            
Writing superblocks and filesystem accounting information: done

This filesystem will be automatically checked every 38 mounts or
180 days, whichever comes first.  Use tune2fs -c or -i to override.
# mkdir /v1
# mount /dev/sdh1 /v1
# df -h /v1
Filesystem            Size  Used Avail Use% Mounted on
/dev/sdh1            1004M  1.3M  952M   1% /v1
# 

Now back in Lisp:

cl-user(43): (create-snapshot v1)
#<ec2-snapshot
   id="snap-c821c2a1"
   volume-id="vol-4593772c"
   status="pending"
   start-time="2008-12-11T06:34:20.000Z"
   @ #x1001b48562>
cl-user(44): (describe-snapshots)
(#<ec2-snapshot
    id="snap-c821c2a1"
    volume-id="vol-4593772c"
    status="completed"
    start-time="2008-12-11T06:34:20.000Z"
    progress="100%"
    @ #x1001b60ee2>)
cl-user(45): 

Now, create a new volume from a snapshot, instead of specifying the size directly:

cl-user(45): (setq snapshot (car (describe-snapshots)))
#<ec2-snapshot
   id="snap-c821c2a1"
   volume-id="vol-4593772c"
   status="completed"
   start-time="2008-12-11T06:34:20.000Z"
   progress="100%"
   @ #x1001b82f12>
cl-user(46): (setq v2 (create-volume "us-east-1c" :snapshot snapshot))
#<ec2-volume
   id="vol-4693772f"
   size="1"
   status="creating"
   create-time="2008-12-11T06:34:47.000Z"
   snapshot-id="snap-c821c2a1"
   @ #x1001ba25c2>
cl-user(47): (attach-volume v2 i "/dev/sdi")
#<ec2-attachment
   volume-id="vol-4693772f"
   instance-id="i-b41aa5dd"
   status="attaching"
   attach-time="2008-12-11T06:34:56.000Z"
   device="/dev/sdi"
   @ #x1001bbd6c2>
cl-user(48): (describe-volumes)
(#<ec2-volume
    id="vol-4693772f"
    size="1"
    status="in-use"
    create-time="2008-12-11T06:34:47.000Z"
    attachments=(#<ec2-attachment # # # # @ #x1001bdba42>)
    @ #x1001bdbad2>
 #<ec2-volume
    id="vol-4593772c"
    size="1"
    status="in-use"
    create-time="2008-12-11T06:32:02.000Z"
    attachments=(#<ec2-attachment # # # # @ #x1001bdbb52>)
    @ #x1001bdbbe2>
 #<ec2-volume
    id="vol-9b8d69f2"
    size="200"
    status="in-use"
    create-time="2008-12-05T22:07:41.000Z"
    attachments=(#<ec2-attachment # # # # @ #x1001bdbc62>)
    @ #x1001bdbcf2>)

Let's undo what we did above:

cl-user(151): (delete-snapshot snapshot)
t
cl-user(152): (describe-snapshots)
nil

Detach is required before delete:

cl-user(52): (delete-volume v1)
Error: IncorrectState: The volume 'vol-4593772c' is 'in-use'..
  [condition type: ec2-error]

Restart actions (select using :continue):
 0: Return to Top Level (an "abort" restart).
 1: Abort entirely from this (lisp) process.
[1] cl-user(53): :res
cl-user(54): (detach-volume v1 i :device "/dev/sdh")
#<ec2-attachment
   volume-id="vol-4593772c"
   instance-id="i-b41aa5dd"
   status="detaching"
   attach-time="2008-12-11T06:32:13.000Z"
   device="/dev/sdh"
   @ #x1001c61152>
cl-user(55): (detach-volume v2 i :device "/dev/sdi")
#<ec2-attachment
   volume-id="vol-4693772f"
   instance-id="i-b41aa5dd"
   status="detaching"
   attach-time="2008-12-11T06:34:56.000Z"
   device="/dev/sdi"
   @ #x1001c7e262>

/dev/sdh1 is still mounted, so it will not detach:

cl-user(56): (describe-volumes)
(#<ec2-volume
    id="vol-4693772f"
    size="1"
    status="available"
    create-time="2008-12-11T06:34:47.000Z"
    @ #x1001e3f2a2>
 #<ec2-volume
    id="vol-4593772c"
    size="1"
    status="in-use"
    create-time="2008-12-11T06:32:02.000Z"
    attachments=(#<ec2-attachment # # # # @ #x1001e3f322>)
    @ #x1001e3f3b2>
 #<ec2-volume
    id="vol-9b8d69f2"
    size="200"
    status="in-use"
    create-time="2008-12-05T22:07:41.000Z"
    attachments=(#<ec2-attachment # # # # @ #x1001e3f432>)
    @ #x1001e3f4c2>)

It is now unmounted, so the status should change:

cl-user(57): (describe-volumes)
(#<ec2-volume
    id="vol-4693772f"
    size="1"
    status="available"
    create-time="2008-12-11T06:34:47.000Z"
    @ #x1001e714e2>
 #<ec2-volume
    id="vol-4593772c"
    size="1"
    status="available"
    create-time="2008-12-11T06:32:02.000Z"
    @ #x1001e71572>
 #<ec2-volume
    id="vol-9b8d69f2"
    size="200"
    status="in-use"
    create-time="2008-12-05T22:07:41.000Z"
    attachments=(#<ec2-attachment # # # # @ #x1001e715f2>)
    @ #x1001e71682>)
cl-user(58): 


10.0 High-level EC2 functions

This section details the high-level EC2 functions, some of which require SSH access to the instance. See Appendix C.7 High-level operators for the formal descriptions of the functions mentioned.

Example using query-status, query-load, and query-memory

cl-user(58): (query-status i)
:running
#<ec2-instance
   id="i-b41aa5dd"
   image-id="ami-2b5fba42"
   state-name=:running
   state-code=16
   private-dns-name="domU-12-31-39-00-ED-54.compute-1.internal"
   dns-name="ec2-75-101-174-18.compute-1.amazonaws.com"
   key-name="aws"
   ami-launch-index=0
   instance-type="m1.small"
   launch-time=3437965855
   availability-zone="us-east-1c"
   kernel-id="aki-a71cf9ce"
   ramdisk-id="ari-a51cf9cc"
   reservation-id="r-d23c9ebb"
   owner-id="210979525344"
   identity=#<ec2-identity
               ssh-identity-file="~/.ssh/id_rsa-aws"
               ssh-user="root"
               keypair-name="aws"
               @ #x10017dd802>
   @ #x1001ea26d2>
cl-user(59): (query-load i)
0.0
0.05
0.02
cl-user(60): (query-memory i)
298136
1449628
cl-user(61): 


11.0 Miscellaneous functions

See Appendix C.8 Miscellaneous operators for formal definitions of the functions listed in this section.

Example using describe-availability-zones

cl-user(117): (describe-availability-zones)
(("us-east-1c" . "available") ("us-east-1b" . "available")
 ("us-east-1a" . "available"))
cl-user(119): 

Example using get-console-output

cl-user(65): (get-console-output i)
(3437966094
 . "Linux version 2.6.21.7-2.fc8xen (mockbuild@xenbuilder1.fedora.redhat.com) (gcc version 4.1.2 20070925 (Red Hat 4.1.2-33)) #1 SMP Fri Feb 15 12:39:36 EST 2008
BIOS-provided physical RAM map:
sanitize start
sanitize bail 0
...
Fedora release 8 (Werewolf)
Kernel 2.6.21.7-2.fc8xen on an i686

domU-12-31-39-00-ED-54 login: ")
cl-user(66): 

Example using describe-regions

cl-user(7): (describe-regions)
(("us-east-1") ("eu-west-1"))
cl-user(8): 


Appendix A: EC2 variables


*aws-access-key*

Variable

Package: net.ec2

The value should a string which is your AWS access key.



*aws-secret-access-key*

Variable

Package: net.ec2

The value should be a string which is your AWS secret access key. Never give this to anyone and guard the security of this access key.



*aws-keypair-name*

Variable

Package: net.ec2

The value should be a string which is the name of your SSH keypair. See create-key-pair for more information.



*ec2-identity*

Variable

Package: net.ec2

The SSH identity for use by the Lisp API. Only used for those API functions which need to use SSH.



*ec2-signature-version*

Variable

Package: net.ec2

The signature version for API calls. Do not change the value of this symbol. This value was changed in the July, 2009 update.



*ec2-signature-method*

Variable

Package: net.ec2

The signature method for API calls. You would specify the type of encoding used by setting or binding this variable but currently only "HmacSHA1" is supported so there is no reason to modify the value. (We do not support SHA-256 in ACL yet.) This variable was added in the July, 2009 update.



*ec2-api-version*

Variable

Package: net.ec2

The EC2 API version used by the Lisp API. Do not change the value of this symbol. This value was changed to "2009-04-04" in the July, 2009 update.



*default-ssh-identity-file*

Variable

Package: net.ec2

The value should be a string which names a the file of your local computer which names your private key for using SSH to the remotely running instances.

See create-key-pair below for information on how to create the contents of this file.

The initial value is "~/.ssh/id_rsa-aws"



*default-ssh-user*

Variable

Package: net.ec2

The value should be a string which names of the user SSH should use when accessing remote running instances.

The initial value is "root".


The following are used to name a default AMI (Amazon Machine Image) and instance type (these terms are defined on http://aws.amazon.com/).


*default-ami-name*

Variable

Package: net.ec2

A string naming the default AMI which the API should use. This and *default-instance-type* must match, in the sense that the instance must be suitable for the machine image. Mismatches will cause errors. See http://aws.amazon.com/ for further information.

The initial value is "ami-2a5fba43", which is equivalent to fedora-8-x86_64-base-v1.07.manifest.xml



*default-instance-type*

Variable

Package: net.ec2

A string naming the default instance type. This and *default-ami-name* must match (see the description of *default-ami-name*).

The initial value is "m1.large".



*default-ami-name*

Variable

Package: net.ec2

A string naming the default AMI which the API should use. This and *default-instance-type* must match, in the sense that the instance must be suitable for the machine image. Mismatches will cause errors. See http://aws.amazon.com/ for further information.

The initial value is "ami-2a5fba43", which is equivalent to fedora-8-x86_64-base-v1.07.manifest.xml



*default-instance-type*

Variable

Package: net.ec2

A string naming the default instance type. This and *default-ami-name* must match (see the description of *default-ami-name*).

The initial value is "m1.large".




Appendix B: EC2 classes


Appendix B.1 The ec2-instance class


ec2-instance

Class

Package: net.ec2

The class for which many API functions return an instance. This represents a running AMI in the cloud.

The predicate that tests whether an object is an ec2-instance is ec2-instance-p. The following are accessors for the slots of this class:



ec2-instance-p

Generic Function

Package: net.ec2

Arguments: object

The predicate for the class ec2-instance, returning true when the argument is an ec2-instance and nil otherwise.



ec2-instance-dns-name

Generic Function

Package: net.ec2

Arguments: ec2-instance

Accessor of data returned by EC2 API calls.



ec2-instance-id

Generic Function

Package: net.ec2

Arguments: ec2-instance

Accessor of data returned by EC2 API calls.



ec2-instance-image-id

Generic Function

Package: net.ec2

Arguments: ec2-instance

Accessor of data returned by EC2 API calls.



ec2-instance-state-name

Generic Function

Package: net.ec2

Arguments: ec2-instance

Accessor of data returned by EC2 API calls.



ec2-instance-state-code

Generic Function

Package: net.ec2

Arguments: ec2-instance

Accessor of data returned by EC2 API calls.



ec2-instance-previous-state-name

Generic Function

Package: net.ec2

Arguments: ec2-instance

Accessor of data returned by EC2 API calls.



ec2-instance-previous-state-code

Generic Function

Package: net.ec2

Arguments: ec2-instance

Accessor of data returned by EC2 API calls.



ec2-instance-private-dns-name

Generic Function

Package: net.ec2

Arguments: ec2-instance

Accessor of data returned by EC2 API calls.



ec2-instance-owner-id

Generic Function

Package: net.ec2

Arguments: ec2-instance

The value is meta-information indirectly gleaned from EC2 API calls.



ec2-instance-reason

Generic Function

Package: net.ec2

Arguments: ec2-instance

Accessor of data returned by EC2 API calls.



ec2-instance-key-name

Generic Function

Package: net.ec2

Arguments: ec2-instance

Accessor of data returned by EC2 API calls.



ec2-instance-ami-launch-index

Generic Function

Package: net.ec2

Arguments: ec2-instance

Accessor of data returned by EC2 API calls.



ec2-instance-instance-type

Generic Function

Package: net.ec2

Arguments: ec2-instance

Accessor of data returned by EC2 API calls.



ec2-instance-launch-time

Generic Function

Package: net.ec2

Arguments: ec2-instance

Accessor of data returned by EC2 API calls.



ec2-instance-availability-zone

Generic Function

Package: net.ec2

Arguments: ec2-instance

Accessor of data returned by EC2 API calls.



ec2-instance-kernel-id

Generic Function

Package: net.ec2

Arguments: ec2-instance

Accessor of data returned by EC2 API calls.



ec2-instance-ramdisk-id

Generic Function

Package: net.ec2

Arguments: ec2-instance

Accessor of data returned by EC2 API calls.



ec2-instance-reservation-id

Generic Function

Package: net.ec2

Arguments: ec2-instance

The value is meta-information indirectly gleaned from EC2 API calls.



ec2-instance-identity

Generic Function

Package: net.ec2

Arguments: ec2-instance

The EC2 identity used in SSH access of the remotely running instance.



Appendix B.2 The ec2-image class


ec2-image

Class

Package: net.ec2

The class for which many API functions return an instance. This represents images which can be run on the cloud.

The predicate that tests whether an object is an ec2-instance is ec2-image-p. The following are accessors for the slots of this class:



ec2-image-p

Generic Function

Package: net.ec2

Arguments: object

The predicate for the class ec2-image, returning true when the argument is an ec2-image and nil otherwise.



ec2-image-architecture

Generic Function

Package: net.ec2

Arguments: ec2-image

The accessor to the named slot of an ec2-image.



ec2-image-id

Generic Function

Package: net.ec2

Arguments: ec2-image

The accessor to the named slot of an ec2-image.



ec2-image-is-public

Generic Function

Package: net.ec2

Arguments: ec2-image

The accessor to the named slot of an ec2-image.



ec2-image-kernel-id

Generic Function

Package: net.ec2

Arguments: ec2-image

The accessor to the named slot of an ec2-image.



ec2-image-location

Generic Function

Package: net.ec2

Arguments: ec2-image

The accessor to the named slot of an ec2-image.



ec2-image-owner-id

Generic Function

Package: net.ec2

Arguments: ec2-image

The accessor to the named slot of an ec2-image.



ec2-image-ramdisk-id

Generic Function

Package: net.ec2

Arguments: ec2-image

The accessor to the named slot of an ec2-image.



ec2-image-state

Generic Function

Package: net.ec2

Arguments: ec2-image

The accessor to the named slot of an ec2-image.



ec2-image-type

Generic Function

Package: net.ec2

Arguments: ec2-image

The accessor to the named slot of an ec2-image.



Appendix B.3 The ec2-key class


ec2-key

Class

Package: net.ec2

The class for which many API functions return an instance. This represents the SSH keyname used to access a remotely running instance.

The predicate that tests whether an object is an ec2-key is ec2-key-p. The following are accessors for the slots of this class:



ec2-key-p

Generic Function

Package: net.ec2

Arguments: object

The predicate for the class ec2-key, returning true when the argument is an ec2-key and nil otherwise.



ec2-key-name

Generic Function

Package: net.ec2

Arguments: ec2-key

The accessor to the named slot of an ec2-key.



ec2-key-fingerprint

Generic Function

Package: net.ec2

Arguments: ec2-key

The accessor to the named slot of an ec2-key.



Appendix B.4 The ec2-security-group class


ec2-security-group

Class

Package: net.ec2

The class for which some API functions return an instance. This represents a security group definition.

The predicate that tests whether an object is an ec2-security-group is ec2-security-group-p. The following are accessors for the slots of this class:



ec2-security-group-p

Generic Function

Package: net.ec2

Arguments: object

The predicate for the class ec2-security-group, returning true when the argument is an ec2-security-group and nil otherwise.



ec2-security-group-description

Generic Function

Package: net.ec2

Arguments: ec2-security-group

The accessor to the named slot of an ec2-security-group.



ec2-security-group-ip-permissions

Generic Function

Package: net.ec2

Arguments: ec2-security-group

The accessor to the named slot of an ec2-security-group.



ec2-security-group-name

Generic Function

Package: net.ec2

Arguments: ec2-security-group

The accessor to the named slot of an ec2-security-group.



ec2-security-group-owner-id

Generic Function

Package: net.ec2

Arguments: ec2-security-group

The accessor to the named slot of an ec2-security-group.



Appendix B.5 The ec2-ip-permissions class


ec2-ip-permissions

Class

Package: net.ec2

The class for which some API functions return an instance. This represents the permissions which can be set for access to an instance.

The predicate that tests whether an object is an ec2-ip-permissions is ec2-ip-permissions-p. The following are accessors for the slots of this class:



ec2-ip-permissions-p

Generic Function

Package: net.ec2

Arguments: object

The predicate for the class ec2-ip-permissions, returning true when the argument is an ec2-ip-permissions and nil otherwise.



ec2-ip-permissions-from-port

Generic Function

Package: net.ec2

Arguments: ec2-ip-permissions

The accessor to the named slot of an ec2-ip-permissions.



ec2-ip-permissions-ip-protocol

Generic Function

Package: net.ec2

Arguments: ec2-ip-permissions

The accessor to the named slot of an ec2-ip-permissions.



ec2-ip-permissions-ip-ranges

Generic Function

Package: net.ec2

Arguments: ec2-ip-permissions

The accessor to the named slot of an ec2-ip-permissions.



ec2-ip-permissions-to-port

Generic Function

Package: net.ec2

Arguments: ec2-ip-permissions

The accessor to the named slot of an ec2-ip-permissions.



Appendix B.6 The ec2-volume class


ec2-volume

Class

Package: net.ec2

The class for which some API functions return an instance. This represents the volume definition, or unit of storage.

The predicate that tests whether an object is an ec2-volume is ec2-volume-p. The following are accessors for the slots of this class:



ec2-volume-p

Generic Function

Package: net.ec2

Arguments: object

The predicate for the class ec2-volume, returning true when the argument is an ec2-volume and nil otherwise.



ec2-volume-attachments

Generic Function

Package: net.ec2

Arguments: ec2-volume

The accessor to the named slot of an ec2-volume.



ec2-volume-create-time

Generic Function

Package: net.ec2

Arguments: ec2-volume

The accessor to the named slot of an ec2-volume.



ec2-volume-id

Generic Function

Package: net.ec2

Arguments: ec2-volume

The accessor to the named slot of an ec2-volume.



ec2-volume-size

Generic Function

Package: net.ec2

Arguments: ec2-volume

The accessor to the named slot of an ec2-volume.



ec2-volume-snapshot-id

Generic Function

Package: net.ec2

Arguments: ec2-volume

The accessor to the named slot of an ec2-volume.



ec2-volume-status

Generic Function

Package: net.ec2

Arguments: ec2-volume

The accessor to the named slot of an ec2-volume.



ec2-volume-availability-zone

Generic Function

Package: net.ec2

Arguments: ec2-volume

(Previously names ec2-volume-zone.) The accessor to the named slot of an ec2-volume.



Appendix B.7 The ec2-attachment class


ec2-attachment

Class

Package: net.ec2

The class for which some API functions return an instance. This represents an attached volume on an instance.

The predicate that tests whether an object is an ec2-attachment is ec2-attachment-p. The following are accessors for the slots of this class:



ec2-attachment-p

Generic Function

Package: net.ec2

Arguments: object

The predicate for the class ec2-attachment, returning true when the argument is an ec2-attachment and nil otherwise.



ec2-attachment-attach-time

Generic Function

Package: net.ec2

Arguments: ec2-attachment

The accessor to the named slot of an ec2-attachment.



ec2-attachment-device

Generic Function

Package: net.ec2

Arguments: ec2-attachment

The accessor to the named slot of an ec2-attachment.



ec2-attachment-instance-id

Generic Function

Package: net.ec2

Arguments: ec2-attachment

The accessor to the named slot of an ec2-attachment.



ec2-attachment-size

Generic Function

Package: net.ec2

Arguments: ec2-attachment

The accessor to the named slot of an ec2-attachment.



ec2-attachment-status

Generic Function

Package: net.ec2

Arguments: ec2-attachment

The accessor to the named slot of an ec2-attachment.



ec2-attachment-volume-id

Generic Function

Package: net.ec2

Arguments: ec2-attachment

The accessor to the named slot of an ec2-attachment.



Appendix B.8 The ec2-snapshot class


ec2-snapshot

Class

Package: net.ec2

The class for which some API functions return an instance. This represents a snapshot of a volume.

The predicate that tests whether an object is an ec2-snapshot is ec2-snapshot-p. The following are accessors for the slots of this class:



ec2-snapshot-p

Generic Function

Package: net.ec2

Arguments: object

The predicate for the class ec2-snapshot, returning true when the argument is an ec2-snapshot and nil otherwise.



ec2-snapshot-id

Generic Function

Package: net.ec2

Arguments: ec2-snapshot

The accessor to the named slot of the snapshot class.



ec2-snapshot-progress

Generic Function

Package: net.ec2

Arguments: ec2-snapshot

The accessor to the named slot of the snapshot class.



ec2-snapshot-start-time

Generic Function

Package: net.ec2

Arguments: ec2-snapshot

The accessor to the named slot of the snapshot class.



ec2-snapshot-status

Generic Function

Package: net.ec2

Arguments: ec2-snapshot

The accessor to the named slot of the snapshot class.



ec2-snapshot-volume-id

Generic Function

Package: net.ec2

Arguments: ec2-snapshot

The accessor to the named slot of the snapshot class.




Appendix C: EC2 operators


Appendix C.1 Image manipulation operators


register-image

Function

Package: net.ec2

Arguments: manifest

Register an image with Amazon. manifest is the full path to your AMI manifest in Amazon S3 storage, a string.

The return value is an image ID, which is unique to the AMI you just registered.

See deregister-image.



describe-images

Function

Package: net.ec2

Arguments: &key image-id owner executable-by

Return a list of available images (ec2-image instances). The search can be narrowed by supplying any of the keyword arguments.

image-id is a list of image IDs to use in the search. It is a list of strings, or a single string.

owner is a list of owners to use in the search. It is a list of strings, or a single string.

executable-by is a list which specific users have access. It is a list of strings, or a single string.



deregister-image

Function

Package: net.ec2

Arguments: image-id

Deregister an image, where image-id is the image instance returned by a call to register-image or describe-images.

Returns t upon success.



Appendix C.2 Instance manipulation operators

See Section 5.0 Functions for instance manipulation for more information and examples.


run-instances

Function

Package: net.ec2

Arguments: image-id min-count max-count &key wait verbose (identity *ec2-identity*) instance-type (key-name *aws-keypair-name*) kernel-id ramdisk-id availability-zone

Runs one or more instances on the cloud. Upon success returns a list of ec2-instance instances.

image-id is a string naming an image. min-count and max-count are numbers. If min-count cannot be launched, none are launched. No more than max-count will be launched but the number actually launched may be less than max-count.

The keyword arguments are:



describe-instances

Function

Package: net.ec2

Arguments: &key (states (quote (:running :shutting-down :pending))) (identity *ec2-identity*) instances

Return a list of instances running in the cloud after updating the cached information in Lisp. The keywords can narrow the result, which is a list of ec2-instance instances.

states specifies which states to consider. Valid values are: :running, :shutting-down, :pending and :terminated. These values are determined by the EC2 API, given here: http://docs.amazonwebservices.com/AWSEC2/2008-12-01/DeveloperGuide/, and are just keyword versions of the strings used to represent these states in the EC2 API.

identity specifies which identity to use for the API access.

instances narrows the search to a specific set of instances. This is useful because the data in Lisp representing running instances does grow stale over time, and the state of a running instance changes.



terminate-instances

Function

Package: net.ec2

Arguments: &rest instances

Terminate the set of instances given by instances, which should be one or more ec2-instances.

Returns a list of status information for each terminated instance.



Appendix C.3 Key pair manipulation operators

See Section 6.0 Functions for key pair manipulation for more information and examples using the functions defined in this section.


create-key-pair

Function

Package: net.ec2

Arguments: key-name

Create a new 2048 bit RSA key pair, used when lauching new instances, and subsequent access thereafter. On success, return a list of key name, key fingerprint (SHA-1 digest of the DER encoded private key) and the key material (an unencrypted PEM encoded RSA private key).

The third list item, the PEM encoded RSA private key can be used as the contents for the file pointed to by *default-ssh-identity-file*. The key-name can be used as the value of the variable *aws-keypair-name*.



describe-key-pairs

Function

Package: net.ec2

Arguments: &key key-names

Retrieve the active key pairs and return a list of ec2-key instances, after updating the information cached in Lisp about them.



delete-key-pair

Function

Package: net.ec2

Arguments: key-name

Delete the key pair given by key-name. Returns t upon success.



Appendix C.4 Security manipulation operators

See Section 7.0 Functions for security manipulation for more information and examples using the functions defined in this section.


create-security-group

Function

Package: net.ec2

Arguments: name description

Creates a new security group named name with description `description', both strings. Returns t upon success.



describe-security-groups

Function

Package: net.ec2

Arguments: &key group-names

Returns a list of security groups, instances of ec2-security-group, after updating the information cached in Lisp about them. If group-names is specified, only those will be updated and returned.



delete-security-group

Function

Package: net.ec2

Arguments: name

Deletes a security group named name. Returns t upon success.



authorize-security-group-ingress

Function

Package: net.ec2

Arguments: name &key source-group-name source-group-owner-id ip-protocol from-port to-port cidr-ip

Modify security group name by the actions specified in the given keyword arguments. There are two types of authorization: user/group pair permission and CIDR IP permission.

user/group pair permission:

source-group-name and source-group-owner-id are used to add an owner to a group.

CIDR IP permission:

ip-protocol is the protocol for the authorization, one of :tcp, :udp, or :icmp. The default protocol is :tcp.

from-port and to-port are the source and destination ports, both integers.

cidr-ip is the IP range, a string. For example, "0.0.0.0/0" for all IP addresses, the default.



revoke-security-group-ingress

Function

Package: net.ec2

Arguments: name &key source-group-name source-group-owner-id ip-protocol from-port to-port cidr-ip

This function is the inverse of authorize-security-group-ingress, revoking any authorization granted by previous calls to that function.



Appendix C.5 Elastic IP address manipulation operators

See Section 8.0 Functions for Elastic IP address manipulation for more information and examples.


allocate-address

Function

Package: net.ec2

Arguments:

Allocates an Elastic, or static, IP address. It is returned as a string, if successful.



describe-addresses

Function

Package: net.ec2

Arguments:

Returns a list of the current mapping of IP to AMI in a list.



release-address

Function

Package: net.ec2

Arguments: ip

Release an elastic IP address, given by ip, a string.



associate-address

Function

Package: net.ec2

Arguments: instance ip

Associate IP ip, a string, with instance (an ec2-instance). Returns t if successful.



disassociate-address

Function

Package: net.ec2

Arguments: ip

Disassociates IP ip' from whatever instance it is associated with. Returns t if successful.



Appendix C.6 Functionality for EBS manipulation

See Section 9.0 Functions for EBS manipulation for further information and an example using these functions.


create-volume

Function

Package: net.ec2

Arguments: availability-zone &key size snapshot

Create a volume in availability-zone, which should be a string naming an availability-zone (see describe-availability-zones), with specified size (a number of gigabytes) or with data from a snapshot you own given by snapshot. Only one of the arguments size or snapshot can be given.



describe-volumes

Function

Package: net.ec2

Arguments: &key volumes

return a list of all active volumes (if volumes is unspecified) or a list of volumes specified by volumes. volumes, if specified, should be a list of ec2-volume instances. Returns a list of ec2-volume instances.



delete-volume

Function

Package: net.ec2

Arguments: volume

Delete the given volume. volume must be of type ec2-volume. Returns t if successful.



attach-volume

Function

Package: net.ec2

Arguments: volume instance device

Attach volume (an ec2-volume) to instance (an ec2-instance) giving it the name device (a string). Returns an instance of ec2-attachment if successful.



detach-volume

Function

Package: net.ec2

Arguments: volume instance &key device force

Detach volume on instance. If device is given, only detach if volume is attached using that device name. If force is specified non-nil, detach even if in use. Returns an instance of ec2-attachment if successful.



create-snapshot

Function

Package: net.ec2

Arguments: volume

Create a snapshot of volume, returning an ec2-snapshot if successful.



describe-snapshots

Function

Package: net.ec2

Arguments: &key snapshots

Returns a list of description of all current snapshots, or of those specified by snapshots if specified, after updating the information cached in Lisp about them. Returns a list of ec2-snapshot instances.



delete-snapshot

Function

Package: net.ec2

Arguments: snapshot

Delete the given snapshot. Returns t if successful.



Appendix C.7 High-level operators

See Section 10.0 High-level EC2 functions for more information on these functions.


wait-for-instances

Function

Package: net.ec2

Arguments: instances &key (state :running) verbose (sleep 2) (identity *ec2-identity*)

Wait for instances to enter a particular state. instances can be a single instance of a list of instances.

state is a keyword identifying the state the instances should be in when this function returns. The default is :running. See describe-instances for other possible values for state (we list the possible values in one place only so changes can most easily be tracked consistently.)

verbose causes reports sent to *terminal-io* of the actions performed.

sleep specifies the query period.

identity specifies which identity to use for the API access.

When the instances are in the new state, this function returns a list of the newly made instances of type ec2-instance. New instances are returned rather than the argument list of instances because the status of various slots in those objects could have different values.



query-status

Function

Package: net.ec2

Arguments: instance &key (identity *ec2-identity*)

Return two values: the status of instance, and a new copy of the instance, just in case it changed.

identity specifies which identity to use for the API access.



query-load

Function

Package: net.ec2

Arguments: instance

Return as multiple values the three values printed by the /usr/bin/uptime command.

This function requires SSH access and only works with Linux guest operating system.



query-memory

Function

Package: net.ec2

Arguments: instance

Return two values: the used and free memory as reported by the /usr/bin/free command.

This function requires SSH access and only works with Linux guest operating system.



ssh-command-output

Function

Package: net.ec2

Arguments: instance command &key &allow-other-keys

This function is just like excl.osi:command-output, except it takes an additional required argument (the first), which is the instance on which to execute the command via ssh.



ssh-copy-file

Function

Package: net.ec2

Arguments: instance local-file remote-file &key (preserve-time t) recurse &allow-other-keys

Copy local-file to the pathname relative to instance using name remote-file. All keywords to excl.osi:command-output are also accepted. preserve-time and recurse correspond to the -p and -r scp command line arguments.



Appendix C.8 Miscellaneous operators

See Section 11.0 Miscellaneous functions for more information and examples.


describe-availability-zones

Function

Package: net.ec2

Arguments: &rest zone-names

Returns a list of availability zones and their current status. zone-names can be used to narrow the return value search to a specific set of zone names.



get-console-output

Function

Package: net.ec2

Arguments: instance

Return the console output from instance, as a string. The actual return value is a dotted cons of the time the output was last updated and a string containing the output. If no output is yet available, then nil is returned for the string.

The time is in Common Lisp universal time.

The return value from the EC2 API is a base64 string. This function converts the base64 to a human readable string.



reboot-instances

Function

Package: net.ec2

Arguments: &rest instances

Reboots the specified instances. Returns t if successful.



describe-regions

Function

Package: net.ec2

Arguments: &rest region-names

Returns a list of regions and (possibly) their url.

region-names can be used to narrow the return value search to a specific set of region names.




Appendix D: EC2 other functionality


ec2-identity

Class

Package: net.ec2

This is the class for ec2-identities. You create an identity and set the value of *ec2-identity* to it when you start using the EC2 API. The slots are keypair-name (defaults to the value of *aws-keypair-name*), ssh-user (defaults to the value of *default-ssh-user*) and ssh-identity-file (defaults to the value of *default-ssh-identity-file*). See Section 2.0 EC2 setup and requirements for information of initializing the EC2 API. You create and identity instance with make-instance, as always with CLOS objects:

(make-instance 'ec2-identity)

There are three accessors to ec2-identity slots:


ec2-identity-ssh-identity-file

Generic Function

Package: net.ec2

Arguments: ec2-identity

Accessor to the ssh-identity-file slot of an ec2-identity.



ec2-identity-keypair-name

Generic Function

Package: net.ec2

Arguments: ec2-identity

Accessor to the keypair-name slot of an ec2-identity.



ec2-identity-ssh-user

Generic Function

Package: net.ec2

Arguments: ec2-identity

Accessor to the ssh-user slot of an ec2-identity.



ec2-error

Class

Package: net.ec2

The condition type of errors signaled by the Allegro CL EC2 API.



Copyright (c) 1998-2009, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 8.1. This page is new in the 8.1 release.
Created 2007.4.30.

ToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 8.1
New since 8.1 release.