Development repository for Chef Cookbook push-jobs
Ruby HTML Shell
Latest commit 20594a6 Mar 22, 2017 @tas50 tas50 Update Apache license string in metadata
Signed-off-by: Tim Smith <>
Failed to load latest commit information.
.delivery Test with Local Delivery instead of Rake Mar 1, 2017
.github Update for the DCO Oct 4, 2016
attributes Merge pull request #103 from akadoya/master Mar 17, 2017
libraries Merge pull request #103 from akadoya/master Mar 17, 2017
recipes Merge pull request #103 from akadoya/master Mar 17, 2017
resources Revert "Cookstyle fixes" Feb 24, 2017
spec Add support for using a local Push Jobs package Dec 11, 2016
tasks Fix copyright headers Dec 30, 2016
templates Fix for issue #107 Dec 30, 2016
test Typo preventing berks upload Mar 16, 2017
.foodcritic Resolve cookstyle and foodcritic warnings May 26, 2016
.gitignore Test with Local Delivery instead of Rake Mar 1, 2017
.kitchen.dokken.yml Test with Local Delivery instead of Rake Mar 1, 2017
.kitchen.yml Require Chef 12.5+ and remove compat_resource dependency Feb 15, 2017
.rubocop.yml Convert to cookstyle May 24, 2016
.travis.yml Update Apache license string in metadata Mar 22, 2017
Berksfile Remove apt-get update from test kitchen May 31, 2016 Release 4.0 Feb 15, 2017 Update docs Sep 10, 2015
Gemfile Update Apache license string in metadata Mar 22, 2017
LICENSE Update the license file Apr 27, 2016 Expand platforms we test on Sep 22, 2016
MAINTAINERS.toml Update maintainers wording and format [skip-ci] Sep 8, 2016 Merge pull request #103 from akadoya/master Mar 17, 2017 Update docs Sep 10, 2015
chefignore Update ignore files Apr 27, 2016
metadata.rb Update Apache license string in metadata Mar 22, 2017

push-jobs cookbook

Build Status Cookbook Version

Installs the Chef Push client package and sets it up to run as a service.

The official documentation is on


Requires Chef Server with the Chef Push Server add-on.


  • Debian/Ubuntu
  • Windows

Tested with Test Kitchen suites on Ubuntu 12.04/14.04/16.04, CentOS 6/7, and Windows 2012 R2. It may work on other debian, rhel, or windows platform families with or without modification.


  • Chef 12.5+



Include the default recipe in a node's run list. On Windows, the URL to the package to install and its SHA256 checksum are required so the package may be retrieved. Please note that if the URL cannot be parsed from the URL, the package_version attribute will also need to be set. For example:

node.default['push_jobs']['package_url'] = ""
node.default['push_jobs']['package_checksum'] = "a-sha256-checksum"
node.default['push_jobs']['package_version'] = 'the-version-of-push-jobs' # optional - set this if the version of the installer cannot be parsed from the attribute package_url

Optionally, if you have a copy of the package on the local filesystem you can specify it to be used for the installation. For example:

node.default['push_jobs']['local_package_path'] = 'D:\\'

Set a whitelist of job names and their commands in the configuration file. This is automatically generated from the node['push_jobs']['whitelist'] attribute Hash, such as:

node.default['push_jobs']['whitelist'] = {
  "chef-client" => "chef-client",
  "apt-get-update" => "apt-get update"

As this is an attribute, interesting uses arise from orchestrating a Chef Client run. Assuming the above is present on the node prior to running the recipe, run Chef Client with this command from the local workstation:

knife job start chef-client A_NODE_NAME

New jobs can be added to the whitelist simply by creating attributes. This can be done with knife exec:

knife exec -E 'nodes.transform("name:A_NODE_NAME") do |n|
  n.set["push_jobs"]["whitelist"]["ntpdate"] = "ntpdate -u time"

Then, run the chef-client job, and then the ntpdate job:

knife job start chef-client A_NODE_NAME
knife job start ntpdate A_NODE_NAME

Enabling 1.X Server Compatibility

If you're running the 2.X push jobs client with the 1.X server you'll need to set allow_unencrypted to true with this attribute:

node.default['push_jobs']['allow_unencrypted'] = true


See attributes/default.rb for default values.


There are several recipes in this cookbook, so they can be used all together (include the default recipe), or as necessary.


The default recipe includes the appropriate recipe based on the node's platform_family. It will raise an error if:

  • The package URL and checksum attributes are not set on Windows
  • The whitelist is not a Hash.
  • The node's platform is not supported.


This recipe ensures the platform-specific configuration directory (/etc/chef) is created, and renders the configuration file (push-jobs-client.rb) using the whitelist attribute. Any environment variables can be set using environment_variables attribute with key value pairs. You can provide your own push-jobs-client.rb.erb template file in a wrapper cookbook and set the ['config']['template_cookbook'] attribute to the name of that wrapper cookbook.

The path to the configuration file is set using the PushJobsHelper module's #config_path method. This is done to ensure the correct file path is used on Linux and Windows platforms, as it uses Chef::Config's #platform_specific_path method.


This recipe is responsible for handling the service resource based on the node's platform. On Linux (Debian and RHEL families), it will create a runit, upstart, or systemd service. upstart and systemd will be used where those are the native init system for your distro. If neither are available or default['push_jobs']['init_style'] is set to runit then runit will be installed and the service will use runit. On Windows nodes, the recipe will add a registry key for the Chef Push client, and manage the Windows service.

The service resources expect to be restarted if the configuration template is changed, using subscribes notification.

Client Connection Configuration

The push job client establishes a command and heartbeat channel to the push server over tcp. The tcp connection information is read from the Chef Server upon startup of the push client service from an endpoint similar to the following:


The connection information for the push server is established when the push server is installed and the Chef Server is reconfigured. In the case the Chef Server is not providing the correct push server configuration, please verify hostnames are correct and that both the push server and Chef Server have been reconfigured.

Verify Push Jobs Client Connection

If the push client has been successfully installed on a node, the client should be able to successfully respond to a knife job directed to the node. If the node is not responding correctly, please consult the logs node['push_jobs']['logging_dir']/push-jobs-client.log (default: /var/log/chef/push-jobs-client.log) (for Debian and Rhel families) and look for entries similar to the following:

INFO: [pclient] Starting client ...
INFO: [pclient] Retrieving configuration from https://private-chef-server/organizations/org1/pushy/config/pc_6_1 ...
INFO: [pclient] Connecting to command channel at tcp://private-chef-server:10002
INFO: [pclient] Listening for server heartbeat at tcp://private-chef-server:10000
INFO: [pclient] Started client.

License & Authors

Copyright:: 2009-2016, Chef Software, Inc

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,
See the License for the specific language governing permissions and
limitations under the License.