missing documentation or examples on how to use this formula.

[eMBee]

it would be helpful to have some instructions on how to use this formula and create an example setup.

as i discovered, at a minimum, the following steps are necessary:

---

• install the formula as in the Salt Formulas installation and usage instructions.

• in top.sls set up the server with:

  'nagios-server':
    - nagios.server
    - nagios.server.dynamic
  

• copy pillar.example to the the pillar directory (eg as nagios.sls)

• add the nagios pillar to the nagios server and to all machines that are monitored through nrpe

• edit the pillar file to the fix the conflicting ID 'checks' by choosing whether to target only the server or minions as well.

• link/copy the provided apache2.conf into the apache directory (the debian nagios packages pull in a ready-to-run apache server. on other distributions, the webserver may need to be configured independently, which is beyond the scope of this formula):

  /etc/apache2/sites-enabled/nagios.conf:
      file.symlink:
          - target: /etc/nagios3/apache2.conf
  

• create a user:passwd entry for nagios admin:

  /etc/nagios3/htpasswd.users:
      file.managed:
          - source: salt://services/nagios/htpasswd
          - mode: 755
  

---

only at that point nagios is actually running and accessible by webbrowser.

next i need to figure out how to add our local configuration. it looks like this involves setting up NRPE

maybe this issue can be used to create some basic instructions on how to get started.

[gravyboat]

This sort of documentation isn't in the repos but exists over here: https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html. We expect that people have a bit of knowledge regarding the basics of how salt works prior to using formulas. You may wish to review https://docs.saltstack.com/en/getstarted/ for details on getting started.

[eMBee]

i am not asking for documentation on how to use formulas in general. i had no problem to get the formula loaded using the documentation given. it was after loading the formula, that i was missing instructions on how to actually use this formula in particular. i was unable to find any instructions that would tell me the steps that i have shown. these steps are specific to this particular formula, and would not even have a place in the general documentation on using formulas.

[gravyboat]

Hmm, maybe I am confused then, the only part I see that isn't part of the docs is the last step you noted, which is noted here: https://github.com/saltstack-formulas/nagios-formula/blob/master/pillar.example#L153 and here: https://github.com/saltstack-formulas/nagios-formula/blob/master/pillar.example#L170. Maybe I am misunderstanding the issue, @BABILEN does this make sense to you as something we should fix for this formula?

[eMBee]

the general instructions only tell to use states from the formula, but they don't say which states are necessary to get the system to work.

they also claim that "Salt Formulas are designed to work out of the box with no additional configuration." which for me was not the case. (maybe this needs a separate bug report)

i started with using only the - nagios.server state, expecting to get a minimally running server. instead i got errors about missing host, service and contacts.

i then had to figure out that - nagios.server.dynamic and the pillar.example would help me fix those errors. - this is something that could be documented.

"many Formula support additional configuration and customization through Pillar" implies that pillar support is optional. however, - nagios.server.dynamic requires a pillar file (as it says in the description), which further implies that there is a minimum of pillar config values that must be present for the state to work.

the lines 153 and 170 in the example explain what the purpose of the respective trees is, but they don't explain that i need to remove one or the other. this is an issue because the error caused when not doing so is hidden in the master log-file instead of given directly in the output as sls errors usually are.

[gravyboat]

Fair enough! Feel free to prep a PR if you would like to add this documentation. Hopefully @BABILEN will respond as well to help clarify some of the reasoning behind that stuff.

[eMBee]

is - nagios.server needing additional configuration a bug, given that formulas generally should work without additional configuration?

[eMBee]

before making a PR i'd like to get a better understanding of what would be the correct instructions.

at this point i am thinking of an additional paragraph for - nagios.server similar to:

this state requires the definition of hosts, services and contacts. either use it in combination with - nagios.server.dynamic or add the necessary configuration manually.

[eMBee]

i also discovered that the formula does not set up a webinterface.

am i missing something or is that intentionally left out?

[eMBee]

i got the webinterface to work by creating an additional salt-state which links the apache config file from /etc/nagios3/apache2.conf to /etc/apache2/sites-enabled/nagios.conf and by adding /etc/nagios3/htpasswd.users

i believe such a state should be included into the formula, possibly with some pillar configuration to manage the users.

[wwentland]

I am only using this formula for configuring the nrpe client and started long before checks were introduced. I'll try to make sense of the current state of this formula soon and will hopefully be able to provide some insight into the directions it has been taken in the interim.

[wwentland]

Okay, I looked into this and the example pillar is showing different ways of configuring the nagios server. The main difference lies in the configuration of remote/non-NRPE checks as they would only be configured on the nagios server and not the clients.

It's tricky to show all different variants while still providing a generic enough pillar. I would argue that using the same namespace for checks is a bit unfortunate and that this issue could have easily been avoided by not conflating NRPE and nagios server.

OTOH, I don't necessarily think that users should, by default, be able to copy pillar.example verbatim and assume that to do something useful.

[wwentland]

In regard to the webinterface: This is a sensible area as we do not allow to depend on other formulas and I really wouldn't like to maintain the apache formula and nginx formula in here also. I can, however, also understand the wish to be able to configure a fully working nagios installation with a single formula.

In my opinion it would be best to ship a pillar example for the apache and nginx formula.

[eMBee]

the webinterface does not depend on any other formulas. at least not on debian. the nagios debian packages depend on apache, and thus just nagios.server causes apache to be installed and running by itself. there is no need for any salt formula to get apache to work. the only thing needed to get nagios to work with apache was to link/copy the provided apache2.conf into the apache directory.

of course, if debian is the exception here, then i agree.

in any case an example would go a long way. it's not that setting up the webinterface would be complex and require a complete formula but rather that a small bit was missing that can easily improved with some docs and an example.

[wwentland]

@eMBee I wholeheartedly agree that more and better documentation would go a long way even if implementing this in a simple state is not feasible on all platforms. I was just thinking of the implications setting up a service that's comprised of many different components would have.

[eMBee]

i have taken the liberty to update the initial issue description with any additional steps to get nagios running as i discover them. i don't know if this represents a typical use of this formula, and if not, how a typical example would look like. but in any case it could be converted into a setup guide as part of the documentation, a wiki page or some other form.