archive
Version information
This version is compatible with:
- Puppet Enterprise 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x, 2018.1.x
- Puppet >= 5.5.8 < 7.0.0
- Archlinux, , , , , , , , , , ,
Start using this module
Add this module to your Puppetfile:
mod 'puppet-archive', '4.6.0'
Learn more about managing modules with a PuppetfileDocumentation
Puppet Archive
Table of Contents
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:
- 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. 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:
Archive {
provider => 'ruby',
}
Users of the module are responsible for archive package dependencies, for alternative providers and all extraction utilities such as tar, gunzip, bunzip:
if $facts['osfamily'] != 'windows' {
package { 'wget':
ensure => present,
}
package { 'bunzip':
ensure => present,
}
Archive {
provider => 'wget',
require => Package['wget', 'bunzip'],
}
}
Usage
Archive module dependencies are managed by the archive
class. This is only
required on Windows. By default 7zip is installed via chocolatey, but
the MSI package can be installed instead:
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
Simple example that downloads from web server:
archive { '/tmp/vagrant.deb':
ensure => present,
source => 'https://releases.hashicorp.com/vagrant/2.2.3/vagrant_2.2.3_x86_64.deb',
user => 0,
group => 0,
}
More complex example :
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:
$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:
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 for full working example):
$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:
$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:
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).
# 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.
On non-Windows systems, the archive
class will install this dependency when
the aws_cli_install
parameter is set to true
:
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:
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
archive { '/tmp/gravatar.png': ensure => present, source => 's3://bodecoio/gravatar.png', download_options => ['--region', 'eu-central-1'], }
-
puppet
provider
override: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 isruby
(no effect).
This option can also be applied globally to address issues for specific OS:
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.
puppet-staging (without extraction)
class { 'staging':
path => '/tmp/staging',
}
staging::file { 'master.zip':
source => 'https://github.com/voxpupuli/puppet-archive/archive/master.zip',
}
puppet-archive (without extraction)
archive { '/tmp/staging/master.zip':
source => 'https://github.com/voxpupuli/puppet-archive/archive/master.zip',
}
puppet-staging (with zip file extraction)
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 (with zip file extraction)
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 files with checksum.archive::go
: archive wrapper for GO Continuous Delivery files with checksum.archive::nexus
: archive wrapper for Sonatype Nexus files with checksum.archive::download
: archive wrapper and compatibility shim for 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 support sprintf format ('tar xvf %s') which will be processed with the filename: sprintf('tar xvf %s', filename)temp_dir
: Specify an alternative temporary directory to use for copying files, if unset then the operating system default will be used.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 pathhttp:://{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
$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
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:
RSpec.configure do |c|
c.default_facts = { :puppetversion => Puppet.version }
end
Changelog
All notable changes to this project will be documented in this file. Each new release typically also includes the latest modulesync defaults. These should not affect the functionality of the module.
v4.6.0 (2020-08-21)
Implemented enhancements:
- Add
temp_dir
parameter toarchive::nexus
#415 (alexcit) - Use curl netrc file instead of
--user
#399 (alexjfisher)
Closed issues:
- Feature request: make password sensitive and hide on fail #397
Merged pull requests:
v4.5.0 (2020-04-02)
Implemented enhancements:
- Add VZ 6/7 to metadata.json #402 (bastelfreak)
Closed issues:
- Could not autoload puppet/parser/functions/artifactory_sha1: no such file to load -- puppet_x/bodeco/util #320
Merged pull requests:
- Convert
archive
class docs to puppet-strings and small README improvements #394 (alexjfisher) - Convert
go_md5
function to modern API #392 (alexjfisher) - Use
relative_require
in artifactory functions #391 (alexjfisher) - Convert
assemble_nexus_url
to modern API #390 (alexjfisher) - Remove duplicate CONTRIBUTING.md file #389 (dhoppe)
- Add Darwin (mac os x) compatibility #387 (bjoernhaeuser)
v4.4.0 (2019-11-04)
Implemented enhancements:
- Extract .zip using PowerShell (native) as alternative to 7-zip #380
- Add support for .tar.Z files and uncompress #385 (hajee)
Merged pull requests:
v4.3.0 (2019-10-16)
Implemented enhancements:
- Add Archlinux compatibility #383 (bastelfreak)
- Add CentOS/RHEL 8 compatibility #382 (bastelfreak)
v4.2.0 (2019-08-14)
Implemented enhancements:
v4.1.0 (2019-07-04)
Closed issues:
- 4 Certificates expired, 3 expiring soon in cacert.pem #372
Merged pull requests:
- Update cacert.pem #373 (alexjfisher)
- drop Ubuntu 14.04 support #371 (bastelfreak)
v4.0.0 (2019-05-29)
Breaking changes:
- modulesync 2.7.0 and drop puppet 4 #368 (bastelfreak)
Implemented enhancements:
- Allow
puppetlabs/stdlib
6.x #369 (alexjfisher)
Merged pull requests:
v3.2.1 (2018-10-19)
Merged pull requests:
- modulesync 2.1.0 and allow puppet 6.x #355 (bastelfreak)
v3.2.0 (2018-08-26)
Implemented enhancements:
- Bump stdlib dependency to \<6.0.0 #352 (HelenCampbell)
- Fallback to PowerShell for zip files on Windows #351 (GeoffWilliams)
v3.1.1 (2018-08-02)
Fixed bugs:
Closed issues:
- need a good example for extracting a tgz #335
Merged pull requests:
- fix documentation - refactor example when extracting tar.gz #342 (azbarcea)
- purge EOL ubuntu 10.04/12.04 from metadata.json #341 (bastelfreak)
- README.md: how to handle a .tar.gz file #338 (bastelfreak)
v3.1.0 (2018-06-14)
Closed issues:
- HTTPS download broken again on windows #289
Merged pull requests:
- Allow Ubuntu 18.04 #336 (mpdude)
- Remove docker nodesets #334 (bastelfreak)
- drop EOL OSs; fix puppet version range #332 (bastelfreak)
v3.0.0 (2018-03-31)
Breaking changes:
- Rewrite artifactory_sha1 function with puppet v4 api #323 (alexjfisher)
- Remove deprecated archive::artifactory parameters #322 (alexjfisher)
Implemented enhancements:
- Adding windows server 2016 to metadata.json #325 (TraGicCode)
Merged pull requests:
- bump puppet to latest supported version 4.10.0 #326 (bastelfreak)
- Don't glob archive URL with curl #318 (derekhiggins)
v2.3.0 (2018-02-21)
Implemented enhancements:
- Support fetching latest SNAPSHOT artifacts #284 (alexjfisher)
Fixed bugs:
Merged pull requests:
- Fix checksum_type sh256 -> sha256 typo #309 (tylerjl)
- Fix typo "voxpupoli" #308 (nmesstorff)
v2.2.0 (2017-11-21)
Closed issues:
- Setting an invalid proxy_server parameter should return a more helpful error message. #220
Merged pull requests:
- Log actual and expected checksums on mismatch #305 (jeffmccune)
v2.1.0 (2017-10-10)
Closed issues:
- unzip not installed and results in errors #291
- Support puppet:/// urls or edit readme? #283
- Using proxy_server and/or proxy_port has no effect on Windows #277
- puppet source #151
Merged pull requests:
- Fix typos in puppet:/// URL example #298 (gabe-sky)
- Update cacert.pem #290 (nanliu)
- Support Nexus 3 urls for artifact downloads #285 (rvdh)
v2.0.0 (2017-08-25)
Breaking changes:
- BREAKING: Drop puppet 3 support. Replace validate_* functions with Puppet 4 data type validations #264 (jkroepke)
Implemented enhancements:
- Enable allow_insecure in archive::download #295 (alexjfisher)
- Add custom download options #279 (nanliu)
- Add support for downloading puppet URL’s #270 (hajee)
Fixed bugs:
- wget proxy implementation incorrect #256
Closed issues:
- allow_insecure is not working #294
- Can't download latest SNAPSHOT artifactory artifacts #282
- Need option to set curl SSL protocol #273
- Add guide for migrating from puppet-staging #266
- Rubocop: fix RSpec/MessageSpies #260
- -z for curl option #241
- RSpec/MessageExpectation violations #208
Merged pull requests:
- Change how ruby proxy is invoked. #280 (nanliu)
- Pass proxy values using the wget -e option #272 (nanliu)
- GH-260 Fix rubocop RSpec/MessageSpies #271 (nanliu)
- Fix README typo on credentials file and add the config too #269 (aerostitch)
- Add puppet-staging migration examples #268 (alexjfisher)
v1.3.0 (2017-02-10)
v1.2.0 (2016-12-25)
- Modulesync with latest Vox Pupuli defaults
- Fix wrong license in repo
- Fix several rubocop issues
- Fix several markdown issues in README.md
- Add temp_dir option to override OS temp dir location
v1.1.2 (2016-08-31)
- GH-213 Fix allow_insecure for ruby provider
- GH-205 Raise exception on bad source parameters
- GH-204 Resolve camptocamp archive regression
- Expose allow_insecure in nexus defined type
- Make archive_windir fact confinement work on ruby 1.8 systems. Note this does not mean the type will work on unsupported ruby 1.8 systems.
v1.1.1 (2016-08-18)
- Modulesync with latest Vox Pupuli defaults
- Fix cacert path
- Fix AIX extraction
- Feature: make allow_insecure parameter universal
v1.0.0 (2016-07-13)
- GH-176 Add Compatiblity layer for camptocamp/archive
- GH-174 Add allow_insecure parameter
- Numerous Rubocop and other modulesync changes
- Drop support for ruby 1.8
v0.5.1 (2016-03-18)
- GH-146 Set aws_cli_install default to false
- GH-142 Fix wget cookie options
- GH-114 Document extract customization options
- Open file in binary mode when writing files for windows download
v0.5.0 (2016-03-10)
Release 0.5.x contains significant changes:
-
faraday, faraday_middleware no longer required.
-
ruby provider is the default for windows (using net::http).
-
archive gem_provider attribute deprecated.
-
archive::artifactory server, port, url_path attributes deprecated.
-
S3 bucket support (experimental).
-
GH-55 use net::http to stream files
-
Add additional documentation
-
Simplify duplicate code in download/content methods
-
Pin rake to avoid rubocop/rake 11 incompatibility
-
Surface "checksum_verify" parameter in archive::nexus
-
GH-48 S3 bucket support
v0.4.8 (2016-03-02)
- VoxPupuli Release
- modulesync to fix forge release issues.
- Cosmetic changes due to rubocop update.
v0.4.7 (2016-03-1)
- VoxPupuli Release
- Raise exception when error occurs during extraction.
v0.4.6 (2016-02-26)
- VoxPupuli Release
v0.4.5 (2016-02-26)
- Puppet-community release
- Update travis/forge badge location
- Fix aio-agent detection
- Support .gz .xz format
- Fix local files for non faraday providers
- Fix GH-77 allows local files to be specified without using file:///
- Fix GH-78 allow local file:///c:/... on windows
- Fix phantom v0.4.4 release.
v0.4.4 (2015-12-2)
- Puppet-community release
- Ignore files properly for functional release
- Add authentication to archive::nexus
- Create directory before transfering file
- Refactor file download code
- Create and use fact for archive_windir
- Cleanup old testing code
v0.4.3 (2015-11-25)
- Puppet-community release
v0.4.1 (2015-11-25)
- Automate release :)
v0.4.0 (2015-11-25)
- Migrate Module to Puppet-Community
- Make everything Rubocop Clean
- Make everything lint clean
- Various fixes concerning Jar handling
- Support for wget
- Spec Tests for curl
- Support for bzip
- More robust handling of sha512 checksums
0.3.0 (2015-04-23)
Release 0.3.x contains breaking changes
-
The parameter 7zip have been changed to seven_zip to conform to Puppet 4.x variable name requirements.
-
The namevar name have been changed to path to allow files with the same filename to exists in different filepath.
-
This project have been migrated to voxpupuli, please adjust your repo git source.
-
Fix Puppet 4 compatability issues
-
Fix archive namevar to use path
0.2.2 (2015-03-05)
- Add FTP and File support
0.2.1 (2015-02-26)
- Fix ruby 1.8.7 syntax error
0.2.0 (2015-02-23)
- Fix custom flags options
- Add msi installation option for 7zip
- Add support for configuring extract command user/group
- Use temporary filepath for download
0.1.8 (2014-12-08)
- Update documentation
- puppet-lint, metadata.json cleanup
0.1.7 (2014-11-13)
- Fix Puppet Enterprise detection
- Fix checksum length restriction
- Add puppetlabs stdlib/pe_gem dependency
- Add spec testing
0.1.6 (2014-11-05)
- Fix Windows SSL authentication issues
0.1.5 (2014-11-04)
- Add cookie support
0.1.4 (2014-10-03)
- Fix file overwrite and re-extract
0.1.3 (2014-10-03)
- Fix windows x86 path bug
0.1.2 (2014-10-02)
- Fix autorequire and installation of dependencies
0.1.1 (2014-10-01)
- Add windows extraction support via 7zip
0.1.0 (2014-09-26)
- Initial Release
* This Changelog was automatically generated by github_changelog_generator
Dependencies
- puppetlabs/stdlib (>= 4.18.0 < 7.0.0)
Copyright 2014 Bodeco Inc Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. Copyright [yyyy] [name of copyright owner] Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.