Forge Home

xml_fragment

A native Puppet module that manages XML documents using REXML.

70,412 downloads

1,315 latest version

5.0 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 1.0.5 (latest)
  • 1.0.4
  • 1.0.3
  • 1.0.2
  • 1.0.1
  • 1.0.0
released Oct 1st 2023
This version is compatible with:
  • Puppet Enterprise 2023.8.x, 2023.7.x, 2023.6.x, 2023.5.x, 2023.4.x, 2023.3.x, 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x, 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x, 2018.1.x, 2017.3.x, 2017.2.x, 2017.1.x, 2016.5.x, 2016.4.x
  • Puppet >= 3.0.0 < 9.0.0
  • RedHat, Centos, OracleLinux, Scientific, SLES, Debian, Ubuntu, Solaris, AIX,

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'ianoberst-xml_fragment', '1.0.5'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add ianoberst-xml_fragment
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install ianoberst-xml_fragment --version 1.0.5

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download

Documentation

ianoberst/xml_fragment — version 1.0.5 Oct 1st 2023

xml_fragment

Overview

The xml_fragment manages xml fragments within xml documents.

Module Description

The xml_fragment module allows you to manage targeted XML fragments within XML files using xpath.

Requirements

The xmlfragment module is driven from a ruby-based provider, so it _should work on most operating systems. To this date it has only been tested on Windows Server 2012 with Puppet Agent 3.8.0, though it will likely work on others. Please let me know your success/failure with various operating system. It does require REXML to be installed.

Reference

Types

xml_fragment

Manages an XML fragment within an XML file.

  • ensure: Optional. Specifies whether the XML tag specified by the xpath parameter should be present or absent. Valid options: 'present' and 'absent'. Default: 'present'.

  • path: The path to the XML file.

  • xpath: The xpath for the xml tag to manage. The last tag in the xpath expression will be used as the name of the tag if it does not exist. Example: '/hosts/host[@ip="127.0.0.1"]' would cause the xml_fragment to manage the 'host' tag where the attribute 'id' was equal to localhost.

  • purge: Optional. Specifies if unmanaged children of the XML tag should be removed. Valid options: 'true' and 'false'. Default: 'false'.

  • content: Optional. A hash describing the contents and attributes of the XML tag. Valid keys: 'value' and 'attributes'. The 'value' entry should specify the value of the tag, or be excluded if the tag is empty or will contain children. The 'attributes' entry should be a hash describing the attributes on the tag, where each key/pair in the hash is the attribute/value pair on the tag.

The default behavior of the xml_fragment resource is to create or update the tag indicated by the xpath parameter. If the tag does not exist it will be created. If it exists the value and attributes of the tag will be updated if needed. Note that if the tag indicated does not have a valid parent tag in the XML document, an error will be thrown. In this XML file, an xpath of '/foo/bar/value' would result in an error because 'bar' does not exist, but '/foo/bar' is valid.

<foo>
</foo>

Setting ensure to absent will remove any tags that match the xpath parameter, and their children. Purge will also cause the children of any tags matching the xpath parameter to be removed, but only if they are not managed by an xml_fragment resource.

Examples

Basic Creation

Create a host entry in the "hosts.xml" file for localhost. If the host does not exist, the entry will be created. Note that the "Hosts" tag must already be present.

xml_fragment { "Localhost Host":
    path        => "C:/hosts.xml",
    ensure      => 'present',
    xpath       => "/hosts/host[@ip='127.0.0.1']",
    content     => {
        value   => "Localhost",
        attributes => {
            "ip" => "127.0.0.1"
        }
    }
}

Purge

Given the following XML file template:

<hosts>
    <host ip="0.0.0.0">Example</host>
</hosts>

These xml_fragments will cause our own host to be added to the file and the example host to be removed:

xml_fragment { "Hosts":
    path        => "C:/hosts.xml",
    ensure      => 'present',
    xpath       => "/hosts",
    purge       => true
}

xml_fragment { "Localhost Host":
    path        => "C:/hosts.xml",
    ensure      => 'present',
    xpath       => "/hosts/host[@ip='127.0.0.1']",
    content     => {
        value   => "Localhost",
        attributes {
            "ip" => "127.0.0.1"
        }
    }
}