Report Templates Guide

Report templates are ruby scripts executed on the orcharhino itself and able to extract, process, and present information from the orcharhino databases in a tabular form. They represent an easy way within orcharhino to generate customizable reports. This guide aims at giving some insight into writing and modifying report templates. For usage of already existing report templates refer to the report templates page.

orcharhino already contains a selection of generic report templates as found in the monitor menu:

List of report templates

This guide shows how to write a new template, which will return the number and kind of host-installable errata. Linux errata contain information to update and/or patch software. They can cover security updates, bugfixes, or new software features. For this purpose, every erratum contains a list of packages affected by the update. Keeping a watchful eye on errata is therefore always a good idea to keep your hosts up to date. In this context, orcharhino distinguishes between two types of errata, installable and available errata:

  • Available errata for a host are always determined with respect to the latest packages maintained by the orcharhino.

  • Available errata may differ from installable errata, as hosts are normally registered to a frozen state of packages, so called content views.

  • The final template both shows the number of applicable and installable errata for each host.

Report Template for Applicable Errata

The first step on this way of is going to be a report template, which returns a short summary of all errata affected hosts. It will focus on available errata first.

The new report is generated by selecting the corresponding button on the Monitor > Report Templates page. Then, the template name and some generic information like the template category, i.e. a collection of templates with similar purpose, are added as well as the template code:

<%#
name: Applicable Errata
description: A basic report template for gathering all applicable errata.
model: ReportTemplate
-%>
<%# Loop over all hosts-%>
<%-  load_hosts(includes: [:operatingsystem, :applicable_errata, :lifecycle_environment]).each_record do |host| -%>
<%-    @errata = 0 -%>
<%-    if host.operatingsystem.family != "Windows" -%>
<%-      # Loop over all errata for the single host -%>
<%-      host_applicable_errata_filtered(host).each do |erratum| -%>
<%-        @errata = @errata+1 -%>
<%-      end -%>
<%-      report_row(
          'Host': host.name,
          'OS': host.operatingsystem,
          'Environment': host.lifecycle_environment,
          'Total': @errata,
         ) -%>
<%-    end -%>
<%-  end -%>
<%= report_render -%>

The first part of the code from line 1 to 5 is a commentary block, indicated by the brackets <%# …​ -%>. This block contains metadata like the template name and its description. The first executable Ruby code starts in line 7, marked by the brackets <%- -%>. The macro load_hosts in this line loads the host data contained in the orcharhino. Which information it exactly processes is determined by the includes keyword. In this case, these are the operating system, the lifecycle environment, and the applicable errata. In typical ruby-style, the following each_record do |host| iterates over all returned hosts entries saved in host. Windows hosts are explicitly excluded from the host list in line 9. The applicable errata for each Linux host are then processed via the host_applicable_errata_filtered() macro in line 11. The exact number of applicable errata is then summed up in the counter @errata and passed to the report_row() macro in line 14. This macro adds a corresponding host line to the report table, which is then rendered via <%= report\_render -%> at the end of the template.

After defining the template can now be executed by hitting the Generate button below the template in the web GUI. The appearing interface requires some additional information like the execution time and date, the file format (csv, json, yaml, html), and mail forwarding, if desired. The template is now executed, returns a table in the csv-format, and uses no mail forwarding.

The final report looks like this:

Host OS Environment Total

centos7.example.com

CentOS 7

Testing

32

oracle7.example.com

OracleLinux 7

Testing

163

debian10.example.com

Debian 10

Testing

23

Every row of the table represents one host with some basic information and the total available errata count. This short and easy to read table now serves as a basis for further enhancement of the template.

Errata Types

Extend the template with two additional features: First, allow users to restrict the report to a list of selected hosts instead of all hosts and second, display the kind of errata in the report. The modified template looks as follows:

<%#
name: Applicable Errata
description: A basic report template for gathering all applicable errata.
template_inputs:
- name: Hosts filter
  required: false
  input_type: user
  advanced: false
  value_type: plain
  hidden_value: false
model: ReportTemplate
-%>
<%# Loop over all or input list of hosts -%>
<%-  load_hosts(search: input('Hosts filter'), includes: [:operatingsystem, :applicable_errata, :lifecycle_environment]).each_record do |host| -%>
<%-    if host.operatingsystem.family != "Windows" -%>
<%-      @errata = 0 -%>
<%-      @bugfix = 0 -%>
<%-      @misc_err = 0 -%>
<%-      @enhancement = 0 -%>
<%-      @security = 0 -%>
<%-      # Loop over all errata for the single host -%>
<%-      host_applicable_errata_filtered(host).each do |erratum| -%>
<%-        @errata = @errata+1 -%>
<%-        if erratum[:errata_type]=="security" -%>
<%-          @security=@security+1 -%>
<%-        elsif erratum[:errata_type]=="bugfix" -%>
<%-          @bugfix=@bugfix+1 -%>
<%-        elsif erratum[:errata_type]=="recommended" -%>
<%-          @bugfix=@bugfix+1 -%>
<%-        elsif erratum[:errata_type]=="enhancement" -%>
<%-          @enhancement=@enhancement+1 -%>
<%-        elsif erratum[:errata_type]=="optional" -%>
<%-          @enhancement=@enhancement+1 -%>
<%-        else -%>
<%-          @misc_err=@misc_err+1 -%>
<%-        end -%>
<%-      end -%>
<%-      report_row(
          'Host': host.name,
          'OS': host.operatingsystem,
          'Environment': host.lifecycle_environment,
          #Library specific errata
          'Security': @security,
          'Bugfix': @bugfix,
          'Enhance': @enhancement,
          'Misc': @misc_err,
          'Total': @errata,
         ) -%>
