diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..73624c6 --- /dev/null +++ b/doc/Makefile @@ -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 ' where 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." diff --git a/doc/source/appendix.rst b/doc/source/appendix.rst new file mode 100644 index 0000000..86148e8 --- /dev/null +++ b/doc/source/appendix.rst @@ -0,0 +1,10 @@ +================== +Appendix +================== + +Links +========================= + +- `Mirantis OpenStack User Guide `_ +- `Fuel Plugins Catalog `_ +- `Quick Start Guide `_ diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 0000000..1eab320 --- /dev/null +++ b/doc/source/conf.py @@ -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}'} diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst new file mode 100644 index 0000000..34bbacc --- /dev/null +++ b/doc/source/configuration.rst @@ -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 `_. + +#. 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 `_. + + diff --git a/doc/source/description.rst b/doc/source/description.rst new file mode 100644 index 0000000..6ec0529 --- /dev/null +++ b/doc/source/description.rst @@ -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. diff --git a/doc/source/guide.rst b/doc/source/guide.rst new file mode 100644 index 0000000..5d8e9f3 --- /dev/null +++ b/doc/source/guide.rst @@ -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://:5000/v3/auth/tokens + + HTTP/1.1 201 Created + X-Subject-Token: 77a7c2da81f54bb7b46efefa7c7bb5ae + Vary: X-Auth-Token + Content-Type: application/json + Content-Length: 2173 + diff --git a/doc/source/images/dashboard.png b/doc/source/images/dashboard.png new file mode 100644 index 0000000..c63947e Binary files /dev/null and b/doc/source/images/dashboard.png differ diff --git a/doc/source/images/default_domain.png b/doc/source/images/default_domain.png new file mode 100644 index 0000000..fe4df2c Binary files /dev/null and b/doc/source/images/default_domain.png differ diff --git a/doc/source/images/domain_context.png b/doc/source/images/domain_context.png new file mode 100644 index 0000000..5c8f750 Binary files /dev/null and b/doc/source/images/domain_context.png differ diff --git a/doc/source/images/domains.png b/doc/source/images/domains.png new file mode 100644 index 0000000..745a1a4 Binary files /dev/null and b/doc/source/images/domains.png differ diff --git a/doc/source/images/enable_ldap_plugin.png b/doc/source/images/enable_ldap_plugin.png new file mode 100644 index 0000000..edfc126 Binary files /dev/null and b/doc/source/images/enable_ldap_plugin.png differ diff --git a/doc/source/images/group_ldap_settings.png b/doc/source/images/group_ldap_settings.png new file mode 100644 index 0000000..44962f0 Binary files /dev/null and b/doc/source/images/group_ldap_settings.png differ diff --git a/doc/source/images/ldap-checkbox.png b/doc/source/images/ldap-checkbox.png new file mode 100644 index 0000000..27ee64f Binary files /dev/null and b/doc/source/images/ldap-checkbox.png differ diff --git a/doc/source/images/ldap_plugin.png b/doc/source/images/ldap_plugin.png new file mode 100644 index 0000000..52421a3 Binary files /dev/null and b/doc/source/images/ldap_plugin.png differ diff --git a/doc/source/images/ldap_settings.png b/doc/source/images/ldap_settings.png new file mode 100644 index 0000000..a086aba Binary files /dev/null and b/doc/source/images/ldap_settings.png differ diff --git a/doc/source/images/project.png b/doc/source/images/project.png new file mode 100644 index 0000000..b4ab3f4 Binary files /dev/null and b/doc/source/images/project.png differ diff --git a/doc/source/images/project_members.png b/doc/source/images/project_members.png new file mode 100644 index 0000000..d34d64d Binary files /dev/null and b/doc/source/images/project_members.png differ diff --git a/doc/source/images/settings.png b/doc/source/images/settings.png new file mode 100644 index 0000000..c3bf3f2 Binary files /dev/null and b/doc/source/images/settings.png differ diff --git a/doc/source/images/tls_settings.png b/doc/source/images/tls_settings.png new file mode 100644 index 0000000..7f67e5a Binary files /dev/null and b/doc/source/images/tls_settings.png differ diff --git a/doc/source/images/user_ldap_settings.png b/doc/source/images/user_ldap_settings.png new file mode 100644 index 0000000..10b4b9b Binary files /dev/null and b/doc/source/images/user_ldap_settings.png differ diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 0000000..f2f761c --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,18 @@ +================================================================================== +Welcome to the Mirantis OpenStack LDAP Plugin Documentation! +================================================================================== + +Plugin Guide +================== + +.. toctree:: + :maxdepth: 2 + + description + installation + configuration + guide + appendix + + + diff --git a/doc/source/installation.rst b/doc/source/installation.rst new file mode 100644 index 0000000..922ec00 --- /dev/null +++ b/doc/source/installation.rst @@ -0,0 +1,39 @@ +================== +Installation Guide +================== + +Installing LDAP plugin +============================================ + +To install LDAP plugin, follow these steps: + +#. Download the plugin from the + `Fuel Plugins Catalog `_. + +#. 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 + `_: + + .. code-block:: bash + + # scp ldap-1.0-1.0.0-1.noarch.rpm root@:/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. diff --git a/doc/source/removal.rst b/doc/source/removal.rst new file mode 100644 index 0000000..b4d089e --- /dev/null +++ b/doc/source/removal.rst @@ -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 + ---|---------------------------|----------|------ + +