root/README @ 8717fb5f6353d199eb0d5dc240d1fd27657e995c

-*- outline -*-

* PXE Manager

The idea is to build an automaton to control when to boot from the
local drives and when to boot from the network.

The systems can be used to run automated tests. You can also use this
system only to provision on demand systems or backup your partitions
using partimage or anything you want to do with an automated PXE
system...

The systems must be configured to always boot over PXE.

** Install

- edit the database and PXE config in the settings.py according to
  your local setup.

- you need python-django installed.

- run ./manage.py syncdb to create the needed sql tables.

- create the PXE profiles in pxelinux.cfg/profiles/ ending in
  .prof. The local.prof is mandatory and must point to a local boot
  config. The user running the scripts must have the right to write in
  pxelinux.cfg. I usually create a group and put it under control of
  the files under pxelinux.cfg.

- export these 2 environment variables:
  DJANGO_SETTINGS_MODULE=settings and PYTHONPATH=$PWD.

- run pxemngr syncbootnames to add the names of the PXE profiles in the
  database.

- add the systems that you want to control by this system like this:

pxemngr addsystem <name> <mac address> [<mac address 2>...]

- set which profile you want your system to PXE boot:

pxemngr nextboot <name> <profile name>

If you want to assign a default profile to all systems, use the
reserved system name 'default'.

- run ./manage.py runserver <ip addr>:<port> to have a web server
  waiting for requests to boot locally. You can also configure django
  to use apache instead of the little embedded server.

- then your PXE scripts must access the following web page
  http://<ipaddr>:<port>/localboot/ to request a local boot
  before rebooting else the PXE boot will continue to loop on the same
  install.

** Advanced

- in your auto-install scripts, you can access the current profile by
  accessing the following url: http://<ipaddr>:<port>/profile/

** Test system

*** Description

The test system allows to provide test scripts to running systems
declared in the PXE manager database.

The target system can request a test by using this url:
http://<ipaddr>:<port>/nexttest/

The tests are usually shell scripts that are built using Django
templating system. By convention, the tests are usinf a suffix of
.test. They are stored in the directory set in settings.py under the
TESTS_DIR variable. A wait.test must exist and will be sent by the
server to the target system when no test is available. This wait.test
must wait for some time and then exit to let the system send a new
test if needed or send back a new wait.test.

After the execution of a test script, the result is sent back to the
server using the following url: http://<ipaddr>:<port>/upload/<test id>/. I
usualy run the following curl command to upload the result:

curl --retry 0 -s -f -F "file=@$output" http://<ipaddr>:<port>/upload/<test id>/

These uploaded files are stored under the directory set by the
TEST_UPLOAD_DIR variable in settings.py.

The system uses a simple convention in these files to lookup
information. It parses the lines to store informations, warnings and
errors lines if they begin by 'I: ', 'W: ' and 'E: '. The system also
tries to find the version of the system by looking for a line starting
by 'V: '.

You can then navigate on web pages displaying these parsed
informations under: http://<ipaddr>:<port>/.

*** Control

To instruct the system about which tests are available, use the
following command:

pxemngr synctestnames

To assign a test to a target system, use the following command:

pxemngr nexttest <system name> <test name>

To display all the tests scheduled for a system, use:

pxemngr dpytest <system name>

*** Web navigation

By pointing your browser to http://<ipaddr>:<port>/, you can navigate
in the results of the test system.