xcat-core/xCAT-client/pods/man1/updatenode.1.pod

=head1 NAME

B<updatenode> - Update nodes in an xCAT cluster environment.

=head1 SYNOPSIS

B<updatenode> B<noderange> [B<-V>|B<--verbose>] [B<-F>|B<--sync>] [B<-S>|B<--sw>] [B<-P>|B<--scripts> [B<script1,script2...>]] [B<-s>|B<--sn>] [B<-A>|B<--updateallsw>] [B<-c>|B<--cmdlineonly>] [B<-d alt_source_dir>] [B<attr=val> [B<attr=val...>]]

B<updatenode> B<noderange> [B<-k>|B<--security> [B<--user>] [B<--devicetype>]]

B<updatenode> B<noderange> [B<-V>|B<--verbose>] [B<script1,script2...>]

B<updatenode> [B<-h>|B<--help>] [B<-v>|B<--version>]

=head1 DESCRIPTION

The updatenode command is run on the xCAT management node and can be used
to perform the following node updates:

=over 3

=item 1

Distribute and synchronize files.  

=item 2

Install or update software on diskfull nodes.

=item 3

Run postscripts.

=item 4

Update the ssh keys and host keys for the service nodes and compute nodes;
Update the ca and credentials for the service nodes.

=back

The default behavior of updatenode will be to attempt to perform the update 
which doing by "-S", "-P" and "-F" flags.
If you wish to limit updatenode to one or two specific 
actions you can use combinations of the "-S", "-P", and "-F" flags.

If more than one actions doing by "-S", "-P" and "-F" need to be performed,
the execution sequence is "-F", "-S" and then "-P".

For example, If you just want to synchronize configuration file you could
specify the "-F" flag.   If you want to synchronize files and update 
software you would specify the "-F" and "-S" flags. See the descriptions 
of these flags and examples below.

The flag "-k" (--security) can NOT be used together with "-S", "-P", and "-F"
flags. The flag "--user" and "--devicetype" ONLY can be used with "-k" flag to
update the ssh keys for specific device.

Note: In a large cluster environment the updating of nodes in an ad hoc 
manner can quickly get out of hand, leaving the system administrator with 
a very confusing environment to deal with. The updatenode command is 
designed to encourage users to handle cluster updates in a manner that 
is recorded and easily repeatable.  

=head2 To distribute and synchronize files

The basic process for distributing and synchronizing nodes is:

=over 3

=item *

Create a synclist file.

=item *

Indicate the location of the synclist file.

=item *

Run the updatenode command to update the nodes.

=back

Files may be distributed and synchronized for both diskless and 
diskfull nodes.  However, since some filesystems are mounted 
read-only on AIX diskless nodes it my not be possible to update all 
files on AIX systems.  For example, any files under /usr on AIX 
diskless nodes cannot be updated.

More information on using the  synchronization file function is in  
https://sourceforge.net/apps/mediawiki/xcat/index.php?title=Using_Updatenode.

=head3 Create the synclist file

The synclist file contains the configuration entries that specify 
where the files should be synced to. In the synclist file, each 
line is an entry which describes the location of the source files 
and the destination location for the files on the target node. 

The basic entry format looks like following:

  path_of_src_file1  -> path_of_dst_file1
  path_of_src_file1  -> path_of_dst_directory ( must end in /)
  path_of_src_file1  path_of_src_file2 ... -> path_of_dst_directory

The path_of_src_file* should be the full path of the source file 
on the Management Node.
The path_of_dst_file* should be the full path of the destination 
file on target node.
The path_of_dst_directory should be the full path of the destination directory.
Since the synclist file is for common purpose, the target node 
need not be configured in it, it will be the noderange input to 
updatenode. 

The following formats are supported:

=over 3

=item 1

sync file /etc/file1 to the file /etc/file1 on the node with 
the same file name. Note with one file, full path to file 
must be provide.

  /etc/file1 -> /etc/file1
 or
  /etc/file1 -> /etc/

=item 2

sync file /etc/file2 to the file /etc/file3 on the node (with 
different file name)

  /etc/file2 -> /etc/file3

=item 3

