Common issues
=============
The iLO interfaces aren't the most helpful when they detect something
erroneous. These are some common issues and their solutions. If you have a
problem that is not listed here, or solved with these instructions, please file
an issue at https://github.com/seveas/python-hpilo. When reporting bugs, please
do send the problematic XML responses. These XML responses can be saved as
follows::

  hpilo_cli example-server.int.kaarsemaker.net --save-response=for_bugreport.txt get_fw_version

Of course you should replace the hostname  with the actual iLO hostname or ip,
and get_fw_version with the actual call you want to make. If you use the python
API instead of the CLI tool, set the :data:`save_response` attribute on the ilo
object::

  ilo = hpilo.Ilo(hostname, login, password)
  ilo.save_response = "for_bugreport.txt"
  ilo.get_fw_version()

These debug responses may contain sensitive information, which you should edit
out. Please use a hexeditor to do so, or at least make sure your editor does
not try to normalize newlines. It is important that the number of characters in
the file stays the same, so don't add or remove data, just overwrite sensitive
values with XXXX.

As github issues do not support attachments, feel fee to mail this debug
information to `the author`_ directly.

.. _`the author`: mailto:dennis@kaarsemaker.net

Update your firmware
--------------------
This might sound like a lame cop-out, but quite a few versions of especially
iLO 3 firmware contain serious bugs that cause the XML interface to misbehave.
Upgrading the firmware of an iLO is simple and does not impact the host at all,
so it's always a good idea to start with a firmware update::

  hpilo_cli example-server.int.kaarsemaker.net update_rib_firmware version=latest

Syntax error: Line #0
---------------------
Occasionally you might see this error at the end of a traceback::

  hpilo.IloError: Error communicating with iLO: Syntax error: Line #0: syntax error near "" in the line: ""

This generaly means that you are trying to call a method that is not supported
for your device or the firmware version you use. Get this information with::

  hpilo_cli example-server.int.kaarsemaker.net get_fw_version

And consult the HP sample XML files to find out whether this call is supported
for your device and firmware version. If it is, please file a bug report.

Note that for some calls (most notable mod_global_settings), support for the
call may be there, but not all arguments are supported.

ElementTree.ParseError
-----------------------
Occasionally you might see either of these errors at the end of a traceback::

  cElementTree.ParseError: not well-formed (invalid token): line 301, column 23
  xml.etree.ElementTree.ParseError: not well-formed (invalid token): line 301, column 23

This means that the iLO interface is spewing invalid XML back at you.
python-hpilo has some workarounds in place for common cases, and most other
cases have been fixed in newer firmware versions. Please update your firmware
version and try again. If the problem persists, please file a bug report.

Unexpected errors after a login failure
---------------------------------------
If you use the wrong credentials to access the XML interface, some iLO's get
into some weird state. Call :func:`get_fw_version` a few times to clear this
state and recover.

Failure to update iLO3 firmware
-------------------------------
The early firmware versions of iLO3 had quite a few issues. To update from
anything older than 1.28 to 1.50 or newer, you need to update in two steps:
first update to 1.28 and then update to a later version::

  hpilo_cli example-server.int.kaarsemaker.net update_rib_firmware version=1.28
  hpilo_cli example-server.int.kaarsemaker.net update_rib_firmware version=latest
