ZABBIX documentation

[Alexei]

We are looking forward to improve ZABBIX documentation.

I would like to ask ZABBIX users what is missing currently? Quick start guide? Basic concepts? Something else? Perhaps current structure of the manual is not intuitive enough? What was the most confusing part when you met ZABBIX for the first time? :)

Many thanks for any response!

[abi]

hi,

well, a Quick Start Guide might be best. I think most people
are confused by the different components (agent/agend). It may be
good to have some short Description what each of the services does.

[themons]

Some times it very difficulte to find item table, supported item by plateform or triggers function.

So i made a paper version of a quick reference guide. I always have it near me :) it may be a good idea to make a quicke reference guide with tables and usefull information.

[Jabberwocky]

The description of the services would be most helpful. Also maybe a map/diagram of the components and how they interact, and where they can be found on the users machine.

[befortin]

A FAQ would definitly be nice. For example :"How to monitor Windows logs". Most users will find out how to setup this kind of thing in the forums, but it would be nice if it was in the documentation. Also, "How agent status works (why it isn't 'updated')". "How to use performance monitor". "How multipliers work and when to use them". "How to configure alerts (for example, use "trigger value == ON and trigger name like "blablabla".

Some documentation about how to install the agent on Windows is also missing. I know it's easy to setup the agent on windows, using the .bat file that comes in Zabbix, but still...

Also, I think some information is missing about how to use templates. How they work and how you can use them. Maybe also explain how you can use templates with triggers.

I don't see anything about the Inventory thing in the documentation. When you click on the "?" icon on the Inventory page, it sends you to the following page, which doesn't exist : "http://www.zabbix.com/manual/v1.1/web.host_profile.php".

But most of all, I think we need more informations about items and which OS supports which items.

[dantheman]

I think a good step by step instruction on how to setup a host, how to setup an item(agent, simple check, and SNMP), how to setup a trigger. .. etc.. would be a good thing.

And not just saying "enter the key here".. explain what each setting, parameter does as you go. So not only would the reader find out how to do something, they would be able to understand what the different parts do.

[ericb]

how the windows agent works and what it can do.

i dont mind doing some documentation by the way, im looking to implementing Zabbix in my work place removing Nagios and Cacti so i will be providing documentation to the engineers anyway.

[clubbing80s]

please could you provide pdf's of the manuals..

Thanks

[Alexei]

Thanks for all suggestions! We have started Quick Start Guide:

http://www.zabbix.com/manual/v1.1/qs.login.php

Please let me know what you think. Is it detailed enough and has good format? What other topics you'd like to see covered?

[befortin]

Maybe something about templates? How to use them to create hosts, triggers, actions, macros, etc.

[amcorreia]

please could you provide pdf's of the manuals..

Thanks

I think, pdf format is a poor idea, because you don't can read this in a console (text mode), (okay, have programs to transform this to text. ex pdf2text), but can this a alternative format.

[clubbing80s]

The document type is irrelevant, my isssue is that the doc's on the web site are difficult to print out. I'd be happy with a text file that prints to A4.. I like to make notes as I work ..

Greg

[Fábio Emilio Costa]

I believe it's okay to maintain a PDF copy with HTML copy for Zabbix Docs. PDF for printing and HTML for online reading.

Fábio

[nelsonab]

Not sure if this is the right thread for this but the following came up in the forum which I could not find in the documentation:

http://www.zabbix.com/forum/showpost.php?p=13935&postcount=2

