1Metadata-Version: 2.1
2Name: pybix
3Version: 0.0.8
4Summary: Python based Zabbix API utility with helper functions
5Home-page: https://github.com/mattykay/pybix
6Author: Matthew Kalnins
7Author-email: pybix@matthewkalnins.com
8License: UNKNOWN
9Description: # pybix
10
11        **NOTE: This module is still in development and may not be fully stable. Use at own risk.**
12
13        ## Description
14
15        Python based Zabbix API utility containing helper functions and CLI capabilities.
16
17        Takes inspiration from existing Python-Zabbix API modules like [lukecyca/pyzabbix](https://github.com/lukecyca/pyzabbix) and [adubkov/py-zabbix](https://github.com/adubkov/py-zabbix).
18
19        While this module can be used in a similar way, the aim is to add a few out of the box helper functions and CLI handling for a more "batteries included" module. For example GraphImage as described in usage which enables saving Zabbix graphs which is not possible via the API at this time.
20
21        ## Install
22
23        ### Pip
24
25        ```
26        pip install pybix
27        ```
28
29        ### Docker
30
31        TODO - not yet available.
32
33        ## Requirements
34
35        * Python 3.6 or greater
36        * Zabbix 2.0 or greater
37          * Only tested on >4.0
38
39        ## Usage
40
41        ### Zabbix API
42
43        Refer to [Zabbix Offical API object](https://www.zabbix.com/documentation/4.2/manual/api/reference) references for objects that can be queried and their parameters.
44
45        API structure all uses format like `ZAPI.<object>.<action>(<parameters>)` e.g. `ZAPI.host.get(output='extend')`.
46
47        #### Import as Python module
48
49        ##### Directly
50
51        ```python
52        from pybix import ZabbixAPI
53        ZAPI = ZabbixAPI(url="http://localhost/zabbix")
54        ZAPI.login(user="Admin", password="zabbix")
55
56        # Print all monitored hosts
57        for host in ZAPI.host.get(output="extend",monitored_hosts=1):
58            print(host['host'])
59
60        ZAPI.logout() # Explicitly logout to clear Zabbix session
61        ```
62
63        ##### With context manager to handle logout
64
65        Note: Login still must be done manually (as in the future we may allow passing existing session, hence might not need to login everytime).
66
67        ```python
68        from pybix import ZabbixAPI
69
70        with ZabbixAPI() as ZAPI: # using defaults for server
71            ZAPI.login() # using defaults for user, password
72
73            # Print all monitored hosts
74            for host in ZAPI.host.get(output="extend",monitored_hosts=1):
75                print(host['host'])
76        ```
77
78        #### Zabbix API CLI
79
80        ##### Zabbix API CLI Usage
81
82        ```bash
83        Usage:
84            pybix.py <method> [--zabbix-server=ZABBIX_SERVER] [--zabbix-user=ZABBIX_USER]
85                    [--zabbix-password=ZABBIX_PASSWORD] [--ssl-verify] [(-v | --verbose)] [<args> ...]
86            pybix.py (-h | --help)
87            pybix.py --version
88
89        Arguments:
90          method        either Zabbix API reference as '<object>.<action>' or GraphImage API as 'graphimage.<search_type>' (e.g. 'host.get' or 'graphimage.graph_id')
91          args          what arguments to pass to API call
92
93        Options:
94          -h, --help
95          --version
96          -v, --verbose                      Whether to use verbose logging [default: False]
97          --output-path=PATH                 Where to save graphs to default: cwd
98          --zabbix-server=ZABBIX_SERVER      [default: https://localhost/zabbix]
99          --zabbix-user=ZABBIX_USER          [default: Admin]
100          --zabbix-password=ZABBIX_PASSWORD  [default: zabbix]
101          --ssl-verify                       Whether to use SSL verification for API [default: True]
102        ```
103
104        ##### Zabbix API CLI Example
105
106        ```bash
107        python -m pybix host.get filter="{host:server1}" # Get host server1
108        python -m pybix host.get filter="{host:[server1,server2]}" # Get host server1 and server2
109        python -m pybix user.get # Get all Users
110        ```
111
112        ### Graph Image Export
113
114        Zabbix does not let you export graphs via API (only the configuration for them). Instead of using `ZabbixAPI` class, use included `GraphImage`.
115
116        #### GraphImage Python Example
117
118        ```python
119        from pybix import GraphImageAPI
120        graph = GraphImageAPI(url="http://localhost/zabbix",
121                              user="Admin",
122                              password="zabbix")
123        graph.get_by_graphid("4038") # will save to png file in current working directory
124        graph.get_by_graphname("CPU") # will save any "CPU" graph png images to file in current working directory
125        ```
126
127        #### GraphImage CLI
128
129        ##### GraphImage CLI Usage
130
131        Refer to [ZabbixAPI usage](#####zabbix-api-cli-usage).
132
133        `search_types` include `graph_id, graph_name, item_names, item_keys, item_ids`
134
135        ##### GraphImage CLI Examples
136
137        ```bash
138        python -m pybix graphimage.graph_name graph_name=CPU host_names=server1
139        python -m pybix graphimage.graph_name graph_name=CPU host_names=[server1,server2]
140        python -m pybix graphimage.item_names item_names=CPU host_names=server1
141        python -m pybix graphimage.item_keys item_keys=availability.agent.available host_names=server1
142
143        # Not as useful, but is what above methods call after calculating id
144        python -m pybix graphimage.graph_id graph_id=4038 host_names=server1
145        python -m pybix graphimage.item_ids item_ids=138780,138781 host_names=server1
146        ```
147
148        ## Known Issues
149
150        ### SSL Verification
151
152        * If server using a self signed cert or serving on HTTPS, will need to use `ssl_verify` overide
153
154        ### User configuration
155
156        * Zabbix user used during API calls must have viewing rights to queried Zabbix object
157          * i.e. appropriate hostgroup read rights to user/usergroup OR super admin
158          * If it does not, it will simply return empty results without warning
159
160        ### Graph Items Usage
161
162        * User used to login must have frontend access (i.e. in Zabbix user group, set frontend access to true)
163        * No error messages or warnings if graph is invalid (i.e. wrong values used to call it)
164
165        ## Contributing
166
167        Feel free to raise any feature requests/problems/improvements as issue or pull request via [GitHub](https://github.com/mattykay/pybix).
168
169Keywords: zabbix,monitoring,api
170Platform: UNKNOWN
171Classifier: Programming Language :: Python
172Classifier: Programming Language :: Python :: 3
173Classifier: Programming Language :: Python :: 3.6
174Classifier: Programming Language :: Python :: 3.7
175Classifier: License :: OSI Approved :: MIT License
176Classifier: Operating System :: OS Independent
177Classifier: Natural Language :: English
178Classifier: Topic :: System :: Monitoring
179Requires-Python: >=3.6
180Description-Content-Type: text/markdown
181