Inconsistent documentation

Just some examples

CMK

no spaces before and after the “=”

suddenly spaces

“recap” and a sudden, unexplained, “import pprint” appears.

1 Like

Hi @checknl,

thank you for the input! We will take a closer look into the article, when we’re starting a revise. Meanwhile - and just if you’re interested - you could also provide us a Pull request on GitHub or open an issue there.

@marcel.arentz TBH the high standards you (as in checkmk) seem to impose on contributors here and here but not on your own documentation, dis-encourages me to contribute.

Hi @checknl,

I’m sorry to hear, that you do not have the feeling, that our documentation has high standards. Indeed, we work hard on the quality - but also try not to scare potential contributors away.

To provide you my perspective: We do have a documentation with roughly ~50.000 lines and ~1.100 screenshots per language. Most of these articles did follow the four eyes principle (exceptions are old parts, which are still valid). The particular article for developing check plugins has been authored in cooperation with the developers, which have been designing the new Check-API.
Considering, that we’re working constantly on several parts of our documentation, we are aware of having several parts, that need a revise.

Knowing my perspective, I’m truly interested in your detailed opinion of what you’re currently missing the most. Especially regarding your motivation of contributing.

1 Like

I’m truly interested in your detailed opinion of what you’re currently missing the most

An example for what I consider “core documentation”, not some obscure plugin. Documentation that should be usable for everyone starting with check_mk (don’t get me started on the checkmk check_mk inconsistency).

I have no trouble setting up ssl on apache/nginx with bought certificates or letsencrypt. But since checkmk scatters the apache config files all over the place;

  • /etc/apache2/conf-available/zzz_omd.conf
  • /omd/apache/
  • /omd/sites//etc/apache/
  • /omd/sites//etc/apache/conf.d/*
  • /omd/sites//etc/check_mk/apache.conf
  • /omd/sites//etc/nagvis/apache.conf

I turn to the documentation to find out what would be the preferred/best place for the apache SSLCertificateFile directive. But it is never mentioned in the documentation: Securing the web interface with HTTPS ?!?

Beside the ‘prerequisites’ and ‘additional options’ this documentation only enables a redirect to port 443; nowhere does it actually " Securing the web interface with HTTPS".

LibreNMS tells you exactly which file to edit and what to add: SSL Configuration - LibreNMS Docs
PRTG clearly documents how the application will take care of SSL Using Your Own SSL Certificate with the PRTG Web Server | PRTG Manual

It really shouldn’t be this hard for an user to run and maintain checkmk imho.

Compare Changelog - LibreNMS Docs with CheckMK [Release] Checkmk stable release 2.0.0p22 - #5 by jplitza

CheckMK: no mention or thanx to contributors. No link to the actual changes, only “werks” which are totally non-transparent to users. Mix of languages. The audacity to only listen to “qualified” feedback. etc. etc.

Need more?

Since the link to my reply in the changelog thread notified me of this thread, I’ll just post my 2 cents regarding contribution:

I agree that the required standards for “outside” contribution are quite high (and setting up a local development environment with the right version of Python is quite a challenge just to blacken a small patch), but the most irritating requirement (if you understand Check_MK as a FOSS project) is that only bugfixes are allowed as PRs. Everything not strictly a bugfix is turned down, however well worked out.

But I understand that Check_MK isn’t a FOSS project, but rather a company product that happens to be open source. And from that perspective, I can understand that there are not enough resources to pamper every small niche contribution.

Regarding the documentation for plugin developers, I totally agree: Large parts are completely undocumented (Special Agents? What APIs/modules are safe to use?) and I regularly resort to look at the Check_MK source code itself.

That’s also true for details of the user-facing functionality. Take the comment linked to above as an example: When you specify a monitoring state for a special IPMI sensor, will it override whatever would have been generated otherwise, or can I only make it CRIT instead of WARN? In this case, that detail even (unexpectedly and without mention) changed in a patch release.

The same question came up for the ruleset “Status of the Checkmk”: Can I make the check OK if “specific check plugins receive no monitoring data”? No, I cannot, because any missing plugin data will make it WARN. Is that a bug or “works as intended”? I don’t know, because the intent isn’t stated anywhere (and hence a patch probably wouldn’t be considered a bugfix and rejected).

I love Check_MK as a platform, but only after spending countless hours reading its source code and programing several plugins myself. And yet, I’d rather manage my local patches than submit them upstream.

2 Likes

