Skip to content
Development repository for users Chef cookbook
Find file
Latest commit 588b9b6 @iennae iennae Merge pull request #131 from chef-cookbooks/nkadel-skyhook-82
Minor change based off of @nkadel-skyhook PR 82.
Failed to load latest commit information.
libraries Convert uid/gid into integers if databag objects are of type string.
providers Minor change based off of @nkadel-skyhook PR 82.
recipes Update copyrights
resources Rubocop fixes
spec fixing rubocop errors inadvertently added with last commits
tasks Add Testing and maintainers Rakefile
templates/default Remove node.fqdn from the template
test/fixtures adding kitchen.dokken.yml for dokken testing and fixing the sysadmin …
.gitignore Update ignore files
.kitchen.docker.yml Add opensuse 13.2
.kitchen.dokken.yml minor updates to kitchen yaml to ensure working test environments
.kitchen.vmware.yml Resolves Issue 118 fixing provider to work on Mac OS X
.kitchen.yml minor updates to kitchen yaml to ensure working test environments
.rubocop.yml Add a rubocop to-do file
.rubocop_todo.yml Add a rubocop to-do file
.travis.yml Remove suse for now
Berksfile Fix test-kitchen failing to converge due to missing 'apt' cookbook. Minor change based off of @nkadel-skyhook PR 82. Use the new contributing doc
Gemfile Remove cloud gems
LICENSE Update license file Add Testing and maintainers Rakefile
MAINTAINERS.toml Add Testing and maintainers Rakefile minor fix to the README
Rakefile Test using kitchen-docker in travis Add testing doc
chefignore Update ignore files
metadata.rb Clarified the readme to be more specific about assumptions, as well a…

users Cookbook

Build Status Cookbook Version

Manages OS users from databags.


This cookbook is concerned with the management of OS users and groups from databags. It also manages the distribution of ssh keys to a user's home directory.


A data bag populated with user objects must exist. The default data bag in this recipe is users. See USAGE.


  • Chef 11+

Platform Support

The following platforms have been tested with Test Kitchen:

  • Debian / Ubuntu and derivatives
  • RHEL and derivatives
  • Fedora
  • FreeBSD / OpenBSD
  • Mac OS X

Cookbook Dependencies

  • none


To use the resource users_manage, make sure to add the dependency on the users cookbook by the following line to your wrapper cookbook's metadata.rb:

depends 'users'

or to pin to a specific version of the users cookbook, in this case any version of 2.X:

depends 'users', '~> 2'

Then in a recipe:

users_manage 'GROUPNAME' do
  group_id GROUPID
  action [:remove, :create]
  data_bag 'DATABAG_NAME'


users_manage 'testgroup' do
  group_id 3000
  action [:remove, :create]
  data_bag 'test_home_dir'

Note: If you do not specify the data_bag, the default will be to look for a databag called users.

Databag Definition

