Getting Started

Support
16

That is precisely the kind of tidbit that would be very useful up front.
I am just exploring in a test environment, and learning as I go.
What tools are available, how they might be used, and how to get started…

Add an overview section to the documentation that highlights some of the more popular modules,
then a roadmap of the learning curve. This all seems to assume prior knowledge and skill sets.
I had actually used Puppet in a prior company, but didn’t set it up. But I didn’t know about Foreman.
I had planned to look into Katello later, once I had gotten more familiar with Foreman.

Glad to find out now that I should start over with Katello in mind, before I get too deep and can’t
add it in easily later. Are there any others that I might need to know about? :wink:

17

This brings up a few more questions, if I may …
Are you saying that it is best for me to start over? New box, rather than uninstall?

I think we might be interested in Puppet, Katello, DigitalOcean, Docker, OpenSCAP, Xen,
Remote Execution, Templates, Monitoring, and possibly others like Datacenter, Discovery, Setup, …

Is there a compatibility matrix somewhere so I know which versions to install with Foreman 1.20.1 ?

And is the sequence something like:

install katello
foreman-installer --scenario katello (options) …

What about all the other enable-forman-plugin-* modules?
All added on the same command line, or run the installer again separately?
Or once foreman is installed, added as separate module installs?

Sorry, but this just doesn’t jump out from the documentation.

1 Like
18

Hi @jmrice6640 ,

I have been struggling through similar issues to what you and @Peek have been reporting in this thread.

In an attempt to answer your question, I’ll share what I’ve done so far. My immediate goal is to bootstrap a Foreman/Katello controlled environment - ie starting with nothing but my laptop, a few bare metal hosts, a switch, a router and an Internet connection. I don’t have any other existing infrastructure, such as a DNS server that is serving a local domain, directory for authentication, etc.

Some of my confusion has been with sorting out the order of operations in order to successfully stand up Foreman and Katello. The thing that really threw me for a while was the apparent requirement for more than one run of the foreman-installer program, with different options each time. As far as I can tell, it’s not possible to specify all the options you want on the first run of the installer. The following is a summary of the process to bootstrap this configuration:

  • Install CentOS on a baremetal host

    • set the hostname and domain
    • add the IP and FQDN to /etc/hosts
    • disable the firewall for now (just for testing in my lab, not for production deployment)

  • Setup the necessary yum repos, install a couple prerequisite packages and then apply updates

  • yum -y install katello

  • edit the katello answer file to specify plugins to install and to set the default organization and location

  • foreman-installer --scenario katello

  • make note of the generated admin credentials

  • after the install finishes, you need to grab the oauth credentials that were generated during the install

    • grep oauth /etc/foreman/settings.yaml | grep consumer

  • then re-run the foreman-installer in order to configure DHCP, DNS and TFTP

    foreman-installer --scenario katello
    –enable-foreman-proxy
    –foreman-proxy-tftp=true
    –foreman-proxy-tftp-servername=192.168.50.20
    –foreman-proxy-dhcp=true
    –foreman-proxy-dhcp-interface=eth0
    –foreman-proxy-dhcp-gateway=192.168.50.1
    –foreman-proxy-dhcp-nameservers=“192.168.50.20”
    –foreman-proxy-dns=true
    –foreman-proxy-dns-interface=eth0
    –foreman-proxy-dns-zone=example.com
    –foreman-proxy-dns-reverse=50.168.192.in-addr.arpa
    –foreman-proxy-dns-forwarders=9.9.9.9
    –foreman-proxy-foreman-base-url=https://foreman.example.com
    –foreman-proxy-oauth-consumer-key=CHANGEME!
    –foreman-proxy-oauth-consumer-secret=CHANGEME!

At this point you should be able to point your laptop to the DNS server running on your new host, login to the web interface and start working through the process of configuring Foreman and Katello. If you prefer using the CLI, just make sure that you had selected the necessary CLI plugins when you were editing the katello answer file above.

