VM::EC...Volume(3pm)

📦

version 1.28 · 7 versions

1.28 · debian trixie, ubuntu resolute, ubuntu stonking (latest)
1.28 · epel 9
1.28 · fedora 43
1.28 · ubuntu jammy
1.28 · fedora 44
1.28 · ubuntu noble
1.28 · debian bookworm

, in debian trixie, ubuntu resolute, ubuntu stonking

💖 VM::EC2::Staging::Volume 💖

ok bestie, welcome to VM::EC2::Staging::Volume(3pm), straight outta the User Contributed Perl Documentation. yes it's a manual page, yes it's about cloud volumes, and yes we're gonna make it make sense. no cap. 🫶

✨ NAME ✨

VM::EC2::Staging::Volume — High level functions for provisioning and populating EC2 volumes. literally the vibe: you want a volume, you want stuff on it, you don't wanna hand-manage servers to get there. this is that. 💅

🌸 SYNOPSIS 🌸

ok so here's the whole flow, and honestly it's giving main character energy:

use VM::EC2::Staging::manager;

# get a new staging manager
my $ec2     = VM::EC2->new;
my $staging = $ec2->staging_manager();                                         );

my $vol1 = $staging->get_volume(-name => 'Backup',
                                -fstype => 'ext4',
                                -size   => 11,
                                -zone   => 'us-east-1a');

# make a couple of directories in new volume
$vol1->mkdir('pictures');
$vol1->mkdir('videos');

# use rsync to copy local files onto a subdirectory of this volume
$vol1->put('/usr/local/my_pictures/' =>'pictures');
$vol1->put('/usr/local/my_videos/'   =>'videos');

# use rsync to to copy a set of files on the volume to a local directory
mkdir('/tmp/jpegs');
$vol1->get('pictures/*.jpg','/tmp/jpegs');

# note that these commands are executed on the remote server as root!
@listing = $vol1->ls('-r','pictures');
$vol1->chown('fred','pictures');
$vol1->chgrp('nobody','pictures');
$vol1->chmod('0700','pictures');
$vol1->rm('-rf','pictures/*');
$vol1->rmdir('pictures');

# get some information about the volume
my $mtpt     = $vol->mtpt;
my $mtdev    = $vol->mtdev;
my $mounted  = $vol->mounted;
my $server   = $vol->server;

# detach the volume
$vol->detach;

# delete the volume entirely
$vol->delete;

🦋 DESCRIPTION 🦋

ok so listen. this is a high-level interface to EBS volumes, and it's meant to be used together with VM::EC2::Staging::Manager and VM::EC2::Staging::Server. its whole thing is making it so much easier to allocate and manage EBS volumes — it handles filesystem creation, directory management, and data transfer to and from the volume, all automated, no manual labor, periodt. 😌

the way that you can use staging volumes without having to manually create and manage the instances you'd need to actually manipulate those volumes?? iconic. when it's needed, the staging manager will spin up the server(s) required to run whatever action you asked for. you just ask. it does. 💅

staging volumes are wrappers around VM::EC2::Volume, so they've got all the methods those objects have. on top of the standard EC2 volume characteristics, every staging volume in an EC2 region also has a symbolic name, which is how you can grab a volume you made earlier without having to remember its volume ID (ngl, who remembers volume IDs). that symbolic name lives in the tag StagingName. volumes also have a filesystem type, which lives in the tag StagingFsType. and when a volume is mounted on a staging server, it also gets a mount point on the file system, plus a mounting device (like /dev/sdf1). 🎀

🌈 Staging Volume Creation 🌈

staging volumes get created through a staging manager's get_volume() or provision_volume() methods. go look at VM::EC2::Staging::Manager for the details. one typical invocation looks like this:

my $ec2     = VM::EC2->new;
my $manager = $ec2->staging_manager();                                         );
my $vol = $manager->get_volume(-name => 'Backup',
                               -fstype => 'ext4',
                               -size   => 5,
                               -zone   => 'us-east-1a');

