More detail about required paths for test suite. Add caution to never change anything...

diff --git a/Installation.md b/Installation.md
index 1a578f87b4d30e01157cb45189e12b466aee5285..c93d9fcc911150a2a775e7ae1084ab67689d78cf 100644 (file)
--- a/Installation.md
+++ b/Installation.md
@@ -26,24 +26,24 @@ This will create the repo checkout in the directory *~/code/*.
 9. Edit the *build-farm.conf* file and adjust to your local configuration.  The only options that absolutely require changing are the _animal_ and _secret_ configuration settings.  Your machine's sysname alias must be assigned to *animal* and the secret key assigned to *secret*.  The rest of the default build configuration should work to build a basic Exim configuration with no added features/capabilities and it will run the test suite.
 10. Whatever directory is set as the *build_root* must exist before anything will run.  If you didn't change it, this will be all that's needed:
 `mkdir $HOME/buildfarm`
 9. Edit the *build-farm.conf* file and adjust to your local configuration.  The only options that absolutely require changing are the _animal_ and _secret_ configuration settings.  Your machine's sysname alias must be assigned to *animal* and the secret key assigned to *secret*.  The rest of the default build configuration should work to build a basic Exim configuration with no added features/capabilities and it will run the test suite.
 10. Whatever directory is set as the *build_root* must exist before anything will run.  If you didn't change it, this will be all that's needed:
 `mkdir $HOME/buildfarm`

+**CAUTION:** Do not ever change anything in the git repo under that is created in *$HOME/buildfarm/HEAD/exim/*. It will cause the build to fail in the Git-Checkout phase.

 11. Directory permissions must be lax enough for the **exim** user running the test suite to be able to access the files that user farm has checked out.  One recommendation that we know works is to make the **farm** user's home directory be both group and world readable and group and world searchable:
 `chmod og+rx $HOME`.  Additionally, every subdirectory between */* and *$HOME/buildfarm* should have this permissive access.  One thing that these tighter permissions will break, for example, is test 0005, because the sudo'd exim process in the test suite will be unable to read that test config file.
 12. Make sure that your umask is 0022: `umask 0022`.  This also will need to be set in any script you call the run_build.pl script.
 13. Test the configure process by running `./run_build.pl --test --verbose=2 --only-steps=configure`. If there are errors, you'll need to correct them until the process succeeds (ends with OK).  You can repeat this as many times as necessary because test mode does not store the status of the git repo or the status of each stage of the build.
 14. Test the build process by running `./run_build.pl --test --verbose=2 --only-steps=configure,make`. If there are build errors, make adjustments, install additional packages, etc, and repeat the test.
 11. Directory permissions must be lax enough for the **exim** user running the test suite to be able to access the files that user farm has checked out.  One recommendation that we know works is to make the **farm** user's home directory be both group and world readable and group and world searchable:
 `chmod og+rx $HOME`.  Additionally, every subdirectory between */* and *$HOME/buildfarm* should have this permissive access.  One thing that these tighter permissions will break, for example, is test 0005, because the sudo'd exim process in the test suite will be unable to read that test config file.
 12. Make sure that your umask is 0022: `umask 0022`.  This also will need to be set in any script you call the run_build.pl script.
 13. Test the configure process by running `./run_build.pl --test --verbose=2 --only-steps=configure`. If there are errors, you'll need to correct them until the process succeeds (ends with OK).  You can repeat this as many times as necessary because test mode does not store the status of the git repo or the status of each stage of the build.
 14. Test the build process by running `./run_build.pl --test --verbose=2 --only-steps=configure,make`. If there are build errors, make adjustments, install additional packages, etc, and repeat the test.

-15. Test the test suite by running `./run_build.pl --test --verbose=2 --only-steps=configure,make,test --override range_num_tests='1 2'`.  If there are build errors when building the test suite, or runtime errors trying to run the test suite, you may need to install additional packages (you shouldn't though).
+15. Test the test suite by running `./run_build.pl --test --verbose=2 --only-steps=configure,make,test --override range_num_tests='1 2'`.  There will be one error on a standard system: the Exim test suite uses ifconfig to obtain the IP address, and this binary is frequently not in a regular user's path.  Temporarily fix this by running `export PATH="/usr/sbin:/sbin:$PATH"` to prepend the probably directories where that command is located to your regular user path. (Instructions on how to do this automatically in the cron job are below).  If there are build errors when building the test suite, or runtime errors trying to run the test suite, you may need to install additional packages (you shouldn't though).

 16. If you enabled the documentation building process in the *build-farm.conf*, then you can try to build it with `./run_build.pl --test --verbose=2 --only-steps=configure,make-doc`.  For documentation generation to succeed, it will require extra packages to be installed to support xml, xslt, pdf, and a few other things. Please see the comments on the [Building Documentation](https://github.com/mrballcb/exim-build-farm-client/wiki/BuildingDocs) page.
 17. If you can get past each of these steps, then your build farm system meets the minimum requirements.
 18. The official process can be kicked off by running `/home/farm/code/run_cron.sh --run-all`.  This will run the default build configuration, keep track of the git repository status, and upload the build results to the server.
 16. If you enabled the documentation building process in the *build-farm.conf*, then you can try to build it with `./run_build.pl --test --verbose=2 --only-steps=configure,make-doc`.  For documentation generation to succeed, it will require extra packages to be installed to support xml, xslt, pdf, and a few other things. Please see the comments on the [Building Documentation](https://github.com/mrballcb/exim-build-farm-client/wiki/BuildingDocs) page.
 17. If you can get past each of these steps, then your build farm system meets the minimum requirements.
 18. The official process can be kicked off by running `/home/farm/code/run_cron.sh --run-all`.  This will run the default build configuration, keep track of the git repository status, and upload the build results to the server.

-19. Once that command runs with no complaints, add it to the **farm** user crontab.  You can run it at whatever frequency you choose, I suggest 1 hour.  If a previous instantiation is still running, the script will detect the lockfile and exit so as not to step on each other.
-20. I had a problem running the *run_cron.sh* script in that cron gives a highly sanitized path to the script when it runs it.  I made a second wrapper script to call the first one so I could put path elements in that were needed:
+19. Once that command runs with no complaints, add it to the **farm** user crontab.  You can run it at whatever frequency you choose, I suggest 1 hour.  If a previous instantiation is still running, the script will detect the lockfile and exit so as not to step on each other.  I had a problem running the *run_cron.sh* script in that cron gives a highly sanitized path to the script when it runs it.  I made a second script to call the first one so I could insert path elements in that were needed:

 <pre><code>$ more /home/farm/bin/build_farm.sh
 #!/bin/bash
 export PATH="/usr/local/bin:/sbin:/usr/sbin:$PATH"
 $HOME/code/run_cron.sh --run-all $@
 </code></pre>
 Then I make my cronjob call: `6 * * * * $HOME/bin/build_farm.sh` .... but ...
 <pre><code>$ more /home/farm/bin/build_farm.sh
 #!/bin/bash
 export PATH="/usr/local/bin:/sbin:/usr/sbin:$PATH"
 $HOME/code/run_cron.sh --run-all $@
 </code></pre>
 Then I make my cronjob call: `6 * * * * $HOME/bin/build_farm.sh` .... but ...

-21. My cronjob ran great for a couple weeks.  Then another problem popped up running the cron job in that the test portion suddenly started failing with an odd error:
+20. My cronjob ran great for a couple weeks.  Then another problem popped up running the cron job in that the test portion suddenly started failing with an odd error:

 <pre><code>** runtest error: Failed to open /dev/tty: No such device or address</code></pre>
 This is not a sudo issue.  This is happening because the cron daemon does not give a tty to the cronjob that it starts.  (How the heck did it ever work?)  The runtest script needs a tty in normal operation.  To fix this, I used an old trick of ssh'ing to localhost with the *-tt* option to **force** allocation of a local tty when starting the *build_farm.sh* script.  To do this, you need to configure the **farm** user to use key-based authentication with its own key.  Assuming you have not generated an ssh key yet:
 <pre><code># Press Enter to use defaults for all questions in
 <pre><code>** runtest error: Failed to open /dev/tty: No such device or address</code></pre>
 This is not a sudo issue.  This is happening because the cron daemon does not give a tty to the cronjob that it starts.  (How the heck did it ever work?)  The runtest script needs a tty in normal operation.  To fix this, I used an old trick of ssh'ing to localhost with the *-tt* option to **force** allocation of a local tty when starting the *build_farm.sh* script.  To do this, you need to configure the **farm** user to use key-based authentication with its own key.  Assuming you have not generated an ssh key yet:
 <pre><code># Press Enter to use defaults for all questions in