ZABBIX documentation

[MarkusL]

Hi everyone,

I´m pretty new to zabbix, but I love it! :-)
When we startet with zabbix (reading the manual) I just thought: oh my god. This is gonna be hard work. So we rented a consultant. In 10 days, we set up our zabbix (master server in our house; meanwhile about 15 proxies at our customers houses, all proxies automatically start an ssh-tunnel to our server, whole communication over that secure tunnel. Rollout of a new proxy by mindi/mondo and a written script; a new proxy is ready to go from the scatch in about 30min).

But back to the point:
As I was "in" the concept an "thinking" of zabbix (thanks to the great work of our consultant), I had no problem about finding solutions, matching articles in the forum or understanding the manual. I could even help debugging and testing very effective.

So I have to ask: why can I do within 10 days of work that much? Because of our consultant, of course. And why is it not possible to do this on my own, only with the docu?

Because:
- the basic installation is to hard
- when the installation is ready, I didn´t know how to start
- when I startet I did not see "the whole thing", so I was not able to use zabbix strategically; I just was able to guess and click; try and error
- when I saw "the whole thing" I needed so much time for finding a technical way of doing things; begins with finding the right SNMP-OIDs, writing scripts, configuring, configuring, testing, testing; the point: I was missing the best practices / templates

Now, some months later, I got what I want. Nearly all my wishes found there way to zabbix; working fine.


So, what now about the manual. My thinking is, to get the problems away I discribed above (and I think many beginners have the same problems in the same order!):

- we need a good docu about the installation from the scratch, matching the actual release

- it would be great to rollout a vmware-image with the actual zabbix-release; great for beginners; a "certified" installation. I think this would be also be great for testing. Offen, a problem is laying in a miss-configuration. With a "certified installation", we all have ONE SIMILAR base we can discuss on; maybe - in the style of open source - upgrade and perfect it all together (backup processes, scripts, etc.)

- we need a visual thing, discribing "the whole thing". Maybe a Visio-sheet or something, just visualizing, what zabbix can do all over

- we need a good documentation and matching best practices (Templates, read-and-click-descriptions)


Let´s come to the "how to write the docu". In my work I often have to write documentations; for beginners and users, for pros or myself. The one thing I found in all situations: a large document, just giving one point after the other one (PDF, DOC, etc.) is not a practicable thing. It gives you a good feeling ("I have done my work"), but it is far away from "I can work with it an I really NEED it".

So, I think, the best way of implementing a docu is a wiki. BUT: I would "implement" it in zabbix!!!! The zabbix-developers have implemented a "?" in zabbix, pointing to the downloadpage of the PDF-docu.
Exactly this "?" I would use on every page and needed situation to point to the right page in the wiki. So we setup up a wiki exactly in the way, zabbix is structured:
- Main page Monitoring
- Dashboard
- ...
- Configuration
- Hosts
- ...
When I´m by configuring a new item, I just click the ? and come to the wiki to the item-section.

Every section is structured exactly the same:
for example:
1.) Screenshot of the page
2.) short discription of every button, setting, etc.
3.) Best practices to the section (for example creating an item to monitor a DELL-RAID-Controller)
4.) Downloadsection for needy tools, templates, screenshots from users, etc.


What remains is the question, if it is still needed to HAVE a PDF. I don´t think so; maybe because I´m working that much paper-less. If needed, I can (with a printerfriendly wiki) print me out the section, that I need.


Merry christmas to everybody!
Markus.

[MrKen]

So, I think, the best way of implementing a docu is a wiki.

Actually, Zabbix already has a wiki.

http://www.zabbix.com/wiki/doku.php

Most of the contributions in the wiki have come from individual Zabbix-users who have something that they want to share with the rest of the zabbix community.

Your ideas for 'real' examples detailing the various steps involved in configuring zabbix sound great. If you have something that you feel like sharing, please log in to the wiki and give it your best!

And, a Happy New Year to you too!


MrKen

[Cray]

Hi all

I was told by swaterhouse to post here for the documentation / manual improvements to be made.

So here are the few points I noticed :

- is there any reason to jump from point 4 to point 7 on the table of contents ?

- the screens need to be updated (screenshots from 1.4.x a still present in the 1.6.2 manual)

- regarding the zabbix server configuration file parameters (p. 65-68) the following args are missing : startIPMIpollers, startPingers, tmpDir

