First pass at per-command documentation

17 files changed, 432 insertions, 7 deletions

diff --git a/ipalib/plugins/cert.py b/ipalib/plugins/cert.py
index a2ecce421..17e4c46b0 100644
--- a/ipalib/plugins/cert.py
+++ b/ipalib/plugins/cert.py
@@ -20,7 +20,42 @@
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 
 """
-Command plugins for IPA-RA certificate operations.
+IPA certificate operations
+
+Implements a set of commands for managing server SSL certificates.
+
+Certificate request come in the form of a Certificate Signing Request (CSR)
+in PEM format.
+
+If using the selfsign backend then the subject in the CSR needs to match
+the subject configured in the server. The dogtag CA uses just the CN
+value of the CSR and forces the rest of the subject.
+
+A certificate is stored with a service principal and a service principal
+needs a host. So in order to request a certificate the following conditions
+must be met:
+
+* The host exists
+* The service exists (or you use the --add option to automatically add it)
+
+EXAMPLES:
+
+ Request a new certificate, add the principal:
+   ipa cert-request --add --principal=HTTP/lion.example.com example.csr
+
+ Retrieve an existing certificate:
+   ipa cert-request 1032
+
+ Revoke a certificate (see RFC 5280 for reason details):
+   ipa cert-revoke --revocation-reason=6 1032
+
+ Remove a certificate from revocation hold status:
+   ipa cert-remove-hold 1032
+
+ Check the status of a signing request:
+   ipa cert-status 10
+
+IPA currently immediately issues (or declines) all certificate requests.
 """
 
 from ipalib import api, SkipPluginModule
diff --git a/ipalib/plugins/config.py b/ipalib/plugins/config.py
index b89f17cab..b704a7a26 100644
--- a/ipalib/plugins/config.py
+++ b/ipalib/plugins/config.py
@@ -18,7 +18,38 @@
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 """
-IPA configuration
+Manage IPA configuration
+
+Manage default values tha IPA uses and some tuning parameters:
+
+ Show the current configuration:
+   ipa config-show
+
+ Modify the configuration:
+   ipa config-mod --maxusername=99
+
+The available options are:
+
+User management options:
+
+  --maxusername=INT     Max username length when creating/modifing a user
+  --homedirectory=STR   Default location of home directories (default /home)
+  --defaultshell=STR    Default shell for new users (default /bin/sh)
+  --defaultgroup=STR    Default group for new users (default ipausers)
+  --emaildomain=STR     Default e-mail domain new users
+
+Search tuning options. These impact how much data is searched through and
+how many records may be returned on a given search.
+
+  --searchtimelimit=INT Max. amount of time (sec.) for a search (-1 is
+                        unlimited)
+  --searchrecordslimit=INT Max. number of records to search (-1 is unlimited)
+
+Server Configuration.
+
+  --enable-migration=BOOL Enable migration mode
+  --subject=STR           base for certificate subjects (OU=Test,O=Example)
+
 """
 
 from ipalib import api
