Browse Source

Merge "Adds Plugin Guide"

Jenkins 2 years ago
parent
commit
44156eb215

+ 183
- 0
doc/Makefile View File

@@ -0,0 +1,183 @@
1
+# Makefile for Sphinx documentation
2
+#
3
+
4
+# You can set these variables from the command line.
5
+SPHINXOPTS    =
6
+SPHINXBUILD   = sphinx-build
7
+PAPER         =
8
+BUILDDIR      = build
9
+
10
+# User-friendly check for sphinx-build
11
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
12
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
13
+endif
14
+
15
+# Internal variables.
16
+PAPEROPT_a4     = -D latex_paper_size=a4
17
+PAPEROPT_letter = -D latex_paper_size=letter
18
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
19
+# the i18n builder cannot share the environment and doctrees with the others
20
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
21
+# SVG to PDF conversion
22
+SVG2PDF         = inkscape
23
+SVG2PDF_FLAGS	=
24
+# Build a list of SVG files to convert to PDF
25
+PDF_FILES := $(foreach dir, images, $(patsubst %.svg,%.pdf,$(wildcard $(dir)/*.svg)))
26
+
27
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
28
+
29
+help:
30
+	@echo "Please use \`make <target>' where <target> is one of"
31
+	@echo "  html       to make standalone HTML files"
32
+	@echo "  dirhtml    to make HTML files named index.html in directories"
33
+	@echo "  singlehtml to make a single large HTML file"
34
+	@echo "  pickle     to make pickle files"
35
+	@echo "  json       to make JSON files"
36
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
37
+	@echo "  qthelp     to make HTML files and a qthelp project"
38
+	@echo "  devhelp    to make HTML files and a Devhelp project"
39
+	@echo "  epub       to make an epub"
40
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
41
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
42
+	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
43
+	@echo "  text       to make text files"
44
+	@echo "  man        to make manual pages"
45
+	@echo "  texinfo    to make Texinfo files"
46
+	@echo "  info       to make Texinfo files and run them through makeinfo"
47
+	@echo "  gettext    to make PO message catalogs"
48
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
49
+	@echo "  xml        to make Docutils-native XML files"
50
+	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
51
+	@echo "  linkcheck  to check all external links for integrity"
52
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
53
+
54
+clean:
55
+	rm -rf $(BUILDDIR)/*
56
+	rm -f $(PDF_FILES)
57
+
58
+html:
59
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
60
+	@echo
61
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
62
+
63
+dirhtml:
64
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
65
+	@echo
66
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
67
+
68
+singlehtml:
69
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
70
+	@echo
71
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
72
+
73
+pickle:
74
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
75
+	@echo
76
+	@echo "Build finished; now you can process the pickle files."
77
+
78
+json:
79
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
80
+	@echo
81
+	@echo "Build finished; now you can process the JSON files."
82
+
83
+htmlhelp:
84
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
85
+	@echo
86
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
87
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
88
+
89
+qthelp:
90
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
91
+	@echo
92
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
93
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
94
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/LMAcollector.qhcp"
95
+	@echo "To view the help file:"
96
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/LMAcollector.qhc"
97
+
98
+devhelp:
99
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
100
+	@echo
101
+	@echo "Build finished."
102
+	@echo "To view the help file:"
103
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/LMAcollector"
104
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/LMAcollector"
105
+	@echo "# devhelp"
106
+
107
+epub:
108
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
109
+	@echo
110
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
111
+
112
+latex:
113
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
114
+	@echo
115
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
116
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
117
+	      "(use \`make latexpdf' here to do that automatically)."
118
+
119
+latexpdf:
120
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
121
+	@echo "Running LaTeX files through pdflatex..."
122
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
123
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
124
+
125
+latexpdfja:
126
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
127
+	@echo "Running LaTeX files through platex and dvipdfmx..."
128
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
129
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
130
+
131
+text:
132
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
133
+	@echo
134
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
135
+
136
+man:
137
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
138
+	@echo
139
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
140
+
141
+texinfo:
142
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
143
+	@echo
144
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
145
+	@echo "Run \`make' in that directory to run these through makeinfo" \
146
+	      "(use \`make info' here to do that automatically)."
147
+
148
+info:
149
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
150
+	@echo "Running Texinfo files through makeinfo..."
151
+	make -C $(BUILDDIR)/texinfo info
152
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
153
+
154
+gettext:
155
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
156
+	@echo
157
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
158
+
159
+changes:
160
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
161
+	@echo
162
+	@echo "The overview file is in $(BUILDDIR)/changes."
163
+
164
+linkcheck:
165
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
166
+	@echo
167
+	@echo "Link check complete; look for any errors in the above output " \
168
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
169
+
170
+doctest:
171
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
172
+	@echo "Testing of doctests in the sources finished, look at the " \
173
+	      "results in $(BUILDDIR)/doctest/output.txt."
174
+
175
+xml:
176
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
177
+	@echo
178
+	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
179
+
180
+pseudoxml:
181
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
182
+	@echo
183
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

+ 10
- 0
doc/source/appendix.rst View File

@@ -0,0 +1,10 @@
1
+==================
2
+Appendix
3
+==================
4
+
5
+Links
6
+=========================
7
+
8
+- `Mirantis OpenStack User Guide <https://docs.mirantis.com/openstack/fuel/fuel-7.0/user-guide.html>`_
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/>`_

+ 33
- 0
doc/source/conf.py View File

@@ -0,0 +1,33 @@
1
+# Always use the default theme for Readthedocs
2
+RTD_NEW_THEME = True
3
+
4
+extensions = []
5
+templates_path = ['_templates']
6
+
7
+source_suffix = '.rst'
8
+
9
+master_doc = 'index'
10
+
11
+project = u'The LDAP plugin for Fuel'
12
+copyright = u'2015, Mirantis Inc.'
13
+
14
+version = '1.0-1.0.0-1'
15
+release = '1.0-1.0.0-1'
16
+
17
+exclude_patterns = []
18
+
19
+pygments_style = 'sphinx'
20
+
21
+html_theme = 'classic'
22
+html_static_path = ['_static']
23
+
24
+latex_documents = [
25
+  ('index', 'LDAPPluginforFuel.tex',
26
+   u'The LDAP plugin for Fuel documentation',
27
+   u'Mirantis Inc.', 'manual'),
28
+  ]
29
+
30
+# make latex stop printing blank pages between sections
31
+# http://stackoverflow.com/questions/5422997/sphinx-docs-remove-blank-pages-from-generated-pdfs
32
+latex_elements = {'classoptions': ',openany,oneside', 'babel':
33
+                  '\\usepackage[english]{babel}'}

+ 75
- 0
doc/source/configuration.rst View File

@@ -0,0 +1,75 @@
1
+
2
+Configuring LDAP plugin
3
+-----------------------
4
+
5
+#. Create a new OpenStack environment to use an existing LDAP server as authentication
6
+   backend for Keystone.
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>`_.
10
+
11
+#. Open *Settings* tab of the Fuel Web UI, scroll the page down and select
12
+   the *LDAP plugin for Keystone* checkbox:
13
+
14
+   .. image:: images/ldap-checkbox.png
15
+
16
+#. Fill in plugin settings into the text field. LDAP plugin features the following
17
+   parameters to enter:
18
+
19
+    ================================== ===============
20
+    Field                              Comment
21
+    ================================== ===============
22
+    Domain name                        Name of the Keystone domain.
23
+    LDAP URL                           URL for connecting to the LDAP server.
24
+    LDAP Suffix                        LDAP server suffix.
25
+    Use TLS                            Enable TLS for communicating with the LDAP server.
26
+    CA Chain                           CA trust chain in PEM format.
27
+
28
+    LDAP User                          User BindDN to query the LDAP server.
29
+    LDAP User Password                 Password for the BindDN to query the LDAP
30
+                                       server.
31
+    LDAP Query Scope                   The LDAP scope for queries, this can be
32
+                                       either "one" (onelevel/singleLevel) or
33
+                                       "sub" (subtree/wholeSubtree).
34
+    Users Tree DN                      Search base for users.
35
+    User Filter                        LDAP search filter for users.
36
+    User Object Class                  LDAP objectclass for users.
37
+    User ID Attribute                  LDAP attribute mapped to user id.
38
+    User Name Attribute                LDAP attribute mapped to user name.
39
+    User Password Attribute            LDAP attribute mapped to password.
40
+    User Enabled/Disabled Attribute    LDAP attribute mapped to enabled/disabled.
41
+    Groups Tree DN                     Search base for groups.
42
+    Group Filter                       LDAP search filter for groups.
43
+    Group Object Class                 LDAP objectclass for groups.
44
+    Group ID Attribute                 LDAP attribute mapped to group id.
45
+    Group Name Attribute               LDAP attribute mapped to group name.
46
+    Group Member Attribute             LDAP attribute that maps user to group.
47
+    Group description Attribute        LDAP attribute mapped to description.
48
+
49
+    ================================== ===============
50
+   
51
+
52
+   .. image:: images/settings.png
53
+
54
+   * Specify domain name, LDAP URL, LDAP suffix:
55
+
56
+     .. image:: images/ldap_settings.png
57
+
58
+   * Enable TLS use and put certificate if it is needed:
59
+
60
+     .. image:: images/tls_settings.png
61
+
62
+   * Specify LDAP user, password and other settings:
63
+
64
+     .. image:: images/user_ldap_settings.png
65
+
66
+   * To use LDAP groups, enter the corresponding values:
67
+
68
+     .. image:: images/group_ldap_settings.png
69
+
70
+
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>`_.
74
+
75
+

+ 26
- 0
doc/source/description.rst View File

@@ -0,0 +1,26 @@
1
+
2
+LDAP plugin for Fuel
3
+====================
4
+
5
+This plugin extends Mirantis OpenStack functionality by adding LDAP
6
+support. It allows to use an existing LDAP server as authentication
7
+backend for Keystone. Enabling this plugin means that all users
8
+except system users will be authenticated against the configured
9
+LDAP server.
10
+
11
+Please note that Fuel will not validate the settings, e.g. by
12
+attempting to connect to the LDAP server.
13
+
14
+Requirements
15
+------------
16
+
17
+================================== ===============
18
+Requirement                        Version/Comment
19
+================================== ===============
20
+Fuel                               7.0
21
+Pre-configured LDAP server
22
+MU (Maintenance Update)            3
23
+================================== ===============
24
+
25
+LDAP server should be pre-deployed and be accessible via Public network
26
+from Controller nodes.

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

@@ -0,0 +1,58 @@
1
+==========
2
+User Guide
3
+==========
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
+#. After successful deployment, all users from the LDAP directory matching the
23
+   configured filter criteria can authenticate against Keystone. To validate the
24
+   configuration, log into the Horizon dashboard using LDAP credentials:
25
+
26
+   .. 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/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/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_settings.png View File


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


BIN
doc/source/images/project_members.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


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

@@ -0,0 +1,18 @@
1
+==================================================================================
2
+Welcome to the Mirantis OpenStack LDAP Plugin Documentation!
3
+==================================================================================
4
+
5
+Plugin Guide
6
+==================
7
+
8
+.. toctree::
9
+   :maxdepth: 2
10
+
11
+   description
12
+   installation
13
+   configuration
14
+   guide
15
+   appendix
16
+
17
+
18
+

+ 39
- 0
doc/source/installation.rst View File

@@ -0,0 +1,39 @@
1
+==================
2
+Installation Guide
3
+==================
4
+
5
+Installing LDAP plugin
6
+============================================
7
+
8
+To install LDAP plugin, follow these steps:
9
+
10
+#. Download the plugin from the
11
+   `Fuel Plugins Catalog <https://www.mirantis.com/products/
12
+   openstack-drivers-and-plugins/fuel-plugins/>`_.
13
+
14
+#. Copy the plugin on an already installed Fuel Master node (SSH can be used for
15
+   that). If you do not have the Fuel Master node yet, see `Quick Start Guide
16
+   <https://software.mirantis.com/quick-start/>`_:
17
+
18
+   .. code-block:: bash
19
+
20
+      # scp ldap-1.0-1.0.0-1.noarch.rpm root@<Fuel_Master_IP>:/tmp
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
28
+
29
+#. Check if the plugin was installed successfully
30
+
31
+   .. code-block:: bash
32
+
33
+        # 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.

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

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

Loading…
Cancel
Save