{"id":13781441,"url":"https://github.com/sous-chefs/users","last_synced_at":"2025-04-05T04:14:15.389Z","repository":{"id":2725797,"uuid":"3720714","full_name":"sous-chefs/users","owner":"sous-chefs","description":"Development repository for the users cookbook","archived":false,"fork":false,"pushed_at":"2024-07-15T17:11:46.000Z","size":475,"stargazers_count":138,"open_issues_count":7,"forks_count":217,"subscribers_count":42,"default_branch":"main","last_synced_at":"2024-10-29T20:23:21.586Z","etag":null,"topics":["chef","chef-cookbook","chef-resource","hacktoberfest","managed-by-terraform","users"],"latest_commit_sha":null,"homepage":"https://supermarket.chef.io/cookbooks/users","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sous-chefs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"open_collective":"sous-chefs"}},"created_at":"2012-03-14T18:22:55.000Z","updated_at":"2024-07-15T17:11:49.000Z","dependencies_parsed_at":"2024-11-06T02:05:04.568Z","dependency_job_id":"73fc5b8f-3bcf-4868-bf3f-eea606932acd","html_url":"https://github.com/sous-chefs/users","commit_stats":{"total_commits":484,"total_committers":66,"mean_commits":7.333333333333333,"dds":0.7768595041322314,"last_synced_commit":"d084e0a30a93fb9cd5f7b92cd69f3923817d6a28"},"previous_names":[],"tags_count":61,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sous-chefs%2Fusers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sous-chefs%2Fusers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sous-chefs%2Fusers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sous-chefs%2Fusers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sous-chefs","download_url":"https://codeload.github.com/sous-chefs/users/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247284953,"owners_count":20913704,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chef","chef-cookbook","chef-resource","hacktoberfest","managed-by-terraform","users"],"created_at":"2024-08-03T18:01:26.011Z","updated_at":"2025-04-05T04:14:15.357Z","avatar_url":"https://github.com/sous-chefs.png","language":"Ruby","readme":"# users Cookbook\n\n[![Cookbook Version](https://img.shields.io/cookbook/v/users.svg)](https://supermarket.chef.io/cookbooks/users)\n[![CI State](https://github.com/sous-chefs/users/workflows/ci/badge.svg)](https://github.com/sous-chefs/users/actions?query=workflow%3Aci)\n[![OpenCollective](https://opencollective.com/sous-chefs/backers/badge.svg)](#backers)\n[![OpenCollective](https://opencollective.com/sous-chefs/sponsors/badge.svg)](#sponsors)\n[![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](https://opensource.org/licenses/Apache-2.0)\n\nManages OS users and groups (optionally from databags).\n\n## Scope\n\nThis cookbook is concerned with the management of OS users and groups (optionally from databags). It also manages the distribution of ssh keys to a user's home directory.\n\n## Maintainers\n\nThis 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](https://sous-chefs.org/) or come chat with us on the Chef Community Slack in [#sous-chefs](https://chefcommunity.slack.com/messages/C2V7B88SF).\n\n## Requirements\n\nIf you are upgrading from a version \u003c 6.0.0 please see [upgrading.md](https://github.com/sous-chefs/users/upgrading.md)\n\n### Platforms\n\nThe following platforms have been tested with Test Kitchen:\n\n- Debian / Ubuntu derivatives\n- RHEL and derivatives\n- Fedora\n- openSUSE / SUSE Linux Enterprises\n- FreeBSD / OpenBSD\n- macOS\n- AIX\n\n### Chef\n\n- Chef 12.7+\n\n### Cookbooks\n\n- none\n\n## Usage\n\nTo 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](https://docs.chef.io/config_rb_metadata.html):\n\n```\ndepends 'users'\n```\n\nor to pin to a specific version of the users cookbook, in this case any version of 6.X:\n\n```\ndepends 'users', '~\u003e 6'\n```\n\nThen in a recipe use the `user_manage` resource to add all users in the defined group to the system:\n\n```ruby\nusers_variable = [{\n  id: 'databag_test_user',\n  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\",\n  groups: [ 'GROUPNAME' ],\n}]\n\nusers_manage 'GROUPNAME' do\n  group_id GROUPID\n  action [:create]\n  users users_variable\nend\n```\n\nExample:\n\n```ruby\nusers_manage 'testgroup' do\n  group_id 3000\n  action [:create]\n  users node['users']['array_of_users']\nend\n```\n\n**Note**: The users property needs to be given an Array of Hashes that contains one user per hash. This can be done by passing a data bag like the example below or from any other source.\n\n### Databag Definition\n\nThis is an alternative to the attribute definition as mentioned below.\n\nYou could for instance create a databag called `users`. You then create a subdatabag for each user object.\n\nA sample user object in a users databag would look like:\n\n```json\n{\n  \"id\": \"test_user\",\n  \"password\": \"$1$5cE1rI/9$4p0fomh9U4kAI23qUlZVv/\",\n  \"ssh_keys\": [\n    \"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\",\n    \"ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAklOUpkDHrfHY17SbrmTIpNLTGK9Tjom/BWDSU\\nGPl+nafzlHDTYW7hdI4yZ5ew18JH4JW9jbhUFrviQzM7xlELEVf4h9lFX5QVkbPppSwg0cda3\\nPbv7kOdJ/MTyBlWXFCR+HAo3FXRitBqxiX1nKhXpHAZsMciLq8V6RjsNAQwdsdMFvSlVK/7XA\\nt3FaoJoAsncM1Q9x5+3V0Ww68/eIFmb1zuUFljQJKprrX88XypNDvjYNby6vw/Pb0rwert/En\\nmZ+AW4OZPnTPI89ZPmVMLuayrD2cE86Z/il8b+gw3r3+1nKatmIkjn2so1d01QraTlMqVSsbx\\nNQCPO0ZZEa1== chefuser@mylaptop.local\"\n  ],\n  \"groups\": [ \"testgroup\", \"nfsgroup\" ],\n  \"uid\": 9001,\n  \"shell\": \"\\/bin\\/bash\",\n  \"comment\": \"Test User\"\n}\n```\n\nA sample user to remove from a system would like like:\n\n```json\n{\n  \"id\": \"mwaddams\",\n  \"action\": \"remove\",\n  \"groups\": [ \"testgroup\", \"nfsgroup\" ]\n}\n```\n\n### Attributes Definition\n\nThis is an alternative to the data bag definition as mentioned above.\n\nConsider having a cookbook called `usermanagement` where you include this `users` cookbook.\n\nYou could then set the attributes like this:\n\n```ruby\ndefault['usermanagement']['users'] = [\n  {\n    id: 'test_user',\n    password: '$1$5cE1rI/9$4p0fomh9U4kAI23qUlZVv/',\n    ssh_keys: [\n      \"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\",\n      \"ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAklOUpkDHrfHY17SbrmTIpNLTGK9Tjom/BWDSU\\nGPl+nafzlHDTYW7hdI4yZ5ew18JH4JW9jbhUFrviQzM7xlELEVf4h9lFX5QVkbPppSwg0cda3\\nPbv7kOdJ/MTyBlWXFCR+HAo3FXRitBqxiX1nKhXpHAZsMciLq8V6RjsNAQwdsdMFvSlVK/7XA\\nt3FaoJoAsncM1Q9x5+3V0Ww68/eIFmb1zuUFljQJKprrX88XypNDvjYNby6vw/Pb0rwert/En\\nmZ+AW4OZPnTPI89ZPmVMLuayrD2cE86Z/il8b+gw3r3+1nKatmIkjn2so1d01QraTlMqVSsbx\\nNQCPO0ZZEa1== chefuser@mylaptop.local\"\n    ],\n    groups: %w(testgroup nfsgroup),\n    uid: 9001,\n    shell: '/bin/bash',\n    comment: 'Test User'\n  },\n  {\n     id: 'mwaddams',\n     action: 'remove',\n     groups: %w(testgroup nfsgroup)\n  }\n]\n```\n\n## User Key Definitions\n\n- `id`: _String_ specifies the username, as well as the data bag object id.\n- `password`: _String_ specifies the user's password.\n- `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.\n- `groups`: _Array_ an array of groups that the user will be added to\n- `uid`: _Integer_ a unique identifier for the user\n- `shell`: _String_ the user's shell\n- `comment`:_String_ the [GECOS field](https://en.wikipedia.org/wiki/Gecos_field), generally the User's full name.\n\nOther potential fields (optional):\n\n- `home`: _String_ User's home directory. If not assigned, will be set based on platform and username.\n- `manage_home`: _True, False_ Creates/removes the home directory. Defaults to false.\n- `homedir_mode`: _String, Integer_ Modifies a user's home directory permissions.\n- `no_user_group`: _True, False_ Specifies if the user needs to get a group with the name of the users. Defaults to false.\n- `action`: _String_ Supported actions are one's supported by the [user](https://docs.chef.io/resource_user.html#actions) resource. If not specified, the default action is `create`.\n- `ssh_private_key`: _String_ manages user's private key generally ~/.ssh/id_*\n- `ssh_public_key`: _String_ manages user's public key generally ~/.ssh/id_*.pub\n- `authorized_keys_file`: _String_ a nonstandard location for the authorized_keys file\n- `gid`: _String, Integer_ Specifies the primary group of a user by the gid number or the group name. If `gid` is an integer and no `primary_group` is specified than the gid will be assigned to the username group, if applicable. The group will be created if it doesn't exist.\n- `primary_group`: _String_ To be used in combination with the `gid` field when the `gid` is an integer. Specifying the group name prevents errors where the user is created before their primary group.\n- `system`: _True, False_ Specifies if a user is a system account. See the `-r` option of `useradd`.\n\n## Resources Overview\n\n### users_manage\n\nThe `users_manage` resource manages users and groups based off the `users` property or of a data bag search and the specified action(s).\n\n#### Examples\n\nCreates the `sysadmin` group and users defined in the `users` databag.\n\n```ruby\n# Get the users from the data bag\nusers_from_databag = search('users', '*:*')\n\nusers_manage 'sysadmin' do\n  group_id 2300\n  action [:create]\n  users users_from_databag\nend\n```\n\nCreates the `testgroup` group, and users defined in the `test_home_dir` attribute.\n\n```ruby\nusers_manage 'testgroup' do\n  group_id 3000\n  action [:create]\n  users node['test_home_dir']\nend\n```\n\nCreates the `nfsgroup` group, and users defined in the `test_home_dir` local variable and does not manage nfs home directories.\n\n```ruby\nusers_manage 'nfsgroup' do\n  group_id 4000\n  action [:create]\n  users test_home_dir\n  manage_nfs_home_dirs false\nend\n```\n\n#### Parameters\n\n- `users` _Array_ This is the source of the users. It needs to be an array of hashes, where each hash represents its own user. You can use data bags, attributes or something different here.\n- `group_name` _String_ name of the group to create, defaults to resource name\n- `group_id` _Integer_ numeric id of the group to create, default is to allow the OS to pick next\n- `cookbook` _String_ name of the cookbook that the authorized_keys template should be found in\n- `manage_nfs_home_dirs` _Boolean_ whether to manage nfs home directories.\n- `system` _True, False_ Specifies if a group is a system group. See the `-r` option of `groupadd`.\n\n**Reminder**\n`users_manage` module will only create the user as long as the user's group (`groups` array) in the attribute or databag includes the users_manage's group name.\n\n## Recipe Overview\n\nRecipes are not directly used. Please include the `users_manage` resource directly in your cookbook.\n\n## Data bag Overview\n\n**Reminder** You do not have to use data bags, you can also pass the users directly to the resource from a different source as explained above.\n\n**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.\n\nUse knife to create a data bag for users.\n\n```bash\nknife data bag create users\n```\n\nCreate a user in the data_bag/users/ directory.\n\nAn optional password hash can be specified that will be used as the user's password.\n\nThe hash can be generated with the following command.\n\n```bash\nopenssl passwd -1 \"plaintextpassword\"\n```\n\nNote: The ssh_keys attribute below can be either a String or an Array. However, we are recommending the use of an Array.\n\n```json\n{\n  \"id\": \"bofh\",\n  \"ssh_keys\": \"ssh-rsa AAAAB3Nz...yhCw== bofh\"\n}\n```\n\n```json\n{\n  \"id\": \"bofh\",\n  \"password\": \"$1$d...HgH0\",\n  \"ssh_keys\": [\n    \"ssh-rsa AAA123...xyz== foo\",\n    \"ssh-rsa AAA456...uvw== bar\"\n  ],\n  \"groups\": [ \"sysadmin\", \"dba\", \"devops\" ],\n  \"uid\": 2001,\n  \"shell\": \"\\/bin\\/bash\",\n  \"comment\": \"BOFH\"\n}\n```\n\nYou can pass any action listed in the [user](http://docs.chef.io/chef/resources.html#user) resource for Chef via the \"action\" option. For Example:\n\nLock a user, johndoe1.\n\n```bash\nknife data bag edit users johndoe1\n```\n\nAnd then change the action to \"lock\":\n\n```javascript\n{\n  \"id\": \"johndoe1\",\n  \"groups\": [\"sysadmin\", \"dba\", \"devops\"],\n  \"uid\": 2002,\n  \"action\": \"lock\", // \u003c--\n  \"comment\": \"User violated access policy\"\n}\n```\n\nRemove a user, johndoe1.\n\n```bash\nknife data bag edit users johndoe1\n```\n\nAnd then change the action to \"remove\":\n\n```javascript\n{\n  \"id\": \"johndoe1\",\n  \"groups\": [ \"sysadmin\", \"dba\", \"devops\" ],\n  \"uid\": 2002,\n  \"action\": \"remove\", // \u003c--\n  \"comment\": \"User quit, retired, or fired.\"\n}\n```\n\n- Note only user bags with the \"action : remove\" and a search-able \"group\" attribute will be purged by the :remove action.\n- 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](https://docs.chef.io/resource_user.html) 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.\n\nIf you have different requirements, for example:\n\n- You want to search a different data bag specific to a role such as mail. You may change the `data_bag` searched.\n\n  ```ruby\n  data_bag `mail`\n  ```\n\n- 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.\n\n  ```ruby\n  search_group `postmaster`\n  ```\n\n- 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.\n\n  ```ruby\n  group_name `wheel`\n  ```\n\nPutting these requirements together our recipe might look like this:\n\n```ruby\nusers_manage \"postmaster\" do\n  data_bag \"mail\"\n  group_name \"wheel\"\n  group_id 10\nend\n```\n\nKnife 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:\n\n```bash\n$ mkdir data_bags/users\n$EDITOR data_bags/users/bofh.json\n```\n\nPaste 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.\n\nThe 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.\n\n## Contributors\n\nThis project exists thanks to all the people who [contribute.](https://opencollective.com/sous-chefs/contributors.svg?width=890\u0026button=false)\n\n### Backers\n\nThank you to all our backers!\n\n![https://opencollective.com/sous-chefs#backers](https://opencollective.com/sous-chefs/backers.svg?width=600\u0026avatarHeight=40)\n\n### Sponsors\n\nSupport this project by becoming a sponsor. Your logo will show up here with a link to your website.\n\n![https://opencollective.com/sous-chefs/sponsor/0/website](https://opencollective.com/sous-chefs/sponsor/0/avatar.svg?avatarHeight=100)\n![https://opencollective.com/sous-chefs/sponsor/1/website](https://opencollective.com/sous-chefs/sponsor/1/avatar.svg?avatarHeight=100)\n![https://opencollective.com/sous-chefs/sponsor/2/website](https://opencollective.com/sous-chefs/sponsor/2/avatar.svg?avatarHeight=100)\n![https://opencollective.com/sous-chefs/sponsor/3/website](https://opencollective.com/sous-chefs/sponsor/3/avatar.svg?avatarHeight=100)\n![https://opencollective.com/sous-chefs/sponsor/4/website](https://opencollective.com/sous-chefs/sponsor/4/avatar.svg?avatarHeight=100)\n![https://opencollective.com/sous-chefs/sponsor/5/website](https://opencollective.com/sous-chefs/sponsor/5/avatar.svg?avatarHeight=100)\n![https://opencollective.com/sous-chefs/sponsor/6/website](https://opencollective.com/sous-chefs/sponsor/6/avatar.svg?avatarHeight=100)\n![https://opencollective.com/sous-chefs/sponsor/7/website](https://opencollective.com/sous-chefs/sponsor/7/avatar.svg?avatarHeight=100)\n![https://opencollective.com/sous-chefs/sponsor/8/website](https://opencollective.com/sous-chefs/sponsor/8/avatar.svg?avatarHeight=100)\n![https://opencollective.com/sous-chefs/sponsor/9/website](https://opencollective.com/sous-chefs/sponsor/9/avatar.svg?avatarHeight=100)\n","funding_links":["https://opencollective.com/sous-chefs"],"categories":["Resources"],"sub_categories":["User Management/Authorization"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsous-chefs%2Fusers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsous-chefs%2Fusers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsous-chefs%2Fusers/lists"}