I could not find a discussion anywhere regarding the difference between (300) and (#300) which I'm sure other users may find useful.

If it is there and I'm just plain blind, is it in the right location for a user to find it easilly?

Also is this the correct thread for posting missing stuff for the manual?

[progressivepenguin]

I believe it's okay to maintain a PDF copy with HTML copy for Zabbix Docs. PDF for printing and HTML for online reading.

Fábio

I agree that PDF documentation (or something similar) is what I'm missing. I can use the html version, but it is not as convenient for me to use as pdfs.

[StanZoid]

There are places, such as in the IT services section (please?), where there is no documentation at all! I would use that if I could figure it out!

Also, the sections on events and platforms are not complete and inconsistent. For example, the log[] function is not there, and the web functions are in some places but not others. Also, the lists by platform are not current with releases.

There are some other areas, like SNMP implementation, where the documentation seems to assume more knowledge on the part of the reader than what is actually there (like me). A more complete explanation would be helpful.

I think a review of hot topics in the forum would also give some idea of what needs more documentation...

StanZoid

[jawanda]

Moreover I wud like to appreciate the "Quick start guide" option, as it greatly helps me a lot in understanding the basics of zabbix, and setting up the initial server.

But Im still unable to understand the some terms, how to set them, like
1. how to make custom parameters ( this section must b included in Quick start guide )
2. wat zabbix can do, must be stated in layman's language, so that one may not confuse in technical terms.

thnx

[Maveric]

Could you document the purpose of "Applications" in the "Configuration\Hosts" menu ?
What is the exact scope of "Applications" ? Can it be used to moniter a distributed (on several host) application ? Any other purposes ?
I could not find any clue in the manual.

Many thanks,

[lcondado]

A "no line" option when creating a connection between two elements in a map would be useful to use two or more connections, each one for a different severity (info, warning, alert). Then, we can see a green line if the severity is warning, or a red line if the severity is alert.
THANKS.

[limo]

I am voting for better help inside frontend..
There are some places where users are lost..

Eg. color of triggers. Sometimes it is red, sometime gree, sometimes blinking. Nobody knows what it means. Did I lost some point of documentation ?
Same with IT services.

[welkin]

http://www.zabbix.com/forum/showthread.php?t=5465
Here's something for the TriggerBlinking :)
mfg
welkin

[bobster]

My overall opinion of the manual is that's simply not thorough enough.

From the beginning of my efforts - even installation of prerequisite software - Apache and PHP along with the godawful missing libphp5.so [Solaris SPARC environment] was a weeklong study onto itself and most of the help I received was from numerous 3rd party articles and webpages NOT the Zabbix documentation. As far as working out bugs or trying to get things working in the front end, the forum was somewhat helpful but there was no clue whatsoever in the main (.pdf) manual that i downloaded along with the original source code.

Even an unorganized collection of 6-10 examples - explaining, for example - how to set up remote commands in the "cookbook section" . It would be far better than the usual format of "syntax chart along with small amount of text that has not been proof-read."

While my opinion of the documentation is low, my opinion of the softare
is very high indeed. Hats off and a big bravo to the developeers.

:cool:

[Vanyuan]

Alo all,

This is absolutely great news!

* How about a quick-start guide on getting zabbix to run for the impatient?
* Tutorials on adding a single trigger, action & item that will better explain how everything fits together?

V.

[kberrien]

My overall opinion of the manual is that's simply not thorough enough.

From the beginning of my efforts - even installation of prerequisite software - Apache and PHP along with the godawful missing libphp5.so [Solaris SPARC environment] was a weeklong study onto itself and most of the help I received was from numerous 3rd party articles and webpages NOT the Zabbix documentation. As far as working out bugs or trying to get things working in the front end, the forum was somewhat helpful but there was no clue whatsoever in the main (.pdf) manual that i downloaded along with the original source code.

Even an unorganized collection of 6-10 examples - explaining, for example - how to set up remote commands in the "cookbook section" . It would be far better than the usual format of "syntax chart along with small amount of text that has not been proof-read."

While my opinion of the documentation is low, my opinion of the softare
is very high indeed. Hats off and a big bravo to the developeers.

:cool:

Well put, and totally agree. People very well might skip the project all together due to poor and inaccurate documentation.

[limo]

Absolutly sure. I ithink it is time to do documentation job now. there are enaught features in 1.4... Better to document anything.

[Niels]

I also agree with bobster. While the manual (pdf) does have a glossary, things simply aren't explained enough. It's often difficult to understand what is meant, if there's any mention at all about one's current problem.

Here's an example:
5.10.3. SNMP Agent
ZABBIX must be configured with SNMP support in order to be able to retrieve data provided by SNMP agents.

A number of question spring to mind:
- Is this a new executable, or just the Zabbix agent?
- Which program must be configured thusly -- the server, the agent or, possibly, the new agent?
- Which program receives what?

[Niels]

1.4 is out (congratulations!) and so is rev 7 of the manual. The manual is obviously not complete and free from errors. Here's an easy one to fix:

In the section about creating the initial database for MySQL, the paths in the manual don't match the ones on the tarball.

[zombiehunter]

1.4 is out (congratulations!) and so is rev 7 of the manual. The manual is obviously not complete and free from errors. Here's an easy one to fix:

In the section about creating the initial database for MySQL, the paths in the manual don't match the ones on the tarball.

I kept getting stuck during/after compilation due to inaccurate install instructions. I'm only partially familiar with compiling my own source so a step-by-step install guide needs to be accurate. This info will help, but what are the correct paths? Another example is that when I went to "make install" it would fail and with recursive errors. Is this related to the broken MySQL paths?

[Niels]

No, make errors are not related to this. The section I'm talking about is where 3 SQL files are loaded into the database. It should read:


shell> mysql -u <username> -p
mysql> create database zabbix;
mysql> quit;
shell> cd create
shell> cat schema/mysql.sql | mysql -u <username> -p zabbix
shell> cat data/data.sql | mysql -u <username> -p zabbix
shell> cat data/images_mysql.sql | mysql -u <username> -p zabbix


It ought to explain how to set up the user and give privileges to the Zabbix database.

[dratliff]

A lot of great input from this forum. I think this forum and it's users should be complimented for the sharing of their knowledge and experience. I have found a lot of great information searching the forums. That has it's draw backs though. It can take about a week to figure out zabbix. I think a quick start guide, a little more thorough documentation and ton's of examples.

I know there is a wiki associated with this site. We use a wiki page within our organization (a county within Minnesota) to organize our data on systems, status and general information. Has anyone expanded that idea to further the wiki concept to the zabbix movement?

I have been documenting the zabbix work I have done in our wiki for all to read. Not that anyone has time to leisurely read wiki entries, but in this scenario, it might help with the documentation effort and provide a great starting point. The cookbook is great, but I think it is lacking some direction. Is the cookbook what is intended to share information?

Just my $0.02 worth.

[zombiehunter]

A lot of great input from this forum. I think this forum and it's users should be complimented for the sharing of their knowledge and experience. I have found a lot of great information searching the forums. That has it's draw backs though. It can take about a week to figure out zabbix. I think a quick start guide, a little more thorough documentation and ton's of examples.

I know there is a wiki associated with this site. We use a wiki page within our organization (a county within Minnesota) to organize our data on systems, status and general information. Has anyone expanded that idea to further the wiki concept to the zabbix movement?

I have been documenting the zabbix work I have done in our wiki for all to read. Not that anyone has time to leisurely read wiki entries, but in this scenario, it might help with the documentation effort and provide a great starting point. The cookbook is great, but I think it is lacking some direction. Is the cookbook what is intended to share information?

Just my $0.02 worth.

Any chance we can peruse the wiki or is it available only to internal users?

[dratliff]

sorry zombie, it is for internal use only on a private network. I can try to export the information maybe.

I guess what I am getting at with using a wiki-based knowledge base is just that. Instead of having to hunt through the forums for information, allow users to post it there. Or have a manager moderate the information and post the data there in a format that is quick and easy to understand.

I would never want to take away the usefulness of the forums though. That is what must be debated, I guess.

[zombiehunter]

I think it's a fantastic idea. With the issues there are right now with the documentation, searching the forums for knowledge to get this up and running and configured properly takes an awful lot of time. The wiki is perfect for this issue. Hopefully getting everyone to use it won't be hard. It's sparse now.

[dratliff]

The goal I think should be to get the documentation load off the developers and put it mainly on the implementors. When new features come out, obviously, the developers will have to document it. This philosophy allows the people who are using zabbix to document solutions and how-to's.

The only problem is that we are going to get 50 wiki pages on how to install it. Therefore there needs to be a moderator for it. Otherwise, it is useless. It would be easier to search the forums.

[Bharathu]

I struggled a lot in zabbix. I still have a long way to go. I need to setup active checks. Then I need to monitor tomacat, web logic, web spehre. I have no idea how to do it.

But iwas successful in setting up passive checks and I was able to monitor windows and Solaris boxes. I made my own 60page document specifically aimed at newbies like me in the field on Unix.

Alexei, if you are interested in viewing my document plz PM me ur email ID as I will send u a copy of it. I even attached all the web page downloads I have come across with my document. There by i want to make this document as one stop solution for UNIX newbies.

[Andreas Bollhalder]

In contrast to the documentation in the ZABBIX Manual v1.4 rev 7 on page 84, the item parameter "sytem.localtime" is working for Windows too.

Andreas

[orla]

Hi
Just startet using Zabbix - still testing.
Installation went pretty much smoothly on CentOS 5 following the Wiki.

Defining working time following the manual, could be more clear, that you have to use
1-2,08:00-16:00;3-3,08:00-18:00;4-5,08:00-16:00;
(3-3 for just one day)
Tried with 1-2,08:00-16:00;3,08:00-18:00;4-5,08:00-16:00;
which is not accepted.

You could in the example list, that one day is 3-3 - or whatever day.

Looking forward to testing the product.

Orla

[Crazy Marty]

One I'd like to see is just exactly how to set up a multi-server arrangement, step by step. I have 5 sites to monitor local machines at, and several (not all) are interconnected via VPNs. I am currently monitoring them all from just 1 server, and I'm very pleased so far, but that server's site is bandwidth limited, so I'd prefer to take advantage of one of the features that does make Zabbix stand out.

I would expect that my starting point isn't terribly different from how others have gone about it, so I would think that a complete guide to converting from a single site to distributed data collection. And then adding all the magic to see that all the links are up.

[cstackpole]

My question is, why is the documentation not readily available for users to easily contribute to? If it is on the Wiki and I missed it, I apologize. However, last I looked, i couldn't find it; if it is on the Wiki it should be more prominent.

The documentation (aka the PDF) should be there for the community to edit and improve. Several times I have seen posts that say "I just found a problem with the documentation. Heres what it should be." I have even made posts like this myself. Sometimes these posts have an acknowledgment and sometimes I look at the latest PDF and find that the change was not made (yet).

Other frustrating posts go something like "I really need to do this. Why isn't it in the PDF documentation?" or "Why does the documentation just say to be filled in / coming soon?" If someone find the answers that should go in those place holders, they should be able to submit that information for the next person who reads the documentation.

Personally, I think that the PDF versions should be snapshots of what is on the wiki. It is already set up for us to edit pages and see who made what changes; so why not just put everything on there? If person A finds a mistake, then they can fix it. If person B thinks that something is missing, they can add it.

I do understand that someone should be in charge of the 'final' PDF snapshot that is taken every x days; that way there are not duplicate entries and everything is kept in proper order. In that regard a wiki may make things a bit more difficult for that person who does the PDF. But at the very least, can there be a forum that is dedicated to user documentation? That way we can make a post and know for certain that the update/edit/fix is going to be implemented in the next version or at least going to be looked at and acknowledged with a reason why the change was not made. A separate forum for documentation would help distinguish between 'i have a problem and I don't know whats wrong' and 'i had a problem, here is the solution and information that may help the next person and should be included in the next PDF'.

The only other improvement that I REALLY want is a better search function on the forums. It is extremely annoying when a search is made and nothing of value is returned (or worse you get the "The following words are either very common, too long, or too short and were not included in your search" message with every term you searched for). Yet the _/exact/_ same search on Google with the site:zabbix.com added to the query returns pretty much exactly what is needed. I guarantee that this hinders newcomers and practicality encourages repeat questions. I try really really hard not to ask repeat / stupid questions that have been answered many times but there are times in which I just can't find the information easily because it isn't in the PDF and I can't find it on the forum. We have all seen those questions submitted and they are greeted with "this was answered here , here, and here". The poster with the problem responds with "Dang. Sorry. That didn't come up in my search and I couldn't find that in the documentation. Oh well. Thanks!"

Maybe its just me and my opinion, but if the same questions keep being asked, then it should be well documented and easily found.

I understand that doing documentation can be a pain in the neck (and lower regions as well) but it is a necessity. Especially since I would rather the developers be working on new features then answering the same questions over and over again.

Anyway, those are my opinions at least :D
Thanks guys! Keep up the good work!
cstackpole

[Alexei]

Give me Wiki style editor having ability to create high quality PDFs (printer ready, references, images in right places, etc) and I will be happy! Any ideas?

[Niels]

Give me Wiki style editor having ability to create high quality PDFs (printer ready, references, images in right places, etc) and I will be happy! Any ideas?
Write it from scratch? ;-)

