Managing iLO's with puppet
==========================

Instead of writing your own code to manage iLO interfaces with python-hpilo,
you can also use a puppet module. While it doesn't support all the
functionality of hpilo.py or hpilo_cli, it does support the more common
functions (and more can be added, just file a bug!)

It uses the same network device management framework as the existing tools to
manage cisco devices or F5 loadbalancers, so you don't need to install anything
special on each server and no custom iLO code is required.

To install the module, simply copy the `modules/ilo` directory into your puppet
tree and follow the instructions below to create recipes.

Caching
-------
This module heavily caches iLO output, most for more than a day. The cache is
invalidated if settings etc. are changed by this module, but if you make
changes manually, you will need to remove the cached information yourself. The
cache lives in the per-device directories in `/var/lib/puppet/devices`.

Because of this caching, applying the catalog takes only a few seconds instead
of several minutes if there are no changes.

Configuring puppet
------------------
Please configure `hpilo_cli` itself first, including username and password. The
puppet `ilo` module works by using this tool. Once it works for you, you can
configure puppet.

To use `puppet device` to manage iLO's, the iLO devices must be added to
`/etc/puppet/device.conf` on the server you want to use for managing them.

The ilo module can be used in two ways: to manage an iLO remotely via HTTP and
to manage an iLO locally via hpilo. With the former you can manage many iLOs
from a single server, with the latter you can manage iLOs that are not (yet)
reachable via the network.

To manage the local iLO, you can put something this in `device.conf`::

    [server-001.ilo.kaarsemaker.net]
    type ilo
    url ilo://server-001.ilo.kaarsemaker.net

Note that the scheme is `ilo://`, this makes the ilo module use `hpilo_cli` in
local mode. You must still use the ilo's FQDN though, as each node needs a
unique name in puppet.

I personally prefer the network method and configuring DHCP properly so all
iLOs are reachable via the network. For this, `device.conf` looks like the
following::

    [server-001.ilo.kaarsemaker.net]
    type ilo
    url http://server-001.ilo.kaarsemaker.net

    [server-002.ilo.kaarsemaker.net]
    type ilo
    url http://server-002.ilo.kaarsemaker.net

    [server-003.ilo.kaarsemaker.net]
    type ilo
    url http://server-003.ilo.kaarsemaker.net

In fact, it's generated by the iLO module. The management server has this
snippet in its recipe:

.. code-block:: puppet

    class s_mgmt {
        class{'ilo::proxy':
            devices => [
                "http://server-001.ilo.kaarsemaker.net",
                "http://server-002.ilo.kaarsemaker.net",
                "http://server-003.ilo.kaarsemaker.net",
            ]
        }
    }

Of course you can generate this however you want.

Facts
-----
Several facts are available for use in your recipes.

* `$devicetype` is set to `ilo`
* `$users` contains a list of all users
* `$firmware_version`, `$firmware_date`, `$management_processor`, and
  `$license_type` are set to what `get_fw_version` provides
* `$oa_encl`, `$oa_rack`, `$oa_ipaddress`, `$oa_location`, `$oa_macaddress`,
  `$oa_uidstatus` and `$oa_system_health` are set to what `get_oa_info`
  provides. These are only available on blade servers.

Managing users
--------------
You can use this module to create, modify and delete users. Unfortunately the
normal `user` type cannot be used, so there's a special `ilo_user` type.

.. code-block:: puppet

    ilo_user {
        "Administrator":
            admin_priv => true;
        "jack":
            ensure => absent;
        "dkaarsemaker":
            ensure => present,
            display_name => 'Dennis Kaarsemaker',
            password_atcreate => 'P4ssw0rd',
            reset_server_priv => false;
        "linda":
            ensure => present,
            password => 'hunter2'
            display_name => 'Linda',
            admin_priv => false,
            config_ilo_priv => false,
            reset_server_priv => true;
    }

These example users show the features of this type:

* You can create (`ensure => present`) or delete (`ensure => absent`) users.
* You can manage their permissions (`admin_priv`, `config_ilo_priv`,
  `remote_cons_priv`, `reset_server_priv` and `virtual_media_priv`)
* You can manage display names and passwords. Note that for users you want this
  module to create, these are mandatory attributes.

