Getting Started

Support
1

Installation of the latest version (1.20.1) of Foreman has been a breeze. Getting a handle on the management thereof, unfortunately not.

I started with the manual @ Foreman :: Manual which I unfortunately find lacking in guiding newcomers on the basics for implementation. I then reverted to Youtube. Information as to guide a newcomer feels scattered resulting in being either sidetracked or a feeling of wasting time.

As such, what sources of pre-requisite knowledge or possible (newbie) guides (be it Youtube channels) would ease the learning curve ? Is it advised/assumed to first acquire adequate Puppet confidence before reverting to Foreman ?

1 Like
2

Hi,
thank you for a valuable feedback. We are aware that our manual is ā€˜this is what you can doā€™ rather than ā€˜how to do xā€™ and there are other aspect of theforeman.org that need improvement. We are currently in a process of redesigning the pages and restructuring the information (more on that in a separate thread). Docs at theforeman.org, youtube videos, IRC channel and this forum are the main sources of information that we have.

I would say that the knowledge you need depends on what you want to achieve. Different people have different workflows and most people use only a subset of features. You do not need Puppet knowledge if you do not plan to use it.

What are your expectations of Foreman? What brought you to installing it in the first place? Is there a specific thing that you want Foreman to do for you?

3

I have to say that our goal is to change navigation and landing page mainly, we are not rewriting nothing in particular in docs. This is a huge opportunity for others - our manual needs improvement, new chapters, new content and diagrams, screenshots.

Good source of material is Red Hat Satellite 6 documentation suite which is unfortunately copyrighted. But you can read and most of it applies to Foreman as well (with Katello plugin installed for content management).

4

Me too ā€¦ Began investigating foreman as an alternative to puppet PE.

Looking to do system management, from provisioning to deployment, upgrading/patches,
application deployments, configuration management, security scans/compliance reporting,
smart proxies, user authentication management (FreeIPA), and asset management,
logging, monitoring, certificates, ā€¦, is there anything it canā€™t do?

But having a good place to ā€œstartā€, not only with what it can do, but how to go about doing it ā€¦
The quickstart guide is good. Iā€™ve got it installed. Now what?

5

Jim nailed the issue perfectly. The ā€œGetting startedā€ guide is unfortunately no more than a ā€œHow to install Foremanā€ and does not provide the ā€œgetting startedā€ aspect a noob require to get going.

Also, quite a few new components/aspects is introduced with Foreman with which most have not had any past experience. With time always being a limiting factor, spending weeks on trying to understand the various (possibly unrelated) components defeats the advantage of getting a few auto-provisioned hosts setup, thereby allowing the beginner to experiment/play with Foreman and then only to delve deeper into the various possibilities available.

IMHO. A quick guide (following the current install layout) on the most minimalist configuration required prior to, and then the auto-provisioning of a new host, followed by adding an already established host, concluded with a group configuration change, (i.e. domain name change, app deployment) would surely provide the newcomer with sufficient basics from which to explore and investigate further.

1 Like
6

I definitely agree we could do much better here.

Contributions to the website are most welcome - its source code is all at https://github.com/theforeman/theforeman.org and is mostly written in markdown, so you donā€™t even have to be a programmer to contribute to it! As a new user, your insights are super valuable, since long-time users or developers are already used to much of how Foreman works and donā€™t see the difficulties you face.

Another source of information can be Foreman :: Training which includes material from a couple of training courses that have kindly open-sourced their materials, and Foreman :: Media which includes several intro-level talks in it.

1 Like
7

We would be even happy for a blogpost, your journey of getting Foreman installed. We can learn a lot by reading what were the weak points, then we can start from there. Any feedback is valuable.

8

Iā€™m not sure about a blogpost, but I can offer one small example here if it helps.
I can be very verbose at times, so please redirect me to the appropriate forum to provide the gory details.

The best analogy I can come up with to describe my experience so far is that of wandering into a field
of rabbit holes (not as bad as a mine field), but in the fog. And, keep in mind, I lack any knowledge of
foreman, let alone puppet. That said, I followed the quick start guide and managed to get foreman installed
using the foreman-installer with all defaults.

