\documentclass{ictlab}

\RCS $Revision: 1.4 $

\usepackage{alltt,key,moreverb}
%\usepackage[leftnum,lineno5,noindent]{lgrind}
\usepackage[lineno5,noindent]{lgrind}
\LGnuminterval=1
\def\LGfsize{\footnotesize}
\def\LGsize{\tiny}

\def\listinglabel#1{%
  \llap{\scriptsize\rmfamily\the#1}\hskip\listingoffset\relax%
}

\ifx\pdftexversion\undefined \else
  \usepackage[pdfpagemode=None,pdfauthor={Nick Urbanik}]{hyperref}
\fi

\newcommand*{\labTitle}{The Rescue Disk, Trouble Shooting and other
  Related Topics}
\renewcommand*{\subject}{Operating Systems and Systems Integration}

\begin{document}

\section{Aim}
\label{sec:aim}

After completing this exercise, you will:
\begin{itemize}
\item be aware of the usefulness of mini-Linux distributions in
  solving many problems, many of which are not Linux problems

\item have practical experience with one of the best mini-Linux
  distributions, \texttt{tomsrtbt}, available from
  \url{http://www.toms.net/rb/}.

\item be introduced to a shell script \texttt{report} that may be used
  to diagnose many computer problems, and through that:
  \begin{itemize}
  \item learn some aspects of shell script programming

  \item learn about the Linux \texttt{/proc} file system and its
    usefulness in describing the computer and its operation, as well
    as the operation of the operating system
  \end{itemize}
\end{itemize}
\section{Procedure}
\label{sec:procedure}


\subsection{A mini-Linux distribution: \texttt{tomsrtbt}}
\label{sec:tomsrtbt}

The mini Linux distribution \texttt{tomsrtbt} is useful for recovering
from many problems; it can be used to start a restore from backups
after the hard disk has been completely destroyed.  It is also useful
as a trouble-shooting aid.  This is how we will use it today.

Note that \texttt{tomsrtbt} uses the old \texttt{libc5} libraries,
which are not included in Red Hat 7.0 and later.  You will need to
install these libraries to be able to work with \texttt{tomsrtbt}.  It
is convenient to install them from Red Hat 6.2.


\begin{enumerate}
\item NFS mount the ftp directory from CSAlinux:
  \begin{alltt}
$ sudo mount CSAlinux:/var/ftp/pub /mnt
  \end{alltt}%$

\item Change to the Red Hat 6.2 RPM directory:
  \begin{alltt}
$ cd /mnt/redhat-6.2/RedHat/RPMS
  \end{alltt}%$

\item Install the \texttt{libc5} libraries:
  \begin{alltt}
$ sudo rpm -Uhv ld.so-1.9.5-13.i386.rpm libc-5.3.12-31.i386.rpm
  \end{alltt}%$
  Use the \key{Tab} key to complete the filenames rather than typing
  all the numbers in manually.

\item Change to your home directory.

\item Extract the contents of the file
  \texttt{tomsrtbt-1.7.218.tar.gz} with the command
  \begin{alltt}
$ tar xvzf /mnt/tomsrtbt/tomsrtbt-1.7.218.tar.gz
  \end{alltt}%$
  Again, use filename completion.

\item Unmount the network file system from CSAlinux:
  \begin{alltt}
$ sudo umount /mnt
  \end{alltt}%$

\item Install \texttt{tomsrtbt} on your floppy disk by changing into
  the directory \texttt{$\sim$/tomsrtbt-1.7.218} and typing
  \begin{alltt}
$ sudo ./install.s
  \end{alltt}%$

\item If you do not see the message ``Succeeded!'' after a few minutes
  of disk activity, your floppy disk has some defects; since it needs
  to be formatted with a high capacity, the floppy disk needs to be in
  new condition.  Use a new floppy disk.

\item Boot a computer with this floppy disk.

\item Log in as root.

\item Change to the directory \texttt{/proc} and examine the content
  of the files \texttt{cpuinfo}, \texttt{meminfo},
  \texttt{interrupts}, \texttt{pci}.  Can you imagine any uses for
  these files?

\item List the partition information on your computer.

\end{enumerate}

\subsection{The shell script \texttt{report}}
\label{sec:report}

\begin{enumerate}
\item Download the shell script \texttt{report} from
  \url{http://CSAlinux.tycm.vtc.edu.hk/ossi/lab/tomsrtbt/report} (from
  the subject home page), and save it to your $\sim$\texttt{/bin}
  directory (create $\sim$\texttt{/bin} if it doesn't exist).

\item Make it executable (you should know how!), then execute it to
  see what it does.

\item Take a few minutes to look at the files that have been made in
  the directory \texttt{/tmp/reports}.  What could these files be used
  for?
\end{enumerate}


\subsection{Rebuilding \texttt{tomsrtbt} to create a trouble shooting tool}
\label{sec:rebulding-tomsrtbt}

\begin{enumerate}
\item Open the file \texttt{tomsrtbt.FAQ} so that you can easily refer
  to it while working in this section.

\item Unpack the contents of \texttt{tomsrtbt} onto your hard disk by
  executing\\
  \texttt{sudo ./unpack.s~tomsrtbt.raw}
  
\item Copy the shell script \texttt{report} to the directory
  \texttt{tomsrtbt-1.7.218.unpacked/2/usr/bin}

\item Rebuild a new disk image containing \texttt{report} by
  executing \texttt{sudo 2/usr/doc/buildit.s}

\item A new package will be formed in your current directory.  Change
  into the new directory (which has a name like
  \texttt{\textit{xxxx}.tycm.vtc.edu.hk-tomsrtbt-1.7.219}), and
  rewrite your \texttt{tomsrtbt} disk by executing
  \texttt{./install.s} there.

\item Boot a computer with this disk, and execute the report program
  there.

\item Examine the files created there.

\item See if you can devise a way of:
  \begin{enumerate}
  \item putting these files into a second \acro{FAT} formatted floppy
    disk

  \item putting them onto the \texttt{tomsrtbt} disk itself.  You will
    need to delete some files from your \texttt{2} directory and
    rebuild the disk image to achieve this.
  \end{enumerate}
  
\end{enumerate}

\paragraph{Homework, due at the second laboratory session (within two
  weeks, i.e., week 24):}

Arrange this so that it is all automatic, so that you have a single
disk that you could give to a customer with instructions to boot the
computer with one floppy disk, then return the disk to you so that you
have evidence that you can analyse to solve problems, without a site
visit.

Here are a few ideas that you might like to consider:
\begin{thinItemise}
\item You will need to delete some commands from \texttt{tomsrtbt} to
  make room for the reports.  You could start by deleting the two
  editors and the man pages.  You may need a bit of trial and error to
  see what commands are required for this all to work.
  
\item The file \texttt{1/rc.custom.gz} is the startup script.  You
  will probably need to start \texttt{report} from this script; you
  will do most (all?) of the customisation here.

\item You could write the reports to the \RAM disk in \texttt{/tmp}

\item You could compress the reports so that they take less space
  using \texttt{tar} and \texttt{bzip2}

\item You will need to mount the floppy with a command
like
\begin{alltt}
# mount /dev/fd0u1722 /fl
\end{alltt}

\item Your script should shutdown the computer when it is finished.
\end{thinItemise}


\appendix
\section{Appendix: the shell script \texttt{report} and shell programming}
\label{sec:shell-programming}


\subsection{The shell script itself}
\label{sec:report-script}

The shell script \texttt{report} is shown here:

% {\footnotesize
% \listinginput{1}{report}
% }%
\lgrindfile{report.lg}

A warning: I completed this script recently, and have not tested it
extensively.  I need your help there!

\subsection{Features of shell programming used in this shell script }
\label{sec:report-description}

I have written comments in the script to describe what it is doing.  I
hope that I have used reasonably self-documenting code.  But I shall
point out a few things that aren't obvious.  Most questions can be
answered by reading the manual pages for \texttt{bash}, \texttt{test},
\texttt{awk} and \texttt{sed}.



\subsubsection{Control Structures in Shell programming}
\label{sec:control-structures}

\begin{enumerate}
\item The shell provides the following control structures:
  \begin{itemize}
  \item a \texttt{while} loop (see line 252).  The syntax is:
    \texttt{while \textit{condition}; do \textit{commands}; done}
    
  \item a \texttt{for} loop (see lines 19, 66, 74, 107, 161 and
    % 19, 65, 73, 106, 163
    316).  The syntax is: \texttt{for \textit{variable} in
      \textit{list\_of\_words}; do \textit{commands}; done} \ The
    variable is set to the value of each of the words in turn, and the
    commands in the loop body are executed once for each word.  This
    is a different syntax from \texttt{for} loops in C or Java\@.
    
  \item an \texttt{if} statement with syntax: \texttt{if
      \textit{condition}; then \textit{commands}; elif \textit{condition}
      \textit{commands};\ldots\ else \textit{commands} fi} \ I've used it
    very much here.  See lines 22, 39, 50, 68, 76, 93, 110, 121, 128,
    143, 150, 151, 167, 171, 175, 191, 195, 298 and 311.

    % 22, 39, 50, 67, 75, 87, 109, 123, 130,
    % 145, 152, 153, 69, 173, 177, 193, 197, 295, 300 and 313.
    
  \item a \texttt{case} statement that works rather like the
    \texttt{switch} statement in C\@.  The syntax is \texttt{case
      \textit{word} in \textit{pattern} | \textit{pattern})
      \textit{commands};; \ldots\ esac} \ See lines 254 to 287.
  \end{itemize}
\end{enumerate}

\subsubsection{Other Features of Shell Programming}

\paragraph{\texttt{awk} and \texttt{sed}:}

You may notice that I have used the program \texttt{awk} on lines 21,
24, 26, 94, 96, 207, 215, 226
%21, 24, 26, 88, 90, 209, 217, 228,
 and the program \texttt{sed} on line
280.  We have not (nor will we) cover these in detail.  \texttt{awk}
is a whole programming language in its own right, but here I have used
it mainly for splitting strings into their component parts, though I
have also used its regular expressions for translating strings.  As
with most other things in Linux, you can read about them in their
\texttt{man} pages.


\paragraph{Back Quotes and Command Substitution}

You have noticed that \emph{back quotes} (or \emph{back ticks}) have
some special property when you installed the Secure Shell agent.  They
are used here on lines 19, 21, 24, 25, 28, 66, 107, 246, 249, 280
and 316.  The effect of back quotes is called \emph{command
  substitution}; you can search for this phrase in the \texttt{bash}
manual page.  In the example \texttt{`command`}, the shell performs
the expansion by executing \texttt{command} and replacing
\texttt{`command`} with the standard output of \texttt{command}, with
any trailing newlines deleted.  Functions can only return a number.
To get the effect of returning a string, we can have the function
print the string to standard output, then put the function call in
back quotes, as in lines 107, 249 and 316.

\paragraph{Here documents}

The \texttt{usage()} function uses a \emph{here document}, where all
the text between \texttt{<<EOF} and \texttt{EOF} are treated as if
they were double quoted, and are given as input to the \texttt{cat}
command (in this example).


\paragraph{Some other miscellaneous features of shell programming}

\begin{itemize}
\item The \texttt{\&\&} logical AND operator will execute the right
  command if the left command is true (successful).

\item When a command is successful, it returns the value 0, which is
  considered as \texttt{true}.
  
\item in the \texttt{while} and \texttt{if} statements, the
  \textit{\texttt{condition}} can be a command, or can be a
  \texttt{test} command.  Try \texttt{man test} for more information.
  
\item Programs and functions have parameters \texttt{\$1},
  \texttt{\$2}, \texttt{\$3},\ldots \texttt{\$9} \ The number of
  parameters is held in \texttt{\$\#}.  The name of the program is
  stored in \texttt{\$0}.
  
\item Signals and traps.  Signals are exceptions sent from one process
  to another.  The \texttt{trap} command on line 307
  ``\texttt{catches}'' signals and calls (in this case) the function
  \texttt{clean\_up()}.
  
\item Assignments to shell variables cannot have spaces around the
  assignment operator `\texttt{=}'.
  
\item Notice that I have used redirection and pipelines extensively
  here.  This shell script is typical in that it combines the use of
  many tools to create a new tool.
\end{itemize}


\paragraph{Debugging}

Debugging shell scripts is quite easy; you can execute the script with
\texttt{sh~-x~$\sim$/bin/report}.  Try it.  The script has an option
\texttt{-d} which has the same effect.

\end{document}