I think the official (pdf) documentation should be written by developers, and the wiki should be for us users. The official documentation must be consistent and as error-free as possible, and that's not easy with a public wiki. Hopefully the wiki will grow so that it can be a help in writing the manual.

[Alexei]

The official documentation must be consistent and as error-free as possible, and that's not easy with a public wiki. Hopefully the wiki will grow so that it can be a help in writing the manual.
What I would like to avoid is a duplicate effort when synchronizing official documentation with the Wiki. I just do not want to maintain and synchronize two sources of information, the Wiki and the official docs.

[Niels]

What I would like to avoid is a duplicate effort when synchronizing official documentation with the Wiki. I just do not want to maintain and synchronize two sources of information, the Wiki and the official docs.

A wiki is usually made by the community, generally speaking. If you (the developer) want the information there to be ultra correct, up to date and under your control, then you'll have to do the work yourself. But, again, that's not what a wiki is for.

Another solution is to focus on the wiki, helping the community maintain and improve it. Remove the pdf and point to the wiki for information. Use your time and knowledge to manage the wiki.

[cstackpole]

What I would like to avoid is a duplicate effort when synchronizing official documentation with the Wiki. I just do not want to maintain and synchronize two sources of information, the Wiki and the official docs.

I agree. Maintaining two sources would be difficult. Increasing the difficulty is the last thing I want to do to the Zabbix team. My suggestions are there only to inspire some thoughts to improve the documentation and make it easier for the Developers and Users. I may not be familiar enough with the code to help produce patches, but I can certainly read through the documentation and point out potential problems/errors as well as bits of information that can be useful to others. There are many of us like that.

