Adoptable Cookbooks List

Looking for a cookbook to adopt? You can now see a list of cookbooks available for adoption!
List of Adoptable Cookbooks

Supermarket Belongs to the Community

Supermarket belongs to the community. While Chef has the responsibility to keep it running and be stewards of its functionality, what it does and how it works is driven by the community. The chef/supermarket repository will continue to be where development of the Supermarket application takes place. Come be part of shaping the direction of Supermarket by opening issues and pull requests or by joining us on the Chef Mailing List.

Select Badges

Select Supported Platforms

Select Status


users (68) Versions 7.1.0

Creates users from a databag search

cookbook 'users', '= 7.1.0', :supermarket
cookbook 'users', '= 7.1.0'
knife supermarket install users
knife supermarket download users
Quality 83%

users Cookbook

Cookbook Version
CI State

Manages OS users and groups (optionally from databags).


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


This cookbook is maintained by the Sous Chefs. The Sous Chefs are a community of Chef cookbook maintainers working together to maintain important cookbooks. If you’d like to know more please visit or come chat with us on the Chef Community Slack in #sous-chefs.


If you are upgrading from a version < 6.0.0 please see


The following platforms have been tested with Test Kitchen:

  • Debian / Ubuntu derivatives
  • RHEL and derivatives
  • Fedora
  • openSUSE / SUSE Linux Enterprises
  • FreeBSD / OpenBSD
  • macOS
  • AIX


  • Chef 12.7+


  • 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 6.X:

depends 'users', '~> 6'

Then in a recipe use the user_manage resource to add all users in the defined group to the system:

users_variable = [{
  id: 'databag_test_user',
  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",
  groups: [ 'GROUPNAME' ],

users_manage 'GROUPNAME' do
  group_id GROUPID
  action [:create]
  users users_variable


users_manage 'testgroup' do
  group_id 3000
  action [:create]
  users node['users']['array_of_users']

Note: The users property needs to be given an Array of Hashes that contains one user per hash. This can be done by passing a data bag like the example below or from any other source.

Databag Definition

This is an alternative to the attribute definition as mentioned below.

You could for instance create a databag called users. You then create a subdatabag for each user object.

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"

A sample user to remove from a system would like like:

  "id": "mwaddams",
  "action": "remove",
  "groups": [ "testgroup", "nfsgroup" ]

Attributes Definition

This is an alternative to the data bag definition as mentioned above.

Consider having a cookbook called usermanagement where you include this users cookbook.

You could then set the attributes like this:

default['usermanagement']['users'] = [
    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: %w(testgroup nfsgroup),
    uid: 9001,
    shell: '/bin/bash',
    comment: 'Test User'
     id: 'mwaddams',
     action: 'remove',
     groups: %w(testgroup nfsgroup)

User 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 $HOME/.ssh/authorized_keys. A key can include an https endpoint that returns a line separated list of keys such as$GITHUB_USERNAME.keys this will retrieve all the keys and add it to the array and can be used with static keys as well as dynamic ones.
  • 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 (optional):

  • home: String User's home directory. If not assigned, will be set based on platform and username.
  • manage_home: True, False Creates/removes the home directory. Defaults to false.
  • homedir_mode: String, Integer Modifies a user's home directory permissions.
  • no_user_group: True, False Specifies if the user needs to get a group with the name of the users. Defaults to false.
  • 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
  • authorized_keys_file: String a nonstandard location for the authorized_keys file
  • gid: String, Integer Specifies the primary group of a user by the gid number or the group name. The group will be created if it doesn't exist.
  • primary_group: String To be used in combination with the gid field when the gid is an integer. Specifying the group name prevents errors where the user is created before their primary group.

Resources Overview


The users_manage resource manages users and groups based off the users property or of a data bag search and the specified action(s).


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

# Get the users from the data bag
users_from_databag = search('users', '*:*')

users_manage 'sysadmin' do
  group_id 2300
  action [:create]
  users users_from_databag

Creates the testgroup group, and users defined in the test_home_dir attribute.

users_manage 'testgroup' do
  group_id 3000
  action [:create]
  users node['test_home_dir']

Creates the nfsgroup group, and users defined in the test_home_dir local variable and does not manage nfs home directories.

users_manage 'nfsgroup' do
  group_id 4000
  action [:create]
  users test_home_dir
  manage_nfs_home_dirs false


  • users Array This is the source of the users. It needs to be an array of hashes, where each hash represents its own user. You can use data bags, attributes or something different here.
  • 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.

Recipe Overview

Recipes are not directly used. Please include the users_manage resource directly in your cookbook.

Data bag Overview

Reminder You do not have to use data bags, you can also pass the users directly to the resource from a different source as explained above.

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.
  • As of v2.0.3 you can use the force parameter within the user data bag object for users with action remove. As per user docs this may leave the system in an inconsistent state. For example, a user account will be removed even if the user is logged in. A user's home directory will be removed, even if that directory is shared by multiple users.

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 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 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.


This project exists thanks to all the people who contribute.


Thank you to all our backers!


Support this project by becoming a sponsor. Your logo will show up here with a link to your website.

Dependent cookbooks

This cookbook has no specified dependencies.

Contingent cookbooks

base_install Applicable Versions
baseserver Applicable Versions
cafe-core Applicable Versions
chef-nsq Applicable Versions
cloudera-manager Applicable Versions
codenamephp_users Applicable Versions
config-driven-helper Applicable Versions
ctfhooks Applicable Versions
gmvault Applicable Versions
magentostack Applicable Versions
mw_server_base Applicable Versions
oh-my-zsh Applicable Versions
paramount Applicable Versions
r1337-linux-users Applicable Versions
sftp Applicable Versions
survivor Applicable Versions
tfchefint Applicable Versions
ugid-management Applicable Versions
users_sshkeys Applicable Versions

users Cookbook CHANGELOG

This file is used to list changes made in each version of the users cookbook.

7.1.0 - 2021-07-28

  • Give group ownership of each users .ssh/* files to that users primary group
  • Allow user to set file permissions for their home directory
  • Add a primary_group and homedir_mode key to the user hash options

7.0.1 - 2021-07-02

  • Allows a given user to be in a group of the same name, that is already created or explicitly defined in its groups key

7.0.0 - 2021-06-21

  • Set unified_mode to true for the users_manage resource
  • Set minium Chef version to 15.3 for unified_mode
  • Inspec fix from nil to ''

6.0.3 - 2021-06-01

6.0.2 - 2021-03-29

  • Allow users attribute to be unset, allowing to create a group without any users.

6.0.1 - 2021-03-16

  • Fix invalid checking of user[:uid] which could lead to root owning the users folders and files. Thanks @evandam

6.0.0 - 2021-03-12

  • Removed hard dependency on data bags. See for details
  • Added per user no_user_group option to skip creating user group with the same name.
  • Cleaned up the manage resource
  • Added pubkey_type helper
  • Added more integration tests and updated unit tests to chefspec.

5.7.0 - 2021-03-08

  • Add manage_home to the remove action of the manage resource

5.6.0 - 2021-01-31

  • Sous Chefs Adoption
  • Standardise files with files in sous-chefs/repo-management
  • Add integration testing for MacOS
  • Remove testing for Amazon Linux 201x, CentOS 6 and Ubuntu 16.04
  • Exclude uid and home properties from user resource on MacOS

5.5.0 (2020-09-01)


  • Add code owners file
  • Use the org wide GitHub templates
  • Replace TravisCI with Github Actions for testing
  • Add Ubuntu 20.04 and include other platforms on dokken for tests
  • Enable enforce_idempotency


  • Update README - formatting fixes
  • Simplify platform specific logic and remove foodcritic comments
  • Require Chef Infra Client 12.15+


  • Cookstyle fixes
  • MDL fixes
  • yamllint fixes
  • Standardise files with files in chef-cookbooks/repo-management
  • Update keys so test passes


  • Remove Ubuntu 14.04 testing
  • Remove one-off ubuntu-16.04-chef-12.7 suite
  • Remove .rubocop.yml as it's no longer needed

5.4.0 (2018-07-18)

  • Remove ChefSpec matchers which are now auto-generatedb y ChefSpec
  • Add a new databag entry for the keyfile location

5.3.1 (2017-12-15)

  • Remove special case for freebsd in favor of later shell validity check

5.3.0 (2017-12-07)

  • Add check if user shell exists
  • Verify the shell is allowed on AIX
  • Add AIX as a supported platform

5.2.2 (2017-11-29)

  • Add home directory base for solaris

5.2.1 (2017-10-31)

  • Make sure ssh_keys can be an array or a string by converting strings to an array if they're passed

5.2.0 (2017-10-31)

  • Require Chef 12.7+ as 12.5 and 12.6 had bugs in their custom resource implementation
  • Allow fetching one or more ssh_keys from a url

5.1.0 (2017-05-30)

  • Keep ssh keys out of the chef logs
  • Improve docs and examples
  • Remove class_eval and require Chef 12.7+ as class_eval causes issues with later Chef 12 releases

5.0.0 (2017-04-17)

Breaking changes

  • The users_manage LWRP has been converted to a custom resource, which requires Chef 12.5 or later
  • The sysadmins recipe contains no resources now and will do nothing

Other changes

  • Added integration tests with Inspec
  • Fixed all deprecation warnings
  • Fixed group creation on macOS when the group already exists
  • Added suse platforms as supported in the metadata
  • Switched to a SPDX apache-2.0 license string
  • Moved all templates out of the default directory as we don't support Chef 11 anymore

4.0.3 (2016-11-23)

  • Update manage provider to return true/false in guard block which avoids warnings during run on Chef 12.14+

4.0.2 (2016-11-18)

  • Deprecate the sysadmins recipe

4.0.1 (2016-09-15)

  • Fix creation of user home directory

4.0.0 (2016-09-15)

  • Add chef_version to the metadata
  • Require Chef 12.1+
  • Testing updates
  • Fixed compatibility with Chef 12.14
  • Properly define the Chefspec matcher
  • Add a warning if someone includes users::default since that does nothing


  • @onlyhavecans - Fix FreeBSD support
  • @stem - Fix user creation on Mac OS X on 10.7 and 10.8
  • Remove old style chef solo code to clean up rubocop issues, move to using cookstyle
  • Adding zlinux support


  • @nkadel-skyhook - create .ssh directory only if keys are configured.
  • @signe - allow force parameter to be specified for users configured to be removed.
  • @FlorentFlament - adding the ability to manage groups for existing users.

v2.0.2 (2016-1-25)

v2.0.1 (2016-1-8)

  • Fixed provider to work on Mac OS X
  • funzoneq - add correct default shell for FreeBSD if not provided
  • Added kitchen.dokken to speed up platform testing

v2.0.0 (2015-12-11)

  • Removed Chef 10 compatibility code
  • Removed the nodes fqdn from the authorized_keys file
  • Removed a trailing comma in a readme example
  • Added chef standard .gitignore and chefignore files
  • Added chef standard .rubocop.yml file and resolved warnings
  • Resolved foodcritic warnings

v1.8.2 (2015-03-18)

  • No changes, just republishing 1.8.1

v1.8.1 (2015-03-12)

  • Add source_url and issues_url to the metadata.rb so Supermarket can display appropriate links

v1.8.0 (2015-03-09)

  • Expose LWRP state attributes
  • [COOK-4401] - Add unit tests with ChefSpec
  • [COOK-4404] - Determine file system and add manage_nfs_home_dirs attribute to disable managing NFS mounted home directories
  • Remove converge_by when creating home directory, the directory resource already handles this
  • Do not manage home directory if the path does not exist
  • Add integration with TravisCI
  • "Opscode" to "Chef" replacements
  • Retire unsupported Ruby 1.9.3 and add Ruby 2.2 to the Travis integration tests
  • Updates for RSpec 3

v1.7.0 (2014-02-14)

  • [COOK-4139] - users_manage resource always notifies
  • [COOK-4078] - users cookbook fails in why-run mode for .ssh directory
  • [COOK-3959] - Add support for Mac OS X to users cookbook



  • COOK-3744 - Allow passing an action option via the data_bag to the user resource




  • [COOK-2427] - Mistakenly released instead of sudo :-).


  • [COOK-2479] - Permit users cookbook to work with chef-solo if edelight/chef-solo-search is installed
  • [COOK-2486] - specify precedence when setting node attribute


  • [COOK-1842] - allow specifying private SSH keys
  • [COOK-2021] - Empty default recipe for including users LWRPs


  • [COOK-1398] - Provider manage.rb ignores username attribute
  • [COOK-1582] - ssh_keys should take an array in addition to a string separated by new lines


  • [COOK-1396] - removed users get recreated
  • [COOK-1433] - resolve foodcritic warnings
  • [COOK-1583] - set passwords for users


  • [COOK-1076] - authorized_keys template not found in another cookbook


  • [COOK-623] - LWRP conversion

Collaborator Number Metric

7.1.0 passed this metric

Contributing File Metric

7.1.0 passed this metric

Foodcritic Metric

7.1.0 failed this metric

FC009: Resource attribute not recognised: users/resources/manage.rb:98
FC022: Resource condition within loop may not behave as expected: users/resources/manage.rb:144
Run with Foodcritic Version 16.3.0 with tags metadata,correctness ~FC031 ~FC045 and failure tags any

No Binaries Metric

7.1.0 passed this metric

Testing File Metric

7.1.0 passed this metric

Version Tag Metric

7.1.0 passed this metric