[Freeipa-devel] [PATCH] 0076-0077 Document trust commands and external group member

[Alexander Bokovoy]

Hi,

attached patches 0076 and 0077 add base documentation about trust
commands. Part of that documentation is also added to group membership
plugin to describe external groups and external members.

-- 
/ Alexander Bokovoy
-------------- next part --------------
>From bb0c11364826c0738ab7bd649101cdaeaa0081f4 Mon Sep 17 00:00:00 2001
From: Alexander Bokovoy <abokovoy at redhat.com>
Date: Thu, 20 Sep 2012 14:25:05 +0300
Subject: [PATCH 3/4] Add documentation for 'ipa trust' set of commands

---
 ipalib/plugins/trust.py | 60 +++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 58 insertions(+), 2 deletions(-)

diff --git a/ipalib/plugins/trust.py b/ipalib/plugins/trust.py
index bced06f4db83b98f16e75b63ba0c0c252a12e489..9d3e9a873e8f6335c12729e9f9475e59499fb3d4 100644
--- a/ipalib/plugins/trust.py
+++ b/ipalib/plugins/trust.py
@@ -34,11 +34,67 @@ if api.env.in_server and api.env.context in ['lite', 'server']:
     try:
         import ipaserver.dcerpc #pylint: disable=F0401
         _bindings_installed = True
-    except Exception, e:
+    except ImportError:
         _bindings_installed = False
 
 __doc__ = _("""
-Manage trust relationship between realms
+Cross-realm trusts
+
+Manage trust relationship between IPA and Active Directory domains.
+
+In order to allow users from a remote domain to access resources in IPA
+domain, trust relationship needs to be established. Currently IPA supports
+only trusts between IPA and Active Directory domains under control of Windows
+Server 2008 or later, with functional level 2008 or later.
+
+Please note that DNS on both IPA and Active Directory domain sides should be
+configured properly to discover each other. Trust relationship relies on
+ability to discover special resources in the other domain via DNS records.
+
+Examples:
+
+1. Establish cross-realm trust with Active Directory using AD administrator
+   credentials:
+
+   ipa trust-add --type=ad <ad.domain> --admin <AD domain administrator> --password
+
+2. List all existing trust relationships:
+
+   ipa trust-find
+
+3. Show details of the specific trust relationship:
+
+   ipa trust-show <ad.domain>
+
+4. Delete existing trust relationship:
+
+   ipa trust-del <ad.domain>
+
+Once trust relationship is established, remote users will need to be mapped
+to local POSIX groups in order to actually use IPA resources. The mapping should
+be done via use of external membership of non-POSIX group and then this group
+should be included into one of local POSIX groups.
+
+Example:
+
+1. Make note of the trusted domain security identifier
+
+   domainsid = `ipa trust-show <ad.domain> | grep Identifier | cut -d: -f2`
+
+2. Create group for the trusted domain admins' mapping and their local POSIX group:
+
+   ipa group-add --desc='<ad.domain> admins external map' ad_admins_external --external
+   ipa group-add --desc='<ad.domain> admins' ad_admins
+
+3. Add security identifier of Domain Admins of the <ad.domain> to the ad_admins_external
+   group (security identifier of <ad.domain SID>-513 is Domain Admins group):
+
+   ipa group-add-member ad_admins_external --external ${domainsid}-513
+
+4. Allow members of ad_admins_external group to be associated with ad_admins POSIX group:
+
+   ipa group-add-member ad_admins --groups ad_admins_external
+
 """)
 
 trust_output_params = (
-- 
1.7.12

-------------- next part --------------
>From 29598d8e958e571fcba0c4a81ea671092375b727 Mon Sep 17 00:00:00 2001
From: Alexander Bokovoy <abokovoy at redhat.com>
Date: Thu, 20 Sep 2012 14:31:01 +0300
Subject: [PATCH 4/4] Document use of external group membership

---
 ipalib/plugins/group.py | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/ipalib/plugins/group.py b/ipalib/plugins/group.py
index ae00aa8ac7d087befa5107df4eb978f1ada00240..3775056a12400ddc236bf5c12ff862731f699431 100644
--- a/ipalib/plugins/group.py
+++ b/ipalib/plugins/group.py
@@ -76,6 +76,35 @@ EXAMPLES:
 
  Display information about a named group.
    ipa group-show localadmins
+
+External group membership is designed to allow users from trusted domains
+to be mapped to local POSIX groups in order to actually use IPA resources.
+External members should be added to groups that specifically created as
+external and non-POSIX. Such group later should be included into one of POSIX
+groups.
+
+An external group member is currently a Security Identifier as defined by
+the trusted domain.
+
+Example:
+
+1. Make note of the trusted domain security identifier
+
+   domainsid = `ipa trust-show <ad.domain> | grep Identifier | cut -d: -f2`
+
+2. Create group for the trusted domain admins' mapping and their local POSIX group:
+
+   ipa group-add --desc='<ad.domain> admins external map' ad_admins_external --external
+   ipa group-add --desc='<ad.domain> admins' ad_admins
+
+3. Add security identifier of Domain Admins of the <ad.domain> to the ad_admins_external
+   group (security identifier of <ad.domain SID>-513 is Domain Admins group):
+
+   ipa group-add-member ad_admins_external --external ${domainsid}-513
+
+4. Allow members of ad_admins_external group to be associated with ad_admins POSIX group:
+
+   ipa group-add-member ad_admins --groups ad_admins_external
 """)
 
 protected_group_name = u'admins'
-- 
1.7.12