xmlfile

TERC Puppet XMLFile Library

Project URL RSS Feed Report issues

Module Stats

11,607 downloads

10,388 latest version

3.8 quality score

Version information

released Jun 9th 2014

This module has been deprecated by its author since Jun 22nd 2021.

The author has suggested puppet-xmlfile as its replacement.

Start using this module

Installation method

Add this module to your Puppetfile:

mod 'terc-xmlfile', '0.4.0'

Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add terc-xmlfile

Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install terc-xmlfile --version 0.4.0

Tags: library, provider, type, xml

Documentation

terc/xmlfile — version 0.4.0 Jun 9th 2014

TERC Puppet XMLFile Library

####Table of Contents

Overview - What is the xmlfile module?
Why - Reasoning for developing this module
Implementation - Summary of the under the hood implementation of the module
Limitations - Known issues and limitations of the implementation
Release Notes - Notes on the most recent updates to the module

Overview

The xmlfile module provides the xmlfile and xmlfile_modification types as well as associated providers.

No manifest code is included. This is pretty much pure ruby code for inclusion in other modules.

Why?

While working on a variety of modules I kept running into cases where what I really, really wanted to do was apply augeas lenses to a template, but this was problematic. There were several options for this, none of them good. I could use a file concat library, and sandwich augeas and file types that way, have a triggered exec resource, etc. No matter what we're basically managing multiple resources when what we really want is just one and some changes. Just no good way to really deal with it.

My first thought was "my kingdom for an array!" which led to the databucket library, the idea behind which was to do collection of resource parameters at catalog compilition into an array, and then use that within the template. This idea, while cool, is, unfortunately, probably not reliable enough for production or capable of being made reliable enough for production. So collecting and using virtual or exported data and directly referencing it(IE: in a template) is out.

Hence this, which sidetracks the whole issue.

Implementation

By extending the Puppet file type and using some providers we can merge templated or sourced content and modifications and have puppet treat this content as if it had been passed directly.

The changes themeselves are applied via the XmlLens class, which fakes being augeas. This is accomplished via the standard ruby REXML library. Upshot of this is we can add in things like sorting.

Limitations

I don't have a complete windows puppet kit and so while we extend the windows provider and it should work, I can't actually test it.

Property fix is called via send on object creation. This may create a security issue when a file is first created if the properties are not correctly set, although this should get fixed on the next puppet run.

The augeas implementation is incomplete and not exact. If you notice an issue or unexpected behavior, please open an issue.

REXML has some limitations and quirks of its own. <, &, and > if by themselves will be automagically converted to < & and > and there's no way to turn this off. Content is otherwise put into raw mode and so it shouldn't be messed with.

Release Notes

v0.4.0

Fixes issues introduced by deprecation of :parent and type inheritance.

v0.3.1

Regular expressions tweaked for 1.8.7 compatibility.

v0.3.0

Augeas add command equivalent added.
Aliases for ins and rm(insert and remove, respectively) created so it functions more like the augeas type.
Sort behavior fixed so that matching for child node name sorting is triggered on both null and 0-length string args.
Conditional behavior for numerals improved. If both parts of evaluate are pure digits, does a to_i on both before comparison.
Raw processing now on by default.
Updated this document.

v0.2.0

Automatic importation of docs for inherited attributes.

Types in this module release

xmlfile_modification

Apply a change or an array of changes constrained by conditionals, to a specified xml file using syntax similar to the augeas XML lens. Changes are applied in memory during content generation when the catalog is applied.

Requires:

- REXML

Sample usage with strings:

    xmlfile_modification{"test" :
      file    => "/etc/activemq/activemq.conf.xml",
      changes => "set /beans/broker/transportConnectors/transportConnector[last()+1]/#attribute/name \"test\"",
      onlyif  => "match /beans/broker/transportConnectors/transportConnector[#attribute/name == \"test\"] size < 1",
    }

