Merge pull request #487 from zet809/refine_discovery_doc

add bmcsetup in discovery doc, add chain document in Advanced Topics …

docs/source/advanced/chain/chain_table.rst

@@ -0,0 +1,14 @@
+Understanding chain table
+=========================
+
+The chain table (``tabdump chain``) is an xCAT database table that holds the chain configuration. The following attributes can be defined to perform the chain function: ::
+
+ * currstate
+ * currchain
+ * chain
+
+To know how are those three attributes used, pls reference the picture: 
+
+.. image:: chain_tasks_logic.png 
+ 
+

docs/source/advanced/chain/chain_tasks.rst

@@ -0,0 +1,45 @@
+Task Type
+=========
+
+xCAT supports following types of task which could be set in the chain:
+
+* runcmd ::
+
+    runcmd=<cmd>
+
+Currently only the ``bmcsetup`` command is officially supplied by xCAT to run to configure the bmc of the compute node. You can find the ``bmcsetup`` in /opt/xcat/share/xcat/netboot/genesis/<arch>/fs/bin/. You also could create your command in this directory and adding it to be run by ``runcmd=<you cmd>``. ::
+
+    runcmd=bmcsetup
+
+**Note**: the command ``mknb <arch>`` is needed before reboot the node.
+
+* runimage ::
+
+    runimage=<URL>
+
+**URL** is a string which can be run by ``wget`` to download the image from the URL. The example could be: ::
+  
+    runimage=http://<IP of xCAT Management Node>/<dir>/image.tgz
+
+The ``image.tgz`` **must** have the following properties:
+  * Created using the ``tar zcvf`` command
+  * The tarball must include a ``runme.sh`` script to initiate the execution of the runimage
+
+To create your own image, please reference :ref:`creating image for runimage <create_image_for_runimage>`. 
+
+**Tip**: You could try to run ``wget http://<IP of xCAT Management Node>/<dir>/image.tgz`` manually to make sure the path has been set correctly.
+
+* osimage ::
+
+   osimage=<image name>
+
+This task is used to specify the image that should be deployed onto the compute node.
+
+* shell
+
+Causes the genesis kernel to create a shell for the administrator to log in and execute commands.
+
+* standby
+
+Causes the genesis kernel to go into standby and wait for tasks from the chain. ... 
+

docs/source/advanced/chain/create_image_for_runimage.rst

@@ -0,0 +1,42 @@
+.. _create_image_for_runimage:
+
+How to prepare a image for ``runimage`` in ``chain``
+====================================================
+
+* The things needed
+    * The pkgs, scripts or other files that you needed
+    * The runme.sh script that you create to operate the needed files
+
+* The steps to generate the image
+    * create a directory under /install or any other directory that can be accessed with http.
+    * modify the permission for runme.sh to make sure it is able to be executed
+    * copy or move the needed files and runme.sh to the created directory
+    * go to the directory and run `tar -zcvf <image> .`
+
+* Example
+    In the example, it shows how to install an independent pkg a.rpm 
+
+    * Create the directory for the image: ::
+
+        mkdir -p /install/my_image
+
+    * Go to the direcotry and copy the rpm file into it: ::
+
+        cd /install/my_image
+        cp /tmp/a.rpm /install/my_image
+
+    * Write the runme.sh script and modify the permission: ::
+
+         cat runme.sh
+         echo "start installing a.rpm"
+         rpm -ivh a.rpm  
+
+    * modify the runme.sh script permission: ::
+
+         chmod +x runme.sh
+
+    * Create the tar ball for the directory: ::
+
+         tar -zcvf my_image.tgz .
+
+

docs/source/advanced/chain/index.rst

@@ -0,0 +1,15 @@
+Chain
+=====
+
+The **chain** mechanism is created to allow the administrator to define a series of tasks or operations that will be executed in series on the target node.
+
+The **chain** mechanism is implemented in xCAT genesis system. The genesis is a customized Linux system, if can be used to do discovery and configuration after booted on the specified node.
+
+.. toctree::
+    :maxdepth: 2
+
+    chain_table.rst
+    chain_tasks.rst
+    run_tasks_during_discovery.rst
+    run_tasks_to_configure.rst
+     

docs/source/advanced/chain/run_tasks_during_discovery.rst

@@ -0,0 +1,9 @@
+Run Task List During Discovery
+==============================
+
+To run a list of tasks during the discovery, set the tasks in the chain table by using the ``chdef`` command to change the chain attribute, before powering on the nodes. For example: ::
+
+    chdef <noderange> chain='runcmd=bmcsetup,osimage=<osimage name>'
+
+These tasks will be run after the discovery.
+