My setup: desktop system running Ubuntu 18.04 with VirtualBox 6.0.
VMs: CentOS 7 with foreman 1.20.1 and puppet 5.5.10
CentOS 7 installations as a sandbox running nginx as a load balancer in front of 3 apache web servers.
These are on a NAT Network using port forwarding.

From the foreman GUI, I was only able to see the foreman host until I installed the puppet-agent on each of
the VMs, and ran ā€œpuppet agent --testā€. It took a lot more googling and searching to find out about the
Puppet CA and getting the certificates signed ā€¦

It was another bit of digging before I was able to get a report and facts sent to foreman, and briefly,
I had all 5 hosts displayed and ā€œIn Syncā€. But soon they were Out of Sync, and I am now looking forward to
more time spent searching through rabbit holes to troubleshoot that ā€¦

I am purchasing a book called ā€œMastering Puppetā€, but have found almost nothing about Foreman.

I feel like a clueless noob. It shouldnā€™t be this difficult to find the path.
But rather than further polluting this thread, I will silently slither away in frustration.

1 Like
9

jmrice6640, slither back mate! Once again, I share the EXACT same frustrations.

The main difference being that Iā€™m current stuck at the Puppet CA cert process ā€¦

Only other differences is that Iā€™m using Debian instead of CentOS with KVM-Qemu on a ā€œpureā€ IPv6 subnet.

1 Like
10

I may not be able to help with your situation, but happy to try.
We might have to take that offline, unless the community is curious about our specific travailsā€¦

I have an update. I was able to fix the fact reporting merely by enabling and starting the puppet agent
as a service on each host. I changed the runinterval in puppet.conf to 30 minutes to match foremanā€™s
sync interval so it stops complaining.

Next, I just followed the puppet docs for adding modules, like NTP, DNS, ā€¦
I am finally making some progress, and filling in some of the blanks, like manifests, classes, etc.
I know I have much to learn, but I should have been at this stage a few days ago, without the headache.

12

Note that this can also be adjusted in Foreman settings if 30 minutes is not fitting your needs.

13

Please keep sharing, I believe I speak for much of the community when I say we are very interested.

One of the biggest blind spots we developers have is in seeing what is most confusing to newcomers. Since we are already used to many quirks and workflows, and so are the more experienced users who we usually hear more from, we donā€™t get enough fresh perspectives on how we can improve the initial onboarding experience.

3 Likes
14

The initial goal had been a bare metal deployment of Debian via UEFI over IPv6. aka ā€œUEFI HTTP bootā€. Thus eliminating the insecure TFTP server and also possibly allowing booting over the NET via HTTPS.

At present, Iā€™ll settle for iPXE over IPv6 via TFTP. (Though stuck at trying to fathom why the TFTP service is not ā€œavailableā€ although the (only) Smart Proxy (being Foreman) reports ā€œLogs, Puppet, Puppet CA, and TFTPā€ as features.

In hindsight, I advise newcomers to start with Dominic Clealā€™s Youtube videos labled ā€œForeman Quickstart: installation and Puppet Managementā€ (https://www.youtube.com/watch?v=2dwyzPpFJYQ) and ā€œForeman Quickstart: unattended installationā€ (https://www.youtube.com/watch?v=eHjpZr3GB6s). Though outdated, it colours the picture quite well. If only heā€™d completed the third screencast labled ā€œNext screencast: soon, integrating DHCP and DNS managementā€ā€¦

In the meanwhile, Iā€™ll continue picking at the iceberg of available info to accomplish this feat. Time being a hurdle of itā€™s own, yet I believe other features such as Katello would then click much easier thereafter.

1 Like
15

One thing to keep in mind, if you plan on using katello in the future, is that currenty katello canā€™t be installed on an existing foreman easily. Though some have managed to do it, it does take quite a bit of extra effort compared to other plugins. Iā€™m not sure if youā€™re currently trying out foreman in a lab or production setup, but if it is the latter, it may be good to start with katello installed rather than attempt to migrate everything later.

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