From 4b6b710ba6ce75ffcb9ced43acee0d55adb6163c Mon Sep 17 00:00:00 2001 From: Rob Crittenden Date: Tue, 24 Aug 2010 23:40:32 -0400 Subject: Update command documentation based on feedback from docs team. ticket #158 --- ipalib/plugins/aci.py | 54 +++++++++++++++++++++++++--------- ipalib/plugins/cert.py | 17 ++++++----- ipalib/plugins/config.py | 14 ++++----- ipalib/plugins/dns.py | 8 ++--- ipalib/plugins/group.py | 42 +++++++++++++++------------ ipalib/plugins/hbac.py | 66 +++++++++++++++++++++++------------------- ipalib/plugins/hbacsvc.py | 17 ++++++----- ipalib/plugins/hbacsvcgroup.py | 30 ++++++++++--------- ipalib/plugins/host.py | 46 +++++++++++++++-------------- ipalib/plugins/hostgroup.py | 32 +++++++++++--------- ipalib/plugins/krbtpolicy.py | 14 ++++----- ipalib/plugins/netgroup.py | 26 ++++++++--------- ipalib/plugins/passwd.py | 16 +++++----- ipalib/plugins/pwpolicy.py | 42 ++++++++++++++------------- ipalib/plugins/rolegroup.py | 45 +++++++++++++++------------- ipalib/plugins/service.py | 56 ++++++++++++++++++++--------------- ipalib/plugins/taskgroup.py | 20 +++++++------ ipalib/plugins/user.py | 26 ++++++++++------- 18 files changed, 323 insertions(+), 248 deletions(-) (limited to 'ipalib/plugins') diff --git a/ipalib/plugins/aci.py b/ipalib/plugins/aci.py index b6b40e260..ae1c40058 100644 --- a/ipalib/plugins/aci.py +++ b/ipalib/plugins/aci.py @@ -20,41 +20,67 @@ """ Directory Server Access Control Instructions (ACIs) -ACI's are used to allow or deny access to information. This module is -currently designed to allow, not deny, access, primarily write access. +ACIs are used to allow or deny access to information. This module is +currently designed to allow, not deny, access. -The primary use of this plugin is to create low-level permission sets -to allow a group to write or update entries or a set of attributes. This -may include adding or removing entries as well. These groups are called -taskgroups. These low-level permissions can be combined into roles -that grant broader access. These roles are another type of group, rolegroups. +The aci commands are designed to grant permissions that allow updating +existing entries or adding or deleting new ones. The goal of the ACIs +that ship with IPA is to provide a set of low-level permissions that +grant access to special groups called taskgroups. These low-level +permissions can be combined into roles that grant broader access. These +roles are another type of group, rolegroups. For example, if you have taskgroups that allow adding and modifying users you could create a rolegroup, useradmin. You would assign users to the useradmin rolegroup to allow them to do the operations defined by the taskgroups. -You can create ACIs that delegate permission so users in -group A can write attributes on group B. +You can create ACIs that delegate permission so users in group A can write +attributes on group B. The type option is a map that applies to all entries in the users, groups or host location. It is primarily designed to be used when granting add permissions (to write new entries). +An ACI consists of three parts: +1. target +2. permissions +3. bind rules + +The target is a set of rules that define which LDAP objects are being +targetted. This can include a list of attributes, an area of that LDAP +tree or an LDAP filter. + +The permissions define what the ACI is allowed to do, they are one or more +of: +1. write - write one or more attributes +2. read - read one or more attributes +3. add - add a new entry to the tree +4. delete - delete an existing entry +5. all - all permissions are granted + +Note the distinction between attributes and entries. The permissions are +independent, so being able to add a user does not mean that the user will +be editabe. + +The bind rule defines who this ACI grants permissions to. The LDAP server +allows this to be any valid LDAP entry but we encourage the use of +taskgroups so that the rights can be easily shared through rolegroups. + For a more thorough description of access controls see http://www.redhat.com/docs/manuals/dir-server/ag/8.0/Managing_Access_Control.html EXAMPLES: - Add an ACI so the group 'secretaries' can update the address on any user: + Add an ACI so that the group "secretaries" can update the address on any user: ipa aci-add --attrs=streetAddress --memberof=ipausers --group=secretaries --permissions=write "Secretaries write addresses" Show the new ACI: ipa aci-show "Secretaries write addresses" - Add an ACI that allows members of the 'addusers' taskgroup to add new users: + Add an ACI that allows members of the "addusers" taskgroup to add new users: ipa aci-add --type=user --taskgroup=addusers --permissions=add "Add new users" -The show command will show the raw DS ACI. +The show command shows the raw 389-ds ACI. IMPORTANT: When modifying the target attributes of an existing ACI you must include all existing attributes as well. When doing an aci-mod the @@ -77,7 +103,7 @@ _type_map = { } _valid_permissions_values = [ - u'read', u'write', u'add', u'delete', u'selfwrite', u'all' + u'read', u'write', u'add', u'delete', u'all' ] class ListOfACI(output.Output): @@ -279,7 +305,7 @@ class aci(Object): cli_name='permissions', label=_('Permissions'), doc=_('comma-separated list of permissions to grant' \ - '(read, write, add, delete, selfwrite, all)'), + '(read, write, add, delete, all)'), normalizer=_normalize_permissions, ), List('attrs?', diff --git a/ipalib/plugins/cert.py b/ipalib/plugins/cert.py index 8920cfe4f..1154e2e30 100644 --- a/ipalib/plugins/cert.py +++ b/ipalib/plugins/cert.py @@ -24,7 +24,7 @@ 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) +Certificate request exist 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 @@ -32,15 +32,16 @@ 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: +needs a host. -* The host exists -* The service exists (or you use the --add option to automatically add it) +In order to request a certificate: + +* The host must exist +* The service must exist (or you use the --add option to automatically add it) EXAMPLES: - Request a new certificate, add the principal: + Request a new certificate and add the principal: ipa cert-request --add --principal=HTTP/lion.example.com example.csr Retrieve an existing certificate: @@ -55,7 +56,9 @@ EXAMPLES: Check the status of a signing request: ipa cert-status 10 -IPA currently immediately issues (or declines) all certificate requests. +IPA currently immediately issues (or declines) all certificate requests so +the status of a request is not normally useful. This is for future-use +or the case where a CA does not immediately issue a certificate. """ from ipalib import api, SkipPluginModule diff --git a/ipalib/plugins/config.py b/ipalib/plugins/config.py index b704a7a26..8b6095f74 100644 --- a/ipalib/plugins/config.py +++ b/ipalib/plugins/config.py @@ -18,14 +18,14 @@ # along with this program; if not, write to the Free Software # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA """ -Manage IPA configuration +Manage the IPA configuration -Manage default values tha IPA uses and some tuning parameters: +Manage the default values tha IPA uses and some of its tuning parameters. - Show the current configuration: + To show the current configuration: ipa config-show - Modify the configuration: + To modify the configuration: ipa config-mod --maxusername=99 The available options are: @@ -48,7 +48,7 @@ how many records may be returned on a given search. Server Configuration. --enable-migration=BOOL Enable migration mode - --subject=STR base for certificate subjects (OU=Test,O=Example) + --subject=STR Base for certificate subjects (OU=Test,O=Example) """ @@ -126,7 +126,7 @@ class config(LDAPObject): Str('ipacertificatesubjectbase?', cli_name='subject', label=_('Certificate Subject base'), - doc=_('base for certificate subjects (OU=Test,O=Example)'), + doc=_('Base for certificate subjects (OU=Test,O=Example)'), ), ) @@ -153,7 +153,7 @@ api.register(config_mod) class config_show(LDAPRetrieve): """ - Display configuration options. + Show the current configuration. """ api.register(config_show) diff --git a/ipalib/plugins/dns.py b/ipalib/plugins/dns.py index d651ec041..b154b5dff 100644 --- a/ipalib/plugins/dns.py +++ b/ipalib/plugins/dns.py @@ -17,10 +17,10 @@ # along with this program; if not, write to the Free Software # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA """ -Domain Name System (DNS) plugin +Domain Name System (DNS) plug-in Implements a set of commands useful for manipulating DNS records used by -the BIND LDAP plugin. +the BIND LDAP plug-in. EXAMPLES: @@ -42,10 +42,10 @@ EXAMPLES: Show zone example.com: ipa dns-show example.com - Find zone with 'example' in it's domain name: + Find zone with "example" in it's domain name: ipa dns-find example - Find records for resources with 'www' in their name in zone example.com: + Find records for resources with "www" in their name in zone example.com: ipa dns-find-rr example.com www Find A records for resource www in zone example.com diff --git a/ipalib/plugins/group.py b/ipalib/plugins/group.py index 9bf5b1de8..616eff2a7 100644 --- a/ipalib/plugins/group.py +++ b/ipalib/plugins/group.py @@ -20,43 +20,49 @@ """ 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. +Manage groups of users. By default, new groups are not POSIX groups. You +can add the --posix to the group-add command to mark a new group +as POSIX, and you can use the same argument to the group-mod command to +convert a non-POSIX group to a POSIX group. POSIX groups cannot be +converted to non-POSIX groups. 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. +POSIX groups must have a Group ID number (GID). Changing a GID is +supported but can have impact on your file permissions. It is not necessary +to supply a GID when creating a group. IPA will generate one automatically +if it is not provided. EXAMPLES: Add a new group: ipa group-add --desc='local administrators' localadmins - Add a new posix group: + Add a new POSIX group: ipa group-add --posix --desc='remote administrators' remoteadmins - Promote a non-posix group to posix: + Convert a non-POSIX group to posix: ipa group-mod --posix localadmins - Create a group with a specific group ID number" + Add a new POSIX group with a specific Group ID number: ipa group-add --posix --gid=500 --desc='unix admins' unixadmins + Add a new POSIX group and let IPA assign a Group ID number: + ipa group-add --posix --desc='printer admins' printeradmins + Remove a group: ipa group-del unixadmins - Manage group membership, nested groups: + To add the "remoteadmins" group to the "localadmins" group: ipa group-add-member --groups=remoteadmins localadmins - Manage group membership, users: + Add a list of users to the "localadmins" group: ipa group-add-member --users=test1,test2 localadmins - Manage group membership, users: + Remove a user from the "localadmins" group: ipa group-remove-member --users=test2 localadmins - Show a group: + Display information about a named group. ipa group-show localadmins """ @@ -122,7 +128,7 @@ api.register(group) class group_add(LDAPCreate): """ - Create new group. + Create a new group. """ msg_summary = _('Added group "%(value)s"') @@ -176,7 +182,7 @@ api.register(group_del) class group_mod(LDAPUpdate): """ - Modify group. + Modify a group. """ msg_summary = _('Modified group "%(value)s"') @@ -218,7 +224,7 @@ api.register(group_find) class group_show(LDAPRetrieve): """ - Display group. + Display information about a named group. """ api.register(group_show) @@ -226,7 +232,7 @@ api.register(group_show) class group_add_member(LDAPAddMember): """ - Add members to group. + Add members to a group. """ api.register(group_add_member) @@ -234,7 +240,7 @@ api.register(group_add_member) class group_remove_member(LDAPRemoveMember): """ - Remove members from group. + Remove members from a group. """ api.register(group_remove_member) diff --git a/ipalib/plugins/hbac.py b/ipalib/plugins/hbac.py index 0df012d49..4d7681c48 100644 --- a/ipalib/plugins/hbac.py +++ b/ipalib/plugins/hbac.py @@ -17,32 +17,40 @@ # along with this program; if not, write to the Free Software # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA """ -Host based access control +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. +Control who can access what services on what hosts and from where. You +can use HBAC to control which users or groups on a source host can +access a service, or group of services, on a target host. You can also +control the times that the rule is active. -You can also control the times that the rule is active. +You can also specify a category of users, target hosts, and source +hosts. This is currently limited to "all", but might be expanded in the +future. -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. +The access time(s) of a host are cumulative and are not guaranteed to be +applied in the order displayed. -Hosts and source hosts must be host entries in IPA (see host plugin). +Target hosts and source hosts in HBAC rules must be hosts managed by IPA. + +The available services and groups of services are controlled by the +hbacsvc and hbacsvcgroup plug-ins respectively. EXAMPLES: - Create a new rule that grants all users access to the host 'server' from + Create a rule, "test1", 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: + Display the properties of a named HBAC rule: ipa hbac-show test1 - Add an access time to a rule: + Specify that the rule "test1" be active every day between 0800 and 1400: ipa hbac-add-accesstime --time='periodic daily 0800-1400' test1 + + Specify that the rule "test1" be active once, from 10:32 until 10:33 on + December 16, 2010: ipa hbac-add-accesstime --time='absolute 201012161032 ~ 201012161033' test1 Create a rule for a specific service. This lets the user john access @@ -51,10 +59,10 @@ EXAMPLES: ipa hbac-add-user --users=john john_sshd ipa hbac-add-service --hbacsvcs=sshd john_sshd - Disable a rule: + Disable a named HBAC rule: ipa hbac-disable test1 - Remove an HBAC rule: + Remove a named HBAC rule: ipa hbac-del allow_server """ @@ -186,7 +194,7 @@ api.register(hbac) class hbac_add(LDAPCreate): """ - Create new HBAC rule. + Create a new HBAC rule. """ def pre_callback(self, ldap, dn, entry_attrs, attrs_list, *keys, **options): if not dn.startswith('cn='): @@ -203,7 +211,7 @@ api.register(hbac_add) class hbac_del(LDAPDelete): """ - Delete HBAC rule. + Delete an HBAC rule. """ api.register(hbac_del) @@ -211,7 +219,7 @@ api.register(hbac_del) class hbac_mod(LDAPUpdate): """ - Modify HBAC rule. + Modify an HBAC rule. """ api.register(hbac_mod) @@ -227,7 +235,7 @@ api.register(hbac_find) class hbac_show(LDAPRetrieve): """ - Dispaly HBAC rule. + Display the properties of an HBAC rule. """ api.register(hbac_show) @@ -235,7 +243,7 @@ api.register(hbac_show) class hbac_enable(LDAPQuery): """ - Enable HBAC rule. + Enable an HBAC rule. """ def execute(self, cn): ldap = self.obj.backend @@ -259,7 +267,7 @@ api.register(hbac_enable) class hbac_disable(LDAPQuery): """ - Disable HBAC rule. + Disable an HBAC rule. """ def execute(self, cn): ldap = self.obj.backend @@ -283,7 +291,7 @@ api.register(hbac_disable) class hbac_add_accesstime(LDAPQuery): """ - Add access time to HBAC rule. + Add an access time to an HBAC rule. """ takes_options = ( @@ -360,7 +368,7 @@ api.register(hbac_remove_accesstime) class hbac_add_user(LDAPAddMember): """ - Add users and groups affected by HBAC rule. + Add users and groups to an HBAC rule. """ member_attributes = ['memberuser'] member_count_out = ('%i object added.', '%i objects added.') @@ -370,7 +378,7 @@ api.register(hbac_add_user) class hbac_remove_user(LDAPRemoveMember): """ - Remove users and groups affected by HBAC rule. + Remove users and groups from an HBAC rule. """ member_attributes = ['memberuser'] member_count_out = ('%i object removed.', '%i objects removed.') @@ -380,7 +388,7 @@ api.register(hbac_remove_user) class hbac_add_host(LDAPAddMember): """ - Add hosts and hostgroups affected by HBAC rule. + Add target hosts and hostgroups to an HBAC rule """ member_attributes = ['memberhost'] member_count_out = ('%i object added.', '%i objects added.') @@ -390,7 +398,7 @@ api.register(hbac_add_host) class hbac_remove_host(LDAPRemoveMember): """ - Remove hosts and hostgroups affected by HBAC rule. + Remove target hosts and hostgroups from a HBAC rule. """ member_attributes = ['memberhost'] member_count_out = ('%i object removed.', '%i objects removed.') @@ -400,7 +408,7 @@ api.register(hbac_remove_host) class hbac_add_sourcehost(LDAPAddMember): """ - Add source hosts and hostgroups affected by HBAC rule. + Add source hosts and hostgroups from a HBAC rule. """ member_attributes = ['sourcehost'] member_count_out = ('%i object added.', '%i objects added.') @@ -410,7 +418,7 @@ api.register(hbac_add_sourcehost) class hbac_remove_sourcehost(LDAPRemoveMember): """ - Remove source hosts and hostgroups affected by HBAC rule. + Remove source hosts and hostgroups from an HBAC rule. """ member_attributes = ['sourcehost'] member_count_out = ('%i object removed.', '%i objects removed.') @@ -420,7 +428,7 @@ api.register(hbac_remove_sourcehost) class hbac_add_service(LDAPAddMember): """ - Add services affected by HBAC rule. + Add services to an HBAC rule. """ member_attributes = ['memberservice'] member_count_out = ('%i object added.', '%i objects added.') @@ -430,7 +438,7 @@ api.register(hbac_add_service) class hbac_remove_service(LDAPRemoveMember): """ - Remove source hosts and hostgroups affected by HBAC rule. + Remove source hosts and hostgroups from an HBAC rule. """ member_attributes = ['memberservice'] member_count_out = ('%i object removed.', '%i objects removed.') diff --git a/ipalib/plugins/hbacsvc.py b/ipalib/plugins/hbacsvc.py index 2383d70c0..d5302cdee 100644 --- a/ipalib/plugins/hbacsvc.py +++ b/ipalib/plugins/hbacsvc.py @@ -24,16 +24,17 @@ must match the service name that PAM is evaluating. EXAMPLES: - Create a new service: + Add a new HBAC service: ipa hbacsvc-add tftp - Update a service: - ipa hbacsvc-mod --desc='TFTP service' tftp + Modify an existing HBAC service: + ipa hbacsvc-mod --desc="TFTP service" tftp - Find a service (this will find 2, the ftp service and the new tftp service): + Search for HBAC services. This example will return two results, the FTP + service and the newly-added tftp service: ipa hbacsvc-find ftp - Remove a service: + Delete an HBAC service: ipa hbacsvc-del tftp """ @@ -78,7 +79,7 @@ api.register(hbacsvc) class hbacsvc_add(LDAPCreate): """ - Add new HBAC service. + Add a new HBAC service. """ msg_summary = _('Added service "%(value)s"') @@ -96,7 +97,7 @@ api.register(hbacsvc_del) class hbacsvc_mod(LDAPUpdate): """ - Modify HBAC service. + Modify an HBAC service. """ api.register(hbacsvc_mod) @@ -112,7 +113,7 @@ api.register(hbacsvc_find) class hbacsvc_show(LDAPRetrieve): """ - Display HBAC service. + Display information about an HBAC service. """ api.register(hbacsvc_show) diff --git a/ipalib/plugins/hbacsvcgroup.py b/ipalib/plugins/hbacsvcgroup.py index 53a8ca460..70dd32b13 100644 --- a/ipalib/plugins/hbacsvcgroup.py +++ b/ipalib/plugins/hbacsvcgroup.py @@ -19,25 +19,27 @@ """ HBAC Service Groups -Manage groups of services for HBAC +HBAC service groups can contain any number of individual services, +or "members", and can also contain other service groups. Every group must +have a description. EXAMPLES: - - Create a group of HBAC services: + + Add a new HBAC services group: ipa hbacsvcgroup-add --desc="login services" login - Add some members to a HBAC service group: + Add members to an HBAC services group: ipa hbacsvcgroup-add-member --hbacsvcs=sshd,login login - Show a group: + Display information about a named group: ipa hbacsvcgroup-show login - A group can contain other groups, add a new group to login: + Add a new group to the "login" group: 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: + Delete an HBAC services group: ipa hbacsvcgroup-del login """ @@ -94,7 +96,7 @@ api.register(hbacsvcgroup) class hbacsvcgroup_add(LDAPCreate): """ - Create new hbacsvcgroup. + Add a new HBAC services group. """ msg_summary = _('Added HBAC Service group "%(value)s"') @@ -103,7 +105,7 @@ api.register(hbacsvcgroup_add) class hbacsvcgroup_del(LDAPDelete): """ - Delete hbacsvcgroup. + Delete an HBAC services group. """ msg_summary = _('Deleted HBAC Service group "%(value)s"') @@ -112,7 +114,7 @@ api.register(hbacsvcgroup_del) class hbacsvcgroup_mod(LDAPUpdate): """ - Modify hbacsvcgroup. + Modify an HBAC services group. """ msg_summary = _('Modified HBAC Service group "%(value)s"') @@ -121,7 +123,7 @@ api.register(hbacsvcgroup_mod) class hbacsvcgroup_find(LDAPSearch): """ - Search the groups. + Search for an HBAC services group. """ msg_summary = ngettext( '%(count)d group matched', '%(count)d groups matched', 0 @@ -132,7 +134,7 @@ api.register(hbacsvcgroup_find) class hbacsvcgroup_show(LDAPRetrieve): """ - Display hbacsvcgroup. + Display information about an HBAC services group. """ api.register(hbacsvcgroup_show) @@ -140,7 +142,7 @@ api.register(hbacsvcgroup_show) class hbacsvcgroup_add_member(LDAPAddMember): """ - Add members to hbacsvcgroup. + Add members to an HBAC services group. """ api.register(hbacsvcgroup_add_member) @@ -148,7 +150,7 @@ api.register(hbacsvcgroup_add_member) class hbacsvcgroup_remove_member(LDAPRemoveMember): """ - Remove members from hbacsvcgroup. + Remove members from an HBAC services group. """ api.register(hbacsvcgroup_remove_member) diff --git a/ipalib/plugins/host.py b/ipalib/plugins/host.py index 78d4d5a02..d207f5267 100644 --- a/ipalib/plugins/host.py +++ b/ipalib/plugins/host.py @@ -18,47 +18,49 @@ # along with this program; if not, write to the Free Software # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA """ -Hosts/Machines (Identity) +Hosts/Machines 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 +- a host can 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. +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. +1. You are enrolling as a full administrator. The host entry may exist + or not. A full administrator is a member of the hostadmin rolegroup + or the admins group. +2. You are enrolling as a limited administrator. The host must already + exist. A limited administrator is a member of the enrollhost rolegroup. 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 only be enrolled once. If a client has enrolled and needs to +be re-enrolled, the host entry must be removed and re-created. Note that +re-creating the host entry will result in all services for the host being +removed, and all SSL certificates associated with those services being +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 + Add a new host: + ipa host-add --location="3rd floor lab" --locality=Dallas test.example.com - Remove a host + Delete a host: ipa host-del test.example.com - Create a new host with a one-time password + Add a new host with a one-time password: ipa host-add --os='Fedora 12' --password=Secret123 test.example.com - Update information about a host + Modify information about a host: ipa host-mod --os='Fedora 12' test.example.com - Disable the host kerberos key + Disable the host kerberos key: ipa host-disable test.example.com """ @@ -191,7 +193,7 @@ api.register(host) class host_add(LDAPCreate): """ - Create new host. + Add a new host. """ msg_summary = _('Added host "%(value)s"') @@ -227,7 +229,7 @@ api.register(host_add) class host_del(LDAPDelete): """ - Delete host. + Delete a host. """ msg_summary = _('Deleted host "%(value)s"') @@ -261,7 +263,7 @@ api.register(host_del) class host_mod(LDAPUpdate): """ - Modify host. + Modify information about a host. """ msg_summary = _('Modified host "%(value)s"') @@ -328,7 +330,7 @@ api.register(host_find) class host_show(LDAPRetrieve): """ - Display host. + Display information about a host. """ has_output_params = ( Flag('has_keytab', @@ -351,7 +353,7 @@ api.register(host_show) class host_disable(LDAPQuery): """ - Disable the kerberos key of this host. + Disable the kerberos key of a host. """ has_output = output.standard_value msg_summary = _('Removed kerberos key from "%(value)s"') diff --git a/ipalib/plugins/hostgroup.py b/ipalib/plugins/hostgroup.py index ff97a1394..2f9cbab2c 100644 --- a/ipalib/plugins/hostgroup.py +++ b/ipalib/plugins/hostgroup.py @@ -20,24 +20,30 @@ """ Groups of hosts. -This is useful for Host-Based Access Control (HBAC) to group a series -of hosts together for applying access control. +Manage groups of hosts. This is useful for applying access control to a +number of hosts by using Host-based Access Control. EXAMPLES: - Create a new host group: - ipa hostgroup-add --desc='Baltimore hosts' baltimore + Add a new host group: + ipa hostgroup-add --desc="Baltimore hosts" baltimore - Add some hosts to the group: + Add another new host group: + ipa hostgroup-add --desc="Maryland hosts" maryland + + Add members to the hostgroup: ipa hostgroup-add-member --hosts=box1,box2,box3 baltimore - Remove a host from the group: + Add a hostgroup as a member of another hostgroup: + ipa hostgroup-add-member --hostgroups=baltimore maryland + + Remove a host from the hostgroup: ipa hostgroup-remove-member --hosts=box2 baltimore Display a host group: ipa hostgroup-show baltimore - Removey a host group: + Delete a hostgroup: ipa hostgroup-del baltimore """ @@ -94,7 +100,7 @@ api.register(hostgroup) class hostgroup_add(LDAPCreate): """ - Create new hostgroup. + Add a new hostgroup. """ msg_summary = _('Added hostgroup "%(value)s"') @@ -104,7 +110,7 @@ api.register(hostgroup_add) class hostgroup_del(LDAPDelete): """ - Delete hostgroup. + Delete a hostgroup. """ msg_summary = _('Deleted hostgroup "%(value)s"') @@ -114,7 +120,7 @@ api.register(hostgroup_del) class hostgroup_mod(LDAPUpdate): """ - Modify hostgroup. + Modify a hostgroup. """ msg_summary = _('Modified hostgroup "%(value)s"') @@ -136,7 +142,7 @@ api.register(hostgroup_find) class hostgroup_show(LDAPRetrieve): """ - Display hostgroup. + Display information about a hostgroup. """ api.register(hostgroup_show) @@ -144,7 +150,7 @@ api.register(hostgroup_show) class hostgroup_add_member(LDAPAddMember): """ - Add members to hostgroup. + Add members to a hostgroup. """ api.register(hostgroup_add_member) @@ -152,7 +158,7 @@ api.register(hostgroup_add_member) class hostgroup_remove_member(LDAPRemoveMember): """ - Remove members from hostgroup. + Remove members from a hostgroup. """ api.register(hostgroup_remove_member) diff --git a/ipalib/plugins/krbtpolicy.py b/ipalib/plugins/krbtpolicy.py index 2c797fd13..5d773d205 100644 --- a/ipalib/plugins/krbtpolicy.py +++ b/ipalib/plugins/krbtpolicy.py @@ -19,13 +19,13 @@ """ 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. +There is a single Kerberos ticket policy. This policy defines the +maximum ticket lifetime and the maximum renewal age, the period during +which the ticket is renewable. EXAMPLES: - Display the current policy: + Display the current Kerberos ticket policy: ipa krbtpolicy-show Reset the policy to the default: @@ -85,7 +85,7 @@ api.register(krbtpolicy) class krbtpolicy_mod(LDAPUpdate): """ - Modify kerberos ticket policy. + Modify Kerberos ticket policy. """ def pre_callback(self, ldap, dn, entry_attrs, attrs_list, *keys, **options): # disable all flag @@ -99,7 +99,7 @@ api.register(krbtpolicy_mod) class krbtpolicy_show(LDAPRetrieve): """ - Display kerberos ticket policy. + Display the current Kerberos ticket policy. """ def pre_callback(self, ldap, dn, attrs_list, *keys, **options): # disable all flag @@ -123,7 +123,7 @@ api.register(krbtpolicy_show) class krbtpolicy_reset(LDAPQuery): """ - Reset kerberos ticket policy to default. + Reset Kerberos ticket policy to the default values. """ has_output = output.standard_entry diff --git a/ipalib/plugins/netgroup.py b/ipalib/plugins/netgroup.py index d2ffc404e..144505be8 100644 --- a/ipalib/plugins/netgroup.py +++ b/ipalib/plugins/netgroup.py @@ -25,19 +25,19 @@ user and host values. EXAMPLES: - Create a new netgroup: - ipa netgroup-add --desc='NFS admins' admins + Add a new netgroup: + ipa netgroup-add --desc="NFS admins" admins - Add a member to the group: + Add members to the netgroup: ipa netgroup-add-member --users=tuser1,tuser2 admins - Remove a member from the group: + Remove a member from the netgroup: ipa netgroup-remove-member --users=tuser2 admins - Display a netgroup: + Display infromation about a netgroup: ipa netgroup-show admins - Remove a netgroup: + Delete a netgroup: ipa netgroup-del admins """ @@ -131,7 +131,7 @@ api.register(netgroup) class netgroup_add(LDAPCreate): """ - Create new netgroup. + Add a new netgroup. """ has_output_params = output_params def pre_callback(self, ldap, dn, entry_attrs, attrs_list, *keys, **options): @@ -149,7 +149,7 @@ api.register(netgroup_add) class netgroup_del(LDAPDelete): """ - Delete netgroup. + Delete a netgroup. """ api.register(netgroup_del) @@ -157,7 +157,7 @@ api.register(netgroup_del) class netgroup_mod(LDAPUpdate): """ - Modify netgroup. + Modify a netgroup. """ has_output_params = output_params @@ -166,7 +166,7 @@ api.register(netgroup_mod) class netgroup_find(LDAPSearch): """ - Search the groups. + Search for a netgroup. """ has_output_params = output_params @@ -175,7 +175,7 @@ api.register(netgroup_find) class netgroup_show(LDAPRetrieve): """ - Display netgroup. + Display information about a netgroup. """ has_output_params = output_params @@ -184,7 +184,7 @@ api.register(netgroup_show) class netgroup_add_member(LDAPAddMember): """ - Add members to netgroup. + Add members to a netgroup. """ has_output_params = LDAPAddMember.has_output_params + output_params member_attributes = ['memberuser', 'memberhost'] @@ -220,7 +220,7 @@ api.register(netgroup_add_member) class netgroup_remove_member(LDAPRemoveMember): """ - Remove members from netgroup. + Remove members from a netgroup. """ has_output_params = LDAPRemoveMember.has_output_params + output_params member_attributes = ['memberuser', 'memberhost'] diff --git a/ipalib/plugins/passwd.py b/ipalib/plugins/passwd.py index f4f722f1e..ef515605e 100644 --- a/ipalib/plugins/passwd.py +++ b/ipalib/plugins/passwd.py @@ -17,23 +17,21 @@ # along with this program; if not, write to the Free Software # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA """ -User password changes +Set a user's password -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) +If someone other than user changes their 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. +The IPA password policy controls how often a password may be changed, +what strength requirements exist, and the length of the password history. EXAMPLES: - Reset your own password: + To reset your own password: ipa passwd - Change another user's password: + To change another user's password: ipa passwd tuser1 """ @@ -45,7 +43,7 @@ from ipalib import _ class passwd(Command): """ - Change user password. + Set a user's password """ takes_args = ( diff --git a/ipalib/plugins/pwpolicy.py b/ipalib/plugins/pwpolicy.py index e7cfab654..dbbb47135 100644 --- a/ipalib/plugins/pwpolicy.py +++ b/ipalib/plugins/pwpolicy.py @@ -19,29 +19,31 @@ """ 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 +A password policy sets limitations on IPA passwords, including maximum +lifetime, minimum lifetime, the number of passwords to save in +history, the number of character classes required (for stronger passwords) +and the minimum password length. + +By default there is a single, global policy for all users. You can also +create a password policy to apply to a group. Each user is only subject +to one password policy, either the group policy or the global policy. A +group policy stands alone; it is not 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. +is in multiple groups that have password policies, this priority determines +which password policy is applied. A lower value indicates a higher priority +policy. -A group password policy is automatically removed when the group it is -assicated with it is removed. +Group password policies are automatically removed when the groups they +are associated with are removed. EXAMPLES: - Update the global policy: + Modify the global policy: ipa pwpolicy-mod --minlength=10 - Create a group password policy: + Add a new group password policy: ipa pwpolicy-add --maxlife=90 --minlife=1 --history=10 --minclasses=3 --minlength=8 --priority=10 localadmins Display the global password policy: @@ -49,11 +51,11 @@ EXAMPLES: 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: + Modify a group password policy: ipa pwpolicy-mod --minclasses=2 localadmins """ @@ -266,7 +268,7 @@ api.register(pwpolicy) class pwpolicy_add(LDAPCreate): """ - Create new group password policy. + Add a new group password policy. """ def get_args(self): yield self.obj.primary_key.clone(attribute=True, required=True) @@ -295,7 +297,7 @@ api.register(pwpolicy_add) class pwpolicy_del(LDAPDelete): """ - Delete group password policy. + Delete a group password policy. """ def get_args(self): yield self.obj.primary_key.clone(attribute=True, required=True) @@ -312,7 +314,7 @@ api.register(pwpolicy_del) class pwpolicy_mod(LDAPUpdate): """ - Modify group password policy. + Modify a group password policy. """ def pre_callback(self, ldap, dn, entry_attrs, attrs_list, *keys, **options): self.obj.convert_time_on_input(entry_attrs) @@ -356,7 +358,7 @@ api.register(pwpolicy_mod) class pwpolicy_show(LDAPRetrieve): """ - Display group password policy. + Display information about password policy. """ takes_options = ( Str('user?', diff --git a/ipalib/plugins/rolegroup.py b/ipalib/plugins/rolegroup.py index 9ff3ef775..99560c46c 100644 --- a/ipalib/plugins/rolegroup.py +++ b/ipalib/plugins/rolegroup.py @@ -20,36 +20,41 @@ """ 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. +A rolegroup is used for fine-grained delegation. Access control rules +(ACIs) grant permission to perform given tasks (add a user, modify a group, +etc.), to task groups. Rolegroups are members of taskgroups, giving them +permission to perform the task. -The logic looks like this: +The logic behind ACIs and rolegroups proceeds as follows: - ACI grants permission to taskgroup + ACIs grants permission to taskgroup rolegroups are members of taskgroups - users, groups, hosts and hostgroups are members of role groups + users, groups, hosts and hostgroups are members of rolegroups -A host/hostgroup may be members because you may want to perform +Rolegroups can contain both hosts and hostgroups, enabling operations using the host service principal associated with a machine. -A rolegroup may not be members of other rolegroups. +Rolegroups can not contain other rolegroups. EXAMPLES: - Create a new role group: - ipa rolegroup-add --desc="Junion level admin" junioradmin + Add a new rolegroup: + ipa rolegroup-add --desc="Junior-level admin" junioradmin - Add this role to some tasks + 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 + Yes, this can seem backwards. The taskgroup is the entry that is granted + permissions by the ACIs. By adding a rolegroup as a member of a taskgroup + it inherits those permissions. + Add a group of users to this role: - ipa rolegroup-add-member --groups=junioradmins junioradmin + ipa group-add --desc="User admins" useradmins + ipa rolegroup-add-member --groups=useradmins junioradmin - Display this role group: + Display information about a rolegroup: ipa rolegroup-show junioradmin """ @@ -104,7 +109,7 @@ api.register(rolegroup) class rolegroup_add(LDAPCreate): """ - Create new rolegroup. + Add a new rolegroup. """ msg_summary = _('Added rolegroup "%(value)s"') @@ -114,7 +119,7 @@ api.register(rolegroup_add) class rolegroup_del(LDAPDelete): """ - Delete rolegroup. + Delete a rolegroup. """ msg_summary = _('Deleted rolegroup "%(value)s"') @@ -124,7 +129,7 @@ api.register(rolegroup_del) class rolegroup_mod(LDAPUpdate): """ - Edit rolegroup. + Modify a rolegroup. """ msg_summary = _('Modified rolegroup "%(value)s"') @@ -146,7 +151,7 @@ api.register(rolegroup_find) class rolegroup_show(LDAPRetrieve): """ - Display rolegroup. + Display information about a rolegroup. """ api.register(rolegroup_show) @@ -154,7 +159,7 @@ api.register(rolegroup_show) class rolegroup_add_member(LDAPAddMember): """ - Add member to rolegroup. + Add members to a rolegroup. """ api.register(rolegroup_add_member) @@ -162,7 +167,7 @@ api.register(rolegroup_add_member) class rolegroup_remove_member(LDAPRemoveMember): """ - Remove member from rolegroup. + Remove members from a rolegroup. """ api.register(rolegroup_remove_member) diff --git a/ipalib/plugins/service.py b/ipalib/plugins/service.py index c9ae0b88e..50e8d54fd 100644 --- a/ipalib/plugins/service.py +++ b/ipalib/plugins/service.py @@ -19,44 +19,54 @@ # along with this program; if not, write to the Free Software # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA """ -Services (Identity) +Services -A service represents a running service on a host. This service record -may store a kerberos principal or an SSL certificate (or both). +A IPA service represents a service that runs on a host. The IPA service +record can store a Kerberos principal, 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. +An IPA service can be managed directly from a machine, provided that +machine has been given the correct permission. This is true even for +machines other than the one the service is associated with. For example, +requesting an SSL certificate using the host service principal credentials +of the host. To manage a services using a host credentials you need to +kinit as 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. + # kinit -kt /etc/krb5.keytab host/ipa.example.com@EXAMPLE.COM -The certificate stored in a service is just the public portion. The -private key is not stored. +Adding an IPA service allows the associated service to request an SSL +certificate or keytab, but this is performed as a separate step; they +are not produced as a result of adding the service. + +Only the public aspect of a certificate is stored in a service record; +the private key is not stored. EXAMPLES: - Add a service: + Add a new IPA service: ipa service-add HTTP/web.example.com - Allow a host to manage the service certificate: + Allow a host to manage an IPA 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: + Delete an IPA service: ipa service-del HTTP/web.example.com - Find all services for a host: + Find all IPA services assicated with a host: ipa service-find web.example.com Find all HTTP services: ipa service-find HTTP - Disable a service kerberos key: + Disable a service Kerberos key: ipa service-disable HTTP/web.example.com + Request a certificate for an IPA service: + ipa cert-request --principal=HTTP/web.example.com example.csr + + Generate and retrieve a keytab for an IPA service: + ipa-getkeytab -s ipa.example.com -p HTTP/web.example.com -k /etc/httpd/httpd.keytab + """ import base64 @@ -161,7 +171,7 @@ api.register(service) class service_add(LDAPCreate): """ - Add new service. + Add a new IPA new service. """ msg_summary = _('Added service "%(value)s"') member_attributes = ['managedby'] @@ -209,7 +219,7 @@ api.register(service_add) class service_del(LDAPDelete): """ - Delete an existing service. + Delete an IPA service. """ msg_summary = _('Deleted service "%(value)s"') member_attributes = ['managedby'] @@ -246,7 +256,7 @@ api.register(service_del) class service_mod(LDAPUpdate): """ - Modify service. + Modify an existing IPA service. """ msg_summary = _('Modified service "%(value)s"') takes_options = LDAPUpdate.takes_options + ( @@ -282,7 +292,7 @@ api.register(service_mod) class service_find(LDAPSearch): """ - Search for services. + Search for IPA services. """ msg_summary = ngettext( '%(count)d service matched', '%(count)d services matched' @@ -324,7 +334,7 @@ api.register(service_find) class service_show(LDAPRetrieve): """ - Display service. + Display information about an IPA service. """ member_attributes = ['managedby'] takes_options = LDAPRetrieve.takes_options + ( @@ -370,7 +380,7 @@ api.register(service_remove_host) class service_disable(LDAPQuery): """ - Disable the kerberos key of this service. + Disable the Kerberos key of a service. """ has_output = output.standard_value msg_summary = _('Removed kerberos key from "%(value)s"') diff --git a/ipalib/plugins/taskgroup.py b/ipalib/plugins/taskgroup.py index e9e95448c..0ee90474d 100644 --- a/ipalib/plugins/taskgroup.py +++ b/ipalib/plugins/taskgroup.py @@ -20,11 +20,13 @@ """ 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 enables fine-grained delegation of permissions. Access Control +Rules, or instructions (ACIs), grant permission to taskgroups to perform +given tasks such as adding a user, modifying a group, etc. A taskgroup may not be members of other taskgroups. + +See rolegroup and aci for additional information. """ from ipalib.plugins.baseldap import * @@ -79,7 +81,7 @@ api.register(taskgroup) class taskgroup_add(LDAPCreate): """ - Create new taskgroup. + Add a new taskgroup. """ msg_summary = _('Added taskgroup "%(value)s"') @@ -89,7 +91,7 @@ api.register(taskgroup_add) class taskgroup_del(LDAPDelete): """ - Delete taskgroup. + Delete a taskgroup. """ msg_summary = _('Deleted taskgroup "%(value)s"') @@ -99,7 +101,7 @@ api.register(taskgroup_del) class taskgroup_mod(LDAPUpdate): """ - Modify taskgroup. + Modify a taskgroup. """ msg_summary = _('Modified taskgroup "%(value)s"') @@ -121,7 +123,7 @@ api.register(taskgroup_find) class taskgroup_show(LDAPRetrieve): """ - Display taskgroup. + Display information about a taskgroup. """ api.register(taskgroup_show) @@ -129,7 +131,7 @@ api.register(taskgroup_show) class taskgroup_add_member(LDAPAddMember): """ - Add member to taskgroup. + Add members to a taskgroup. """ api.register(taskgroup_add_member) @@ -137,7 +139,7 @@ api.register(taskgroup_add_member) class taskgroup_remove_member(LDAPRemoveMember): """ - Remove member from taskgroup. + Remove members from a taskgroup. """ api.register(taskgroup_remove_member) diff --git a/ipalib/plugins/user.py b/ipalib/plugins/user.py index f698aa703..5841d7a01 100644 --- a/ipalib/plugins/user.py +++ b/ipalib/plugins/user.py @@ -18,19 +18,23 @@ # along with this program; if not, write to the Free Software # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA """ -Users (Identity) +Users -Manage user entries. +Manage user entries. All users are POSIX users. + +Locking a user account prevents that user from obtaining new Kerberos +credentials. It does not invalidate any credentials that have already +been issued. EXAMPLES: - Create a new user: + Add a new user: ipa user-add --first=Tim --last=User --passwd tuser1 - Find a user Tim: + Find all users whose entries include the string "Tim": ipa user-find Tim - Find all users with Tim as the first name: + Find all users with "Tim" as the first name: ipa user-find --first=Tim Lock a user account: @@ -156,7 +160,7 @@ api.register(user) class user_add(LDAPCreate): """ - Create new user. + Add a new user. """ msg_summary = _('Added user "%(value)s"') @@ -205,7 +209,7 @@ api.register(user_add) class user_del(LDAPDelete): """ - Delete user. + Delete a user. """ msg_summary = _('Deleted user "%(value)s"') @@ -224,7 +228,7 @@ api.register(user_del) class user_mod(LDAPUpdate): """ - Modify user. + Modify a user. """ msg_summary = _('Modified user "%(value)s"') @@ -246,7 +250,7 @@ api.register(user_find) class user_show(LDAPRetrieve): """ - Display user. + Display information about a user. """ api.register(user_show) @@ -254,7 +258,7 @@ api.register(user_show) class user_lock(LDAPQuery): """ - Lock user account. + Lock a user account. """ has_output = output.standard_value @@ -280,7 +284,7 @@ api.register(user_lock) class user_unlock(LDAPQuery): """ - Unlock user account. + Unlock a user account. """ has_output = output.standard_value -- cgit