Merge "Adds Plugin Guide"

This commit is contained in:
Jenkins 2016-05-12 14:33:19 +00:00 committed by Gerrit Code Review
commit 44156eb215
23 changed files with 458 additions and 0 deletions

183
doc/Makefile Normal file
View File

@ -0,0 +1,183 @@
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = build
# User-friendly check for sphinx-build
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
$(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/)
endif
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
# SVG to PDF conversion
SVG2PDF = inkscape
SVG2PDF_FLAGS =
# Build a list of SVG files to convert to PDF
PDF_FILES := $(foreach dir, images, $(patsubst %.svg,%.pdf,$(wildcard $(dir)/*.svg)))
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " xml to make Docutils-native XML files"
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
clean:
rm -rf $(BUILDDIR)/*
rm -f $(PDF_FILES)
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/LMAcollector.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/LMAcollector.qhc"
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/LMAcollector"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/LMAcollector"
@echo "# devhelp"
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
latexpdfja:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through platex and dvipdfmx..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
gettext:
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
xml:
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
@echo
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
pseudoxml:
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
@echo
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

10
doc/source/appendix.rst Normal file
View File

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

33
doc/source/conf.py Normal file
View File

@ -0,0 +1,33 @@
# Always use the default theme for Readthedocs
RTD_NEW_THEME = True
extensions = []
templates_path = ['_templates']
source_suffix = '.rst'
master_doc = 'index'
project = u'The LDAP plugin for Fuel'
copyright = u'2015, Mirantis Inc.'
version = '1.0-1.0.0-1'
release = '1.0-1.0.0-1'
exclude_patterns = []
pygments_style = 'sphinx'
html_theme = 'classic'
html_static_path = ['_static']
latex_documents = [
('index', 'LDAPPluginforFuel.tex',
u'The LDAP plugin for Fuel documentation',
u'Mirantis Inc.', 'manual'),
]
# make latex stop printing blank pages between sections
# http://stackoverflow.com/questions/5422997/sphinx-docs-remove-blank-pages-from-generated-pdfs
latex_elements = {'classoptions': ',openany,oneside', 'babel':
'\\usepackage[english]{babel}'}

View File

@ -0,0 +1,75 @@
Configuring LDAP plugin
-----------------------
#. Create a new OpenStack environment to use an existing LDAP server as authentication
backend for Keystone.
For more information about environment creation, see `Mirantis OpenStack
User Guide <http://docs.mirantis.com/openstack
/fuel/fuel-7.0/user-guide.html#create-a-new-openstack-environment>`_.
#. Open *Settings* tab of the Fuel Web UI, scroll the page down and select
the *LDAP plugin for Keystone* checkbox:
.. image:: images/ldap-checkbox.png
#. Fill in plugin settings into the text field. LDAP plugin features the following
parameters to enter:
================================== ===============
Field Comment
================================== ===============
Domain name Name of the Keystone domain.
LDAP URL URL for connecting to the LDAP server.
LDAP Suffix LDAP server suffix.
Use TLS Enable TLS for communicating with the LDAP server.
CA Chain CA trust chain in PEM format.
LDAP User User BindDN to query the LDAP server.
LDAP User Password Password for the BindDN to query the LDAP
server.
LDAP Query Scope The LDAP scope for queries, this can be
either "one" (onelevel/singleLevel) or
"sub" (subtree/wholeSubtree).
Users Tree DN Search base for users.
User Filter LDAP search filter for users.
User Object Class LDAP objectclass for users.
User ID Attribute LDAP attribute mapped to user id.
User Name Attribute LDAP attribute mapped to user name.
User Password Attribute LDAP attribute mapped to password.
User Enabled/Disabled Attribute LDAP attribute mapped to enabled/disabled.
Groups Tree DN Search base for groups.
Group Filter LDAP search filter for groups.
Group Object Class LDAP objectclass for groups.
Group ID Attribute LDAP attribute mapped to group id.
Group Name Attribute LDAP attribute mapped to group name.
Group Member Attribute LDAP attribute that maps user to group.
Group description Attribute LDAP attribute mapped to description.
================================== ===============
.. image:: images/settings.png
* Specify domain name, LDAP URL, LDAP suffix:
.. image:: images/ldap_settings.png
* Enable TLS use and put certificate if it is needed:
.. image:: images/tls_settings.png
* Specify LDAP user, password and other settings:
.. image:: images/user_ldap_settings.png
* To use LDAP groups, enter the corresponding values:
.. image:: images/group_ldap_settings.png
#. Finalize environment configuration and run network verification check.
Once done,
`deploy your environment <http://docs.mirantis.com/openstack/fuel/fuel-7.0/user-guide.html#deploy-changes>`_.

View File

@ -0,0 +1,26 @@
LDAP plugin for Fuel
====================
This plugin extends Mirantis OpenStack functionality by adding LDAP
support. It allows to use an existing LDAP server as authentication
backend for Keystone. Enabling this plugin means that all users
except system users will be authenticated against the configured
LDAP server.
Please note that Fuel will not validate the settings, e.g. by
attempting to connect to the LDAP server.
Requirements
------------
================================== ===============
Requirement Version/Comment
================================== ===============
Fuel 7.0
Pre-configured LDAP server
MU (Maintenance Update) 3
================================== ===============
LDAP server should be pre-deployed and be accessible via Public network
from Controller nodes.

58
doc/source/guide.rst Normal file
View File

@ -0,0 +1,58 @@
==========
User Guide
==========
#. After successfull environment deployment, log into Horizon into the default domain:
.. image:: images/default_domain.png
#. Go to Identity -> Domains, select the required domain and select
*Set Domain Context* for it:
.. image:: images/domains.png
.. image:: images/domain_context.png
#. Go to Identity -> Projects and select 'Create Project' to create a new project for the domain
and add user members to the project:
.. image:: images/project.png
.. image:: images/project_members.png
#. After successful deployment, all users from the LDAP directory matching the
configured filter criteria can authenticate against Keystone. To validate the
configuration, log into the Horizon dashboard using LDAP credentials:
.. image:: images/dashboard.png
#. You can also try to obtain a token to validate authentication:
.. code-block:: bash
# curl -i -s -H "Content-Type: application/json" -d '
{ "auth": {
"identity": {
"methods": ["password"],
"password": {
"user": {
"name": "admin",
"domain": { "id": "default" },
"password": "admin"
}
}
},
"scope": {
"project": {
"name": "admin",
"domain": { "id": "default" }
}
}
}
}' http://<dashboard_ip>:5000/v3/auth/tokens
HTTP/1.1 201 Created
X-Subject-Token: 77a7c2da81f54bb7b46efefa7c7bb5ae
Vary: X-Auth-Token
Content-Type: application/json
Content-Length: 2173

Binary file not shown.

After

Width:  |  Height:  |  Size: 16 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 16 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 38 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 48 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 127 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 42 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 26 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 122 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 22 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 60 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 60 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 100 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 123 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 63 KiB

18
doc/source/index.rst Normal file
View File

@ -0,0 +1,18 @@
==================================================================================
Welcome to the Mirantis OpenStack LDAP Plugin Documentation!
==================================================================================
Plugin Guide
==================
.. toctree::
:maxdepth: 2
description
installation
configuration
guide
appendix

View File

@ -0,0 +1,39 @@
==================
Installation Guide
==================
Installing LDAP plugin
============================================
To install LDAP plugin, follow these steps:
#. Download the plugin from the
`Fuel Plugins Catalog <https://www.mirantis.com/products/
openstack-drivers-and-plugins/fuel-plugins/>`_.
#. Copy the plugin on an already installed Fuel Master node (SSH can be used for
that). If you do not have the Fuel Master node yet, see `Quick Start Guide
<https://software.mirantis.com/quick-start/>`_:
.. code-block:: bash
# scp ldap-1.0-1.0.0-1.noarch.rpm root@<Fuel_Master_IP>:/tmp
#. Log into the Fuel Master node. Install the plugin:
.. code-block:: bash
# cd /tmp
# fuel plugins --install ldap-1.0-1.0.0-1.noarch.rpm
#. Check if the plugin was installed successfully
.. code-block:: bash
# fuel plugins
id | name | version | package_version
---|--------------|----------|----------------
1 | ldap | 1.0.0 | 2.0.0
#. MU-3 (Maintenance Update) should be installed to provide proper work of keystone providers
with domains during deployment process.

16
doc/source/removal.rst Normal file
View File

@ -0,0 +1,16 @@
Uninstalling LDAP plugin
------------------------
Delete all environments, in which the LDAP plugin has been enabled.
#. Uninstall the plugin::
# fuel plugins --remove ldap==1.0.0
#. Check if the plugin was uninstalled successfully::
# fuel plugins$
id | name | version | package_version
---|---------------------------|----------|------