docs/source/advanced/chain/run_tasks_to_configure.rst

@@ -0,0 +1,11 @@
+Run Task List to Configure a Node
+=================================
+
+Run the ``nodeset`` command to set the tasks for the compute node and ``rpower <noderange> reset`` to initiate the running of tasks. ::
+
+    nodeset <noderange> runimage=http://<IP of xCAT Management Node>/image.tgz,osimage=<image_name>
+    rpower <noderange> reset
+
+In this example, the ``runimage`` will be run first, and then the image <image_name> will be deployed to the node.
+
+

docs/source/advanced/index.rst

@@ -4,19 +4,20 @@ Advanced Topics
 .. toctree::
    :maxdepth: 2
 
-   confluent/index.rst
+   chain/index.rst
    cluster_maintenance/index.rst
+   confluent/index.rst
    docker/index.rst
    gpu/index.rst
    hamn/index.rst
    hierarchy/index.rst
+   kit/index.rst
    mixed_cluster/index.rst
    networks/index.rst
    ports/xcat_ports.rst
    raid/index.rst
    security/index.rst
    softlayer/index.rst
-   kit/index.rst
    switches/index.rst
    sysclone/index.rst
    webservices/index.rst

docs/source/guides/admin-guides/manage_clusters/ppc64le/discovery/mtms_discovery.rst

@@ -51,8 +51,11 @@ The server definition will be like this::
 
 After the physical server is defined into xCATdb, the next thing is update the node definition with the example node attributes::
 
-  # chdef cn1 ip=10.0.101.1
-  1 object definitions have been created or modified.
+  chdef cn1 ip=10.0.101.1
+
+In order to do BMC configuration during the discovery process, set ``runcmd=bmcsetup``. For more info about chain, please refer to :doc:`Chain <../../../../../advanced/chain/index>`   ::
+
+  chdef cn1 chain="runcmd=bmcsetup"
 
 Then, add node info into /etc/hosts and DNS::
 

docs/source/guides/admin-guides/manage_clusters/ppc64le/discovery/seq_discovery.rst

@@ -17,7 +17,11 @@ Predefine a group of nodes with desired IP address for host and IP address for F
 
     nodeadd cn1 groups=powerLE,all
     chdef cn1 mgt=ipmi cons=ipmi ip=10.0.101.1 bmc=50.0.101.1 netboot=petitboot installnic=mac primarynic=mac
- 
+
+In order to do BMC configuration during the discovery process, set ``runcmd=bmcsetup``. For more info about chain, please refer to :doc:`Chain <../../../../../advanced/chain/index>`   ::
+
+    chdef cn1 chain="runcmd=bmcsetup"
+
 Initialize the discovery process
 ````````````````````````````````
 

docs/source/guides/admin-guides/manage_clusters/ppc64le/discovery/switch_discovery.rst

@@ -52,6 +52,10 @@ After switches are defined, the server node can be predefined with the following
     chdef cn1 mgt=ipmi cons=ipmi ip=10.0.101.1 bmc=50.0.101.1 netboot=petitboot installnic=mac primarynic=mac
     chdef cn1 switch=switch1 switchport=0
 
+In order to do BMC configuration during the discovery process, set ``runcmd=bmcsetup``. For more info about chain, please refer to :doc:`Chain <../../../../../advanced/chain/index>`   ::
+
+    chdef cn1 chain="runcmd=bmcsetup"
+
 Add cn1 into DNS::
 
     makehosts cn1

docs/source/guides/admin-guides/references/man5/chain.5.rst

@@ -56,7 +56,7 @@ chain Attributes:
 
 \ **chain**\ 
  
- A comma-delimited chain of actions to be performed automatically when this node is discovered. ("Discovered" means a node booted, but xCAT and DHCP did not recognize the MAC of this node. In this situation, xCAT initiates the discovery process, the last step of which is to run the operations listed in this chain attribute, one by one.) Valid values:  boot or reboot, install or netboot, runcmd=<cmd>, runimage=<URL>, shell, standby. (Default - same as no chain - it will do only the discovery.).  Example, for BMC machines use: runcmd=bmcsetup,shell.
+ A comma-delimited chain of actions to be performed automatically when this node is discovered. ("Discovered" means a node booted, but xCAT and DHCP did not recognize the MAC of this node. In this situation, xCAT initiates the discovery process, the last step of which is to run the operations listed in this chain attribute, one by one.) Valid values:  boot, runcmd=<cmd>, runimage=<URL>, shell, standby. (Default - same as no chain - it will do only the discovery.).  Example, for BMC machines use: runcmd=bmcsetup,shell.
  
 
 

