Added support for a couple of options.
[deployable.git] / deployable
blobf2fd04b9ef6867cad63d168d2dc8dbe292853323
1 #!/usr/bin/env perl
2 use strict;
3 use warnings;
4 use Carp;
5 use version; our $VERSION = qv('0.0.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 POSIX qw( strftime );
13 use Cwd qw( realpath );
15 # Other recommended modules (uncomment to use):
16 # use IO::Prompt;
17 # use Readonly;
18 # use Data::Dumper;
20 # Integrated logging facility
21 # use Log::Log4perl qw( :easy );
22 # Log::Log4perl->easy_init($INFO);
24 my %config = (
25 output => '-',
26 remote => catfile(dirname(realpath(__FILE__)), 'remote'),
27 tarfile => [],
28 heredir => [],
29 rootdir => [],
30 root => [],
31 deploy => [],
33 GetOptions(
34 \%config, 'usage',
35 'help', 'man',
36 'version', 'output|o=s',
37 'deploy|exec|d=s@', 'workdir|work-directory|deploy-directory|w=s',
38 'cleanup|c!', 'tarfile|T=s@',
39 'heredir|H=s@', 'bundle|all-exec|X!',
40 'rootdir|R=s@', 'root|r=s@',
42 pod2usage(message => "$0 $VERSION", -verbose => 99, -sections => '')
43 if $config{version};
44 pod2usage(-verbose => 99, -sections => 'USAGE') if $config{usage};
45 pod2usage(-verbose => 99, -sections => 'USAGE|EXAMPLES|OPTIONS')
46 if $config{help};
47 pod2usage(-verbose => 2) if $config{man};
49 pod2usage(
50 message => 'working directory must be an absolute path',
51 -verbose => 99,
52 -sections => ''
54 if exists $config{workdir} && !file_name_is_absolute($config{workdir});
56 my $out_fh = \*STDOUT;
57 if ($config{output} ne '-') {
58 open my $fh, '>', $config{output} ## no critic
59 or croak "open('$config{output}'): $OS_ERROR";
60 $out_fh = $fh;
63 # Emit script code to be executed remotely. It is guaranteed to end
64 # with __END__, so that all what comes next is data
65 print {$out_fh} get_remote_script();
67 # Emit these configurations, if present
68 print {$out_fh} '#' x 72, "\n# General configurations\n\n";
69 for my $name (qw( workdir cleanup bundle )) {
70 print {$out_fh} confline($name, $config{$name}), "\n\n"
71 if exists $config{$name};
74 # Emit list of deploy scripts
75 print {$out_fh} confline('deploy@', $_), "\n\n"
76 for @{$config{deploy}};
78 # Time for tarfiles now
79 print {$out_fh} '#' x 72, "\n# List of files\n[files]\n\n";
81 # Process files and directories. All these will be reported in the
82 # extraction directory, i.e. basename() will be applied to them. For
83 # directories, they will be re-created
84 for my $file (@ARGV) {
85 croak "'$file' not readable" unless -r $file;
86 if (-d $file) {
87 print {*STDERR} "processing directory '$file'\n";
88 print {$out_fh} as_comment("directory $file, extracted into:"), "\n";
89 print {$out_fh} confline('directory', '.'), "\n";
90 save_directory('.', $file, $out_fh);
91 } ## end if (-d $file)
92 else {
93 print {*STDERR} "processing file '$file'\n";
94 my $mode = sprintf '0%lo', (stat $file)[2] & oct(7777);
95 print {$out_fh} as_comment('file saves both mode and filename'),
96 "\n";
97 print {$out_fh} confline('file', $mode . ' ' . basename($file)),
98 "\n";
99 save_file($file, $out_fh);
100 } ## end else [ if (-d $file)
101 } ## end for my $file (@ARGV)
103 # Tarfiles are files that will be extracted in the target directory
104 for my $tarfile (@{$config{tarfile}}) {
105 croak "'$tarfile' not readable" unless -r $tarfile;
106 print {*STDERR} "processing tarfile '$tarfile'\n";
107 print {$out_fh} as_comment('tarfile will also be extracted into .'),
108 "\n";
109 print {$out_fh} confline(tarfile => $tarfile), "\n";
110 save_file($tarfile, $out_fh);
111 } ## end for my $tarfile (@{$config...
113 # Heredirs are directories that are extracted directly into the ex dir
114 for my $heredir (@{$config{heredir}}) {
115 croak "'$heredir' not readable" unless -r $heredir;
116 print {*STDERR} "processing here-directory '$heredir'\n";
117 print {$out_fh}
118 as_comment("here-directory = $heredir, extracted into:"), "\n";
119 print {$out_fh} confline('directory', '.'), "\n";
120 save_directory($heredir, '.', $out_fh);
121 } ## end for my $heredir (@{$config...
123 for my $rootdir (@{$config{rootdir}}) {
124 croak "'$rootdir' not readable" unless -r $rootdir;
125 print {*STDERR} "processing root-directory '$rootdir'\n";
126 print {$out_fh}
127 as_comment("root-directory = $rootdir, extracted into:"), "\n";
128 print {$out_fh} confline('directory', '/'), "\n";
129 save_directory('.', $rootdir, $out_fh);
132 for my $root (@{$config{root}}) {
133 croak "'$root' not readable" unless -r $root;
134 print {*STDERR} "processing root-directory '$root'\n";
135 print {$out_fh}
136 as_comment("root-directory = $root, extracted into:"), "\n";
137 print {$out_fh} confline('directory', '/'), "\n";
138 save_directory($root, '.', $out_fh);
141 close $out_fh;
142 if ($config{output} ne '-') {
143 chmod oct(755), $config{output}
144 or carp "chmod(0755, '$config{output}'): $OS_ERROR";
147 sub save_directory {
148 my ($changedir, $filename, $out_fh) = @_;
150 ## no critic
151 open my $fh, '-|', '/bin/tar', 'czf', '-', '-b', '1', '-C', $changedir,
152 $filename,
153 or croak "open() for /bin/tar: $OS_ERROR";
155 return hexified_copy($fh, $out_fh);
156 } ## end sub save_directory
158 sub save_file {
159 my ($filename, $out_fh) = @_;
161 ## no critic
162 open my $fh, '<', $filename
163 or croak "open('$filename'): $OS_ERROR";
164 return hexified_copy($fh, $out_fh);
165 } ## end sub save_file
167 sub hexified_copy {
168 my ($in_fh, $out_fh) = @_;
169 binmode $in_fh;
170 while (read $in_fh, my $data, 32) {
171 print {$out_fh} unpack('H*', $data), "\n";
173 print {$out_fh} "\n";
174 return;
175 } ## end sub hexified_copy
177 sub as_comment { ## no critic
178 return join "\n", map { '# ' . $_ } map { split /\n/mxs } @_;
181 sub confline {
182 my ($name, $data) = @_;
183 my $comment = "$name = $data";
184 my $line = join ' = ', $name, unpack 'H*', $data;
185 return join "\n", as_comment("$name = $data"), $line;
186 } ## end sub confline
188 sub get_remote_script {
189 open my $fh, '<', $config{remote}
190 or croak "open('$config{remote}'): $OS_ERROR";
191 my @lines;
192 while (<$fh>) {
193 last if /\A __END__ \s*\z/mxs;
194 push @lines, $_;
196 close $fh;
197 return join '', @lines, "__END__\n";
198 } ## end sub get_remote_script
200 __END__
202 =head1 NAME
204 deployable - create a deploy script for some files/scripts
207 =head1 VERSION
209 See version at beginning of script, variable $VERSION, or call
211 shell$ deployable --version
214 =head1 USAGE
216 deployable [--usage] [--help] [--man] [--version]
218 deployable [--cleanup|-c] [--deploy|--exec-d <program>]
219 [--heredir|-H <dirname>] [--output|-o <filename>]
220 [--tarfile|-T <filename>] [--workdir|-w <path>]
221 [ files or directories... ]
224 =head1 EXAMPLES
226 shell$ deployable
228 # Create script.pl embedding distro.tar.gz. When executed, this
229 # tar file will be extracted, and script.sh will be executed.
230 shell$ deployable -o script.pl --exec script.sh -T distro.tar.gz
232 =head1 DESCRIPTION
234 This is a meta-script to create deploy scripts. The latter ones are
235 suitable to be distributed in order to deploy something.
237 You basically have to provide two things: files to install and programs
238 to be executed. Files can be put directly into the deployed script, or
239 can be included in gzipped tar archives.
241 When called, this script creates a deploy script for you. This script
242 includes all the specified files, and when executed it will extract
243 those files and execute the given programs. In this way, you can ship
244 both files and logic needed to correctly install those files, but this
245 is of course of of scope.
247 All files and archives will be extracted under a configured path
248 (see L<--workdir> below), which we'll call I<workdir> from now on. Under
249 the I<workdir> a temporary directory will be created, and the files
250 will be put in the temporary directory. You can specify if you want to
251 clean up this temporary directory or keep it, at your choice. (You're able
252 to both set a default for this cleanup when invoking deployable, or when
253 invoking the deploy script itself). The temporary directory will be
254 called I<tmpdir> in the following.
256 There are several ways to embed files to be shipped:
258 =over
260 =item *
262 specify the file name directly on the command line. A file given in this
263 way will always be extracted into the I<tmpdir>, whatever its initial path
264 was.
266 =item *
268 specify the name of a directory on the command line. In this case,
269 C<tar> will be used to archive the directory, with the usual option to
270 turn absolute paths into relative ones; this means that directories will
271 be re-created under I<tmpdir> when extraction is performed.
273 =item *
275 give the name of an already available gzipped C<tar> archive, using the
276 C<--tarfile|-T> option. This lets you have the maximum flexibility.
278 =item *
280 give the name of a directory to be used as a "here directory", using
281 the C<--heredir|-H> option. This is much the same as giving the directory
282 name (see above), but in this case C<tar> will be told to change into the
283 directory first, and archive '.'. This means that the contents of the
284 "here-directory" will be extracted directly into I<tmpdir>.
286 =back
288 =head2 Extended Example
290 Suppose you have a few server which have the same configuration, apart
291 from some specific stuff (e.g. the hostname, the IP addresses, etc.).
292 You'd like to perform changes to all with the minimum work possible...
293 so you know you should script something.
295 For example, suppose you want to update a few files in /etc, setting these
296 files equal for all hosts. You would typically do the following:
298 # In your computer
299 shell$ mkdir -p /tmp/newfiles/etc
300 shell$ cd /tmp/newfiles/etc
301 # Craft the new files
302 shell$ cd ..
303 shell$ tar cvzf newetc.tar.gz etc
305 # Now, for each server:
306 shell$ scp newetc.tar.gz $server:/tmp
307 shell$ ssh $server tar xvzf /tmp/newetc.tar.gz -C /
310 So far, so good. But what if you need to kick in a little more logic?
311 For example, if you update some configuration files, you'll most likey
312 want to restart some services. So you could do the following:
314 shell$ mkdir -p /tmp/newfiles/tmp
315 shell$ cd /tmp/newfiles/tmp
316 # craft a shell script to be executed remotely and set the exec bit
317 # Suppose it's called deploy.sh
318 shell$ cd ..
319 shell$ tar cvzf newetc.tar.gz etc tmp
321 # Now, for each server:
322 shell$ scp newetc.tar.gz $server:/tmp
323 shell$ ssh $server tar xvzf /tmp/newetc.tar.gz -C /
324 shell$ ssh $server /tmp/deploy.sh
326 And what if you want to install files depending on the particular machine?
327 Or you have a bundle of stuff to deploy and a bunch of scripts to execute?
328 You can use deployable. In this case, you can do the following:
330 shell$ mkdir -p /tmp/newfiles/etc
331 shell$ cd /tmp/newfiles/etc
332 # Craft the new files
333 shell$ cd ..
334 # craft a shell script to be executed remotely and set the exec bit
335 # Suppose it's called deploy.sh
336 shell$ deployable -o deploy.pl etc deploy.sh --exec deploy.sh
338 # Now, for each server
339 shell$ scp deploy.pl $server:/tmp
340 shell$ ssh $server /tmp/deploy.pl
342 And you're done. This can be particularly useful if you have another
343 layer of deployment, e.g. if you have to run a script to decide which
344 of a group of archives should be deployed. For example, you could craft
345 a different new "etc" for each server (which is particularly true if
346 network configurations are in the package), and produce a simple script
347 to choose which file to use based on the MAC address of the machine. In
348 this case you could have:
350 =over
352 =item newetc.*.tar.gz
354 a bunch of tar files with the configurations for each different server
356 =item newetc.list
358 a list file with the association between the MAC addresses and the
359 real tar file to deploy from the bunch in the previous bullet
361 =item deploy-the-right-stuff.sh
363 a script to get the real MAC address of the machine, select the right
364 tar file and do the deployment.
366 =back
368 So, you can do the following:
370 shell$ deployable -o deploy.pl newetc.*.tar.gz newetc.list \
371 deploy-the-right-stuff.sh --exec deploy-the-right-stuff.sh
373 # Now, for each server:
374 shell$ scp deploy.pl $server:/tmp
375 shell$ ssh $server /tmp/deploy.pl
377 So, once you have the deploy script on the target machine all you need
378 to do is to execute it. This can come handy when you cannot access the
379 machines from the network, but you have to go there physically: you
380 can prepare all in advance, and just call the deploy script.
383 =head1 OPTIONS
385 Meta-options:
387 =over
389 =item B<--help>
391 print a somewhat more verbose help, showing usage, this description of
392 the options and some examples from the synopsis.
394 =item B<--man>
396 print out the full documentation for the script.
398 =item B<--usage>
400 print a concise usage line and exit.
402 =item B<--version>
404 print the version of the script.
406 =back
408 Real-world options:
410 =over
412 =item B<< --cleanup | -c >>
414 Set cleanup flag in the produced script. If the cleanup flag is set, the
415 I<deploy script> will clean up after having performed all operations.
417 You can set this flag to C<0> by using C<--no-cleanup>.
419 =item B<< --deploy | --exec | -d <filename> >>
421 Set the name of a program to execute after extraction. You can provide
422 multiple program names, they will be executed in the same order.
424 =item B<< --heredir | -H <path> >>
426 Set the name of a "here directory" (see L<DESCRIPTION>). You can use this
427 option multiple times to provide multiple directories.
429 =item B<< --output | -o <filename> >>
431 Set the output file name. By default the I<deploy script> will be given
432 out on the standard output; if you provide a filename (different from
433 C<->, of course!) the script will be saved there and the permissions will
434 be set to 0755.
436 =item B<< --tarfile | -T <filename >>
438 Set the name of a B<tar> file, see L<DESCRIPTION>. You can use this option
439 multiple times to provide multiple B<tar> archives.
441 =item B<< --workdir | --deploy-directory | -w <path> >>
443 Set the working directory for the deploy.
445 =back
447 =head1 THE DEPLOY SCRIPT
449 The net result of calling this script is to produce another script,
450 that we call the I<deploy script>. This script is made of two parts: the
451 code, which is fixed, and the configurations/files, which is what is
452 actually produced. The latter part is put after the C<__END__> marker,
453 as usual.
455 Stuff in the configuration part is always hexified in order to prevent
456 strange tricks or errors. Comments will help you devise what's inside the
457 configurations themselves.
459 The I<deploy script> has options itself, even if they are quite minimal.
460 In particular, it supports the same options C<--workdir|-w> and
461 C<--cleanup> described above, allowing the final user to override the
462 configured values. By default, the I<workdir> is set to C</tmp/our-deploy>
463 and the script will clean up after itself.
465 The following options are supported in the I<deploy script>:
467 =over
469 =item B<--usage | --man | --help>
471 print a minimal help and exit
473 =item B<--version>
475 print script version and exit
477 =item B<--bundle | --all-exec | -X>
479 treat all executables in the main deployment directory as scripts
480 to be executed
482 =item B<--cleanup | --no-cleanup>
484 perform / don't perform temporary directory cleanup after work done
486 =item B<--dryrun | --dry-run>
488 print final options and exit
490 =item B<< --inspect <dirname> >>
492 just extract all the stuff into <dirname> for inspection. Implies
493 C<--no-deploy>, C<--no-tempdir>, ignores C<--bundle> (as a consequence of
494 C<--no-deploy>), disables C<--cleanup> and sets the working directory
495 to C<dirname>
497 =item B<--no-deploy>
499 prevent execution of deploy scripts (they are executed by default)
501 =item B<--no-workdir>
503 execute directly in workdir (see below), without creating the
504 temporary directory
506 =item B<--show | --show-options | -s>
508 print configured options and exit
510 =item B<--workdir | -w>
512 working base directory (a temporary subdirectory will be created
513 there anyway)
515 =back
517 Note the difference between C<--show> and C<--dryrun>: the former will
518 give you the options that are "embedded" in the I<deploy script> without
519 taking into account other options given on the command line, while the
520 latter will give you the final options that would be used if the script
521 were called without C<--dryrun>.
523 =head2 Deploy Script Example Usage
525 In the following, we'll assume that the I<deploy script> is called
526 C<deploy.pl>.
528 To execute the script with the already configured options, you just have
529 to call it:
531 shell$ ./deploy.pl
533 If you just want to see which configurations are in the I<deploy script>:
535 shell$ ./deploy.pl --show
537 Extract contents of the script in a temp directory and simply inspect
538 what's inside:
540 # extract stuff into subdirectory 'inspect' for... inspection
541 shell$ ./deploy.pl --no-tempdir --no-deploy --workdir inspect
543 =head2 Deploy Script Requirements
545 Care has been taken to make the requirements of the deploy script as low
546 as possible. The result is that you'll need a working Perl with version
547 at least 5.6.2, and GNU B<tar> with support for options C<--touch> and
548 C<--no-same-owner>. Good luck.
551 =head1 DIAGNOSTICS
553 Each error message should be enough explicit to be understood without the
554 need for furter explainations. Which is another way to say that I'm way
555 too lazy to list all possible ways that this script has to fail.
558 =head1 CONFIGURATION AND ENVIRONMENT
560 deployable requires no configuration files or environment variables.
562 Please note that deployable B<needs> to find its master B<remote> file
563 to produce the final script. This must be put in the same directory where
564 deployable is put. You should be able to B<symlink> deployable where you
565 think it's better, anyway - it will go search for the original file
566 and look for B<remote> inside the same directory. This does not apply to
567 hard links, of course.
570 =head1 DEPENDENCIES
572 All core modules, apart from L<version> which is nearly-core.
575 =head1 BUGS AND LIMITATIONS
577 No bugs have been reported.
579 Please report any bugs or feature requests to the AUTHOR below.
582 =head1 AUTHOR
584 Flavio Poletti C<flavio [AT] polettix.it>
587 =head1 LICENSE AND COPYRIGHT
589 Copyright (c) 2006, Flavio Poletti C<flavio [AT] polettix.it>. All rights reserved.
591 This script is free software; you can redistribute it and/or
592 modify it under the same terms as Perl itself. See L<perlartistic>
593 and L<perlgpl>.
595 Questo script è software libero: potete ridistribuirlo e/o
596 modificarlo negli stessi termini di Perl stesso. Vedete anche
597 L<perlartistic> e L<perlgpl>.
600 =head1 DISCLAIMER OF WARRANTY
602 BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
603 FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
604 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
605 PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
606 EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
607 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
608 ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
609 YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
610 NECESSARY SERVICING, REPAIR, OR CORRECTION.
612 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
613 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
614 REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE
615 LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL,
616 OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
617 THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
618 RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
619 FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
620 SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
621 SUCH DAMAGES.
623 =head1 NEGAZIONE DELLA GARANZIA
625 Poiché questo software viene dato con una licenza gratuita, non
626 c'è alcuna garanzia associata ad esso, ai fini e per quanto permesso
627 dalle leggi applicabili. A meno di quanto possa essere specificato
628 altrove, il proprietario e detentore del copyright fornisce questo
629 software "così com'è" senza garanzia di alcun tipo, sia essa espressa
630 o implicita, includendo fra l'altro (senza però limitarsi a questo)
631 eventuali garanzie implicite di commerciabilità e adeguatezza per
632 uno scopo particolare. L'intero rischio riguardo alla qualità ed
633 alle prestazioni di questo software rimane a voi. Se il software
634 dovesse dimostrarsi difettoso, vi assumete tutte le responsabilità
635 ed i costi per tutti i necessari servizi, riparazioni o correzioni.
637 In nessun caso, a meno che ciò non sia richiesto dalle leggi vigenti
638 o sia regolato da un accordo scritto, alcuno dei detentori del diritto
639 di copyright, o qualunque altra parte che possa modificare, o redistribuire
640 questo software così come consentito dalla licenza di cui sopra, potrà
641 essere considerato responsabile nei vostri confronti per danni, ivi
642 inclusi danni generali, speciali, incidentali o conseguenziali, derivanti
643 dall'utilizzo o dall'incapacità di utilizzo di questo software. Ciò
644 include, a puro titolo di esempio e senza limitarsi ad essi, la perdita
645 di dati, l'alterazione involontaria o indesiderata di dati, le perdite
646 sostenute da voi o da terze parti o un fallimento del software ad
647 operare con un qualsivoglia altro software. Tale negazione di garanzia
648 rimane in essere anche se i dententori del copyright, o qualsiasi altra
649 parte, è stata avvisata della possibilità di tali danneggiamenti.
651 Se decidete di utilizzare questo software, lo fate a vostro rischio
652 e pericolo. Se pensate che i termini di questa negazione di garanzia
653 non si confacciano alle vostre esigenze, o al vostro modo di
654 considerare un software, o ancora al modo in cui avete sempre trattato
655 software di terze parti, non usatelo. Se lo usate, accettate espressamente
656 questa negazione di garanzia e la piena responsabilità per qualsiasi
657 tipo di danno, di qualsiasi natura, possa derivarne.
659 =cut