Once you have foreman installed you are likely to want to use foreman in a manifest that you have written. Fortunately there is an API wrapper that has been written for use in your code. An example of this is below and we will cover this further towards the end of this article.

You may receive the following error

You will notice in the above output the error is Unknown function: ‘foreman’ . This happens because the foreman query module isn’t loaded. The quick and easy way to fix this is to link the foreman module into the module path.

Start by identifying the modulepath locations on the server

In the above output we can see the directory /opt/puppetlabs/puppet/modules is an option. So we need to get the foreman module into this directory, we can do this using a symbolic link like so

Rerun your agent and it should work just fine

Lets just take a moment to look at the foreman query function and how we can call it. The first step is to head over to the module itself, To give you a clue on this your looking for a file by the name of foreman.rb and now it can be found at /opt/puppetlabs/puppet/modules/foreman/lib/puppet/parser/functions.

Lets take a look at the beginning of this file to see what inputs it might accept/require.

From the above code in the file we can see there are a number of inputs these are item, search, per_page, foreman_url, foreman_user, foreman_pass, filter_result, and timeout.

The main ones you will want to set are foreman _user and foreman_pass, by default the query assumes your url is on the localhost, if it isn’t you will need to set that too. If we take a look back at the module from the start you will see our module has some inputs of its own.

In the above sample you can see that there are 2 strings the module accepts in (with default values). I would recommend that with settings like these that you set them in foreman not on the module, this allows your code to be usable without you having to sanitise your code prior to exporting it.

You can set the values in foreman by clicking Configure > Classes > <Name of your module> > Smart Class Parameter

For foreman_pass and foreman_user you will need to click override and then provide a value. You will also want to create an account just for this with more limited permissions, require then using the administrator.


Failure to correctly set your user/pass combination will show the following output, apiuser is the default value in the sample code.

Hopefully this run down will save you a couple of hours working out how to use the wrapper.