Review needed: Configuring Foreman with existing services (guide)

Hello,

I wrote a guide about configuring Foreman Proxy against existing ISC
services (DHCP, DNS, TFTP) on a remote server. This needs a review both
technically and grammatically. It has been tested on RHEL 7, if you want
to extend it for RHEL6 or Debian, feel free to add notes for these
platforms (RHEL6 is easy, the only difference is IMHO NFS service
names).

My intention is to put this either on Foreman blog or into our
documentation site. The only drawback for our official docs site is
missing Debian instructions. If there is a volunteer with a Debian
system and some spare time, this would be awesome.

The doc is open for comments and edits. All kind of improvements are
welcome, if you intend to change commands or configuration files, please
verify the whole process.

··· -- Later, Lukas #lzap Zapletal

I'd advise against publishing it under the blog, since that dates really
badly.

In a year's time, instructions about the installer or whatever will be
out of date - making the effort to put this into the manual means we can
keep the docs in sync with Foreman as it changes. There are already
existing docs in the manual about setting up DHCP servers, installing
smart proxies via the installer etc that can be improved upon.

··· On 11/09/15 14:53, Lukas Zapletal wrote: > Hello, > > I wrote a guide about configuring Foreman Proxy against existing ISC > services (DHCP, DNS, TFTP) on a remote server. This needs a review both > technically and grammatically. It has been tested on RHEL 7, if you want > to extend it for RHEL6 or Debian, feel free to add notes for these > platforms (RHEL6 is easy, the only difference is IMHO NFS service > names). > > My intention is to put this either on Foreman blog or into our > documentation site. The only drawback for our official docs site is > missing Debian instructions. If there is a volunteer with a Debian > system and some spare time, this would be awesome.


Dominic Cleal
dominic@cleal.org

> In a year's time, instructions about the installer or whatever will be
> out of date - making the effort to put this into the manual means we can
> keep the docs in sync with Foreman as it changes. There are already
> existing docs in the manual about setting up DHCP servers, installing
> smart proxies via the installer etc that can be improved upon.

Indeed, volunteers do not hesitate to take the doc and drag best bits of
it in our documentation. Particularly the NFS configuration is what we
miss, other than that it's typical setup. And also what is missing is
the Feature #11676: Proxy cannot be configured with remote DHCP server - Smart Proxy - Foreman I fixed recently.

If there are none, I'll give it a try later this month.

··· -- Later, Lukas #lzap Zapletal

I'll do what I can for Debian once I've had a chance to actually read it :wink:

Greg

··· On 11 September 2015 at 14:53, Lukas Zapletal wrote: > Hello, > > I wrote a guide about configuring Foreman Proxy against existing ISC > services (DHCP, DNS, TFTP) on a remote server. This needs a review both > technically and grammatically. It has been tested on RHEL 7, if you want > to extend it for RHEL6 or Debian, feel free to add notes for these > platforms (RHEL6 is easy, the only difference is IMHO NFS service > names). > > My intention is to put this either on Foreman blog or into our > documentation site. The only drawback for our official docs site is > missing Debian instructions. If there is a volunteer with a Debian > system and some spare time, this would be awesome.

> I wrote a guide about configuring Foreman Proxy against existing ISC
> services (DHCP, DNS, TFTP) on a remote server. This needs a review both
> technically and grammatically. It has been tested on RHEL 7, if you want
> to extend it for RHEL6 or Debian, feel free to add notes for these
> platforms (RHEL6 is easy, the only difference is IMHO NFS service
> names).

Reads fine, for the most part. Here's a few comments:

Page 1 - the installer already defaults to false for DNS and DHCP,
according to foreman_proxy::params.pp. I think it's fine to include
the command to explicitly disable them, just in case, but the first
paragraph should probably be reworded.

Page 4 - you call "rndc freeze" but not "rndc thaw" which will leave
the zone in a frozen state.

Page 7 - slight typo:

"In our example, lease range is 192.168.38.10 - 192.168.38.100 so
lease range (defined in Foreman WebUI) would be 192.168.38.101 -
192.168.38.250"

should probably read

"In our example, lease range is 192.168.38.10 - 192.168.38.100 so
reservation range (defined in Foreman WebUI) would be 192.168.38.101

  • 192.168.38.250".

I'd also consider not mentioning the GUI until you're ready to
configure it, so maybe something like

"In our example, lease range is 192.168.38.10 - 192.168.38.100 so the
reservation range is be 192.168.38.101 - 192.168.38.250"

Page 8 - In the Proxy DHCP config, you don't mention your two new
options from #11676, :dhcp_server and :dhcp_omapi_port

I also fixed a couple of very minor style things :slight_smile:

> My intention is to put this either on Foreman blog or into our
> documentation site. The only drawback for our official docs site is
> missing Debian instructions. If there is a volunteer with a Debian
> system and some spare time, this would be awesome.

I'll try and test Debian later this week. I'll copy the doc and
rewrite it for jessie, and then we can compare and figure out a PR for
manual (which can use the same OS selection-box style as the
quickstart page, I think).

Greg

··· On 11 September 2015 at 14:53, Lukas Zapletal wrote:

> I'll do what I can for Debian once I've had a chance to actually read it :wink:

The link is open to edit, no sign-in required. But it will be better
maybe to create the PR so you can add Debian stuff right there. Looks
like I will only add the NFS stuff.