I suggested the wiki because it is already in place ready for users to edit and contribute and those were the best ideas I had at the time. I just want to ensure that the community has the ability to contribute to the documentation and know that the contribution is going to be used or know why the contribution was rejected.

If the wiki is going to be difficult to manage (which I could see being a possibility as I don't have a foolproof plan yet), what about opening another forum? Then any user can post "I have an addition to make to section X.xx" and the document maintainer can post a reply "accepted" or "denied, duplicate information" or "correction has been made". Then every user can make a suggestion, addition, or correction and know that they are being heard by the Zabbix team member in charge of the official documentation.

Again, I don't have a perfect solution. I am just trying to spur on some ideas / debate to help the Zabbix team with documentation. We want to eliminate problems and increase usefulness, right? Any one have thoughts, ideas, potential problems with these ideas that they would like to share?

[fatiha]

Hi,

Why don't you comment php code so that I can generate documentation with phpdocumentor?

Thanks to reply,
Fatiha

[Tenzer]

Why don't you comment php code so that I can generate documentation with phpdocumentor?
Without knowing very much about phpdocumentor, I don't think that you can use it, since Zabbix does not only consist of PHP code, but also have both client and server software written in C.

Another thing is that Zabbix isn't directly targeted for using as a framework like other PHP systems, and as such aren't there any need for documenting the code to the same extend as other projects.

[fatiha]

Maybe you don't understand my recommandation, documentating php code only means adding few lines of comments before every class or method.

See the example below :

<?php
/**
* Documents the class following
* @package SomePackage
*/
class SomeClass {
}
?>




I have already installed phpdocumentor, it works.

more informations (http://manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/tutorial_tags.pkg.html)

Thanks
Fatiha

[nelsonab]

I would *LOVE* to see better documentation of the PHP code. However I don't feel something like PHPDocumentor would be useful for the Zabbix manual. It is not useful for a user to know how the Graph class is used and so forth. They want to know how to use the Chart page.

However for developers, I think this would be great! Just not for users.

[fatiha]

To nelsonab,

I do agree with you as a developer ;) In the frontend, I added the possibility to backup/restore data.

But when I started reading php code I was disappointed :( I need to evoluate the interface and the documentation is very necessary.
-------------
To Tenzer,

I simply need to modify the php interface and I am not talking about C code.

Fatiha

[cedric]

Looking at the C code, it lack of docs, it is sure.

Doxygen is one of the alternatives I would suggest (work with so many languages, and very fine with php and C), there are others.

[fatiha]

Yes, you're right, doxygen is better than phpdocumentor. I installed it and generated documentation of php code.

[cedric]

zabbix doc in pdf is a pain :

* you can not read it in a term
* in a pdfviewer, you can not 'click' the titles
* the summary is not provided in the 'views'

doc in plain text AND in htlm are a 'must have', I think.

[fatiha]

I agree with you, zabbix documentation is very difficult to read.

[bee]

For me, it's good enough! but definetly need more sample of triggers and IT service.
Thanks
BEE

[dan.trainor]

Hi -

I just wanted to bump this thread a bit, because I've spent about an entire week learning the innards of Zabbix, and how we might be able to use it in a production environment.

I think that some more clear and conscience documentation would not only be nice - but rather, completely mandatory. I saw someone say in the forum that there are probably a good number of people who have simply walked away from Zabbix for this very reason, and from a managerial standpoint, I don't think I'd let any of my Juniors implement any sort of software that was not clearly documented. The only reason why we're evaluating Zabbix is because it's power far outweighs its nuances in documentation.

I'll start to contribute a lot to the wiki, since I've found quite a few caveats and discrepancies between the documentation and an actual production, real-world environment. After which time I hope that you all learn something, as well.

Thanks
-dant

[FreeTheMallocs]

I think we all know that the downfall of most open source projects is poor documentation. Developers would much rather write code than documentation. The success of projects like Ubuntu and Gentoo before it have everything to do with the excellent, accessible documentation provided by the projects and the community in the form of wikis and howtos.

I've been extremely disappointed with the documentation (or lack thereof) with Zabbix. Fortunately, I've had some free time at work to muddle through, and found a few of the wiki articles helpful enough to extend my own understanding, but I'm certainly not a typical case. If this project expects to grow, the developers need to do two things, and they need to do them in short order.

1) Develop decent, comprehensive documentation. This is time consuming, but not difficult. The community can be very helpful here. I've seen half a dozen offers to help clean up the documentation and yet none of these are apparently being answered.

2) Fix the inconsistencies within the current code base. There's no way to burn off potential new users faster than code that doesn't work consistently. New features are shiny and all, but if your existing features don't work, as advertised, reliably then you will lose users.

