Browse Source

Adds Plugin Guide.

Documentation of LDAP plugin for Fuel-9.0 was added.

Change-Id: Ied40e1d731feea6eee8c306b3fdef6487da2038e
changes/01/337801/6
Maksym Yatsenko 2 years ago
parent
commit
895e53166b

+ 1
- 2
doc/source/appendix.rst View File

@@ -5,6 +5,5 @@ Appendix
5 5
 Links
6 6
 =========================
7 7
 
8
-- `Mirantis OpenStack User Guide <https://docs.mirantis.com/openstack/fuel/fuel-7.0/user-guide.html>`_
8
+- `Mirantis OpenStack Documentation Center <https://docs.mirantis.com/openstack/fuel/fuel-9.0/>`_
9 9
 - `Fuel Plugins Catalog <https://www.mirantis.com/products/openstack-drivers-and-plugins/fuel-plugins/>`_
10
-- `Quick Start Guide <https://software.mirantis.com/quick-start/>`_

+ 16
- 0
doc/source/changelog.rst View File

@@ -0,0 +1,16 @@
1
+Release notes / Changelog
2
+=========================
3
+
4
+**3.0.0**
5
+
6
+* Support of ldap proxy
7
+* Compatibility with MOS 9.0
8
+
9
+**2.0.0**
10
+
11
+* Support of multi-domains
12
+* Compatibility with MOS 8.0
13
+
14
+**1.0.0**
15
+
16
+* This is the first release of the plugin

+ 3
- 3
doc/source/conf.py View File

@@ -9,10 +9,10 @@ source_suffix = '.rst'
9 9
 master_doc = 'index'
10 10
 
11 11
 project = u'The LDAP plugin for Fuel'
12
-copyright = u'2015, Mirantis Inc.'
12
+copyright = u'2016, Mirantis Inc.'
13 13
 
14
-version = '1.0-1.0.0-1'
15
-release = '1.0-1.0.0-1'
14
+version = '3.0-3.0.0-1'
15
+release = '3.0-3.0.0-1'
16 16
 
17 17
 exclude_patterns = []
18 18
 

+ 77
- 20
doc/source/configuration.rst View File

@@ -5,26 +5,52 @@ Configuring LDAP plugin
5 5
 #. Create a new OpenStack environment to use an existing LDAP server as authentication
6 6
    backend for Keystone.