so what does that do?? it will either go find an existing volume named "Backup", or, if there isn't one, create a brand new one using the spec you gave it. and behind the scenes? a staging server gets allocated to mount the volume. the manager is lowkey a resource-hoarder-in-reverse — it tries to conserve resources, so if there's a suitable running staging server just chilling there, it'll reuse it. slay. 🔥

the other typical invocation is this one:

my $vol = $manager->provision_volume(-name => 'Backup',
                                     -fstype => 'ext4',
                                     -size   => 5,
                                     -zone   => 'us-east-1a');

this one forces creation of a new volume with the characteristics you listed. so if a volume with that same name already exists, this method will die with a fatal error. 💀 to dodge that, you either wrap it in an eval, or just leave off the -name argument and let the manager pick a unique name for you. your call, bestie.

🧚 Volume Information 🧚

the methods in this section hand you status info about the staging volume. little vibe check, but for data.

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

get or set the symbolic name tied to this volume. 🏷️

`$mounted = $vol->mounted`

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

`$type = $vol->fstype`

returns the filesystem type that was requested back at volume creation time.

`$server = $vol->server`

gets the server associated with this volume, if there is one.

`$device = $vol->mtdev`

gets the device the volume is attached to, like /dev/sdf1. if the volume isn't attached to a server, this returns undef. 😭

`$device = $vol->mtpt`

gets the mount point for this volume on the attached server. if the volume isn't mounted, returns undef.

`$ebs_vol = $vol->ebs`

gets the underlying EBS volume that's associated with this staging volume object. 🫶

`$manager = $vol->manager`

returns the VM::EC2::Staging::Manager that manages this volume.

`$string = $vol->fstab_line();`

this method returns the line in /etc/fstab you'd need in order to mount this volume, on the server it's currently attached to, at boot time. for example:

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

and you can add that to the current server's fstab with this little 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`

returns the volume's actual filesystem type. heads up though — this can be different from the type you requested, if somebody later altered it by running mkfs on the volume, or if the contents of the disk got overwritten by a block-level dd command. 🙈 side effect alert: calling this method also sets fstype() to the current correct value. so it fixes things up while it's at it. helpful fr fr.

👑 Lifecycle Methods 👑

these are the ones that control the actual state of the volume. glow up, glow down, whatever you need.

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

creates a VM::EC2::Snapshot of the volume, with an optional description. the way this differs from the VM::EC2::Volume method with the same name: this one is aware of the mount state of the volume, and it'll first try to unmount it so that the snapshot comes out clean. then, once the snapshot has started, the volume gets remounted. ✨

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

identical to create_snapshot(), just with a shorter method name. same energy, fewer characters. 💅

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

mounts 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 gets detached first. and if any of these steps fails, the method will die with a fatal error. 💀

when you call it with no arguments, the volume gets automounted on a staging server — creating or starting that server if it needs to.

`$vol->unmount()`

unmounts the volume from wherever it is, but leaves it attached to the staging server. if it's not already mounted, nothing happens. no drama.

ngl there's a lil caveat here: it's possible for a volume to be mounted on a stopped server. in that case, the server will be started, and the volume only gets unmounted once the server is up and running.

`$vol->detach()`

unmounts and detaches the volume from its current server, if it has one.

same lil caveat, same warning: a volume can be mounted on a stopped server, and in that case the server will be started and the volume only unmounted when it's up and running.

`$vol->delete()`

deletes the volume entirely. if it's mounted and/or attached to a server, it gets unmounted/detached first. and if any of those steps fail, the method will die with a fatal error. 💀

🦋 and that's part 1, bestie — this page keeps going, so don't go anywhere 💖

🌈 Data Operations 🌈

okay so this whole section? it's about what's inside the volume, the actual files and folders, the vibes. 💖 And here's the tea: these methods mostly run with root privileges on the server machine, through some very judicious use of sudo. You do not need elevated permissions on your local machine (the one running the script). So like, relax, your laptop is fine. ✨

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