@@ -90,7 +121,7 @@ class config(LDAPObject):
         Bool('ipamigrationenabled?',
             cli_name='enable_migration',
             label=_('Migration mode'),
-            doc=_('Enabled migration mode'),
+            doc=_('Enable migration mode'),
         ),
         Str('ipacertificatesubjectbase?',
             cli_name='subject',
diff --git a/ipalib/plugins/dns.py b/ipalib/plugins/dns.py
index bc6c73d88..d651ec041 100644
--- a/ipalib/plugins/dns.py
+++ b/ipalib/plugins/dns.py
@@ -24,7 +24,7 @@ the BIND LDAP plugin.
 
 EXAMPLES:
 
- Add new zone;
+ Add new zone:
    ipa dns-add example.com nameserver.example.com admin@example.com
 
  Add second nameserver for example.com:
@@ -36,6 +36,9 @@ EXAMPLES:
  Add new A record for www.example.com: (random IP)
    ipa dns-add-rr example.com www A 80.142.15.2
 
+ Add new PTR record for www.example.com
+   ipa dns-add-rr 15.142.80.in-addr.arpa 2 PTR www.example.com.
+
  Show zone example.com:
    ipa dns-show example.com
 
diff --git a/ipalib/plugins/group.py b/ipalib/plugins/group.py
index 296366f6d..0f3743784 100644
--- a/ipalib/plugins/group.py
+++ b/ipalib/plugins/group.py
@@ -19,6 +19,45 @@
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 """
 Groups of users
+
+Manage groups of users. By default new groups are not Posix groups.
+You can mark it as Posix at creation time with the --posix flag and
+can promose a non-Posix group using the --posix flag in group-mod.
+Once a group is a Posix group there is no way to undo this.
+
+Every group must have a description.
+
+Posix groups must have a group id number (gid). Changing a gid is
+supported but can have impact on your file permissions.
+
+EXAMPLES:
+
+ Add a new group:
+   ipa group-add --desc='local administrators' localadmins
+
+ Add a new posix group:
+   ipa group-add --posix --desc='remote administrators' remoteadmins
+
+ Promote a non-posix group to posix:
+   ipa group-mod --posix localadmins
+
+ Create a group with a specific group ID number"
+   ipa group-add --posix --gid=500 --desc='unix admins' unixadmins
+
+ Remove a group:
+   ipa group-del unixadmins
+
+ Manage group membership, nested groups:
+   ipa group-add-member --groups=remoteadmins localadmins
+
+ Manage group membership, users:
+   ipa group-add-member --users=test1,test2 localadmins
+
+ Manage group membership, users:
+   ipa group-remove-member --users=test2 localadmins
+
+ Show a group:
+   ipa group-show localadmins
 """
 
 from ipalib import api
diff --git a/ipalib/plugins/hbac.py b/ipalib/plugins/hbac.py
index 1438ea955..0df012d49 100644
--- a/ipalib/plugins/hbac.py
+++ b/ipalib/plugins/hbac.py
@@ -18,6 +18,44 @@
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 """
 Host based access control
+
+Control who can access what services where from where. With HBAC
+you can control which users or groups of users may access a service
+or group of services, additionally restricting the source and source
+hosts.
+
+You can also control the times that the rule is active.
+
+It is possible to specify a category of users, hosts or source hosts.
+Currently this is limited to 'all' but may be expanded in the future.
+
+Hosts and source hosts must be host entries in IPA (see host plugin).
+
+EXAMPLES:
+
+ Create a new rule that grants all users access to the host 'server' from
+ anywhere:
+   ipa hbac-add --type=allow --usercat=all --srchostcat=all test1
+   ipa hbac-add-host --hosts=server.example.com test1
+
+ Show an HBAC rule:
+   ipa hbac-show test1
+
+ Add an access time to a rule:
+   ipa hbac-add-accesstime --time='periodic daily 0800-1400' test1
+   ipa hbac-add-accesstime --time='absolute 201012161032 ~ 201012161033' test1
+
+ Create a rule for a specific service. This lets the user john access
+ the sshd service on any machine from any machine:
+   ipa hbac-add --type=allow --hostcat=all --srchostcat=all john_sshd
+   ipa hbac-add-user --users=john john_sshd
+   ipa hbac-add-service --hbacsvcs=sshd john_sshd
+
+ Disable a rule:
+   ipa hbac-disable test1
+
+ Remove an HBAC rule:
+   ipa hbac-del allow_server
 """
 
 from ipalib import api, errors
diff --git a/ipalib/plugins/hbacsvc.py b/ipalib/plugins/hbacsvc.py
index f6eda165f..1879980de 100644
--- a/ipalib/plugins/hbacsvc.py
+++ b/ipalib/plugins/hbacsvc.py
@@ -18,6 +18,24 @@
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 """
 HBAC Services
+
+The PAM services that HBAC can control access to. The name used here
+must match the service name that PAM is evaluating.
+
+EXAMPLES:
+
+ Create a new service:
+   ipa hbacsvc-add tftp
+
+ Update a service:
+   ipa hbacsvc-mod --desc='TFTP service' tftp
+
+ Find a service (this will find 2, the ftp service and the new tftp service):
+   ipa hbacsvc-find ftp
+
+ Remove a service:
+   ipa hbacsvc-del tftp
+
 """
 import base64
 
diff --git a/ipalib/plugins/hbacsvcgroup.py b/ipalib/plugins/hbacsvcgroup.py
index cc0d4fd46..53a8ca460 100644
--- a/ipalib/plugins/hbacsvcgroup.py
+++ b/ipalib/plugins/hbacsvcgroup.py
@@ -18,6 +18,27 @@
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 """
 HBAC Service Groups
+
+Manage groups of services for HBAC
+
+EXAMPLES:
+ 
+ Create a group of HBAC services:
+   ipa hbacsvcgroup-add --desc="login services" login
+
+ Add some members to a HBAC service group:
+   ipa hbacsvcgroup-add-member --hbacsvcs=sshd,login login
+
+ Show a group:
+   ipa hbacsvcgroup-show login
+
+ A group can contain other groups, add a new group to login:
+   ipa hbacsvcgroup-add --desc="switch users" suers
+   ipa hbacsvcgroup-add-member --hbacsvcs=su,su-l suers
+   ipa hbacsvsgroup-add-member --hbacsvsgroups=suers login
+
+ Remove a group:
+   ipa hbacsvcgroup-del login
 """
 
 from ipalib import api, errors
diff --git a/ipalib/plugins/host.py b/ipalib/plugins/host.py
index 320cf34f7..82ef16457 100644
--- a/ipalib/plugins/host.py
+++ b/ipalib/plugins/host.py
@@ -19,6 +19,44 @@
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 """
 Hosts/Machines (Identity)
+
+A host represents a machine. It can be used in a number of contexts:
+- service entries are associated with a host
+- a host stores the host/ service principal
+- a host may be used in Host-Based Access Control (HBAC) rules
+- every enrolled client generates a host entry
+
+ENROLLMENT:
+
+There are three enrollment scenarios when enrolling a new client.
+
+1. You are enrolling as a full administrator (hostadmin rolegroup). The
+   host entry may exist or not.
+2. You are enrolling as a limited administrator (enrollhost rolegroup). The
+   host must already exist.
+3. The host has been created with a one-time password.
+
+A host may only be enrolled once. If a client has enrolled and needs to
+be re-enrolled then the host entry needs to be removed and re-created.
+Note that this will result in all services for this host being removed too,
+and all SSL certificates associated with those services to be revoked.
+
+A host can optionally store information such as where it is located,
+the OS that it runs, etc.
+
+EXAMPLES:
+
+ Create a new host
+   ipa host-add --location='3rd floor lab' --locality=Dallas test.example.com
+
+ Remove a host
+   ipa host-del test.example.com
+
+ Create a new host with a one-time password
+   ipa host-add --os='Fedora 12' --password=Secret123 test.example.com
+
+ Update information about a host
+   ipa host-mod --os='Fedora 12' test.example.com
 """
 
 import platform
diff --git a/ipalib/plugins/hostgroup.py b/ipalib/plugins/hostgroup.py
index f233e2869..fe5bed76b 100644
--- a/ipalib/plugins/hostgroup.py
+++ b/ipalib/plugins/hostgroup.py
@@ -19,6 +19,26 @@
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 """
 Groups of hosts.
+
+This is useful for Host-Based Access Control (HBAC) to group a series
+of hosts together for applying access control.
+
+EXAMPLES:
+
+ Create a new host group:
+   ipa hostgroup-add --desc='Baltimore hosts' baltimore
+
+ Add some hosts to the group:
+   ipa hostgroup-add-member --hosts=box1,box2,box3 baltimore
+
+ Remove a host from the group:
+   ipa hostgroup-remove-member --hosts=box2 baltimore
+
+ Display a host group:
+   ipa hostgroup-show baltimore
+
+ Removey a host group:
+   ipa hostgroup-del baltimore
 """
 
 from ipalib.plugins.baseldap import *
diff --git a/ipalib/plugins/krbtpolicy.py b/ipalib/plugins/krbtpolicy.py
index 3f9eeee68..2c797fd13 100644
--- a/ipalib/plugins/krbtpolicy.py
+++ b/ipalib/plugins/krbtpolicy.py
@@ -18,6 +18,21 @@
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 """
 Kerberos ticket policy
+
+There is a single kerberos ticket policy. This policy defines the
+maximum ticket lifetime (maximum life of a ticket) and maximum renewal
+age, the period during which the ticket is renewable.
+
+EXAMPLES:
+
+ Display the current policy:
+  ipa krbtpolicy-show
+
+ Reset the policy to the default:
+  ipa krbtpolicy-reset
+
+ Modify the policy to 8 hours max life, 1-day max renewal:
+  ipa krbtpolicy-mod --maxlife=28800 --maxrenew=86400
 """
 
 from ipalib import api
@@ -51,12 +66,12 @@ class krbtpolicy(LDAPObject):
         Int('krbmaxticketlife?',
             cli_name='maxlife',
             label=_('Max life'),
-            doc=_('Maximum ticket life'),
+            doc=_('Maximum ticket life (seconds)'),
         ),
         Int('krbmaxrenewableage?',
             cli_name='maxrenew',
             label=_('Max renew'),
-            doc=_('Maximum renewable age'),
+            doc=_('Maximum renewable age (seconds)'),
         ),
     )
 