7 7
    For more information about environment creation, see `Mirantis OpenStack
8
-   User Guide <http://docs.mirantis.com/openstack
9
-   /fuel/fuel-7.0/user-guide.html#create-a-new-openstack-environment>`_.
8
+   User Guide <http://docs.openstack.org/developer/fuel-docs
9
+   /userdocs/fuel-user-guide/create-environment.html>`_.
10 10
 
11 11
 #. Open *Settings* tab of the Fuel Web UI, scroll the page down and select
12 12
    the *LDAP plugin for Keystone* checkbox:
13 13
 
14
-   .. image:: images/ldap-checkbox.png
14
+   .. image:: images/ldap_plugin.png
15
+   .. image:: images/enable_ldap_plugin.png
15 16
 
16
-#. Fill in plugin settings into the text field. LDAP plugin features the following
17
-   parameters to enter:
17
+#. Enter plugin settings into the text fields:
18
+
19
+   .. image:: images/settings.png
20
+
21
+   Specify domain name, LDAP URL, LDAP suffix:
22
+
23
+   .. image:: images/ldap_settings.png
24
+   .. image:: images/ldap_settings_suffix.png
25
+
26
+   Enable TLS use and put certificate if it is needed:
27
+
28
+   .. image:: images/tls_settings.png
29
+
30
+   Enable LDAP proxy and put custom config if it is needed:
31
+
32
+   .. image:: images/enable_ldap_proxy.png
33
+   .. image:: images/custom_proxy_configs.png
34
+
35
+   Specify LDAP user, password and other settings:
36
+
37
+   .. image:: images/user_ldap_settings.png
38
+
39
+   To use LDAP groups provide settings for it:
40
+
41
+   .. image:: images/group_ldap_settings.png
42
+
43
+   Fields description:
18 44
 
19 45
     ================================== ===============
20 46
     Field                              Comment
21 47
     ================================== ===============
22 48
     Domain name                        Name of the Keystone domain.
23 49
     LDAP URL                           URL for connecting to the LDAP server.
24
-    LDAP Suffix                        LDAP server suffix.
50
+    LDAP proxy                         Enable LDAP proxy.
25 51
     Use TLS                            Enable TLS for communicating with the LDAP server.
26 52
     CA Chain                           CA trust chain in PEM format.
27
-
53
+    LDAP Suffix                        LDAP server suffix.
28 54
     LDAP User                          User BindDN to query the LDAP server.
29 55
     LDAP User Password                 Password for the BindDN to query the LDAP
30 56
                                        server.
@@ -45,31 +71,62 @@ Configuring LDAP plugin
45 71
     Group Name Attribute               LDAP attribute mapped to group name.
46 72
     Group Member Attribute             LDAP attribute that maps user to group.
47 73
     Group description Attribute        LDAP attribute mapped to description.
74
+    Page Size Attribute                Maximum results per page.
75
+    Chase referrals Attribute          Referral chasing behavior for queries.
76
+    List of additional Domains         Blocks of additional domains/parameters that should be created.
77
+    List of custom LDAP proxy configs  List of custom LDAP proxy configs.
48 78
 
49 79
     ================================== ===============
50
-   
51 80
 
52
-   .. image:: images/settings.png
81
+#. To deploy an environment with support of multiple domains 'List of additional Domains'
82
+   text area should be used. All needed parameters that describes a domain should be copied there,
83
+   all parameters form a block of parameters.
84
+
85
+   .. image:: images/additional_domains.png
86
+
87
+   To add multiple domains such block of parameters should be added
88
+   to 'List of additional Domains' text area and these blocks should
89
+   be separated by empty line.
90
+
91
+#. To set up an environment with activated LDAP proxy 'LDAP proxy' checkbox should be selected.
92
+   When only 'LDAP proxy' checkbox is selected: it activates LDAP proxy for base domain and activates
93
+   LDAP proxy for additional domains if they have 'ldap_proxy=true' parameter in their configurations.
94
+
95
+   .. image:: images/enable_ldap_proxy.png
96
+   .. image:: images/ldap_proxy_param.png
97
+
98
+   In this case LDAP proxy configurations for LDAP domains are taken from templates located in the plugin.
99
+   Configurations from the templates have minimal functionality and they are intended for testing needs.
53 100
 
54
-   * Specify domain name, LDAP URL, LDAP suffix:
101
+   To specify custom settings for LDAP proxy 'List of custom LDAP proxy configs' text area should be used.
102
+   There can be specified base settings for a proxy service: 'includes', loglevel and etc. can be added to a
103
+   proxy configuration file. For this 'config_for' parameter with 'base_config' value should be specified and
104
+   after that needed settings should be added.
55 105
 
56
-     .. image:: images/ldap_settings.png
106
+   .. image:: images/proxy_base_config.png
57 107
 
58
-   * Enable TLS use and put certificate if it is needed:
108
+   To specify custom settings for LDAP domain 'config_for' parameter with <domain_name> value should be added
109
+   and after that custom settings can be specified.
59 110
 
60
-     .. image:: images/tls_settings.png
111
+   .. image:: images/proxy_custom_config.png
61 112
 
62
-   * Specify LDAP user, password and other settings:
113
+   Blocks of custom settings should be separated by empty line.
63 114
 
64
-     .. image:: images/user_ldap_settings.png
115
+#.Continue with environment configuration and deploy it;
116
+   for instructions, see
117
+   `Fuel User Guide <http://docs.openstack.org/developer/fuel-docs/mitaka/userdocs/fuel-user-guide.html>`_.
65 118
 
66
-   * To use LDAP groups, enter the corresponding values:
119
+#. After successful environment deployment log into dashboard in default domain:
67 120
 
68
-     .. image:: images/group_ldap_settings.png
121
+   .. image:: images/default_domain.png
69 122
 
123
+#. Go to Identity -> Domains, select needed domain and 'Set Domain Context' for the domain:
70 124
 
71
-#. Finalize environment configuration and run network verification check.
72
-   Once done,
73
-   `deploy your environment <http://docs.mirantis.com/openstack/fuel/fuel-7.0/user-guide.html#deploy-changes>`_.
125
+   .. image:: images/domains.png
126
+   .. image:: images/domain_context.png
74 127
 
128
+#. Go to Identity -> Projects and select 'Create Project' to create a new project for the domain
129
+   and add user members to the project:
75 130
 
131
+   .. image:: images/project.png
132
+   .. image:: images/project_members.png

+ 1
- 2
doc/source/description.rst View File

@@ -17,9 +17,8 @@ Requirements
17 17
 ================================== ===============
18 18
 Requirement                        Version/Comment
19 19
 ================================== ===============
20
-Fuel                               7.0
20
+Fuel                               9.0
21 21
 Pre-configured LDAP server