Thanks for the insights. But if you have no trouble setting up SSL on apache2, I’m a bit confused because of your problems. There’s a reason, why we do not mention all the internal apache2 config files: Because you don’t need them. You just need the standard apache2 paths - which are listed in the mentioned article. If you’re not fine with rewriting, you could use any other method to enforce HTTPS. The same goes for the certificate files: Just use the apache2 standards or your preferred way (like placing unique certificates for each virtual server).

I can ensure, that we’re partially on the same page in this case - that’s why we’re already working on an improved article to explain the process with more details in the prerequisites.

You still missing the point. It’s not about enforcing https, it is about adding a certificate to checmk to enable ssl in the first place.

Any other application would have an /etc/apache2/sites-enabled/.conf with an virtualhost stanza (Debian). That would be the place to add SSLCertificateFile but no checkmk needs to do things differently; there is no /etc/apache2/sites-enabled/checkmk.conf and if you dare to question the documentation, you’ll get “the standard apache2 paths”. Really helpfull. Thanks a lot.

edit: Lets not make this thread about apache config. It’s about the quality of the CheckMK documentation in general.

I do not like comparisons in this kind of topic. Neither do I want to point a finger on someone else, nor do I want to praise our product by talking bad about another one. That’s simply not my nature.

What about: Agent Bakery: Minimize time locking the Checkmk configuration
Or this one: Fix possible ValueError on dashboards after update to 2.1
Or this one: sentry_pdu_v4: PDU support for Servertech v4 devices
I just had a quick look at some of the latest werks.

But I was asking for something different: Why don’t you want to contribute to the documentation? Because we’re not proving a list of contributors in the docs manual?

It seems, that I did offend you and this has not been my intention. Any other application is running the apache2 on a system user (e.g. www-data) – which we don’t. We start every apache2 instance with limited permissions as site user.

So I disagree: The place to add a SSLCertificateFile is not /etc/apache2/sites-enabled/.conf. It would be below the path /etc/apache2/sites-available/ and the exact file default-ssl.conf. But, this is only true for Debian based systems. That’s why we chose – in the past – to not explain the requirements in more detail.

Thanks again for the input - it’s telling, that we’re actually working on the most important articles.

1 Like

I sure would contribute / document if I had the feeling that it would help someone. But the whole werks system, the lack of any feedback on any bug report, the sloppy documentation. The weird bugs you’ll only learn about if they got fixed ( Fix possible ValueError on dashboards after update to 2.1), all those don’t make this the community I would spend much of my time at. If I would like to fix the documentation, I first have to understand it. A suddenly random “import pprint” does not help. I am a CheckMK use, a system administrator not a Python programmer. Like @jplitza said:

I love Check_MK as a platform, but only after spending countless hours reading its source code and programing several plugins myself. And yet, I’d rather manage my local patches than submit them upstream.

No. Did I ask for SSL on the whole server? I wanted SSL on CheckMK.

We start every apache2 instance with limited permissions as site user.

Then document that, and explain how I can make (apache) adjustments without breaking your system.

Thank for replying @marcel.arentz , although disagreeing about a lot, I appreciate it.

I strongly believe, we need a nice and kind tone to have a helpful outcome in our discussion. So, I guess, we shared all our arguments in this topic and there is not much more to add. :slight_smile:

I cannot force you or any other member of the community to contribute. But everyone, who’s interested, is welcome. Also and especially in the documentation.

PS: You’re welcome @checknl. I’m serious with the “I’m truly interested in your detailed opinion” part. And not only yours. We’re all learning a lot about our own product during conversations with the actual users. Even or maybe especially while disagreeing.

3 Likes

@marcel.arentz how would I edit / correct NGINX: Performance Indicators ?

..
Now add the following block:

location /nginx_status stub_status on; access_log off; allow 127.0.0.1; deny all;

Afterwards execute
..

should, of course, be

...
Now add the following block:

location /nginx_status {
    stub_status on;
    access_log off;
    allow 127.0.0.1;
    deny all;
}

Afterwards execute
...

:zipper_mouth_face:

1 Like

Hi,

that’s indeed a question, that you rarely can solve on your own. Our man pages allow limited use of HTML. In this case, I embedded the code part into <pre>. Just in case, you’re thinking about a pull request: I already have that internally in review. :wink:

Good to hear it’s getting fixed. The limited use of HTML is a weak excuse to publish documentation like this. Especially if it has been internally reviewed before publishing. Something high standards… etc. etc.

I seriously hope CheckMK will step up it’s documentation game. It would make me, and i feel many others, far more enthusiast to try, use, learn and contribute to CheckMK. Thanks for listening.

Give things time and consider from where we have come in the last 4 years. I have already mentioned the background regardings PRs in other thread somwehere.

I can elaborate on the details, if interested, for both docs + checkmk itself.