A Chef cookbook to unpack file archives like TAR and ZIP files.
Clone or download
Latest commit d8df2e9 Feb 3, 2018


Poise-Archive Cookbook

Build Status Gem Version Cookbook Version Coverage Gemnasium License

A Chef cookbook to unpack file archives.

It supports .tar, .tar.gz, .tar.bz2, and .zip archive files.

Quick Start

To download an unpack and archive:

poise_archive 'https://example.com/myapp.tgz' do
  destination '/opt/myapp'


Chef 12.1 or newer is required.


This cookbook supports all platforms (including Windows) but some Unix platforms (Solaris, AIX) may see very slow tar file unpacking when using the pure-Ruby fallback implementation.



The poise_archive resource unpacks file archives.

poise_archive '/tmp/myapp-1.2.0.tar' do
  destination '/srv/myapp-1.2.0'

A URL can also be passed as the source path, optionally with extra properties to be merged with source_properties.

poise_archive 'http://example.com/myapp-1.2.0.zip' do
  destination '/srv/myapp-1.2.0'

poise_archive ['http://example.com/myapp-1.2.0.zip', {headers: {'User-Agent' => 'myrecipe-1.0.0'}}] do
  destination '/srv/myapp-1.2.0'

To pass sensitive information like authentication credentials, use the path or source_properties properties:

poise_archive 'myapp.zip' do
  path "https://username:#{password}@example.com/myapp-1.2.0.zip"
  destination '/srv/myapp-1.2.0'

poise_archive  do
  path 'http://example.com/myapp-1.2.0.zip'
  source_properties headers: {'X-Auth-Token' => token}
  destination '/srv/myapp-1.2.0'


  • :unpack – Unpack the archive. (default)


  • path – Path to the archive. If relative, it is taken as a file inside Chef::Config[:file_cache_path]. If a URL, it is downloaded to a cache file first. (name attribute)
  • destination – Path to unpack the archive to. If not specified, the path of the archive without the file extension is used. Required when unpacking from a URL. (default: auto)
  • group – Group to run the unpack as.
  • keep_existing – Keep existing files in the destination directory when unpacking. (default: false)
  • source_properties – Property key/value pairs to be applied to the remote_file file resource when downloading a URL. (default: {retries: 5})
  • strip_components – Number of intermediary directories to skip when unpacking. Works like GNU tar's --strip-components. (default: 1)
  • user – User to run the unpack as.


Development sponsored by Bloomberg.

The Poise test server infrastructure is sponsored by Rackspace.


Copyright 2016-2017, Noah Kantrowitz

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


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.

BZip2 implementation is based on RBzip2. Copyright Sebastian Staudt, Brian Lopez. RBzip2 code used under the terms of the new BSD license.