22
-MU (Maintenance Update)            3
23 22
 ================================== ===============
24 23
 
25 24
 LDAP server should be pre-deployed and be accessible via Public network

+ 0
- 49
doc/source/guide.rst View File

@@ -2,57 +2,8 @@
2 2
 User Guide
3 3
 ==========
4 4
 
5
-
6
-#. After successfull environment deployment, log into Horizon into the default domain:
7
-
8
-   .. image:: images/default_domain.png
9
-
10
-#. Go to Identity -> Domains, select the required domain and select
11
-   *Set Domain Context* for it:
12
-
13
-   .. image:: images/domains.png
14
-   .. image:: images/domain_context.png
15
-
16
-#. Go to Identity -> Projects and select 'Create Project' to create a new project for the domain
17
-   and add user members to the project:
18
-
19
-   .. image:: images/project.png
20
-   .. image:: images/project_members.png
21
-
22 5
 #. After successful deployment, all users from the LDAP directory matching the
23 6
    configured filter criteria can authenticate against Keystone. To validate the
24 7
    configuration, log into the Horizon dashboard using LDAP credentials:
25 8
 
26 9
    .. image:: images/dashboard.png
27
-
28
-#. You can also try to obtain a token to validate authentication:
29
-
30
-   .. code-block:: bash
31
-
32
-    # curl -i -s -H "Content-Type: application/json" -d '
33
-      { "auth": {
34
-          "identity": {
35
-            "methods": ["password"],
36
-            "password": {
37
-              "user": {
38
-                "name": "admin",
39
-                "domain": { "id": "default" },
40
-                "password": "admin"
41
-              }
42
-            }
43
-          },
44
-          "scope": {
45
-            "project": {
46
-              "name": "admin",
47
-              "domain": { "id": "default" }
48
-            }
49
-          }
50
-        }
51
-      }' http://<dashboard_ip>:5000/v3/auth/tokens
52
-
53
-    HTTP/1.1 201 Created
54
-    X-Subject-Token: 77a7c2da81f54bb7b46efefa7c7bb5ae
55
-    Vary: X-Auth-Token
56
-    Content-Type: application/json
57
-    Content-Length: 2173
58
-

BIN
doc/source/images/additional_domains.png View File


BIN
doc/source/images/custom_proxy_configs.png View File


BIN
doc/source/images/dashboard.png View File


BIN
doc/source/images/default_domain.png View File


BIN
doc/source/images/domain_context.png View File


BIN
doc/source/images/domains.png View File


BIN
doc/source/images/enable_ldap_plugin.png View File


BIN
doc/source/images/enable_ldap_proxy.png View File


BIN
doc/source/images/group_ldap_settings.png View File


BIN
doc/source/images/ldap-checkbox.png View File


BIN
doc/source/images/ldap_plugin.png View File


BIN
doc/source/images/ldap_proxy_param.png View File


BIN
doc/source/images/ldap_settings.png View File


BIN
doc/source/images/ldap_settings_suffix.png View File


BIN
doc/source/images/project.png View File


BIN
doc/source/images/project_members.png View File


BIN
doc/source/images/proxy_base_config.png View File


BIN
doc/source/images/proxy_custom_config.png View File


BIN
doc/source/images/settings.png View File


BIN
doc/source/images/tls_settings.png View File


BIN
doc/source/images/user_ldap_settings.png View File


+ 4
- 0
doc/source/index.rst View File

@@ -9,9 +9,13 @@ Plugin Guide
9 9
    :maxdepth: 2
10 10
 
11 11
    description
12
+   changelog
13
+   limitations
12 14
    installation
13 15
    configuration
14 16
    guide
17
+   verification
18
+   troubleshooting
15 19
    appendix
16 20
 
17 21
 

+ 9
- 16
doc/source/installation.rst View File

@@ -13,27 +13,20 @@ To install LDAP plugin, follow these steps:
13 13
 
14 14
 #. Copy the plugin on an already installed Fuel Master node (SSH can be used for
15 15
    that). If you do not have the Fuel Master node yet, see `Quick Start Guide
16
-   <https://software.mirantis.com/quick-start/>`_:
16
+   <http://docs.openstack.org/developer/fuel-docs/userdocs/fuel-install-guide/install/install_install_fuel_master_node.html>`_::
17 17
 
18
-   .. code-block:: bash
18
+   # scp ldap-3.0-3.0.0-1.noarch.rpm root@<Fuel_Master_IP>:/tmp
19 19
 