On the other hand, tutorial-like article is also not bad. Our
documentation is not structured this way. If you like, we can edit
first, push onto the blog (with warning this works only with 1.9) and
then pull some parts back into docs.

··· -- Later, Lukas #lzap Zapletal

> Page 1 - the installer already defaults to false for DNS and DHCP,
> according to foreman_proxy::params.pp. I think it's fine to include
> the command to explicitly disable them, just in case, but the first
> paragraph should probably be reworded.

Reworded, please review once again, I struggled a bit :slight_smile:

> Page 4 - you call "rndc freeze" but not "rndc thaw" which will leave
> the zone in a frozen state.

Oh great catch. Is there any more clever way of syncing zones?

> Page 7 - slight typo:
>
> "In our example, lease range is 192.168.38.10 - 192.168.38.100 so
> lease range (defined in Foreman WebUI) would be 192.168.38.101 -
> 192.168.38.250"
>
> should probably read
>
> "In our example, lease range is 192.168.38.10 - 192.168.38.100 so
> reservation range (defined in Foreman WebUI) would be 192.168.38.101
> - 192.168.38.250".
>
> I'd also consider not mentioning the GUI until you're ready to
> configure it, so maybe something like
>
> "In our example, lease range is 192.168.38.10 - 192.168.38.100 so the
> reservation range is be 192.168.38.101 - 192.168.38.250"

Yeah, fixed. The latter, I agree but I see many confused users about
DHCP reservation configuration (what to do in dhcpd.conf and what in
Foreman), therefore I am trying to be more explicit here. Up to you to
change it.

> Page 8 - In the Proxy DHCP config, you don't mention your two new
> options from #11676, :dhcp_server and :dhcp_omapi_port

Oh of course! Important point.

> I'll try and test Debian later this week. I'll copy the doc and
> rewrite it for jessie, and then we can compare and figure out a PR for
> manual (which can use the same OS selection-box style as the
> quickstart page, I think).

Thank you so much for doing this, the document needs maybe a different
form to be integrated with our docs. This tutorial-style is perhaps not
good fit.

··· -- Later, Lukas #lzap Zapletal

"External DNS service”, section "Foreman Proxy configuration” covers
the old (pre-modularized) dns providers. Might make sense to describe
current dns module configuration, or mention that it differs from the
one described (and suggest running config file migrations?).

Cheers,
-d

··· On Mon, Sep 14, 2015 at 10:31 AM, Lukas Zapletal wrote: >> I'll do what I can for Debian once I've had a chance to actually read it ;) > > The link is open to edit, no sign-in required. But it will be better > maybe to create the PR so you can add Debian stuff right there. Looks > like I will only add the NFS stuff. > > On the other hand, tutorial-like article is also not bad. Our > documentation is not structured this way. If you like, we can edit > first, push onto the blog (with warning this works only with 1.9) and > then pull some parts back into docs. > > -- > Later, > Lukas #lzap Zapletal > > -- > You received this message because you are subscribed to the Google Groups "foreman-dev" group. > To unsubscribe from this group and stop receiving emails from it, send an email to foreman-dev+unsubscribe@googlegroups.com. > For more options, visit https://groups.google.com/d/optout.

>> Page 1 - the installer already defaults to false for DNS and DHCP,
>> according to foreman_proxy::params.pp. I think it's fine to include
>> the command to explicitly disable them, just in case, but the first
>> paragraph should probably be reworded.
>
> Reworded, please review once again, I struggled a bit :slight_smile:

I think that reads fine now. I've made a minor rewrite for clarity,
but you did fine :slight_smile:

>> Page 4 - you call "rndc freeze" but not "rndc thaw" which will leave
>> the zone in a frozen state.
>
> Oh great catch. Is there any more clever way of syncing zones?

I don't think so. Freeze/thaw is fine now that both are present.

>> Page 7 - slight typo:
>
> Yeah, fixed. The latter, I agree but I see many confused users about
> DHCP reservation configuration (what to do in dhcpd.conf and what in
> Foreman), therefore I am trying to be more explicit here. Up to you to
> change it.

Good point. I've clarified it further for that reasoning, see what you think.

>> Page 8 - In the Proxy DHCP config, you don't mention your two new
>> options from #11676, :dhcp_server and :dhcp_omapi_port
>
> Oh of course! Important point.

That seems fine, but your Warning refers to :dhcp_config - wasn't it
:dhcp_server and :dhcp_omapi_port that were added in 1.10?

>> I'll try and test Debian later this week. I'll copy the doc and
>> rewrite it for jessie, and then we can compare and figure out a PR for
>> manual (which can use the same OS selection-box style as the
>> quickstart page, I think).
>
> Thank you so much for doing this, the document needs maybe a different
> form to be integrated with our docs. This tutorial-style is perhaps not
> good fit.

It's fine for now while we get docs that work. Lets worry about
integration and style once the data is correct.

Greg

··· On 17 September 2015 at 11:12, Lukas Zapletal wrote:

> That seems fine, but your Warning refers to :dhcp_config - wasn't it
> :dhcp_server and :dhcp_omapi_port that were added in 1.10?

Of course, fixed.

> It's fine for now while we get docs that work. Lets worry about
> integration and style once the data is correct.

Sure.

··· -- Later, Lukas #lzap Zapletal