akips 0.2.3__tar.gz → 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.1
2
2
  Name: akips
3
- Version: 0.2.3
3
+ Version: 0.3.0
4
4
  Summary: Module to interact with the AKiPS Network Monitoring Software API interface
5
5
  Home-page: https://github.com/wwhitaker/akips
6
6
  License: MIT
@@ -1,6 +1,6 @@
1
1
  """ This akips python module provides a simple way for python scripts to interact with
2
2
  the AKiPS Network Monitoring Software Web API interface. """
3
- __version__ = '0.2.3'
3
+ __version__ = '0.3.0'
4
4
 
5
5
  import io
6
6
  import re
@@ -32,7 +32,15 @@ class AKIPS:
32
32
  requests.packages.urllib3.disable_warnings() # pylint: disable=no-member
33
33
 
34
34
  def get_devices(self, group_filter='any', groups=[]):
35
- """ Pull a list of key attributes for all devices in akips """
35
+ """
36
+ Pull a list of key attributes for multiple devices. Can be filtered by group
37
+ but the default is all devices.
38
+
39
+ AKiPS command syntax:
40
+ `mget {type} [{parent regex} [{child regex} [{attribute regex}]]]
41
+ [value {text|/regex/|integer|ipaddr}] [profile {profile name}]
42
+ [any|all|not group {group name} ...]`
43
+ """
36
44
  attributes = [
37
45
  'ip4addr',
38
46
  'SNMPv2-MIB.sysName',
@@ -44,7 +52,7 @@ class AKIPS:
44
52
  'cmds': f'mget text * sys /{cmd_attributes}/',
45
53
  }
46
54
  if groups:
47
- """ [any|all|not group {group name} ...] """
55
+ # [any|all|not group {group name} ...]
48
56
  group_list = " ".join(groups)
49
57
  params['cmds'] += f" {group_filter} group {group_list}"
50
58
  text = self._get(params=params)
@@ -65,7 +73,14 @@ class AKIPS:
65
73
  return None
66
74
 
67
75
  def get_device(self, name):
68
- """ Pull the entire configuration for a single device """
76
+ """
77
+ Pull the entire configuration for a single device.
78
+
79
+ AKiPS command syntax:
80
+ `mget {type} [{parent regex} [{child regex} [{attribute regex}]]]
81
+ [value {text|/regex/|integer|ipaddr}] [profile {profile name}]
82
+ [any|all|not group {group name} ...]`
83
+ """
69
84
  params = {
70
85
  'cmds': f'mget * {name} * *'
71
86
  }
@@ -94,17 +109,38 @@ class AKIPS:
94
109
  return None
95
110
 
96
111
  def get_device_by_ip(self, ipaddr, use_cache=True):
97
- """ Search for a device by an alternate IP address
98
- This makes use of a special site script and not the normal api """
99
- # params = {
100
- # 'function': 'web_find_device_by_ip',
101
- # 'ipaddr': ipaddr
102
- # }
103
- # section = '/api-script/'
104
- pass
112
+ """
113
+ Devices may have additional IP addresses recorded in akips, but only one primary
114
+ name and address. Search for a device name by an alternate IP address.
115
+
116
+ AKiPS user "api-rw" is required to run api scripts. This call makes use of a
117
+ special site script and not the normal web API commands.
118
+ """
119
+ params = {
120
+ 'function': 'web_find_device_by_ip',
121
+ 'ipaddr': ipaddr
122
+ }
123
+ text = self._get(section='/api-script/', params=params)
124
+ if text:
125
+ lines = text.split('\n')
126
+ for line in lines:
127
+ match = re.match(r"IP Address (\S+) is configured on (\S+)", line)
128
+ if match:
129
+ address = match.group(1)
130
+ device_name = match.group(2)
131
+ logger.debug(f"Found {address} on device {device_name}")
132
+ return device_name
133
+ return None
105
134
 
106
135
  def get_unreachable(self):
107
- """ Pull a list of unreachable IPv4 ping devices """
136
+ """
137
+ Pull a list of unreachable IPv4 ping devices
138
+
139
+ AKiPS command syntax:
140
+ `mget {type} [{parent regex} [{child regex} [{attribute regex}]]]
141
+ [value {text|/regex/|integer|ipaddr}] [profile {profile name}]
142
+ [any|all|not group {group name} ...]`
143
+ """
108
144
  params = {
109
145
  'cmds': 'mget * * * /PING.icmpState|SNMP.snmpState/ value /down/',
110
146
  }
@@ -153,11 +189,21 @@ class AKIPS:
153
189
 
154
190
  return data
155
191
 
156
- def get_group_membership(self):
157
- """ Pull a list of device to group memberships """
192
+ def get_group_membership(self, device='*', group_filter='any', groups=[]):
193
+ """
194
+ Pull a list of device names to group memberships. Defaults to all devices
195
+ and all groups (including the special 'maintenance_mode' group).
196
+
197
+ AKiPS command syntax:
198
+ `mgroup {type} [{parent regex}]
199
+ [any|all|not group {group name} ...]`
200
+ """
158
201
  params = {
159
- 'cmds': 'mgroup device *',
202
+ 'cmds': f'mgroup {device} *',
160
203
  }
204
+ if groups:
205
+ group_list = " ".join(groups)
206
+ params['cmds'] += f" {group_filter} group {group_list}"
161
207
  text = self._get(params=params)
162
208
  if text:
163
209
  data = {}
@@ -173,34 +219,55 @@ class AKIPS:
173
219
  return data
174
220
  return None
175
221
 
