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

The syntax for using the user resource in a recipe is as follows:

user "name" do
  attribute "value" # see attributes section below
  ...
  action :action # see actions section below
end

where

  • user tells the chef-client to use one of the following providers during the chef-client run: Chef::Provider::User::Useradd, Chef::Provider::User::Pw, Chef::Provider::User::Dscl, or Chef::Provider::User::Windows. The provider that is used by the chef-client depends on the platform of the machine on which the chef-client run is taking place
  • name is the name of the resource block; when the username attribute is not specified as part of a recipe, name is also the name of the user
  • attribute is zero (or more) of the attributes that are available for this resource
  • :action identifies which steps the chef-client will take to bring the node into the desired state

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 One (or more) comments about the user.
gid The identifier for the group.
home The location of the home directory.
iterations 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.
password The password shadow hash. This attribute requires that ruby-shadow be installed. This is part of the Debian package: libshadow-ruby1.8.
provider Optional. Use to explicitly specify a provider. (See “Providers” section below for more information.)
salt 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 The login shell.
supports 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 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 The numeric user identifier.
username 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