Merge pull request #245 from whowutwut/advance

Reorganize the Advanced section and topics in the documentation

docs/Makefile

@@ -49,7 +49,7 @@ help:
 	@echo "  coverage   to run coverage check of the documentation (if enabled)"
 
 clean:
-	rm -rf $(BUILDDIR)/*
+	rm -rf $(BUILDDIR)
 
 html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html

docs/source/advanced/change_mn_ip.rst

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

docs/source/advanced/change_node_ip.rst

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

docs/source/advanced/cluster_maintenance/compute_node/changing_hostname_ip.rst

@@ -1,2 +1,2 @@
-Configuring IPv6 in xCAT Cluster
+Changing the hostname/IP address
 ================================

docs/source/advanced/cluster_maintenance/compute_node/index.rst

@@ -0,0 +1,7 @@
+Compute Node
+============
+
+.. toctree::
+   :maxdepth: 2
+
+   changing_hostname_ip.rst 

docs/source/advanced/cluster_maintenance/index.rst

@@ -0,0 +1,9 @@
+Cluster Maintenance
+===================
+
+.. toctree::
+   :maxdepth: 2
+
+   compute_node/index.rst 
+   mgmt_node/index.rst
+   sw_fw_inventory.rst

docs/source/advanced/cluster_maintenance/mgmt_node/changing_hostname_ip.rst

@@ -0,0 +1,4 @@
+Changing the hostname/IP address
+================================
+
+There may be times when it is required to change the hostname or IP address of the xCAT management nodes.  This document helps to outline the steps required to ensure successfully changing this attribute on the management node. 

docs/source/advanced/cluster_maintenance/mgmt_node/index.rst

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

docs/source/advanced/gpu/index.rst

@@ -0,0 +1,7 @@
+GPUs
+====
+
+.. toctree::
+   :maxdepth: 2
+
+   cuda.rst 

docs/source/advanced/hamn/high_available_management_node.rst

@@ -1,22 +1,17 @@
-========
 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: 
 
@@ -35,9 +30,8 @@ Warning: Running database through network file system has a lot of potential pro
 
 **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
-*************************************
+Manual 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: 
 
@@ -55,7 +49,6 @@ The configuration for the high availability applications is usually complex, it
 
 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
 =====================
 

docs/source/advanced/hamn/index.rst

@@ -1,5 +1,7 @@
-Highly Available Management Node
-================================
+High Avaiability
+================
+
+The following pages describes ways to configure the xCAT Management Node for High Availbility. 
 
 .. toctree::
    :maxdepth: 2

docs/source/advanced/hierarchy/index.rst

@@ -0,0 +1,7 @@
+Hierarchical Clusters
+=====================
+
+.. toctree::
+   :maxdepth: 2
+
+   introduction.rst

docs/source/advanced/hierarchy/introduction.rst

@@ -0,0 +1,10 @@
+Introduction
+============
+
+In supporting large clusters, it is desirable to have more than a single management node handling the installation and management of compute nodes.  
+
+In xCAT, these additional nodes are referred to as *Service Nodes (SN)*.  The management node can delegate all management operations for a compute node to the Service node that is managing them.  You can have one of more service nodes configured to install and manage a group of compute nodes. 
+
+
+Service Nodes
+-------------

docs/source/advanced/ib.rst

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

docs/source/advanced/index.rst

@@ -4,24 +4,22 @@ Advanced Topics
 .. toctree::
    :maxdepth: 2
 
-   restapi/index.rst
-   mixed_cluster/index.rst   
-   hierarchy_cluster.rst
+   confluent/index.rst
+   cluster_maintenance/index.rst
+   docker/index.rst
+   gpu/index.rst
    hamn/index.rst
+   hierarchy/index.rst
+   mixed_cluster/index.rst
+   networks/index.rst
    change_mn_ip.rst
    change_node_ip.rst
-   xcat_security.rst
+   ports/xcat_ports.rst
+   raid/index.rst
+   security/index.rst
+   softlayer/index.rst
    kit/index.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
-   firmware_inventory.rst
-   configraid.rst
-   cuda.rst
+   switches/index.rst
+   sysclone/index.rst
+   webservices/index.rst
+   zones/index.rst

docs/source/advanced/kit/hpckit.rst

@@ -2,12 +2,12 @@ IBM HPC Product Software Kits
 -----------------------------
 
 Obtaining the Kits
-```````````````````
+``````````````````
 
-Complete kits for some product software is shipped on the product distribution media. For other software, only partial kits may be available. The partial product kits are available from the FixCentral download site.  For the IBM XLF and XLC Compilers,  xCAT ships Ubuntu partial Kits on Sourceforge. the current redhat7.2 partial Kits, it ships on GitHub: http://xcat.org/files_new/kits/hpckits/2.11/rhels7.2/ppc64le/
+Complete kits for some product software is shipped on the product distribution media. For other software, only partial kits may be available. The partial product kits are available from the FixCentral download site.  For the IBM XLF and XLC Compilers,  xCAT ships Ubuntu partial Kits on Sourceforge. the current redhat7.2 partial Kits, it ships on xcat.org: http://xcat.org/files/kits/hpckits/2.11/rhels7.2/ppc64le/
 
 General Instructions for all HPC Kits
-``````````````````````````````````````
+`````````````````````````````````````
 
 This is a quick overview of the commands will use to add kits to the xCAT cluster and use them in the Linux OS images.
 
@@ -185,7 +185,7 @@ For XLC 13.1.1.0 and XLF 15.1.1.0, xCAT ships partial software kits for Ubuntu o
 
 For XLC 13.1.2.0 and XLF 15.1.2.0, xCAT ships partial software kits for rhels7.2 on github
 
-  http://xcat.org/files_new/kits/hpckits/2.11/rhels7.2/ppc64le/
+  http://xcat.org/files/kits/hpckits/2.11/rhels7.2/ppc64le/
   
 For older Linux releases on System P, and for AIX, use the xCAT HPC Integration Support
 

docs/source/advanced/networks/index.rst

@@ -0,0 +1,9 @@
+Networks
+========
+
+.. toctree::
+   :maxdepth: 2
+
+   infiniband/index.rst
+   ipv6/index.rst
+   vlan/index.rst

docs/source/advanced/networks/infiniband/driver_and_installation.rst

@@ -0,0 +1,2 @@
+IB Driver Preparation and Installation
+======================================

docs/source/advanced/networks/infiniband/firmware_updates.rst

@@ -0,0 +1,2 @@
+Firmware Updates
+================

docs/source/advanced/networks/infiniband/index.rst

@@ -0,0 +1,11 @@
+Infiniband (Mellanox)
+=====================
+
+.. toctree::
+   :maxdepth: 2
+
+   driver_and_installation.rst
+   network_configuration.rst
+   switch_configuration.rst
+   ufm_configuration.rst
+   firmware_updates.rst

docs/source/advanced/networks/infiniband/network_configuration.rst

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

docs/source/advanced/networks/infiniband/switch_configuration.rst

@@ -0,0 +1,2 @@
+IB Switch Configuration
+=======================

docs/source/advanced/networks/infiniband/ufm_configuration.rst

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

docs/source/advanced/networks/ipv6/index.rst

@@ -0,0 +1,7 @@
+IPv6
+====
+
+.. toctree::
+   :maxdepth: 2
+
+   ipv6_support.rst

docs/source/advanced/networks/ipv6/ipv6_support.rst

@@ -0,0 +1,2 @@
+Configuring IPv6
+================

docs/source/advanced/networks/vlan/index.rst

@@ -0,0 +1,7 @@
+VLANs
+=====
+
+.. toctree::
+   :maxdepth: 2
+
+   vlan.rst

docs/source/advanced/ports/xcat_ports.rst

@@ -0,0 +1,4 @@
+Port Usage
+==========
+
+TODO: http://sourceforge.net/p/xcat/wiki/XCAT_Port_Usage/?version=4

docs/source/advanced/raid/hardware_raid.rst

@@ -1,5 +1,5 @@
-Configuring hardware RAID in xCAT cluster
-=========================================
+Hardware RAID
+=============
 
 Overview
 --------

docs/source/advanced/raid/index.rst

@@ -0,0 +1,7 @@
+RAID
+====
+
+.. toctree::
+   :maxdepth: 2
+
+   hardware_raid.rst

docs/source/advanced/restapi/restapi.rst

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

docs/source/advanced/security/index.rst

@@ -0,0 +1,8 @@
+Security
+========
+
+TODO, organize/rewrite from http://sourceforge.net/p/xcat/wiki/XCAT_2_Security/
+
+.. toctree::
+   :maxdepth: 2
+

docs/source/advanced/softlayer/index.rst

@@ -0,0 +1,7 @@
+SoftLayer
+=========
+
+.. toctree::
+   :maxdepth: 2
+
+   softlayer.rst

docs/source/advanced/switch_mgmt.rst

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

docs/source/advanced/switches/ethernet_switches.rst

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

docs/source/advanced/switches/index.rst

@@ -0,0 +1,7 @@
+Switch Management
+=================
+
+.. toctree::
+   :maxdepth: 2
+
+   ethernet_switches.rst 

docs/source/advanced/sysclone/index.rst

@@ -0,0 +1,7 @@
+System Clone (sysclone)
+=======================
+
+.. toctree::
+   :maxdepth: 2
+
+   sysclone.rst

docs/source/advanced/webservices/index.rst

@@ -1,5 +1,5 @@
-xCAT Web Services REST API
-==========================
+Web Services
+============
 
 .. toctree::
    :maxdepth: 2

docs/source/advanced/webservices/restapi.rst

@@ -0,0 +1,2 @@
+RESTful APIs
+============

docs/source/advanced/webservices/set_up_ws.rst

@@ -1,7 +1,7 @@
-Set Up Web Service for REST API
-===============================
+Configure Web Services
+======================
 
-The following steps describe how to setup the WEB Service to use the REST API
+The following steps describe how to setup the Web Service to use the REST API
 
 Enable the HTTPS service for REST API
 -------------------------------------

docs/source/advanced/xcat_security.rst

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

docs/source/advanced/zones/change_zones.rst

@@ -0,0 +1,2 @@
+Change Zones
+============

docs/source/advanced/zones/configure_zones.rst

@@ -1,2 +1,2 @@
-xCAT Port Usage
+Configure Zones
 ===============

docs/source/advanced/zones/create_zones.rst

@@ -0,0 +1,2 @@
+Create Zones
+============

docs/source/advanced/zones/index.rst

@@ -0,0 +1,11 @@
+Zones
+=====
+
+.. toctree::
+   :maxdepth: 2
+
+   overview.rst
+   configure_zones.rst
+   create_zones.rst
+   change_zones.rst
+   remove_zones.rst 

docs/source/advanced/zones/overview.rst

@@ -0,0 +1,4 @@
+Overview
+========
+
+xCAT supports the concept of zones within a single xCAT cluster managed by one (1) Management Node.  The nodes in the cluster can be divided up into multiple zones that have different ssh keys managed separately. 

docs/source/advanced/zones/remove_zones.rst

@@ -0,0 +1,2 @@
+Remove Zones
+============