cookbook 'users', '= 3.0.0'
users
(68) Versions
3.0.0
-
-
8.1.20
-
8.1.19
-
8.1.18
-
8.1.17
-
8.1.16
-
8.1.15
-
8.1.14
-
8.1.13
-
8.1.12
-
8.1.11
-
8.1.10
-
8.1.9
-
8.1.8
-
8.1.7
-
8.1.6
-
8.1.5
-
8.1.4
-
8.1.3
-
8.1.2
-
8.1.1
-
8.1.0
-
8.0.0
-
7.1.1
-
7.1.0
-
7.0.1
-
7.0.0
-
6.0.3
-
6.0.2
-
6.0.1
-
6.0.0
-
5.7.0
-
5.6.0
-
5.5.0
-
5.4.0
-
5.3.1
-
5.3.0
-
5.2.2
-
5.2.1
-
5.2.0
-
5.1.0
-
5.0.0
-
4.0.3
-
4.0.2
-
4.0.1
-
4.0.0
-
3.0.0
-
2.0.3
-
2.0.2
-
2.0.1
-
2.0.0
-
1.8.2
-
1.8.1
-
1.8.0
-
1.7.0
-
1.6.0
-
1.5.2
-
1.5.0
-
1.4.0
-
1.3.0
-
1.2.0
-
1.1.4
-
1.1.2
-
1.1.0
-
1.0.0
-
0.3.1
-
0.3.0
-
0.2.0
-
0.1.0
Follow264
- 8.1.20
- 8.1.19
- 8.1.18
- 8.1.17
- 8.1.16
- 8.1.15
- 8.1.14
- 8.1.13
- 8.1.12
- 8.1.11
- 8.1.10
- 8.1.9
- 8.1.8
- 8.1.7
- 8.1.6
- 8.1.5
- 8.1.4
- 8.1.3
- 8.1.2
- 8.1.1
- 8.1.0
- 8.0.0
- 7.1.1
- 7.1.0
- 7.0.1
- 7.0.0
- 6.0.3
- 6.0.2
- 6.0.1
- 6.0.0
- 5.7.0
- 5.6.0
- 5.5.0
- 5.4.0
- 5.3.1
- 5.3.0
- 5.2.2
- 5.2.1
- 5.2.0
- 5.1.0
- 5.0.0
- 4.0.3
- 4.0.2
- 4.0.1
- 4.0.0
- 3.0.0
- 2.0.3
- 2.0.2
- 2.0.1
- 2.0.0
- 1.8.2
- 1.8.1
- 1.8.0
- 1.7.0
- 1.6.0
- 1.5.2
- 1.5.0
- 1.4.0
- 1.3.0
- 1.2.0
- 1.1.4
- 1.1.2
- 1.1.0
- 1.0.0
- 0.3.1
- 0.3.0
- 0.2.0
- 0.1.0
Creates users from a databag search
cookbook 'users', '= 3.0.0', :supermarket
knife supermarket install users
knife supermarket download users
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.
Requirements
A data bag populated with user objects must exist. The default data bag in this recipe is users
. See USAGE.
Chef
- 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
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:
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" }
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 iscreate
. -
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
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
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. 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 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 LWRP resource name.
- search_group
postmaster
- search_group
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
- group_name
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.
License & Authors
Author: Cookbook Engineering Team (cookbooks@chef.io)
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
http://www.apache.org/licenses/LICENSE-2.0
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.
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.
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
andissues_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
Collaborator Number Metric
3.0.0 passed this metric
Foodcritic Metric
3.0.0 failed this metric
FC003: Check whether you are running with chef server before using server-specific features: /tmp/8d755578cd1461ba437132c5/users/providers/manage.rb:28
FC003: Check whether you are running with chef server before using server-specific features: /tmp/8d755578cd1461ba437132c5/users/providers/manage.rb:40
3.0.0 passed this metric
3.0.0 failed this metric
FC003: Check whether you are running with chef server before using server-specific features: /tmp/8d755578cd1461ba437132c5/users/providers/manage.rb:28
FC003: Check whether you are running with chef server before using server-specific features: /tmp/8d755578cd1461ba437132c5/users/providers/manage.rb:40