Unless the intent here is to let the user community languish with sub-standard documentation and broken-ness in the hopes that they'll purchase support contracts. One almost has to wonder if this is the case.

[loophole]

I'm missing some informtion on the privileges the mysql user needs for the zabbix database.

For sure it needs: Insert
But what about Update? Also why do we have the check for "Create Table" when running install.php. The drop privilge during this test is for sure due to the create.

Maybe you could fill the needed privileges into the document and remove create an drop from the install. (If not needed for normale usage).

Thanks in advance Loophole

[vikty]

Hi,

In the site is ther the db's zabbix schema documantation?
an explanation on the means of the fields tables....

[nelsonab]

Hi,

In the site is ther the db's zabbix schema documantation?
an explanation on the means of the fields tables....

There isn't one on the recent tables, however the 1.0 docs do have one.

[timmix]

Hello,

I'd managed a installation of ZABBIX and it runs fine (as far as I know). But reading the manual is almost to technical AND the pictures are most useless because nobody can read the text in them.

I.e. in the manual (section 11.5, Real life scenarios) you wrote (Step 3) "Add steps for monitoring", but the exact syntax is only showed in the screenshot and by kompression of PDF it isn't readable. It's frustating.

I accede to some posters before that a manual in HTML format and with UNCOMPRESSED pictures would be helpful.

