\subsection{Upgrading OpenHPC Packages}  \label{appendix:upgrade}


As newer \OHPC{} releases are made available, users are encouraged to upgrade
their locally installed packages against the latest repository versions to
obtain access to bug fixes and newer component versions. This can be
accomplished with the underlying package manager as \OHPC{} packaging maintains
versioning state across releases. Also, package builds available from the
\OHPC{} repositories have ``\texttt{-ohpc}'' appended to their names so that
wild cards can be used as a simple way to obtain updates. The following general
procedure highlights a method for upgrading existing installations.
When upgrading from a minor release older than v\OHPCVerTree{}, you will first
need to update your local \OHPC{} repository configuration to point against the
v\OHPCVerTree{} release (or update your locally hosted mirror). Refer to
\S\ref{sec:enable_repo} for more details on enabling the latest
repository. In contrast, when upgrading between micro releases on the same
branch (e.g. from v\OHPCVerTree{} to \OHPCVerTree{}.2), there is no need to
adjust local package manager configurations when using the public repository as
rolling updates are pre-configured.

\begin{enumerate*}
\item (Optional) Ensure repo metadata is current (on head node and in chroot
  location(s)). Package managers will naturally do this on their own over time,
  but if you are wanting to access updates immediately after a new release,
  the following can be used to sync to the latest.

\begin{lstlisting}[language=bash,keywords={}]
[sms](*\#*)  (*\clean*)
[sms](*\#*)  (*\chrootclean*)
\end{lstlisting}

\item Upgrade master (SMS) node

\begin{lstlisting}[language=bash,keywords={}]
[sms](*\#*)  (*\upgrade*) "*-ohpc"

# Any new Base OS provided dependencies can be installed by
# updating the ohpc-base metapackage
[sms](*\#*)  (*\upgrade*) "ohpc-base"
\end{lstlisting}

\item Upgrade packages in compute image

\begin{lstlisting}[language=bash,keywords={}]
[sms](*\#*)  (*\chrootupgrade*) "*-ohpc"

# Any new compute-node Base OS provided dependencies can be installed by
# updating the ohpc-base-compute metapackage
[sms](*\#*)  (*\chrootupgrade*) "ohpc-base-compute"
\end{lstlisting}

\item Rebuild image(s)

\iftoggleverb{isWarewulf}
\begin{lstlisting}[language=bash,keywords={}]
[sms](*\#*) wwvnfs --chroot $CHROOT
\end{lstlisting}
\fi

\iftoggleverb{isxCAT}
\begin{lstlisting}[language=bash,keywords={},basicstyle=\fontencoding{T1}\fontsize{8.0}{10}\ttfamily,
    literate={-}{-}1 {BOSVER}{\baseos{}}1 {ARCH}{\arch{}}1]
[sms](*\#*) packimage BOSVER-x86_64-netboot-compute
\end{lstlisting}
\fi

\end{enumerate*}

\noindent In the case where packages were upgraded within the chroot compute image,
you will need to reboot the compute nodes when convenient to enable the
changes.

%%% \subsubsection{New component variants}
%%%
%%% As newer variants of key compiler/MPI stacks are released, \OHPC{} will
%%% periodically add toolchains enabling the latest variant. To stay consistent
%%% throughout the build hierarchy, minimize recompilation requirements for existing
%%% binaries, and allow for multiple variants to coexist, unique delimiters are
%%% used to distinguish RPM package names and module hierarchy.
%%%
%%% In the case of a fresh install, \OHPC{} recipes default to installation of the
%%% latest toolchains available in a given release branch. However, if upgrading a
%%% previously installed system, administrators can {\em opt-in} to enable new
%%% variants as they become available. To illustrate this point, consider the
%%% previous \OHPC{} 1.3.5 release as an example which contained GCC 7.3.0
%%% along with runtimes and libraries compiled with this toolchain.  In the case
%%% where an admin would like to enable the newer {``gnu8''} toolchain,
%%% installation of these additions is simplified with the use of \OHPC{}'s
%%% meta-packages (see Table~\ref{table:groups} in Appendix
%%% \ref{appendix:manifest}).  The following example illustrates adding the
%%% complete ``gnu8'' toolchain.  Note that we leverage the convenience
%%% meta-packages containing MPI-dependent builds, and we also update the
%%% modules environment to make it the default.
%%%
%%% \begin{lstlisting}[language=bash,keywords={}]
%%% # Install GCC 8.x-compiled meta-packages with dependencies
%%% [sms](*\#*)  (*\install*) ohpc-gnu8-perf-tools \
%%%                          ohpc-gnu8-io-libs \
%%%                          ohpc-gnu8-python-libs \
%%%                          ohpc-gnu8-runtimes \
%%%                          ohpc-gnu8-serial \
%%%                          ohpc-gnu8-parallel-libs
%%%
%%% # Update default environment
%%% [sms](*\#*) (*\remove*) lmod-defaults-gnu7-openmpi3-ohpc
%%% [sms](*\#*) (*\install*) lmod-defaults-gnu8-openmpi3-ohpc
%%%
%%% \end{lstlisting}
%%%
%%%
