Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
VM::EC2::Staging::ManaUser3Contributed Perl DocumeVM::EC2::Staging::Manager(3)

NAME
       VM::EC2::Staging::Manager - Automate VMs	and volumes for	moving data in
       and out of cloud.

SYNOPSIS
	use VM::EC2::Staging::Manager;

	my $ec2	    = VM::EC2->new(-region=>'us-east-1');
	my $staging = $ec2->staging_manager(-on_exit	 => 'stop', # default, stop servers when process exists
					    -verbose	 => 1,	    # default, verbose progress	messages
					    -scan	 => 1,	    # default, scan region for existing	staging	servers	and volumes
					    -image_name	 => 'ubuntu-precise-12.04',  # default server image
					    -user_name	 => 'ubuntu',		     # default server login name
					    );

	# Assuming an EBS image	named ami-12345	is located in the US, copy it into
	# the South American region, returning the AMI ID in South America
	my $new_image =	$staging->copy_image('ami-12345','sa-east-1');

	# provision a new server, using	defaults. Name will be assigned	automatically
	my $server = $staging->provision_server(-availability_zone => 'us-east-1a');

	# retrieve a new server	named "my_server", if one exists. If not, it creates one
	# using	the specified options
	my $server = $staging->get_server(-name		     =>	'my_server',
					  -availability_zone =>	'us-east-1a',
					  -instance_type     =>	't1.micro');

	# open up an ssh session in an xterm
	$server->shell;

	# run a	command	over ssh on the	server.	See VM::EC2::Staging::Server
	$server->ssh('whoami');

	# run a	command	over ssh on the	server,	returning the result as	an array of lines or a
	# scalar string, similar to backticks (``)
	my @password_lines = $server->scmd('cat	/etc/passwd');

	# run a	command	on the server and read from it using a filehandle
	my $fh	= $server->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	= $server->scmd_write('sudo -s "cat >>/etc/fstab"');
	print $fh "/dev/sdf3 /mnt/demo ext3 0 2\n";
	close $fh;

	# Provision a new volume named "Pictures". Will	automatically be mounted to a staging server in
	# the specified	zone. Server will be created if	needed.
	my $volume = $staging->provision_volume(-name		   => 'Pictures',
						-fstype		   => 'ext4',
						-availability_zone => 'us-east-1a',
						-size		   => 2) or die	$staging->error_str;

	# gets an existing volume named	"Pictures" if it exists. Otherwise provisions a	new volume;
	my $volume = $staging->get_volume(-name		     =>	'Pictures',
					  -fstype	     =>	'ext4',
					  -availability_zone =>	'us-east-1a',
					  -size		     =>	2) or die $staging->error_str;

	# copy contents	of local directory /opt/test to	remote volume $volume using rsync
	# See VM::EC2::Staging::Volume
	$volume->put('/opt/test/');

	# same thing, but first	creating a subdirectory	on the remote volume
	$volume->put('/opt/test/' => './mirrors/');

	# copy contents	of remote volume $volume to local directory /tmp/test using rsync
	$volume->get('/tmp/test');

	# same thing, but from a subdirectory of the remote volume
	$volume->get('./mirrors/' => '/tmp/test');

	# server to server transfer (works both	within and between availability	regions)
	my $south_america = VM::EC2->new(-region=>'sa-east-1')->staging_manager;    # create a staging manager in Sao Paolo
	my $volume2 = $south_america->provision_volume(-name		  => 'Videos',
						       -availability_zone => 'sa-east-1a',
						       -size		  => 2);
	$staging->rsync("$volume/mirrors" => "$volume2/us-east");

	$staging->stop_all_servers();
	$staging->start_all_servers();
	$staging->terminate_all_servers();
	$staging->force_terminate_all_servers();

