Skip to content

Commit 096d574

Browse files
aiantsenaiantsen
committed
Initial commit
0 parents  commit 096d574

38 files changed

+3212
-0
lines changed

‎.gitignore

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Editors
2+
.vscode
3+
.idea
4+
5+
# Compiled
6+
__pycache__/
7+
*.py[cod]
8+
*$py.class
9+
10+
# Packaging
11+
build/
12+
develop-eggs/
13+
dist/
14+
*.egg-info/
15+
16+
# Environments
17+
.env
18+
.venv

‎CHANGELOG.md

Whitespace-only changes.

‎LICENSE

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
MIT License
2+
3+
Copyright (C) 2001-2023 Zabbix SIA
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy of
6+
this software and associated documentation files (the "Software"), to deal in
7+
the Software without restriction, including without limitation the rights to use,
8+
copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
9+
Software, and to permit persons to whom the Software is furnished to do so,
10+
subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
17+
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS
18+
OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
19+
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
20+
IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

‎README.md

+193
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
# Zabbix utils library
2+
3+
**zabbix_utils** is a Python library for working with [Zabbix API](https://www.zabbix.com/documentation/current/manual/api/reference) as well as with [Zabbix sender](https://www.zabbix.com/documentation/current/manpages/zabbix_sender) and [Zabbix get](https://www.zabbix.com/documentation/current/manpages/zabbix_get) protocols.
4+
5+
## Get started
6+
* [Requirements](#requirements)
7+
* [Installation](#installation)
8+
* [Zabbix API](#to-work-with-zabbix-api)
9+
* [Zabbix Sender](#to-work-via-zabbix-sender-protocol)
10+
* [Zabbix Get](#to-work-via-zabbix-get-protocol)
11+
* [Debug log](#enabling-debug-log)
12+
13+
## Requirements
14+
15+
Supported versions:
16+
17+
* Zabbix 5.0+
18+
* Python 3.10+
19+
20+
Tested on:
21+
22+
* Zabbix 4.0, 5.0, 6.0, 6.4 and 7.0
23+
* Python 3.7, 3.8, 3.9, 3.10 and 3.11
24+
25+
## Documentation
26+
27+
### Installation
28+
29+
Install **zabbix_utils** library using pip:
30+
31+
```bash
32+
$ pip install zabbix_utils
33+
```
34+
35+
### Use cases
36+
37+
##### To work with Zabbix API
38+
39+
To work with Zabbix API you can import and use **zabbix_utils** library as follows:
40+
41+
```python
42+
from zabbix_utils import ZabbixAPI
43+
44+
api = ZabbixAPI(url="127.0.0.1")
45+
api.login(user="User", password="zabbix")
46+
47+
users = api.user.get(
48+
output=['userid', 'alias']
49+
)
50+
51+
for user in users:
52+
print(user['alias'])
53+
54+
api.logout()
55+
```
56+
57+
You can also authenticate using an API token (supported since Zabbix 5.4):
58+
59+
```python
60+
from zabbix_utils import ZabbixAPI
61+
62+
api = ZabbixAPI(url="127.0.0.1")
63+
api.login(token="xxxxxxxx")
64+
65+
users = api.user.get(
66+
output=['userid', 'alias']
67+
)
68+
69+
for user in users:
70+
print(user['alias'])
71+
72+
api.logout()
73+
```
74+
75+
You can compare Zabbix API version with strings and numbers, for example:
76+
77+
```python
78+
from zabbix_utils import ZabbixAPI
79+
80+
url = "127.0.0.1"
81+
user = "User"
82+
password = "zabbix"
83+
84+
api = ZabbixAPI(url=url, user=user, password=password)
85+
86+
# Method to get version
87+
ver = api.api_version()
88+
print(type(ver).__name__, ver) # ZabbixAPIVersion 7.0.0
89+
90+
# ZabbixAPI prototype with version
91+
ver = api.version
92+
print(type(ver).__name__, ver) # ZabbixAPIVersion 7.0.0
93+
94+
# Comparing versions
95+
print(ver > 6.0) # True
96+
print(ver != 7.0) # False
97+
print(ver <= 7) # True
98+
print(ver != "7.0.0") # False
99+
100+
# Version additional methods
101+
print(ver.major) # 7.0
102+
print(ver.minor) # 0
103+
print(ver.is_lts()) # True
104+
105+
api.logout()
106+
```
107+
108+
> Please, refer to the [Zabbix API Documentation](https://www.zabbix.com/documentation/current/manual/api/reference) and the [using examples](https://github.com/zabbix/python-zabbix-utils/tree/master/examples/api) for more information.
109+
110+
##### To work via Zabbix sender protocol
111+
112+
To send item values to a Zabbix server or a Zabbix proxy you can import and use the library as follows:
113+
114+
```python
115+
from zabbix_utils import ZabbixSender
116+
117+
sender = ZabbixSender(server='127.0.0.1', port=10051)
118+
resp = sender.send_value('host', 'item.key', 'value', 1695713666)
119+
120+
print(resp)
121+
# {"processed": 1, "failed": 0, "total": 1, "time": "0.000338", "chunk": 1}
122+
```
123+
124+
Or you can prepare a list of item values and send all at once:
125+
126+
```python
127+
from zabbix_utils import ZabbixItem, ZabbixSender
128+
129+
items = [
130+
ZabbixItem('host1', 'item.key1', 10),
131+
ZabbixItem('host1', 'item.key2', 'test message'),
132+
ZabbixItem('host2', 'item.key1', -1, 1695713666),
133+
ZabbixItem('host3', 'item.key1', '{"msg":"test message"}'),
134+
ZabbixItem('host2', 'item.key1', 0, 1695713666, 100)
135+
]
136+
137+
sender = ZabbixSender(server='127.0.0.1', port=10051)
138+
chunks_resp = sender.send(items)
139+
140+
print(chunks_resp)
141+
# [{"processed": 5, "failed": 0, "total": 5, "time": "0.001661", "chunk": 1}]
142+
```
143+
144+
> Please, refer to the [Zabbix sender protocol](https://www.zabbix.com/documentation/current/manual/appendix/protocols/zabbix_sender) and the [using examples](https://github.com/zabbix/python-zabbix-utils/tree/master/examples/sender) for more information.
145+
146+
##### To work via Zabbix get protocol
147+
148+
To get a value by item key from a Zabbix agent or agent 2 you can import and use the library as follows:
149+
150+
```python
151+
from zabbix_utils import ZabbixGet
152+
153+
agent = ZabbixGet(host='127.0.0.1', port=10050)
154+
resp = agent.get('system.uname')
155+
156+
print(resp)
157+
# Linux test_server 5.15.0-3.60.5.1.el9uek.x86_64
158+
```
159+
160+
> Please, refer to the [Zabbix agent protocol](https://www.zabbix.com/documentation/current/manual/appendix/protocols/zabbix_agent) and the [using examples](https://github.com/zabbix/python-zabbix-utils/tree/master/examples/get) for more information.
161+
162+
### Enabling debug log
163+
164+
If it needed to debug some issue with Zabbix API, sender or get you can enable the output of logging. The **zabbix_utils** library uses the default python logging module, but it logs to the `null` by default. You can define logging handler to see records from the library, for example:
165+
166+
```python
167+
import logging
168+
from zabbix_utils import ZabbixGet
169+
170+
logging.basicConfig(
171+
format=u'[%(asctime)s] %(levelname)s %(message)s',
172+
level=logging.DEBUG
173+
)
174+
175+
agent = ZabbixGet(host='127.0.0.1', port=10050)
176+
resp = agent.get('system.uname')
177+
178+
print(resp)
179+
```
180+
181+
And then you can see records like the following:
182+
183+
```
184+
[2023-10-01 12:00:01,587] DEBUG Content of the packet: b'ZBXD\x01\x0c\x00\x00\x00\x00\x00\x00\x00system.uname'
185+
[2023-10-01 12:00:01,722] DEBUG Zabbix response header: b'ZBXD\x01C\x00\x00\x00C\x00\x00\x00'
186+
[2023-10-01 12:00:01,723] DEBUG Zabbix response body: Linux test_server 5.15.0-3.60.5.1.el9uek.x86_64
187+
[2023-10-01 12:00:01,724] DEBUG Response from [127.0.0.1:10050]: Linux test_server 5.15.0-3.60.5.1.el9uek.x86_64
188+
Linux test_server 5.15.0-3.60.5.1.el9uek.x86_64
189+
190+
```
191+
192+
## License
193+
**zabbix_utils** is distributed under MIT License.

‎examples/api/auth_by_token.py

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
from zabbix_utils import ZabbixAPI
2+
3+
# Use an authentication token generated via the web interface or
4+
# API instead of standard authentication by username and password.
5+
ZABBIX_AUTH = {
6+
"url": "127.0.0.1",
7+
"token": "8jF7sGh2Rp4TlQ1ZmXo0uYv3Bc6AiD9E"
8+
}
9+
10+
# Create an instance of the ZabbixAPI class with the specified authentication details
11+
api = ZabbixAPI(**ZABBIX_AUTH)
12+
13+
# Retrieve a list of users, including their user ID and alias
14+
users = api.user.get(
15+
output=['userid', 'alias']
16+
)
17+
18+
# Print the aliases of the retrieved users
19+
for user in users:
20+
print(user['alias'])

‎examples/api/check_auth_state.py

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
from zabbix_utils import ZabbixAPI
2+
3+
# Zabbix server details and authentication credentials
4+
ZABBIX_AUTH = {
5+
"url": "127.0.0.1", # Zabbix server URL or IP address
6+
"user": "Admin", # Zabbix user name for authentication
7+
"password": "zabbix" # Zabbix user password for authentication
8+
}
9+
10+
# Create an instance of the ZabbixAPI class with the specified authentication details
11+
api = ZabbixAPI(**ZABBIX_AUTH)
12+
13+
# Some actions when your session can be released
14+
# For example, api.logout()
15+
16+
# Check if authentication is still valid
17+
if api.check_auth():
18+
# Retrieve a list of hosts from the Zabbix server, including their host ID and name
19+
hosts = api.host.get(
20+
output=['hostid', 'name']
21+
)
22+
23+
# Print the names of the retrieved hosts
24+
for host in hosts:
25+
print(host['name'])
26+
27+
# Logout to release the Zabbix API session
28+
api.logout()

‎examples/api/disabling_validate_certs.py

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
from zabbix_utils import ZabbixAPI
2+
3+
# SSL certificate verification will be ignored.
4+
# This can be useful in some cases, but it also poses security risks because
5+
# it makes the connection susceptible to man-in-the-middle attacks.
6+
ZABBIX_AUTH = {
7+
"url": "127.0.0.1",
8+
"user": "Admin",
9+
"password": "zabbix",
10+
"validate_certs": False
11+
}
12+
13+
# Create an instance of the ZabbixAPI class with the specified authentication details
14+
# Note: Ignoring SSL certificate validation may expose the connection to security risks.
15+
api = ZabbixAPI(**ZABBIX_AUTH)
16+
17+
# Retrieve a list of users from the Zabbix server, including their user ID and alias
18+
users = api.user.get(
19+
output=['userid', 'alias']
20+
)
21+
22+
# Print the aliases of the retrieved users
23+
for user in users:
24+
print(user['alias'])
25+
26+
# Logout to release the Zabbix API session
27+
api.logout()

‎examples/api/export_templates.py

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
from zabbix_utils import ZabbixAPI
2+
3+
# Zabbix server details and authentication credentials
4+
ZABBIX_AUTH = {
5+
"url": "127.0.0.1", # Zabbix server URL or IP address
6+
"user": "Admin", # Zabbix user name for authentication
7+
"password": "zabbix" # Zabbix user password for authentication
8+
}
9+
10+
# Template IDs to be exported
11+
TEMPLATE_IDS = [10050]
12+
13+
# File path and format for exporting configuration
14+
FILE_PATH = "templates_export_example.{}"
15+
16+
# Create an instance of the ZabbixAPI class with the specified authentication details
17+
api = ZabbixAPI(**ZABBIX_AUTH)
18+
19+
# Determine the file extension based on the Zabbix API version
20+
FILE_EXTENSION = "yaml"
21+
if api.version < 5.4:
22+
FILE_EXTENSION = "xml"
23+
24+
# Export configuration for specified template IDs
25+
configuration = api.configuration.export(
26+
options={
27+
"templates": TEMPLATE_IDS
28+
},
29+
format=FILE_EXTENSION
30+
)
31+
32+
# Write the exported configuration to a file
33+
with open(FILE_PATH.format(FILE_EXTENSION), mode='w', encoding='utf-8') as f:
34+
f.write(configuration)
35+
36+
# Logout to release the Zabbix API session
37+
api.logout()

‎examples/api/skip_version_check.py

+39
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
from zabbix_utils import ZabbixAPI
2+
3+
# Use ZabbixAPI with skipping the version check
4+
# This can be useful in some cases when your Zabbix API version is
5+
# unsupported by the zabbix_utils, but you're sure it will work properly.
6+
with ZabbixAPI(url="127.0.0.1", skip_version_check=True) as api:
7+
# Authenticate with the Zabbix API using provided user credentials
8+
api.login(user="Admin", password="zabbix")
9+
10+
# Print the full Zabbix API version
11+
print(api.version)
12+
13+
# Print the major version component
14+
print(api.version.major)
15+
16+
# Print the minor version component
17+
print(api.version.minor)
18+
19+
# Check if the Zabbix API version is a Long Term Support (LTS) release
20+
print(api.version.is_lts())
21+
22+
# Use ZabbixAPI with the default behavior (version check enabled)
23+
# Default behavior is that ZabbixNotSupported exception will
24+
# be raised for unsupported Zabbix API versions.
25+
with ZabbixAPI(url="127.0.0.1") as api:
26+
# Authenticate with the Zabbix API using provided user credentials
27+
api.login(user="Admin", password="zabbix")
28+
29+
# Print the full Zabbix API version
30+
print(api.version)
31+
32+
# Print the major version component
33+
print(api.version.major)
34+
35+
# Print the minor version component
36+
print(api.version.minor)
37+
38+
# Check if the Zabbix API version is a Long Term Support (LTS) release
39+
print(api.version.is_lts())

0 commit comments

Comments
 (0)