sync file /etc/file2 to the file /etc/tmp/file3 on the node  
with different file name, different directory)
If the directory does not exist, it will be created.

  /etc/file2 -> /etc/tmp/file3

=item 4

sync the multiple files /etc/file1, /etc/file2,  /etc/file3, 
... to the directory /tmp/etc (/tmp/etc must be a directory when 
multiple files are sync'd at one time).  If the directory does 
not exist, xdcp will create it.

  /etc/file1 /etc/file2 /etc/file3 -> /tmp/etc
  or
  /etc/file1 /etc/file2 /etc/file3 -> /tmp/etc/

=item 5 

sync all the files in /etc to /tmp/etc 

  /etc/* -> /tmp/etc/

=back

=head3 Indicate the location of the synclist file

For Linux nodes, the path of the synclist should be following format:

   /install/custom/<inst_type>/<distro>/<profile>.<os>.<arch>.synclist
 
where:

     <inst_type>: "install", "netboot"
     <distro>: "rh", "centos", "fedora", "sles"
     <profile>,<os> and <arch> are what you set for the node

For AIX nodes, add a full path of the synclist file to the "synclists" 
attribute base on the xCAT osimage name used by the node 
in the osimage table. 

  chdef -t osimage -o myosimage synclists=/mydir/syncfile1

=head3 Run updatenode to synchronize the files
        
  updatenode <noderange> -F


=head2 To install or update software

The basic process for updating software on a node is:

=over 3

=item *

Copy the software to a directory.

=item *

Create a record of what software to install.

=item *

Run the updatenode command to update the nodes.

=back

=over 3

B<For Linux systems:>

=over 3

=item 1

Copy the extra rpms you are going to add on to

  /install/post/otherpkgs/<os>/<arch>/
 
 where <os> and <arch> are defined in the <nodetype> table.

=item 2

Add rpm names (without version number) into

  /install/custom/<inst_type>/<ostype>/<profile>.<os>.<arch>.otherpkgs.pkglist

In the file path, the <inst_type> should be "install" if the
node was installed in diskfull state, otherwise it should be 
"netboot" if it was installed in diskless state.
<ostype> is the operating system name without the version
number.The following <ostype> are recognized by xCAT:

=over 1

=item centos

=item fedora

=item rh

=item sles

=item windows

=back

In the file name, the <profile>, <os>, <arch> are defined in
the <nodetype> table. And the <os> and <arch> fields can be
ignored if the pkglist file is available just depend on the 
<profile> attribute.

=item 3

Type:

  updatenode <noderange> -S

=back

B<For AIX systems:>

Note: The updatenode command is used to update AIX diskfull nodes only. For updating diskless AIX nodes refer to the xCAT for AIX update documentation and use the xCAT mknimimage command.

You can update the software on AIX nodes using AIX installp filesets, RPM 
packages or AIX interim fix manager packages. The updatenode command will 
handle the underlying calls to the appropriate AIX commands.  The AIX
installp, rpm and emgr commands will be used.  See the AIX documentation for 
more details on these commands.

The software packages that you wish to install on the nodes must be 
copied to a directory location that can be exported and mounted on the
node.  This should normally be the appropriate directory location in 
the NIM lpp_source resource corresponding to the operating system image
that was used to install the node.  You can, however, specify a different
directory location by specifying the "-d" option on the command line.

Note: To find the correct lpp_source for the node get the name of
the xCAT osimage definition from the "provmethod" attribute of the xCAT node
definition and then get the name of the lpp_source resource from the
osimage definition. You can use the xCAT lsdef command to display the node 
and osimage definitions.

A simple way to copy software to the lpp_source resource is to use 
the "nim -o update" command.  For example, assuming the software is in 
/images and the lpp_source resource used for this node is named "mylpp" then 
you could run:

B<nim -o update -a packages=all -a source=/images mylpp>

The software you wish to install or update must be specified to
the updatenode command.  There are two methods that may be used to specify 
the software to update.

The first is to specify the software in the osimage definition 
that is included in the node definiton.  In this case the software 
to install would be whatever is provided in the "installp_bundle" and/or
"otherpkgs" attributes of the xCAT osimage definition.

The second method is to specify the software to install on the updatenode
command line.  You can do this by providing either the "otherpkgs" or
"installp_bundle" attributes or the "-A" flag.

Using the first method provides a record of what was updated which is stored
in the xCAT database. This can be useful when managing a large cluster 
environment.  The second method is more "ad hoc" but also can be more flexible.

The updatenode command will either use the information in the database or the
information on the command line - BUT NOT BOTH.  If you specify information
on the command line it will use that, otherwise it will use what is in the 
database.

The "installp_bundle" attribute value may be set to a comma separated list of
one or more NIM installp_bundle resource names.  These NIM resources must
be created using standard NIM interfaces. See the AIX documentation for more 
information on creating NIM resources. Also, there are examples for creating 
installp_bundle resources in several of the xCAT for AIX documents.

The "otherpkgs" attribute value may be set to a comma separated list of 
installp filesets, RPM packages or epkg (AIX interim fix package) files.

Along with the names of the software to install you may also provide the
specific installp, rpm, and emgr flags you want used when those commands 
are run on the nodes.  Use the "installp_flags", "rpm_flags", and "emgr_flags"
attributes to provide this information. Make sure you specify the exact 
string you want used in quotes.  For example: 
I<installp_flags="-apXY" rpm_flags="-i --nodeps" emgr_flags="-X">.  The 
flags specified on the updatenode command line will replace the
default values.

The default value for installp_flags is "-agQX" and the default value for 
rpm_flags is "-Uvh --replacepkgs". There is no default for the emgr command.  

The underlying calls to the installp and emgr commands are both handled by
creating a temporary file containing the list of software to install and 
then using the "-f listfile" option. 

When doing software maintenance on AIX nodes you may also find the "-c" 
flag useful.  When you specify this flag on the updatenode command line
the command will know to use the command line information ONLY, even if
there is no software specified (i.e. It won't go look in the database.).  
This option would be needed when using installp, rpm or emgr options that 
do not require a list of software.

If you wish to see the output from the installp, emgr or rpm commands 
then you must specifiy "-V" on the updatenode command line.

See the examples below for more details.

When working in a hierarchical xCAT cluster the updatenode command will
distribute the software to the service nodes as needed.

=back

=head2 To run postscripts

The scripts must be copied to the /install/postscripts 
directory on the xCAT management node. (Make sure they are 
executable.)

To run scripts on a node you must either specify them on the 
command line or you must add them to the "postscripts" attribute 
for the node.  

To set the postscripts attribute of the node (or group) 
definition you can use the xCAT chdef command. Set the value to 
be a comma separated list of the scripts that you want to be 
executed on the nodes. The order of the scripts in the list 
determines the order in which they will be run.  You could also set
the postscripts value by directly editing the xCAT "postscripts" 
database table using the xCAT tabedit command.

Scripts may be run on both diskless and diskfull nodes.

To run all the customization scripts that have been designated 
for the nodes, (in the "postscripts" attribute), type:

  updatenode <noderange> -P

To run the "syslog" script for the nodes, type:

  updatenode <noderange> -P syslog

To run  a list of scripts, type:

  updatenode <noderange> -P script1,script2

The flag '-P' can be omitted when only postscripts parameters are
specified.

Note: script1,script2 may or may not be designated as scripts to 
automatically run on the node. However, if you want script1 and 
script2 to get invoked next time the nodes are deployed then make sure 
to add them to the "postscripts" attribute in the database for the nodes. 

=head2 Update security

The basic functions of update security for nodes:

=over 3

=item *

Setup the ssh keys for the target nodes. It makes the management
node and service node access the target nodes without password.

=item *

Redeliver the host keys to the target nodes.

=item *

Redeliver the ca and certificates files to the service node.
These files are used to authenticate the ssl connection between
xcatd's of management node and service node.

=item *

Remove the entries of target nodes from known_hosts file.

=back

I<Set up the SSH keys>

A password for the user who is running this command is needed to setup
the ssh keys. This user must have the same uid and gid as
the userid on the target node where the keys will be setup.

If the current user is root, roots public ssh keys will be put in the
authorized_keys* files under roots .ssh directory on the node(s).
If the current user is non-root, the user must be in the policy table
and have credential to run the xdsh command.
The non-root users public ssh keys and root's public ssh keys will be put in
the authorized_keys* files under the non-root users .ssh directory on the node(s
).

Other device types, such as IB switch, are also supported.  The
device should be defined as a node and nodetype should be defined
as switch before connecting.

The flags B<--user> and B<--devicetype> can be used to specify the 'user'
and configuration file to set up the ssh keys for the specific device.

I<Handle the hierarchical scenario>

When update security files for the node which is served by a service node,
the service node will be updated automatically first, and then the target
node.

The ca and certificates files are needed for service node to authenticate
the ssl connections between the xCAT client and xcatd on the service node,
and the xcatd's between service node and management node. The files in the
directories /etc/xcat/cert/ and ~/.xcat/ will be updated.

Since the certificates have the validity time, the ntp service is recommended 
to be set up between management node and service node.

Simply running following command to update the security keys:
	 B<updatenode> I<noderange> -k


=head1 PARAMETERS

=over 10

=item B<noderange>

A set of comma delimited xCAT node names
and/or group names. See the xCAT "noderange"
man page for details on additional supported 
formats.

=item B<script1,script2...>

A comma-separated list of script names. 
The scripts must be executable and copied 
to the /install/postscripts directory.

=item [B<attr=val> [B<attr=val...>]]

Specifies one or more "attribute equals value" pairs, separated by spaces.
Attr=val pairs must be specified last on the command line.  The currently
supported attributes are: "installp_bundle", "otherpkgs", "installp_flags", 
"emgr_flags" and "rpm_flags".  These attribute are only valid for AIX software
maintenance support.

=back

=head1 OPTIONS

=over 10

=item B<-A|--updateallsw>

Install or update all software contained in the source directory. (AIX only)

=item B<-c|cmdlineonly>

Specifies that the updatenode command should only use software maintenance
information provided on the command line.  This flag is only valid when
using AIX software maintenance support.

=item B<--devicetype>

Specify a user-defined device type that references the location
of relevant device configuration file. The devicetype value must
correspond to a valid device configuration file under the /var/opt/xcat/
directory.
For example, /var/opt/xcat/IBSwitch/Qlogic/config is the configuration
file location if devicetype is specified as IBSwitch::Qlogic

This flag ONLY can be used with -k and --user.

=item B<-d alt_source_dir>

Used to specify a source directory other than the standard lpp_source directory specified in the xCAT osimage definition.  (AIX only)

=item B<-F|--sync>

Specifies the file synchronization should be
performed on the nodes.  rsync and ssh must
be installed and configured on the nodes. 

=item B<-h|--help>

Display usage message.

=item B<-k|--security>

Update the ssh keys and host keys for the service nodes and compute nodes;
Update the ca and credentials to the service nodes.

=item B<-P|--scripts>

Specifies that postscripts should be run on the nodes.

=item B<-S|--sw>

Specifies that node software should be updated.

=item B<-s|--sn>

Set the server information stored on the nodes.

=item B<--user>

Specifies a remote user name to login a specific device.

This flag ONLY can be used with -k and --devicetype.

=item B<-v|--version>

Command Version.

=item B<-V|--verbose>

Verbose mode.

=back

=head1 RETURN VALUE

0  The command completed successfully.

1  An error has occurred.


=head1 EXAMPLES

=over 3

=item 1

To perform all updatenode features for the Linux nodes in the group
"compute":

B<updatenode compute>

The command will: run any scripts listed in the nodes "postscripts" 
attribute, install or update any software indicated in the 
/install/custom/install/<ostype>/profile.otherpkgs.pkglist (refer to the 
B<To install or update software part>), synchronize any files indicated by 
the synclist files specified in the osimage "synclists" attribute.

=item 2

To perform a software update and file synchronization only on the node
"clstrn01":

B<updatenode clstrn01 -F -P>

=item 3

Running updatenode -P with the syncfiles postscript is not supported. You should use updatenode -F instead. 

Do not run:

B<updatenode clstrno1 -P syncfiles>

Run:

B<updatenode clstrn01 -F>

=item 3

To run the postscripts which indicated in the postscripts attribute on 
the node "clstrn01":

B<updatenode clstrn01 -P>

=item 4

To run the postscripts script1 and script2 on the node "clstrn01":

B<cp script1,script2 /install/postscripts>

B<updatenode clstrn01 -P script1,script2>

Since flag '-P' can be omitted when only postscripts parameters are specified, 
the following command is equivalent:

B<updatenode clstrn01 script1,script2>

=item 5

To synchronize the files on the node "clstrn01":  Prepare the synclist file. 
For AIX, set the full path of synclist in the osimage table synclists 
attribute. For Linux, put the synclist file into the location: 
/install/custom/<inst_type>/<distro>/<profile>.<os>.<arch>.synclist
Then:

B<updatenode clstrn01 -F>

=item 6

To perform the software update on the Linux node "clstrn01":  Copy the extra 
rpm into the /install/post/otherpkgs/<os>/<arch>/* and add the rpm names into 
the /install/custom/install/<ostype>/profile.otherpkgs.pkglist .  Then:

B<updatenode clstrn01 -S>

=item 7

To update the AIX node named "xcatn11" using the "installp_bundle" and/or
"otherpkgs" attribute values stored in the xCAT database.  Use the default installp, rpm and emgr flags.

B<updatenode xcatn11 -V -S>

Note: The xCAT "xcatn11" node definition points to an xCAT osimage definition 
which contains the "installp_bundle" and "otherpkgs" attributes as well as
the name of the NIM lpp_source resource.

=item 8

To update the AIX node "xcatn11" by installing the "bos.cpr" fileset using 
the "-agQXY" installp flags.  Also display the output of the installp command.

B<updatenode xcatn11 -V -S otherpkgs="bos.cpr" installp_flags="-agQXY">

=item 9 

To uninstall the "bos.cpr" fileset that was installed in the previous example.

B<updatenode xcatn11 -V -S otherpkgs="bos.cpr" installp_flags="-u">

=item 10

To update the AIX nodes "xcatn11" and "xcatn12" with the "gpfs.base" fileset
and the "rsync" rpm using the installp flags "-agQXY" and the rpm flags "-i --nodeps".

B<updatenode xcatn11,xcatn12 -V -S otherpkgs="gpfs.base,R:rsync-2.6.2-1.aix5.1.ppc.rpm" installp_flags="-agQXY" rpm_flags="-i --nodeps">

Note: Using the "-V" flag with multiple nodes may result in a large amount of output.

=item 11

To uninstall the rsync rpm that was installed in the previous example.

B<updatenode xcatn11 -V -S otherpkgs="R:rsync-2.6.2-1" rpm_flags="-e">

=item 12

Update the AIX node "node01" using the software specified in the NIM "sslbnd" and "sshbnd" installp_bundle resources and the "-agQXY" installp flags.

B<updatenode node01 -V -S installp_bundle="sslbnd,sshbnd" installp_flags="-agQXY">

=item 13

To get a preview of what would happen if you tried to install the "rsct.base" fileset on AIX node "node42".  (You must use the "-V" option to get the full output from the installp command.)

B<updatenode node42 -V -S otherpkgs="rsct.base" installp_flags="-apXY">

=item 14

To check what rpm packages are installed on the AIX node "node09". (You must use the "-c" flag so updatenode does not get a list of packages from the database.)

B<updatenode node09 -V -c -S rpm_flags="-qa">

=item 15

To install all software updates contained in the /images directory.

B<updatenode node27 -V -S -A -d /images>

Note:  Make sure the directory is exportable and that the permissions are set
correctly for all the files.  (Including the .toc file in the case of
installp filesets.)

=item 16

Install the interim fix package located in the /efixes directory.

B<updatenode node29 -V -S -d /efixes otherpkgs=IZ38930TL0.120304.epkg.Z>

=item 17

To uninstall the interim fix that was installed in the previous example.

B<updatenode xcatsn11 -V -S -c emgr_flags="-r -L IZ38930TL0">

=item 18

To update the security keys for the node "node01"

B<updatenode node01 -k>

=back

=head1 FILES

/opt/xcat/bin/updatenode