Chef

Table Of Contents

user

A resource defines the desired state for a single configuration item present on a node that is under management by Chef. A resource collection—one (or more) individual resources—defines the desired state for the entire node. During a chef-client run, the current state of each resource is tested, after which the chef-client will take any steps that are necessary to repair the node and bring it back into the desired state.

Use the user resource to add users, update existing users, remove users, and to lock/unlock user passwords.

Note

System attributes are collected by Ohai at the start of every chef-client run. By design, the actions available to the user resource are processed after the start of the chef-client run. This means that attributes added or modified by the user resource during the chef-client run must be reloaded before they can be available to the chef-client. These attributes can be reloaded in two ways: by picking up the values at the start of the (next) chef-client run or by using the ohai resource to reload these attributes during the current chef-client run.

Syntax

A user resource block manages users on a node:

user 'a user' do
  comment 'A random user'
  uid 1234
  gid 'users'
  home '/home/random'
  shell '/bin/bash'
  password '$1$JJsvHslasdfjVEroftprNn4JHtDi'
end

The full syntax for all of the attributes that are available to the user resource is:

user 'name' do
  comment                    String
  force                      TrueClass, FalseClass # see description
  gid                        String, Integer
  home                       String
  iterations                 Integer
  manage_home                TrueClass, FalseClass
  non_unique                 TrueClass, FalseClass
  password                   String
  provider                   Chef::Provider::User
  salt                       String
  shell                      String
  supports                   Hash
  system                     TrueClass, FalseClass
  uid                        String, Integer
  username                   String # defaults to 'name' if not specified
  action                     Symbol # defaults to :create if not specified
end

where

  • user is the resource
  • name is the name of the resource block
  • :action identifies the steps the chef-client will take to bring the node into the desired state
  • comment, force, gid, home, iterations, manage_home, non_unique, password, provider, salt, shell, supports, system, uid, and username are attributes of this resource, with the Ruby type shown. (See “Attributes” section below for more information about all of the attributes that may be used with this resource.)

Actions

This resource has the following actions:

Action Description
:create Default. Use to create a user with given attributes. If a user already exists (but does not match), use to update that user to match.
:remove Use to remove a user.
:modify Use to modify an existing user. This action will raise an exception if the user does not exist.
:manage Use to manage an existing user. This action will do nothing if the user does not exist.
:lock Use to lock a user’s password.
:unlock Use to unlock a user’s password.

Attributes

This resource has the following attributes:

Attribute Description
comment

Ruby Type: String

One (or more) comments about the user.

force

Ruby Types: TrueClass, FalseClass

Use to force the removal of a user. (May be used only with the :remove action.)

Warning

Using this attribute 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.

gid

Ruby Types: String, Integer

The identifier for the group.

home

Ruby Type: String

The location of the home directory.

iterations

Ruby Type: Integer

Mac OS X platform only, 10.8 (or higher). Use to specify the number of iterations for a password with a SALTED-SHA512-PBKDF2 shadow hash.

manage_home

Ruby Types: TrueClass, FalseClass

Use to manage a user’s home directory.

With the :create action, a user’s home directory is created based on HOME_DIR. If the home directory is missing, it will be created unless CREATE_HOME in /etc/login.defs is set to no. When created, a skeleton set of files and sub-directories is also created in the home directory.

With the :modify action, a user’s home directory is moved to HOME_DIR. If the home directory is missing, it will be created unless CREATE_HOME in /etc/login.defs is set to no. The contents of the user’s home directory are moved to the new location.

non_unique

Ruby Types: TrueClass, FalseClass

Use to create a duplicate (non-unique) user account.

password

Ruby Type: String

The password shadow hash. This attribute requires that ruby-shadow be installed. This is part of the Debian package: libshadow-ruby1.8.

provider

Ruby Type: Chef Class

Optional. Use to explicitly specify a provider. (See “Providers” section below for more information.)

salt

Ruby Type: String

Mac OS X platform only, 10.7 or higher. Use to specify the salt value for a password shadow hash. Mac OS X version 10.7 uses SALTED-SHA512 and version 10.8 (and higher) uses SALTED-SHA512-PBKDF2 to calculate password shadow hashes.

shell

Ruby Type: String

The login shell.

supports

Ruby Type: Hash

A Mash where keys represent features and values are booleans that indicate if that feature is supported. Default value: :manage_home => false, :non_unique => false.

system

Ruby Types: TrueClass, FalseClass

Use to create a system user. This attribute may be used with useradd as the provider to create a system user which passes the -r flag to useradd.

uid

Ruby Types: String, Integer

The numeric user identifier.

username

Ruby Type: String

The name of the user. Default value: the name of the resource block. (See “Syntax” section above for more information.)

Supported Features