The other caveats that I can share so far are:

  • Don’t use the setup plugin, it’s not compatible with foreman 1.20.1
  • Don’t try to sync the Puppet Forge repos, this process is broken in 1.20.1
  • Even though you should follow the Katello 3.10 install instructions… Don’t. The instructions will lead you to install an ancient version of Puppet. The list of repos I gave above is a mixture of the Foreman and Katello install instructions, which installs the latest 5.x version of Puppet along with the latest Katello and Foreman packages.

I hope this helps!

Mason

3 Likes
19

Thank you, Mason. That helps a lot. I think you have saved me days, and much grief.
At least I feel like I am beginning to ask more intelligent questions. There will be more …

20

Thank you Mason ! You’re a torch in a dark tunnel.

Some notes as I start the rebuild process:

  1. Default to CentOS for compatibility down the road. (… and to keep one’s sanity)
  2. Puppet Forge Repo does not support IPv4 at present.
  3. … more to follow soon

Jim, (@jmrice6640) would you be willing to share your installation notes as we progress ?

21

Here’s @mason 's notes, expanded as to how my latest setup is running:

Please do comment/advise on any (additional) headings that could assist in paving the way for newcomers.

Unfortunately I’m out-of-time today, being somehow stuck at adding DHCP, DNS and TFTP with the foreman-installer repetitively complaining about “ERROR: too many arguments” …

Min Requirements:

2x logical processsors
8GB RAM
50GB+ storage

1. Install CentOS

  • Create non-privileged “user”
  • Set the hostname “foreman” and domain “example.com”

Upon restart:

  • Allow “user” to sudo

usermod –a –G wheel “user”

  • add IP and FQDN for local name resolution

sudo vi /etc/hosts

    2001:db8::51f0 foreman.example.com foreman
  • Disable IPv4

sudo vi /etc/sysconfig/network-scripts/ifcfg-ens160

    BOOTPROTO=”dhcp”                    <- Uncomment for dual stack support
    IPV6_ADDR_GEN_MODE=”stable-privacy” <- Comment for MAC -> EUI64
  • Setup NTP

sudo yum install ntp
systemctl enable ntps
systemctl start ntpd
systemctl status ntpd

  • Firewall ports:

firewall-cmd –get active-zones
firewall-cmd --zone=public --add-port=22/tcp –permanent

    22          TCP        SSH
    53          TCP/UDP    DNS
    67,68       UDP        DHCP
    69          UDP        TFTP **
    80,443      TCP        HTTP / HTTPS           Foreman
    3000        TCP        WEB UI                 Foreman
    3306        TCP        MySQL DB
    5432        TCP        PostgreSQL DB
    5647        TCP        qrouterd               Katello
    5910-5930   TCP        VNC Consoles           Foreman
    8140        TCP        Puppet Master
    8443        TCP        Smart Proxy            Foreman
    9090        TCP        HTTPS – Smart Proxy    Katello

Firewall-cmd --reload

  • Optional : disable firewall (just for testing, not for production deployment)

systemctl status firewalld
systemctl disable firewalld
systemctl stop firewalld
systemctl status firewalld

  • Tools – Validation:

sudo yum –y install net-tools nmap

  • @host:

hostname –f
hostname –s
hostname -d
netstat -tulpan

  • @remote

nmap –v -6 foreman.example.com

2. Setup Repos:

sudo yum -y install https://fedorapeople.org/groups/katello/releases/yum/3.10/katello/el7/x86_64/katello-repos-latest.rpm
sudo yum -y install http://yum.theforeman.org/releases/1.20/el7/x86_64/foreman-release.rpm
sudo yum -y install https://yum.puppetlabs.com/puppet5/puppet5-release-el-7.noarch.rpm
** No IPv6 support @ dl.fedoraproject.org - Reverting to dual stack **
sudo yum -y install http://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm 
sudo yum -y install foreman-release-scl python2-django
sudo yum -y update

sudo yum -y install katello

3. Pre-install Config:

Katello:

Edit the katello answer file (/etc/foreman-installer/scenario.d/katello-answers.yaml)

Specify

  • default organization
  • default location
  • plugins to install <- ( ** What would be advisable for experimenting beginners **) ?

