ToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 9.0
Significantly revised from 8.2.
8.2 version

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

This document contains the following sections:

1.0 EC2 introduction and release notes for 9.0
   1.1 region keyword argument removed, identity keyword argument added
   1.2 net.ec2 symbols which have been unexported
   1.3 Other release notes
2.0 EC2 introduction
   2.1 The EC2 module, package, and supported platforms
   2.2 Example requirements
   2.3 General comments on the EC2 interface
3.0 EC2 setup and requirements
4.0 EC2 classes
5.0 Functions for image manipulation
6.0 Functions for instance manipulation
7.0 Functions for key pair manipulation
8.0 Functions for security manipulation
9.0 Functions for Elastic IP address manipulation
10.0 Functions for EBS manipulation
11.0 High-level EC2 functions
12.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: ec2-region, ec2-identity, and ec2-error


1.0 EC2 introduction and release notes for 9.0

The EC2 module was significantly (and not back-compatibly) revised in the 9.0 release. Because of code changes (some symbols are no longer exported, some argument lists have changed, etc.), code that worked before the update may no longer work. We start with release notes describing the changes. This document has been updated to reflect the new functionality. The update does not apply to version 8.2 (and earlier). The 8.2 documentation (linked to with the version 8.2 link at the top right of this document) describes the old interface.

A further update in early November, 2014, made these changes:

  1. The signing version is now Version 4. New regions introduced after 1/1/2014 only support Version 4 signing. (This change is internal and does not affect user code.)
  2. API version support is now 2014-09-01.

You must update your images to see the November, 2014 changes (see sys:update-allegro).


1.1 region keyword argument removed, identity keyword argument added

The region keyword argument has been removed and an identity keyword argument has been added to the functions listed just below. Below that is a list of functions which had identity arguments already as well as region arguments. Their region arguments have been removed. The region arguments defaulted to the value of *default-region*. The identity argument defaults to *default-identity*.

The identity should be an instance of the ec2-identity class, which contains the region in its ec2-identity-region slot, along with other information. The region will be extracted from that instance.

The following functions already had an identity keyword argument as well as a region keyword argument. The region keyword argument has been removed.


1.2 net.ec2 symbols which have been unexported

The following symbols have been unexported (some were not included in the released documentation).


1.3 Other release notes

New exports from the net.ec2 package:

Other notes



2.0 EC2 introduction

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 2014-09-01. The Getting Started Guide is here: http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EC2_GetStarted.html. The API documentation for this version is here: http://docs.aws.amazon.com/AWSEC2/latest/APIReference/Welcome.html.

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 (note the SOAP API is deprecated by Amazon). 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: https://aws.amazon.com/developertools/9302537431253167.

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.


2.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.


2.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 3.0 EC2 setup and requirements. See the information in that section under the heading Using a file to set the keys and identity.


2.3 General comments on the EC2 interface



3.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.

To use the EC2 interface, you must create a default identity and make it the value of *default-identity* and following three slot must be filled with the AWS access key, the secret access key, and the keypair name using the accessors ec2-identity-access-key, ec2-identity-secret-access-key, and ec2-identity-keypair-name.

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

(setf (ec2-identity-access-key *default-identity*) [your access key])
(setf (ec2-identity-secret-access-key *default-identity*) [your secret access key])
;; Never give this to anyone and guard the security of this secret access key.
(setf (ec2-identity-keypair-name *default-identity*) [your keypair name])
;; See create-key-pair for more information.

;; You can specify those values with init args as well as using
;; the accessors.

Once you have set the access key and the secret access key, you need to put together the identities you will be using. The components of an identity are given by the ec2-identity class, and are (in addition to the three mentioned above):

The SSH user will vary depending on the AMI you are using. For Ubuntu (Linux) it will be "ubuntu". For Fedora (Linux) it will be "root".

Here are some example identities that you might use (assumes the net.ec2 package has been used):

(defparameter *identity-us-east*
   (make-instance 'ec2-identity
     :ssh-user "ubuntu"
     :keypair-name "aws-us-east"
     :ssh-identity-file "~/.ssh/aws-us-east.pem"
     :region (find-region-by-name "us-east")))