DESCRIPTION
       VM::EC2::Staging::Manager manages a set of EC2 volumes and servers in a
       single AWS region. It was primarily designed to simplify	the process of
       provisioning and	populating volumes, but	it also	provides a handy set
       of ssh commands that allow you to run remote commands programmatically.

       The manager also	allows you to copy EBS-backed AMIs and their attached
       volumes from one	region to another, something that is otherwise
       difficult to do.

       The main	classes	are:

	VM::EC2::Staging::Manager -- A set of volume and server	resources in
				     a single AWS region.

	VM::EC2::Staging::Server -- A staging server running somewhere in the
				    region. It is a VM::EC2::Instance
				    extended to	provide	remote command and
				    copy facilities.

	VM::EC2::Staging::Volume -- A staging disk volume running somewhere in the
				    region. It is a VM::EC2::Volume
				    extended to	provide	remote copy
				    facilities.

       Staging servers can provision volumes, format them, mount them, copy
       data between local and remote (virtual) machines, and execute secure
       shell commands. Staging volumes can mount themselves on servers,	run a
       variety of filesystem-oriented commands,	and invoke commands on the
       servers to copy data around locally and remotely.

       See VM::EC2::Staging::Server and	VM::EC2::Staging::Volume for the full
       details.

Constructors
       The following methods allow you to create new VM::EC2::Staging::Manager
       instances. Be aware that	only one manager is allowed per	EC2 region;
       attempting to create additional managers	in the same region will	return
       the same	one each time.

   $manager = $ec2->staging_manager(@args)
       This is a simplified way	to create a staging manager. First create the
       EC2 object in the desired region, and then call its staging_manager()
       method:

	$manager = VM::EC2->new(-region=>'us-west-2')->staging_manager()

       The staging_manager() method is only known to VM::EC2 objects if	you
       first "use" VM::EC2::Staging::Manager.

       Required	Arguments
	   None.

       Optional	Arguments
	   The optional	arguments change the way that the manager creates new
	   servers and volumes.

	    -on_exit	   What	to do with running servers when	the manager goes
			   out of scope	or the script exits. One of 'run',
			   'stop' (default), or	'terminate'. "run" keeps all
			   created instances running, so beware!

	    -architecture  Architecture	for newly-created server
			   instances (default "i386"). Can be overridden in calls to get_server()
			   and provision_server().

	    -instance_type Type	of newly-created servers (default "m1.small"). Can be overridden
			   in calls to get_server() and	provision_server().

	    -root_type	   Root	type for newly-created servers (default	depends
			   on the -on_exit behavior; "ebs" for exit behavior of
			   "stop" and "instance-store" for exit	behavior of "run"
			   or "terminate".

	    -image_name	   Name	or ami ID of the AMI to	use for	creating the
			   instances of	new servers. Defaults to 'ubuntu-precise-12.04'.
			   If the image	name begins with "ami-", then it is
			   treated as an AMI ID. Otherwise it is treated as
			   a name pattern and will be used to search the AMI
			   name	field using the	wildcard search	"*$name*".
			   Names work better than AMI ids here,	because	the
			   latter change from one region to another. If	multiple
			   matching image candidates are found,	then an	alpha
			   sort	on the name is used to find the	image with the
			   highest alpha sort value, which happens to work with
			   Ubuntu images to find the latest release.

	    -availability_zone Availability zone for newly-created
			   servers. Default is undef, in which case a random
			   zone	is selected.

	    -username	   Username to use for ssh connections.	Defaults to
			   "ubuntu". Note that this user must be able to use
			   sudo	on the instance	without	providing a password,
			   or functionality of this module will	be limited.

	    -verbose	   Integer level of verbosity. Level 1 prints warning
			   messages. Level 2 (the default) adds	informational
			   messages as well. Level 3 adds verbose debugging
			   messages. Level 0 suppresses	all messages.

	    -quiet	   (deprecated)	If true, turns off all verbose messages.

	    -scan	   Boolean, default true. If true, scans region	for
			   volumes and servers created by earlier manager
			   instances.

	    -reuse_key	   Boolean, default true. If true, creates a single
			   ssh keypair for each	region and reuses it. Note that
			   the private key is kept on the local	computer in the
			   directory ~/.vm-ec2-staging,	and so additional
			   keypairs may	be created if you use this module on
			   multiple local machines. If this option is false,
			   then	a new keypair will be created for every	server
			   you partition.

	    -reuse_volumes Boolean, default true. If this flag is true,	then
			   calls to provision_volume() will return existing
			   volumes if they share the same name as the requested
			   volume. If no suitable existing volume exists, then
			   the most recent snapshot of this volume is used to
			   create it in	the specified availability zone. Only
			   if no volume	or snapshot exist will a new volume be
			   created from	scratch.

	    -dotdir	   Path	to the directory that contains keyfiles	and other
			   stable configuration	information for	this module.
			   Defaults to ~/.vm_ec2_staging. You may wish to change
			   this	to, say, a private dropbox directory or	an NFS-mount
			   in order to share keyfiles among machines. Be aware of
			   the security	implications of	sharing	private	key files.

	    -server_class  By default, staging server objects created by the manager
			   are of class	type VM::EC2::Staging::Server. If you create
			   a custom server subclass, you need to let the manager know
			   about it by passing the class name to this argument.

	    -volume_class  By default, staging volume objects created by the manager
			   are of class	type VM::EC2::Staging::Volume. If you create
			   a custom volume subclass, you need to let the manager know
			   about it by passing the class name to this argument.

   $manager = VM::EC2::Staging::Manager(-ec2 =>	$ec2,@args)
       This is a more traditional constructur for the staging manager.

       Required	Arguments
	     -ec2     A	VM::EC2	object.

       Optional	Arguments
	   All of the arguments	listed in the description of
	   VM::EC2->staging_manager().

Interzone Copying of AMIs and Snapshots
       This library provides convenience methods for copying whole AMIs	as
       well as individual snapshots from one zone to another. It does this by
       gathering information about the AMI/snapshot in the source zone,
       creating	staging	servers	in the source and target zones,	and then
       copying the volume data from the	source to the target. If an
       AMI/snapshot does not use a recognized filesystem (e.g. it is part of
       an LVM or RAID disk set), then block level copying of the entire	device
       is used.	Otherwise, rsync() is used to minimize data transfer fees.

       Note that interzone copying of instance-backed AMIs is not supported.
       Only EBS-backed images can be copied in this way.

       See also	the command-line script	migrate-ebs-image.pl that comes	with
       this package.

   $new_image_id =
       $manager->copy_image($source_image,$destination_zone,@register_options)
       This method copies the AMI indicated by $source_image from the zone
       that $manager belongs to, into the indicated $destination_zone, and
       returns the AMI ID of the new image in the destination zone.

       $source_image may be an AMI ID, or a VM::EC2::Image object.

       $destination_zone may be	a simple region	name, such as "us-west-2", or
       a VM::EC2::Region object	(as returned by	VM::EC2->describe_regions), or
       a VM::EC2::Staging::Manager object that is associated with the desired
       region. The latter form gives you control over the nature of the
       staging instances created in the	destination zone. For example, if you
       wish to use 'm1.large' high-I/O instances in both the source and
       destination reasons, you	would proceed like this:

	my $source	= VM::EC2->new(-region=>'us-east-1'
				      )->staging_manager(-instance_type=>'m1.large',
							 -on_exit      =>'terminate');
	my $destination	= VM::EC2->new(-region=>'us-west-2'
				      )->staging_manager(-instance_type=>'m1.large',
							 -on_exit      =>'terminate');
	my $new_image	= $source->copy_image('ami-123456' => $destination);

       If present, the named argument list @register_options will be passed to
       register_image()	and used to override options in	the destination	image.
       This can	be used	to set ephemeral device	mappings, which	cannot
       currently be detected and transferred automatically by copy_image():

	$new_image =$source->copy_image('ami-123456'   => 'us-west-2',
					-description   => 'My AMI western style',
					-block_devices => '/dev/sde=ephemeral0');

   $dest_kernel	= $manager->match_kernel($src_kernel,$dest_zone)
       Find a kernel in	$dest_zone that	matches	the $src_kernel	in the current
       zone. $dest_zone	can be a VM::EC2::Staging manager object, a region
       name, or	a VM::EC2::Region object.

   $new_snapshot_id =
       $manager->copy_snapshot($source_snapshot,$destination_zone)
       This method copies the EBS snapshot indicated by	$source_snapshot from
       the zone	that $manager belongs to, into the indicated
       $destination_zone, and returns the ID of	the new	snapshot in the
       destination zone.

       $source_snapshot	may be an string ID, or	a VM::EC2::Snapshot object.

       $destination_zone may be	a simple region	name, such as "us-west-2", or
       a VM::EC2::Region object	(as returned by	VM::EC2->describe_regions), or
       a VM::EC2::Staging::Manager object that is associated with the desired
       region.

       Note that this call uses	the Amazon CopySnapshot	API call that was
       introduced in 2012-12-01	and no longer involves the creation of staging
       servers in the source and destination regions.

Instance Methods for Managing Staging Servers
       These methods allow you to create and interrogate staging servers. They
       each return one or more VM::EC2::Staging::Server	objects. See
       VM::EC2::Staging::Server	for more information about what	you can	do
       with these servers once they are	running.

   $server = $manager->provision_server(%options)
       Create a	new VM::EC2::Staging::Server object according to the passed
       options,	which override the default options provided by the Manager
       object.

	-name	       Name for	this server, which can be used to retrieve
		       it later	with a call to get_server().

	-architecture  Architecture for	the newly-created server
		       instances (e.g. "i386").	If not specified, then defaults
		       to the default_architecture() value. If explicitly
		       specified as undef, then	the architecture of the	matching
		       image will be used.

	-instance_type Type of the newly-created server	(e.g. "m1.small").

	-root_type     Root type for the server	("ebs" or "instance-store").

	-image_name    Name or ami ID of the AMI to use	for creating the
		       instance	for the	server.	If the image name begins with
		       "ami-", then it is treated as an	AMI ID.	Otherwise it
		       is treated as a name pattern and	will be	used to
		       search the AMI name field using the wildcard search
		       "*$name*". Names	work better than AMI ids here,
		       because the latter change from one region to
		       another.	If multiple matching image candidates are
		       found, then an alpha sort on the	name is	used to	find
		       the image with the highest alpha	sort value, which
		       happens to work with Ubuntu images to find the latest
		       release.

	-availability_zone Availability	zone for the server, or	undef to
		       choose an availability zone randomly.

	-username      Username	to use for ssh connections. Defaults to
		       "ubuntu". Note that this	user must be able to use
		       sudo on the instance without providing a	password,
		       or functionality	of this	server will be limited.

       In addition, you	may use	any of the options recognized by
       VM::EC2->run_instances()	(e.g. -block_devices).

   $server = $manager->get_server(-name=>$name,%other_options)
   $server = $manager->get_server($name)
       Return an existing VM::EC2::Staging::Server object having the indicated
       symbolic	name, or create	a new server if	one with this name does	not
       already exist. The server's instance characteristics will be configured
       according to the	options	passed to the manager at create	time (e.g.
       -availability_zone, -instance_type). These options can be overridden by
       %other_args. See	provision_volume() for details.

   $server =
       $manager->get_server_in_zone(-zone=>$availability_zone,%other_options)
   $server = $manager->get_server_in_zone($availability_zone)
       Return an existing VM::EC2::Staging::Server running in the indicated
       symbolic	name, or create	a new server if	one with this name does	not
       already exist. The server's instance characteristics will be configured
       according to the	options	passed to the manager at create	time (e.g.
       -availability_zone, -instance_type). These options can be overridden by
       %other_args. See	provision_server() for details.

   $server = $manager->find_server_by_instance($instance_id)
       Given an	EC2 instanceId,	return the corresponding
       VM::EC2::Staging::Server, if any.

   @servers $manager->servers
       Return all registered VM::EC2::Staging::Servers in the zone managed by
       the manager.

   $manager->start_all_servers
       Start all VM::EC2::Staging::Servers that	are currently in the "stop"
       state.

   $manager->stop_all_servers
       Stop all	VM::EC2::Staging::Servers that are currently in	the "running"
       state.

   $manager->terminate_all_servers
       Terminate all VM::EC2::Staging::Servers and unregister them.

   $manager->force_terminate_all_servers
       Force termination of all	VM::EC2::Staging::Servers, even	if the
       internal	registration system indicates that some	may be in use by other
       Manager instances.

   $manager->wait_for_servers(@servers)
       Wait until all the servers on the list @servers are up and able to
       accept ssh commands. You	may wish to wrap this in an eval{} and timeout
       in order	to avoid waiting indefinitely.

Instance Methods for Managing Staging Volumes
       These methods allow you to create and interrogate staging volumes. They
       each return one or more VM::EC2::Staging::Volume	objects. See
       VM::EC2::Staging::Volume	for more information about what	you can	do
       with these staging volume objects.

   $volume = $manager->provision_volume(%options)
       Create and register a new VM::EC2::Staging::Volume and mount it on a
       staging server in the appropriate availability zone. A new staging
       server will be created for this purpose if one does not already exist.

       If you provide a	symbolic name for the volume and the manager has
       previously snapshotted a	volume by the same name, then the snapshot
       will be used to create the volume (this behavior	can be suppressed by
       passing -reuse=>0). This	allows for the following pattern for
       efficiently updating a snapshotted volume:

	my $vol	= $manager->provision_volume(-name=>'MyPictures',
					     -size=>10);
	$vol->put('/usr/local/my_pictures/');	# will do an rsync from	local directory
	$vol->create_snapshot;	# write	out to a snapshot
	$vol->delete;

       You may also explicitly specify a volumeId or snapshotId. The former
       allows you to place an existing volume under management of
       VM::EC2::Staging::Manager and returns a corresponding staging volume
       object. The latter creates the staging volume from the indicated
       snapshot, irregardless of whether the snapshot was created by the
       staging manager at an earlier time.

       Newly-created staging volumes are automatically formatted as ext4
       filesystems and mounted on the staging server under /mnt/Staging/$name,
       where $name is the staging volume's symbolic name. The filesystem type
       and the mountpoint can be modified with the -fstype and -mount
       arguments, respectively.	In addition, you may specify an	-fstype	of
       "raw", in which case the	volume will be attached	to a staging server
       (creating the server first if necessary)	but not	formatted or mounted.
       This is useful when creating multi-volume RAID or LVM setups.

       Options:

	-name	    Name of the	staging	volume.	A fatal	error issues if	a staging
		    volume by this name	already	exists (use get_volume() to
		    avoid this).  If no	name is	provided, then a random
		    unique one is chosen for you.

	-availability_zone
		    Availability zone in which to create this
		    volume. If none is specified, then a zone is chosen	that
		    reuses an existing staging server, if any.

	-size	    Size of the	desired	volume,	in GB.

	-fstype	    Filesystem type for	the volume, ext4 by default. Supported
		    types are ext2, ext3, ext4,	xfs, reiserfs, jfs, hfs,
		    ntfs, vfat,	msdos, and raw.

	-mount	    Mount point	for this volume	on the staging server (e.g. /opt/bin).
		    Use	with care, as there are	no checks to prevent you from mounting
		    two	staging	volumes	on top of each other or	mounting over essential
		    operating system paths.

	-label	    Volume label. Only applies to filesystems that support labels
		    (all except	hfs, vfat, msdos and raw).

	-volume_id  Create the staging volume from an existing EBS volume with
		    the	specified ID. Most other options are ignored in	this
		    case.

	-snapshot_id
		    Create the staging volume from an existing EBS
		    snapshot. If a size	is specified that is larger than the
		    snapshot, then the volume and its filesystem will be
		    automatically extended (this only works for	ext volumes
		    at the moment). Shrinking of volumes is not	currently
		    supported.

	-reuse	    If true, then the most recent snapshot created from	a staging
		    volume of the same name is used to create the
		    volume. This is the	default. Pass 0	to disable this
		    behavior.

       The -reuse argument is intended to support the following	use case in
       which you wish to rsync a directory on a	host system somewhere to an
       EBS snapshot, without maintaining a live	server and volume on EC2:

	my $volume = $manager->provision_volume(-name=>'backup_1',
						-reuse	=> 1,
						-fstype	=> 'ext3',
						-size	=> 10);
	$volume->put('fred@gw.harvard.edu:my_music');
	$volume->create_snapshot('Music	Backup '.localtime);
	$volume->delete;

       The next	time this script is run, the "backup_1"	volume will be
       recreated from the most recent snapshot,	minimizing copying. A new
       snapshot	is created, and	the staging volume is deleted.

   $volume = $manager->get_volume(-name=>$name,%other_options)
   $volume = $manager->get_volume($name)
       Return an existing VM::EC2::Staging::Volume object with the indicated
       symbolic	name, or else create a new volume if one with this name	does
       not already exist. The volume's characteristics will be configured
       according to the	options	in %other_args.	See provision_volume() for
       details.	If called with no arguments, this method returns Volume	object
       with default characteristics and	a randomly-assigned name.

   $result = $manager->rsync($src1,$src2,$src3...,$dest)
       This method provides remote 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. Verbosity	is set so that the names of copied files are
       printed to STDERR. If you do not	wish this, then	use call the manager's
       quiet() method with a true value.

       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_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
	$staging_volume:absolute/path
	$staging_volume/absolute/path
	     All these syntaxes	accomplish the same thing, which is to
	     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_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.

       The same	syntax is supported for	destination paths, except that it
       makes no	difference whether a path has a	trailing slash or not.

       As with the rsync command, if you proceed a path	with a single colon
       (:/my/path), it is a short hand to use the previous server/volume/host
       in the source list.

       When specifying multiple	source directories, all	source directories
       must reside on the same local or	remote machine.	This is	legal:

	$manager->rsync("$picture_volume:/family/vacations",
			"$picture_volume:/family/picnics"
			=> "$backup_volume:/recent_backups");

       This is not:

	$manager->rsync("$picture_volume:/family/vacations",
			"$audio_volume:/beethoven"
			=> "$backup_volume:/recent_backups");

       When specifying multiple	sources, you may give the volume or server
       once for	the first source and then start	additional source paths	with a
       ":" to indicate the same	volume or server is to be used:

	$manager->rsync("$picture_volume:/family/vacations",
			":/family/picnics"
			=> "$backup_volume:/recent_backups");

       When copying to/from the	local machine, the rsync process will run as
       the user	that the script	was launched by. However, on remote servers
       managed by the staging manager, the rsync process will run as
       superuser.

       The rsync() method will also accept regular remote DNS names and	IP
       addresses, optionally preceded by a username:

	$manager->rsync("$picture_volume:/family/vacations" => 'fred@gw.harvard.edu:/tmp')

       When called in this way,	the method does	what it	can to avoid prompting
       for a password or passphrase on the non-managed host (gw.harvard.edu in
       the above example). This	includes turning off strict host checking and
       forwarding the user agent information from the local machine.

   $result = $manager->rsync(\@options,$src1,$src2,$src3...,$dest)
       This is a variant of the	rsync command in which extra options can be
       passed to rsync by providing an array reference as the first argument.
       For example:

	   $manager->rsync(['--exclude'	=> '*~'],
			   '/usr/local/backups',
			   "$my_server:/usr/local");

   $manager->dd($source_vol=>$dest_vol)
       This method 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.

   $volume = $manager->find_volume_by_volid($volume_id)
       Given an	EC2 volumeId, return the corresponding
       VM::EC2::Staging::Volume, if any.

   $volume = $manager->find_volume_by_name($name)
       Given a staging name (assigned at volume	creation time),	return the
       corresponding VM::EC2::Staging::Volume, if any.

   @volumes = $manager->volumes
       Return all VM::EC2::Staging::Volumes managed in this zone.

Instance Methods for Accessing Configuration Options
       This section documents accessor methods that allow you to examine or
       change configuration options that were set at create time. Called with
       an argument, the	accessor changes the option and	returns	the option's
       previous	value. Called without an argument, the accessor	returns	the
       option's	current	value.

   $on_exit = $manager->on_exit([$new_behavior])
       Get or set the "on_exit"	option,	which specifies	what to	do with
       existing	staging	servers	when the staging manager is destroyed. Valid
       values are "terminate", "stop" and "run".

   $reuse_key =	$manager->reuse_key([$boolean])
       Get or set the "reuse_key" option, which	if true	uses the same
       internally-generated ssh	keypair	for all	running	instances. If false,
       then a new keypair will be created for each staging server. The keypair
       will be destroyed automatically when the	staging	server terminates (but
       only if the staging manager initiates the termination itself).

   $username = $manager->username([$new_username])
       Get or set the username used to log into	staging	servers.

   $architecture = $manager->architecture([$new_architecture])
       Get or set the architecture (i386, x86_64) to use for launching new
       staging servers.

   $root_type =	$manager->root_type([$new_type])
       Get or set the instance root type for new staging servers ("instance-
       store", "ebs").

   $instance_type = $manager->instance_type([$new_type])
       Get or set the instance type to use for new staging servers (e.g.
       "t1.micro"). I recommend	that you use "m1.small"	(the default) or
       larger instance types because of	the extremely slow I/O of the micro
       instance. In addition, micro instances running Ubuntu have a known bug
       that prevents them from unmounting and remounting EBS volumes
       repeatedly on the same block device. This can lead to hangs when	the
       staging manager tries to	create volumes.

   $reuse_volumes = $manager->reuse_volumes([$new_boolean])
       This gets or sets the "reuse_volumes" option, which if true causes the
       provision_volumes() call	to create staging volumes from existing	EBS
       volumes and snapshots that share	the same staging manager symbolic
       name. See the discussion	under VM::EC2->staging_manager(), and
       VM::EC2::Staging::Manager->provision_volume().

   $name = $manager->image_name([$new_name])
       This gets or sets the "image_name" option, which	is the AMI ID or AMI
       name to use when	creating new staging servers. Names beginning with
       "ami-" are treated as AMI IDs, and everything else is treated as	a
       pattern match on	the AMI	name.

   $zone = $manager->availability_zone([$new_zone])
       Get or set the default availability zone	to use when creating new
       servers and volumes. An undef value allows the staging manager to
       choose the zone in a way	that minimizes resources.

   $class_name = $manager->volume_class([$new_class])
       Get or set the name of the perl package that implements staging
       volumes,	VM::EC2::Staging::Volume by default. Staging volumes created
       by the manager will have	this class type.

   $class_name = $manager->server_class([$new_class])
       Get or set the name of the perl package that implements staging
       servers,	VM::EC2::Staging::Server by default. Staging servers created
       by the manager will have	this class type.

   $boolean = $manager->scan([$boolean])
       Get or set the "scan" flag, which if true will cause the	zone to	be
       scanned quickly for existing managed servers and	volumes	when the
       manager is first	created.

   $path = $manager->dot_directory([$new_directory])
       Get or set the dot directory which holds	private	key files.

Internal Methods
       This section documents internal methods that are	not normally called by
       end-user	scripts	but may	be useful in subclasses. In addition, there
       are a number of undocumented internal methods that begin	with the "_"
       character. Explore the source code to learn about these.

   $ok	 = $manager->environment_ok
       This performs a check on	the environment	in which the module is
       running.	For this module	to work	properly, the ssh, rsync and dd
       programs	must be	found in the PATH. If all three	programs are found,
       then this method	returns	true.

       This method can be called as an instance	method or class	method.

   $name = $manager->default_verbosity
       Returns the default verbosity level (2: warning+informational
       messages). This is overridden using -verbose at create time.

   $name = $manager->default_exit_behavior
       Return the default exit behavior	("stop") when the manager terminates.
       Intended	to be overridden in subclasses.

   $name = $manager->default_image_name
       Return the default image	name ('ubuntu-precise-12.04') for use in
       creating	new instances. Intended	to be overridden in subclasses.

   $name = $manager->default_user_name
       Return the default user name ('ubuntu') for use in creating new
       instances. Intended to be overridden in subclasses.

   $name = $manager->default_architecture
       Return the default instance architecture	('i386') for use in creating
       new instances. Intended to be overridden	in subclasses.

   $name = $manager->default_root_type
       Return the default instance root	type ('instance-store')	for use	in
       creating	new instances. Intended	to be overridden in subclasses.	Note
       that this value is ignored if the exit behavior is "stop", in which
       case an ebs-backed instance will	be used. Also, the m1.micro instance
       type does not come in an	instance-store form, so	ebs will be used in
       this case as well.

   $name = $manager->default_instance_type
       Return the default instance type	('m1.small') for use in	creating new
       instances. Intended to be overridden in subclasses. We default to
       m1.small	rather than a micro instance because the I/O in	m1.small is
       far faster than in t1.micro.

   $name = $manager->default_reuse_keys
       Return the default value	of the -reuse_keys argument ('true'). This
       value allows the	manager	to create an ssh keypair once, and use the
       same one	for all	servers	it creates over	time. If false,	then a new
       keypair is created for each server and then discarded when the server
       terminates.

   $name = $manager->default_reuse_volumes
       Return the default value	of the -reuse_volumes argument ('true'). This
       value instructs the manager to use the symbolic name of the volume to
       return an existing volume whenever a request is made to provision a new
       one of the same name.

   $path = $manager->default_dot_directory_path
       Return the default value	of the -dotdir argument
       ("$ENV{HOME}/.vm-ec2-staging"). This value instructs the	manager	to use
       the symbolic name of the	volume to return an existing volume whenever a
       request is made to provision a new one of the same name.

   $class_name = $manager->default_volume_class
       Return the class	name for staging volumes created by the	manager,
       VM::EC2::Staging::Volume	by default. If you wish	a subclass of
       VM::EC2::Staging::Manager to create a different type of volume,
       override	this method.

   $class_name = $manager->default_server_class
       Return the class	name for staging servers created by the	manager,
       VM::EC2::Staging::Server	by default. If you wish	a subclass of
       VM::EC2::Staging::Manager to create a different type of volume,
       override	this method.

   $server = $manager->register_server($server)
       Register	a VM::EC2::Staging::Server object. Usually called internally.

   $manager->unregister_server($server)
       Forget about the	existence of VM::EC2::Staging::Server. Usually called
       internally.

   $manager->register_volume($volume)
       Register	a VM::EC2::Staging::Volume object. Usually called internally.

   $manager->unregister_volume($volume)
       Forget about a VM::EC2::Staging::Volume object. Usually called
       internally.

   $pid	= $manager->pid([$new_pid])
       Get or set the process ID of the	script that is running the manager.
       This is used internally to detect the case in which the script has
       forked, in which	case we	do not want to invoke the manager class's
       destructor in the child process (because	it may stop or terminate
       servers still in	use by the parent process).

   $path = $manager->dotdir([$new_dotdir])
       Low-level version of dot_directory(), differing only in the fact	that
       dot_directory will automatically	create the path, including
       subdirectories.

   $manager->scan_region
       Synchronize internal list of managed servers and	volumes	with the EC2
       region. Called automatically during new() and needed only if servers &
       volumes are changed from	outside	the module while it is running.

   $group = $manager->security_group
       Returns or creates a security group with	the permissions	needed used to
       manage staging servers. Usually called internally.

   $keypair = $manager->keypair
       Returns or creates the ssh keypair used internally by the manager to to
       access staging servers. Usually called internally.

   $name = $manager->new_volume_name
       Returns a new random name for volumes provisioned without a -name
       argument. Currently names are in	of the format "volume-12345678", where
       the numeric part	are 8 random hex digits. Although no attempt is	made
       to prevent naming collisions, the large number of possible names	makes
       this unlikely.

   $name = $manager->new_server_name
       Returns a new random name for server provisioned	without	a -name
       argument. Currently names are in	of the format "server-12345678", where
       the numeric part	are 8 random hex digits.  Although no attempt is made
       to prevent naming collisions, the large number of possible names	makes
       this unlikely.

   $description	= $manager->volume_description($volume)
       This method is called to	assign a description to	newly-created volumes.
       The current format is "Staging volume for Foo created by
       VM::EC2::Staging::Manager", where Foo is	the volume's symbolic name.

   $manager->debug("Debugging message\n")
   $manager->info("Informational message\n")
   $manager->warn("Warning message\n")
       Prints an informational message to standard error if current
       verbosity() level allows.

   $verbosity =	$manager->verbosity([$new_value])
       The verbosity() method get/sets a flag that sets	the level of
       informational messages.

SEE ALSO
       VM::EC2 VM::EC2::Staging::Server	VM::EC2::Staging::Volume
       migrate-ebs-image.pl

AUTHOR
       Lincoln Stein <lincoln.stein@gmail.com>.

       Copyright (c) 2012 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.

perl v5.32.1			  2021-02-28	  VM::EC2::Staging::Manager(3)

NAME | SYNOPSIS | DESCRIPTION | Constructors | Interzone Copying of AMIs and Snapshots | Instance Methods for Managing Staging Servers | Instance Methods for Managing Staging Volumes | Instance Methods for Accessing Configuration Options | Internal Methods | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=VM::EC2::Staging::Manager&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help