zabbix/limosek-zaf
1
0
Fork 0
mirror of https://github.com/limosek/zaf.git synced 2024-11-21 18:09:06 +01:00
Code Issues Releases Wiki Activity

Rewrited readme

Browse Source
This commit is contained in:
Lukas Macura 2016-04-04 16:08:07 +02:00
parent 5c3338fdb9
commit 604c247777
3 changed files with 76 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

105
README.md
View File

@ -5,57 +5,96 @@ But there is problem with installation, update and centralised management. This
install and configure zabbix agent on systems with one step. Primary goal is not to make all plugins available here but to be able to use any plugin and decentralized development.
If you are maintainer of some external check, it is enough to create zaf file in your repo and use zaf installer everywhere.
## Motivation
Did you install lot of zabbix agents? Do you want to setup them all? Do you want to change some zabbix agent options on lot of system? Do you want to write your own simple check or discovery rule for zabbix and it is nightmare to deploy same script on more zabbix agents? Are you tired searching some system specific agent check and setup them individualy?
So zaf is here for you :)
## Features
* Minimal dependencies. At this time, only sh, sed, awk and curl
* Minimal code (less than 50kb of code)
* Minimal runtime version to fit on different systems (openwrt, debian, ubuntu, ...)
* Modular. Zaf module can be maintained externaly from this framework
* Sharing code. Many zabbix external checks share common shell functions.
* Simplification of userparameter functions (does not have to be one-line long code)
* Zabbix discovery simplification. Creating zabbix item for discovery is not so easy in shell based system and result is not nice. But you can use framework function to do so.
* OS packaging support.
* OS packaging support (in future).
* Zabbix agent autoinstallation and autoconfiguration suitable to use in puppet or another tool
## Installing Zaf
You need to be root and you must have curl installed on your system. Depending on your system, github certificates may not be available so you have to use *-k* option for curl (insecure). Default installation type is silent. So there will be no questions and everything will be autodetected. This command should be used on most systems:
```
curl https://raw.githubusercontent.com/limosek/zaf/master/install.sh | sh
```
but in openwrt, you should use this:
You need to be root and you must have curl installed on your system. Depending on your system, github certificates may not be available so you have to use *-k* option for curl (insecure). Default installation type is silent. So there will be no questions and everything will be autodetected. This simple command should be used on most systems:
```
curl -k https://raw.githubusercontent.com/limosek/zaf/master/install.sh | sh
```
## Example
Best way how to explain everything is example. Supposing we are working on debian-like system.
### Install options and autoconfiguration
General parameters for install.sh on any system (simplest way how to install)
```
curl https://raw.githubusercontent.com/limosek/zaf/master/install.sh | sudo sh
sudo zaf install process-info
sudo zaf install http://other.check.domain/check/
zaf make-deb
zaf make-opkg
zaf make-rpm
zaf self-upgrade
curl -k https://raw.githubusercontent.com/limosek/zaf/master/install.sh | sh -s {auto|interactive|debug-auto|debug-interactive} [Agent-Options] [Zaf-Options]
```
or use git version:
```
git clone https://github.com/limosek/zaf.git
./install.sh {auto|interactive|debug-auto|debug-interactive} [Agent-Options] [Zaf-Options]
Agent-Options: A_Option=value [...]
Zaf-Options: ZAF_OPT=value [...]
```
So you can pass ANY configuration of your zabbix agent directly to installer. Installer will try to autoguess suitable config options for your system.
Now everything was tested on Debian and OpenWrt. If somebody is interrested in, you can help and test with some rpm specific functions.
### Example
Suppose you want to autoinstall agent on clean system. You need only curl installed. Everything else is one-cmd process.
This command will install zaf, install zabbix-agent if necessary and sets zabbix variables on agent to reach server. This command can be automatized by puppet or another deploying system.
```
curl -k https://raw.githubusercontent.com/limosek/zaf/master/install.sh | sh -s Z_Server=zabbix.server.local Z_ServerActive=zabbix.server.local Z_HostnameItem=system.hostname Z_RefreshActiveChecks=60 ZAF_PLUGINS_GITURL="git://gitserver.local"
```
## Zaf plugin
Zaf plugin is set of configuration options and binaries which are needed for specific checks. For example, to monitor postfix, we need some cron job which is automaticaly run and next ti this, some external items which has to be configured.
Zaf plugin is set of configuration options and binaries which are needed for specific checks. For example, to monitor postfix, we need some cron job which is automaticaly run and next ti this, some external items which has to be configured. Do not mix zaf plugin and zabbix plugin. While zaf plugin is set of scripts or binaries external to zabbix agent, zabbix plugin is internal zabbix lodadable module.
## Zaf utility
Zaf binary can be installed on any system from openwrt to big system. It has minimal dependencies and is shell based. Is has minimal size (up to 50kb of code). It can be used for installing, removing and testing zaf plugin items. Zaf should be run as root.
```
zaf
/usr/bin/zaf Version trunk. Please use some of this commands:
/usr/bin/zaf update To update repo
/usr/bin/zaf plugins To list installed plugins
/usr/bin/zaf show [plugin] To show installed plugins or plugin info
/usr/bin/zaf items [plugin] To list all suported items [for plugin]
/usr/bin/zaf test [plugin[.item]] To test all suported items [for plugin]
/usr/bin/zaf install plugin To install plugin
/usr/bin/zaf remove plugin To remove plugin
/usr/bin/zaf self-upgrade To self-upgrade zaf
/usr/bin/zaf self-remove To self-remove zaf and its config
```
### Installing plugin
To install plugin from common repository. If git is available, local git repo is tried first. If not, remote https repo is tried second.
```
zaf install zaf
```
To install plugin from external source, external plugin has to be "zafable". This means that its maitainer will create control.zaf file located at http://some.project/plugin/control.zaf. Nothing else.
```
zaf install http://some.project/plugin
```
To install plugin from local directory:
```
zaf install /some/plugin
```
Installer will look into control file, run setup task defined there, fetch binaries and scripts needed for specific plugin and test system dependencies for that plugin. If everything is OK, zaf_plugin.conf is created in zabbix_agentd.d conf directory and userparameters are automaticaly added.
## How it works
There is central zaf reposirory on github. There are basic checks and zaf code itself. Next to this, each project can have its own zaf structure. Adding url of plugin to zaf will make it useable and updatable.
## Zaf plugin structure
Each zaf plugin url MUST have this items:
```
/plugin/README.md # Documentation
/plugin/control # Control file
/plugin/template.xml # Template for Zabbix
```
## Zaf control file
Control files are similar to Debian Control files
```
will be explained
```
Zaf installer will do most of actions needed to monitor some specific plugin items. Configuration of plugin is very simple and text readable. Anybody can write its own plugin or make its plugin "zafable". It is enough to create *control.zaf" file. For example, look into https://github.com/limosek/zaf-plugins repository. This is default repository for zaf.
## I want to make my own plugin!
Great! Look into https://github.com/limosek/zaf-plugins repository, look to control files and try to create your own. It is easy! You can contact me for help.
## I want to help with zaf!
Great! I have no time for testing on systems and writing system specific hacks. Next to this, templates should be optimized and tested for basic plugins.

