users (69) Versions 5.7.0 Follow264

Creates users from a databag search

Policyfile

Berkshelf

Knife

cookbook 'users', '= 5.7.0', :supermarket

cookbook 'users', '= 5.7.0'

knife supermarket install users

knife supermarket download users

README

Dependencies

Changelog

Quality -%

users Cookbook

Manages OS users from databags.

Scope

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.

Maintainers

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 sous-chefs.org or come chat with us on the Chef Community Slack in #sous-chefs.

Requirements

Platforms

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

Chef 12.7+

Cookbooks

none

Usage

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 use the user_manage resource to add all users in the defined group to the system:

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

Example:

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

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"
}

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

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

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 $HOME/.ssh/authorized_keys. A key can include an https endpoint that returns a line separated list of keys such as https://github.com/$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.
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

Resources Overview

users_manage

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

Examples

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

users_manage 'sysadmin' do
  group_id 2300
  action [:create]
end

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

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

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 [:create]
  data_bag 'test_home_dir'
  manage_nfs_home_dirs false
end

Parameters

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

Deprecation Notice

This recipe has been deprecated and the resource will be removed from the recipe in a new major release of this cookbook in April 2017. The functionality can easily be recreated and changed to suit your organization by copying the single resource below into your own cookbook.

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 [ :create ]
end

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.

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 AAA123...xyz== 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
end

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.

Contributors

This project exists thanks to all the people who contribute.

Backers

Thank you to all our backers!

Dependent cookbooks

This cookbook has no specified dependencies.

Contingent cookbooks

users Cookbook CHANGELOG

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

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)

Added

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

Changed

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

Fixed

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

Removed

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

v3.0.0

@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

v2.0.3

@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)

@375gnu- validate uid/gid for strings versus numeric
fix rubocop errors based on https://github.com/bbatsov/rubocop/issues/2608
fix kitchen configurations for testing

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

v1.6.0

Bug

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

v1.5.2

Bug

COOK-3215 - Make group_id optional

v1.5.0

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

v1.4.0

[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

v1.3.0

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

v1.2.0

[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

v1.1.4

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

v1.1.2

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

v1.1.0

[COOK-623] - LWRP conversion

Adoptable Cookbooks List

Supermarket Belongs to the Community

View our collection of guides, documentation, and articles

Select Badges

Select Supported Platforms

Select Status