docs/source/guides/admin-guides/references/man7/group.7.rst

@@ -183,7 +183,7 @@ group Attributes:
 
 \ **chain**\  (chain.chain)
  
- A comma-delimited chain of actions to be performed automatically when this node is discovered. ("Discovered" means a node booted, but xCAT and DHCP did not recognize the MAC of this node. In this situation, xCAT initiates the discovery process, the last step of which is to run the operations listed in this chain attribute, one by one.) Valid values:  boot or reboot, install or netboot, runcmd=<cmd>, runimage=<URL>, shell, standby. (Default - same as no chain - it will do only the discovery.).  Example, for BMC machines use: runcmd=bmcsetup,shell.
+ A comma-delimited chain of actions to be performed automatically when this node is discovered. ("Discovered" means a node booted, but xCAT and DHCP did not recognize the MAC of this node. In this situation, xCAT initiates the discovery process, the last step of which is to run the operations listed in this chain attribute, one by one.) Valid values:  boot, runcmd=<cmd>, runimage=<URL>, shell, standby. (Default - same as no chain - it will do only the discovery.).  Example, for BMC machines use: runcmd=bmcsetup,shell.
  
 
 

docs/source/guides/admin-guides/references/man7/node.7.rst

@@ -195,7 +195,7 @@ node Attributes:
 
 \ **chain**\  (chain.chain)
  
- A comma-delimited chain of actions to be performed automatically when this node is discovered. ("Discovered" means a node booted, but xCAT and DHCP did not recognize the MAC of this node. In this situation, xCAT initiates the discovery process, the last step of which is to run the operations listed in this chain attribute, one by one.) Valid values:  boot or reboot, install or netboot, runcmd=<cmd>, runimage=<URL>, shell, standby. (Default - same as no chain - it will do only the discovery.).  Example, for BMC machines use: runcmd=bmcsetup,shell.
+ A comma-delimited chain of actions to be performed automatically when this node is discovered. ("Discovered" means a node booted, but xCAT and DHCP did not recognize the MAC of this node. In this situation, xCAT initiates the discovery process, the last step of which is to run the operations listed in this chain attribute, one by one.) Valid values:  boot, runcmd=<cmd>, runimage=<URL>, shell, standby. (Default - same as no chain - it will do only the discovery.).  Example, for BMC machines use: runcmd=bmcsetup,shell.
  
 
 

perl-xCAT/xCAT/Schema.pm

@@ -353,7 +353,7 @@ chain => {
   node => 'The node name or group name.',
   currstate => 'The current or next chain step to be executed on this node by xCAT-genesis.  Set by xCAT during node discovery or as a result of nodeset.',
   currchain => 'The chain steps still left to do for this node.  This attribute will be automatically adjusted by xCAT while xCAT-genesis is running on the node (either during node discovery or a special operation like firmware update).  During node discovery, this attribute is initialized from the chain attribute and updated as the chain steps are executed.',
-  chain => 'A comma-delimited chain of actions to be performed automatically when this node is discovered. ("Discovered" means a node booted, but xCAT and DHCP did not recognize the MAC of this node. In this situation, xCAT initiates the discovery process, the last step of which is to run the operations listed in this chain attribute, one by one.) Valid values:  boot or reboot, install or netboot, runcmd=<cmd>, runimage=<URL>, shell, standby. (Default - same as no chain - it will do only the discovery.).  Example, for BMC machines use: runcmd=bmcsetup,shell.',
+  chain => 'A comma-delimited chain of actions to be performed automatically when this node is discovered. ("Discovered" means a node booted, but xCAT and DHCP did not recognize the MAC of this node. In this situation, xCAT initiates the discovery process, the last step of which is to run the operations listed in this chain attribute, one by one.) Valid values:  boot, runcmd=<cmd>, runimage=<URL>, shell, standby. (Default - same as no chain - it will do only the discovery.).  Example, for BMC machines use: runcmd=bmcsetup,shell.',
   ondiscover => 'This attribute is currently not used by xCAT.  The "nodediscover" operation is always done during node discovery.',
      comments => 'Any user-written notes.',
      disable => "Set to 'yes' or '1' to comment out this row.",