$name = $vol->name([$newname])

Get/set the symbolic name associated with this volume.

$mounted = $vol->mounted

Returns true if the volume is currently mounted on a server.

$type = $vol->fstype

Return the filesystem type requested at volume creation time.

$server = $vol->server

Get the server associated with this volume, if any.

$device = $vol->mtdev

Get the device that the volume is attached to, e.g. /dev/sdf1. If the volume is not attached to a server, returns undef.

$device = $vol->mtpt

Get the mount point for this volume on the attached server. If the volume is not mounted, returns undef.

$ebs_vol = $vol->ebs

Get the underlying EBS volume associated with the staging volume object.

$manager = $vol->manager

Return the VM::EC2::Staging::Manager which manages this volume.

$string = $vol->fstab_line();

This method returns the line in /etc/fstab that would be necessary to mount this volume on the server to which it is currently attached at boot time. For example:

 /dev/sdf1 /mnt/staging/Backups ext4 defaults,nobootwait 0 2

You can add this to the current server's fstab using the following code fragment:

 my $server = $vol->server;
 my $fh = $server->scmd_write('sudo -s "cat >>/etc/fstab"');
 print $fh $vol->fstab,"\n";
 close $fh;

$type = $vol->get_fstype

Return the volume's actual filesystem type. This can be different from the requested type if it was later altered by running mkfs on the volume, or the contents of the disk were overwritten by a block-level dd command. As a side effect, this method sets fstype() to the current correct value.

$snapshot = $vol->create_snapshot('description')

Create a VM::EC2::Snapshot of the volume with an optional description. This differs from the VM::EC2::Volume method of the same name in that it is aware of the mount state of the volume and will first try to unmount it so that the snapshot is clean. After the snapshot is started, the volume is remounted.

$snapshot = $vol->snapshot('description')

Identical to create_snapshot(), but the method name is shorter.

$vol->mount($server [,$mtpt])

$vol->mount()

Mount the volume on the indicated VM::EC2::Staging::Server, optionally at a named mount point on the file system. If the volume is already attached to a different server, it will be detached first. If any of these step fails, the method will die with a fatal error.

When called with no arguments, the volume is automounted on a staging server, creating or starting the server if necessary.

$vol->unmount()

Unmount the volume from wherever it is, but leave it attached to the staging server. If the volume is not already mounted, nothing happens.

Note that it is possible for a volume to be mounted on a stopped server, in which case the server will be started and the volume only unmounted when it is up and running.

$vol->detach()

Unmount and detach the volume from its current server, if any.

Note that it is possible for a volume to be mounted on a stopped server, in which case the server will be started and the volume only unmounted when it is up and running.

$vol->delete()

Delete the volume entirely. If it is mounted and/or attached to a server, it will be unmounted/detached first. If any steps fail, the method will die with a fatal error.

$vol->get($source_on_vol_1,$source_on_vol_2,...,$dest)

Invoke rsync() on the server to copy files & directories from the indicated source locations on the staging volume to the destination. Source paths can be relative paths, such as "media/photos/vacation", in which case they are relative to the top level of the mounted volume, or absolute paths, such as "/usr/local/media/photos/vacation", in which case they are treated as absolute paths on the server on which the volume is mounted.

The destination can be a path on the local machine, a host:/path on a remote machine, a staging server and path in the form $server:/path, or a staging volume and path in the form "$volume/path". See "Instance Methods for Managing Staging Volumes" in VM::EC2::Staging::Manager for more formats you can use.

As a special case, if you invoke get() with a single argument:

 $vol->get('/tmp/foo')

Then the entire volume will be rsynced into the destination directory /tmp/foo.

$vol->copy($source_on_vol_1,$source_on_vol_2,...,$dest)

This is an alias for get(). It is intended to make it easier to read the intent of this command:

 $source_volume->copy($destination_volume);

Which basically makes a copy of $source_volume onto $destination_volume.

$vol->put($source1,$source2,$source3,...,$dest_on_volume)

Invoke rsync() on the server to copy files & directories from the indicated source locations a destination located on the staging volume. The rules for paths are the same as for the get() method and as described in "Instance Methods for Managing Staging Volumes" in VM::EC2::Staging::Manager .

As a special case, if you invoke put() with a single argument:

 $vol->put('/tmp/foo')

Then the local directory /tmp/foo will be copied onto the top level of the staging volume. To do something similar with multiple source directories, use '/' or '.' as the destination:

 $vol->put('/tmp/pictures','/tmp/audio' => '/');

$vol->dd($destination_volume)

The dd() method performs a block level copy of the volume's disk onto the destination. The destination must be another staging volume.

$output = $vol->cmd($cmd,@args)

This method runs command $cmd on the server that is mounting the volume using ssh. Before the command is run, the working directory is changed to the top level of the volume's mount point. Any arguments, switches, etc you wish to pass to the command can be provided as @args. The output of the command is returned as a string in a scalar context, or an array of lines in a list context.

Example:

 @log = $volume->cmd('tar cvf /tmp/archive.tar .');

$result = $vol->ssh($cmd,@args)

This is similar to cmd(), except that the output of the command is sent to STDOUT and the method returns true if the command executed succcessfully on the remote machine. The cmd() and ssh() methods are equivalent to backticks are system() respectively.

Example:

 $volume->ssh('gzip /tmp/archive.tar') or die "couldn't compress archive";

$output = $vol->df(@args)

$output = $vol->ls(@args)

$success = $vol->mkdir(@args)

$success = $vol->chown(@args)

$success = $vol->chgrp(@args)

$success = $vol->chmod(@args)

$success = $vol->cp(@args)

$success = $vol->mv(@args)

$success = $vol->rm(@args)

$success = $vol->rmdir(@args)

Each of these methods performs the same function as the like-named command-line function, after first changing the working directory to the top level of the volume. They behave as shown in the pseudocode below:

 chdir $vol->mtpt;
 sudo  $method @args

The df() and ls() methods return the output of their corresponding commands. In a scalar context each method returns a string corresponding to the output of running the command on the server to which the volume is attached. In a list context, the methods return one element per line of output.

For example:

 my $free      = $volume->df('.');  # free on current directory
 my ($percent) = $free =~ /(\d+)%/;
 warn "almost out of space" if $percent > 90;

The other methods return a boolean value indicating successful execution of the command on the remote machine.

Command line switches can be passed along with other arguments:

 $volume->mkdir('-p','media/photos/vacation');
 $volume->chown('-R','fred','media');

With the exception of df, each of these commands runs as the superuser, so be careful how you call them.

You may run your own commands using the cmd() and ssh() methods. The former returns the output of the command. The latter returns a success code:

 @log = $volume->cmd('tar cvf /tmp/archive.tar .');
 $volume->ssh('gzip /tmp/archive.tar') or die "couldn't compress archive";

Before calling any of these methods, the volume must be mounted and its server running. A fatal error will occur otherwise.