The supports attribute allows a list of supported features to be identified. There are two features of note:

  • :manage_home indicates whether a user’s home directory will be created when the user is created. When the Useradd provider is used, -dm wil be passed to useradd (when the :create action is used) and -d will be passed to usermod (when the :manage or :modify actions are used). If supports :manage_home=>true, the user resource passes the -d and -m parameters together (i.e. -dm) to usermod.

    When the Windows provider is used, Microsoft Windows does not create a home directory for a user until that user logs on for the first time; specifying the home directory does not have any effect as to where Microsoft Windows ultimately places the home directory.

  • :non_unique indicates whether non-unique UIDs are allowed. This option is currently unused by the existing providers.

Password Shadow Hash

There are a number of encryption options and tools that can be used to create a password shadow hash. In general, using a strong encryption method like SHA-512 and the passwd command in the OpenSSL toolkit is a good approach, however the encryption options and tools that are available may be different from one distribution to another. The following examples show how the command line can be used to create a password shadow hash. When using the passwd command in the OpenSSL tool:

openssl passwd -1 "theplaintextpassword"

When using mkpasswd:

mkpasswd -m sha-512

For more information:

  • http://www.openssl.org/docs/apps/passwd.html
  • Check the local documentation or package repository for the distribution that is being used. For example, on Ubuntu 9.10-10.04, the mkpasswd package is required and on Ubuntu 10.10+ the whois package is required.

Providers

Where a resource represents a piece of the system (and its desired state), a provider defines the steps that are needed to bring that piece of the system from its current state into the desired state.

The chef-client will determine the correct provider based on configuration data collected by Ohai at the start of the chef-client run. This configuration data is then mapped to a platform and an associated list of providers.

Generally, it’s best to let the chef-client choose the provider and this is (by far) the most common approach. However, in some cases specifying a provider may be desirable. There are two approaches:

  • Use a more specific short name—yum_package "foo" do instead of package "foo" do, script "foo" do instead of bash "foo" do, and so on—when available
  • Use the provider attribute to specify the long name as an attribute of a resource, e.g. provider Chef::Provider::Long::Name

This resource has the following providers:

Long name Short name Notes
Chef::Provider::User::Useradd user The default provider for the user resource.
Chef::Provider::User::Pw user The provider that is used with the FreeBSD platform.
Chef::Provider::User::Dscl user The provider that is used with the Mac OS X platform.
Chef::Provider::User::Windows user The provider that is used with all Microsoft Windows platforms.

Examples

The following examples demonstrate various approaches for using resources in recipes. If you want to see examples of how Chef uses resources in recipes, take a closer look at the cookbooks that Chef authors and maintains: https://github.com/opscode-cookbooks.

Create a random user

user 'random' do
  supports :manage_home => true
  comment 'Random User'
  uid 1234
  gid 'users'
  home '/home/random'
  shell '/bin/bash'
  password '$1$JJsvHslV$szsCjVEroftprNn4JHtDi'
end

Create a system user

user 'systemguy' do
  comment 'system guy'
  system true
  shell '/bin/false'
end

Create a system user with a variable

The following example shows how to create a system user using a variable called user_home where the matching nodes have a group identifier that is the same as the node, and the login shell is /bin/bash:

user_home = '/#{node[:matching_node][:user]}'

user node[:matching_node][:group] do
  gid node[:matching_node][:group]
  shell '/bin/bash'
  home user_home
  system true
  action :create
end

where matching_node represents a type of node. For example, if the user_home variable specified {node[:nginx]...}, a recipe might look something like this:

user_home = '/#{node[:nginx][:user]}'

user node[:nginx][:group] do
  gid node[:nginx][:group]
  shell '/bin/bash'
  home user_home
  system true
  action :create
end

Use SALTED-SHA512 passwords

Mac OS X 10.7 calculates the password shadow hash using SALTED-SHA512. The length of the shadow hash value is 68 bytes, the salt value is the first 4 bytes, with the remaining 64 being the shadow hash itself. The following code will calculate password shadow hashes for Mac OS X 10.7:

password = 'my_awesome_password'
salt = OpenSSL::Random.random_bytes(4)
encoded_password = OpenSSL::Digest::SHA512.hexdigest(salt + password)
shadow_hash = salt.unpack('H*').first + encoded_password

Use the calculated password shadow hash with the user resource:

user 'my_awesome_user' do
  password 'c9b3bd....d843'  # Length: 136
end

Use SALTED-SHA512-PBKDF2 passwords

Mac OS X 10.8 (and higher) calculates the password shadow hash using SALTED-SHA512-PBKDF2. The length of the shadow hash value is 128 bytes, the salt value is 32 bytes, and an integer specifies the number of iterations. The following code will calculate password shadow hashes for Mac OS X 10.8 (and higher):

password = 'my_awesome_password'
salt = OpenSSL::Random.random_bytes(32)
iterations = 25000 # Any value above 20k should be fine.

shadow_hash = OpenSSL::PKCS5::pbkdf2_hmac(
  password,
  salt,
  iterations,
  128,
  OpenSSL::Digest::SHA512.new
).unpack('H*').first
salt_value = salt.unpack('H*').first

Use the calculated password shadow hash with the user resource:

user 'my_awesome_user' do
  password 'cbd1a....fc843'  # Length: 256
  salt 'bd1a....fc83'        # Length: 64
  iterations 25000
end