A sample user object in a users databag would look like:

  "id": "test_user",
  "password": "$1$5cE1rI/9$4p0fomh9U4kAI23qUlZVv/",
  "ssh_keys": [
    "ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAklOUpkDHrfHY17SbrmTIpNLTGK9Tjom/BWDSU\nGPl+nafzlHDTYW7hdI4yZ5ew18JH4JW9jbhUFrviQzM7xlELEVf4h9lFX5QVkbPppSwg0cda3\nPbv7kOdJ/MTyBlWXFCR+HAo3FXRitBqxiX1nKhXpHAZsMciLq8V6RjsNAQwdsdMFvSlVK/7XA\nt3FaoJoAsncM1Q9x5+3V0Ww68/eIFmb1zuUFljQJKprrX88XypNDvjYNby6vw/Pb0rwert/En\nmZ+AW4OZPnTPI89ZPmVMLuayrD2cE86Z/il8b+gw3r3+1nKatmIkjn2so1d01QraTlMqVSsbx\nNrRFi9wrf+M7Q== chefuser@mylaptop.local",
    "ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAklOUpkDHrfHY17SbrmTIpNLTGK9Tjom/BWDSU\nGPl+nafzlHDTYW7hdI4yZ5ew18JH4JW9jbhUFrviQzM7xlELEVf4h9lFX5QVkbPppSwg0cda3\nPbv7kOdJ/MTyBlWXFCR+HAo3FXRitBqxiX1nKhXpHAZsMciLq8V6RjsNAQwdsdMFvSlVK/7XA\nt3FaoJoAsncM1Q9x5+3V0Ww68/eIFmb1zuUFljQJKprrX88XypNDvjYNby6vw/Pb0rwert/En\nmZ+AW4OZPnTPI89ZPmVMLuayrD2cE86Z/il8b+gw3r3+1nKatmIkjn2so1d01QraTlMqVSsbx\nNQCPO0ZZEa1== chefuser@mylaptop.local"
  "groups": [ "testgroup", "nfsgroup" ],
  "uid": 9001,
  "shell": "\/bin\/bash",
  "comment": "Test User"

Databag Key Definitions

  • id: String specifies the username, as well as the data bag object id.
  • password: String specifies the user's password.
  • ssh_keys: Array an array of authorized keys that will be managed by Chef to the user's home directory in .ssh/authorized_keys
  • groups: Array an array of groups that the user will be added to
  • uid: Integer a unique identifier for the user
  • shell: String the user's shell
  • comment:String the GECOS field, generally the User's full name.

Other potential fields:

  • home: String User's home directory. If not assigned, will be set based on platform and username.
  • action: String Supported actions are one's supported by the user resource. If not specified, the default action is create.
  • ssh_private_key: String manages user's private key generally ~/.ssh/id_*
  • ssh_public_key: String manages user's public key generally ~/.ssh/id_*.pub

Resources Overview


The users_manage resource manages users and groups based off of a data bag search and specified action.


Creates the sysadmin group and users defined in the users databag.

users_manage 'sysadmin' do
  group_id 2300
  action [:remove, :create]

Removes, then creates the testgroup group, and users defined in the test_home_dir databag.

users_manage 'testgroup' do
  group_id 3000
  action [:remove, :create]
  data_bag 'test_home_dir'

Removes, then creates the nfsgroup group, and users defined in the test_home_dir databag and does not manage nfs home directories.

users_manage 'nfsgroup' do
  group_id 4000
  action [:remove, :create]
  data_bag 'test_home_dir'
  manage_nfs_home_dirs false


  • data_bag String is the data bag to search
  • search_group String groups name to search for, defaults to resource name
  • group_name String name of the group to create, defaults to resource name
  • group_id Integer numeric id of the group to create, default is to allow the OS to pick next
  • cookbook String name of the cookbook that the authorized_keys template should be found in
  • manage_nfs_home_dirs Boolean whether to manage nfs home directories.

Otherwise, this cookbook is specific for setting up sysadmin group and users with the sysadmins recipe for now.

Recipe Overview

sysadmins.rb: recipe that manages the group sysadmins with group id 2300, and adds users to this group.

To use:

include_recipe "users::sysadmins"

The recipe is defined as follows:

users_manage "sysadmin" do
  group_id 2300
  action [ :remove, :create ]

This users_manage resource searches the users data bag for the sysadmin group attribute, and adds those users to a Unix security group sysadmin. The only required attribute is group_id, which represents the numeric Unix gid and must be unique. The default action for the resource is :create.

The recipe, by default, will also create the sysadmin group. The sysadmin group will be created with GID 2300. This may become an attribute at a later date.

Data bag Overview

Reminder Data bags generally should not be stored in cookbooks, but in a policy repo within your organization. Data bags are useful across cookbooks, not just for a single cookbook.

Use knife to create a data bag for users.

$ knife data bag create users

Create a user in the data_bag/users/ directory.

An optional password hash can be specified that will be used as the user's password.

The hash can be generated with the following command.

$ openssl passwd -1 "plaintextpassword"

Note: The ssh_keys attribute below can be either a String or an Array. However, we are recommending the use of an Array.

  "id": "bofh",
  "ssh_keys": "ssh-rsa AAAAB3Nz...yhCw== bofh"
  "id": "bofh",
  "password": "$1$d...HgH0",
  "ssh_keys": [
    "ssh-rsa foo",
    "ssh-rsa AAA456...uvw== bar"
  "groups": [ "sysadmin", "dba", "devops" ],
  "uid": 2001,
  "shell": "\/bin\/bash",
  "comment": "BOFH"

You can pass any action listed in the user resource for Chef via the "action" option. For Example:

Lock a user, johndoe1.

$ knife data bag edit users johndoe1

And then change the action to "lock":

  "id": "johndoe1",
  "groups": ["sysadmin", "dba", "devops"],
  "uid": 2002,
  "action": "lock", // <--
  "comment": "User violated access policy"

Remove a user, johndoe1.

$ knife data bag edit users johndoe1

And then change the action to "remove":

  "id": "johndoe1",
  "groups": [ "sysadmin", "dba", "devops" ],
  "uid": 2002,
  "action": "remove", // <--
  "comment": "User quit, retired, or fired."
  • Note only user bags with the "action : remove" and a search-able "group" attribute will be purged by the :remove action. If you have different requirements, for example:
  • You want to search a different data bag specific to a role such as
  • mail. You may change the data_bag searched.

    • data_bag mail
  • You want to search for a different group attribute named

  • postmaster. You may change the search_group attribute. This
  • attribute defaults to the LWRP resource name.

    • search_group postmaster
  • You want to add the users to a security group other than the

  • lightweight resource name. You may change the group_name attribute.
  • This attribute also defaults to the LWRP resource name.
    • group_name wheel

Putting these requirements together our recipe might look like this:

users_manage "postmaster" do
  data_bag "mail"
  group_name "wheel"
  group_id 10

Knife supports reading data bags from a file and automatically looks in a directory called +data_bags+ in the current directory. The "bag" should be a directory with JSON files of each item. For the above:

$ mkdir data_bags/users
$EDITOR data_bags/users/bofh.json

Paste the user's public SSH key into the ssh_keys value. Also make sure the uid is unique, and if you're not using bash, that the shell is installed.

The Apache cookbook can set up authentication using OpenIDs, which is set up using the openid key here. See the Chef Software 'apache2' cookbook for more information about this.

Chef Solo

As of version 1.4.0, this cookbook might work with Chef Solo when using chef-solo-search by edelight. That cookbook is not a dependency of this one as Chef solo doesn't support dependency resolution using cookbook metadata - all cookbooks must be provided to the node manually when using Chef Solo.

License & Authors

Author: Cookbook Engineering Team (

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.
Something went wrong with that request. Please try again.