diff --git a/.gitignore b/.gitignore new file mode 100644 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +# Sphinx +docs/_build/ diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,225 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help +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 " applehelp to make an Apple Help Book" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " epub3 to make an epub3" + @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)" + @echo " coverage to run coverage check of the documentation (if enabled)" + @echo " dummy to check syntax errors of document sources" + +.PHONY: clean +clean: + rm -rf $(BUILDDIR)/* + +.PHONY: html +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +.PHONY: dirhtml +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +.PHONY: singlehtml +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +.PHONY: pickle +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +.PHONY: json +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +.PHONY: htmlhelp +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." + +.PHONY: qthelp +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/salt-wrapper.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/salt-wrapper.qhc" + +.PHONY: applehelp +applehelp: + $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp + @echo + @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." + @echo "N.B. You won't be able to view it unless you put it in" \ + "~/Library/Documentation/Help or install it in your application" \ + "bundle." + +.PHONY: devhelp +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/salt-wrapper" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/salt-wrapper" + @echo "# devhelp" + +.PHONY: epub +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +.PHONY: epub3 +epub3: + $(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3 + @echo + @echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3." + +.PHONY: latex +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)." + +.PHONY: latexpdf +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." + +.PHONY: latexpdfja +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." + +.PHONY: text +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +.PHONY: man +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +.PHONY: texinfo +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)." + +.PHONY: info +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." + +.PHONY: gettext +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +.PHONY: changes +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +.PHONY: linkcheck +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." + +.PHONY: doctest +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +.PHONY: coverage +coverage: + $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage + @echo "Testing of coverage in the sources finished, look at the " \ + "results in $(BUILDDIR)/coverage/python.txt." + +.PHONY: xml +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +.PHONY: pseudoxml +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." + +.PHONY: dummy +dummy: + $(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy + @echo + @echo "Build finished. Dummy builder generates no files." diff --git a/docs/admin.rst b/docs/admin.rst new file mode 100644 --- /dev/null +++ b/docs/admin.rst @@ -0,0 +1,200 @@ +================================= +salt-wrapper administrator manual +================================= + +*************** +Problems solved +*************** + +Run multiple Salt masters on one server +======================================= + +You want to maintain several Salt masters from an unique server, +for example to target different projects. + +This can be useful to kickstart the Salt configuration for a new project, +before you dedicate a standalone instance for this project master. + +This configuration, if not well documented on Salt, is possible: +you can have several etc salt configuration directories, and pass +the right one to your salt commands using ``--config-dir`` argument. + +We offer a ``salt-get-config-dir`` command to map working directories +(generally a clone of a repository containing your Salt states) +and a Salt configuration directory to pass to the ``--config-dir`` argument. + +The map between working directories and configuration directories is stored +as a JSON document in ``/usr/local/etc/salt-wrapper.conf``. + +Wrapper to invoke salt commands +=============================== + +The ``salt-wrapper`` command allows to call a Salt command as the right user, +with the right configuration directory parameter. + +Use sudo capabilities +--------------------- +If you've an operations or deployment group, it's convenient to allow through +sudo capability the group users to run salt commands as ``salt`` user. + +There is one exception: if you need to run ``salt-call --local`` to provision +your salt master, this should be run as root. + +Instead to need to write or alias something like ``sudo -u salt salt ...``, +the wrapper takes care to prepend the salt command with the right sudo. + +Allow to avoid configuration parameters +--------------------------------------- + +The wrapper takes cake to call ``salt-get-config-dir`` and to pass the +result to the ``--config-dir`` argument. + +************ +Installation +************ + +OS +== + +UNIX-like OS +------------ +Currently, the wrapper targets POSIX operating systems. + +This software has been tested on FreeBSD 11. + +Not intended for Windows +------------------------ + +The ``salt-get-config-dir`` command will work on Windows +inside a Cygwin environment, but a dedicated wrapper using +``runas`` should be written. + +Manual installation +=================== + +Dependencies +------------ + +salt-wrapper requires the following software: + - Python 3 + - sudo + +Procedure +--------- + +#. Clone the repository or unpack a release archive +#. Run ``make install`` + +Upgrade +------- + +#. Unpack a new release archive or use ``git pull`` to update the repository +#. Run ``make deinstall install`` + +Deinstall +--------- + +#. Go to the source code folder +#. Run ``make deinstall`` + +Configuration file +================== + +The salt-wrapper configuration is written in JSON in the +``/usr/local/etc/salt-wrapper.conf`` file. + +If you wish to store the configuration file elsewhere, +define the ``SALT_WRAPPER_CONF`` environment variable +to the path to the configuration file. + +Here a sample: + +.. code-block:: json + :caption: /usr/local/etc/salt-wrapper.conf + :name: salt-wrapper-conf + + { + "roots": [ + { + "config": "/usr/local/etc/salt-woodscloud", + "states": "/opt/woodscloud-operations" + }, + { + "config": "/usr/local/etc/salt", + "states": "/opt/nasqueron-operations" + } + ] + } + +The ``roots`` array is a map of config and states directories: + - the ``config`` directory is the Salt one, containing your ``master`` file. + - the ``states`` directory is the one where your top.sls file exists. + +.. _shell-aliases: + +Shell aliases +============= + +tcsh +---- + +You add to your ``.cshrc`` file the following aliases: + +.. code-block:: tcsh + + alias salt 'salt-wrapper salt' + alias salt-call 'salt-wrapper salt-call' + alias salt-cloud 'salt-wrapper salt-cloud' + alias salt-key 'salt-wrapper salt-key' + alias salt-run 'salt-wrapper salt-run' + alias salt-ssh 'salt-wrapper salt-ssh' + +bash +---- + +You can add to your ``.profile`` or ``.bashrc`` file the following aliases: + +.. code-block:: bash + + alias salt='salt-wrapper salt' + alias salt-call='salt-wrapper salt-call' + alias salt-cloud='salt-wrapper salt-cloud' + alias salt-key='salt-wrapper salt-key' + alias salt-run='salt-wrapper salt-run' + alias salt-ssh='salt-wrapper salt-ssh' + +.. _sudo: + +Sudo configuration +================== + +In your /etc/sudoers.d directory (or directly in your /etc/sudoers, +you can provide rules to allow a dedicated operations or deployment +group to run salt as the salt user. + +Here a sample for FreeBSD: + +.. code-block:: none + :caption: /usr/local/etc/sudoers.d/salt + :name: sudo-for-salt + + Cmnd_Alias SALT = /usr/local/bin/salt, /usr/local/bin/salt-api, /usr/local/bin/salt-call, /usr/local/bin/salt-cloud, /usr/local/bin/salt-cp, /usr/local/bin/salt-key, /usr/local/bin/salt-master, /usr/local/bin/salt-minion, /usr/local/bin/salt-proxy, /usr/local/bin/salt-run, /usr/local/bin/salt-ssh, /usr/local/bin/salt-syndic, /usr/local/etc/rc.d/salt_master + + %salt ALL=(salt) NOPASSWD: SALT + %salt ALL=(ALL) NOPASSWD: /usr/local/bin/salt-call + +Here a sample for Linux: + +.. code-block:: none + :caption: /etc/sudoers.d/salt + :name: sudo-for-salt-linux + + Cmnd_Alias SALT = /usr/bin/salt, /usr/bin/salt-api, /usr/bin/salt-call, /usr/bin/salt-cloud, /usr/bin/salt-cp, /usr/bin/salt-key, /usr/bin/salt-master, /usr/bin/salt-minion, /usr/bin/salt-proxy, /usr/bin/salt-run, /usr/bin/salt-ssh, /usr/bin/salt-syndic, /usr/local/etc/rc.d/salt_master + + %salt ALL=(salt) NOPASSWD: SALT + %salt ALL=(ALL) NOPASSWD: /usr/bin/salt-call + +The last line allows to run ``salt-call`` as root, to be able to run +``salt-call --local`` to provision the master. That implies you give +root access to group, as they can run through Salt anything they want +as root. diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,63 @@ +# -*- coding: utf-8 -*- + +# +# ------------------------------------------------------------- +# Sphinx configuration for salt-wrapper +# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +# Project: salt-wrapper +# License: Trivial work, not eligible to copyright +# ------------------------------------------------------------- + +# ------------------------------------------------------------- +# Table of contents +# ------------------------------------------------------------- +# +# :: General onfiguration +# :: HTML output +# :: LaTeX output +# +# ------------------------------------------------------------- + +# ------------------------------------------------------------- +# General configuration +# ------------------------------------------------------------- + +extensions = [] +templates_path = ['_templates'] +source_suffix = '.rst' +master_doc = 'index' +project = u'salt-wrapper' +copyright = u'2017, Nasqueron' +author = u'Sébastien Santoro aka Dereckson' + +version = u'0.1' +release = u'0.1' + +language = None + +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +pygments_style = 'sphinx' + +todo_include_todos = False + +# ------------------------------------------------------------- +# HTML output +# ------------------------------------------------------------- + +html_theme = 'alabaster' +html_static_path = ['_static'] +htmlhelp_basename = 'salt-wrapperdoc' + +# ------------------------------------------------------------- +# LaTeX output +# ------------------------------------------------------------- + +latex_elements = { + 'papersize': 'a4paper' +} + +latex_documents = [ + (master_doc, 'salt-wrapper.tex', u'salt-wrapper Documentation', + u'Sébastien Santoro aka Dereckson', 'manual'), +] diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,21 @@ +.. salt-wrapper documentation master file, created by + sphinx-quickstart on Tue Oct 3 10:57:36 2017. + +Welcome to the salt-wrapper documentation +========================================= + +The documentation is divided in two parts, +by target users. + +Contents: + +.. toctree:: + :maxdepth: 3 + + admin + user + +Appendices +========== + +* :ref:`search` diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,281 @@ +@ECHO OFF + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set BUILDDIR=_build +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . +set I18NSPHINXOPTS=%SPHINXOPTS% . +if NOT "%PAPER%" == "" ( + set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% + set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% +) + +if "%1" == "" goto help + +if "%1" == "help" ( + :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. epub3 to make an epub3 + echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter + echo. text to make text files + echo. man to make manual pages + echo. texinfo to make Texinfo files + echo. gettext to make PO message catalogs + echo. changes to make an overview over 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 + echo. coverage to run coverage check of the documentation if enabled + echo. dummy to check syntax errors of document sources + goto end +) + +if "%1" == "clean" ( + for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i + del /q /s %BUILDDIR%\* + goto end +) + + +REM Check if sphinx-build is available and fallback to Python version if any +%SPHINXBUILD% 1>NUL 2>NUL +if errorlevel 9009 goto sphinx_python +goto sphinx_ok + +:sphinx_python + +set SPHINXBUILD=python -m sphinx.__init__ +%SPHINXBUILD% 2> nul +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +:sphinx_ok + + +if "%1" == "html" ( + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/html. + goto end +) + +if "%1" == "dirhtml" ( + %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. + goto end +) + +if "%1" == "singlehtml" ( + %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. + goto end +) + +if "%1" == "pickle" ( + %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the pickle files. + goto end +) + +if "%1" == "json" ( + %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the JSON files. + goto end +) + +if "%1" == "htmlhelp" ( + %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run HTML Help Workshop with the ^ +.hhp project file in %BUILDDIR%/htmlhelp. + goto end +) + +if "%1" == "qthelp" ( + %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run "qcollectiongenerator" with the ^ +.qhcp project file in %BUILDDIR%/qthelp, like this: + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\salt-wrapper.qhcp + echo.To view the help file: + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\salt-wrapper.ghc + goto end +) + +if "%1" == "devhelp" ( + %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. + goto end +) + +if "%1" == "epub" ( + %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The epub file is in %BUILDDIR%/epub. + goto end +) + +if "%1" == "epub3" ( + %SPHINXBUILD% -b epub3 %ALLSPHINXOPTS% %BUILDDIR%/epub3 + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The epub3 file is in %BUILDDIR%/epub3. + goto end +) + +if "%1" == "latex" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdf" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf + cd %~dp0 + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdfja" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf-ja + cd %~dp0 + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "text" ( + %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The text files are in %BUILDDIR%/text. + goto end +) + +if "%1" == "man" ( + %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The manual pages are in %BUILDDIR%/man. + goto end +) + +if "%1" == "texinfo" ( + %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. + goto end +) + +if "%1" == "gettext" ( + %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The message catalogs are in %BUILDDIR%/locale. + goto end +) + +if "%1" == "changes" ( + %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes + if errorlevel 1 exit /b 1 + echo. + echo.The overview file is in %BUILDDIR%/changes. + goto end +) + +if "%1" == "linkcheck" ( + %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck + if errorlevel 1 exit /b 1 + echo. + echo.Link check complete; look for any errors in the above output ^ +or in %BUILDDIR%/linkcheck/output.txt. + goto end +) + +if "%1" == "doctest" ( + %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest + if errorlevel 1 exit /b 1 + echo. + echo.Testing of doctests in the sources finished, look at the ^ +results in %BUILDDIR%/doctest/output.txt. + goto end +) + +if "%1" == "coverage" ( + %SPHINXBUILD% -b coverage %ALLSPHINXOPTS% %BUILDDIR%/coverage + if errorlevel 1 exit /b 1 + echo. + echo.Testing of coverage in the sources finished, look at the ^ +results in %BUILDDIR%/coverage/python.txt. + goto end +) + +if "%1" == "xml" ( + %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The XML files are in %BUILDDIR%/xml. + goto end +) + +if "%1" == "pseudoxml" ( + %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml. + goto end +) + +if "%1" == "dummy" ( + %SPHINXBUILD% -b dummy %ALLSPHINXOPTS% %BUILDDIR%/dummy + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. Dummy builder generates no files. + goto end +) + +:end diff --git a/docs/user.rst b/docs/user.rst new file mode 100644 --- /dev/null +++ b/docs/user.rst @@ -0,0 +1,70 @@ +======================== +salt-wrapper user manual +======================== + +Purpose +======= + +**salt-wrapper** allows you to run Salt command to target the correct +Salt configuration folder (for example if you've several Salt +masters on one server) and to prepend your command by sudo. + +Configure shell aliases +======================= + +See :ref:`shell-aliases` in the admin manual. + +Run a salt command +================== + +1. Go to the right folder containing your Salt states +2. Run from there (or any subdirectory) your Salt commands + +The aliases configured in the previous section will take care +to run salt-wrapper <your command> instead. + +If you don't want such alias, you can manually prepend your Salt +command by ``salt-wrapper``, it will works too. + +Troubleshoot +============ + +Nothing happens +--------------- + +If you run a ``salt-wrapper`` command and nothing happens, check you aren't +outside a directory declared in ``/usr/local/etc/salt-wrapper.conf`` +configuration file. + +You can also check that through the exit code of the wrapper script: + +.. code-block:: shell + + $ cd /tmp + $ salt-wrapper salt-call + $ echo $? + 1 + +I got a sudo prompt +------------------- + +To use comfortably with seamless integration the wrapper, +you need to configure sudo to allow an ops group to run +commands as salt. + +See :ref:`sudo` in the admin manual. + +I need to disable something +--------------------------- +The ``salt-wrapper`` development follows the YAGNI principle: to reduce +the cost of maintenance, we only implement features deemed necessary. + +As such, in the initial release, there is no flag to enable of disable +features. If you've a root problem requiring such flag to disable a feature, +we'll be happy to add an option in ``salt-wrapper.conf`` or offer a workaround. +Just report an issue on our tracker. + +Report issues +------------- + +Issues can be reported at https://devcentral.nasqueron.org