(defparameter *identity-us-west*
   (make-instance 'ec2-identity
     :ssh-user "ubuntu"
     :keypair-name "aws-us-west"
     :ssh-identity-file "~/.ssh/aws-us-west.pem"
     :region  (find-region-by-name "us-west")))

Using a file to set the keys, regions, and identities

Once you have created identities, it's probably a good idea to put the settings of ec2-identity-access-key, ec2-identity-secret-access-key, and ec2-identity-keypair-name in a file that is appropriately protected. You can also specifiy a *default-identity* (to capture other slots). The examples below will use ~/src/aws.cl. It should contain something like this:

  (in-package :net.ec2)

  (setq *default-identity* (make-instance 'ec2-identity))
  (setf (ec2-identity-access-key *default-identity*) [your access key])
  (setf (ec2-identity-secret-access-key *default-identity*) [your secret access key])
  (setf (ec2-identity-keypair-name *default-identity*) [your keypair name])
;; etc.

Other variables

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

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

EC2 errors

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



4.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.



5.0 Functions for image manipulation

This section deals with copying, 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


6.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): 


7.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): 


8.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): 


9.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.



10.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): 


11.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): 


12.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 ([email protected]) (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

This variable is no longer supported. Instead, use the ec2-identity-access-key accessot to an ec2-identity instance.



*aws-secret-access-key*

Variable

Package: net.ec2

This variable is no longer supported. Instead, use the ec2-identity-secret-access-key accessot to an ec2-identity instance.



*aws-keypair-name*

Variable

Package: net.ec2

This variable is no longer supported. Instead, use the ec2-identity-keypair-name accessot to an ec2-identity instance.



*ec2-identity*

Variable

Package: net.ec2

This variable has been removed. In earlier versions of the interface, there was only one ec2-identity instance so it made sense to have it be the value of a variable, but now identities are associated with regions and there can be many.



*ec2-signature-version*

Variable

Package: net.ec2

The signature version for API calls. Do not change the value of this symbol.



*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.)



*ec2-api-version*

Variable

Package: net.ec2

The EC2 API version used by the Lisp API. Do not change the value of this symbol.



*default-ssh-identity-file*

Variable

Package: net.ec2

This variable is no longer supported.



*default-ssh-user*

Variable

Package: net.ec2

This variable is no longer supported.



*default-instance-type*

Variable

Package: net.ec2

This variable is no longer supported.



*default-ami-name*

Variable

Package: net.ec2

This variable is no longer supported.



*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-region

Generic Function

Package: net.ec2

Arguments: ec2-instance

Accessor of the slot of ec2-instance (an ec2-instance) holding the region at the time of the instance's creation.



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


copy-image

Function

Package: net.ec2

Arguments: source-region source-image-id &key (identity *default-identity*)

Copies source-image-id from source-region to the region specified in identity. This allows copying AMIs from one region to another.



register-image

Function

Package: net.ec2

Arguments: manifest &key (identity *default-identity*)

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 (identity *default-identity*)

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 &key (identity *default-identity*)

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 6.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 region instance-type 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 instances region

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.

One of instance and identity must be specified. If instance is specified, the region and identity are inferred, so they should not be specified (as they will be either redundant or incorrect).

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.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-lifecycle.html, 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. Should not be specified if instance is.

The argument region specifies the region. If identity is also specified, it must be associated with region if region is also specified and the value of region defaults to the region associated with the specified identity. Should not be specified if instance is.

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: instances &key verbose

Terminate the set of instances given by instances, which should be a single instance of a list of instances, all of class ec2-instances.

If verbose is specified true, additional information will be printed.

Returns a list of status information for each terminated instance.



Appendix C.3 Key pair manipulation operators

See Section 7.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 &key (identity *default-identity*)

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 (identity *default-identity*)

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 &key (identity *default-identity*)

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



Appendix C.4 Security manipulation operators

See Section 8.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 &key (identity *default-identity*)

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 (identity *default-identity*)

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 &key (identity *default-identity*)

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



authorize-security-group-ingress

Function

Package: net.ec2

Arguments: name &key (identity *default-identity*) 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 (identity *default-identity*) 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 9.0 Functions for Elastic IP address manipulation for more information and examples.


