The Administering Foreman guide is now live on

Hello Foreman people,

We have migrated one more Red Hat Satellite guide to Foreman - the Administering Foreman guide that you can find at

You can use this guide to learn how to perform system administrative tasks using Foreman. Furthermore, how to integrate Foreman with external databases, external identity management systems, such as FreeIPA and Keycloak.

Check out the guide and feel free to submit feedback and contribute on our foreman-documentation GitHub repository.


This is great, @spetrosi!
Thanks once again.
This was the largest guide that remained to migrate upstream.
Iā€™m so glad to see this done.

From a first and short look I have to say it looks very promising. I only have one bigger concern. You can very clearly see that it comes from the Satellite docs because it mixes topics which are relevant for a Foreman-only installation and Katello installation which could be confusing for users.

Not sure if restructuring or adding some additional notes would be more useful.

Just to give one example. The guide starts with ā€œInstalling the Katello Root CA Certificateā€ which is only valid for Katello, but it could be done in a different way also for Foreman-only which at the moment uses the Puppet certificates but this will change in the future for sure.

I think the idea of these guides is to have somewhat of an integrated and user-centred approach rather than separate them out by components and document features.

I think if there is a loud enough call for it, it will be possible (not right now because of the structure of these docs) later to separate the upstream versions of these guides into Foreman only or Foreman + Katello.

I think @ekohl has some promising content on doing this for Foreman only. When he returns, I will talk to him.

We mainly aim for the Foreman Installation with the Katello plug-in. The Installing Foreman Server instructs to install Foreman with Katello by default.

However, we still try to add notes in sections that are aimed for the users of the Katello plug-in. It seemed obvious to me that this ā€œInstalling the Katello Root CA Certificateā€ section is aimed for the Katello plug-in users because of the heading, hence I did not add a note there.

I pasted a wrong link here by mistake. Here is the correct link to the repository:

1 Like

There are multiple things to consider.

First, when docs team brings guides upstream, they want to do minimum possible changes so we track what was actually modified in order to have the content relevant. The most important changes in this phase are replacing Satellite with Foreman/Katello, replacing many example code, URLs and hiding irrelevant parts (subscription manager, RHEL).

What we get is a starting point we, as a community, can improve on. And this is where we at, what you see. So far, we have been adding various remarks or new content which covers some differences, including the whole Debian guide which is already amazing contribution. But I would like to stop here and think.

If you look at the current official docs as a newcomer, you are confused. Thereā€™s Foreman, theres Katello, installations are completely different. There are many plugins which are documented on various places yet you are not given a good overview of what Forman is capable to. We fail to explain this and this new documentation could be our chance to be more opinionated.

The new generation documentation on the other hand is consistent experience. There are still gaps we can fill, particularly in describing how things work as these guides are more process oriented. Thatā€™s where we can step in and fill in the content.

Saying that Katello is the only deployment type is definitely not a solution, hence I would like us to discuss this before we commit to any upstream-only changes in our new documentation. What we can do on multiple levels with this Foreman vs Katello problem. Unifying installers with ability to ā€œupgradeā€ has been a long discussion. I believe this could be a good solution, one installation for everyone. Where we stand today can probably @ehelms or @ekohl comment on. Certificates are often major problem of this, you actually mentioned it. I am aware that we are planning some changes in this regard to solve it. Maybe moving into containers shakes everything so much that this is no longer an issue? Is that a solution? I donā€™t know. There are many things to consider.

Anyway, I would like to say loud that there is no pressure on anyone here for getting the documentation merged. We can take our time, our writers team will continue working in the new upstream repository, we can be closer when contributing features and users can report/fix bugs or typos more easily. In the meantime, our official documentation is still what we promote on our webpage. (You will see me often linking the new docs, but I canā€™t help myself - provisioning is not well covered in our official docs.)

In the end, I would love to see our new documentation to join documentation effort across most Foreman-based products. I know that every single product available out there has different setup, different installation instructions, different everything. There is undergoing change in the new docs which is called ā€œmodularizationā€. Every bit of documentation is a reusable module (think: separate file) and books are assembled from those. So there is a lot we can work with.


Hello and thanks!

Is there a tracker (spreadsheet, anything) of the guides which are planned to be migrated?

I know that not all guides are useful upstream, but feel free to migrate all the rest so you only have one place to work with (github). Those guides which are not relevant for Foreman/Katello can be built but should not be linked from the landing page.

We did not discuss that far actually, the Admin guide was our main milestone. I would say that the Planning for Red Hat Satellite is a good next candidate.

1 Like