xCAT/xcat-core
2
0
Fork 0
mirror of https://github.com/xcat2/xcat-core.git synced 2025-08-22 11:10:24 +00:00
Code Issues Releases Wiki Activity

Merge branch 'master' of xcat-doc into DOC_MERGE

Browse Source
This commit is contained in:
Victor Hu
2015-08-20 15:56:25 -04:00
parent 1c135343c0 dfe749793c
commit 32f0347d8a
177 changed files with 2901 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

192
docs/Makefile Normal file
View File

@@ -0,0 +1,192 @@
# 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
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage 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 " applehelp to make an Apple Help Book"
@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)"
@echo " coverage to run coverage check of the documentation (if enabled)"
clean:
rm -rf $(BUILDDIR)/*
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/xCAT3.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/xCAT3.qhc"
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."
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/xCAT3"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/xCAT3"
@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."
coverage:
$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
@echo "Testing of coverage in the sources finished, look at the " \
"results in $(BUILDDIR)/coverage/python.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."

263
docs/make.bat Normal file
View File

@@ -0,0 +1,263 @@
@ECHO OFF
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set BUILDDIR=build
set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% source
set I18NSPHINXOPTS=%SPHINXOPTS% source
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. 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
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% 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\xCAT3.qhcp
echo.To view the help file:
echo.^> assistant -collectionFile %BUILDDIR%\qthelp\xCAT3.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" == "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
)
:end

2
docs/source/advanced/change_mn_ip.rst Normal file
View File

@@ -0,0 +1,2 @@
Changing the Hostname or IP for Management Node
===============================================

2
docs/source/advanced/change_node_ip.rst Normal file
View File

@@ -0,0 +1,2 @@
Chaning the Hostname or IP for Compute Node
===========================================

52
docs/source/advanced/confluent/client/confluent_client.rst Normal file
View File

@@ -0,0 +1,52 @@
Starting the confetty client
============================
As the root user, running ``/opt/confluent/bin/confetty`` will open the confetty prompt ::
[root@c910f02c05p03 ~]# /opt/confluent/bin/confetty
/ ->
Creating a non root user
========================
It's recommenteed to create a non root user to use to connect to confetty
#. Create a non-root user on the management node: ::
useradd -m vhu
#. As root, create a non-root user in confetty: ::
/opt/confluent/bin/confetty create users/vhu
#. Set the password for the non-root user: ::
/opt/confluent/bin/confetty set users/vhu password="mynewpassword"
password="********"
Connecting to a remote server
=============================
In order to do remote sessions, keys must first be added to ``/etc/confluent``
* /etc/confluent/privkey.pem - private key
* /etc/confluent/srvcert.pem - server cert
If you want to use the xCAT Keys, you can simple copy them into ``/etc/confluent`` ::
cp /etc/xcat/cert/server-key.pem /etc/confluent/privkey.pem
cp /etc/xcat/cert/server-cert.pem /etc/confluent/srvcert.pem
Start confetty, specify the server IP address: ::
confetty -s 127.0.0.1
TODO: Add text for exporting user/pass into environment

7
docs/source/advanced/confluent/client/index.rst Normal file
View File

@@ -0,0 +1,7 @@
confluent-client
================
.. toctree::
:maxdepth: 2
confluent_client.rst

16
docs/source/advanced/confluent/index.rst Normal file
View File

@@ -0,0 +1,16 @@
Confluent
=========
Confluent is a new codebase with a few goals in mind:
* Augment xCAT 2.X series
* Potentially serve in place of xCAT-server for the next generation of xCAT
**Disclaimer:** *Confluent code in conjunction with xCAT 2.X is currently BETA, use at your own risk*
.. toctree::
:maxdepth: 2
server/index.rst
client/index.rst

166
docs/source/advanced/confluent/server/confluent_server.rst Normal file
View File

@@ -0,0 +1,166 @@
Getting Started
===============
For xCAT 2.9.1 and later, confluent is intended to be used in conjunction with xCAT.
The following documentation assumes that xCAT is already installed and configured on the management node.
Download
========
confluent
---------
rpms
~~~~
The latest confluent rpms are built and provided for your convenience: `confluent rpms <https://sourceforge.net/projects/xcat/files/confluent/rpms>`_. However, the rpms are not built on a regular release schedule. To use the latest code base, consider building the rpms from :ref:`label_confluent_source`.
The following example downloads the confluent tar package and creates a local repository on your management node::
mkdir ~/confluent
cd ~/confluent
wget https://path-to-confluent/confluent-X.X-repo.tbz2
tar jxvf confluent-X.X-repo.tbz2
cd confluent-X.X
./mklocalrepo.sh
.. _label_confluent_source:
source
~~~~~~
To build from source, ensure your machine has the correct development packages to build rpms, then execute hte following:
* Clone the git repo: ::
git clone https://github.com/xcat2/confluent.git
* Build the ``confluent-server`` and ``confluent-client`` packages: ::
cd confluent/confluent_server ; ./buildrpm ; cd -
cd confluent/confluent_client ; ./buildrpm ; cd -
confluent-dep
-------------
The latest confluent dependency packages are provided for your convenience: `confluent-deps <http://sourceforge.net/projects/xcat/files/confluent-dep/>`_
The following example describes the steps for **rhels7.1** on **ppc64le**::
mkdkir ~/confluent
cd ~/confluent
wget https://path/to/confluent-dep/rh7/ppc64le/confluent-dep-rh7-ppc64le.tar.bz2
tar -jxvf confluent-dep-rh7-ppc64le.tar.bz2
cd confluent-dep-rh7-ppc64le/
./mklocalrepo.sh
**Note:** If the OS/architecture you are looking for is not provided under confluent-dep,
please send an email to the xcat-users mailing list: xcat-users@lists.sourceforge.net
Install
=======
*confluent and confluent-deps must be downloaded to the management node before installing*
xCAT 2.9.1 began shipping a new rpm ``xCAT-confluent``.
Installing ``xCAT-confluent`` via yum will pull in the confluent dependencies::
yum install xCAT-confluent
You may find it helpful to add the confluent paths into your system path::
CONFLUENTROOT=/opt/confluent
export PATH=$CONFLUENTROOT/bin:$PATH
export MANPATH=$CONFLUENTROOT/share/man:$MANPATH
Configuration
=============
Starting/Stopping confluent
---------------------------
To start confluent::
service confluent start
To stop confluent::
service confluent stop
If you want confluent daemon to start automatically at bootup, add confluent service to ``chkconfig``::
chkconfig --add confluent
Replacing conserver with confluent
----------------------------------
A new keyword, ``consoleservice``, has been added to the xCAT site table to allow the system administrator to control between **conserver** and **confluent**. If ``consoleservice`` is not set, default behavior is to use **conserver**.
Set the consoleservice to confluent::
chdef -t site consoleservice='confluent'
Run ``makeconfluentcfg`` to create the confluent configuration files::
makeconfluentcfg
Use ``rcons`` as before to start the console session.::
rcons <singlenode>
# If using confluent, a timestamp will be shown on the
# console title next to the node name
<singlenode> [15:05]
Web Browser access
==================
Confluent-api and confluent-consoles are able to be accessed from the browser.
It is **highly** recommended that you create a non-root user to access the sessions::
Create the non-root user on the management node
# useradd -m vhu
Create a non-root user in confetty
# /opt/confluent/bin/confetty create users/vhu
Set the password for the non-root user
# /opt/confluent/bin/confetty set users/vhu password="mynewpassword"
password="********"
Rest Explorer
=============
TODO: some intro text
Configure the httpd configuration for confluent-api by creating a ``confluent.conf`` file under ``/etc/httpd/conf.d/`` directory::
The example uses server ip: 10.2.5.3 and port 4005
cat /etc/httpd/conf.d/confluent.conf
LoadModule proxy_http_module modules/mod_proxy_http.so
<Location /confluent-api>
ProxyPass http://10.2.5.3:4005
</Location>
#restart httpd
service httpd restart
Now point your browser to: ``http://<server ip>:<port>`` and log in with the non-root user and password created above.
Confluent consoles
==================
confluent-web is provided in a subdirectory under the confluent project `confluent_web <https://sourceforge.net/p/xcat/confluent/ci/master/tree/confluent_web/>`_
Download the content of that directory to ``/var/www/html/confluent`` and point your browser to::
http://<server ip>/confluent/consoles.html

8
docs/source/advanced/confluent/server/index.rst Normal file
View File

@@ -0,0 +1,8 @@
confluent-server
================
.. toctree::
:maxdepth: 2
confluent_server.rst

7
docs/source/advanced/docker/index.rst Normal file
View File

@@ -0,0 +1,7 @@
Docker
======
Placeholder for Docker related topics
.. toctree::
:maxdepth: 2

72
docs/source/advanced/hamn/high_available_management_node.rst Normal file
View File

@@ -0,0 +1,72 @@
========
Overview
========
The xCAT management node plays an important role in the cluster, if the management node is down for whatever reason, the administrators will lose the management capability for the whole cluster, until the management node is back up and running. In some configuration, like the Linux nfs-based statelite in a non-hierarchy cluster, the compute nodes may not be able to run at all without the management node. So, it is important to consider the high availability for the management node.
The goal of the HAMN(High Availability Management Node) configuration is, when the primary xCAT management node fails, the standby management node can take over the role of the management node, either through automatic failover or through manual procedure performed by the administrator, and thus avoid long periods of time during which your cluster does not have active cluster management function available.
============================
Configuration considerations
============================
xCAT provides several configuration options for the HAMN, you can select one of the option based on your failover requirements and hardware configuration, the following configuration considerations should be able to help you to make the decision.
******************************
Data synchronization mechanism
******************************
The data synchronization is important for any high availability configuration. When the xCAT management node failover occurs, the xCAT data needs to be exactly the same before failover, and some of the operating system configuration should also be synchronized between the two management nodes. To be specific, the following data should be synchronized between the two management nodes to make the xCAT HAMN work:
* xCAT database
* xCAT configuration files, like /etc/xcat, ~/.xcat, /opt/xcat
* The configuration files for the services that are required by xCAT, like named, DHCP, apache, nfs, ssh, etc.
* The operating systems images repository and users customization data repository, the /install directory contains these repositories in most cases.
There are a lot of ways for data syncronization, but considering the specific xCAT HAMN requirements, only several of the data syncronziation options are practical for xCAT HAMN.
**1\. Move physical disks between the two management nodes**: if we could physically move the hard disks from the failed management node to the backup management node, and bring up the backup management node, then both the operating system and xCAT data will be identical between the new management node the failed management node. RAID1 or disk mirroring could be used to avoid the disk be a single point of failure.
**2\. Shared data**: the two management nodes use the single copy of xCAT data, no matter which management node is the primary MN, the cluster management capability is running on top of the single data copy. The acess to the data could be done through various ways like shared storage, NAS, NFS, samba etc. Based on the protocol being used, the data might be accessable only on one management node at a time or be accessable on both management nodes in parellel. If the data could only be accessed from one management node, the failover process need to take care of the data access transition; if the data could be accessed on both management nodes, the failover does not need to consider the data access transition, it usually means the failover process could be faster.
Warning: Running database through network file system has a lot of potential problems and is not practical, however, most of the database system provides database replication feature that can be used to synronize the database between the two management nodes.
**3\. Mirroring**: each of the management node has its own copy of the xCAT data, and the two copies of data are syncronized through mirroring mechanism. DRBD is used widely in the high availability configuration scenarios, to provide data replication by mirroring a whole block device via network. If we put all the important data for xCAT onto the DRBD devices, then it could assure the data is synchronized between the two management nodes. Some parallel file system also provides capability to mirror data through network.
*************************************
Manual failover VS automatic failover
*************************************
When the primary management node fails, the backup management node could automatically take over, or the administrator has to perform some manual procedure to finish the failover. In general, the automatic failover takes less time to detect the failure and perform and failover, comparing with the manual failover, but the automatic failover requires more complex configuration. We could not say the automatic failover is better than the manual failover in all cases, the following factors should be considered when deciding the manual failover or automatic failover:
**1\. How long the cluster could survive if the management node is down?**
If the cluster could not survive for more than several minutes, then the automatic failover might be the only option; if the compute nodes could run without the management node, at least for a while, then the manual failover could be an option.
From xCAT perspective, if the management node needs to provide network services like DHCP, named, ntp or nfs to the compute nodes, then the cluster probably could not survive too long if the management node is down; if the management node only performs hardware control and some other management capabilities, then the failed management node may not cause too much trouble for the cluster. xCAT provides various options for configuring if the compute nodes rely on the network services on the management node.
**2\. Configuration complexity**
The configuration for the high availability applications is usually complex, it may take a long time to configure, debug and stablize the high availability configuration.
**3\. Maintenance effort**
The automatic failover brings in several high availability applications, after the initial configuration is done, additional maintenance effort will be needed. For example, taking care of the high availability applications during cluster update, the updates for the high availability applications themselves, trouble shooting any problems with the high availability applications. A simple question may be able to help you to decide: could you get technical support if some of the high availability applications run into problems? All software has bugs ...
=====================
Configuration Options
=====================
The combinations of data synchronization mechanism and manual/automatic failover indicates different HAMN configuration options, the table below list all the combinations (the bold numbers are the combinations xCAT has documented and tested):
+-------------------+-------------------------+-----------------+--------------+
|# | **Move physical disks** | **Shared data** | **Mirroring**|
+-------------------+-------------------------+-----------------+--------------+
|Manual Failover | **1** | **2** | 3 |
+-------------------+-------------------------+-----------------+--------------+
|Automatic Failover | 4 | 5 | **6** |
+-------------------+-------------------------+-----------------+--------------+

7
docs/source/advanced/hamn/index.rst Normal file
View File

@@ -0,0 +1,7 @@
Highly Available Management Node
================================
.. toctree::
:maxdepth: 2
high_available_management_node.rst

2
docs/source/advanced/hierarchy_cluster.rst Normal file
View File

@@ -0,0 +1,2 @@
Setting Up a Linux Hierarchical Cluster
=======================================

2
docs/source/advanced/ib.rst Normal file
View File

@@ -0,0 +1,2 @@
Managing the Mellanox Infiniband Network
========================================

24
docs/source/advanced/index.rst Normal file
View File

@@ -0,0 +1,24 @@
Advanced Topics
===============
.. toctree::
:maxdepth: 2
restapi/index.rst
mixed_cluster.rst
hierarchy_cluster.rst
hamn/index.rst
change_mn_ip.rst
change_node_ip.rst
xcat_security.rst
kit.rst
ib.rst
confluent/index.rst
docker/index.rst
ipv6_support.rst
xcat_port.rst
sysclone.rst
switch_mgmt.rst
vlan.rst
zone.rst
softlayer.rst

2
docs/source/advanced/ipv6_support.rst Normal file
View File

@@ -0,0 +1,2 @@
Configuring IPv6 in xCAT Cluster
================================

2
docs/source/advanced/kit.rst Normal file
View File

@@ -0,0 +1,2 @@
Using Software KITs
===================

87
docs/source/advanced/mixed_cluster.rst Normal file
View File

@@ -0,0 +1,87 @@
Mixed Cluster Management
========================
ppc64 mgmt node
---------------
Provision x86_64 (bare metal)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In order to provision x86_64 ipmi-based machines from xCAT management node (ppc64), there are a few required xCAT dependency RPMs that must be installed:
* ``elilo-xcat``
* ``xnba-undi``
* ``syslinux-xcat``
Install these RPMs using the following command: ::
yum install elilo-xcat xnba-undi syslinux-xcat
On the ppc64 management node, obtain an x86_64 operating system ISO and add it into the xCAT osimage table by using the copycds command: ::
copycds /tmp/RHEL-6.6-20140926.0-Server-x86_64-dvd1.iso
Create a node definition for the x86_64 compute node, here is a sample: ::
lsdef -z c910f04x42
# <xCAT data object stanza file>
c910f04x42:
objtype=node
arch=x86_64
bmc=10.4.42.254
bmcpassword=PASSW0RD
bmcusername=USERID
chain=runcmd=bmcsetup,shell
cons=ipmi
groups=all
initrd=xcat/osimage/rhels6.6-x86_64-install-compute/initrd.img
installnic=mac
kcmdline=quiet repo=http://!myipfn!:80/install/rhels6.6/x86_64 ks=http://!myipfn!:80/install/autoinst/c910f04x42 ksdevice=34:40:b5:b9:c0:18 cmdline console=tty0 console=ttyS0,115200n8r
kernel=xcat/osimage/rhels6.6-x86_64-install-compute/vmlinuz
mac=34:40:b5:b9:c0:18
mgt=ipmi
netboot=xnba
nodetype=osi
os=rhels6.6
profile=compute
provmethod=rhels6.6-x86_64-install-compute
serialflow=hard
serialport=0
serialspeed=115200
Provision the node using the following commands: ::
# The following prepares the kickstart file in /install/autoinst
nodeset c910f04x42 osimage=rhels6.6-x86_64-install-compute
# Tells the BIOS to network boot on the next power on
rsetboot c910f04x42 net
# Reboots the node
rpower c910f04x42 boot
Provision x86_64 (diskless)
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Troubleshooting
^^^^^^^^^^^^^^^
**Error:** The following Error message comes out when running nodeset: ::
Error: Unable to find pxelinux.0 at /opt/xcat/share/xcat/netboot/syslinux/pxelinux.0
**Resolution:**
The syslinux network booting files are missing.
Install the sylinux-xcat package provided in the xcat-deps repository: ``yum -y install syslinux-xcat``
x86_64 mgmt node
----------------
Provision ppc64 compute nodes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

8
docs/source/advanced/restapi/index.rst Normal file
View File

@@ -0,0 +1,8 @@
xCAT Web Services REST API
==========================
.. toctree::
:maxdepth: 2
set_up_ws.rst
restapi.rst

2
docs/source/advanced/restapi/restapi.rst Normal file
View File

@@ -0,0 +1,2 @@
REST API Reference
==================

2
docs/source/advanced/restapi/set_up_ws.rst Normal file
View File

@@ -0,0 +1,2 @@
Set Up Web Service for REST API
===============================

2
docs/source/advanced/softlayer.rst Normal file
View File

@@ -0,0 +1,2 @@
Using xCAT in SoftLayer
=======================

2
docs/source/advanced/switch_mgmt.rst Normal file
View File

@@ -0,0 +1,2 @@
Managing Ethernet Switches
==========================

2
docs/source/advanced/sysclone.rst Normal file
View File

@@ -0,0 +1,2 @@
Using System Clone to Deploy Diskful Node
=========================================

2
docs/source/advanced/vlan.rst Normal file
View File

@@ -0,0 +1,2 @@
VLAN Configuration
==================

2
docs/source/advanced/xcat_port.rst Normal file
View File

@@ -0,0 +1,2 @@
xCAT Port Usage
===============

2
docs/source/advanced/xcat_security.rst Normal file
View File

@@ -0,0 +1,2 @@
xCAT 2 Security
===============

2
docs/source/advanced/zone.rst Normal file
View File

@@ -0,0 +1,2 @@
Setting Up Management Zones
===========================

292
docs/source/conf.py Normal file
View File

@@ -0,0 +1,292 @@
# -*- coding: utf-8 -*-
#
# xCAT documentation build configuration file, created by
# sphinx-quickstart on Thu May 28 14:34:34 2015.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import sys
import os
import shlex
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.autodoc',
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'xCAT'
copyright = u'2015, IBM Corporation'
author = u'IBM Corporation'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '0.0.1'
# The full version, including alpha/beta/rc tags.
release = '0.0.1'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = []
# The reST default role (used for this markup: `text`) to use for all
# documents.
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# If true, keep warnings as "system message" paragraphs in the built documents.
#keep_warnings = False
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
import os
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
if on_rtd:
html_theme = 'default'
else:
# some of the popular themes: alabaster, sphinx_rtd_theme, classic, nature
html_theme = 'sphinx_rtd_theme'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#html_extra_path = []
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
#html_domain_indices = True
# If false, no index is generated.
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None
# Language to be used for generating the HTML full-text search index.
# Sphinx supports the following languages:
# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr'
#html_search_language = 'en'
# A dictionary with options for the search language support, empty by default.
# Now only 'ja' uses this config value
#html_search_options = {'type': 'default'}
# The name of a javascript file (relative to the configuration directory) that
# implements a search results scorer. If empty, the default will be used.
#html_search_scorer = 'scorer.js'
# Output file base name for HTML help builder.
htmlhelp_basename = 'xCAT3doc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#'preamble': '',
# Latex figure (float) alignment
#'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'xCAT3.tex', u'xCAT3 Documentation',
u'IBM Corporation', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False
# If true, show page references after internal links.
#latex_show_pagerefs = False
# If true, show URL addresses after external links.
#latex_show_urls = False
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_domain_indices = True
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'xcat3', u'xCAT3 Documentation',
[author], 1)
]
# If true, show URL addresses after external links.
#man_show_urls = False
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'xCAT3', u'xCAT3 Documentation',
author, 'xCAT3', 'One line description of project.',
'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
#texinfo_appendices = []
# If false, no module index is generated.
#texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'
# If true, do not generate a @detailmenu in the "Top" node's menu.
#texinfo_no_detailmenu = False

2
docs/source/developers/debug_xcat.rst Normal file
View File

@@ -0,0 +1,2 @@
Debug xCAT Problems
===================

2
docs/source/developers/developer_guide.rst Normal file
View File

@@ -0,0 +1,2 @@
Developer Guide
===============

14
docs/source/developers/git/index.rst Normal file
View File

@@ -0,0 +1,14 @@
Git
===
xCAT uses git for source code version control. There are many resources and documentation available to help you learn git. A great place to start would be: http://git-scm.com/doc
* https://training.github.com/kit/downloads/github-git-cheat-sheet.pdf
.. toctree::
:maxdepth: 2

14
docs/source/developers/index.rst Normal file
View File

@@ -0,0 +1,14 @@
Developers
==========
This page is for developers interested in working with xCAT.
.. toctree::
:maxdepth: 2
developer_guide.rst
programming_tips.rst
debug_xcat.rst
license/index.rst
git/index.rst

9
docs/source/developers/license/contributor_license_agreement.rst Normal file
View File

@@ -0,0 +1,9 @@
.. _xcat-contributor-license-label:
xCAT Contributor License Agreement
==================================
For **one** of the following agreements, print it, fill it out, sign it, scan it, and email it to: xcat-legal@lists.sourceforge.net.
* :ref:`xcat-individual-contributor-license-label`
* :ref:`xcat-corporate-contributor-license-label`

52
docs/source/developers/license/index.rst Normal file
View File

@@ -0,0 +1,52 @@
Contributor and Maintainer Agreements
=====================================
xCAT 2 is licensed under the `Eclipse Public License <http://www.opensource.org/licenses/eclipse-1.0.php>`_. All contributions to xCAT must be licensed to xCAT pursuant to the referenced :ref:`xcat-contributor-license-label`.
Contributor
-----------
We welcome new developers willing to contribute to the xCAT code to make it better. In order to do that, you need to:
* License your contribution(s) pursuant to the :ref:`xcat-contributor-license-label`.
* Decide if you want to sign the contributor license agreement as an individual or as a corporate. The **individual license agreement** allows the individual contributor to submit contributions to the xCAT community. The **corporate contributor license agreement** allows an entity (the "Corporation") to submit contributions to the xCAT Community.
* Print the :ref:`xcat-individual-contributor-license-label` or :ref:`xcat-corporate-contributor-license-label`, fill it out, sign it, scan it, then email it to: xcat-legal@lists.sourceforge.net.
* After submitting the signed license agreement, you can fork the xcat project, make changes, and submit pull requests so they can be integrated into the xCAT code stream.
* If you are an experienced xCAT user and plan to contribute to the xCAT code regularly, request to become a Maintainer with Git push access. See the section below for details.
Maintainer
----------
If you are an experienced xCAT user and plan to contribute to the xCAT code regularly, you can request to become an xCAT Maintainer (which includes git push access) by posting to the xCAT mailing list.
If you are approved to become an xCAT maintainer, you must print the agreement :download:`xCAT Maintainer License Agreement <xcat-project-maintainer-agreement.pdf>`, fill it out and sign it, scan it in, and email it to xcat-legal@lists.sourceforge.net .
The roles and responsibilities of the maintainers are:
* set the direction for the xCAT project, including architectural and design decisions
* commit code (new function or fixes) to the xCAT GitHub repository (either their own code, or on behalf of another contributor - see below)
* review requests for xCAT members to become maintainers (All such requests will be subject to a vote of current maintainers. Consensus of current maintainers is required for approval.)
* review and help resolve technical concerns or problems regarding the project
All decisions by the maintainers are made by consensus.
When a maintainer pushes code to the xCAT GitHub repository for another contributor (i.e. **not** your own code), they must:
* Require that each code contributor sign the :ref:`xcat-individual-contributor-license-label` or :ref:`xcat-corporate-contributor-license-label` and email it to xcat-legal@lists.sourceforge.net .
* Require that all code be contributed under the EPL.
* Create a log entry with intellectual property information about the contribution & contributor. Each log entry should contain the information below, and should be posted to xcat-legal@lists.sourceforge.net: ::
Maintainer Name: (the person who committed the code to the xCAT GitHub repository)
Maintainer Sourceforge Id:
Contributor Name: (the author of the code)
Contributor's Organization or Employer (if the contribution was made on the organization's/employer's behalf):
Contributor Sourceforge Id:
GitHub Id of This Code PUSH:
Date Code was Committed:
Purpose/Description of New/Changed Code:
Approximate Number of Lines of Code Added/Changed/Removed by This Commit:
Additional Authors of the Contributed Code:
License Used (if other than EPL, need approval from the xCAT Maintainers):
Code Reviewed By (usually the maintainer who commits it):

BIN
docs/source/developers/license/xcat-project-maintainer-agreement.pdf Normal file
View File

Binary file not shown.

100
docs/source/developers/license/xcat_corporate_contributor_license_agreement.rst Normal file
View File

@@ -0,0 +1,100 @@
.. _xcat-corporate-contributor-license-label:
The xCAT Community Software Grant and Corporate Contributor License Agreement ("Agreement")
-------------------------------------------------------------------------------------------
In order to clarify the intellectual property license granted with Contributions from any person or entity made for the benefit of the xCAT Community, a Contributor License Agreement (CLA) must be on file that has been signed by each Contributor, indicating agreement to the license terms below. This license is for your protection as a Contributor as well as the protection of the xCAT Community and its users; it does not change your rights to use your own Contributions for any other purpose.
This version of the Agreement allows an entity (the "Corporation") to submit Contributions to the xCAT Community, to authorize Contributions submitted by its designated employees to the xCAT Community, and to grant copyright and patent licenses thereto.
If you have not already done so, please print this form, complete it, sign it, and send a scanned copy via email to **xcat-legal@lists.sourceforge.net** . Please read this document carefully before signing and keep a copy for your records.
Corporation name: ___________________________________________________
Address 1: ___________________________________________________
Address 2: ___________________________________________________
Point of Contact: ___________________________________________________
E-Mail: _____________________________________________________________
Telephone: __________________________ Fax: __________________________
You accept and agree to the following terms and conditions for Your present and future Contributions submitted to the xCAT Community. Except for the license granted herein to the xCAT Community, You reserve all right, title, and interest in and to Your Contributions.
1\. Definitions.
"You" (or "Your") shall mean the copyright owner or legal entity authorized by the copyright owner that is making this Agreement. For legal entities, the entity making a Contribution and all other entities that control, are controlled by, or are under common control with that entity are considered to be a single Contributor. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
"Contribution" shall mean the code, documentation or other original works of authorship expressly identified in Schedule B, as well as any original work of authorship, including any modifications or additions to an existing work, that is intentionally submitted by You to the xCAT Community for inclusion in, or documentation of, any of the products owned or managed by members of the xCAT Community (the "Work"). For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to members of the xCAT Community, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the xCAT Community for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by You as "Not a Contribution."
“xCAT Community” shall mean International Business Machines Corporation and other users of xCAT. Accepted Contributions will be made available to the xCAT Community at large through sourceforge.net or other open source community.
2\. Grant of Copyright License. Subject to the terms and conditions of this Agreement, You hereby grant to the xCAT Community a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute Your Contributions and such derivative works.
3\. Grant of Patent License. Subject to the terms and conditions of this Agreement, You hereby grant to the xCAT Community a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by You that are necessarily infringed by Your Contribution(s) alone or by combination of Your Contribution(s) with the Work to which such Contribution(s) were submitted. If any entity institutes patent litigation against You or any other entity (including a cross-claim or counterclaim in a lawsuit) alleging that Your Contribution, or the Work to which You have contributed, constitutes direct or contributory patent infringement, then any patent licenses granted to that entity under this Agreement for that Contribution or Work shall terminate as of the date such litigation is filed.
4\. You represent that You are legally entitled to grant the above license. You represent further that each employee of the Corporation designated on Schedule A below (or in a subsequent written modification to that Schedule) is authorized to submit Contributions on behalf of the Corporation.
5\. You represent that each of Your Contributions is Your original creation (see section 7 for submissions on behalf of others).
6\. You are not expected to provide support for Your Contributions, except to the extent You desire to provide support. You may provide support for free, for a fee, or not at all. Unless required by applicable law or agreed to in writing, You provide Your Contributions on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE.
7\. Should You wish to submit work that is not Your original creation, You may submit it to the xCAT Community separately from any Contribution, identifying the complete details of its source and of any license or other restriction (including, but not limited to, related patents, trademarks, and license agreements) of which You are personally aware, and conspicuously marking the work as "Submitted on behalf of a third-party: [named here]".
8\. It is Your responsibility to notify the xCAT Community (xcat-legal@lists.sourceforge.net) when any change is required to the list of designated employees authorized to submit Contributions on behalf of the Corporation, or to the Corporation's Point of Contact with the xCAT Community.
9\. You agree that your signature, as received by e-mail, will constitute an “original” signature of this Agreement.
Please sign: __________________________________ Date: _______________
Title: __________________________________
Corporation: __________________________________
Schedule A
[Initial list of designated employees. NB: authorization is not tied to particular Contributions.]
Schedule B
[Identification of optional concurrent software grant. Would be left blank or omitted if there is no concurrent software grant.]

68
docs/source/developers/license/xcat_individual_contributor_license_agreement.rst Normal file
View File

@@ -0,0 +1,68 @@
.. _xcat-individual-contributor-license-label:
The xCAT Community Individual Contributor License Agreement ("Agreement")
=========================================================================
In order to clarify the intellectual property license granted with Contributions from any person or entity made for the benefit of the xCAT Community, a Contributor License Agreement ("CLA") must be on file that has been signed by each Contributor, indicating agreement to the license terms below. This license is for your protection as a Contributor as well as the protection of the xCAT Community and its users; it does not change your rights to use your own Contributions for any other purpose. If you have not already done so, please print this form, complete it, sign it, and send a scanned copy via email to **xcat-legal@lists.sourceforge.net**.
Full name: _______________________________ E-Mail: ______________________
Mailing Address: _________________________ Telephone: ______________________
__________________________________________ Facsimile: ______________________
__________________________________________ Country: ______________________
You accept and agree to the following terms and conditions for Your present and future Contributions submitted to the xCAT Community. Except for the license granted herein to the xCAT Community, You reserve all right, title, and interest in and to Your Contributions.
1\. Definitions.
"You" (or "Your") shall mean the copyright owner or legal entity authorized by the copyright owner that is making this Agreement. For legal entities, the entity making a Contribution and all other entities that control, are controlled by, or are under common control with that entity are considered to be a single Contributor. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
"Contribution" shall mean any original work of authorship, including any modifications or additions to an existing work, that is intentionally submitted by You to the xCAT Community for inclusion in, or documentation of, any of the products owned or managed by members of the xCAT Community (the "Work"). For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to members of the xCAT Community, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the xCAT Community for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by You as "Not a Contribution."
“xCAT Community” shall mean International Business Machines Corporation and other users of xCAT. Accepted Contributions will be made available to the xCAT Community at large through sourceforge.net or other open source community.
2\. Grant of Copyright License. Subject to the terms and conditions of this Agreement, You hereby grant to the xCAT Community a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute Your Contributions and such derivative works.
3\. Grant of Patent License. Subject to the terms and conditions of this Agreement, You hereby grant to the xCAT Community a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by You that are necessarily infringed by Your Contribution(s) alone or by combination of Your Contribution(s) with the Work to which such Contribution(s) was submitted. If any entity institutes patent litigation against You or any other entity (including a cross-claim or counterclaim in a lawsuit) alleging that your Contribution, or the Work to which You have contributed, constitutes direct or contributory patent infringement, then any patent licenses granted to that entity under this Agreement for that Contribution or Work shall terminate as of the date such litigation is filed.
4\. You represent that You are legally entitled to grant the above license. If Your employer(s) has rights to intellectual property that You create that includes Your Contributions, You represent
that You have received permission to make Contributions on behalf of that employer, that Your employer has waived such rights for Your Contributions to the xCAT Community, or that Your employer has executed a separate Corporate CLA with the xCAT Community.
5\. You represent that each of Your Contributions is Your original creation (see section 7 for submissions on behalf of others). You represent that Your Contribution submissions include complete details of any third-party license or other restriction (including, but not limited to, related patents and trademarks) of which You are personally aware and which are associated with any part of Your Contributions.
6\. You are not expected to provide support for Your Contributions, except to the extent You desire to provide support. You may provide support for free, for a fee, or not at all. Unless required by applicable law or agreed to in writing, You provide Your Contributions on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE.
7\. Should You wish to submit work that is not Your original creation, You may submit it to the xCAT Community separately from any Contribution, identifying the complete details of its source and of any license or other restriction (including, but not limited to, related patents, trademarks, and license agreements) of which You are personally aware, and conspicuously marking the work as
"Submitted on behalf of a third-party: [named here]".
8\. You agree to notify the xCAT Community (xcat-legal@lists.sourceforge.net) of any facts or circumstances of which You become aware that would make these representations inaccurate in any respect.
9\. You agree that your signature, as received by e-mail, will constitute an “original” signature of this Agreement.
Please sign: __________________________________ Date: ________________

68
docs/source/developers/license/xcat_maintainer_license_agreement.rst Normal file
View File

@@ -0,0 +1,68 @@
.. _xcat-maintainer-license-label:
The xCAT Community Individual Contributor License Agreement ("Agreement")
=========================================================================
In order to clarify the intellectual property license granted with Contributions from any person or entity made for the benefit of the xCAT Community, a Contributor License Agreement ("CLA") must be on file that has been signed by each Contributor, indicating agreement to the license terms below. This license is for your protection as a Contributor as well as the protection of the xCAT Community and its users; it does not change your rights to use your own Contributions for any other purpose. If you have not already done so, please print this form, complete it, sign it, and send a scanned copy via email to **xcat-legal@lists.sourceforge.net**.
Full name: _______________________________ E-Mail: ______________________
Mailing Address: _________________________ Telephone: ______________________
__________________________________________ Facsimile: ______________________
__________________________________________ Country: ______________________
You accept and agree to the following terms and conditions for Your present and future Contributions submitted to the xCAT Community. Except for the license granted herein to the xCAT Community, You reserve all right, title, and interest in and to Your Contributions.
1\. Definitions.
"You" (or "Your") shall mean the copyright owner or legal entity authorized by the copyright owner that is making this Agreement. For legal entities, the entity making a Contribution and all other entities that control, are controlled by, or are under common control with that entity are considered to be a single Contributor. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
"Contribution" shall mean any original work of authorship, including any modifications or additions to an existing work, that is intentionally submitted by You to the xCAT Community for inclusion in, or documentation of, any of the products owned or managed by members of the xCAT Community (the "Work"). For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to members of the xCAT Community, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the xCAT Community for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by You as "Not a Contribution."
“xCAT Community” shall mean International Business Machines Corporation and other users of xCAT. Accepted Contributions will be made available to the xCAT Community at large through sourceforge.net or other open source community.
2\. Grant of Copyright License. Subject to the terms and conditions of this Agreement, You hereby grant to the xCAT Community a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute Your Contributions and such derivative works.
3\. Grant of Patent License. Subject to the terms and conditions of this Agreement, You hereby grant to the xCAT Community a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by You that are necessarily infringed by Your Contribution(s) alone or by combination of Your Contribution(s) with the Work to which such Contribution(s) was submitted. If any entity institutes patent litigation against You or any other entity (including a cross-claim or counterclaim in a lawsuit) alleging that your Contribution, or the Work to which You have contributed, constitutes direct or contributory patent infringement, then any patent licenses granted to that entity under this Agreement for that Contribution or Work shall terminate as of the date such litigation is filed.
4\. You represent that You are legally entitled to grant the above license. If Your employer(s) has rights to intellectual property that You create that includes Your Contributions, You represent
that You have received permission to make Contributions on behalf of that employer, that Your employer has waived such rights for Your Contributions to the xCAT Community, or that Your employer has executed a separate Corporate CLA with the xCAT Community.
5\. You represent that each of Your Contributions is Your original creation (see section 7 for submissions on behalf of others). You represent that Your Contribution submissions include complete details of any third-party license or other restriction (including, but not limited to, related patents and trademarks) of which You are personally aware and which are associated with any part of Your Contributions.
6\. You are not expected to provide support for Your Contributions, except to the extent You desire to provide support. You may provide support for free, for a fee, or not at all. Unless required by applicable law or agreed to in writing, You provide Your Contributions on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE.
7\. Should You wish to submit work that is not Your original creation, You may submit it to the xCAT Community separately from any Contribution, identifying the complete details of its source and of any license or other restriction (including, but not limited to, related patents, trademarks, and license agreements) of which You are personally aware, and conspicuously marking the work as
"Submitted on behalf of a third-party: [named here]".
8\. You agree to notify the xCAT Community (xcat-legal@lists.sourceforge.net) of any facts or circumstances of which You become aware that would make these representations inaccurate in any respect.
9\. You agree that your signature, as received by e-mail, will constitute an “original” signature of this Agreement.
Please sign: __________________________________ Date: ________________

2
docs/source/developers/programming_tips.rst Normal file
View File

@@ -0,0 +1,2 @@
Programming Tips
================

4
docs/source/guides/admin-guides/basic_concepts/global_cfg/index.rst Normal file
View File

@@ -0,0 +1,4 @@
Global Configuration
====================
Configure the **master**, **domain** ...

10
docs/source/guides/admin-guides/basic_concepts/index.rst Normal file
View File

@@ -0,0 +1,10 @@
Basic Concepts
==============
.. toctree::
:maxdepth: 2
xcat_object/index.rst
xcat_db/index.rst
global_cfg/index.rst
network_planning/index.rst

8
docs/source/guides/admin-guides/basic_concepts/network_planning/index.rst Normal file
View File

@@ -0,0 +1,8 @@
Network Planning
================
.. toctree::
:maxdepth: 2
network_service/index.rst
network_cfg/index.rst

2
docs/source/guides/admin-guides/basic_concepts/network_planning/network_cfg/index.rst Normal file
View File

@@ -0,0 +1,2 @@
Network Configuration
=====================

4
docs/source/guides/admin-guides/basic_concepts/network_planning/network_service/index.rst Normal file
View File

@@ -0,0 +1,4 @@
Network Services
================
The following network services are used by xCAT...

20
docs/source/guides/admin-guides/basic_concepts/xcat_db/index.rst Normal file
View File

@@ -0,0 +1,20 @@
Database
========
xCAT stores all the persistent data used to manage clusters in a database.
As the administrator, you can use a set of table oriented commands to modify the data (**recommended**), or directly modify the table using the ``tabedit`` command.
For a more indepth overview see the manpage for xcatdb: ``man xcatdb``
Commands
--------
Object Definitions
------------------
Node Groups
-----------
Regular Expressions
-------------------

2
docs/source/guides/admin-guides/basic_concepts/xcat_object/group.rst Normal file
View File

@@ -0,0 +1,2 @@
``group``
=========

10
docs/source/guides/admin-guides/basic_concepts/xcat_object/index.rst Normal file
View File

@@ -0,0 +1,10 @@
Objects
=======
.. toctree::
:maxdepth: 2
node.rst
osimage.rst
group.rst
nodegroup.rst

5
docs/source/guides/admin-guides/basic_concepts/xcat_object/node.rst Normal file
View File

@@ -0,0 +1,5 @@
``node``
========
Node Range
----------

2
docs/source/guides/admin-guides/basic_concepts/xcat_object/nodegroup.rst Normal file
View File

@@ -0,0 +1,2 @@
``nodegroup``
=============

2
docs/source/guides/admin-guides/basic_concepts/xcat_object/osimage.rst Normal file
View File

@@ -0,0 +1,2 @@
``osimage``
===========

10
docs/source/guides/admin-guides/index.rst Normal file
View File

@@ -0,0 +1,10 @@
Admin Guide
===========
.. toctree::
:maxdepth: 2
basic_concepts/index.rst
manage_clusters/index.rst
references/index.rst
large_clusters/index.rst

34
docs/source/guides/admin-guides/large_clusters/databases/index.rst Normal file
View File

@@ -0,0 +1,34 @@
Configure a Database
====================
xCAT uses the SQLite database (https://www.sqlite.org/) as the default database and it is initialized during xCAT installation of the Management Node. If using Service Nodes, SQLite **cannot** be used because Service Nodes require remote access to the xCAT database. One of the following databases should be used:
* :ref:`mysql_reference_label`
* :ref:`postgresql_reference_label`
.. _mysql_reference_label:
MySQL/MariaDB
-------------
.. toctree::
:maxdepth: 2
mysql_install.rst
mysql_configure.rst
mysql_using.rst
mysql_remove.rst
.. _postgresql_reference_label:
PostgreSQL
----------
.. toctree::
:maxdepth: 2
postgres_install.rst
postgres_configure.rst
postgres_using.rst
postgres_remove.rst

24
docs/source/guides/admin-guides/large_clusters/databases/mysql_configure.rst Normal file
View File

@@ -0,0 +1,24 @@
Configure MySQL/MariaDB
=======================
Migrate xCAT to use MySQL/MariaDB
---------------------------------
The following utility is provided to migrate an existing xCAT database from SQLite to MySQL/MariaDB. ::
mysqlsetup -i
If you need to update the database at a later time to give access to your service nodes, you can use the ``mysqlsetup -u -f`` command. A file needs to be provided with all the hostnames and/or IP addresses of the servers that need to access the database on the Management node. Wildcards can be used. ::
TODO: Show an example here of file1
mysqlsetup -u -f /path/to/file1
**While not recommended**, if you wish to manually migrate your xCAT database, see the following documentation:
`Manually set up MySQL <https://sourceforge.net/p/xcat/wiki/Setting_Up_MySQL_as_the_xCAT_DB/#configure-mysql-manually>`_
Granting/Revoking access to the database for Service Node Clients
-----------------------------------------------------------------
https://sourceforge.net/p/xcat/wiki/Setting_Up_MySQL_as_the_xCAT_DB/#granting-or-revoking-access-to-the-mysql-database-to-service-node-clients

85
docs/source/guides/admin-guides/large_clusters/databases/mysql_install.rst Normal file
View File

@@ -0,0 +1,85 @@
Install MySQL/MariaDB
=====================
The MySQL database is supported by xCAT since xCAT 2.1. MariaDB is a fork of the MySQL project which was released around 2009 and is a drop-in replacement for MySQL. MariaDB support within xCAT started in version 2.8.5 and is currently fully supported moving forward.
+------------+------------+------------+
| Database | MySQL | MariaDB |
+============+============+============+
| xCAT 2.1+ | Yes | No |
+------------+------------+------------+
| xCAT 2.8.5 | Yes | RHEL 7 |
+------------+------------+------------+
| xCAT 2.9 | Yes | SLES 12 |
+------------+------------+------------+
| xCAT 2.10+ | Yes | Yes |
+------------+------------+------------+
MySQL/MariaDB packages are shipped as part of most Linux Distributions.
Redhat Enterprise Linux
-----------------------
* MySQL - Using ``yum``, ensure that the following packages are installed on the management node: ::
perl-DBD-MySQL*
mysql-server-5.*
mysql-5.*
mysql-devel-5.*
mysql-bench-5.*
mysql-connector-odbc-*
* MariaDB - Using ``yum``, ensure that the following packages are installed on the management node: ::
mariadb-devel-5.*
mariadb-libs-5.*
mariadb-server-5.*
mariadb-bench-5.*
mariadb-5.*
perl-DBD-MySQL*
mysql-connector-odbc-*
unixODBC*
Suse Linux Enterprise Server
----------------------------
* MySQL - Using ``zypper``, ensure that the following packages are installed on the management node: ::
mysql-client-5*
libmysqlclient_r15*
libqt4-sql-mysql-4*
libmysqlclient15-5*
perl-DBD-mysql-4*
mysql-5*
* MariaDB - Using ``zypper``, ensure that the following packages are installed on the management node: ::
mariadb-client-10.*
mariadb-10.*
mariadb-errormessages-10.*
libqt4-sql-mysql-*
libmysqlclient18-*
perl-DBD-mysql-*
Debian/Ubuntu
-------------
* MySQL - Using ``apt-get``, ensure that the following packages are installed on the management node: ::
mysql-server
mysql-common
libdbd-mysql-perl
libmysqlclient18
mysql-client-5*
mysql-client-core-5*
mysql-server-5*
mysql-server-core-5*
* MariaDB - Using ``apt-get``, ensure that the following packages are installed on the management node: ::
libmariadbclient18
mariadb-client
mariadb-common
mariadb-server

2
docs/source/guides/admin-guides/large_clusters/databases/mysql_remove.rst Normal file
View File

@@ -0,0 +1,2 @@
Removing ``xcatdb`` from MySQL/MariaDB
======================================

2
docs/source/guides/admin-guides/large_clusters/databases/mysql_using.rst Normal file
View File

@@ -0,0 +1,2 @@
Using MySQL/MariaDB
===================

36
docs/source/guides/admin-guides/large_clusters/databases/postgres_configure.rst Normal file
View File

@@ -0,0 +1,36 @@
Configure PostgreSQL
====================
Migrate xCAT to use PostgreSQL
------------------------------
A utility is provided to migrate an existing xCAT database from SQLite to PostgreSQL. ::
pgsqlsetup -i -V
**While not recommended**, if you wish to manually migrate your xCAT database, see the following documentation:
`Manually set up PostgreSQL <https://sourceforge.net/p/xcat/wiki/Setting_Up_PostgreSQL_as_the_xCAT_DB/#manually-setup-postgresql>`_
Setting up the Service Nodes
----------------------------
For service nodes, add the IP address of each service nodes to the postgres configuration file: ``/var/lib/pgsql/data/pg_hba.conf``
If you had the following two service nodes: ::
sn10, ip: 192.168.1.10 with netmask 255.255.255.0
sn11, ip: 192.168.1.11 with netmask 255.255.255.0
You would add the following to ``/var/lib/pgsql/data/pg_hba.conf`` ::
host all all 192.168.1.10/24 md5
host all all 192.168.1.11/24 md5
Restart PostgreSQL after editing the file: ::
service postgresql restart
For more information about changing the ``pg_hab.conf`` file and ``postgresql.conf`` files, see the following documentation:
`Setup the PostgreSQL Configuraion Files <https://sourceforge.net/p/xcat/wiki/Setting_Up_PostgreSQL_as_the_xCAT_DB/#setup-the-postgresql-configuration-files>`_

34
docs/source/guides/admin-guides/large_clusters/databases/postgres_install.rst Normal file
View File

@@ -0,0 +1,34 @@
Install PostgreSQL
==================
PostgreSQL packages are shipped as part of most Linux Distributions.
Redhat Enterprise Linux
-----------------------
Using yum, install the following rpms: ::
yum install postgresql-libs-* postgresql-server-* postgresql-*
yum install perl-DBD-Pg*
Suse Linux Enterprise Server
----------------------------
**Note:** On SLES, ``perl-DBD`` packages are provided on the SDK iso images.
Using zyppr, install the following rpms: ::
zyppr install postgresql-libs-* postgresql-server-* postgresql-*
zyppr install perl-DBD-Pg*
Debian/Ubuntu
-------------
Using apt, install the following packages: ::
apt install postgresql libdbd-pg-perl

44
docs/source/guides/admin-guides/large_clusters/databases/postgres_remove.rst Normal file
View File

@@ -0,0 +1,44 @@
Removing ``xcatdb`` from PostgreSQL
===================================
To remove ``xcatdb`` completely from the PostgreSQL database:
#. Run a backup of the database to save any information that is needed: ::
mkdir -p ~/xcat-dbback
dumpxCATdb -p ~/xcat-dbback
#. Stop the ``xcatd`` daemon on the management node.
**Note:** If you are using *xCAT Hierarchy (service nodes)* and removing ``xcatdb`` from postgres, hierarchy will no longer work. You will need to configure another database which supports remote database access to continue using the hierarchy feature. ::
service xcatd stop
#. Remove the ``xatdb`` from PostgreSQL: ::
su - postgres
drop the xcatdb: ::
dropdb xcatdb
remove the xcatadm database owner : ::
dropuser xcatadm
clean up the postgresql files (necessary if you want to re-create the database): ::
cd /var/lib/pgsql/data
rm -rf *
#. Move, or remove, the ``/etc/xcat/cfglog`` file as it points xCAT to PostgreSQL. (without this file, xCAT defaults to SQLite): ::
mv /etc/xcat/cfgloc /etc/xcat/cfglog.postgres
#. Restore the PostgreSQL database into SQLite: ::
XCATBYPASS=1 restorexCATdb -p ~/xcat-dbback
#. Restart ``xcatd``: ::
service xcatd start

53
docs/source/guides/admin-guides/large_clusters/databases/postgres_tips.rst Normal file
View File

@@ -0,0 +1,53 @@
PostgreSQL tips
===============
Using PostgreSQL
----------------
* Connect to the database
Use the psql command line utility to connect to the PostgreSQL database: ::
su - postgres
psql -h <hostname> -U xcatadm -d xcatdb
Useful Commands
---------------
* Show create statement for a table, for example prescripts table. ::
/usr/bin/pg_dump xcatdb -U xcatadm -t prescripts
* Clean up the xcatdb completely from PostgreSQL: ::
su - postgres
# drop the xcatdb
dropdb xcatdb
# remove the xcatadm database owner
dropuser xcatadm
# clean up the postgresql files (necessary if you want to re-create the database)
cd /var/lib/pgsql/data
rm -rf *
* List databases: ::
su - postgres
psql -l
* Access the database: ::
su - postgres
psql xcatdb
SELECT * FROM "pg_user"; Select all users
SELECT * FROM "site"; Select the site table
SELECT MAX(recid) from "auditlog";
SELECT MIN(recid) from "auditlog";
drop table zvm; Removes a table
\dt Select all tables
\? help
\q exit

39
docs/source/guides/admin-guides/large_clusters/databases/postgres_using.rst Normal file
View File

@@ -0,0 +1,39 @@
Using PostgreSQL
================
Refer to `<http://www.postgresql.org/>`_ for the latest documentation.
Using ``psql``, connect to the xcat database: ::
su - postgres
psql -h <hostname> -U xcatadm -d xcatdb (default pw: cluster)
list the xCAT tables: ::
xcatdb=> \dt
show the entries in the nodelist table: ::
xcatdb=> select * from nodelist;
quit postgres: ::
xcatdb=> \q
Useful Commands
---------------
Show the SQL create statement for a table: ::
/usr/bin/pg_dump_xcatdb -U xcatadm -t <table_name>
# example, for prescripts table:
/usr/bin/pg_dump xcatdb -U xcatadm -t prescripts
List all databases in postgres: ::
su - postgres
psql -l

22
docs/source/guides/admin-guides/large_clusters/index.rst Normal file
View File

@@ -0,0 +1,22 @@
Large Cluster Support
=====================
xCAT supports management of very large sized cluster through the use of **xCAT Hierarchy** or **xCAT Service Nodes**.
When dealing with large clusters, to balance the load, it is recommended to have more than one node (Management Node, "MN") handling the installation and management of the compute nodes. These additional *helper* nodes are referred to as **xCAT Service Nodes** ("SN"). The Management Node can delegate all management operational needs to the Service Node responsible for a set of compute node.
The following configurations are supported:
* Each service node installs/manages a specific set of compute nodes
* Having a pool of service nodes, any of which can respond to an installation request from a compute node (*Requires service nodes to be aligned with networks broadcast domains, compute node chooses service nodes based on who responds to DHCP request first.*)
* A hybrid of the above, where each specific set of compute nodes have 2 or more service nodes in a pool
The following documentation assumes an xCAT cluster has already been configured and covers the additional steps needed to suport xCAT Hierarchy via Service Nodes.
.. toctree::
:maxdepth: 2
service_nodes/service_nodes101.rst
databases/index.rst
service_nodes/define_service_nodes.rst
service_nodes/provision_service_nodes.rst
tips.rst

81
docs/source/guides/admin-guides/large_clusters/service_nodes/define_service_nodes.rst Normal file
View File

@@ -0,0 +1,81 @@
Define Service Nodes
====================
This next part shows how to configure a xCAT Hierarchy and provision xCAT service nodes from an existing xCAT cluster.
*The document assumes that the compute nodes part of your cluster have already been defined into the xCAT database and you have successfully provisioned the compute nodes using xCAT*
The following table illustrates the cluster being used in this example:
+----------------------+----------------------+
| Operating System | rhels7.1 |
+----------------------+----------------------+
| Architecture | ppc64le |
+----------------------+----------------------+
| xCAT Management Node | xcat01 |
+----------------------+----------------------+
| Compute Nodes | r1n01 |
| (group=rack1) | r1n02 |
| | r1n03 |
| | ... |
| | r1n10 |
+----------------------+----------------------+
| Compute Nodes | r2n01 |
| (group=rack1) | r2n02 |
| | r2n03 |
| | ... |
| | r2n10 |
+----------------------+----------------------+
#. Select the compute nodes that will become service nodes
The first node in each rack, ``r1n01 and r2n01``, is selected to become the xCAT service nodes and manage the compute nodes in that rack
#. Change the attributes for the compute node to make them part of the **service** group: ::
chdef -t node -o r1n01,r2n01 groups=service,all
#. When ``copycds`` was run against the ISO image, several osimages are created into the ``osimage`` table. The ones containing "service" are provided to help easily provision xCAT service nodes. ::
# lsdef -t osimage | grep rhels7.1
rhels7.1-ppc64le-install-compute (osimage)
rhels7.1-ppc64le-install-service (osimage) <======
rhels7.1-ppc64le-netboot-compute (osimage)
#. Add the service nodes to the ``servicenode`` table: ::
chdef -t group -o service setupnfs=1 setupdhcp=1 setuptftp=1 setupnameserver=1 setupconserver=1
**Tips/Hint**
* Even if you do not want xCAT to configure any services, you must define the service nodes in the ``servicenode`` table with at least one attribute, set to 0, otherwise xCAT will not recognize the node as a service node**
* See the ``setup*`` attributes in the node definition man page for the list of available services: ``man node``
* For clusters with subnetted management networks, you might want to set ``setupupforward=1``
#. Add additional postscripts for Service Nodes (optional)
By default, xCAT will execute the ``servicenode`` postscript when installed or diskless booted. This postscript will set up the necessary credentials and installs the xCAT software on the Service Nodes. If you have additional postscripts that you want to execute on the service nodes, copy to ``/install/postscripts`` and run the following: ::
chdef -t group -o service -p postscripts=<mypostscript>
#. Assigning Compute Nodes to their Service Nodes
The node attributes ``servicenode`` and ``xcatmaster``, define which Service node will serve the particular compute node.
* ``servicenode`` - defines which Service Node the **Management Node** should send commands to (e.g ``xdsh``) and should be set to the hostname or IP address of the service node that the management node can conttact it by.
* ``xcatmaster`` - defines which Service Node the **Compute Node** should boot from and should be set to the hostname or IP address of the service node that the compute node can contact it by.
You must set both ``servicenode`` and ``xcatmaster`` regardless of whether or not you are using service node pools, for most scenarios, the value will be identical. ::
chdef -t group -o rack1 servicenode=r1n01 xcatmaster=r1n01
chdef -t group -o rack2 servicenode=r2n01 xcatmaster=r2n01
#. Set the conserver and monserver attributes
Set which service node should run the conserver (console) and monserver (monitoring) daemon for the nodes in the group. The most typical setup is to have the service node also ad as it's conserver and monserver. ::
chdef -t group -o rack1 conserver=r1n01 monserver=r1n01
chdef -t group -o rack2 conserver=r2n01 monserver=r2n01

11
docs/source/guides/admin-guides/large_clusters/service_nodes/provision_service_nodes.rst Normal file
View File

@@ -0,0 +1,11 @@
Provision Service Nodes
=======================
Diskful
-------
Diskless
--------
Verfication
-----------

9
docs/source/guides/admin-guides/large_clusters/service_nodes/service_nodes101.rst Normal file
View File

@@ -0,0 +1,9 @@
Service Nodes 101
=================
Service Nodes are similar to the xCAT Management Node in that each service Nodes runs an instance of the xCAT daemon: ``xcatd``. ``xcatd``'s communicate with each other using the same XML/SSL protocol that the xCAT client uses to communicate with ``xcatd`` on the Management Node.
The Service Nodes need to communicate with the xCAT database running on the Management Node. This is done using the remote client capabilities of the database. This is why the default SQLite database cannot be used.
The xCAT Service Nodes are installed with a special xCAT package ``xCATsn`` which tells ``xcatd`` running on the node to behave as a Service Node and not the Management Node.

5
docs/source/guides/admin-guides/large_clusters/tips.rst Normal file
View File

@@ -0,0 +1,5 @@
Tips/Tuning/Suggestions
=======================
TODO: Content from: https://sourceforge.net/p/xcat/wiki/Hints_and_Tips_for_Large_Scale_Clusters/

5
docs/source/guides/admin-guides/manage_clusters/common/deployment/additional_pkg.rst Normal file
View File

@@ -0,0 +1,5 @@
Install Additional OS Packages
==============================
Install Additional Other Packages
=================================

2
docs/source/guides/admin-guides/manage_clusters/common/deployment/cfg_partition.rst Normal file
View File

@@ -0,0 +1,2 @@
Configure Disk Partition
========================

2
docs/source/guides/admin-guides/manage_clusters/common/deployment/cfg_second_adapter.rst Normal file
View File

@@ -0,0 +1,2 @@
Configure Secondary Network Adapter
===================================

4
docs/source/guides/admin-guides/manage_clusters/common/deployment/create_img.rst Normal file
View File

@@ -0,0 +1,4 @@
Select or Create an osimage Definition
======================================
Run copycds to create image

10
docs/source/guides/admin-guides/manage_clusters/common/deployment/deploy_os.rst Normal file
View File

@@ -0,0 +1,10 @@
Initialize the Compute for Deployment
=====================================
nodeset
Start the OS Deployment
=======================
rsetboot <node> net
rpower <node> on

2
docs/source/guides/admin-guides/manage_clusters/common/deployment/driver_update_disk.rst Normal file
View File

@@ -0,0 +1,2 @@
Using Driver Update Disk
========================

2
docs/source/guides/admin-guides/manage_clusters/common/deployment/enable_kdump.rst Normal file
View File

@@ -0,0 +1,2 @@
Enable Kdump Over Ethernet
==========================

8
docs/source/guides/admin-guides/manage_clusters/common/deployment/generate_img.rst Normal file
View File

@@ -0,0 +1,8 @@
Generate Diskless Image
=======================
Pack Diskless Image
===================
Export and Import Image
=======================

5
docs/source/guides/admin-guides/manage_clusters/common/deployment/pre_post_script.rst Normal file
View File

@@ -0,0 +1,5 @@
Using Prescript
===============
Using Postscript
================

2
docs/source/guides/admin-guides/manage_clusters/common/deployment/raid_cfg.rst Normal file
View File

@@ -0,0 +1,2 @@
Configure RAID before Deploy OS
===============================

2
docs/source/guides/admin-guides/manage_clusters/common/deployment/syncfile.rst Normal file
View File

@@ -0,0 +1,2 @@
Sync Files to Compute Node
==========================

2
docs/source/guides/admin-guides/manage_clusters/common/discover/manually_define.rst Normal file
View File

@@ -0,0 +1,2 @@
Manually Define Nodes
=====================

2
docs/source/guides/admin-guides/manage_clusters/common/discover/manually_discovery.rst Normal file
View File

@@ -0,0 +1,2 @@
Manually Discover Nodes
=======================

2
docs/source/guides/admin-guides/manage_clusters/common/discover/mtms_discovery.rst Normal file
View File

@@ -0,0 +1,2 @@
MTMS-based Discovery
====================

2
docs/source/guides/admin-guides/manage_clusters/common/discover/seq_discovery.rst Normal file
View File

@@ -0,0 +1,2 @@
Sequential-based Discovery
==========================

2
docs/source/guides/admin-guides/manage_clusters/common/discover/switch_discovery.rst Normal file
View File

@@ -0,0 +1,2 @@
Switch-based Discovery
======================

8
docs/source/guides/admin-guides/manage_clusters/common/kvm/manage_vm.rst Normal file
View File

@@ -0,0 +1,8 @@
Manage Virtual Machine
======================
Create Virtual Machine
----------------------
Change Virtual Machine
----------------------

2
docs/source/guides/admin-guides/manage_clusters/common/management.rst Normal file
View File

@@ -0,0 +1,2 @@
Hardware Management
===================

2
docs/source/guides/admin-guides/manage_clusters/common/management/rbeacon.rst Normal file
View File

@@ -0,0 +1,2 @@
``rbeacon``
===========

2
docs/source/guides/admin-guides/manage_clusters/common/management/rcons.rst Normal file
View File

@@ -0,0 +1,2 @@
``rcons``
=========

2
docs/source/guides/admin-guides/manage_clusters/common/management/renergy.rst Normal file
View File

@@ -0,0 +1,2 @@
``renergy``
===========

2
docs/source/guides/admin-guides/manage_clusters/common/management/reventlog.rst Normal file
View File

@@ -0,0 +1,2 @@
``reventlog``
=============

2
docs/source/guides/admin-guides/manage_clusters/common/management/rflash.rst Normal file
View File

@@ -0,0 +1,2 @@
``rflash``
==========

2
docs/source/guides/admin-guides/manage_clusters/common/management/rinv.rst Normal file
View File

@@ -0,0 +1,2 @@
``rinv``
========

13
docs/source/guides/admin-guides/manage_clusters/common/management/rpower.rst Normal file
View File

@@ -0,0 +1,13 @@
``rpower``
==========
rpower1
-------
Here is some common rpower information!
rpower2
-------
some more...

2
docs/source/guides/admin-guides/manage_clusters/common/management/rspconfig.rst Normal file
View File

@@ -0,0 +1,2 @@
``rspconfig``
=============

2
docs/source/guides/admin-guides/manage_clusters/common/management/rvitals.rst Normal file
View File

@@ -0,0 +1,2 @@
``rvitals``
===========

2
docs/source/guides/admin-guides/manage_clusters/common/parallel_cmd.rst Normal file
View File

@@ -0,0 +1,2 @@
Using Parallel Command
======================

2
docs/source/guides/admin-guides/manage_clusters/common/updatenode.rst Normal file
View File

@@ -0,0 +1,2 @@
Update Compute Node
===================

8
docs/source/guides/admin-guides/manage_clusters/index.rst Normal file
View File

@@ -0,0 +1,8 @@
Manage Clusters
===============
.. toctree::
:maxdepth: 2
ppc64le/index.rst
x86_64/index.rst

12
docs/source/guides/admin-guides/manage_clusters/ppc64le/discovery/index.rst Normal file
View File

@@ -0,0 +1,12 @@
Hardware Discoveriy & Define Node
=================================
.. toctree::
:maxdepth: 2
manually_define.rst
mtms_discovery.rst
switch_discovery.rst
seq_discovery.rst
manually_discovery.rst

1
docs/source/guides/admin-guides/manage_clusters/ppc64le/discovery/manually_define.rst Normal file
View File

@@ -0,0 +1 @@
.. include:: ../../common/discover/manually_define.rst

1
docs/source/guides/admin-guides/manage_clusters/ppc64le/discovery/manually_discovery.rst Normal file
View File

@@ -0,0 +1 @@
.. include:: ../../common/discover/manually_discovery.rst

Some files were not shown because too many files have changed in this diff Show More