allocate-address

Function

Package: net.ec2

Arguments: &key (identity *default-identity*)

Allocates an Elastic, or static, IP address for identity, which defaults to *default-identity*. It is returned as a string, if successful.



describe-addresses

Function

Package: net.ec2

Arguments: &key (identity *default-identity*)

Returns a list of the current mapping of IP to AMI for identity (defaults to *default-identity*) in a list.



release-address

Function

Package: net.ec2

Arguments: ip &key (identity *default-identity*)

Release an elastic IP address for identity, given by ip, a string. identity defaults to *default-identity*.



associate-address

Function

Package: net.ec2

Arguments: instance ip

Associate IP ip, a string, with instance (an ec2-instance). Returns t if successful. The relevant region (see ec2-region) is inferred from the instance.



disassociate-address

Function

Package: net.ec2

Arguments: ip &key (identity *default-identity*)

Disassociates IP ip' from whatever instance it is associated with in identity, which defaults to *default-identity*. Returns t if successful.



Appendix C.6 Functionality for EBS manipulation

See Section 10.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 (identity *default-identity*)

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, in identity, which defaults to *default-identity*. Only one of the arguments size or snapshot can be given.



describe-volumes

Function

Package: net.ec2

Arguments: &key volumes (identity *default-identity*)

return a list of all active volumes (if volumes is unspecified) or a list of volumes specified by volumes in identity, which defaults to *default-identity*. 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 &key (identity *default-identity*)

Delete the given volume in identity, which defaults to *default-identity*. 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). The relevant region (see ec2-region) is inferred from the instance.

Returns an instance of ec2-attachment if successful.



detach-volume

Function

Package: net.ec2

Arguments: volume instance &key device force

Detach volume on instance in the region (see ec2-region) inferred from the 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 &key (identity *default-identity*)

Create a snapshot of volume in identity (which defaults to *default-identity*), returning an ec2-snapshot if successful.



describe-snapshots

Function

Package: net.ec2

Arguments: &key snapshots (identity *default-identity*)

Returns a list of description of all current snapshots in identity (which defaults to *default-identity*), 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 &key (identity *default-identity*)

Delete the given snapshot in identity, which defaults to *default-identity*. Returns t if successful.



Appendix C.7 High-level operators

See Section 11.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

Wait for instances to enter a particular state. instances can be a single instance of a list of instances (see ec2-instance). The relevant regions (see ec2-region) is inferred from the instances, as are the relevant identities (see ec2-identity).

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.



wait-for-instance

Function

Package: net.ec2

Arguments: instance &key (state :running) verbose (sleep 2) identity

Wait for instance to enter a particular state. instance must be a single instance (see ec2-instance). The relevant region (see ec2-region) is inferred from the instance, as are the relevant identity (see ec2-identity).

state is a keyword identifying the state the instance 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 instance is in the new state, this function returns a newly made instance of type ec2-instance. A new instance is returned rather than the argument instance because the status of various slots could have different values.



query-status

Function

Package: net.ec2

Arguments: instance

Return two values: the status of instance, and a new copy of the instance, just in case it changed. The relevant region (see ec2-region) is inferred from the instance, as is the relevant identity (see ec2-identity).

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 12.0 Miscellaneous functions for more information and examples.


describe-availability-zones

Function

Package: net.ec2

Arguments: &key zone-names (identity *default-identity*)

Returns a list of availability zones and their current status. zone-names, which must be a single name or a list of names, can be used to narrow the return value search to a specific set of zone names. identity specifies the region and defaults to *default-identity*.



get-console-output

Function

Package: net.ec2

Arguments: instance

Return the console output from instance, as a string. The relevant region is inferred from the instance.

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: instances &key verbose

Reboots the specified instances (a single instance or a list of instances of class ec2-instance). Returns t if successful.

If verbose is specified true, additional information will be printed.



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.



find-region-by-name

Function

Package: net.ec2

Arguments: substring &key (if-does-not-exist :error)

This function returns an ec2-region instance corresponding to the region named by the substring argument. If no region can be found with that matching that name, as a substring, the result depends on the value of the if-does-not-exist keyword argument, which can have the following values:




Appendix D: EC2 other functionality: ec2-region, ec2-identity, and ec2-error


ec2-region

Class

Package: net.ec2

This is the class for ec2-regions. You can have several regions and have an identy for each region. ec2-instances have a region slot and the region can be inferred from an instance. There are several variables holding region objects and new regions can be created with make-instance, specifying the name and the URL (both of which are defined by Amazon). Here is an example:

(make-instance 'ec2-region :region-name "us-east-1" 
                 :region-url "https://ec2.amazonaws.com/")

The variable *default-identity* can be used to specify the default value of the region keyword argument to many functions. The value of the variable *all-regions* is a list of all operating regions.


There are two accessors to ec2-region slots:


ec2-region-name

Generic Function

Package: net.ec2

Arguments: ec2-region

The official EC2 name of the region (e.g., "us-west-1"). See ec2-region.



ec2-region-endpoint

Generic Function

Package: net.ec2

Arguments: ec2-region

Accessor for the endpoint slot of the argument ec2-region.



ec2-region-uri

Generic Function

Package: net.ec2

Arguments: ec2-region

The default method of this generic function computes the URI for the endpoint of of the ec2-region instance. It works essentially as follows:

     (net.uri:parse-uri
       (format nil "https://~a/" (ec2-region-endpoint region)))

See ec2-region.


The predicate for ec2-region is:


ec2-region-p

Generic Function

Package: net.ec2

Arguments: object

Returns true if object is an instance of ec2-region. Returns nil otherwise.


The following variables are predefined regions.


*region-us-east*

Variable

Package: net.ec2

This variable has been removed. See find-region-by-name and *all-regions* which can be used to get region objects.



*region-us-west*

Variable

Package: net.ec2

This variable has been removed. See find-region-by-name and *all-regions* which can be used to get region objects.



*region-eu-west*

Variable

Package: net.ec2

This variable has been removed. See find-region-by-name and *all-regions* which can be used to get region objects.



*region-ap-southeast*

Variable

Package: net.ec2

This variable has been removed. See find-region-by-name and *all-regions* which can be used to get region objects.



*default-region*

Variable

Package: net.ec2

This variable can be set to an ec2-region instance.



*all-regions*

Variable

Package: net.ec2

A list of all operating regions. See ec2-region and find-region-by-name.


ec2-identity


ec2-identity

Class

Package: net.ec2

This is the class for ec2-identities. Identities are region-specific. You create an identity and associate it with a region. The slots are access-key, secret-access-key, account-number, certificate, private-key, keypair-name, ssh-user, and ssh-identity-file. See Section 3.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)


*default-identity*

Variable

Package: net.ec2

This variable can be set to an ec2-identity instance. It serves as the default for the identity keyword argument to many functions. This variable should be set when you use the EC2 interface.


This function will copy ec2-identity instances:


copy-ec2-identity

Function

Package: net.ec2

Arguments: ec2-identity &key ssh-identity-file ssh-user keypair-name region

This function allows for an easy method for creating an identity in a different region, etc, while starting with an existing instance.


These are the accessors to ec2-identity slots:


ec2-identity-region

Generic Function

Package: net.ec2

Arguments: ec2-identity

Accesses the rigion associated with the argument, which should be an instance of ec2-identity.



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-identity-access-key

Generic Function

Package: net.ec2

Arguments: ec2-identity

Accessor to the access-key slot of an ec2-identity.



ec2-identity-secret-access-key

Generic Function

Package: net.ec2

Arguments: ec2-identity

Accessor to the secret-access-key slot of an ec2-identity.



ec2-identity-account-number

Generic Function

Package: net.ec2

Arguments: ec2-identity

Accessor to the account-number slot of an ec2-identity.



ec2-identity-certificate

Generic Function

Package: net.ec2

Arguments: ec2-identity

Accessor to the certificate slot of an ec2-identity.



ec2-identity-private-key

Generic Function

Package: net.ec2

Arguments: ec2-identity

Accessor to the private-key slot of an ec2-identity.


ec2-error


ec2-error

Class

Package: net.ec2

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



Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page has had significant revisions compared to the 8.2 page.
Created 2019.8.20.

ToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 9.0
Significantly revised from 8.2.
8.2 version