- regarding the zabbix proxy configuration file parameters (p. 69-72)
-> the DataSenderFrequency is a non-existant parameter (if I'm right), the correct one is SenderFrequency
-> the PingerFrequency parameter isn't at the right place in the table (it should be right after the PidFile parameter)

[Cray]

Regarding the IPMI chapter, it's written IMPI parameters instead of IPMI.

[zordio]

The manual should describe the difference between "ZABBIX Agent" and "ZABBIX Agent (active)"

[Cray]

p.182 : Use of dynamic indexes

-> [...] on a Cisco device, you may use the following OID

[bhatfield]

The manual needs some serious work on installation. I wish I remembered all the steps I had to take to get the basic install to happen, but it's fairly important to note that the manual missed about half of them.

Furthermore, there needs to be a LOT more examples and "legal values" for everything, all over the manual.

It should be MUCH clearer what the 'flow' of zabbix is - especially for those coming from other monitoring systems such as OpenNMS, I didn't realize that I needed hosts, items, triggers, actions, users, media all set up to get an email notification. A good solution to this would be a simple diagram or flowchart of how Zabbix works in simple terms (ie; you need a host configured with an item, a trigger based upon that item, an action based upon a trigger -- all while providing examples of how someone might set it up.). A second piece of that would be a flowchart/diagram of the Zabbix architecture, for agents (active and passive) through how the server side is structured.

I would be happy to contribute these pieces, but I am unsure of how I get into the zabbix community to provide these things.

Also, note this: http://www.zabbix.com/wiki/doku.php?...nd_hosts_oh_my (not by me)

[froztbyte]

Database schema documentation for those who want to automate things against the ZABBIX database, and/or properly document the attributes the XML storage format uses (ie, the typecodes and such).

[rolandsym]

Writing Documentation

Hi,
I've been using Zabbix for almost 2 years now. I wouldn't same I'm expert in it but I've configured quite a few systems with a proxy to distributed monitoring. I have setup a wide variety of systems into zabbix and experimented on a few more due to the nature of my current occupation. Which is giving me more and more free time.

Since I'm having more free time, I'd gladly help out on Zabbix Documentation. I'm not an expert coder but I believe I can give my contribution in this way. That's if the community would like that?

Roland Sym

[RyanC]

After struggling with compiling the Zabbix Proxy on FreeBSD 7.2, I just wanted to point out a missing example in the Zabbix Manual v1.6. Release 017 (the current one as of this writing).

On page 49 (Section 2.4.4.ZABBIX Proxy), step 4 explains how to configure and compile the Zabbix Proxy. It has examples for the command line to compile the proxy for MySQL, PostgreSQL and Oracle.

What's missing is the command to configure the sources for SQLite. Here's the missing example:

shell> ./configure --enable-proxy --with-sqlite3 --with-net-snmp –with-libcurl # for SQLite + WEB monitoring

Hopefully adding that example to the manual will save someone else some time.

Thanks!

[Eric]

I think this forum is great and also the wiki but I think it would help a lot (especially newbies) to have tips that are listed here inside the documentation.

For example: I spend a long time on getting fping to work after changing a settings in the server config file and eventually found it in the forums.

So please add items to the troubleshooting section of the documentation like:

-> If SourceIpAddress is used in the server conf file your version of fping must support the '-S' switch

[IvanG]

I am thinking about start to translate Zabbix manual to spanish. I think its a growing number of Zabbix users speaking that language and it would be nice to have the manual on our native language.
Another lack of information is with Triggers and Items. Concepts are too easy to understand, but they are too complex to put just few pages on a manual. Maybe some slides can help on this aspect. Information about how to deal with events can be a big help (a document called "My life with Zabbix", or something like that)

Just my 2 cents

[Zarastro]

Miscalculation of database size for "trends" table

The manual reads on page 37, "Housekeeper setting for trends":

ZABBIX keeps 1 hour max/min/avg/count statistics for each item in table trends. The data is used for trending and long period graphs.

The calculation of this value is described as follows:

Suppose we would like to keep trend data for 5 years. 3000 values will require (3000/1800)*(24*3600*365)*128 = 6.3GB per year, or 31.5GB for 5 years.

I understand that this calculation assumes that statistics are kept in half-hour (30 minutes = 1800 seconds) period. Wouldn't be (3000/3600)*(24*3600*365)*128, or just 3000 values * 24 hours * 365 days * 128 bytes = 3.15 GB/year or 15.75 GB for 5 years?

If not, why use 1800 on the example given in the manual?

TIA,
Zarastro

[jaxxm]

Suggestion for manual

could you please add clear screen shots or tell us what is in the screen shots. Especially in the examples of the WEB creating a scenario. In creating a the first step I cannot see what it says on how to use the macro's for logging in. And also how to set up checking log files. (I still have not got this right.)

Good product, just hard to work out the manual thought.

[sgbeal]

Missing documentation for how to escape $# in UserParameter scripts

Consider this snippet (a workaround for the broken >2TB support for vfs.fs.free.)

# hvb.fs.freekb[/path] returns free space in kb. The perl weirdness here is to avoid
# extra $'s (behaviour/escaping of which are not documented in the Zabbix docs) in an
# AWK expression. In Zabbix Item Configuration:
# Type=Numeric (int64), Units=B, Custom Multiplier=1024
# will result in gigabytes.
UserParameter=hvb.fs.freekb[*],df -b $1 | sed 1d | perl -pe 's/\s+/:/g;' | cut -d: -f2


It would be easier to implement using awk '{print $2}' instead of the perl kludge, but the Zabbix docs do not document how one is to escape $# parameters which are not Zabbix function parameters. e.g.:

UserParameter=foo[*],df -b $1 | sed 1d | awk '{print $2}'

that has undefined (or at least undocumented) behavior.




PS: a while later, after some testing: it seems that the following works:

UserParameter=foo[*],df -b $1 | sed 1d | awk '{print $$2}'

that is, escaping the $'s using another $.

On a related note, it appears to be legal to use each $# multiple times and out of order. While that might seem intuitive to most, it should be specified in the manual. e.g.

UserParameter=dollar.test[*],echo $1 $2 $3 $1 $1 $2 $3 $3

zabbix_agentd -t dollar.test[foo,bar,baz]
dollar.test[echo foo bar baz foo foo bar baz baz | awk '{print $1}'] [t|foo]