| Allegro CL version 9.0 Significantly revised from 8.2. 8.2 version | ||||||||
This document contains the following sections:
1.0 EC2 introduction and release notes for 9.0The 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:
You must update your images to see the November, 2014 changes (see sys:update-allegro).
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.
The following symbols have been unexported (some were not included in the released documentation).
*default-identity*
ec2-region class has a new endpoint slot,
see ec2-region-endpoint.
ec2-region) but instead calculates the URI
from the endpoint.
ec2-identity instances.
*all-regions* has been updated to include
all recently added AWS regions.
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.
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 3.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.
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")))
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.
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 copying, 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):
This variable is no longer supported. Instead, use the
ec2-identity-access-key accessot to
an ec2-identity instance.
This variable is no longer supported. Instead, use the
ec2-identity-secret-access-key accessot to
an ec2-identity instance.
This variable is no longer supported. Instead, use the
ec2-identity-keypair-name accessot to
an ec2-identity instance.
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: 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.
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.
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.
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.
See Section 6.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
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
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.
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.
See Section 7.0 Functions for key pair manipulation for more information and examples using the functions defined in this section.
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*.
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.
Arguments: key-name &key (identity *default-identity*)
Delete the key pair given by key-name.
Returns t upon success.
See Section 8.0 Functions for security manipulation for more information and examples using the functions defined in this section.
Arguments: name description &key (identity *default-identity*)
Creates a new security group named name
with description `description', both strings.
Returns t upon success.
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.
Arguments: name &key (identity *default-identity*)
Deletes a security group named name.
Returns t upon success.
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.
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 (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.
See Section 9.0 Functions for Elastic IP address manipulation for more information and examples.
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.
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.
Arguments: ip &key (identity *default-identity*)
Release an elastic IP address for identity,
given by ip, a
string. identity defaults to
*default-identity*.
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 (identity *default-identity*)
Disassociates IP ip' from whatever
instance it is associated with in identity,
which defaults to *default-identity*. Returns t
if successful.
See Section 10.0 Functions for EBS manipulation for further information and an example using these functions.
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.
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.
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.
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 (identity *default-identity*)
Create a snapshot of volume
in identity (which defaults
to *default-identity*), returning an
ec2-snapshot if successful.
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.
Arguments: snapshot &key (identity *default-identity*)
Delete the given snapshot
in identity, which defaults
to *default-identity*.
Returns t if successful.
See Section 11.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 12.0 Miscellaneous functions for more information and examples.
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*.
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
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.
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:
:error (the default): an error is signaled
nil but not :error: a
warning is signaled, nil is returned
nil: nil is returned
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:
Arguments: ec2-region
The official EC2 name of the region (e.g.,
"us-west-1"). See ec2-region.
Arguments: ec2-region
Accessor for the endpoint slot of the argument ec2-region.
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:
Arguments: object
Returns true if object is an instance
of ec2-region. Returns nil
otherwise.
The following variables are predefined regions.
This variable has been removed. See find-region-by-name and
*all-regions* which can be used to get
region objects.
This variable has been removed. See find-region-by-name and
*all-regions* which can be used to get
region objects.
This variable has been removed. See find-region-by-name and
*all-regions* which can be used to get
region objects.
This variable has been removed. See find-region-by-name and
*all-regions* which can be used to get
region objects.
This variable can be set to an ec2-region instance.
A list of all operating regions. See ec2-region
and find-region-by-name.
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)
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:
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:
Arguments: ec2-identity
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.
Arguments: ec2-identity
Accessor to the access-key slot of
an ec2-identity.
Arguments: ec2-identity
Accessor to the secret-access-key slot of
an ec2-identity.
Arguments: ec2-identity
Accessor to the account-number slot of
an ec2-identity.
Arguments: ec2-identity
Accessor to the certificate slot of
an ec2-identity.
Arguments: ec2-identity
Accessor to the private-key slot of
an ec2-identity.
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.
| Allegro CL version 9.0 Significantly revised from 8.2. 8.2 version | ||||||||