4. Installation: (Multiple runs of the foreman-installer, each with different options on each run, is currently a requirement / design)

sudo foreman-installer --scenario katello

  • Note generated admin credentials
  • Grab the oauth credentials generated

sudo grep oauth /etc/foreman/settings.yaml | grep consumer

Re-run the foreman-installer in order to configure DHCP, DNS and TFTP

sudo foreman-installer --scenario katello
–enable-foreman-proxy
–foreman-proxy-tftp=true
–foreman-proxy-tftp-servername=2001:db8::51f0
–foreman-proxy-dhcp=true
–foreman-proxy-dhcp-interface=ens160
–foreman-proxy-dhcp-gateway=2001:db8::1
–foreman-proxy-dhcp-nameservers=2001:db8::51f0
–foreman-proxy-dns=true
–foreman-proxy-dns-interface=ens160
–foreman-proxy-dns-zone=example.com
–foreman-proxy-dns-reverse=0.0.0.0.0.0.0.0.0.8.b.d.1.0.0.2.ip6.arpa.
–foreman-proxy-dns-forwarders=2001:4860:4860::8888
–foreman-proxy-foreman-base-url=https://foreman.example.com
–foreman-proxy-oauth-consumer-key=CHANGEME!
–foreman-proxy-oauth-consumer-secret=CHANGEME!

  • sudo foreman-installer –help will display each option’s current configuration at the end of the particular line

At this point you should be able to point your laptop to the DNS server running on your new host, login to the web interface and start working through the process of configuring Foreman and Katello. If you prefer using the CLI, just make sure that you had selected the necessary CLI plugins when you were editing the katello answer file above.

5. Configuring Foreman / Katello:

… in due course

  • Puppet Modules:

    Adding NTP example:

  • Host management:

    Unattended Host Provisioning:

Existing host discovery:

… what else to add in ?

Caveats:

  • Apparent requirement exist for more than one run of the foreman-installer program, with different options each time. Current understanding is that it’s not possible to specify all the options you might need on the first run of the installer.

  • Don’t use the setup plugin, it’s not compatible with foreman 1.20.1

  • Don’t try to sync the Puppet Forge repos, this process is broken in 1.20.1

  • Even though you should follow the Katello 3.10 install instructions… Don’t. The instructions will lead you to install an ancient version of Puppet. The list of repos I gave above is a mixture of the Foreman and Katello install instructions, which installs the latest 5.x version of Puppet along with the latest Katello and Foreman packages.

Credits:

@mason

22

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

23

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

TFTP_ADDRESS="[2001:db8:51f0]:69"

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).

24

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 https://github.com/theforeman/theforeman.org?

25

It could make a lot of sense to include this in our installer. I haven’t played with this myself, but https://github.com/theforeman/puppet-tftp 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?

26

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 ?

27

Sorry, can’t recall. At the time I followed the Quickstart (https://www.theforeman.org/manuals/1.20/index.html#2.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 dl.fedoraproject.org and forge.puppet.com that does not support IPv6 …

28

This be the way forward :

29

@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.

30

@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 - “foreman.domain.com” 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 … ?

31

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

(Already anticipating slap to rear of head)

32

@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.

33

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 ?

34

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
–enable-foreman-proxy
–foreman-proxy-tftp=true
–foreman-proxy-tftp-servername=2001:db8::51f0
–foreman-proxy-dhcp=true
–foreman-proxy-dhcp-interface=ens160
–foreman-proxy-dhcp-gateway=2001:db8::1
–foreman-proxy-dhcp-nameservers=2001:db8::51f0
–foreman-proxy-dns=true
–foreman-proxy-dns-interface=ens160
–foreman-proxy-dns-zone=example.com
–foreman-proxy-dns-reverse=0.0.0.0.0.0.0.0.0.8.b.d.1.0.0.2.ip6.arpa.
–foreman-proxy-dns-forwarders=2001:4860:4860::8888
–foreman-proxy-foreman-base-url=https://foreman.example.com
1 Like
35

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