176
- def get_maintenance_mode(self):
177
- """ Pull a list of devices in maintenance mode """
178
- # params = {
179
- # 'cmds': 'mget * * any group maintenance_mode',
180
- # }
181
- pass
222
+ def set_group_membership(self, device, group, mode):
223
+ """
224
+ Update manual grouping rules for a device, including the special
225
+ 'maintenance_mode' group. The web api script fails silently if the device or group
226
+ does not exist.
182
227
 
183
- def set_maintenance_mode(self, device_name, mode='True'):
184
- """ Set maintenance mode on or off for a device """
185
- # params = {
186
- # 'function': 'web_manual_grouping',
187
- # 'type': 'device',
188
- # 'group': 'maintenance_mode',
189
- # 'device': device_name
190
- # }
191
- pass
228
+ AKiPS user "api-rw" is required to run api scripts. This call makes use of a
229
+ special site script and not the normal web API commands.
230
+ """
231
+ if not device:
232
+ raise ValueError("a valid device name must be provided for manual grouping update")
233
+ if not group:
234
+ raise ValueError("a valid group name must be provided for manual grouping update")
235
+ if mode not in ('assign', 'clear'):
236
+ raise ValueError("mode must be 'assign' or 'clear' for manual grouping update")
237
+ params = {
238
+ 'function': 'web_manual_grouping',
239
+ 'type': 'device',
240
+ 'group': group, # group_name
241
+ 'mode': mode, # 'assign' or 'clear' for device memberships
242
+ 'device': device # device_name
243
+ }
244
+ text = self._get(section='/api-script/', params=params)
245
+ if text:
246
+ logger.error("Web API request failed: {}".format(text))
247
+ raise AkipsError(message=text)
248
+ return None
192
249
 
193
250
  def get_status(self, device='*', child='*', attribute='*'):
194
- """ Pull the status values we are most interested in """
251
+ """
252
+ Pull the status values we are most interested in
253
+
254
+ AKiPS command syntax:
255
+ `mget {type} [{parent regex} [{child regex} [{attribute regex}]]]
256
+ [value {text|/regex/|integer|ipaddr}] [profile {profile name}]
257
+ [any|all|not group {group name} ...]`
258
+ """
195
259
  pass
196
260
 
197
261
  def get_events(self, event_type='all', period='last1h'):
198
- """ Pull a list of events. Command syntax:
199
- mget event {all,critical,enum,threshold,uptime}
262
+ """
263
+ Pull a list of events.
264
+
265
+ AKiPS command syntax:
266
+ `mget event {all,critical,enum,threshold,uptime}
200
267
  time {time filter} [{parent regex} {child regex}
201
268
  {attribute regex}] [profile {profile name}]
202
- [any|all|not group {group name} ...] """
203
-
269
+ [any|all|not group {group name} ...]`
270
+ """
204
271
  params = {
205
272
  'cmds': f'mget event {event_type} time {period}'
206
273
  }
@@ -229,10 +296,14 @@ class AKIPS:
229
296
 
230
297
  def get_series(self, period='last1h', device='*', attribute='*', get_dict=True,
231
298
  group_filter='any', groups=[]):
232
- """ Pull a series of values. Command syntax:
233
- cseries avg
299
+ """
300
+ Pull a series of counter values.
301
+
302
+ AKiPS command syntax:
303
+ `cseries avg
234
304
  time {time filter} type parent child attribute
235
- [any|all|not group {group name} ...] """
305
+ [any|all|not group {group name} ...]`
306
+ """
236
307
  params = {
237
308
  'cmds': f'cseries avg time {period} * {device} * {attribute}'
238
309
  }
@@ -256,10 +327,14 @@ class AKIPS:
256
327
 
257
328
  def get_aggregate(self, period='last1h', device='*', attribute='*',
258
329
  operator='avg', interval='300', group_filter='any', groups=[]):
259
- """ Aggregate stats in intervals over a period of time. Command syntax:
260
- aggregate interval {avg|total seconds}
330
+ """
331
+ Aggregate counter values in intervals over a period of time.
332
+
333
+ AKiPS command syntax:
334
+ `aggregate interval {avg|total seconds}
261
335
  time {time filter} type parent child attribute
262
- [any|all|not group {group name} ...] """
336
+ [any|all|not group {group name} ...]`
337
+ """
263
338
  params = {
264
339
  'cmds': f'aggregate interval {operator} {interval} time {period} * {device} * {attribute}'
265
340
  }
@@ -278,7 +353,9 @@ class AKIPS:
278
353
  # Base operations
279
354
 
280
355
  def _parse_enum(self, enum_string):
281
- """ Attributes with a type of enum return five values separated by commas. """
356
+ """
357
+ Attributes with a type of enum return five values separated by commas.
358
+ """
282
359
  match = re.match(r'^(\S*),(\S*),(\S*),(\S*),(\S*)$', enum_string)
283
360
  if match:
284
361
  entry = {
@@ -297,7 +374,9 @@ class AKIPS:
297
374
  raise AkipsError(message=f'Not a ENUM type value: {enum_string}')
298
375
 
299
376
  def _get(self, section='/api-db/', params=None, timeout=30):
300
- """ Call HTTP GET against the AKiPS server """
377
+ """
378
+ Call HTTP GET against the AKiPS server
379
+ """
301
380
  server_url = 'https://' + self.server + section
302
381
  params['username'] = self.username
303
382
  params['password'] = self.password
@@ -1,6 +1,6 @@
1
1
  [tool.poetry]
2
2
  name = "akips"
3
- version = "0.2.3"
3
+ version = "0.3.0"
4
4
  description = "Module to interact with the AKiPS Network Monitoring Software API interface"
5
5
  authors = ["William E Whitaker <will.whitaker@unc.edu>"]
6
6
  readme = "README.md"
File without changes
File without changes
File without changes