3rdparty/modules/archive/README.md

   1 # Puppet Archive
   2
   3 [![License](https://img.shields.io/github/license/voxpupuli/puppet-archive.svg)](https://github.com/voxpupuli/puppet-archive/blob/master/LICENSE)
   4 [![Build Status](https://travis-ci.org/voxpupuli/puppet-archive.png?branch=master)](https://travis-ci.org/voxpupuli/puppet-archive)
   5 [![Code Coverage](https://coveralls.io/repos/github/voxpupuli/puppet-archive/badge.svg?branch=master)](https://coveralls.io/github/voxpupuli/puppet-archive)
   6 [![Puppet Forge](https://img.shields.io/puppetforge/v/puppet/archive.svg)](https://forge.puppetlabs.com/puppet/archive)
   7 [![Puppet Forge - downloads](https://img.shields.io/puppetforge/dt/puppet/archive.svg)](https://forge.puppetlabs.com/puppet/archive)
   8 [![Puppet Forge - endorsement](https://img.shields.io/puppetforge/e/puppet/archive.svg)](https://forge.puppetlabs.com/puppet/archive)
   9 [![Puppet Forge - scores](https://img.shields.io/puppetforge/f/puppet/archive.svg)](https://forge.puppetlabs.com/puppet/archive)
  10 [![Camptocamp compatible](https://img.shields.io/badge/camptocamp-compatible-orange.svg)](https://forge.puppet.com/camptocamp/archive)
  11
  12 #### Table of Contents
  13
  14 1. [Overview](#overview)
  15 2. [Module Description](#module-description)
  16 3. [Setup](#setup)
  17 4. [Usage](#usage)
  18    * [Example](#usage-example)
  19    * [Puppet URL](#puppet-url)
  20    * [File permission](#file-permission)
  21    * [Network files](#network-files)
  22    * [Extract customization](#extract-customization)
  23    * [S3 Bucket](#s3-bucket)
  24    * [Migrating from puppet-staging](#migrating-from-puppet-staging)
  25 5. [Reference](#reference)
  26 6. [Development](#development)
  27
  28 ## Overview
  29
  30 This module manages download, deployment, and cleanup of archive files.
  31
  32 ## Module Description
  33
  34 This module uses types and providers to download and manage compress files,
  35 with optional lifecycle functionality such as checksum, extraction, and
  36 cleanup. The benefits over existing modules such as
  37 [puppet-staging](https://github.com/voxpupuli/puppet-staging):
  38
  39 * Implemented via types and provider instead of exec resource.
  40 * Follows 302 redirect and propagate download failure.
  41 * Optional checksum verification of archive files.
  42 * Automatic dependency to parent directory.
  43 * Support Windows file extraction via 7zip or PowerShell (Zip file only).
  44 * Able to cleanup archive files after extraction.
  45
  46 This module is compatible with [camptocamp/archive](https://forge.puppet.com/camptocamp/archive).
  47 For this it provides compatibility shims.
  48
  49 ## Setup
  50
  51 On Windows 7zip is required to extract all archives except zip files which will
  52 be extracted with PowerShell if 7zip is not available (requires
  53 `System.IO.Compression.FileSystem`/Windows 2012+). Windows clients can install
  54 7zip via `include '::archive'`. On posix systems, curl is the default provider.
  55 The default provider can be overwritten by configuring resource defaults in
  56 site.pp:
  57
  58 ```puppet
  59 Archive {
  60   provider => 'ruby',
  61 }
  62 ```
  63
  64 Users of the module is responsbile for archive package dependencies for
  65 alternative providers and all extraction utilities such as tar, gunzip, bunzip:
  66
  67 ```puppet
  68 if $::facts['osfamily'] != 'windows' {
  69   package { 'wget':
  70     ensure => present,
  71   }
  72
  73   package { 'bunzip':
  74     ensure => present,
  75   }
  76
  77   Archive {
  78     provider => 'wget',
  79     require  => Package['wget', 'bunzip'],
  80   }
  81 }
  82 ```
  83
  84 ## Usage
  85
  86 Archive module dependency is managed by the archive class. This is only
  87 required for windows platform. By default 7zip is installed via chocolatey, but
  88 can be adjusted to use the msi package instead:
  89
  90 ```puppet
  91 class { 'archive':
  92   seven_zip_name     => '7-Zip 9.20 (x64 edition)',
  93   seven_zip_source   => 'C:/Windows/Temp/7z920-x64.msi',
  94   seven_zip_provider => 'windows',
  95 }
  96 ```
  97
  98 ### Usage Example
  99
 100 ```puppet
 101 include '::archive' # NOTE: optional for posix platforms
 102
 103 archive { '/tmp/jta-1.1.jar':
 104   ensure        => present,
 105   extract       => true,
 106   extract_path  => '/tmp',
 107   source        => 'http://central.maven.org/maven2/javax/transaction/jta/1.1/jta-1.1.jar',
 108   checksum      => '2ca09f0b36ca7d71b762e14ea2ff09d5eac57558',
 109   checksum_type => 'sha1',
 110   creates       => '/tmp/javax',
 111   cleanup       => true,
 112 }
 113
 114 archive { '/tmp/test100k.db':
 115   source   => 'ftp://ftp.otenet.gr/test100k.db',
 116   username => 'speedtest',
 117   password => 'speedtest',
 118 }
 119 ```
 120
 121 If you want to extract a `.tar.gz` file:
 122
 123 ```puppet
 124 $install_path        = '/opt/wso2'
 125 $package_name        = 'wso2esb'
 126 $package_ensure      = '4.9.0'
 127 $repository_url      = 'http://company.com/repository/wso2'
 128 $archive_name        = "${package_name}-${package_ensure}.tgz"
 129 $wso2_package_source = "${repository_url}/${archive_name}"
 130
 131 archive { $archive_name:
 132   path         => "/tmp/${archive_name}",
 133   source       => $wso2_package_source,
 134   extract      => true,
 135   extract_path => $install_path,
 136   creates      => "${install_path}/${package_name}-${package_ensure}",
 137   cleanup      => true,
 138   require      => File['wso2_appdir'],
 139 }
 140 ```
 141
 142 ### Puppet URL
 143
 144 Since march 2017, the Archive type also supports puppet URLs. Here is an example
 145 of how to use this:
 146
 147 ```puppet
 148
 149 archive { '/home/myuser/help':
 150   source        => 'puppet:///modules/profile/help.tar.gz',
 151   extract       => true,
 152   extract_path  => $homedir,
 153   creates       => "${homedir}/help" #directory inside tgz
 154 }
 155 ```
 156
 157 ### File permission
 158
 159 When extracting files as non-root user, either ensure the target directory
 160 exists with the appropriate permission (see [tomcat.pp](tests/tomcat.pp) for
 161 full working example):
 162
 163 ```puppet
 164 $dirname = 'apache-tomcat-9.0.0.M3'
 165 $filename = "${dirname}.zip"
 166 $install_path = "/opt/${dirname}"
 167
 168 file { $install_path:
 169   ensure => directory,
 170   owner  => 'tomcat',
 171   group  => 'tomcat',
 172   mode   => '0755',
 173 }
 174
 175 archive { $filename:
 176   path          => "/tmp/${filename}",
 177   source        => 'http://www-eu.apache.org/dist/tomcat/tomcat-9/v9.0.0.M3/bin/apache-tomcat-9.0.0.M3.zip',
 178   checksum      => 'f2aaf16f5e421b97513c502c03c117fab6569076',
 179   checksum_type => 'sha1',
 180   extract       => true,
 181   extract_path  => '/opt',
 182   creates       => "${install_path}/bin",
 183   cleanup       => true,
 184   user          => 'tomcat',
 185   group         => 'tomcat',
 186   require       => File[$install_path],
 187 }
 188 ```
 189
 190 or use an subscribing exec to chmod the directory afterwards:
 191
 192 ```puppet
 193 $dirname = 'apache-tomcat-9.0.0.M3'
 194 $filename = "${dirname}.zip"
 195 $install_path = "/opt/${dirname}"
 196
 197 file { '/opt/tomcat':
 198   ensure => 'link',
 199   target => $install_path
 200 }
 201
 202 archive { $filename:
 203   path          => "/tmp/${filename}",
 204   source        => "http://www-eu.apache.org/dist/tomcat/tomcat-9/v9.0.0.M3/bin/apache-tomcat-9.0.0.M3.zip",
 205   checksum      => 'f2aaf16f5e421b97513c502c03c117fab6569076',
 206   checksum_type => 'sha1',
 207   extract       => true,
 208   extract_path  => '/opt',
 209   creates       => $install_path,
 210   cleanup       => 'true',
 211   require       => File[$install_path],
 212 }
 213
 214 exec { 'tomcat permission':
 215   command   => "chown tomcat:tomcat $install_path",
 216   path      => $::path,
 217   subscribe => Archive[$filename],
 218 }
 219 ```
 220
 221 ### Network files
 222
 223 For large binary files that needs to be extracted locally, instead of copying
 224 the file from the network fileshare, simply set the file path to be the same as
 225 the source and archive will use the network file location:
 226
 227 ```puppet
 228 archive { '/nfs/repo/software.zip':
 229   source        => '/nfs/repo/software.zip'
 230   extract       => true,
 231   extract_path  => '/opt',
 232   checksum_type => 'none', # typically unecessary
 233   cleanup       => false,  # keep the file on the server
 234 }
 235 ```
 236
 237 ### Extract Customization
 238
 239 The `extract_flags` or `extract_command` parameters can be used to override the
 240 default extraction command/flag (defaults are specified in
 241 [achive.rb](lib/puppet_x/bodeco/archive.rb)).
 242
 243 ```puppet
 244 # tar striping directories:
 245 archive { '/var/lib/kafka/kafka_2.10-0.8.2.1.tgz':
 246   ensure          => present,
 247   extract         => true,
 248   extract_command => 'tar xfz %s --strip-components=1',
 249   extract_path    => '/opt/kafka_2.10-0.8.2.1',
 250   cleanup         => true,
 251   creates         => '/opt/kafka_2.10-0.8.2.1/config',
 252 }
 253
 254 # zip freshen existing files (zip -of %s instead of zip -o %s):
 255 archive { '/var/lib/example.zip':
 256   extract       => true,
 257   extract_path  => '/opt',
 258   extract_flags => '-of',
 259   cleanup       => true,
 260   subscribe     => ...,
 261 }
 262 ```
 263
 264 ### S3 bucket
 265
 266 S3 support is implemented via the [AWS
 267 CLI](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html).
 268 By default this dependency is only installed for Linux VMs running on AWS, or
 269 enabled via `aws_cli_install` option:
 270
 271 ```puppet
 272 class { '::archive':
 273   aws_cli_install => true,
 274 }
 275
 276 # See AWS cli guide for credential and configuration settings:
 277 # http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html
 278 file { '/root/.aws/credentials':
 279   ensure => file,
 280   ...
 281 }
 282 file { '/root/.aws/config':
 283   ensure => file,
 284   ...
 285 }
 286
 287 archive { '/tmp/gravatar.png':
 288   ensure => present,
 289   source => 's3://bodecoio/gravatar.png',
 290 }
 291 ```
 292
 293 NOTE: Alternative s3 provider support can be implemented by overriding the
 294 [s3_download method](lib/puppet/provider/archive/ruby.rb):
 295
 296 ### Download customizations
 297
 298 In some cases you may need custom flags for curl/wget/s3 which can be
 299 supplied via `download_options`. Since this parameter is provider specific,
 300 beware of the order of defaults:
 301
 302 * s3:// files accepts aws cli options
 303   ```puppet
 304   archive { '/tmp/gravatar.png':
 305     ensure           => present,
 306     source           => 's3://bodecoio/gravatar.png',
 307     download_options => ['--region', 'eu-central-1'],
 308   }
 309   ```
 310 * puppet `provider` override:
 311   ```puppet
 312   archive { '/tmp/jta-1.1.jar':
 313     ensure           => present,
 314     source           => 'http://central.maven.org/maven2/javax/transaction/jta/1.1/jta-1.1.jar',
 315     provider         => 'wget',
 316     download_options => '--continue',
 317   }
 318   ```
 319 * Linux default provider is `curl`, and Windows default is `ruby` (no effect).
 320
 321 This option can also be applied globally to address issues for specific OS:
 322 ```puppet
 323 if $::facts['osfamily'] != 'RedHat' {
 324   Archive {
 325     download_options => '--tlsv1',
 326   }
 327 }
 328 ```
 329
 330 ### Migrating from puppet-staging
 331
 332 It is recommended to use puppet-archive instead of puppet-staging.
 333 Users wishing to migrate may find the following examples useful.
 334
 335 #### Simple example without extraction
 336
 337 ##### puppet-staging
 338
 339 ```puppet
 340 class { 'staging':
 341   path  => '/tmp/staging',
 342 }
 343
 344 staging::file { 'master.zip':
 345   source => 'https://github.com/voxpupuli/puppet-archive/archive/master.zip',
 346 }
 347 ```
 348
 349 ##### puppet-archive
 350
 351 ```puppet
 352 archive { '/tmp/staging/master.zip':
 353   source => 'https://github.com/voxpupuli/puppet-archive/archive/master.zip',
 354 }
 355 ```
 356
 357 #### Example with zip file extraction
 358
 359 ##### puppet-staging
 360
 361 ```puppet
 362 class { 'staging':
 363   path  => '/tmp/staging',
 364 }
 365
 366 staging::file { 'master.zip':
 367   source  => 'https://github.com/voxpupuli/puppet-archive/archive/master.zip',
 368 } ->
 369 staging::extract { 'master.zip':
 370   target  => '/tmp/staging/master.zip',
 371   creates => '/tmp/staging/puppet-archive-master',
 372 }
 373 ```
 374
 375 ##### puppet-archive
 376
 377 ```puppet
 378 archive { '/tmp/staging/master.zip':
 379   source       => 'https://github.com/voxpupuli/puppet-archive/archive/master.zip',
 380   extract      => true,
 381   extract_path => '/tmp/staging',
 382   creates      => '/tmp/staging/puppet-archive-master',
 383   cleanup      => false,
 384 }
 385 ```
 386
 387 ## Reference
 388
 389 ### Classes
 390
 391 * `archive`: install 7zip package (Windows only) and aws cli for s3 support.
 392 * `archive::staging`: install package dependencies and creates staging directory
 393   for backwards compatibility. Use the archive class instead if you do not need
 394   the staging directory.
 395
 396 ### Define Resources
 397
 398 * `archive::artifactory`: archive wrapper for [JFrog Artifactory](http://www.jfrog.com/open-source/#os-arti)
 399   files with checksum.
 400 * `archive::go`: archive wrapper for [GO Continuous Delivery](http://www.go.cd/)
 401   files with checksum.
 402 * `archive::nexus`: archive wrapper for [Sonatype Nexus](http://www.sonatype.org/nexus/)
 403   files with checksum.
 404 * `archive::download`: archive wrapper and compatibility shim for [camptocamp/archive](https://forge.puppet.com/camptocamp/archive).
 405   This is considered private API, as it has to change with camptocamp/archive.
 406   For this reason it will remain undocumented, and removed when no longer needed
 407   . We suggest not using it directly. Instead please consider migrating to
 408   archive itself where possible.
 409
 410 ### Resources
 411
 412 #### Archive
 413
 414 * `ensure`: whether archive file should be present/absent (default: present)
 415 * `path`: namevar, archive file fully qualified file path.
 416 * `filename`: archive file name (derived from path).
 417 * `source`: archive file source, supports http|https|ftp|file|s3 uri.
 418 * `username`: username to download source file.
 419 * `password`: password to download source file.
 420 * `allow_insecure`: Ignore HTTPS certificate errors (true|false). (default: false)
 421 * `cookie`: archive file download cookie.
 422 * `checksum_type`: archive file checksum type (none|md5|sha1|sha2|sha256|sha384|
 423   sha512). (default: none)
 424 * `checksum`: archive file checksum (match checksum_type)
 425 * `checksum_url`: archive file checksum source (instead of specify checksum)
 426 * `checksum_verify`: whether checksum will be verified (true|false). (default: true)
 427 * `extract`: whether archive will be extracted after download (true|false).
 428   (default: false)
 429 * `extract_path`: target folder path to extract archive.
 430 * `extract_command`: custom extraction command ('tar xvf example.tar.gz'), also
 431 * `temp_dir`: specify an alternative temporary directory to use for file downloads, if unset the OS default is used
 432   support sprintf format ('tar xvf %s') which will be processed with the
 433   filename: sprintf('tar xvf %s', filename)
 434 * `extract_flags`: custom extraction options, this replaces the default flags.
 435   A string such as 'xvf' for a tar file would replace the default xf flag. A
 436   hash is useful when custom flags are needed for different platforms. {'tar'
 437   => 'xzf', '7z' => 'x -aot'}.
 438 * `user`: extract command user (using this option will configure the archive
 439   file permission to 0644 so the user can read the file).
 440 * `group`: extract command group (using this option will configure the archive
 441   file permission to 0644 so the user can read the file).
 442 * `cleanup`: whether archive file will be removed after extraction (true|false).
 443   (default: true)
 444 * `creates`: if file/directory exists, will not download/extract archive.
 445 * `proxy_server`: specify a proxy server, with port number if needed. ie:
 446   `https://example.com:8080`.
 447 * `proxy_type`: proxy server type (none|http|https|ftp)
 448
 449 #### Archive::Artifactory
 450
 451 * `path`: fully qualified filepath for the download the file or use
 452   archive_path and only supply filename. (namevar).
 453 * `ensure`: ensure the file is present/absent.
 454 * `url`: artifactory download url filepath. NOTE: replaces server, port,
 455   url_path parameters.
 456 * `server`: artifactory server name (deprecated).
 457 * `port`: artifactory server port (deprecated).
 458 * `url_path`: artifactory file path
 459   `http:://{server}:{port}/artifactory/{url_path}` (deprecated).
 460 * `owner`: file owner (see archive params for defaults).
 461 * `group`: file group (see archive params for defaults).
 462 * `mode`: file mode (see archive params for defaults).
 463 * `archive_path`: the parent directory of local filepath.
 464 * `extract`: whether to extract the files (true/false).
 465 * `creates`: the file created when the archive is extracted (true/false).
 466 * `cleanup`: remove archive file after file extraction (true/false).
 467
 468 #### Archive::Artifactory Example
 469
 470 ```puppet
 471 $dirname = 'gradle-1.0-milestone-4-20110723151213+0300'
 472 $filename = "${dirname}-bin.zip"
 473
 474 archive::artifactory { $filename:
 475   archive_path => '/tmp',
 476   url          => "http://repo.jfrog.org/artifactory/distributions/org/gradle/${filename}",
 477   extract      => true,
 478   extract_path => '/opt',
 479   creates      => "/opt/${dirname}",
 480   cleanup      => true,
 481 }
 482
 483 file { '/opt/gradle':
 484   ensure => link,
 485   target => "/opt/${dirname}",
 486 }
 487 ```
 488
 489 #### Archive::Nexus
 490
 491 #### Archive::Nexus Example
 492
 493 ```puppet
 494 archive::nexus { '/tmp/jtstand-ui-0.98.jar':
 495   url        => 'https://oss.sonatype.org',
 496   gav        => 'org.codehaus.jtstand:jtstand-ui:0.98',
 497   repository => 'codehaus-releases',
 498   packaging  => 'jar',
 499   extract    => false,
 500 }
 501 ```
 502
 503 ## Development
 504
 505 We highly welcome new contributions to this module, especially those that
 506 include documentation, and rspec tests ;) but will happily guide you through
 507 the process, so, yes, please submit that pull request!
 508
 509 Note: If you are writing a dependent module that include specs in it, you will
 510 need to set the puppetversion fact in your puppet-rspec tests. You can do that
 511 by adding it to the default facts of your spec/spec_helper.rb:
 512
 513 ```ruby
 514 RSpec.configure do |c|
 515   c.default_facts = { :puppetversion => Puppet.version }
 516 end
 517 ```