6
install.sh
View File

@ -171,8 +171,8 @@ zaf_configure(){
zaf_get_option ZAF_AGENT_BIN "Zabbix agent binary" "/usr/sbin/zabbix_agentd" "$1"
zaf_get_option ZAF_AGENT_RESTART "Zabbix agent restart cmd" "service zabbix-agent restart" "$1"
if zaf_is_root && ! which $ZAF_AGENT_BIN >/dev/null; then
zaf_err "Zabbix agent not installed? Use ZAF_ZABBIX_AGENT_BIN env variable to specify location. Exiting."
if zaf_is_root && ! [ -x $ZAF_AGENT_BIN ]; then
zaf_err "Zabbix agent ($ZAF_AGENT_BIN) not installed? Use ZAF_AGENT_BIN env variable to specify location. Exiting."
fi
[ -n "$INSTALL_PREFIX" ] && zaf_install_dir "/etc"
@ -250,7 +250,7 @@ install)
zaf_install_dir ${ZAF_PLUGINS_DIR}
zaf_install_dir ${ZAF_BIN_DIR}
zaf_install_bin $(zaf_getrest zaf) ${ZAF_BIN_DIR}
export INSTALL_PREFIX ZAF_CFG_FILE
export INSTALL_PREFIX ZAF_CFG_FILE ZAF_DEBUG
if zaf_is_root; then
[ "${ZAF_GIT}" = 1 ] && ${INSTALL_PREFIX}/${ZAF_BIN_DIR}/zaf update
${INSTALL_PREFIX}/${ZAF_BIN_DIR}/zaf reinstall zaf || zaf_err "Error installing zaf plugin."

1
zaf
View File

@ -33,6 +33,7 @@ check-agent-config)
;;
update)
zaf_wrn "Updating repository ${ZAF_PLUGINS_GITURL}..."
zaf_update_repo
;;