diff --git a/docs/source/advanced/chain/chain_table.rst b/docs/source/advanced/chain/chain_table.rst new file mode 100644 index 000000000..419debe46 --- /dev/null +++ b/docs/source/advanced/chain/chain_table.rst @@ -0,0 +1,9 @@ +Understand chain table +====================== + +The **chain** table is designed to store the tasks(For example: 'runcmd=bmcsetup', 'runimage=', 'osimage=', 'install', 'boot', 'shell', 'standby' ...). There are three related attributes **currstate**,**currchain** and **chain** in the chain table which are used to perform the **chain** mechanism. + +When genesis is running on the node, it will sends 'get_task/get_next_task' request to xcatd. Then, xcatd will first copies the **chain** attribute to the **currchain** attribute, then pops one task from the **currchain** attribute and puts it into the **currstate** attribute. The **currstate** attribute will be send back to the node as the current task. The **currstate** attribute always shows the current task that is running. + +The pop function will continue if another 'get_next_task' request got by xCAT. It will continue until all tasks in the **currchain** attribute are completed (removed) then a 'standby' task will be send back. Then the node will standby for random time and send out 'get_task' again. It will keep in standby state until there is new task assign in ``chain`` for the node. + diff --git a/docs/source/advanced/chain/chain_tasks.rst b/docs/source/advanced/chain/chain_tasks.rst new file mode 100644 index 000000000..b85f56f53 --- /dev/null +++ b/docs/source/advanced/chain/chain_tasks.rst @@ -0,0 +1,40 @@ +Task Type +========= + +xCAT supports following types of task which could be set in the chain: + +* runcmd:: + + runcmd= + +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//fs/bin/. You also could create your command in this directory and adding it to be run by ``runcmd=``. :: + + e.g. runcmd=bmcsetup + +**Note**: the command ``mknb `` is needed before reboot the node. + +* runimage:: + + runimage= + +**URL** is a string which can be run by ``wget`` to download the image from the URL. The example could be: :: + + runimage=http://$MASTER//image.tgz + +The image.tgz should can be uncompressed by ``tar xvf image.tgz``. And image.tgz should include a file named ``runme.sh`` which is a script to initiate the running of the image. Pls reference :ref:`creating image for runimage ` for more information about creating your own ``image``. + +**Note**: You could try to run ``wget http://$MASTER//image.tgz`` manually to make sure the path has been set correctly. + +* osimage:: + + osimage= + +This task is used to specify that the compute node should run the OS deployment with osimage=. + +* shell + +Make the genesis gets into the shell for admin to log in and run command. + +* standby + +Make the genesis gets into standby and waiting for the task from chain. If the compute node gets into this state, any new task set to chain.currstate will be run immediately. diff --git a/docs/source/advanced/chain/create_image_for_runimage.rst b/docs/source/advanced/chain/create_image_for_runimage.rst new file mode 100644 index 000000000..94e116848 --- /dev/null +++ b/docs/source/advanced/chain/create_image_for_runimage.rst @@ -0,0 +1,39 @@ +.. _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 .` + +* 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 + #chmod +x runme.sh + + * Create the tar ball for the directory: :: + + #tar -zcvf my_image.tar . + + diff --git a/docs/source/advanced/chain/index.rst b/docs/source/advanced/chain/index.rst new file mode 100644 index 000000000..135cedd09 --- /dev/null +++ b/docs/source/advanced/chain/index.rst @@ -0,0 +1,15 @@ +Chain +===== + +In xCAT, we introduced the **chain** mechanism which means a series of tasks that had been defined in it can be done one by one on the specified 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 + diff --git a/docs/source/advanced/chain/run_tasks_during_discovery.rst b/docs/source/advanced/chain/run_tasks_during_discovery.rst new file mode 100644 index 000000000..d03522a55 --- /dev/null +++ b/docs/source/advanced/chain/run_tasks_during_discovery.rst @@ -0,0 +1,9 @@ +Run Task List During Discovery +============================== + +If you want 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 chain='runcmd=bmcsetup,osimage=' + +These tasks will be run after the discovery. + diff --git a/docs/source/advanced/chain/run_tasks_to_configure.rst b/docs/source/advanced/chain/run_tasks_to_configure.rst new file mode 100644 index 000000000..34c9feb53 --- /dev/null +++ b/docs/source/advanced/chain/run_tasks_to_configure.rst @@ -0,0 +1,12 @@ +Run Task List to Configure a Node +================================= + +Run the ``nodeset`` command to set the tasks for the compute node and ``rpower reset`` to initiate the running of tasks. :: + + nodeset $node runimage=http://$MASTER/image.tgz,osimage= + rpower $node reset + +In this example, the ``runimage`` will be run first, and then the image will be deployed to the node. + +During ``nodeset`` your request is put into the ``currstate`` attribute. The ``chain`` attribute is not used. The task in the ``currstate`` attribute will be passed to genesis and executed. If additional tasks are defined in the ``currchain`` attribute, these tasks will be run after the tasks in the ``currstate`` attribute are run. + diff --git a/docs/source/advanced/index.rst b/docs/source/advanced/index.rst index 28674613a..8894a6aa0 100644 --- a/docs/source/advanced/index.rst +++ b/docs/source/advanced/index.rst @@ -6,6 +6,7 @@ Advanced Topics confluent/index.rst cluster_maintenance/index.rst + chain/index.rst docker/index.rst gpu/index.rst hamn/index.rst diff --git a/docs/source/guides/admin-guides/manage_clusters/ppc64le/discovery/mtms_discovery.rst b/docs/source/guides/admin-guides/manage_clusters/ppc64le/discovery/mtms_discovery.rst index b4f9d798b..19f883bae 100644 --- a/docs/source/guides/admin-guides/manage_clusters/ppc64le/discovery/mtms_discovery.rst +++ b/docs/source/guides/admin-guides/manage_clusters/ppc64le/discovery/mtms_discovery.rst @@ -54,6 +54,11 @@ After the physical server is defined into xCATdb, the next thing is update the n # chdef cn1 ip=10.0.101.1 1 object definitions have been created or modified. +In order to do BMC configuration during the discovery progress, the following command is needed, for more info about chain, pls refer the **Chain** document in **Advanced Topics** chapter:: + + # chdef cn1 chain="runcmd=bmcsetup" + 1 object definitions have been created or modified. + Then, add node info into /etc/hosts and DNS:: makehosts cn1 diff --git a/docs/source/guides/admin-guides/manage_clusters/ppc64le/discovery/seq_discovery.rst b/docs/source/guides/admin-guides/manage_clusters/ppc64le/discovery/seq_discovery.rst index 00dff6d54..10d494f47 100644 --- a/docs/source/guides/admin-guides/manage_clusters/ppc64le/discovery/seq_discovery.rst +++ b/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 progress, the following command is needed, for more info about chain, pls refer the **Chain** document in **Advanced Topics** chapter:: + + chdef cn1 chain="runcmd=bmcsetup" + Initialize the discovery process ```````````````````````````````` diff --git a/docs/source/guides/admin-guides/manage_clusters/ppc64le/discovery/switch_discovery.rst b/docs/source/guides/admin-guides/manage_clusters/ppc64le/discovery/switch_discovery.rst index d50c95cc7..603a5d573 100644 --- a/docs/source/guides/admin-guides/manage_clusters/ppc64le/discovery/switch_discovery.rst +++ b/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 progress, the following command is needed, for more info about chain, pls refer the **Chain** document in **Advanced Topics** chapter:: + + chdef cn1 chain="runcmd=bmcsetup" + Add cn1 into DNS:: makehosts cn1 diff --git a/docs/source/guides/admin-guides/references/man5/chain.5.rst b/docs/source/guides/admin-guides/references/man5/chain.5.rst index 9aa79776b..0b9ae1cb0 100644 --- a/docs/source/guides/admin-guides/references/man5/chain.5.rst +++ b/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=, runimage=, 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=, runimage=, shell, standby. (Default - same as no chain - it will do only the discovery.). Example, for BMC machines use: runcmd=bmcsetup,shell. diff --git a/docs/source/guides/admin-guides/references/man7/group.7.rst b/docs/source/guides/admin-guides/references/man7/group.7.rst index 5f3fbe5c6..95de3ab9c 100644 --- a/docs/source/guides/admin-guides/references/man7/group.7.rst +++ b/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=, runimage=, 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=, runimage=, shell, standby. (Default - same as no chain - it will do only the discovery.). Example, for BMC machines use: runcmd=bmcsetup,shell. diff --git a/docs/source/guides/admin-guides/references/man7/node.7.rst b/docs/source/guides/admin-guides/references/man7/node.7.rst index bda994e9c..4c2ac6966 100644 --- a/docs/source/guides/admin-guides/references/man7/node.7.rst +++ b/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=, runimage=, 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=, runimage=, shell, standby. (Default - same as no chain - it will do only the discovery.). Example, for BMC machines use: runcmd=bmcsetup,shell. diff --git a/perl-xCAT/xCAT/Schema.pm b/perl-xCAT/xCAT/Schema.pm index fc68c7486..fa527ba6b 100755 --- a/perl-xCAT/xCAT/Schema.pm +++ b/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=, runimage=, 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=, runimage=, 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.",