Skip to content

Commit

Permalink
README update revamp 1.
Browse files Browse the repository at this point in the history
  • Loading branch information
@fnichol
fnichol committed Apr 24, 2012
1 parent 3204311 commit 68b5ba6
Showing 1 changed file with 65 additions and 63 deletions.
128 changes: 65 additions & 63 deletions README.md
View file
@@ -1,16 +1,49 @@
# Description
# <a name="title"></a> chef-user [![Build Status](https://secure.travis-ci.org/fnichol/chef-user.png?branch=master)](http://travis-ci.org/fnichol/chef-user)

## <a name="description"></a> Description

A convenient Chef LWRP to manage user accounts and SSH keys. This is **not**
the Opscode *users* cookbook.

# Requirements
## <a name="usage"></a> Usage

Simply include `recipe[user]` in your run\_list and the `user_account`
resource will be available.

To use `recipe[user::data_bag]`, include it in your run\_list and have a
data bag called `"users"` with an item like the following:

{
"id" : "hsolo",
"comment" : "Han Solo",
"home" : "/opt/hoth/hsolo",
"ssh_keys" : ["123...", "456..."]
}

or a user to be removed:

{
"id" : "lando",
"action" : "remove"
}

The data bag recipe will iterate through a list of usernames defined in
`node['users']` and attempt to pull in the user's information from the data
bag item. In other words, having:

node['users'] = ['hsolo']

will set up the `hsolo` user information and not use the `lando` user
information.

## <a name="requirements"></a> Requirements

## Chef
### <a name="requirements-chef"></a> Chef

Tested on 0.10.2 but newer and older version should work just fine. File an
Tested on 0.10.8 but newer and older version should work just fine. File an
[issue][issues] if this isn't the case.

## Platform
### <a name="requirements-platform"></a> Platform

The following platforms have been tested with this cookbook, meaning that the
recipes run on these platforms without error:
Expand All @@ -19,24 +52,24 @@ recipes run on these platforms without error:
* debian
* mac_os_x

## Cookbooks
### <a name="requirements-cookbooks"></a> Cookbooks

There are **no** external cookbook dependencies.

# Installation
## <a name="installation"></a> Installation

Depending on the situation and use case there are several ways to install
this cookbook. All the methods listed below assume a tagged version release
is the target, but omit the tags to get the head of development. A valid
Chef repository structure like the [Opscode repo][chef_repo] is also assumed.

## From the Opscode Community Platform
### <a name="installation-platform"></a> From the Opscode Community Platform

To install this cookbook from the Opscode platform, use the *knife* command:

knife cookbook site install user

## Using Librarian-Chef
### <a name="installation-librarian"></a> Using Librarian-Chef

[Librarian-Chef][librarian] is a bundler for your Chef cookbooks.
Include a reference to the cookbook in a [Cheffile][cheffile] and run
Expand All @@ -51,7 +84,7 @@ Include a reference to the cookbook in a [Cheffile][cheffile] and run
END_OF_CHEFFILE
librarian-chef install

## Using knife-github-cookbooks
### <a name="installation-kgc"></a> Using knife-github-cookbooks

The [knife-github-cookbooks][kgc] gem is a plugin for *knife* that supports
installing cookbooks directly from a GitHub repository. To install with the
Expand All @@ -61,7 +94,7 @@ plugin:
cd chef-repo
knife cookbook github install fnichol/chef-user/v0.2.10

## As a Git Submodule
### <a name="installation-gitsubmodule"></a> As a Git Submodule

A common practice (which is getting dated) is to add cookbooks as Git
submodules. This is accomplishes like so:
Expand All @@ -72,7 +105,7 @@ submodules. This is accomplishes like so:

**Note:** the head of development will be linked here, not a tagged release.

## As a Tarball
### <a name="installation-tarball"></a> As a Tarball

If the cookbook needs to downloaded temporarily just to be uploaded to a Chef
Server or Opscode Hosted Chef, then a tarball installation might fit the bill:
Expand All @@ -81,64 +114,33 @@ Server or Opscode Hosted Chef, then a tarball installation might fit the bill:
curl -Ls https://github.com/fnichol/chef-user/tarball/v0.2.10 | tar xfz - && \
mv fnichol-chef-user-* user

# Usage

Simply include `recipe[user]` in your run_list and the `user_account`
resource will be available.

To use `recipe[user::data_bag]`, include it in your run_list and have a
data bag called `"users"` with an item like the following:

{
"id" : "hsolo",
"comment" : "Han Solo",
"home" : "/opt/hoth/hsolo",
"ssh_keys" : ["123...", "456..."]
}

or a user to be removed:

{
"id" : "lando",
"action" : "remove"
}

The data bag recipe will iterate through a list of usernames defined in
`node['users']` and attempt to pull in the user's information from the data
bag item. In other words, having:

node['users'] = ['hsolo']

will set up the `hsolo` user information and not use the `lando` user
information.

# Recipes
## <a name="recipes"></a> Recipes

## default
### <a name="recipes-default"></a> default

This recipe is a no-op and does nothing.

## data_bag
### <a name="recipes-data-bag"></a> default

Processes a list of users with data drawn from a data bag. The default data bag
is `users` and the list of user account to create on this node is set on
`node['users']`.

# Attributes
## <a name="attributes"></a> Attributes

## `home_root`
### <a name="attributes-home-root"></a> home_root

The default parent path of a user's home directory. Each resource can override
this value which varies by platform. Generally speaking, the default value is
`"/home"`.

## `default_shell`
### <a name="attributes-default-shell"></a> default_shell

The default user shell given to a user. Each resource can override this value
which varies by platform. Generally speaking, the default value is
`"/bin/bash"`.

## `manage_home`
### <a name="attributes-manage-home"></a> manage_home

Whether of not to manage the home directory of a user by default. Each resource
can override this value. The are 2 valid states:
Expand All @@ -148,7 +150,7 @@ can override this value. The are 2 valid states:

The default is `true`.

## `create_user_group`
### <a name="attributes-create-user-group"></a> create_user_group

Whether or not to to create a group with the same name as the user by default.
Each resource can override this value. The are 2 valid states:
Expand All @@ -158,7 +160,7 @@ Each resource can override this value. The are 2 valid states:

The default is `true`.

## `ssh_keygen`
### <a name="attributes-ssh-keygen"></a> ssh_keygen

Whether or not to generate an SSH keypair for the user by default. Each
resource can override this value. There are 2 valid states:
Expand All @@ -170,21 +172,21 @@ resource can override this value. There are 2 valid states:

The default is `true`.

## `data_bag`
### <a name="attributes-data-bag"></a> data_bag

The data bag name containing a group of user account information. This is used
by the `data_bag` recipe to use as a database of user accounts. The default is
`"users"`.

# Resource and Providers
## <a name="lwrps"></a> Resources and Providers

## user_account
### <a name="lwrps-ua"></a> user_account

**Note:** in order to use the `password` attribute, you must have the
[ruby-shadow gem][ruby-shadow_gem] installed. On Debian/Ubuntu you can get
this by installing the "libshadow-ruby1.8" package.

## Actions
### <a name="lwrps-ua-actions"></a> Actions

Action |Description |Default
----------|------------------------------|-------
Expand All @@ -195,7 +197,7 @@ manage |Manage the user account. |
lock |Lock the user's password. |
unlock |Unlock the user's password. |

## Attributes
### <a name="lwrps-ua-attributes"></a> Attributes

Attribute |Description |Default value
------------|------------|-------------
Expand All @@ -212,37 +214,37 @@ create_group |Whether or not to to create a group with the same name as the user
ssh_keys |A **String** or **Array** of SSH public keys to populate the user's `.ssh/authorized_keys` file. |`[]`
ssh_keygen |Whether or not to generate an SSH keypair for the user. |`node['user']['ssh_keygen']`

## Examples
#### <a name="lwrps-ua-examples"></a> Examples

### Creating a User Account
##### Creating a User Account

user_account 'hsolo' do
comment 'Han Solo'
ssh_keys ['3dc348d9af8027df7b9c...', '2154d3734d609eb5c452...']
home '/opt/hoth/hsolo'
end

### Locking a User Account
##### Locking a User Account

user_account 'lando' do
action :lock
end

### Removing a User account
##### Removing a User account

user_account 'obiwan' do
action :remove
end

# Development
## <a name="development"></a> Development

* Source hosted at [GitHub][repo]
* Report issues/Questions/Feature requests on [GitHub Issues][issues]

Pull requests are very welcome! Make sure your patches are well tested.
Ideally create a topic branch for every separate change you make.

# License and Author
## <a name="license"></a> License and Author

Author:: Fletcher Nichol (<fnichol@nichol.ca>)

Expand Down

0 comments on commit 68b5ba6

Please sign in to comment.