--- /dev/null
+# Puppet Archive
+
+[](https://github.com/voxpupuli/puppet-archive/blob/master/LICENSE)
+[](https://travis-ci.org/voxpupuli/puppet-archive)
+[](https://coveralls.io/github/voxpupuli/puppet-archive)
+[](https://forge.puppetlabs.com/puppet/archive)
+[](https://forge.puppetlabs.com/puppet/archive)
+[](https://forge.puppetlabs.com/puppet/archive)
+[](https://forge.puppetlabs.com/puppet/archive)
+[](https://forge.puppet.com/camptocamp/archive)
+
+#### Table of Contents
+
+1. [Overview](#overview)
+2. [Module Description](#module-description)
+3. [Setup](#setup)
+4. [Usage](#usage)
+ * [Example](#usage-example)
+ * [Puppet URL](#puppet-url)
+ * [File permission](#file-permission)
+ * [Network files](#network-files)
+ * [Extract customization](#extract-customization)
+ * [S3 Bucket](#s3-bucket)
+ * [Migrating from puppet-staging](#migrating-from-puppet-staging)
+5. [Reference](#reference)
+6. [Development](#development)
+
+## Overview
+
+This module manages download, deployment, and cleanup of archive files.
+
+## Module Description
+
+This module uses types and providers to download and manage compress files,
+with optional lifecycle functionality such as checksum, extraction, and
+cleanup. The benefits over existing modules such as
+[puppet-staging](https://github.com/voxpupuli/puppet-staging):
+
+* Implemented via types and provider instead of exec resource.
+* Follows 302 redirect and propagate download failure.
+* Optional checksum verification of archive files.
+* Automatic dependency to parent directory.
+* Support Windows file extraction via 7zip or PowerShell (Zip file only).
+* Able to cleanup archive files after extraction.
+
+This module is compatible with [camptocamp/archive](https://forge.puppet.com/camptocamp/archive).
+For this it provides compatibility shims.
+
+## Setup
+
+On Windows 7zip is required to extract all archives except zip files which will
+be extracted with PowerShell if 7zip is not available (requires
+`System.IO.Compression.FileSystem`/Windows 2012+). Windows clients can install
+7zip via `include '::archive'`. On posix systems, curl is the default provider.
+The default provider can be overwritten by configuring resource defaults in
+site.pp:
+
+```puppet
+Archive {
+ provider => 'ruby',
+}
+```
+
+Users of the module is responsbile for archive package dependencies for
+alternative providers and all extraction utilities such as tar, gunzip, bunzip:
+
+```puppet
+if $::facts['osfamily'] != 'windows' {
+ package { 'wget':
+ ensure => present,
+ }
+
+ package { 'bunzip':
+ ensure => present,
+ }
+
+ Archive {
+ provider => 'wget',
+ require => Package['wget', 'bunzip'],
+ }
+}
+```
+
+## Usage
+
+Archive module dependency is managed by the archive class. This is only
+required for windows platform. By default 7zip is installed via chocolatey, but
+can be adjusted to use the msi package instead:
+
+```puppet
+class { 'archive':
+ seven_zip_name => '7-Zip 9.20 (x64 edition)',
+ seven_zip_source => 'C:/Windows/Temp/7z920-x64.msi',
+ seven_zip_provider => 'windows',
+}
+```
+
+### Usage Example
+
+```puppet
+include '::archive' # NOTE: optional for posix platforms
+
+archive { '/tmp/jta-1.1.jar':
+ ensure => present,
+ extract => true,
+ extract_path => '/tmp',
+ source => 'http://central.maven.org/maven2/javax/transaction/jta/1.1/jta-1.1.jar',
+ checksum => '2ca09f0b36ca7d71b762e14ea2ff09d5eac57558',
+ checksum_type => 'sha1',
+ creates => '/tmp/javax',
+ cleanup => true,
+}
+
+archive { '/tmp/test100k.db':
+ source => 'ftp://ftp.otenet.gr/test100k.db',
+ username => 'speedtest',
+ password => 'speedtest',
+}
+```
+
+If you want to extract a `.tar.gz` file:
+
+```puppet
+$install_path = '/opt/wso2'
+$package_name = 'wso2esb'
+$package_ensure = '4.9.0'
+$repository_url = 'http://company.com/repository/wso2'
+$archive_name = "${package_name}-${package_ensure}.tgz"
+$wso2_package_source = "${repository_url}/${archive_name}"
+
+archive { $archive_name:
+ path => "/tmp/${archive_name}",
+ source => $wso2_package_source,
+ extract => true,
+ extract_path => $install_path,
+ creates => "${install_path}/${package_name}-${package_ensure}",
+ cleanup => true,
+ require => File['wso2_appdir'],
+}
+```
+
+### Puppet URL
+
+Since march 2017, the Archive type also supports puppet URLs. Here is an example
+of how to use this:
+
+```puppet
+
+archive { '/home/myuser/help':
+ source => 'puppet:///modules/profile/help.tar.gz',
+ extract => true,
+ extract_path => $homedir,
+ creates => "${homedir}/help" #directory inside tgz
+}
+```
+
+### File permission
+
+When extracting files as non-root user, either ensure the target directory
+exists with the appropriate permission (see [tomcat.pp](tests/tomcat.pp) for
+full working example):
+
+```puppet
+$dirname = 'apache-tomcat-9.0.0.M3'
+$filename = "${dirname}.zip"
+$install_path = "/opt/${dirname}"
+
+file { $install_path:
+ ensure => directory,
+ owner => 'tomcat',
+ group => 'tomcat',
+ mode => '0755',
+}
+
+archive { $filename:
+ path => "/tmp/${filename}",
+ source => 'http://www-eu.apache.org/dist/tomcat/tomcat-9/v9.0.0.M3/bin/apache-tomcat-9.0.0.M3.zip',
+ checksum => 'f2aaf16f5e421b97513c502c03c117fab6569076',
+ checksum_type => 'sha1',
+ extract => true,
+ extract_path => '/opt',
+ creates => "${install_path}/bin",
+ cleanup => true,
+ user => 'tomcat',
+ group => 'tomcat',
+ require => File[$install_path],
+}
+```
+
+or use an subscribing exec to chmod the directory afterwards:
+
+```puppet
+$dirname = 'apache-tomcat-9.0.0.M3'
+$filename = "${dirname}.zip"
+$install_path = "/opt/${dirname}"
+
+file { '/opt/tomcat':
+ ensure => 'link',
+ target => $install_path
+}
+
+archive { $filename:
+ path => "/tmp/${filename}",
+ source => "http://www-eu.apache.org/dist/tomcat/tomcat-9/v9.0.0.M3/bin/apache-tomcat-9.0.0.M3.zip",
+ checksum => 'f2aaf16f5e421b97513c502c03c117fab6569076',
+ checksum_type => 'sha1',
+ extract => true,
+ extract_path => '/opt',
+ creates => $install_path,
+ cleanup => 'true',
+ require => File[$install_path],
+}
+
+exec { 'tomcat permission':
+ command => "chown tomcat:tomcat $install_path",
+ path => $::path,
+ subscribe => Archive[$filename],
+}
+```
+
+### Network files
+
+For large binary files that needs to be extracted locally, instead of copying
+the file from the network fileshare, simply set the file path to be the same as
+the source and archive will use the network file location:
+
+```puppet
+archive { '/nfs/repo/software.zip':
+ source => '/nfs/repo/software.zip'
+ extract => true,
+ extract_path => '/opt',
+ checksum_type => 'none', # typically unecessary
+ cleanup => false, # keep the file on the server
+}
+```
+
+### Extract Customization
+
+The `extract_flags` or `extract_command` parameters can be used to override the
+default extraction command/flag (defaults are specified in
+[achive.rb](lib/puppet_x/bodeco/archive.rb)).
+
+```puppet
+# tar striping directories:
+archive { '/var/lib/kafka/kafka_2.10-0.8.2.1.tgz':
+ ensure => present,
+ extract => true,
+ extract_command => 'tar xfz %s --strip-components=1',
+ extract_path => '/opt/kafka_2.10-0.8.2.1',
+ cleanup => true,
+ creates => '/opt/kafka_2.10-0.8.2.1/config',
+}
+
+# zip freshen existing files (zip -of %s instead of zip -o %s):
+archive { '/var/lib/example.zip':
+ extract => true,
+ extract_path => '/opt',
+ extract_flags => '-of',
+ cleanup => true,
+ subscribe => ...,
+}
+```
+
+### S3 bucket
+
+S3 support is implemented via the [AWS
+CLI](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html).
+By default this dependency is only installed for Linux VMs running on AWS, or
+enabled via `aws_cli_install` option:
+
+```puppet
+class { '::archive':
+ aws_cli_install => true,
+}
+
+# See AWS cli guide for credential and configuration settings:
+# http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html
+file { '/root/.aws/credentials':
+ ensure => file,
+ ...
+}
+file { '/root/.aws/config':
+ ensure => file,
+ ...
+}
+
+archive { '/tmp/gravatar.png':
+ ensure => present,
+ source => 's3://bodecoio/gravatar.png',
+}
+```
+
+NOTE: Alternative s3 provider support can be implemented by overriding the
+[s3_download method](lib/puppet/provider/archive/ruby.rb):
+
+### Download customizations
+
+In some cases you may need custom flags for curl/wget/s3 which can be
+supplied via `download_options`. Since this parameter is provider specific,
+beware of the order of defaults:
+
+* s3:// files accepts aws cli options
+ ```puppet
+ archive { '/tmp/gravatar.png':
+ ensure => present,
+ source => 's3://bodecoio/gravatar.png',
+ download_options => ['--region', 'eu-central-1'],
+ }
+ ```
+* puppet `provider` override:
+ ```puppet
+ archive { '/tmp/jta-1.1.jar':
+ ensure => present,
+ source => 'http://central.maven.org/maven2/javax/transaction/jta/1.1/jta-1.1.jar',
+ provider => 'wget',
+ download_options => '--continue',
+ }
+ ```
+* Linux default provider is `curl`, and Windows default is `ruby` (no effect).
+
+This option can also be applied globally to address issues for specific OS:
+```puppet
+if $::facts['osfamily'] != 'RedHat' {
+ Archive {
+ download_options => '--tlsv1',
+ }
+}
+```
+
+### Migrating from puppet-staging
+
+It is recommended to use puppet-archive instead of puppet-staging.
+Users wishing to migrate may find the following examples useful.
+
+#### Simple example without extraction
+
+##### puppet-staging
+
+```puppet
+class { 'staging':
+ path => '/tmp/staging',
+}
+
+staging::file { 'master.zip':
+ source => 'https://github.com/voxpupuli/puppet-archive/archive/master.zip',
+}
+```
+
+##### puppet-archive
+
+```puppet
+archive { '/tmp/staging/master.zip':
+ source => 'https://github.com/voxpupuli/puppet-archive/archive/master.zip',
+}
+```
+
+#### Example with zip file extraction
+
+##### puppet-staging
+
+```puppet
+class { 'staging':
+ path => '/tmp/staging',
+}
+
+staging::file { 'master.zip':
+ source => 'https://github.com/voxpupuli/puppet-archive/archive/master.zip',
+} ->
+staging::extract { 'master.zip':
+ target => '/tmp/staging/master.zip',
+ creates => '/tmp/staging/puppet-archive-master',
+}
+```
+
+##### puppet-archive
+
+```puppet
+archive { '/tmp/staging/master.zip':
+ source => 'https://github.com/voxpupuli/puppet-archive/archive/master.zip',
+ extract => true,
+ extract_path => '/tmp/staging',
+ creates => '/tmp/staging/puppet-archive-master',
+ cleanup => false,
+}
+```
+
+## Reference
+
+### Classes
+
+* `archive`: install 7zip package (Windows only) and aws cli for s3 support.
+* `archive::staging`: install package dependencies and creates staging directory
+ for backwards compatibility. Use the archive class instead if you do not need
+ the staging directory.
+
+### Define Resources
+
+* `archive::artifactory`: archive wrapper for [JFrog Artifactory](http://www.jfrog.com/open-source/#os-arti)
+ files with checksum.
+* `archive::go`: archive wrapper for [GO Continuous Delivery](http://www.go.cd/)
+ files with checksum.
+* `archive::nexus`: archive wrapper for [Sonatype Nexus](http://www.sonatype.org/nexus/)
+ files with checksum.
+* `archive::download`: archive wrapper and compatibility shim for [camptocamp/archive](https://forge.puppet.com/camptocamp/archive).
+ This is considered private API, as it has to change with camptocamp/archive.
+ For this reason it will remain undocumented, and removed when no longer needed
+ . We suggest not using it directly. Instead please consider migrating to
+ archive itself where possible.
+
+### Resources
+
+#### Archive
+
+* `ensure`: whether archive file should be present/absent (default: present)
+* `path`: namevar, archive file fully qualified file path.
+* `filename`: archive file name (derived from path).
+* `source`: archive file source, supports http|https|ftp|file|s3 uri.
+* `username`: username to download source file.
+* `password`: password to download source file.
+* `allow_insecure`: Ignore HTTPS certificate errors (true|false). (default: false)
+* `cookie`: archive file download cookie.
+* `checksum_type`: archive file checksum type (none|md5|sha1|sha2|sha256|sha384|
+ sha512). (default: none)
+* `checksum`: archive file checksum (match checksum_type)
+* `checksum_url`: archive file checksum source (instead of specify checksum)
+* `checksum_verify`: whether checksum will be verified (true|false). (default: true)
+* `extract`: whether archive will be extracted after download (true|false).
+ (default: false)
+* `extract_path`: target folder path to extract archive.
+* `extract_command`: custom extraction command ('tar xvf example.tar.gz'), also
+* `temp_dir`: specify an alternative temporary directory to use for file downloads, if unset the OS default is used
+ support sprintf format ('tar xvf %s') which will be processed with the
+ filename: sprintf('tar xvf %s', filename)
+* `extract_flags`: custom extraction options, this replaces the default flags.
+ A string such as 'xvf' for a tar file would replace the default xf flag. A
+ hash is useful when custom flags are needed for different platforms. {'tar'
+ => 'xzf', '7z' => 'x -aot'}.
+* `user`: extract command user (using this option will configure the archive
+ file permission to 0644 so the user can read the file).
+* `group`: extract command group (using this option will configure the archive
+ file permission to 0644 so the user can read the file).
+* `cleanup`: whether archive file will be removed after extraction (true|false).
+ (default: true)
+* `creates`: if file/directory exists, will not download/extract archive.
+* `proxy_server`: specify a proxy server, with port number if needed. ie:
+ `https://example.com:8080`.
+* `proxy_type`: proxy server type (none|http|https|ftp)
+
+#### Archive::Artifactory
+
+* `path`: fully qualified filepath for the download the file or use
+ archive_path and only supply filename. (namevar).
+* `ensure`: ensure the file is present/absent.
+* `url`: artifactory download url filepath. NOTE: replaces server, port,
+ url_path parameters.
+* `server`: artifactory server name (deprecated).
+* `port`: artifactory server port (deprecated).
+* `url_path`: artifactory file path
+ `http:://{server}:{port}/artifactory/{url_path}` (deprecated).
+* `owner`: file owner (see archive params for defaults).
+* `group`: file group (see archive params for defaults).
+* `mode`: file mode (see archive params for defaults).
+* `archive_path`: the parent directory of local filepath.
+* `extract`: whether to extract the files (true/false).
+* `creates`: the file created when the archive is extracted (true/false).
+* `cleanup`: remove archive file after file extraction (true/false).
+
+#### Archive::Artifactory Example
+
+```puppet
+$dirname = 'gradle-1.0-milestone-4-20110723151213+0300'
+$filename = "${dirname}-bin.zip"
+
+archive::artifactory { $filename:
+ archive_path => '/tmp',
+ url => "http://repo.jfrog.org/artifactory/distributions/org/gradle/${filename}",
+ extract => true,
+ extract_path => '/opt',
+ creates => "/opt/${dirname}",
+ cleanup => true,
+}
+
+file { '/opt/gradle':
+ ensure => link,
+ target => "/opt/${dirname}",
+}
+```
+
+#### Archive::Nexus
+
+#### Archive::Nexus Example
+
+```puppet
+archive::nexus { '/tmp/jtstand-ui-0.98.jar':
+ url => 'https://oss.sonatype.org',
+ gav => 'org.codehaus.jtstand:jtstand-ui:0.98',
+ repository => 'codehaus-releases',
+ packaging => 'jar',
+ extract => false,
+}
+```
+
+## Development
+
+We highly welcome new contributions to this module, especially those that
+include documentation, and rspec tests ;) but will happily guide you through
+the process, so, yes, please submit that pull request!
+
+Note: If you are writing a dependent module that include specs in it, you will
+need to set the puppetversion fact in your puppet-rspec tests. You can do that
+by adding it to the default facts of your spec/spec_helper.rb:
+
+```ruby
+RSpec.configure do |c|
+ c.default_facts = { :puppetversion => Puppet.version }
+end
+```
projects / mirror / dsa-puppet.git / blobdiff