Getting Started


Nice, I suggest to pull this out to a separate thread and convert the post to wiki.


With the Debian QuickStart Installation one also has to contend with the following installation errors::

ERROR : invalid locale name: “en_US.utf8”
Resolve: dpkg-reconfigure locales

Set “en_US.UTF-8 UTF-8” as default

Error : tftpd-hpa.service failed: Control process exit…s=66
Resolve: sudo vi /etc/default/tftpd-hpa


sudo service tftpd-hpa restart

Error : Unable to connect to PostgreSQL server! (:5432)
Resolve: sudo vi /etc/postgresql/9.6/main/postgresql.conf

add server’s public IP address to the end of the setting listen_addresses (separate multiple entries by commas); uncomment the line if it is commented out (e.g. with ‘#’)

sudo service postgresql restart

With CentOS, it’s just been a much smoother installation (especially if contemplating Katello).


As one of the maintainers of the installer I feel like I should jump in here. I’m certainly aware that the installer has a lot of options and can be difficult to navigate. Are you aware of foreman-installer --scenario katello --interactive?

We have options for those. Any time you need to edit answers file manually it’s a good indication of a bug/failure on the installers side. For every plugin we should have --enable-foreman-plugin-<plugin>, --enable-foreman-cli-plugin-<plugin> and --foreman-proxy-plugin-<plugin> options. For the default org and location we have --foreman-initial-[organization|location]. There’s also --foreman-[username|password] which will be renamed to --foreman-initial-[username|password] in 1.21 to better indicate it’s only done while seeding. If you later rerun it, it won’t touch the username/password.

It should be possible to do this all in a single run. There should be no need for multiple runs.

This should be autogenerated based on the system hostname.

This should be done out of the box. They are generated randomly but they read the same cache.

You’re totally right. We should fix this oversight. Care to send a PR to


It could make a lot of sense to include this in our installer. I haven’t played with this myself, but could manage this file on Debian(-based) distros. That said, we don’t expose the tftp settings as parameters so then you’d need to edit custom-hiera.yaml which is also not a very good workflow.

I thought we should use sockets by default. We also test this in our nightly builds so this surprises me. Did you change the postgresql hostname Foreman connects to from localhost to $fqdn?


It’s a copy of my current notes.

In all regards, I’m more than willing to post it to a Wiki and continue fleshing it out as we progress. Also adding other common areas of interest for newcomers.

Question would just be, at what (wiki) URL ?


Sorry, can’t recall. At the time I followed the Quickstart ( for Debian 9 (Stretch) on a text based minimal (debian-9.6.0-amd64-netinst.iso) installation to the letter.

… being more concerned over and that does not support IPv6 …


This be the way forward :


@ekohl, yes I started with the interactive option, but it only seemed to provide options for choosing plugins. I had hoped it would follow a question and answer process in order to determine settings for DNS, DHCP, TFTP, etc, but it didn’t. As I’m learning more about the capabilities of Foreman, I can see that there are so many potential deployment scenarios that this Q&A approach could be difficult for anything more than simple deployments or lab style setups.

I chose to edit the answer file, so that it would be easier for me to script a repeatable installation process.

If this is the case, could you please share how? It seems as though the oauth credentials need to be provided in order for Foreman to correctly control these services, yet the credentials are not generated until one run of the installer has been completed. I’m sure the answer will be really obvious, once you point it out, but at the moment it eludes me.

This is the part of the single pass install that currently has me stumped.


@mason, please bear with me for a moment.

At present I’m specifically looking into enabling/configuring DHCP (ISC) and DNS (BIND). I’m only excluding TFTP as it’s already showing as an “Active feature” under Infrastructure > Smart Proxies - “” host.

I understand that I only need to edit:

  • /etc/foreman-proxy/settings.d/dhcp.yml <- changing :enabled: false -> enabled: https
  • /etc/foreman-proxy/settings.d/dns.yml <- changing :enabled: false -> enabled: https

The only pre-requisite to these config changes is to install BIND & ISC_DHCP

#yum install -y bind isc-dhcp-server

Yet after a foreman-proxy restart, Foreman’s logs will state:

ERROR Disabling all modules in the group [‘dns_nsupdate’, ‘dns’] due to a failure in one of them: File at ‘/etc/rndc.key’ defined in ‘dns_key’ parameter doesn’t exist or is unreadable
ERROR Disabling all modules in the group [‘dhcp_isc’, ‘dhcp’] due to a failure in one of them: File at ‘/etc/dhcp/dhcpd.conf’ defined in ‘config’ parameter doesn’t exist or is unreadable

Understandable as neither files exist.

Presently I’m not sure if “foreman_proxy_plugin_dhcp_infoblox” and “foreman_proxy_plugin_dns_infoblox” even has to be configured with the “foreman-installer”, though it is.

Am I on course or just drifting away … ?


Is the ‘foreman-installer’ script to be run as root or is sudo’ing sufficient ?

(Already anticipating slap to rear of head)


@Peek, the installer will install and configure ISC DHCP and BIND, if you tell it to. You don’t need to install them separately. The process that you outlined in your earlier post should work.

@ekohl has said that this can all be done in a single pass of the installer, but as mentioned in my previous post, I don’t know how to do that yet. I think he’s away at FOSDEM, so I’m not sure when he’ll be able to reply back to us. It would be great if I could supply all the arguments that I need for a single pass of the installer.

I’ve been writing a script to install Katello and Foreman and to do all the initial setup of creating products, importing GPG keys, syncing repos, etc. I can share that with you once I have it to the point where I have a basic but functional Foreman/Katello setup.


Reason I’m asking is because “foreman-installer -scenario katello -i” will only provide the following “DHCP” and “DNS” options :

  1. [✓] Configure foreman_proxy_plugin_dhcp_infoblox
  2. [✓] Configure foreman_proxy_plugin_dns_infoblox

and even with them selected and following the steps I listed a moment ago, still leaves me with an incomplete config/setup as mentioned.

Which is why I’m pondering whether this is the point at which you’d start editing the /etc/foreman-installer/scenario.d/katello-answers.yaml file before re-running the foreman-installer ?


Infoblox is a third-party commercial product, you would choose these options if you were in an existing environment that currently used an Infoblox appliance for managing DHCP and DNS. I get the impression that you’re trying to setup an environment from scratch and you want to use ISC DHCP and BIND (this is what I’m doing too).

Yes, that was my experience as well. The installer’s interactive flag only seems to allow you to select plugins, it doesn’t help you setup DHCP, DNS, etc.

No, to have foreman-installer setup DHCP and DNS, you need to pass options to the installer. As mentioned before, the interactive installer doesn’t ask you any questions relating to configuring DNS, DHCP, etc. Note that in the command below, I am specifying that the installer be run in interactive mode (so that you can choose the plugins you want), but I’m explicitly telling it to setup TFTP, DHCP and DNS.

foreman-installer --interactive --scenario katello


Thanks a million. That’s another landmine cleared up.


… though the installer isn’t happy ( IPv6 addresses specified with or without […], using FQDNs or even IPv4 ) result in:

Welcome to the Katello installer!

This wizard will gather all required information. You can change any parameter
to your needs.

Ready to start? (y/n)
You must enter a valid

Ready to start? (y/n)
You must enter a valid

Ready to start? (y/n)
You must enter a valid

Ready to start? (y/n)
Please enter “yes” or “no”.

Ready to start? (y/n)

How stupid am I ? Cause I’ve been at it for an afternoon and simply can’t get it to run :confounded:


Sorry @Peek I didn’t actually carefully look over my last post. I had copied and pasted from an earlier post of yours, just because you had specified all the IPs that were specific to your environment. I just tried running that command on my own test machine and it didn’t work due to a number of formatting issues. Here is a command that I know works, because I just ran it:

foreman-installer --interactive --scenario katello \
--enable-foreman-proxy \
--foreman-proxy-tftp=true \
--foreman-proxy-tftp-servername= \
--foreman-proxy-dhcp=true \
--foreman-proxy-dhcp-interface=eth0 \
--foreman-proxy-dhcp-gateway= \
--foreman-proxy-dhcp-nameservers="" \
--foreman-proxy-dns=true \
--foreman-proxy-dns-interface=eth0 \ \ \
--foreman-proxy-dns-forwarders= \


My 2c’s here:

I think the biggest issue is that our users need to figure out those long installer commands themselves. We do have a (currently broken) foreman setup which somehow guides users and Installation Scenarios section but it’s probably not enough.

I vote for expanding the Installation Scenarios here - please describe your setup, maybe draw a diagram of your infrastructure and then provide the working installer command:

If this is missing in Katello docs we should probably do link from there to Foreman manual. This is fuzzy…


@mason, I second your query to @ekohl. The confusion is not only around syntax errors. For eg:

8 hours ago, I started “anew” on the installer.

foreman-installer -i --scenario katello -–foreman-proxy-dhcp=true --foreman-proxy-dns=true” completed successfully and reflected the DHCP & DNS features as being active on the proxy (visible via web interface -> Infrastructure > Smart Proxies -> localhost) !

Naturally I did do a quick dance around my chair. :star_struck: But this was only the start. :thinking:

I then started applying config changes one-by-one, adding only a single option after every successful foreman-installer run, validating the config change with “foreman-installer --help | less

IPv6 addresses (with or without […]) is definitely not accepted by the foreman-installer which I believe only caters for IPv4 in the DHCP proxy. With FQDN’s being accepted, I’m hoping for a manual DHCP6 configuration workaround a bit later…

… with the DNS proxy though, the foreman-installer happily accepts IPv6 addresses i.e.


though being reflected as [“2001:4860:4860::8888”] when being validated. Yet now I ponder the reasoning for the quotes (") within the brackets ([…]) than being on the outside as one would’ve expected with IPv6 ? :face_with_raised_eyebrow:

Marching on, the “installer initialization string” at this point thus being :

**foreman-installer -i --scenario katello **
**–foreman-proxy-dhcp=true **
**–foreman-proxy-dhcp-interface=ens160 **
**– **
**– **
**–foreman-proxy-dns=true **
**–foreman-proxy-dns-interface=ens160 **
**– **
**–foreman-proxy-dns-forwarders=2001:4860:4860::8888 **

Yet … the moment I started to add TFTP options, the DHCP proxy started to fail with

Couldn’t enable ‘dhcp_isc’: Invalid IP Address

and within


" Disabling all modules in the group [‘dhcp_isc’, ‘dhcp’] due to a failure in one of them: Invalid IP Address"

The host is still dual stacked (IPv4 & IPv6) and resolves correctly to the hosts’s IPv4 address… changing the FQDN to the IPv4 address, doesn’t resolved the issue …

and /etc/hosts has all references to and ::1 removed.

** For clarity, once “foreman-installer -i --scenario katello -–foreman-proxy-dhcp=true --foreman-proxy-dns=true” completed successfully, a single option was tacked on per installer run, until the noted error was experienced.

The DHCP config being:

--foreman-proxy-dhcp          Enable DHCP feature (current: true)
--foreman-proxy-dhcp-additional-interfaces  Additional DHCP listen interfaces (in addition to dhcp_interface). Note: as opposed to dhcp_interface
                              additional subnets using `dhcp::pool` and related resource types (provided by the theforeman/puppet-dhcp
--foreman-proxy-dhcp-config   DHCP config file path (current: "/etc/dhcp/dhcpd.conf")
--foreman-proxy-dhcp-gateway  DHCP pool gateway (current: "")
--foreman-proxy-dhcp-interface  DHCP listen interface (current: "ens160")
--foreman-proxy-dhcp-key-name  DHCP key name (current: UNDEF)
--foreman-proxy-dhcp-key-secret  DHCP password (current: UNDEF)
--foreman-proxy-dhcp-leases   DHCP leases file (current: "/var/lib/dhcpd/dhcpd.leases")
--foreman-proxy-dhcp-listen-on  DHCP proxy to listen on https, http, or both (current: "https")
--foreman-proxy-dhcp-managed  DHCP is managed by Foreman proxy (current: true)
--foreman-proxy-dhcp-nameservers  DHCP nameservers, comma-separated (current: "")
--foreman-proxy-dhcp-netmask  DHCP server netmask value, defaults otherwise to value based on IP of dhcp_interface (current: UNDEF)
--foreman-proxy-dhcp-network  DHCP server network value, defaults otherwise to value based on IP of dhcp_interface (current: UNDEF)
--foreman-proxy-dhcp-node-type  DHCP node type (current: "standalone")
--foreman-proxy-dhcp-omapi-port  DHCP server OMAPI port (current: 7911)
--foreman-proxy-dhcp-option-domain  DHCP use the dhcpd config option domain-name (current: [""])
--foreman-proxy-dhcp-peer-address  The other DHCP servers address (current: UNDEF)
--foreman-proxy-dhcp-provider  DHCP provider (current: "isc")
--foreman-proxy-dhcp-pxefilename  DHCP "filename" value, defaults otherwise to pxelinux.0 (current: "pxelinux.0")
--foreman-proxy-dhcp-pxeserver  DHCP "next-server" value, defaults otherwise to IP of dhcp_interface (current: UNDEF)
--foreman-proxy-dhcp-range    Space-separated DHCP pool range (current: UNDEF)
--foreman-proxy-dhcp-search-domains  DHCP search domains option (current: UNDEF)
--foreman-proxy-dhcp-server   Address of DHCP server to manage (current: "")
--foreman-proxy-dhcp-subnets  Subnets list to restrict DHCP management to (current: [])

Then I tacked on “–foreman-proxy-dhcp-server=” and life is all funky again :partying_face:

The “installer initialization string” now mutating to:

**foreman-installer -i --scenario katello **
**–enable-foreman-proxy **
**–foreman-proxy-dhcp=true **
**–foreman-proxy-dhcp-server= **
**–foreman-proxy-dhcp-interface=ens160 **
**–foreman-proxy-dhcp-gateway= **
**–foreman-proxy-dhcp-nameservers= **
**–foreman-proxy-dns=true **
**–foreman-proxy-dns-interface=ens160 **
**– **
**–foreman-proxy-dns-forwarders=2001:4860:4860::8888 **

… and so the journey continues, still eluding the once off single installer line … and acquiring clarity.

RFC: Make Foreman easy to deploy and maintain

@lzap, I believe @mason and @jmrice6640 would agree that we’re after a very simple, yet fully functional commissioning environment, from scratch. The most basic initial components being:

  1. puppet
  2. dhcp (isc)
  3. dns (bind)
  4. tftp ( I’d LOVE to have this scratched in favor of HTTP Boot)

all on a bed of succulent IPv6. :drooling_face:

Topped off with a quick auto deploying of a CentOS & Debian image.
Config change, i.e. NTP
Remote execution example
and the destruction of the images to conclude the life-cycle thereof.

We just never expected it to be this … frustratingly interesting …


Originally we only hoped to HTTP Boot diskless stations. Only, Intel has other ideas …