20
-      # scp ldap-1.0-1.0.0-1.noarch.rpm root@<Fuel_Master_IP>:/tmp
20
+#. Log into the Fuel Master node. Install the plugin::
21 21
 
22
-#. Log into the Fuel Master node. Install the plugin:
23
-
24
-   .. code-block:: bash
25
-
26
-      # cd /tmp
27
-      # fuel plugins --install ldap-1.0-1.0.0-1.noarch.rpm
22
+   # cd /tmp
23
+   # fuel plugins --install ldap-3.0-3.0.0-1.noarch.rpm
28 24
 
29 25
 #. Check if the plugin was installed successfully
30 26
 
31
-   .. code-block:: bash
27
+   ::
32 28
 
33 29
         # fuel plugins
34
-        id | name         | version  | package_version
35
-        ---|--------------|----------|----------------
36
-        1  | ldap         | 1.0.0    | 2.0.0
37
-
38
-#. MU-3 (Maintenance Update) should be installed to provide proper work of keystone providers
39
-   with domains during deployment process.
30
+        id | name | version | package_version | releases
31
+        ---+------+---------+-----------------+--------------------
32
+        1  | ldap | 3.0.0   | 3.0.0           | ubuntu (mitaka-9.0)

+ 11
- 0
doc/source/limitations.rst View File

@@ -0,0 +1,11 @@
1
+LDAP plugin limitations
2
+-----------------------
3
+
4
+#. LDAP plugin has the following limitations:
5
+
6
+   - Installation of LDAP plugin before deployment only;
7
+   - Fuel will not validate the settings, e.g., by attempting to connect to the LDAP server;
8
+   - In multidomain configuration the attributes of the first domain are filled in the web form,
9
+     whereas the attributes of other domains are filled in one field;
10
+   - The settings of domains determined in “List of additional Domains” field will not be validated;
11
+   - The settings of proxy determined in "List of custom LDAP proxy configs" field will not be validated;

+ 4
- 6
doc/source/removal.rst View File

@@ -5,12 +5,10 @@ Delete all environments, in which the LDAP plugin has been enabled.
5 5
 
6 6
 #. Uninstall the plugin::
7 7
 
8
-      # fuel plugins --remove ldap==1.0.0
8
+      # fuel plugins --remove ldap==3.0.0
9 9
 
10 10
 #. Check if the plugin was uninstalled successfully::
11 11
 
12
-      # fuel plugins$
13
-      id | name                      | version  | package_version
14
-      ---|---------------------------|----------|------
15
-
16
-
12
+      # fuel plugins
13
+      id | name | version | package_version | releases
14
+      ---+------+---------+-----------------+---------

+ 41
- 0
doc/source/troubleshooting.rst View File

@@ -0,0 +1,41 @@
1
+===============
2
+Troubleshooting
3
+===============
4
+
5
+Checking presence of LDAP domain/users
6
+======================================
7
+
8
+To get a list of domains in keystone run the following command on Controller node:
9
+
10
+.. code-block:: bash
11
+
12
+   OS_IDENTITY_API_VERSION=3 openstack domain list
13
+
14
+To get a list of users in a domain run the following command on Controller node:
15
+
16
+.. code-block:: bash
17
+
18
+   OS_IDENTITY_API_VERSION=3 openstack user list --quiet --long --domain <domain_name>
19
+
20
+Checking LDAP server availability
21
+=================================
22
+
23
+To check LDAP server availability run the following command on Controller node:
24
+
25
+.. code-block:: bash
26
+
27
+   ldapsearch -H ldap://<url/ip_address> -x -b dc=<ldap>,dc=<suffix>
28
+
29
+LDAP plugin log files
30
+=====================
31
+
32
+As LDAP plugin only updates keystone configuration files to check keystone
33
+service, these files keep logs:
34
+
35
+/var/log/apache2/keystone_wsgi_admin_access.log
36
+
37
+/var/log/apache2/keystone_wsgi_admin_error.log
38
+
39
+/var/log/apache2/keystone_wsgi_main_access.log
40
+
41
+/var/log/apache2/keystone_wsgi_main_error.log

+ 12
- 0
doc/source/verification.rst View File

@@ -0,0 +1,12 @@
1
+LDAP plugin validation
2
+----------------------
3
+
4
+#. To validate that LDAP plugin is successfully applied after deployment:
5
+
6
+   - Log into Horizon using domain/user credentials from LDAP server;
7
+   - Create an instance;
8
+
9
+   Expecting results:
10
+
11
+   - All LDAP users can authenticate via Keystone;
12
+   - An instance is successfully created;

Loading…
Cancel
Save