Sysadm::Install - Typical installation tasks for system administrators
use Sysadm::Install qw(:all); my $INST_DIR = '/home/me/install/'; cd($INST_DIR); cp("/deliver/someproj.tgz", "."); untar("someproj.tgz"); cd("someproj"); # Write out ... blurt("Builder: Mike\nDate: Today\n", "build.dat"); # Slurp back in ... my $data = slurp("build.dat"); # or edit in place ... pie(sub { s/Today/scalar localtime()/ge; $_; }, "build.dat"); make("test install"); # run a cmd and tap into stdout and stderr my($stdout, $stderr, $exit_code) = tap("ls", "-R");
Have you ever wished for your installation shell scripts to run reproducably, without much programming fuzz, and even with optional logging enabled? Then give up shell programming, use Perl.
Sysadm::Install executes shell-like commands performing typical installation tasks: Copying files, extracting tarballs, calling make. It has a fail once and die policy, meticulously checking the result of every operation and calling die() immeditatly if anything fails.
Sysadm::Install
make
fail once and die
die()
cp($source, $target)
Copy a file from $source to $target. target can be a directory. Note that cp doesn't copy file permissions. If you want the target file to reflect the source file's user rights, use perm_cp() shown below.
$source
$target
target
cp
perm_cp()
mv($source, $target)
Move a file from $source to $target. target can be a directory.
download($url)
Download a file specified by $url and store it under the name returned by basename($url).
$url
basename($url)
untar($tgz_file)
Untar the tarball in $tgz_file, which typically adheres to the someproject-X.XX.tgz convention. But regardless of whether the archive actually contains a top directory someproject-X.XX, this function will behave if it had one. If it doesn't have one, a new directory is created before the unpacking takes place. Unpacks the tarball into the current directory, no matter where the tarfile is located.
$tgz_file
someproject-X.XX.tgz
someproject-X.XX
untar_in($tar_file, $dir)
Untar the tarball in $tgz_file in directory $dir. Create $dir if it doesn't exist yet.
$dir
pick($prompt, $options, $default)
Ask the user to pick an item from a displayed list. $prompt is the text displayed, $options is a referenc to an array of choices, and $default is the number (starting from 1, not 0) of the default item. For example,
$prompt
$options
$default
pick("Pick a fruit", ["apple", "pear", "pineapple"], 3);
will display the following:
[1] apple [2] pear [3] pineapple Pick a fruit [3]>
If the user just hits Enter, "pineapple" (the default value) will be returned. Note that 3 marks the 3rd element of the list, and is not an index value into the array.
If the user enters 1, 2 or 3, the corresponding text string ("apple", "pear", "pineapple" will be returned by pick().
1
2
3
"apple"
"pear"
"pineapple"
pick()
ask($prompt, $default)
Ask the user to either hit Enter and select the displayed default or to type in another string.
mkd($dir)
Create a directory of arbitrary depth, just like File::Path::mkpath.
File::Path::mkpath
rmf($dir)
Delete a directory and all of its descendents, just like rm -rf in the shell.
rm -rf
cd($dir)
chdir to the given directory.
cdback()
chdir back to the last directory before a previous cd.
cd
make()
Call make in the shell.
pie($coderef, $filename, ...)
Simulate "perl -pie 'do something' file". Edits files in-place. Expects a reference to a subroutine as its first argument. It will read out the file $filename line by line and calls the subroutine setting a localized $_ to the current line. The return value of the subroutine will replace the previous value of the line.
$filename
$_
Example:
# Replace all 'foo's by 'bar' in test.dat pie(sub { s/foo/bar/g; $_; }, "test.dat");
Works with one or more file names.
plough($coderef, $filename, ...)
Simulate "perl -ne 'do something' file". Iterates over all lines of all input files and calls the subroutine provided as the first argument.
# Print all lines containing 'foobar' plough(sub { print if /foobar/ }, "test.dat");
my $data = slurp($file)
Slurps in the file and returns a scalar with the file's content.
blurt($data, $file, $append)
Opens a new file, prints the data in $data to it and closes the file. If $append is set to a true value, data will be appended to the file. Default is false, existing files will be overwritten.
$data
$append
($stdout, $stderr, $exit_code) = tap($cmd, @args)
Run a command $cmd in the shell, and pass it @args as args. Capture STDOUT and STDERR, and return them as strings. If $exit_code is 0, the command succeeded. If it is different, the command failed and $exit_code holds its exit code.
$exit_code
Please note that tap() is limited to single shell commands, it won't work with output redirectors (ls >/tmp/foo 2>&1).
tap()
ls >/tmp/foo
In default mode, tap() will concatenate the command and args given and create a shell command line by redirecting STDERR to a temporary file. tap("ls", "/tmp"), for example, will result in
tap("ls", "/tmp")
'ls' '/tmp' 2>/tmp/sometempfile |
Note that all commands are protected by single quotes to make sure arguments containing spaces are processed as singles, and no globbing happens on wildcards. Arguments containing single quotes or backslashes are escaped properly.
If quoting is undesirable, tap() accepts an option hash as its first parameter,
tap({no_quotes => 1}, "ls", "/tmp/*");
which will suppress any quoting:
ls /tmp/* 2>/tmp/sometempfile |
Or, if you prefer double quotes, use
tap({double_quotes => 1}, "ls", "/tmp/$VAR");
wrapping all args so that shell variables are interpolated properly:
"ls" "/tmp/$VAR" 2>/tmp/sometempfile |
$quoted_string = qquote($string, [$metachars])
Put a string in double quotes and escape all sensitive characters so there's no unwanted interpolation. E.g., if you have something like
print "foo!\n";
and want to put it into a double-quoted string, it will look like
"print \"foo!\\n\""
Sometimes, not only backslashes and double quotes need to be escaped, but also the target environment's meta chars. A string containing
print "$<\n";
needs to have the '$' escaped like
"print \"\$<\\n\";"
if you want to reuse it later in a shell context:
$ perl -le "print \"\$<\\n\";" 1212
qquote() supports escaping these extra characters with its second, optional argument, consisting of a string listing all escapable characters:
qquote()
my $script = 'print "$< rocks!\\n";'; my $escaped = qquote($script, '!$'); # Escape for shell use system("perl -e $escaped"); => 1212 rocks!
And there's a shortcut for shells: By specifying ':shell' as the metacharacters string, qquote() will actually use '!$`'.
For example, if you wanted to run the perl code
print "foobar\n";
via
perl -e ...
on a box via ssh, you would use
use Sysadm::Install qw(qquote); my $cmd = 'print "foobar!\n"'; $cmd = "perl -e " . qquote($cmd, ':shell'); $cmd = "ssh somehost " . qquote($cmd, ':shell'); print "$cmd\n"; system($cmd);
and get
ssh somehost "perl -e \"print \\\"foobar\\\!\\\\n\\\"\""
which runs on somehost without hickup and prints foobar!.
somehost
foobar!
$quoted_string = quote($string, [$metachars])
Similar to qquote(), just puts a string in single quotes.
perm_cp($src, $dst, ...)
Read the $src file's user permissions and modify all $dst files to reflect the same permissions.
$src
$dst
sysrun($cmd)
Run a shell command via system() and die() if it fails. Also works with a list of arguments, which are then interpreted as program name plus arguments, just like system() does it.
system()
hammer($cmd, $arg, ...)
Run a command in the shell and simulate a user hammering the ENTER key to accept defaults on prompts.
say($text, ...)
Alias for print ..., "\n", just like Perl6 is going to provide it.
print ..., "\n"
sudo_me()
Check if the current script is running as root. If yes, continue. If not, restart the current script with all command line arguments is restarted under sudo:
sudo scriptname args ...
Make sure to call this before any @ARGV-modifying functions like getopts() have kicked in.
@ARGV
getopts()
bin_find($program)
Search all directories in $PATH (the ENV variable) for an executable named $program and return the full path of the first hit. Returns undef if the program can't be found.
undef
fs_read_open($dir)
Opens a file handle to read the output of the following process:
cd $dir; find ./ -xdev -print0 | cpio -o0 |
This can be used to capture a file system structure.
fs_write_open($dir)
Opens a file handle to write to a
| (cd $dir; cpio -i0)
process to restore a file system structure. To be used in conjunction with fs_read_open.
pipe_copy($in, $out, [$bufsize])
Reads from $in and writes to $out, using sysread and syswrite. The buffer size used defaults to 4096, but can be set explicitely.
Mike Schilli, <m@perlmeister.com>
Copyright (C) 2004 by Mike Schilli
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.3 or, at your option, any later version of Perl 5 you may have available.
1 POD Error
The following errors were encountered while parsing the POD:
You can't have =items (as at line 109) unless the first thing after the =over is an =item
To install Sysadm::Install, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Sysadm::Install
CPAN shell
perl -MCPAN -e shell install Sysadm::Install
For more information on module installation, please visit the detailed CPAN module installation guide.