I believe that ZABBIX is a great and powerfull tool, but at time I'm frustated with the configuration of everything, because I didn't know the exact syntax of quite everything in ZABBIX. :-/

Thank you

[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 (http://www.zabbix.com/forum/../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.

:p

[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?id=triggers_and_actions_and_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]

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:rolleyes:

[Zarastro]

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]

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]

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]

[NOB]

Hi

we use something like
awk '{printf $ 6}'

Notice the blank / space after the $.
Seems to work fine, too.

Regards

Norbert.

[sgbeal]

That approach seems scary, though. Using a space _after_ the $ to escape it is extremely non-conventional (and difficult to see), whereas $$ is used in tools like Make and Ant and many others, and has (IMO) a much more intuitive meaning. When using a space in this way, every example which uses this must (for clarity's sake) include the disclaimer "note the extra space _after_ the dollar!", whereas $$ has a clear meaning to anyone who's used Make, Ant, or any number of other tools which escape using double-dollars.

PS: and it could just be that "$<SPACE>1" is a feature of awk, and may not work in all languages which use $var. That said:

stephan@jareth:~$ perl -e 'print $ ENV{"HOME"};'
/home/stephanstephan@jareth:~$

(disclaimer: note the extra space _after_ the $)

it appears to be a feature of awk/perl. Shell code certainly doesn't allow that, though:

stephan@jareth:~$ echo $ HOME
$ HOME


(disclaimer: note the extra space _after_ the $)

(See, the disclaimer gets annoying ;)

[rosen]

i thought i would be starting a new thread. here's what i thought
would be a new topic.
RE: docs

i'm a newbie to zabbix and i'm finding that the docs don't help me
much. i've reached the point where it looks like penetrating the
docs is going to consume more time than i can justify. if there's
someone out there who can actually __change__ the docs then i'm
willing to help you change them by playing the naive rat and
pointing out what doesn't make sense to a newbie. however, just
hand-holding me w/o changing the docs seems like a waste.

i had, and have, lots of problems w/ zabbix because i've had to guess
at all kinds of things. any of several guesses could be wrong.
thus, even if i correct one error, i may not be able to tell i've
corrected anything if other errors prevent zabbix from working.
in this particular case i was able to blunder along to finally get something
going, but it took much longer than it should have. and i'm not convinced
that what's working -- is actually working the way it should.

this particular one came up with trying to use an external check.

chapter 4.10.8 of the manual, and most of the stuff i found online
will tell you to put the script in the place named by the
parameter ExternalScripts. and that's about all they tell you.

where's ExternalScripts? 4.10.8 says it's in the configuration,
but, of course, that could mean something we did at configure time
(ie, running the configure script--and we ran the configure script
more than once to get a server and an agentd). or it could mean the agentd
config, or the server config. answer, it's the server config file
/etc/zabbix/zabbix_server.conf. that should be in the docs.

where does the script go? yeah, yeah, we just talked about
ExternalScripts, but on which __machine__? it's not unreasonable
for it to be on the server. the zabbix_server.conf file that decides where
the __client__ directory resides is on the server. correct = client.
the server's config file tells the clients where their directory
should be. that should be in the docs. [off topic, seems to me
that each client could decide for itself -- in a sense we're
only deciding the PATH on the client. can't the clients
configure ExternalScripts in their agentd.conf? that's a design quibble.
but you can see how a newbie would get confused.]

when the script runs, what user will be running it?
answer == zabbix, or maybe daemon, but it won't hurt to remind the poor newbie.
the newbie may have something that needs to run as another user.
it's the newbie's job to figure out how to cope. but they should
be told where they're starting from.

4.10.8 says shell or binaries will run, but if you're scratching
your head to figure out what's wrong, you'll start to wonder
if the docs are right about that. can we use sh, bash, csh,
perl, python, what? answer = yeah, any shell, and any binary,
w/in the limits of running as user=zabbix, w/ whatever environment
you get. but the thing must live in ExternalScripts -- even what
you'd find in the PATH won't be found. (i think.)

if you try a shell that isn't on the client, what will the
zabbix web interface say?

here's one that makes me angry: whatever value you want to
return, how do you return it? in desperation i wound up doing this:
echo 40
exit 40
in order to get my test script to do __something__, __anything__.
is it stdout? or the exit value? all i really know is that
something happened, finally. can you return something besides
a number? a string? how? [i know, i could run some more experiments
to answer the echo/exit question. but if i'm about to decide to
drop zabbix it won't matter.]

what mode should the script be? who should own it? answer =
something that the zabbix user can find w/ whatever the environment
looks like. same questions for the dir ExternalScripts points to.
answer = well, this is somewhat a policy question. what do the experts
recommend? to get something to happen i opened these wide, too wide.

you've just put in a new script. do you have to start/stop
anything to get it noticed? any particular order? i flailed
around a long time. nothing was working. in general, how do you get
an external script tested? answer = i don't know. it finally
did, but i don't know what i did that got it going.

early in my floundering the zabbix web interface said this to me:
configuration-->items
"script ... returned nothing."
and that "external checks aren't supported"?
then how does it know it returned nothing? this combination of
msgs makes you doubt what zabbix tells you, and doubt the docs.
i'm not saying that the web interface should debug the script,
or even say whether it found it. but the docs should tell you
that "this list of things" will cause that message. as it stands
"not supported" means (practically) don't even try any external script.
IIRC the msg really meant (at the time) that it (presumably agentd) didn't
find the script on the client.

this is getting under my skin because zabbix looks like it would
help me w/ a problem i have right now. but i have so many zabbix
questions that i can't predict how long it will take me to get
zabbix going, which in turn makes it difficult to justify spending
time on zabbix.

okay, i'll shut up now.

j.

[vellintilteft]

ok, I see one mistake I made. I was looking at the users guide for the BL4S200 not the BL2600. the BL 2600 has some documentation for the function in question.

So now the question begs to be asked, what does the BL4s200 do for digOutConfig???

[cls]

Would it be possible to move the detail tables to an appendix at the end? Maybe the manual would make more sense that way. When I am trying to figure out where to type in a trigger expression, I do not need a five page table of every possible operator I could use in a trigger expression.

Try to imagine that you do not know what the structure of Zabbix is.
You know there is an agent on one host and a server on another host.
Now you want to describe to the server that it should monitor a few things on a the other host. There is nothing in the admin gui that would tell you how to GET STARTED doing that. You just have to GUESS.

Software where the new user has to GUESS is not user friendly. Maybe he has to read a manual. But you should not expect him to suck the 315 page manual into his brain and compile it there. There is too much detail for that. Please give us a 15 page manual and move all the detail to appendixes.

[richlv]

Would it be possible to move the detail tables to an appendix at the end? Maybe the manual would make more sense that way. When I am trying to figure out where to type in a trigger expression, I do not need a five page table of every possible operator I could use in a trigger expression.


that's a pretty good point - while it's probably easier to use in online version, exported versions would still benefit from such a change notably

[warrior.liu]

Hi guys!
I looked the zabbix manual about web monitoring and according to page 213 to 216 setting the web monitoring,but it's not succesful!
I looed the log file find error message :Error doing curl_ease_perform [a timeout was reached]


Thanks for somebody help me!:mad:

[bigmac]

Some words in general: there should be real-life examples in HOWTO section of the manual, i.e. how to setup web monitoring, how to make discovery work, etc

There are lot of black holes in documentation, including:


No information on Units in Items creation menu:
1. What are types available
2. How to use SI standard (kilo-mega-giga) and 1024-based (kibi-mebi-gibi) modifiers
3. How to disable Zabbix using invalid modifiers and show values in eng/sci/fixed format

Make Acknowledgement section more clear and understandable.


No information on using 1.8.2 features like host group selections in dashboards, etc

[mma]

Hello,

I found the French documentation a bit light. Can I add some documentation in french (my native language ;-) ) ?
I want add informations about web monitoring.

[richlv]

I found the French documentation a bit light. Can I add some documentation in french (my native language ;-) ) ?
I want add informations about web monitoring.

currently it is encouraged to translate english manual instead of writing completely new material, because that would soon become impossible to synchronise. would you be interested in that ?

[mma]

I have a lot of work and my English is approximative but why not !
Say me if I'm wrong but pictures in this page aren't pertain to the latest version : http://www.zabbix.com/documentation/1.8/manual/web_monitoring
I don't see the "new" option "Basic Authentification"...?

[niumar]

I think that more explanations about proxys and IT services would be also interesting.

[just4fun]

Hello,

I don't know whether this has alredy been mentioned and whether this
is "allowed" to do here, but what helped me the most to get familiar with
Zabbix is the book:

"Zabbix 1.8 Network Monitoring" (ISBN: 978-1-847197-68-9)

It's a complete step-by-step introduction in monitoring with Zabbix and explain
all the things you need to know in a very clear way!

Christian

[zychonatic]

hi,

i want to do an active/active solution, but there is not a good explaination in the wiki or documentation.
http://www.zabbix.com/wiki/howto/config/ha/highavailability

if possible can someone add this

thx

best regards

[richlv]

ok, so everybody who wants to give some feedback on zabbix manual - especially the structure of it - see http://blog.zabbix.com/rebooting-zabbix-manual ;)