deployable

   1 #!/usr/bin/env perl
   2 use strict;
   3 use warnings;
   4 use Carp;
   5 use version; our $VERSION = qv('0.1.1');
   6 use Fatal qw( close );
   7 use Pod::Usage qw( pod2usage );
   8 use Getopt::Long qw( :config gnu_getopt );
   9 use English qw( -no_match_vars );
  10 use File::Basename qw( basename dirname );
  11 use File::Spec::Functions qw( file_name_is_absolute catfile );
  12 use File::Temp qw( tempfile );
  13 use POSIX qw( strftime );
  14 use Cwd qw( cwd realpath );
  15 use Archive::Tar;
  16 use File::Find::Rule;
  17 use Data::Dumper;
  18 use Encode;
  19
  20 my %config = (
  21    output      => '-',
  22    remote      => catfile(dirname(realpath(__FILE__)), 'remote'),
  23    tarfile     => [],
  24    heredir     => [],
  25    rootdir     => [],
  26    root        => [],
  27    tarfile     => [],
  28    deploy      => [],
  29    passthrough => 0,
  30 );
  31 GetOptions(
  32    \%config,
  33    qw(
  34      usage! help! man! version!
  35
  36      bundle|all-exec|X!
  37      bzip2|bz2|j!
  38      cleanup|c!
  39      deploy|exec|d=s@
  40      gzip|gz|z!
  41      heredir|H=s@
  42      include-archive-tar|T!
  43      no-tar!
  44      output|o=s
  45      passthrough|P!
  46      root|r=s@
  47      rootdir|R=s@
  48      tar|t=s
  49      tarfile|F=s@
  50      tempdir-mode|m=s
  51      workdir|work-directory|deploy-directory|w=s
  52      ),
  53 );
  54 pod2usage(message => "$0 $VERSION", -verbose => 99, -sections => '')
  55   if $config{version};
  56 pod2usage(-verbose => 99, -sections => 'USAGE') if $config{usage};
  57 pod2usage(-verbose => 99, -sections => 'USAGE|EXAMPLES|OPTIONS')
  58   if $config{help};
  59 pod2usage(-verbose => 2) if $config{man};
  60
  61 pod2usage(
  62    message   => 'working directory must be an absolute path',
  63    -verbose  => 99,
  64    -sections => ''
  65 ) if exists $config{workdir} && !file_name_is_absolute($config{workdir});
  66
  67 if ($config{'include-archive-tar'}) {
  68    $config{remote} = catfile(dirname(realpath(__FILE__)), 'remote-at');
  69    if (!-e $config{remote}) {    # "make" it
  70       print {*STDERR} "### Making remote-at...\n";
  71       my $startdir = cwd();
  72       chdir dirname realpath __FILE__;
  73       system {'make'} qw( make remote-at );
  74       chdir $startdir;
  75    } ## end if (!-e $config{remote...})
  76 } ## end if ($config{'include-archive-tar'...})
  77
  78 # Establish output channel
  79 my $out_fh = \*STDOUT;
  80 if ($config{output} ne '-') {
  81    open my $fh, '>', $config{output}    ## no critic
  82      or croak "open('$config{output}'): $OS_ERROR";
  83    $out_fh = $fh;
  84 }
  85 binmode $out_fh;
  86
  87 # Emit script code to be executed remotely. It is guaranteed to end
  88 # with __END__, so that all what comes next is data
  89 print {$out_fh} get_remote_script();
  90
  91 # Where all the data will be kept
  92 print_configuration($out_fh, \%config);
  93
  94 print_here_stuff($out_fh, \%config, @ARGV);
  95 print_root_stuff($out_fh, \%config);
  96
  97 close $out_fh;
  98
  99 # Set as executable
 100 if ($config{output} ne '-') {
 101    chmod oct(755), $config{output}
 102      or carp "chmod(0755, '$config{output}'): $OS_ERROR";
 103 }
 104
 105 sub header {
 106    my %params   = @_;
 107    my $namesize = length $params{name};
 108    return "$namesize $params{size}\n$params{name}";
 109 }
 110
 111 sub print_configuration {    # FIXME
 112    my ($fh, $config) = @_;
 113    my %general_configuration;
 114    for my $name (
 115       qw( workdir cleanup bundle deploy
 116       gzip bzip2 passthrough tempdir-mode )
 117      )
 118    {
 119       $general_configuration{$name} = $config->{$name}
 120         if exists $config->{$name};
 121    } ## end for my $name (qw( workdir cleanup bundle deploy...))
 122    my $configuration = Dumper \%general_configuration;
 123    print {$fh} header(name => 'config.pl', size => length($configuration)),
 124      "\n", $configuration, "\n\n";
 125 } ## end sub print_configuration
 126
 127 # Process files and directories. All these will be reported in the
 128 # extraction directory, i.e. basename() will be applied to them. For
 129 # directories, they will be re-created
 130 sub print_here_stuff {
 131    my $fh     = shift;
 132    my $config = shift;
 133    my @ARGV   = @_;
 134
 135    my $ai = Deployable::Tar->new($config);
 136    $ai->add(
 137       '.' => \@ARGV,
 138       map { $_ => ['.'] } @{$config->{heredir}}
 139    );
 140
 141    print {$fh} header(name => 'here', size => $ai->size()), "\n";
 142    $ai->copy_to($fh);
 143    print {$fh} "\n\n";
 144
 145    return;
 146 } ## end sub print_here_stuff
 147
 148 sub print_root_stuff {
 149    my ($fh, $config) = @_;
 150
 151    my $ai = Deployable::Tar->new($config);
 152    $ai->add(
 153       '.' => $config->{rootdir},
 154       (undef, $config->{tarfile}),
 155       map { $_ => ['.'] } @{$config->{root}}
 156    );
 157
 158    print {$fh} header(name => 'root', size => $ai->size()), "\n";
 159    $ai->copy_to($fh);
 160    print {$fh} "\n\n";
 161
 162    return;
 163 } ## end sub print_root_stuff
 164
 165 sub get_remote_script {
 166    open my $fh, '<', $config{remote}
 167      or croak "open('$config{remote}'): $OS_ERROR";
 168    my @lines;
 169    while (<$fh>) {
 170       last if /\A __END__ \s*\z/mxs;
 171       push @lines, $_;
 172    }
 173    close $fh;
 174    return join '', @lines, "__END__\n";
 175 } ## end sub get_remote_script
 176
 177 package Deployable::Tar;
 178
 179 sub new {
 180    my $package = shift;
 181    my $self = {ref $_[0] ? %{$_[0]} : @_};
 182    $package = 'Deployable::Tar::Internal';
 183    if (!$self->{'no-tar'}) {
 184       if ((exists $self->{tar}) || (open my $fh, '-|', 'tar', '--help')) {
 185          $package = 'Deployable::Tar::External';
 186          $self->{tar} ||= 'tar';
 187       }
 188    } ## end if (!$self->{'no-tar'})
 189    bless $self, $package;
 190    $self->initialise();
 191    return $self;
 192 } ## end sub new
 193
 194 package Deployable::Tar::External;
 195 use File::Temp qw( :seekable );
 196 use English qw( -no_match_vars );
 197 use Cwd ();
 198 use Carp;
 199 our @ISA = qw( Deployable::Tar );
 200
 201 sub initialise {
 202    my $self = shift;
 203    $self->{_temp}     = File::Temp->new();
 204    $self->{_filename} = Cwd::abs_path($self->{_temp}->filename());
 205    return $self;
 206 } ## end sub initialise
 207
 208 sub add {
 209    my $self = shift;
 210    my $tar  = $self->{tar};
 211    delete $self->{_compressed};
 212    while (@_) {
 213       my ($directory, $stuff) = splice @_, 0, 2;
 214       my @stuff = @$stuff;
 215       if (defined $directory) {
 216          while (@stuff) {
 217             my @chunk = splice @stuff, 0, 50;
 218             system {$tar} $tar, 'rvf', $self->{_filename},
 219               '-C', $directory, '--', @chunk;
 220          }
 221       } ## end if (defined $directory)
 222       else {    # it's another TAR file, concatenate
 223          while (@stuff) {
 224             my @chunk = splice @stuff, 0, 50;
 225             system {$tar} $tar, 'Avf', $self->{_filename}, '--', @chunk;
 226          }
 227       } ## end else [ if (defined $directory)]
 228    } ## end while (@_)
 229    return $self;
 230 } ## end sub add
 231
 232 sub _compress {
 233    my $self = shift;
 234    return if exists $self->{_compressed};
 235
 236    $self->{_temp}->sysseek(0, SEEK_SET);
 237    if ($self->{bzip2}) {
 238       require IO::Compress::Bzip2;
 239       $self->{_compressed} = File::Temp->new();
 240
 241       # double-quotes needed to force usage of filename
 242       # instead of filehandle
 243       IO::Compress::Bzip2::bzip2($self->{_temp}, "$self->{_compressed}");
 244    } ## end if ($self->{bzip2})
 245    elsif ($self->{gzip}) {
 246       require IO::Compress::Gzip;
 247       $self->{_compressed} = File::Temp->new();
 248
 249       # double-quotes needed to force usage of filename
 250       # instead of filehandle
 251       IO::Compress::Gzip::gzip($self->{_temp}, "$self->{_compressed}");
 252    } ## end elsif ($self->{gzip})
 253    else {
 254       $self->{_compressed} = $self->{_temp};
 255    }
 256
 257    return $self;
 258 } ## end sub _compress
 259
 260 sub size {
 261    my ($self) = @_;
 262    $self->_compress();
 263    return (stat $self->{_compressed})[7];
 264 }
 265
 266 sub copy_to {
 267    my ($self, $out_fh) = @_;
 268    $self->_compress();
 269    my $in_fh = $self->{_compressed};
 270    $in_fh->sysseek(0, SEEK_SET);
 271    while ('true') {
 272       my $nread = $in_fh->sysread(my $buffer, 4096);
 273       croak "sysread(): $OS_ERROR" unless defined $nread;
 274       last unless $nread;
 275       print {$out_fh} $buffer;
 276    } ## end while ('true')
 277    return $self;
 278 } ## end sub copy_to
 279
 280 package Deployable::Tar::Internal;
 281 use Archive::Tar     ();
 282 use Cwd              ();
 283 use File::Find::Rule ();
 284 use Carp qw< croak >;
 285 our @ISA = qw( Deployable::Tar );
 286
 287 sub initialise {
 288    my $self = shift;
 289    $self->{_tar} = Archive::Tar->new();
 290    return $self;
 291 }
 292
 293 sub add {
 294    my $self = shift;
 295    delete $self->{_string};
 296    my $tar = $self->{_tar};
 297    my $cwd = Cwd::getcwd();
 298    while (@_) {
 299       my ($directory, $stuff) = splice @_, 0, 2;
 300       if (defined $directory) {
 301          chdir $directory;
 302          for my $item (@$stuff) {
 303             $tar->add_files($_) for File::Find::Rule->in($item);
 304          }
 305          chdir $cwd;
 306       } ## end if (defined $directory)
 307       else {
 308          croak 'unsupported TAR files concatenation with internal';
 309       }
 310    } ## end while (@_)
 311    return $self;
 312 } ## end sub add
 313
 314 sub size {
 315    my ($self) = @_;
 316    $self->{_string} = $self->{_tar}->write()
 317      unless exists $self->{_string};
 318    return length $self->{_string};
 319 } ## end sub size
 320
 321 sub copy_to {
 322    my ($self, $out_fh) = @_;
 323    $self->{_string} = $self->{_tar}->write()
 324      unless exists $self->{_string};
 325    print {$out_fh} $self->{_string};
 326 } ## end sub copy_to
 327
 328 __END__
 329
 330 =head1 NAME
 331
 332 deployable - create a deploy script for some files/scripts
 333
 334 =head1 VERSION
 335
 336 See version at beginning of script, variable $VERSION, or call
 337
 338    shell$ deployable --version
 339
 340 =head1 USAGE
 341
 342    deployable [--usage] [--help] [--man] [--version]
 343
 344    deployable [--bundle|--all-exec|-X] [--bzip2|--bz2|-j] [--cleanup|-c]
 345               [--deploy|--exec|d <program>] [--gzip|-gz|-z]
 346               [--heredir|-H <dirname>] [--include-archive-tar|-T]
 347               [--no-tar] [--output|-o <filename>] [--root|-r <dirname>]
 348               [--rootdir|-R <dirname>] [--tar|-t <program-path>]
 349               [--tarfile|-F <filename>] [--tempdir-mode|-m <mode>]
 350               [--workdir|-w <path>] [ files or directories... ]
 351
 352 =head1 EXAMPLES
 353
 354    # pack some files and a deploy script together.
 355    shell$ deployable script.sh file.txt some/directory -d script.sh
 356
 357    # Use a directory's contents as elements for the target root
 358    shell$ ls -1 /path/to/target/root
 359    etc
 360    opt
 361    usr
 362    var
 363    # The above will be deployed as /etc, /opt, /usr and /var
 364    shell$ deployable -o dep.pl --root /path/to/target/root
 365
 366    # Include directory /path/to/etc for inclusion and extraction
 367    # directly as /etc
 368    shell$ deployable -o dep.pl --rootdir /path/to/etc
 369
 370 =head1 DESCRIPTION
 371
 372 This is a meta-script to create deploy scripts. The latter ones are
 373 suitable to be distributed in order to deploy something.
 374
 375 You basically have to provide two things: files to install and programs
 376 to be executed. Files can be put directly into the deployed script, or
 377 can be included in gzipped tar archives.
 378
 379 When called, this script creates a deploy script for you. This script
 380 includes all the specified files, and when executed it will extract
 381 those files and execute the given programs. In this way, you can ship
 382 both files and logic needed to correctly install those files, but this
 383 is of course of of scope.
 384
 385 All files and archives will be extracted under a configured path
 386 (see L<--workdir> below), which we'll call I<workdir> from now on. Under
 387 the I<workdir> a temporary directory will be created, and the files
 388 will be put in the temporary directory. You can specify if you want to
 389 clean up this temporary directory or keep it, at your choice. (You're able
 390 to both set a default for this cleanup when invoking deployable, or when
 391 invoking the deploy script itself). The temporary directory will be
 392 called I<tmpdir> in the following.
 393
 394 There are several ways to embed files to be shipped:
 395
 396 =over
 397
 398 =item *
 399
 400 pass the name of an already-prepared tar file via L</--tarfile>. The
 401 contents of this file will be assumed to be referred to the root
 402 directory;
 403
 404 =item *
 405
 406 specify the file name directly on the command line. A file given in this
 407 way will always be extracted into the I<tmpdir>, whatever its initial path
 408 was;
 409
 410 =item *
 411
 412 specify the name of a directory on the command line. In this case,
 413 C<tar> will be used to archive the directory, with the usual option to
 414 turn absolute paths into relative ones; this means that directories will
 415 be re-created under I<tmpdir> when extraction is performed;
 416
 417 =item *
 418
 419 give the name of a directory to be used as a "here directory", using
 420 the C<--heredir|-H> option. This is much the same as giving the directory
 421 name (see above), but in this case C<tar> will be told to change into the
 422 directory first, and archive '.'. This means that the contents of the
 423 "here-directory" will be extracted directly into I<tmpdir>.
 424
 425 =back
 426
 427 =head2 Extended Example
 428
 429 Suppose you have a few server which have the same configuration, apart
 430 from some specific stuff (e.g. the hostname, the IP addresses, etc.).
 431 You'd like to perform changes to all with the minimum work possible...
 432 so you know you should script something.
 433
 434 For example, suppose you want to update a few files in /etc, setting these
 435 files equal for all hosts. You would typically do the following:
 436
 437    # In your computer
 438    shell$ mkdir -p /tmp/newfiles/etc
 439    shell$ cd /tmp/newfiles/etc
 440    # Craft the new files
 441    shell$ cd ..
 442    shell$ tar cvzf newetc.tar.gz etc
 443
 444    # Now, for each server:
 445    shell$ scp newetc.tar.gz $server:/tmp
 446    shell$ ssh $server tar xvzf /tmp/newetc.tar.gz -C /
 447
 448
 449 So far, so good. But what if you need to kick in a little more logic?
 450 For example, if you update some configuration files, you'll most likey
 451 want to restart some services. So you could do the following:
 452
 453    shell$ mkdir -p /tmp/newfiles/tmp
 454    shell$ cd /tmp/newfiles/tmp
 455    # craft a shell script to be executed remotely and set the exec bit
 456    # Suppose it's called deploy.sh
 457    shell$ cd ..
 458    shell$ tar cvzf newetc.tar.gz etc tmp
 459
 460    # Now, for each server:
 461    shell$ scp newetc.tar.gz $server:/tmp
 462    shell$ ssh $server tar xvzf /tmp/newetc.tar.gz -C /
 463    shell$ ssh $server /tmp/deploy.sh
 464
 465 And what if you want to install files depending on the particular machine?
 466 Or you have a bundle of stuff to deploy and a bunch of scripts to execute?
 467 You can use deployable. In this case, you can do the following:
 468
 469    shell$ mkdir -p /tmp/newfiles/etc
 470    shell$ cd /tmp/newfiles/etc
 471    # Craft the new files
 472    shell$ cd ..
 473    # craft a shell script to be executed remotely and set the exec bit
 474    # Suppose it's called deploy.sh
 475    shell$ deployable -o deploy.pl etc deploy.sh --exec deploy.sh
 476
 477    # Now, for each server
 478    shell$ scp deploy.pl $server:/tmp
 479    shell$ ssh $server /tmp/deploy.pl
 480
 481 And you're done. This can be particularly useful if you have another
 482 layer of deployment, e.g. if you have to run a script to decide which
 483 of a group of archives should be deployed. For example, you could craft
 484 a different new "etc" for each server (which is particularly true if
 485 network configurations are in the package), and produce a simple script
 486 to choose which file to use based on the MAC address of the machine. In
 487 this case you could have:
 488
 489 =over
 490
 491 =item newetc.*.tar.gz
 492
 493 a bunch of tar files with the configurations for each different server
 494
 495 =item newetc.list
 496
 497 a list file with the association between the MAC addresses and the
 498 real tar file to deploy from the bunch in the previous bullet
 499
 500 =item deploy-the-right-stuff.sh
 501
 502 a script to get the real MAC address of the machine, select the right
 503 tar file and do the deployment.
 504
 505 =back
 506
 507 So, you can do the following:
 508
 509    shell$ deployable -o deploy.pl newetc.*.tar.gz newetc.list \
 510       deploy-the-right-stuff.sh --exec deploy-the-right-stuff.sh
 511
 512    # Now, for each server:
 513    shell$ scp deploy.pl $server:/tmp
 514    shell$ ssh $server /tmp/deploy.pl
 515
 516 So, once you have the deploy script on the target machine all you need
 517 to do is to execute it. This can come handy when you cannot access the
 518 machines from the network, but you have to go there physically: you
 519 can prepare all in advance, and just call the deploy script.
 520
 521
 522 =head1 OPTIONS
 523
 524 Meta-options:
 525
 526 =over
 527
 528 =item B<--help>
 529
 530 print a somewhat more verbose help, showing usage, this description of
 531 the options and some examples from the synopsis.
 532
 533 =item B<--man>
 534
 535 print out the full documentation for the script.
 536
 537 =item B<--usage>
 538
 539 print a concise usage line and exit.
 540
 541 =item B<--version>
 542
 543 print the version of the script.
 544
 545 =back
 546
 547 Real-world options:
 548
 549 =over
 550
 551 =item B<< --bundle | --all-exec | -X >>
 552
 553 Set bundle flag in the produced script. If the bundle flag is set, the
 554 I<deploy script> will treat all executables in the main deployment
 555 directory as scripts to be executed.
 556
 557 By default the flag is not set.
 558
 559 =item B<< --bzip2 | --bz2 | -j >>
 560
 561 Compress tar archives with bzip2.
 562
 563 =item B<< --cleanup | -c >>
 564
 565 Set cleanup flag in the produced script. If the cleanup flag is set, the
 566 I<deploy script> will clean up after having performed all operations.
 567
 568 You can set this flag to C<0> by using C<--no-cleanup>.
 569
 570 =item B<< --deploy | --exec | -d <filename> >>
 571
 572 Set the name of a program to execute after extraction. You can provide
 573 multiple program names, they will be executed in the same order.
 574
 575 =item B<< --gzip | --gz | -z >>
 576
 577 Compress tar archives with gzip.
 578
 579 =item B<< --heredir | -H <path> >>
 580
 581 Set the name of a "here directory" (see L<DESCRIPTION>). You can use this
 582 option multiple times to provide multiple directories.
 583
 584 =item B<< --include-archive-tar | -T >>
 585
 586 Embed L<Archive::Tar> (with its dependencies L<Archive::Tar::Constant> and
 587 L<Archive::Tar::File>) inside the final script. Use this when you know (or
 588 aren't sure) that L<Archive::Tar> will not be available in the target
 589 machine.
 590
 591 =item B<< --no-tar >>
 592
 593 Don't use system C<tar>.
 594
 595 =item B<< --output | -o <filename> >>
 596
 597 Set the output file name. By default the I<deploy script> will be given
 598 out on the standard output; if you provide a filename (different from
 599 C<->, of course!) the script will be saved there and the permissions will
 600 be set to 0755.
 601
 602 =item B<< --root | -r <dirname> >>
 603
 604 Include C<dirname> contents for deployment under root directory. The
 605 actual production procedure is: hop into C<dirname> and grab a tarball
 606 of C<.>. During deployment, hop into C</> and extract the tarball.
 607
 608 This is useful if you're already building up the absolute deployment
 609 layout under a given directory: just treat that directory as if it were
 610 the root of the target system.
 611
 612 =item B<< --rootdir | -R <dirname >>
 613
 614 Include C<dirname> as a directory that will be extracted under root
 615 directory. The actual production procedure is: grab a tarball of
 616 C<dirname>. During deployment, hop into C</> and extract the tarball.
 617
 618 This is useful if you have a directory (or a group of directories) that
 619 you want to deploy directly under the root.
 620
 621 =item B<< --tar | -t <program-path> >>
 622
 623 Set the system C<tar> program to use.
 624
 625 =item B<< --tempdir-mode | -m >>
 626
 627 set default permissions for temporary directory of deployable script
 628
 629 =item B<< --workdir | --deploy-directory | -w <path> >>
 630
 631 Set the working directory for the deploy.
 632
 633 =back
 634
 635 =head1 THE DEPLOY SCRIPT
 636
 637 The net result of calling this script is to produce another script,
 638 that we call the I<deploy script>. This script is made of two parts: the
 639 code, which is fixed, and the configurations/files, which is what is
 640 actually produced. The latter part is put after the C<__END__> marker,
 641 as usual.
 642
 643 Stuff in the configuration part is always hexified in order to prevent
 644 strange tricks or errors. Comments will help you devise what's inside the
 645 configurations themselves.
 646
 647 The I<deploy script> has options itself, even if they are quite minimal.
 648 In particular, it supports the same options C<--workdir|-w> and
 649 C<--cleanup> described above, allowing the final user to override the
 650 configured values. By default, the I<workdir> is set to C</tmp>
 651 and the script will clean up after itself.
 652
 653 The following options are supported in the I<deploy script>:
 654
 655 =over
 656
 657 =item B<--usage | --man | --help>
 658
 659 print a minimal help and exit
 660
 661 =item B<--version>
 662
 663 print script version and exit
 664
 665 =item B<--bundle | --all-exec | -X>
 666
 667 treat all executables in the main deployment directory as scripts
 668 to be executed
 669
 670 =item B<--cleanup | --no-cleanup>
 671
 672 perform / don't perform temporary directory cleanup after work done
 673
 674 =item B<< --deploy | --no-deploy >>
 675
 676 deploy scripts are executed by default (same as specifying '--deploy')
 677 but you can prevent it.
 678
 679 =item B<--dryrun | --dry-run>
 680
 681 print final options and exit
 682
 683 =item B<< --filelist | --list | -l >>
 684
 685 print a list of files that are shipped in the deploy script
 686
 687 =item B<< --heretar | --here-tar | -H >>
 688
 689 print out the tar file that contains all the files that would be
 690 extracted in the temporary directory, useful to redirect to file or
 691 pipe to the tar program
 692
 693 =item B<< --inspect <dirname> >>
 694
 695 just extract all the stuff into <dirname> for inspection. Implies
 696 C<--no-deploy>, C<--no-tempdir>, ignores C<--bundle> (as a consequence of
 697 C<--no-deploy>), disables C<--cleanup> and sets the working directory
 698 to C<dirname>
 699
 700 =item B<< --no-tar >>
 701
 702 don't use system C<tar>
 703
 704 =item B<< --rootar | --root-tar | -R >>
 705
 706 print out the tar file that contains all the files that would be
 707 extracted in the root directory, useful to redirect to file or
 708 pipe to the tar program
 709
 710 =item B<--show | --show-options | -s>
 711
 712 print configured options and exit
 713
 714 =item B<< --tar | -t <program-path> >>
 715
 716 set the system C<tar> program to use.
 717
 718 =item B<< --tempdir | --no-tempdir >>
 719
 720 by default a temporary directory is created (same as specifying
 721 C<--tempdir>), but you can execute directly in the workdir (see below)
 722 without creating it.
 723
 724 =item B<< --tempdir-mode | -m >>
 725
 726 temporary directories (see C<--tempdir>) created by File::Temp have
 727 permission 600 that prevents group/others from even looking at the
 728 contents. You might want to invoke some of the internal scripts
 729 from another user (e.g. via C<su>), so you can pass a mode to be
 730 set on the temporary directory.
 731
 732 Works only if C<--tempdir> is active.
 733
 734 =item B<--workdir | --work-directory | --deploy-directory | -w>
 735
 736 working base directory (a temporary subdirectory will be created
 737 there anyway)
 738
 739 =back
 740
 741 Note the difference between C<--show> and C<--dryrun>: the former will
 742 give you the options that are "embedded" in the I<deploy script> without
 743 taking into account other options given on the command line, while the
 744 latter will give you the final options that would be used if the script
 745 were called without C<--dryrun>.
 746
 747 =head2 Deploy Script Example Usage
 748
 749 In the following, we'll assume that the I<deploy script> is called
 750 C<deploy.pl>.
 751
 752 To execute the script with the already configured options, you just have
 753 to call it:
 754
 755    shell$ ./deploy.pl
 756
 757 If you just want to see which configurations are in the I<deploy script>:
 758
 759    shell$ ./deploy.pl --show
 760
 761 To see which files are included, you have two options. One is asking the
 762 script:
 763
 764    shell$ ./deploy.pl --filelist
 765
 766 the other is piping to tar:
 767
 768    shell$ ./deploy.pl --tar | tar tvf -
 769
 770 Extract contents of the script in a temp directory and simply inspect
 771 what's inside:
 772
 773    # extract stuff into subdirectory 'inspect' for... inspection
 774    shell$ ./deploy.pl --no-tempdir --no-deploy --workdir inspect
 775
 776 =head2 Deploy Script Requirements
 777
 778 You'll need a working Perl with version at least 5.6.2.
 779
 780 If you specify L</--include-archive-tar>, the module L<Archive::Tar> will
 781 be included as well. This should ease your life and avoid you to have
 782 B<tar> on the target machine. On the other hand, if you already know
 783 that B<tar> will be available, you can avoid including C<Archive::Tar>
 784 and have the generated script use it (it could be rather slower anyway).
 785
 786 =head1 DIAGNOSTICS
 787
 788 Each error message should be enough explicit to be understood without the
 789 need for furter explainations. Which is another way to say that I'm way
 790 too lazy to list all possible ways that this script has to fail.
 791
 792
 793 =head1 CONFIGURATION AND ENVIRONMENT
 794
 795 deployable requires no configuration files or environment variables.
 796
 797 Please note that deployable B<needs> to find its master B<remote> file
 798 to produce the final script. This must be put in the same directory where
 799 deployable is put. You should be able to B<symlink> deployable where you
 800 think it's better, anyway - it will go search for the original file
 801 and look for B<remote> inside the same directory. This does not apply to
 802 hard links, of course.
 803
 804
 805 =head1 DEPENDENCIES
 806
 807 All core modules, apart the following:
 808
 809 =over
 810
 811 =item B<< Archive::Tar >>
 812
 813 =item B<< File::Find::Rule >>
 814
 815 =back
 816
 817 =head1 BUGS AND LIMITATIONS
 818
 819 No bugs have been reported.
 820
 821 Please report any bugs or feature requests to the AUTHOR below.
 822
 823 Be sure to read L<CONFIGURATION AND ENVIRONMENT> for a slight limitation
 824 about the availability of the B<remote> script.
 825
 826 =head1 AUTHOR
 827
 828 Flavio Poletti C<flavio [AT] polettix.it>
 829
 830
 831 =head1 LICENSE AND COPYRIGHT
 832
 833 Copyright (c) 2008, Flavio Poletti C<flavio [AT] polettix.it>. All rights reserved.
 834
 835 This script is free software; you can redistribute it and/or
 836 modify it under the same terms as Perl itself. See L<perlartistic>
 837 and L<perlgpl>.
 838
 839 Questo script è software libero: potete ridistribuirlo e/o
 840 modificarlo negli stessi termini di Perl stesso. Vedete anche
 841 L<perlartistic> e L<perlgpl>.
 842
 843
 844 =head1 DISCLAIMER OF WARRANTY
 845
 846 BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
 847 FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
 848 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
 849 PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
 850 EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 851 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
 852 ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
 853 YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
 854 NECESSARY SERVICING, REPAIR, OR CORRECTION.
 855
 856 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
 857 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
 858 REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE
 859 LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL,
 860 OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
 861 THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
 862 RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
 863 FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
 864 SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
 865 SUCH DAMAGES.
 866
 867 =head1 NEGAZIONE DELLA GARANZIA
 868
 869 Poiché questo software viene dato con una licenza gratuita, non
 870 c'è alcuna garanzia associata ad esso, ai fini e per quanto permesso
 871 dalle leggi applicabili. A meno di quanto possa essere specificato
 872 altrove, il proprietario e detentore del copyright fornisce questo
 873 software "così com'è" senza garanzia di alcun tipo, sia essa espressa
 874 o implicita, includendo fra l'altro (senza però limitarsi a questo)
 875 eventuali garanzie implicite di commerciabilità e adeguatezza per
 876 uno scopo particolare. L'intero rischio riguardo alla qualità ed
 877 alle prestazioni di questo software rimane a voi. Se il software
 878 dovesse dimostrarsi difettoso, vi assumete tutte le responsabilità
 879 ed i costi per tutti i necessari servizi, riparazioni o correzioni.
 880
 881 In nessun caso, a meno che ciò non sia richiesto dalle leggi vigenti
 882 o sia regolato da un accordo scritto, alcuno dei detentori del diritto
 883 di copyright, o qualunque altra parte che possa modificare, o redistribuire
 884 questo software così come consentito dalla licenza di cui sopra, potrà
 885 essere considerato responsabile nei vostri confronti per danni, ivi
 886 inclusi danni generali, speciali, incidentali o conseguenziali, derivanti
 887 dall'utilizzo o dall'incapacità di utilizzo di questo software. Ciò
 888 include, a puro titolo di esempio e senza limitarsi ad essi, la perdita
 889 di dati, l'alterazione involontaria o indesiderata di dati, le perdite
 890 sostenute da voi o da terze parti o un fallimento del software ad
 891 operare con un qualsivoglia altro software. Tale negazione di garanzia
 892 rimane in essere anche se i dententori del copyright, o qualsiasi altra
 893 parte, è stata avvisata della possibilità di tali danneggiamenti.
 894
 895 Se decidete di utilizzare questo software, lo fate a vostro rischio
 896 e pericolo. Se pensate che i termini di questa negazione di garanzia
 897 non si confacciano alle vostre esigenze, o al vostro modo di
 898 considerare un software, o ancora al modo in cui avete sempre trattato
 899 software di terze parti, non usatelo. Se lo usate, accettate espressamente
 900 questa negazione di garanzia e la piena responsabilità per qualsiasi
 901 tipo di danno, di qualsiasi natura, possa derivarne.
 902
 903 =cut