diff --git a/ipalib/plugins/netgroup.py b/ipalib/plugins/netgroup.py
index 6fd0670b0..ad97c7226 100644
--- a/ipalib/plugins/netgroup.py
+++ b/ipalib/plugins/netgroup.py
@@ -19,6 +19,26 @@
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 """
 Netgroups
+
+A netgroup is a group used for permission checking. It can contain both
+user and host values.
+
+EXAMPLES:
+
+ Create a new netgroup:
+   ipa netgroup-add --desc='NFS admins' admins
+
+ Add a member to the group:
+   ipa netgroup-add-member --users=tuser1,tuser2 admins
+
+ Remove a member from the group:
+   ipa netgroup-remove-member --users=tuser2 admins
+
+ Display a netgroup:
+   ipa netgroup-show admins
+
+ Remove a netgroup:
+   ipa netgroup-del admins
 """
 
 from ipalib import api, errors
diff --git a/ipalib/plugins/passwd.py b/ipalib/plugins/passwd.py
index 50e99c248..f4f722f1e 100644
--- a/ipalib/plugins/passwd.py
+++ b/ipalib/plugins/passwd.py
@@ -17,7 +17,24 @@
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 """
-Password changes
+User password changes
+
+Sets a user password. Normally a user can only change their own password.
+
+If someone other than user changes a password (e.g. helpdesk resets it)
+then the password will need to be changed the first time it is used.
+This is so the end-user is the only one that knows the password.
+
+Password policy will control how often a password may be changed,
+what strength requirements there are and long the password history is.
+
+EXAMPLES:
+
+ Reset your own password:
+   ipa passwd
+
+ Change another user's password:
+   ipa passwd tuser1
 """
 
 from ipalib import api, errors, util