<%-    end -%>
<%-  end -%>
<%= report_render -%>

load_hosts in line 14 is now extended by search: input('Hosts filter'). The macro input allows users to add input during execution of the template. In this case, it limits the search to a list of hosts. In order to let this macro take effect, we have to add the input name Hosts filter to the Inputs tab of the template:

Adding a filter to the inputs tab

Additionally, the template now distinguishes between security, bugfix, and enhancement errata. The corresponding counters are defined in line 16 to 20 and count for the erratum kind in line 22 to 36 via an if-clause.

The user generating the report now has one additional field Hosts filter available:

Use user defined input for a report template

The output for the centos7.example.com host looks as follows:

Host OS Environment Security Bugfix Enhance Misc Total

centos7.example.com

CentOS 7

Testing

9

20

2

1

32

Nine of the applicable errata are in fact security errata, a definite warning sign to patch the host as soon as possible.

Installable vs Available Errata

We still do not know if these errata are also installable on the host and how many packages are indeed affected by available errata. We therefore modify the template one final time:

<%#
name: Applicable Errata
description: A basic report template for gathering all applicable errata.
template_inputs:
- name: Hosts filter
  required: false
  input_type: user
  advanced: false
  value_type: plain
  hidden_value: false
model: ReportTemplate
-%>
<%# Loop over all or input list of hosts -%>
<%-  load_hosts(search: input('Hosts filter'), includes: [:operatingsystem, :applicable_errata, :lifecycle_environment]).each_record do |host| -%>
<%-    if host.operatingsystem.family != "Windows" -%>
<%-      @errata = 0 -%>
<%-      @bugfix = 0 -%>
<%-      @misc_err = 0 -%>
<%-      @enhancement = 0 -%>
<%-      @security = 0 -%>
<%-      #Content View Errata%>
<%-      @cv_misc_err = host.content_facet_attributes.errata_counts[:total] -%>
<%-      @cv_misc_err = @cv_misc_err - host.content_facet_attributes.errata_counts[:enhancement] -%>
<%-      @cv_misc_err = @cv_misc_err - host.content_facet_attributes.errata_counts[:bugfix] -%>
<%-      @cv_misc_err = @cv_misc_err - host.content_facet_attributes.errata_counts[:security] -%>
<%-      # Loop over all errata for the single host -%>
<%-      host_applicable_errata_filtered(host).each do |erratum| -%>
<%-          @errata = @errata+1 -%>
<%-          if erratum[:errata_type]=="security" -%>
<%-             @security=@security+1 -%>
<%-          elsif erratum[:errata_type]=="bugfix" -%>
<%-             @bugfix=@bugfix+1 -%>
<%-          elsif erratum[:errata_type]=="recommended" -%>
<%-             @bugfix=@bugfix+1 -%>
<%-          elsif erratum[:errata_type]=="enhancement" -%>
<%-             @enhancement=@enhancement+1 -%>
<%-          elsif erratum[:errata_type]=="optional" -%>
<%-             @enhancement=@enhancement+1 -%>
<%-          else -%>
<%-             @misc_err=@misc_err+1 -%>
<%-         end -%>
<%-      end -%>
<%-      report_row(
          'Host': host.name,
          'OS': host.operatingsystem,
          'Environment': host.lifecycle_environment,
          #Library specific errata
          'Security': @security,
          'Bugfix': @bugfix,
          'Enhance': @enhancement,
          'Misc': @misc_err,
          'Total': @errata,
          #Content View specific errata
          'CV Security': host.content_facet_attributes.errata_counts[:security],
          'CV Bugfix': host.content_facet_attributes.errata_counts[:bugfix],
          'CV Enhance': host.content_facet_attributes.errata_counts[:enhancement],
          'CV Misc': @cv_misc_err,
          'CV Total': host.content_facet_attributes.errata_counts[:total],
          'Packages': host.content_facet_attributes.applicable_deb_count+host.content_facet_attributes.applicable_rpm_count,
         ) -%>
<%-    end -%>
<%-  end -%>
<%= report_render -%>

We now access the number of installable errata via the host attribute host.content_facet_attributes.errata_counts. Additionally, we save the number of errata belonging to none of the predefined categories in the counter @cv_misc_err. We then return the installable errata counts from line 55 to 59. The report for host centos7.example.com then looks like this:

Host OS Environment Security Bugfix Enhance Misc Total

centos7.example.com

CentOS 7

Testing

9

20

2

1

32

Host CV Security CV Bugfix CV Enhance CV Misc CV Total Packages

centos7.example.com

6

13

1

0

20

242

We now see that the number of installable errata is smaller than the number of available errata. Ensure to update the corresponding content view as soon as possible.

Report templates allow access to all functionalities of the orcharhino API and orcharhino intern variables. For further information, we recommend looking into the Foreman API at https://orcharhino.example.com/apidoc/v2/, Foreman community templates, and the macro help list.