Adds Plugin Guide
This commit provides the following changes: - Plugin Guide in RST format - Sphinx support [1] [1] https://wiki.openstack.org/wiki/Fuel/Plugins#Documentation_files_structure_and_Sphinx_usage Change-Id: I998fb9b68b3b901f2cc6ef20afa2a04cdea60b15
|
@ -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."
|
|
@ -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/>`_
|
|
@ -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}'}
|
|
@ -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>`_.
|
||||
|
||||
|
|
@ -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.
|
|
@ -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
|
||||
|
After Width: | Height: | Size: 16 KiB |
After Width: | Height: | Size: 16 KiB |
After Width: | Height: | Size: 38 KiB |
After Width: | Height: | Size: 48 KiB |
After Width: | Height: | Size: 127 KiB |
After Width: | Height: | Size: 42 KiB |
After Width: | Height: | Size: 26 KiB |
After Width: | Height: | Size: 122 KiB |
After Width: | Height: | Size: 22 KiB |
After Width: | Height: | Size: 60 KiB |
After Width: | Height: | Size: 60 KiB |
After Width: | Height: | Size: 100 KiB |
After Width: | Height: | Size: 123 KiB |
After Width: | Height: | Size: 63 KiB |
|
@ -0,0 +1,18 @@
|
|||
==================================================================================
|
||||
Welcome to the Mirantis OpenStack LDAP Plugin Documentation!
|
||||
==================================================================================
|
||||
|
||||
Plugin Guide
|
||||
==================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
description
|
||||
installation
|
||||
configuration
|
||||
guide
|
||||
appendix
|
||||
|
||||
|
||||
|
|
@ -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.
|
|
@ -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
|
||||
---|---------------------------|----------|------
|
||||
|
||||
|