diff --git a/ipalib/plugins/pwpolicy.py b/ipalib/plugins/pwpolicy.py
index e5b605d7e..e7cfab654 100644
--- a/ipalib/plugins/pwpolicy.py
+++ b/ipalib/plugins/pwpolicy.py
@@ -18,6 +18,43 @@
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 """
 Password policy
+
+A password policy sets limitations on passwords including maximum lifetime,
+minimum lifetime, number of passwords to save in history, number of character
+classes required (for stronger passwords) and the password minimum length.
+
+By default there is a single global policy for all users. One can also
+create a password policy associate with a group. A user has only one
+password policy, either the group policy or the global policy. A group
+policy stands alone, it isn't a super-set of the global policy plus
+custom settings.
+
+Each group password policy requires a unique priority setting. If a user
+is in multiple groups that have password policies this priority determines
+which password policy is applied. The lower the value the higher the priority.
+
+A group password policy is automatically removed when the group it is
+assicated with it is removed.
+
+EXAMPLES:
+
+ Update the global policy:
+   ipa pwpolicy-mod --minlength=10
+
+ Create a group password policy:
+   ipa pwpolicy-add --maxlife=90 --minlife=1 --history=10 --minclasses=3 --minlength=8 --priority=10 localadmins
+
+ Display the global password policy:
+   ipa pwpolicy-show
+
+ Display a group password policy:
+   ipa pwpolicy-show localadmins
+ 
+ Display the policy that would be applied to a given user:
+   ipa pwpolicy-show --user=tuser1
+
+ Modify a group policy:
+   ipa pwpolicy-mod --minclasses=2 localadmins
 """
 
 from ipalib import api
