Provided by: libvm-ec2-perl_1.23-1_all 
NAME
VM::EC2::Staging::Server - High level interface to EC2-based servers
SYNOPSIS
use VM::EC2::Staging::Manager;
# get a new staging manager
my $ec2 = VM::EC2->new;
my $staging = $ec2->staging_manager(); );
# Fetch a server named 'my_server'. Create it if it does not already exist.
my $server1 = $staging->get_server(-name => 'my_server',
-availability_zone => 'us-east-1a',
-architecture => 'i386',
-instance_type => 't1.micro');
# As above, but force a new server to be provisioned.
my $server2 = $staging->provision_server(-name => 'my_server',
-availability_zone => 'us-east-1a',
-architecture => 'i386',
-instance_type => 't1.micro');
# open up a terminal emulator in a separate window
$server1->shell;
# Run a command over ssh on the server. Standard in and out will be connected to
# STDIN/OUT
$server1->ssh('whoami');
# run a command over ssh on the server, returning standard output as an array of lines or a
# scalar string, similar to backticks (``)
my @password_lines = $server1->scmd('cat /etc/passwd');
# run a command on the server and read from it using a filehandle
my $fh = $server1->scmd_read('ls -R /usr/lib');
while (<$fh>) { # do something }
# run a command on the server and write to it using a filehandle
my $fh = $server1->scmd_write('sudo -s "cat >>/etc/fstab"');
print $fh "/dev/sdf3 /mnt/demo ext3 0 2\n";
close $fh;
# provision and mount a 5 gig ext3 volume mounted on /opt, returning
# VM::EC2::Staging::Volume object
my $opt = $server1->provision_volume(-mtpt => '/opt',
-fstype => 'ext3',
-size => 5);
# copy some data from the local filesystem onto the opt volume
$server1->rsync("$ENV{HOME}/local_staging_volume/" => $opt);
# same thing, but using server path name
$server1->put("$ENV{HOME}/local_staging_volume/" => '/opt');
# provision a volume attached to another server, and let the
# system choose the filesystem and mount point for us
my $backups = $server2->provision_volume(-name => 'Backup',
-size => 10);
# copy some data from opt to the new volume using rsync
$server1->rsync($opt => "$backups/opt");
# Do a block-level copy between disks - warning, the filesystem must be unmounted
# before you attempt this.
$backups->unmount;
$server1->dd($opt => $backups);
DESCRIPTION
VM::EC2::Staging::Server objects are an extension of VM::EC2::Instance to allow for
higher-level access, including easy management of ssh keys, remote copying of data from
one server to another, and executing of remote commands on the server from within Perl.
See VM::EC2::Staging::Manager for an overview of staging servers and volumes.
Note that proper functioning of this module is heavily dependent on running on a host
system that has access to ssh, rsync and terminal emulator command-line tools. It will
most likely fail when run on a Windows host.
Staging Server Creation
Staging servers are usually created via a staging manager's get_server() or
provision_server() methods. See VM::EC2::Staging::Manager.
There is also a new() class method that is intended to be used internally in most cases.
It is called like this:
$server = VM::EC2::Staging::Server->new(%args)
With the arguments:
-keyfile path to the ssh public/private keyfile for this instance
-username username for remote login on this instance
-instance VM::EC2::Instance to attach this server to
-manager VM::EC2::Staging::Manager in same zone as the instance
Note that you will have to launch a staging manager, start an instance, and appropriate
provision the SSH credentials for that instance before invoking new() directly.
Information about the Server
VM::EC2::Staging::Server objects have all the methods of VM::EC2::Instance, such as
dnsName(), but add several new methods. The new methods involving getting basic
information about the server are listed in this section.
$name = $server->name
This method returns the server's symbolic name, if any.
Servers can optionally be assigned a symbolic name at the time they are created by the
manager's get_server() or provision_server() methods. The name persists as long as the
underlying instance exists (including in stopped state for EBS-backed instances). Calling
$manager->get_server() with this name returns the server object.
$ec2 = $server->ec2
Return the VM::EC2 object associated with the server.
$ec2 = $server->endpoint
Return the endpoint URL associated with this server.
$instance = $server->instance
Return the VM::EC2::Instance associated with this server.
$file = $server->keyfile
Return the full path to the SSH PEM keyfile used to log into this server.
$user = $server->username
Return the name of the user (e.g. 'ubuntu') used to ssh into this server.
$manager = $server->manager
Returns the VM::EC2::Staging::Manager that manages this server.
Lifecycle Methods
The methods in this section manage the lifecycle of a server.
$flag = $server->ping
The ping() method returns true if the server is running and is reachable via ssh. It is
different from checking that the underlying instance is "running" via a call to
current_status, because it also checks the usability of the ssh daemon, the provided ssh
key and username, firewall rules, and the network connectivity.
The result of ping is cached so that subsequent invocations return quickly.
$result = $server->start
Attempt to start a stopped server. The method will wait until a ping() is successful, or
until a timeout of 120 seconds. The result code will be true if the server was
successfully started and is reachable.
If you wish to start a set of servers without waiting for each one individually, then you
may call the underling instance's start() method:
$server->instance->start;
You may then wish to call the staging manager's wait_for_instances() method to wait on all
of the servers to start:
$manager->wait_for_servers(@servers);
Also check out $manager->start_all_servers().
$result = $server->stop
Attempt to stop a running server. The method will wait until the server has entered the
"stopped" state before returning. It will return a true result if the underlying instance
stopped successfully.
If you wish to stop a set of servers without waiting for each one individually, then you
may call the underling instance's start() method:
$server->instance->stop;
You may then wish to call the staging manager's wait_for_instances() method to wait on all
of the servers to start:
$status = $manager->wait_for_servers(@servers);
Also check out $manager->stop_all_servers().
$result = $server->terminate
Terminate a server and unregister it from the manager. This method will stop and wait
until the server is terminated.
If you wish to stop a set of servers without waiting for each one individually, then you
may call the underling instance's start() method:
$server->instance->terminate;
Remote Shell Methods
The methods in this section allow you to run remote commands on the staging server and
interrogate the results. Since the staging manager handles the creation of SSH keys
internally, you do not need to worry about finding the right public/private keypair.
$result = $server->ssh(@command)
The ssh() method invokes a command on the remote server. You may provide the command line
as a single string, or broken up by argument:
$server->ssh('ls -lR /var/log');
$server->ssh('ls','-lR','/var/log');
The output of the command will appear on STDOUT and STDERR of the perl process. Input, if
needed, will be read from STDIN. If no command is provided, then an interactive ssh
session will be started on the remote server and the script will wait until you have
logged out.
If the remote command was successful, the method result will be true.
$output = $server->scmd(@command)
This is similar to ssh(), except that the standard output of the remote command will be
captured and returned as the function result, similar to the way backticks work in perl:
my $output = $server->scmd('date');
print "The localtime for the server is $output";
$fh = $server->scmd_write(@command)
This method executes @command on the remote server, and returns a filehandle that is
attached to the standard input of the command. Here is a slightly dangerous example that
appends a line to /etc/passwd:
my $fh = $server->scmd_write('sudo -s "cat >>/etc/passwd"');
print $fh "whoopsie:x:119:130::/nonexistent:/bin/false\n";
close $fh;
$fh = $server->scmd_read(@command)
This method executes @command on the remote server, and returns a filehandle that is
attached to the standard output of the command. Here is an example of reading syslog:
my $fh = $server->scmd_read('sudo cat /var/log/syslog');
while (<$fh>) {
next unless /kernel/;
print $_;
}
close $fh;
$server->shell()
This method works in an X Windowing environment by launching a new terminal window and
running an interactive ssh session on the server host. The terminal window is executed in
a fork()ed session, so that the rest of the script continues running. If X Windows is not
running, then the method behaves the same as calling ssh() with no arguments.
The terminal emulator to run is determined by calling the method get_xterm().
Volume Management Methods
The methods in this section allow you to create and manage volumes attached to the server.
These supplement the EC2 facilities for creating and attaching EBS volumes with the
ability to format the volumes with a variety of filesystems, and mount them at a desired
location.
$volume = $server->provision_volume(%args)
Provision and mount a new volume. If successful, the volume is returned as a
VM::EC2::Staging::Volume object.
Arguments (default):
-name Symbolic name for the desired volume (autogenerated)
-fstype Filesystem type for desired volume (ext4)
-size Size for the desired volume in GB (1)
-mtpt Mountpoint for this volume (/mnt/Staging/$name)
-mount Alias for -mtpt
-volume_id ID of existing volume to attach & mount (none)
-snapshot_id ID of existing snapshot to use to create this volume (none)
-reuse Reuse an existing managed volume of same name (false)
-label Disk label to assign during formatting ($name)
-uuid UUID to assign during formatting (none)
None of the arguments are required, and reasonable defaults will be chosen if they are
missing.
The -name argument specifies the symbolic name to be assigned to the newly-created staging
volume. The name allows the staging manager to retrieve this volume at a later date if it
is detached from the server and returned to the available pool. If no name is provided,
then an arbitrary one will be autogenerated.
The -fstype argument specifies the filesystem to be generated on the volume, ext4 by
default. The following filesystems are currently supported: ext2, ext3, ext4, xfs,
reiserfs, jfs, ntfs, nfs, vfat, msdos. In addition, you can specify a filesystem of "raw",
which means to provision and attach the volume to the server, but not to format it. This
can be used to set up LVM and RAID devices. Note that if the server does not currently
have the package needed to manage the desired filesystem, it will use "apt-get" to install
it.
The -mtpt and -mount arguments (they are equivalent) specify the mount point for the
volume on the server filesystem. The default is "/mnt/Staging/$name", where $name is the
symbolic name provided by -name or autogenerated. No checking is done on the sensibility
of the mount point, so try to avoid mounting disks over essential parts of the system.
-volume_id and -snapshot_id instruct the method to construct the staging volume from an
existing EBS volume or snapshot. -volume_id is an EBS volume ID. If provided, the volume
must be located in the server's availability zone and be in the "available" state.
-snapshot_id is an EBS snapshot ID in the server's region. In no case will
provision_volume() attempt to reformat the resulting volume, even if the -fstype argument
is provided. However, in the case of a volume created from a snapshot, you may specify a
-size argument larger than the snapshot and the filesystem will be dynamically resized to
fill the requested space. This currently only works with ext2, ext3 and ext4 volumes, and
cannot be used to make filesystems smaller.
If the -reuse argument is true, and a symbolic name is provided in -name, then the method
will look for an available staging volume of the same name and mount this at the specified
location. If no suitable staging volume is found, then the method will look for a snapshot
created earlier from a staging volume of the same name. If neither a suitable volume nor a
snapshot is available, then a new volume is provisioned. This is intended to support the
following use case of synchronizing a filesystem somewhere to an EBS snapshot:
my $server = $staging_manager->get_server('my_server');
my $volume = $server->provision_volume(-name=>'backup_1',
-reuse => 1,
-fstype => 'ext3',
-size => 10);
$volume->put('fred@gw.harvard.edu:my_music');
$volume->create_snapshot('music_backups');
$volume->delete;
The -label and -uuid arguments are used to set the volume label and UUID during formatting
of new filesystems. The default behavior is to create no label and to allow the server to
choose an arbitrary UUID.
$volume = $server->add_volume(%args)
This is the same as provision_volume().
@volumes = $server->volumes()
Return a list of all the staging volumes attached to this server. Unmanaged volumes, such
as the root volume, are not included in the list.
$server->unmount_volume($volume)
Unmount the volume $volume. The volume will remain attached to the server. This method
will die with a fatal error if the operation fails.
See VM::EC2::Staging::Volume->detach() for the recommended way to unmount and detach the
volume.
$server->detach_volume($volume)
Unmount and detach the volume from the server, waiting until EC2 reports that the
detachment completed. A fatal error will occur if the operation fails.
$server->mount_volume($volume [,$mountpt])
Mount the volume $volume using the mount information recorded inside the
VM::EC2::Staging::Volume object (returned by its mtpt() and mtdev() methods). If the
volume has not previously been mounted on this server, then it will be attached to the
server and a new mountpoint will be allocated automatically. You can change the mount
point by specifying it explicitly in the second argument.
Here is the recommended way to detach a staging volume from one server and attach it to
another:
$server1->detach_volume($volume);
$server2->mount_volume($volume);
This method will die in case of error.
$server->remount_volume($volume)
This is similar to mount_volume(), except that it will fail with a fatal error if the
volume was not previously mounted on this server. This is to be used when temporarily
unmounting and remounting a volume on the same server:
$server->unmount_volume($volume);
# do some work on the volume
$server->remount_volume($volume)
$server->delete_volume($volume)
Unmount, detach, and then delete the indicated volume entirely.
$snap = $server->create_snapshot($volume,$description)
Unmount the volume, snapshot it using the provided description, and then remount the
volume. If successful, returns the snapshot.
The snapshot is tagged with the identifying information needed to associate the snapshot
with the staging volume. This information then used when creating new volumes from the
snapshot with $server->provision_volume(-reuse=>1).
Data Copying Methods
The methods in this section are used to copy data from one staging server to another, and
to copy data from a local file system to a staging server.
$result = $server->rsync($src1,$src2,$src3...,$dest)
This method is a passthrough to VM::EC2::Staging::Manager->rsync(), and provides efficient
file-level synchronization (rsync) file-level copying between one or more source locations
and a destination location via an ssh tunnel. Copying among arbitrary combinations of
local and remote filesystems is supported, with the caveat that the remote filesystems
must be contained on volumes and servers managed by this module (see below for a
workaround).
You may provide two or more directory paths. The last path will be treated as the copy
destination, and the source paths will be treated as copy sources. All copying is
performed using the -avz options, which activates recursive directory copying in which
ownership, modification times and permissions are preserved, and compresses the data to
reduce network usage.
Source paths can be formatted in one of several ways:
/absolute/path
Copy the contents of the directory /absolute/path located on the
local machine to the destination. This will create a
subdirectory named "path" on the destination disk. Add a slash
to the end of the path (i.e. "/absolute/path/") in order to
avoid creating this subdirectory on the destination disk.
./relative/path
Relative paths work the way you expect, and depend on the current
working directory. The terminating slash rule applies.
$staging_server:/absolute/path
Pass a staging server object and absolute path to copy the contents
of this path to the destination disk. Because of string interpolation
you can include server objects in quotes: "$my_server:/opt"
$staging_server:relative/path
This form will copy data from paths relative to the remote user's home
directory on the staging server. Typically not very useful, but supported.
$staging_volume
Pass a VM::EC2::Staging::Volume to copy the contents of the
volume to the destination disk starting at the root of the
volume. Note that you do *not* need to have any knowledge of the
mount point for this volume in order to copy its contents.
$staging_volume:/absolute/path
Copy a subdirectory of a staging volume to the destination disk.
The root of the volume is its top level, regardless of where it
is mounted on the staging server. Because of string
interpolation magic, you can enclose staging volume object names
in quotes in order to construct the path, as in
"$picture_volume:/family/vacations/". As in local paths, a
terminating slash indicates that the contents of the last
directory in the path are to be copied without creating the
enclosing directory on the desetination. Note that you do *not*
need to have any knowledge of the mount point for this volume in
order to copy its contents.
$staging_volume:absolute/path
$staging_volume/absolute/path
These are alternatives to the previous syntax, and all have the
same effect as $staging_volume:relative/path. There is no
The same syntax is supported for destination paths, except that it makes no difference
whether a path has a trailing slash or not.
Note that neither the source nor destination paths need to reside on this server.
See VM::EC2::Staging::Manager->rsync() for examples and more details.
$server->dd($source_vol=>$dest_vol)
This method is a passthrough to VM::EC2::Staging::Manager->dd(), and performs block-level
copying of the contents of $source_vol to $dest_vol by using dd over an SSH tunnel, where
both source and destination volumes are VM::EC2::Staging::Volume objects. The volumes must
be attached to a server but not mounted. Everything in the volume, including its partition
table, is copied, allowing you to make an exact image of a disk.
The volumes do not actually need to reside on this server, but can be attached to any
staging server in the zone.
$server->put($source1,$source2,$source3,...,$dest)
Use rsync to copy the indicated source directories into the destination path indicated by
$dest. The destination is either a path on the server machine, or a staging volume object
mounted on the server (string interpolation is accepted). The sources can be local paths
on the machine the perl script is running on, or any of the formats described for rsync().
Examples:
$server1->put("$ENV{HOME}/my_pictures" => '/var/media');
$server1->put("$ENV{HOME}/my_pictures","$ENV{HOME}/my_audio" => '/var/media');
$server1->put("$ENV{HOME}/my_pictures" => "$backup_volume/home_media");
$server1->put("fred@gw.harvard.edu:media/" => "$backup_volume/home_media");
$server->get($source1,$source2,$source3,...,$dest)
Use rsync to copy the indicated source directories into the destination path indicated by
$dest. The source directories are either paths on the server, or staging volume(s) mounted
on the server (string interpolation to indicate subdirectories on the staging volume also
works). The destination can be any of the path formats described for rsync(), including
unmanaged hosts that accept ssh login.
Examples:
$server1->get('/var/media' =>"$ENV{HOME}/my_pictures");
$server1->get('/var/media','/usr/bin' => "$ENV{HOME}/test");
$server1->get("$backup_volume/home_media" => "$ENV{HOME}/my_pictures");
$server1->get("$backup_volume/home_media" => "fred@gw.harvard.edu:media/");
Internal Methods
This section documents internal methods. They are not intended for use by end-user scripts
but may be useful to know about during subclassing. There are also additional undocumented
methods that begin with a "_" character which you can explore in the source code.
$description = $server->volume_description($vol)
This method is called to get the value of the Name tag assigned to new staging volume
objects. The current value is "Staging volume for $name created by
VM::EC2::Staging::Server."
You will see these names associated with EBS volumes in the AWS console.
($ebs_device,$local_device) = $server->unused_block_device([$major_start])
This method returns an unused block device path. It is invoked when provisioning and
mounting new volumes. The behavior is to take the following search path:
/dev/sdf1
/dev/sdf2
...
/dev/sdf15
/dev/sdfg1
...
/dev/sdp15
You can modify the search path slightly by providing a single character major start. For
example, to leave all the sdf's free and to start the search at /dev/sdg:
($ebs_device,$local_device) = $server->unused_block_device('g');
The result is a two element list consisting of the unused device name from the perspective
of EC2 and the server respectively. The issue here is that on some recent Linux kernels,
the EC2 device /dev/sdf1 is known to the server as /dev/xvdf1. This module understands
that complication and uses the EC2 block device name when managing EBS volumes, and the
kernel block device name when communicating with the server.
$flag = $server->has_key($keyname)
Returns true if the server has a copy of the private key corresponding to $keyname. This
is used by the rsync() method to enable server to server data transfers.
$flag = $server->accepts_key($keyname)
Returns true if the server has a copy of the public key part of $keyname in its
.ssh/authorized_keys file. This is used by the rsync() method to enable server to server
data transfers.
$up = $server->is_up([$new_value])
Get/set the internal is_up() flag, which indicates whether the server is up and running.
This is used to cache the results of the ping() method.
$path = $server->default_mtpt($volume)
Given a staging volume, return its default mount point on the server
('/mnt/Staging/'.$volume->name). Can also pass a string corresponding to the volume's
name.
$server->info(@message)
Log a message to standard output, respecting the staging manager's verbosity() setting.
Subclassing
For reasons having to do with the order in which objects are created,
VM::EC2::Staging::Server is a wrapper around VM::EC2::Instance rather than a subclass of
it. To access the VM::EC2::Instance object, you call the server object's instance()
method. In practice this means that to invoke the underlying instance's method for, say,
start() you will need to do this:
$server->instance->start();
rather than this:
$server->SUPER::start();
You may subclass VM::EC2::Staging::Server in the usual way.
SEE ALSO
VM::EC2 VM::EC2::Instance VM::EC2::Volume VM::EC2::Snapshot
AUTHOR
Lincoln Stein <lincoln.stein@gmail.com>.
Copyright (c) 2011 Ontario Institute for Cancer Research
This package and its accompanying libraries is free software; you can redistribute it
and/or modify it under the terms of the GPL (either version 1, or at your option, any
later version) or the Artistic License 2.0. Refer to LICENSE for the full license text.
In addition, please see DISCLAIMER.txt for disclaimers of warranty.