| Allegro CL version 8.2 Significant update since 8.2 release. 8.1 version | ||||||||
This document contains the following sections:
1.0 EC2 introductionThe EC2 module was significantly (and not back-compatibly) revised in May of 2010, to handle regions. 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.1. The 8.1 documentation (linked to with the version 8.1 link at the top right of this document) describes the old interface.
*ec2-identity* has been removed. Because
regions are now supported and each region has its own distinct
identity, a single variable to hold the identity no longer
makes sense. As we note below, the identity
keyword argument has been removed from some operators. The identity in
those cases can be inferred from the instance
argument. In other operators, the identity
keyword argument remains but has nil as a
default.
The operators whose identity keyword argument has
been removed or has a new (nil) default
are: describe-instances (argument now defaults
to nil), run-instances (argument
now defaults to nil), wait-for-instances
(argument removed), wait-for-instance (argument removed) [this
function was mistakenly not documented
before], query-status (argument removed).
ec2-region, the class for EC2
regions. This class has readers/sccessors ec2-region-name, ec2-region-uri,
and
predicate ec2-region-p.
ec2-identity class.
ec2-instance class.
*region-us-east*, *region-us-west*, *region-eu-west*, *region-ap-southeast*. These definitions
are for convenience only. You can call make-instance on ec2-region and use that
value.
*default-region*: the default region.
*all-regions*: a list of all operating regions.
(&rest instances) to (instances
&key verbose).
(&rest instances) to (instances
&key verbose).
(&rest zone-names)
to (&key zone-names (region *default-region*)).
*default-ssh-identity-file* unexported.
*default-ssh-user* unexported.
*default-ami-name* unexported.
*default-instance-type* unexported.
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 2009-04-04. The Getting Started Guide for this version is described here: http://docs.amazonwebservices.com/AWSEC2/2009-04-04/GettingStartedGuide/. The API documentation for this version is here: http://developer.amazonwebservices.com/connect/entry.jspa?externalID=2489&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.
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.
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.
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.
ec2-identity and ec2-region classes,
there are readers rather than accessors for slots, so the values
cannot be changed with setf. (These values should all be
considered read-only.) The values in the CLOS objects are populated
by calls to the EC2 API.
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.
*aws-access-key*: your AWS access key.
*aws-secret-access-key*: your AWS secret
access key. Never give this to anyone and guard the security of this
access key.
*aws-keypair-name*: the name of your SSH
keypair. See create-key-pair for more information.
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:
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 *region-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 *region-us-west*))
Once you have created identies, it's probably a good idea to put the setting of
*aws-access-key*, *aws-secret-access-key*, and
*aws-keypair-name* in a file that is
appropriately protected. You can also specifiy
a *default-region*. 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 *identity-XXX1* (make-instance 'ec2-identity ...)) (setq *identity-XXX2* (make-instance 'ec2-identity ...)) (setq *default-region* *region-XXX-XXX*) ; if desired
The values of the following special variables should be considered read-only:
*ec2-signature-version*: the signature
version for API calls.
*ec2-api-version*: the EC2 API version
used by the Lisp API
The variable *ec2-signature-method* specifies the
encoding method.
Errors signaled by the Allegro CL EC2 API are of
type ec2-error.
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.
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.
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.
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.
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.
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.
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.
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.
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.
This section deals with registering, querying and deregistering images. The functions discussed are listed below. Follow the links for the complete definitions.
ec2-image instances) after updating the
information about them.
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
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.
ec2-instance
instances. See the full description for descriptions of the arguments.
ec2-instance instances.
ec2-instance. Returns a
list of status information for each terminated instance.
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):
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.
ec2-key instances.
t
upon success.
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):
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.
t upon success.
ec2-security-group. Information about the
security-groups is updated before being returned.
t
upon success.
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):
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.
ec2-instance. Returns
t if successful.
t if successful.
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.
This section deals with EBS volumes and snapshots. See Appendix C.6 Functionality for EBS manipulation for the formal descriptions of the functions mentioned.
ec2-volume instances.
ec2-attachment if successful.
ec2-attachment if successful.
ec2-snapshot if successful.
t if successful.
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):
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.
ec2-instances with slots containing new
values.
ec2-instance with slots containing new
values.
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):
See Appendix C.8 Miscellaneous operators for formal definitions of the functions listed in this section.
cl-user(117): (describe-availability-zones)
(("us-east-1c" . "available") ("us-east-1b" . "available")
("us-east-1a" . "available"))
cl-user(119):
nil is returned for the
string (so the return value is a singleton list containing the
universal time).
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):
t if successful.
cl-user(7): (describe-regions)
(("us-east-1") ("eu-west-1"))
cl-user(8):
The value should a string which is your AWS access key.
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.
The value should be a string which is the name of your SSH keypair. See create-key-pair for more information.
Update note: this variable has been removed.
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.
The signature version for API calls. Do not change the value of this symbol.
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.)
The EC2 API version used by the Lisp API. Do not change the value of this symbol.
This variable is no longer supported.
This variable is no longer supported.
This variable is no longer supported.
This variable is no longer supported.
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".
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:
Arguments: object
The predicate for the class ec2-instance, returning
true when the argument is an ec2-instance
and nil otherwise.
Arguments: ec2-instance
Accessor of the slot of ec2-instance (an
ec2-instance) holding the region at the
time of the instance's creation.
Arguments: ec2-instance
Accessor of data returned by EC2 API calls.
Arguments: ec2-instance
Accessor of data returned by EC2 API calls.
Arguments: ec2-instance
Accessor of data returned by EC2 API calls.
Arguments: ec2-instance
Accessor of data returned by EC2 API calls.
Arguments: ec2-instance
Accessor of data returned by EC2 API calls.
Arguments: ec2-instance
Accessor of data returned by EC2 API calls.
Arguments: ec2-instance
Accessor of data returned by EC2 API calls.
Arguments: ec2-instance
Accessor of data returned by EC2 API calls.
Arguments: ec2-instance
The value is meta-information indirectly gleaned from EC2 API calls.
Arguments: ec2-instance
Accessor of data returned by EC2 API calls.
Arguments: ec2-instance
Accessor of data returned by EC2 API calls.
Arguments: ec2-instance
Accessor of data returned by EC2 API calls.
Arguments: ec2-instance
Accessor of data returned by EC2 API calls.
Arguments: ec2-instance
Accessor of data returned by EC2 API calls.
Arguments: ec2-instance
Accessor of data returned by EC2 API calls.
Arguments: ec2-instance
Accessor of data returned by EC2 API calls.
Arguments: ec2-instance
Accessor of data returned by EC2 API calls.
Arguments: ec2-instance
The value is meta-information indirectly gleaned from EC2 API calls.
Arguments: ec2-instance
The EC2 identity used in SSH access of the remotely running instance.
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:
Arguments: object
The predicate for the class ec2-image, returning
true when the argument is an ec2-image
and nil otherwise.
Arguments: ec2-image
The accessor to the named slot of an ec2-image.
Arguments: ec2-image
The accessor to the named slot of an ec2-image.
Arguments: ec2-image
The accessor to the named slot of an ec2-image.
Arguments: ec2-image
The accessor to the named slot of an ec2-image.
Arguments: ec2-image
The accessor to the named slot of an ec2-image.
Arguments: ec2-image
The accessor to the named slot of an ec2-image.
Arguments: ec2-image
The accessor to the named slot of an ec2-image.
Arguments: ec2-image
The accessor to the named slot of an ec2-image.
Arguments: ec2-image
The accessor to the named slot of an ec2-image.
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:
Arguments: object
The predicate for the class ec2-key, returning
true when the argument is an ec2-key
and nil otherwise.
Arguments: ec2-key
The accessor to the named slot of an ec2-key.
Arguments: ec2-key
The accessor to the named slot of an ec2-key.
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:
Arguments: object
The predicate for the class ec2-security-group, returning
true when the argument is an ec2-security-group
and nil otherwise.
Arguments: ec2-security-group
The accessor to the named slot of an ec2-security-group.
Arguments: ec2-security-group
The accessor to the named slot of an ec2-security-group.
Arguments: ec2-security-group
The accessor to the named slot of an ec2-security-group.
Arguments: ec2-security-group
The accessor to the named slot of an ec2-security-group.
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:
Arguments: object
The predicate for the class ec2-ip-permissions, returning
true when the argument is an ec2-ip-permissions
and nil otherwise.
Arguments: ec2-ip-permissions
The accessor to the named slot of an ec2-ip-permissions.
Arguments: ec2-ip-permissions
The accessor to the named slot of an ec2-ip-permissions.
Arguments: ec2-ip-permissions
The accessor to the named slot of an ec2-ip-permissions.
Arguments: ec2-ip-permissions
The accessor to the named slot of an ec2-ip-permissions.
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:
Arguments: object
The predicate for the class ec2-volume, returning
true when the argument is an ec2-volume
and nil otherwise.
Arguments: ec2-volume
The accessor to the named slot of an ec2-volume.
Arguments: ec2-volume
The accessor to the named slot of an ec2-volume.
Arguments: ec2-volume
The accessor to the named slot of an ec2-volume.
Arguments: ec2-volume
The accessor to the named slot of an ec2-volume.
Arguments: ec2-volume
The accessor to the named slot of an ec2-volume.
Arguments: ec2-volume
The accessor to the named slot of an ec2-volume.
Arguments: ec2-volume
(Previously names ec2-volume-zone.) The accessor to the named
slot of an ec2-volume.
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:
Arguments: object
The predicate for the class ec2-attachment, returning
true when the argument is an ec2-attachment
and nil otherwise.
Arguments: ec2-attachment
The accessor to the named slot of an ec2-attachment.
Arguments: ec2-attachment
The accessor to the named slot of an ec2-attachment.
Arguments: ec2-attachment
The accessor to the named slot of an ec2-attachment.
Arguments: ec2-attachment
The accessor to the named slot of an ec2-attachment.
Arguments: ec2-attachment
The accessor to the named slot of an ec2-attachment.
Arguments: ec2-attachment
The accessor to the named slot of an ec2-attachment.
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:
Arguments: object
The predicate for the class ec2-snapshot, returning
true when the argument is an ec2-snapshot
and nil otherwise.
Arguments: ec2-snapshot
The accessor to the named slot of the snapshot class.
Arguments: ec2-snapshot
The accessor to the named slot of the snapshot class.
Arguments: ec2-snapshot
The accessor to the named slot of the snapshot class.
Arguments: ec2-snapshot
The accessor to the named slot of the snapshot class.
Arguments: ec2-snapshot
The accessor to the named slot of the snapshot class.
Arguments: manifest &key (region *default-region*)
Update note: the region keyword argument was added in the May, 2010 update.
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.
Arguments: &key image-id owner executable-by (region *default-region*)
Update note: the region keyword argument was added in the May, 2010 update.
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.
Arguments: image-id &key (region *default-region*)
Update note: the region keyword argument was added in the May, 2010 update.
Deregister an image, where image-id is the image instance returned by a call to register-image or describe-images.
Returns t upon success.
See Section 5.0 Functions for instance manipulation for more information and examples.
Arguments: image-id min-count max-count &key wait verbose identity region instance-type kernel-id ramdisk-id availability-zone
Update note: the region keyword argument was added and the key-name keyword argument was removed in the May, 2010 update.
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:
nil, then this function returns
immediately, even before the newly run instance is usable.
:wait t.
Arguments: &key (states (quote (:running :shutting-down :pending))) identity instances region
Update note: in the May, 2010 update,
the region keyword argument was added; the
identity argument now defaults
to nil, and one
of identity and instance
must be specified..
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.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. 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.
Arguments: instances &key verbose
Update note: the argument list was changed incompatible (from (&rest instances to the present list) in the May 2010 update.
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.
See Section 6.0 Functions for key pair manipulation for more information and examples using the functions defined in this section.
Arguments: key-name &key (region *default-region*)
Update note: the region keyword argument was added in the May, 2010 update.
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*.
Arguments: &key key-names (region *default-region*)
Update note: the region keyword argument was added in the May, 2010 update.
Retrieve the active key pairs and return a list
of ec2-key instances, after updating the
information cached in Lisp about them.
Arguments: key-name &key (region *default-region*)
Update note: the region keyword argument was added in the May, 2010 update.
Delete the key pair given by key-name.
Returns t upon success.
See Section 7.0 Functions for security manipulation for more information and examples using the functions defined in this section.
Arguments: name description &key (region *default-region*)
Update note: the region keyword argument was added in the May, 2010 update.
Creates a new security group named name
with description `description', both strings.
Returns t upon success.
Arguments: &key group-names (region *default-region*)
Update note: the region keyword argument was added in the May, 2010 update.
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.
Arguments: name &key (region *default-region*)
Update note: the region keyword argument was added in the May, 2010 update.
Deletes a security group named name.
Returns t upon success.
Arguments: name &key (region *default-region*) ip-protocol from-port to-port cidr-ip
Update note: in the May, 2010 update, the keyword arguments source-group-name and source-group-owner-id were removed in order to conform to the EC2 API. The region keyword argument was added.
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.
source-group-name and source-group-owner-id are used to add an owner to a group.
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.
Arguments: name &key (region *default-region*) ip-protocol from-port to-port cidr-ip
Update note: in the May, 2010 update, the keyword arguments source-group-name and source-group-owner-id were removed in order to conform to the EC2 API. The region keyword argument was added.
This function is the inverse of authorize-security-group-ingress, revoking any authorization granted by previous calls to that function.
See Section 8.0 Functions for Elastic IP address manipulation for more information and examples.
Arguments: &key (region *default-region*)
Update note: the region keyword argument was added in the May, 2010 update.
Allocates an Elastic, or static, IP address
for region, which defaults
to *default-region*. It is returned as a
string, if successful.
Arguments: &key (region *default-region*)
Update note: the region keyword argument was added in the May, 2010 update.
Returns a list of the current mapping of IP to AMI
for region (defaults
to *default-region*) in a list.
Arguments: ip &key (region *default-region*)
Update note: the region keyword argument was added in the May, 2010 update.
Release an elastic IP address for region,
given by ip, a
string. region defaults to
*default-region*.
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.
Arguments: ip &key (region *default-region*)
Update note: the region keyword argument was added in the May, 2010 update.
Disassociates IP ip' from whatever
instance it is associated with in region,
which defaults to *default-region*. Returns t
if successful.
See Section 9.0 Functions for EBS manipulation for further information and an example using these functions.
Arguments: availability-zone &key size snapshot (region *default-region*)
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 region, which defaults
to *default-region*. Only one of the
arguments size or snapshot
can be given.
Arguments: &key volumes (region *default-region*)
Update note: the region keyword argument was added in the May, 2010 update.
return a list of all active volumes (if volumes
is unspecified) or a list of volumes specified
by volumes in region,
which defaults to *default-region*.
volumes,
if specified, should be a list of ec2-volume
instances. Returns a list of ec2-volume instances.
Arguments: volume &key (region *default-region*)
Update note: the region keyword argument was added in the May, 2010 update.
Delete the given volume in region, which
defaults to *default-region*. volume
must be of type ec2-volume.
Returns t if successful.
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.
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.
Arguments: volume &key (region *default-region*)
Create a snapshot of volume
in region (which defaults
to *default-region*), returning an
ec2-snapshot if successful.
Arguments: &key snapshots (region *default-region*)
Returns a list of description of all current snapshots
in region (which defaults
to *default-region*), or of those specified
by snapshots if specified, after updating
the information cached in Lisp about them. Returns a list
of ec2-snapshot instances.
Arguments: snapshot &key (region *default-region*)
Delete the given snapshot
in region, which defaults
to *default-region*.
Returns t if successful.
See Section 10.0 High-level EC2 functions for more information on these functions.
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.
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.
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.
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.
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.
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.
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.
See Section 11.0 Miscellaneous functions for more information and examples.
Arguments: &key zone-names (region *default-region*)
Update note: the zone-names argument was changes from an &rest argument to a keyword argument and the region keyword argument was added in the May, 2010 update.
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. region specifies the region and
defaults to *default-region*.
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.
Arguments: instances &key verbose
Update note: the argument list was changed incompatible (from (&rest instances to the present list) in the May 2010 update.
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.
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.
Update note: this class and its associated functionality were added in the May 2010 update.
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-region* 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:
Arguments: ec2-region
The official EC2 name of the region (e.g.,
"us-west-1"). See ec2-region.
Arguments: ec2-region
The base URI of the region's service. This is defined by Amazon. The
URL for us-east-1 is "https://ec2.amazonaws.com/", for example.
See ec2-region.
The predicate for ec2-region is:
Arguments: object
Returns true if object is an instance
of ec2-region. Returns nil
otherwise.
The following variables are predefined regions.
The US East predefined region.
The US West predefined region.
The Europe West predefined region.
The Southeast Asia predefined region.
This variable can be set to an ec2-region instance. It serves as the
default for the region keyword argument to may functions.
A list of all operating regions. See ec2-region.
Update note: before the May 2010 update, there was one identity
which was the value of *ec2-identity*. Now with region support,
there can be many and the variable *ec2-identity*
has been removed.
This is the class for ec2-identities. Identities are region-specific. You create an identity and associate it with a region.
The slots are keypair-name (defaults to
the value of *aws-keypair-name*), ssh-user,
and 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 four accessors to ec2-identity slots:
Arguments: ec2-identity
This generic function was added in the May, 2010 update.
Accesses the rigion associated with the argument, which should be an
instance of ec2-identity.
Arguments: ec2-identity
Accessor to the ssh-identity-file slot of
an ec2-identity.
Arguments: ec2-identity
Accessor to the keypair-name slot of
an ec2-identity.
Arguments: ec2-identity
Accessor to the ssh-user slot of
an ec2-identity.
The condition type of errors signaled by the Allegro CL EC2 API.
Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.
| Allegro CL version 8.2 Significant update since 8.2 release. 8.1 version | ||||||||