diff --git a/ipalib/plugins/rolegroup.py b/ipalib/plugins/rolegroup.py
index 7038e904b..9ff3ef775 100644
--- a/ipalib/plugins/rolegroup.py
+++ b/ipalib/plugins/rolegroup.py
@@ -19,6 +19,38 @@
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 """
 Rolegroups
+
+A rolegroup is used for fine-grained delegation. Access control rules (ACIs)
+grant permission to performa a given task (add user, modify group, etc) to 
+task groups. Role groups are members of task groups, giving them permission
+to perform the task.
+
+The logic looks like this:
+
+ ACI grants permission to taskgroup
+ rolegroups are members of taskgroups
+ users, groups, hosts and hostgroups are members of role groups
+
+A host/hostgroup may be members because you may want to perform
+operations using the host service principal associated with a machine.
+
+A rolegroup may not be members of other rolegroups.
+
+EXAMPLES:
+
+ Create a new role group:
+   ipa rolegroup-add --desc="Junion level admin" junioradmin
+
+ Add this role to some tasks
+   ipa taskgroup-add-member --rolegroups=junioradmin addusers
+   ipa taskgroup-add-member --rolegroups=junioradmin change_password
+   ipa taskgroup-add-member --rolegroups=junioradmin add_user_to_default_group
+
+ Add a group of users to this role:
+   ipa rolegroup-add-member --groups=junioradmins junioradmin
+
+ Display this role group:
+   ipa rolegroup-show junioradmin
 """
 
 from ipalib.plugins.baseldap import *
diff --git a/ipalib/plugins/service.py b/ipalib/plugins/service.py
index 0a878cacc..3484e29a4 100644
--- a/ipalib/plugins/service.py
+++ b/ipalib/plugins/service.py
@@ -20,6 +20,39 @@
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 """
 Services (Identity)
+
+A service represents a running service on a host. This service record
+may store a kerberos principal or an SSL certificate (or both).
+
+A service may be managed directly by a machine, if it has been given
+the proper permission (even a machine other than the one the service is
+associated with). An example of this is requesting an SSL certificate
+using the host service principal credentials of the host.
+
+Adding a service makes it possible to request an SSL certificate or
+keytab for that service but this is done as a separate step later. The
+creation of a service in itself doesn't generate these.
+
+The certificate stored in a service is just the public portion. The
+private key is not stored.
+
+EXAMPLES:
+
+ Add a service:
+   ipa service-add HTTP/web.example.com
+
+ Allow a host to manage the service certificate:
+  ipa service-add-host --hosts=web.example.com HTTP/web.example.com
+  ipa rolegroup-add-member --hosts=web.example.com certadmin
+
+ Remove a service:
+   ipa service-del HTTP/web.example.com
+
+ Find all services for a host:
+   ipa service-find web.example.com
+
+ Find all HTTP services:
+   ipa service-find HTTP
 """
 import base64
 
diff --git a/ipalib/plugins/taskgroup.py b/ipalib/plugins/taskgroup.py
index a7360c352..e9e95448c 100644
--- a/ipalib/plugins/taskgroup.py
+++ b/ipalib/plugins/taskgroup.py
@@ -19,6 +19,12 @@
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 """
 Taskgroups
+
+A taskgroup is used for fine-grained delegation. Access control rules (ACIs)
+grant permission to performa a given task (add user, modify group, etc) to
+task groups. 
+
+A taskgroup may not be members of other taskgroups.
 """
 
 from ipalib.plugins.baseldap import *
diff --git a/ipalib/plugins/user.py b/ipalib/plugins/user.py
index f8783eca4..d72b3bb1b 100644
--- a/ipalib/plugins/user.py
+++ b/ipalib/plugins/user.py
@@ -19,6 +19,28 @@
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 """
 Users (Identity)
+
+Manage user entries.
+
+EXAMPLES:
+
+ Create a new user:
+   ipa user-add --first=Tim --last=User --passwd tuser1
+
+ Find a user Tim:
+   ipa user-find Tim
+
+ Find all users with Tim as the first name:
+   ipa user-find --first=Tim
+
+ Lock a user account:
+   ipa user-lock tuser1
+
+ Unlock a user account:
+   ipa user-unlock tuser1
+
+ Delete a user:
+   ipa user-del tuser1
 """
 
 from ipalib import api, errors