chef/cookbooks/users/metadata.json

{
  "name": "users",
  "version": "1.8.2",
  "description": "Creates users from a databag search",
  "long_description": "users Cookbook\n==============\n![Build Status](https://travis-ci.org/opscode-cookbooks/users.svg?branch=master)\n\nCreates users from a databag search.\n\n\nRequirements\n------------\n### Platforms\n- Debian, Ubuntu\n- CentOS, Red Hat, Fedora\n- FreeBSD\n\nA data bag populated with user objects must exist. The default data\nbag in this recipe is `users`. See USAGE.\n\n\nUsage\n-----\nTo include just the LWRPs in your cookbook, use:\n\n```ruby\ninclude_recipe \"users\"\n```\n\nOtherwise, this cookbook is specific for setting up `sysadmin` group and users with the sysadmins recipe for now.\n\n```ruby\ninclude_recipe \"users::sysadmins\"\n```\n\nUse knife to create a data bag for users.\n\n```bash\n$ knife data bag create users\n```\n\nCreate a user in the data_bag/users/ directory.\n\nWhen using an [Omnibus ruby](http://tickets.opscode.com/browse/CHEF-2848), one can specify an optional password hash. This will be used as the user's password.\n\nThe hash can be generated with the following command.\n\n```bash\n$ openssl 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```javascript\n{\n  \"id\": \"bofh\",\n  \"ssh_keys\": \"ssh-rsa AAAAB3Nz...yhCw== bofh\",\n}\n```\n\n```javascript\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  \"nagios\": {\n    \"pager\": \"8005551212@txt.att.net\",\n    \"email\": \"bofh@example.com\"\n  },\n  \"openid\": \"bofh.myopenid.com\"\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\n$ knife 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\", // <--\n  \"comment\": \"User violated access policy\"\n}\n```\n\nRemove a user, johndoe1.\n\n```bash\n$ knife 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\", // <--\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\nThe sysadmins recipe makes use of the `users_manage` Lightweight Resource Provider (LWRP), and looks like this:\n\n```ruby\nusers_manage \"sysadmin\" do\n  group_id 2300\n  action [ :remove, :create ]\nend\n```\n\nNote this LWRP 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 LWRP is `:create` only.\n\nIf you have different requirements, for example:\n\n * You want to search a different data bag specific to a role such as\n   mail. You may change the data_bag searched.\n   - data_bag `mail`\n * You want to search for a different group attribute named\n   `postmaster`. You may change the search_group attribute. This\n   attribute defaults to the LWRP resource name.\n   - search_group `postmaster`\n * You want to add the users to a security group other than the\n   lightweight resource name. You may change the group_name attribute.\n   This attribute also defaults to the LWRP resource name.\n   - group_name `wheel`\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\nThe latest version of 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:\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. The default search, and Unix group is sysadmin.\n\nThe recipe, by default, will also create the sysadmin group. If you're using the chef sudo cookbook, they'll have sudo access in the default site-cookbooks template. They won't have passwords though, so the sudo cookbook's template needs to be adjusted so the sysadmin group has NOPASSWD.\n\nThe sysadmin group will be created with GID 2300. This may become an attribute at a later date.\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\nChef Solo\n---------\nAs of version 1.4.0, this cookbook might work with Chef Solo when using [chef-solo-search by edelight](https://github.com/edelight/chef-solo-search). That cookbook is not a dependency of this one as Chef solo doesn't support dependency resolution using cookbook metadata - all cookbooks must be provided to the node manually when using Chef Solo.\n\n\nLicense & Authors\n-----------------\n- Author:: Joshua Timberman (<joshua@chef.io>)\n- Author:: Seth Chisamore (<schisamo@chef.io>)\n\n```text\nCopyright:: 2009-2015, Chef Software, Inc\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```\n",
  "source_url": "https://github.com/opscode-cookbooks/users",
  "issues_url": "https://github.com/opscode-cookbooks/users/issues",
  "maintainer": "Chef Software, Inc.",
  "maintainer_email": "cookbooks@chef.io",
  "license": "Apache 2.0",
  "platforms": {
    "ubuntu": ">= 0.0.0",
    "debian": ">= 0.0.0",
    "redhat": ">= 0.0.0",
    "centos": ">= 0.0.0",
    "fedora": ">= 0.0.0",
    "freebsd": ">= 0.0.0",
    "mac_os_x": ">= 0.0.0"
  },
  "dependencies": {
  },
  "recommendations": {
  },
  "suggestions": {
  },
  "conflicting": {
  },
  "providing": {
  },
  "replacing": {
  },
  "attributes": {
  },
  "groupings": {
  },
  "recipes": {
    "users": "Empty recipe for including LWRPs",
    "users::sysadmins": "Create and manage sysadmin group"
  }
}