Table Of Contents


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.


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.


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


  • 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 is the step that the resource will ask the provider to take during the chef-client run


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.


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.
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 specify a provider by using its long name. For example: provider Chef::Provider::Long::Name. See the Providers section below for the list of providers available to this resource.
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).

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 does not pass 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:

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


The following providers are available. Use the short name to use the provider in a recipe:

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.


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:

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

Create a system user

user "systemguy" do
  comment "system guy"
  system true
  shell "/bin/false"

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

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