
********************************************************************************
* WARNING!                                                                     *
*                                                                              *
* This tool runs as the root user and installs packages on its own!            *
* Therefore it can do pretty much harm if it gets out of control.              *
* We have tried to make the script reasonably safe but there is no warranty.   *
* Use it at YOUR OWN RISK only, and only if you know what you are doing.       *
*                                                                              *
* PLEASE DO NOT RUN IT ON A MACHINE THAT HOLDS IMPORTANT DATA, OR PROVIDES     *
* IMPORTANT SERVICES!                                                          *
********************************************************************************

---=< Prerequisites >=---

For running the script, you need to install the following tools:

* Perl
* rpm (should be always present for a LSB compliant distro)
* alien, if package manager on your distro isn't RPM.
* lsb_release (should be always present for a LSB compliant distro)
* standard Unix tools (grep, diff, etc.)
* Xvfb, some fonts (for X11 tests)
* Some locales are required for libstdc++ test. That may turn into a problem for
  your distro. If that's the case, maybe the following solution for Debian 
  will help you:
  http://people.debian.org/~taggart/lsb/tests.html

All packages containing appropriate LSB tests will be downloaded automatically.

---=< Usage >=---

Some of the tests can temporarily put heavy load on the system (CPU, memory,
and disk), and various testing user accounts, servers and system config files
are created during the testing, causing temporary security holes.
All the changes should be reversed automatically after the testing is finished.

To start working with this tool using web-UI, run the following script from the
installation directory (/opt/lsb/test/manager by default):
# ./bin/lsb-tef-start.sh [port]
It will launch a simple web-server, and then try to open the start page in 
a browser. The optional parameter 'port' allows to specify which port should be
used by the server. By default 8888 is taken.

Use the script ./bin/lsb-tef-stop.sh if you want to shutdown the server.

You can also work with the testkit via a command-line interface. Run
# ./lsb-autotest/lsb-autotest.pl --help
for a detailed list of options and their meanings.

---=< Troubleshooting >=---

* Some locales are required for libstdc++ test. That may turn into a problem for
  your distro. If that's the case, maybe the following solution for Debian 
  will help you:
  http://people.debian.org/~taggart/lsb/tests.html

* In the case when the autotest couldn't find fonts, there is a workaround.
  First, find the font directory (see the files /etc/X11/xorg.conf and
  /etc/X11/fs/config). Also you may try the command 'find / -name 75dpi' to find
  all 75dpi font directories. Choose the appropriate font directory and make
  sure that the following subdirectories are present: 'misc', '75dpi', '100dpi'.

  Autotest tries to find these subdirectories in the following locations:
  /usr/X11R6/lib/X11/fonts/
  /usr/share/fonts/X11/
  /usr/share/X11/fonts/
  /usr/share/fonts/

  Create symlinks to the found directories (misc, 75dpi, 100dpi) into one of the
  directories listed above so that autotest could find them next time.

* If you have no 100dpi fonts installed, you should install them using the tools
  provided by your distro.

Error: Couldn't recognize the host platform.
(You can identify your platform using the command 'uname -i'.)
If you believe that your platform is the one of the listed supported platforms,
but it's name wasn't recognized by the Test Execution Framework (TEF), please
first of all send the bugreport (see contacts below).
If you use the command-line tool, you can just specify the platform using
the -p parameter. E.g. './lsb-tef.pl -p ppc32' to state the platform is ppc32.
If you use webUI, there is no solution. You may try the command-line interface.

Error: Couldn't recognize package manager for this distro.
or Error: ... Unknown package manager ...
If you are sure that your package manager is RPM or dpkg with alien installed,
there is a method to state the correct package manager.
If you use the command-line tool, you can just specify the package manager using
the -pm option. E.g. './lsb-tef.pl -pm RPM' for RPM and './lsb-tef.pl -pm dpkg'
for dpkg.
If you use webUI, there is no solution. You may try the command-line interface.

Error: Couldn't find LSB loader (loader_name) for this platform (host_platform).
or Error: No LSB modules are available.
Most likely, you haven't installed special LSB modules for your distro.
You could install LSB modules using the tools provided by your distro. 
(Like 'apt-get install lsb' on Debian-based distros.)

Error: Couldn't find a required tool: '<some tool>'
This error message occurs when you haven't some tool, which TEF uses. You could
try to install this tool.

Error: Can't find lsb-autotest in <some_dir>.
'lsb_autotest' is a tool used by TEF to automatically run the tests. TEF tries
to find lsb_autotest at the specified location (usually at tef/autotest). 
Check that the file tef/autotest/lsb-autotest exists and has appropriate 
rights to be executed by root (TEF runs tests as root). If the file doesn't
exists, it is most likely that the TEF wasn't installed correctly, so you could
reinstall it.

Error: Could not open problem database <file_name>
'problem_db' is a file that contains information about some known problems.
Information in this file is used for the report creation. This file should be
located at tef/autotest-ext/problem_db. Check that this file exists 
and has appropriate privileges to be read by root (TEF works as root). 
If the file doesn't exists, it is most likely that the TEF wasn't installed 
correctly, so you could reinstall it.

Error: FTP init failed.
or Error: FTP login (anonymous) failed.
This occurs occasionally because of poor internet connection or high load 
of the FTP server. Try again some time later.
If you have all the test packages downloaded (all tests are available at 
the first column 'localhost' on the Configure page of webUI), you could chose
not to use internet, and the TEF will not connect to the FTP.

Error: Failed to execute: <command>
or Error: Couldn't open file '<file_name>' for writing.
or Error: Failed to copy: ...
This means that the TEF failed to fulfil some service operation. Your bugreport
with the log of console output attached will be truly appreciated.

If you can't find a suitable solution, you can write to <fsgteam@ispras.ru>.

---=< Bug reporting >=---

If you find a bug, or wish to advise a possible enhancement, please
send an e-mail to ISP RAS <fsgteam@ispras.ru>.

---=< Credits >=---

Copyright (C) 2007 The Linux Foundation.

This program has been developed by ISP RAS <fsgteam@ispras.ru> for LF with some
parts derived from lsb-autotest written by Jiri Dluhos <jdluhos@suse.cz>
Copyright (C) 2005-2007 SuSE Linux Products GmbH