This one invokes rsync() on the server to copy files & directories from the source locations you name on the staging volume over to the destination. Copying era fr fr. 🦋

Your source paths can be:

relative paths, like "media/photos/vacation" — in which case they're relative to the top level of the mounted volume
absolute paths, like "/usr/local/media/photos/vacation" — in which case they're treated as absolute paths on the server where the volume is mounted

And the destination? So many options, main character energy:

a path on the local machine
a host:/path on a remote machine
a staging server and path in the form $server:/path
a staging volume and path in the form "$volume/path"

Peep "Instance Methods for Managing Staging Volumes" in VM::EC2::Staging::Manager for even more formats you can use. 👑

Special case alert 🚨 — if you call get() with a single argument:

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

Then the entire volume gets rsynced into the destination directory /tmp/foo. the whole thing. no cap.

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

This is literally just an alias for get(). It exists purely so your code reads nicer, because intent matters bestie:

$source_volume->copy($destination_volume);

Which basically makes a copy of $source_volume onto $destination_volume. That's it. that's the method. iconic behaviour honestly. 💖

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

Same energy as get() but the other direction — it invokes rsync() on the server to copy files & directories from the source locations you name to 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.

Special case again, because we love a special case ✨ — if you call put() with a single argument:

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

Then the local directory /tmp/foo gets copied onto the top level of the staging volume. And if you wanna 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 does a block level copy of the volume's disk onto the destination. And the destination must be another staging volume. That's the rule, no negotiating. 💀

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

This runs command $cmd on the server that's mounting the volume, and it does it using ssh. Before the command runs, the working directory gets changed to the top level of the volume's mount point. Any arguments, switches, etc. you wanna pass to the command go in @args.

Output comes back as a string in scalar context, or an array of lines in list context. Chef's kiss. 😭

Example:

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

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

Similar to cmd(), except the output of the command gets sent to STDOUT, and the method returns true if the command executed successfully on the remote machine. So cmd() and ssh() are equivalent to backticks and system() respectively. iykyk. 💅

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 one of these does the exact same thing as the like-named command-line function, except it first changes the working directory to the top level of the volume. They behave like 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. bestie please be careful. 🙈

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. no exceptions, periodt.

💜 SEE ALSO 💜

VM::EC2
VM::EC2::Staging::Manager
VM::EC2::Staging::Server
VM::EC2::Instance
VM::EC2::Volume
VM::EC2::Snapshot

✨ AUTHOR ✨

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

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.

and that's a wrap bestie!! 🌈💖✨ This lil doc was cooked up with perl v5.38.2 and last touched on 2024-08-10. go forth and mount responsibly, mwah 💅🎀🦋

📦 where this page comes from

debian trixie: libvm-ec2-perl 1.28-5 · Artistic-2.0 OR GPL-1.0-or-later
ubuntu resolute: libvm-ec2-perl 1.28-5 · Artistic-2.0 OR GPL-1.0-or-later
ubuntu stonking: libvm-ec2-perl 1.28-5 · Artistic-2.0 OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

VM::EC...Volume(3pm)

💖 VM::EC2::Staging::Volume 💖

✨ NAME ✨

🌸 SYNOPSIS 🌸

🦋 DESCRIPTION 🦋

🌈 Staging Volume Creation 🌈

🧚 Volume Information 🧚

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

$mounted = $vol->mounted

$type = $vol->fstype

$server = $vol->server

$device = $vol->mtdev

$device = $vol->mtpt

$ebs_vol = $vol->ebs

$manager = $vol->manager

$string = $vol->fstab_line();

$type = $vol->get_fstype

👑 Lifecycle Methods 👑

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

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

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

$vol->unmount()

$vol->detach()

$vol->delete()

🌈 Data Operations 🌈

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

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

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

🔥 $vol->dd($destination_volume)

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

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

👑 $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)