Trim diskless rootimg
=====================

To reduce the memory and boot-up time for the diskless node, the initrd and rootimg.gz should be kept as compact as possible under the premise of meeting the user's requirements.

Exclude list
------------

xCAT provides an attribute ``exlist`` in the **osimage** object definition, that allows the user to select files to exclude when building the ``rootimg.gz`` file for the diskless node.


Take the osimage **sles12.1-ppc64le-netboot-compute** for example::

  # lsdef -t osimage -o sles12.1-ppc64le-netboot-compute -i exlist
  Object name: sles12.1-ppc64le-netboot-compute
      exlist=/opt/xcat/share/xcat/netboot/sles/compute.sles12.ppc64le.exlist


Content of the Exclude List file
--------------------------------

The file specified in ``linuximage.exlist`` includes **relative path** of the directories and files that will be excluded from the **rootimg.gz** generated by ``packimage``. The **relative path** assumes the ``rootimg`` directory, ``/install/netboot/sles12.1/ppc64le/compute/rootimg`` here, to be the base directory. [1]_

The following is a sample of ``exlist`` file ::

  ...
  ./usr/share/X11/locale/*
  ./usr/lib/perl[0-9]/[0-9.]*/ppc64le-linux-thread-multi/Encode/JP*
  +./usr/share/X11/locale/C*
  ...

The content above presents some syntax supported in exlist file:

* Exclude files::

    ./usr/share/X11/locale/*

  All the files and subdirectories under ``rootimg/usr/share/X11/locale/`` will be excluded.

..

* Exclude Files using Patterns [2]_::

    ./usr/lib/perl[0-9]/[0-9.]*/ppc64le-linux-thread-multi/Encode/JP*

  Use regular expression to easily exclude files. The above example will exclude any Perl library installed under ``/usr/lib/`` matching ``ppc64le-linux-thread-multi/Encode/JP*``

..

* Include files::

    +./usr/share/locale/C*

  It is useful to include files following an exclude entry to quickly remove a larger set of files using a wildcard and then adding back the few necessary files using the + sign. In the above example, all the files and sub-directories matching the pattern ``/usr/share/locale/C*`` will be included in the ``rootimg.gz`` file.


Customize the ``exlist`` file and the osimage definition
--------------------------------------------------------

Check the default exlist file and make sure:

 * all files and directories you do not want in the image will be excluded from the rootimg.

 * no file or directory you need will be excluded from the rootimg.


If you want to customize the osimage ``sles12.1-ppc64le-netboot-compute`` with your own exlist file, follow the following steps: ::

  #create a customized exlist file based on the default one
  cp /opt/xcat/share/xcat/netboot/sles/compute.sles12.ppc64le.exlist /install/custom/netboot/sles/compute.sles12.ppc64le.exlist

  #edit the newly created exlist file according to your need
  vi /install/custom/netboot/sles/compute.sles12.ppc64le.exlist

  #specify the newly created exlist file in the osimage definition
  chdef -t osimage -o sles12.1-ppc64le-netboot-compute exlist=/install/custom/netboot/sles/compute.sles12.ppc64le.exlist

.. [1]  The ``exlist`` file entry should not end with a slash ``/``, For example, this entry will never match anything: ``./usr/lib/perl[0-9]/[0-9.]*/ppc64le-linux-thread-multi/Encode/``.

.. [2] Pattern match test applies to the whole file name, starting from one of the start points specified in the ``exlist`` file entry. The regex syntax should comply with the regex syntax of system command ``find -path``, refer to its doc for details.
