Local Requests XML

Deprecated

This page documents the deprecated XML format. New deployments should use the YAML format.

Etch is based on a client/server model where the server normally generates a client's configuration based on a configuration repository stored on the server and basic facts about the client supplied by the client from the Facter library. In other words the configuration is centrally managed and the client has little control over what configuration it receives. However, sometimes you want to allow individual clients to request additions or modifications to the standard configuration. In particular we use this to allow software packages from our package management tool to request things like accounts, kernel settings and NFS mounts. For example, the mysql package requests a "mysql" user and group. It is up to your configuration script or template to do something with the request, so by default requests will be ignored. You can choose to implement the request only under certain circumstances. For example, we only implement account requests for accounts that have already been defined, and only obey requests for human accounts on non-production machines.

Client Side

On the client side requests are created by dropping an XML file into /var/etch/requests/[path to file]. For example, if you want a request associated with /etc/passwd you'd create a file like /var/etch/requests/etc/passwd/myrequest. The filename within the directory doesn't matter, use whatever helps you keep them straight. Our packaging tool creates requests using filenames based on the package that included the request, for example. Anytime the etch client submits a request for that file it will include the XML from all files in the directory.

The XML must be wrapped in a <request></request> element. Any valid text or XML can be included in that element. At the simple end of things a request for an account might look like <request>mysql</request>.

Server Side

Your script or template will receive any requests from the client in the @local_requests variable. The requests will be bundled within a <requests></requests> element. I.e. if the client just had the one mysql request above you'll receive a string like "<requests><request>mysql</request></requests>". The XML is not parsed for you in order to save some CPU cycles if your script/template doesn't use it. The REXML XML library is included with Ruby and can be used to parse the XML. The etch server itself uses the LibXML library, so you can also assume it is installed and available. Etch uses LibXML for greater performance and for some features like DTD validation. Neither are likely to be concerns when parsing these small pieces of XML, so feel free to use whichever library you prefer. The REXML tutorial might help you get started.

Here's an example for processing requests for users that could go in your etc/passwd/passwd.script, assuming you've defined a method named add_user which reads from your source(s) of accounts and adds the right data to @contents:

if @local_requests && !@local_requests.empty?
  require 'rexml/document'
  requests_xml = REXML::Document.new(@local_requests)
  requests_xml.elements.each('/requests/request') do |request_xml|
    if request_xml.text
      request_xml.text.split("\n").each do |user|
        if user && !user.empty?
          user.strip!
          add_user(user)
        end
      end
    end
  end
end