Sample usage with arrays:

    xmlfile_modification{"test" :
      file    => "/etc/activemq/activemq.conf.xml",
      changes => [ "set /beans/broker/transportConnectors/transportConnector[last()+1]/#attribute/name \"tests\"", 
                   "set /beans/broker/transportConnectors/transportConnector[last()+1]/#attribute/value \"tests\""],
      onlyif =>  [ "match /beans/broker/transportConnectors/transportConnector[#attribute/name == \"tests\"] size < 1" ],
    }

Parameters
changes	Changes which should be applied to the file. Can be a command or an array of commands. Augeas-esque syntax. Paths are XPATHs. Attributes are matched via #attribute/<ATTR>, or assumed to be text. Evaluations must be bracketed. Commands: - add <PATH> : Adds an empty node at path(always creates last element, rest as needed) - set <PATH> "<VALUE>" : Sets the path to value, creates it if it does not exist - rm <PATH> : Removes the path. - remove : Alias for rm. - clear <PATH> : Clears the specied path. Does not create it. - ins <PATH> (before\|after) <LOCATION> : Constructs an element(or elements) using path and inserts it before or after the path specified by location - insert : Alias for ins - sort <PATH> (<VALUE>\|text) : Sorts all elements that match path by the attribute specified in value(or by element name if nothing specified). Path Functions: - last() : During initial parsing, substitutes for the index of the last item that matches the expression.
file	The path of the xmlfile to work with.
name	Name to use to identify this modification. Must be unique.
onlyif	Constrains application of changes via conditionals. Augeas-esque syntax. `Paths are XPATHs. Attributes are matched via #attribute/<ATTR>, or assumed to be text. Evaluations must be bracketed. Commands: - match <PATH> size (==\|!=\|<\|>\|<=\|>=) <VALUE> : Evaluates if a match for the given path meets the conditions specified. - get <PATH> (==\|!=\|<\|>\|<=\|>=) <VALUE> : Checks if a path matches a given value under the conditions specified Path Functions: - last() : During initial parsing, substitutes for the index of the last item that matches the expression.`

xmlfile

Previously an extension of the base file resource type, now a partial reimplementation with the deprecation of :parent. An xmlfile behaves like a file in all ways except that its content can be modified via xmlfile_modification resources.

This enables the mixing of exported or virtual content and
templated or static content, while managing the end-result as a single resource.

The following attributes are inherited from the file type:
- ctime (read-only)
- group
- mode
- path
- mtime (read-only)
- owner
- selinux_ignore_defaults
- selrange
- selrole
- seltype
- seluser
- source
See: http://docs.puppetlabs.com/references/latest/type.html#file for details

Parameters
ensure
format	The desired formatting of the content after being passed through the REXML lens.
path	The path to the file to manage. Must be fully qualified. On Windows, the path should include the drive letter and should use `/` as the separator character (rather than `\\`).
provider
raw	The desired formatting of the content after being passed through the REXML lens.

Properties
content	The desired contents of a file, as a string. This attribute is mutually exclusive with `source`.

Providers
xmlfile_posix
xmlfile_windows

Copyright 2013, Nick Cammorato

Permission is given to redistribute and/or modify this software under any of the following licenses:

1)  Apache 2.0 License

	Licensed under the Apache License, Version 2.0 (the "License");
	you may not use this file except in compliance with the License.
	You may obtain a copy of the License at
		
	  http://www.apache.org/licenses/LICENSE-2.0
		
	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.

Modules

Discover

Contribute

Puppet

Premium features

Downloads

Resources

About Forge

Getting Started

xmlfile

Version information

This module has been deprecated by its author since Jun 22nd 2021.

Start using this module

Documentation

TERC Puppet XMLFile Library

Overview

Why?

Implementation

Limitations

Release Notes

v0.4.0

v0.3.1

v0.3.0

v0.2.0

Types in this module release

xmlfile_modification

xmlfile

terc-xmlfile changelog

Summary

Enhancements

Bugfixes

2013-11-07 Release 0.3.1

Summary

Enhancements

Bugfixes

2013-10-10 Release 0.3.0

Summary

Features

Enhancements

Bugfixes

2013-10-07 Release 0.2.0

Summary

Detailed Changes

2013-10-07 Release 0.1.0

Summary