From 901ccc1393a7e494f7b1b64eaeb2f7809056aafa Mon Sep 17 00:00:00 2001 From: Rob Crittenden Date: Wed, 2 Jun 2010 14:08:50 -0400 Subject: First pass at per-command documentation --- ipalib/plugins/cert.py | 37 ++++++++++++++++++++++++++++++++++++- ipalib/plugins/config.py | 35 +++++++++++++++++++++++++++++++++-- ipalib/plugins/dns.py | 5 ++++- ipalib/plugins/group.py | 39 +++++++++++++++++++++++++++++++++++++++ ipalib/plugins/hbac.py | 38 ++++++++++++++++++++++++++++++++++++++ ipalib/plugins/hbacsvc.py | 18 ++++++++++++++++++ ipalib/plugins/hbacsvcgroup.py | 21 +++++++++++++++++++++ ipalib/plugins/host.py | 38 ++++++++++++++++++++++++++++++++++++++ ipalib/plugins/hostgroup.py | 20 ++++++++++++++++++++ ipalib/plugins/krbtpolicy.py | 19 +++++++++++++++++-- ipalib/plugins/netgroup.py | 20 ++++++++++++++++++++ ipalib/plugins/passwd.py | 19 ++++++++++++++++++- ipalib/plugins/pwpolicy.py | 37 +++++++++++++++++++++++++++++++++++++ ipalib/plugins/rolegroup.py | 32 ++++++++++++++++++++++++++++++++ ipalib/plugins/service.py | 33 +++++++++++++++++++++++++++++++++ ipalib/plugins/taskgroup.py | 6 ++++++ ipalib/plugins/user.py | 22 ++++++++++++++++++++++ 17 files changed, 432 insertions(+), 7 deletions(-) (limited to 'ipalib/plugins') 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 -- cgit