Because user passwords cannot be queried, this module has to check the password
every time by doing an http request. This can take a while and goes against the
aggressive caching. To prevent these constant checks, you can use the
`password_atcreate` parameter instead of the `password` parameter. This is only
used when creating the user and is not checked subsequently. Should you want to
change the user's password you can temporarily also add a `password` parameter
until all devices have been updated.

Managing iLO firmware
---------------------
The `ilo_firmware` type can be used to manage firmware on your iLOs.

.. code-block:: puppet

    ilo_firmware { $management_processor:
        ensure => "latest",
        http_proxy => "http://webproxy:3128"
    }

The name of the resource must be the same as the iLO type, you can use a fact
to make sure it is. `ensure` accepts any version number or the string `latest`,
which will always upgrade to the latest version.

`http_proxy` is optional and can be used to specify a proxy via which to
download the firmware config and firmware.

Managing settings
-----------------
This module also includes an `ilo_settings` type. This is a relatively thin
wrapper around functions like `mod_global_settings` to configure any of the
following settings: global (`mod_global_settings`), network
(`mod_network_settings`), snmp (`mod_snmp_im_settings`) and directory
authentication (`mod_dir_config`). As with the above types, an example should
make it clear.

.. code-block:: puppet

    ilo_settings {
        "global":
            settings => {
                "remote_console_port" => 23,
                "enforce_aes"         => true,
                "f8_login_required"   => true,
            };
        "network":
            settings => {
                "prim_dns_server"     => "10.42.1.31",
                "sec_dns_server"      => "10.42.1.32",
            };
    }

As you can see, the individual settings are not all parameters, instead there's
only one settings parameter. Any setting that is not managed by puppet is
completely left alone by this module, there are no defaults.

Installing licenses
-------------------
The last functionality (for now) is the `ilo_license` type, which you can use
to install licenses.

.. code-block:: puppet

    ilo_license { "iLO 3 Advanced":
        key => "12345-67890-ABCDE-FGHIJ-KLMNO"
    }

Note that the spelling of the license name is important. If it's not exactly
the same as what `get_all_licenses` shows, puppet will try to activate the
license again and again.

Complete example
----------------
And here's a complete example to put all the above together.

`/etc/puppet/device.conf`::

    [server-001.ilo.kaarsemaker.net]
    type ilo
    url http://server-001.ilo.kaarsemaker.net

`/etc/puppet/manifests/nodes.pp`

.. code-block:: puppet

    node 'management-server.kaarsemaker.net' {
        include s_mgmt
    }

    node 'server-001.ilo.kaarsemaker.net' {
        include s_ilo
    }

    node 'server-002.ilo.kaarsemaker.net' {
        include s_ilo
    }

    node 'server-003.ilo.kaarsemaker.net' {
        include s_ilo
    }

`/etc/puppet/modules/s_mgmt/manifests/init.pp`

.. code-block:: puppet

    class s_mgmt {
        class{'ilo::proxy':
            devices => [
                "http://server-001.ilo.kaarsemaker.net",
                "http://server-002.ilo.kaarsemaker.net",
                "http://server-003.ilo.kaarsemaker.net",
            ]
        }
    }

`/etc/puppet/modules/s_ilo/manifests/init.pp`

.. code-block:: puppet

    class s_ilo {

        # Always upgrade firmware
        ilo_firmware { $management_processor:
            ensure => "latest",
            http_proxy => "http://webproxy:3128"
        }

        # We only have iLO 3's in this setup, so one license will do
        ilo_license { "iLO 3 Advanced":
            key => "12345-67890-ABCDE-FGHIJ-KLMNO"
        }

        ilo_settings {
            "global":
                settings => {
                    "remote_console_port" => 23,
                    "enforce_aes"         => true,
                    "f8_login_required"   => true,
                };
            "network":
                settings => {
                    "prim_dns_server"     => "10.42.1.31",
                    "sec_dns_server"      => "10.42.1.32",
                };
        }

        ilo_user {
            "Administrator":
                # Temporary until changed everywhere
                password => 'P4ssw0rd',
            "dennis":
                ensure => present,
                display_name => 'Dennis Kaarsemaker',
                password_atcreate => 'MyPass!',
                reset_server_priv => false;
            # Remove leavers
            ["jack", "bob"]:
                ensure => absent,
        }
    }