113 lines
3.3 KiB
Markdown
113 lines
3.3 KiB
Markdown
# API Wrapper: Pi-hole
|
|
>A basic API wrapper for Pi-hole
|
|
|
|
## Usage Pihole v6 (PiholeAPI.py)
|
|
> still in progress...
|
|
### base usage
|
|
```python
|
|
pih = PiholeAPI() # if pihole.json exists
|
|
pih = PiholeAPI(host='10.10.10.10', password='mypassword') # without conf file
|
|
```
|
|
|
|
### auth handling
|
|
```python
|
|
pih.need_auth() # get a valid session if no auth required
|
|
pih._check_auth() # check if wrapper has a valid session stored
|
|
pih.do_auth() # (runs automaticly if need) do a auth with password
|
|
pih.get_sessions() # get all known sessions (webgui sessions too...)
|
|
pih.delete_session() # delet a session by id (collect from get_sessions) - withour parameters it will clear it own sessions
|
|
pih.clear_sessions() # delete all sessions without it own
|
|
pih.get_app_password() # generate a app password. good for use without TOTP. clears all sessions! (Hint: must be set in config, not implementet at now)
|
|
```
|
|
|
|
### metric handling
|
|
```python
|
|
pih.get_history() # Get activity graph data of dns querys
|
|
pih.get_history_timerange() # bugged!
|
|
pih.get_client_history() # Get per-client activity graph data of dns querys
|
|
pih.get_client_history_timerange() # bugged!
|
|
pih.get_queries() # Request query details.
|
|
```
|
|
|
|
### config handling
|
|
```python
|
|
pih.get_config() # get full running config
|
|
pih.get_config('dns/hosts') # get full tree but only ['dns']['hosts'] be filled
|
|
pih.patch_config(config) # send config update, all given elemnts will be overriden. config from get_config can be use.
|
|
```
|
|
|
|
#### custom dns handling
|
|
```python
|
|
pih.get_dns_host(['ip', 'fqdn']) # get a custom dns hosts als list
|
|
# return: [[ip, fqdn], [ip, fqdn]]
|
|
pih.remove_dns_host(['', 'fqdn'], match_ip=False) # get all custom dns hosts als list which match fqdn only
|
|
pih.remove_dns_host(['ip', ''], match_fqdn=False) # get all custom dns hosts als list which match ip only
|
|
pih.add_dns_host(['ip', 'fqdn']) # add new custom dns host. checks fist if identical host exists
|
|
pih.remove_dns_host(['ip', 'fqdn']) # remove a host which match ip and fqdn
|
|
pih.remove_dns_host(['', 'fqdn'], match_ip=False) # remove all hosts which match fqdn only
|
|
pih.remove_dns_host(['ip', ''], match_fqdn=False) # remove all hosts which match ip only
|
|
```
|
|
|
|
## Usage Pihole v5 and below (Pihole.py)
|
|
### Custom DNS
|
|
Read, add or delete a custom dns entry (no cname's!)
|
|
```python
|
|
get_custom_dns()
|
|
add_custom_dns(domain, ip)
|
|
del_custom_dns(domain, ip)
|
|
```
|
|
|
|
### Custom CNAMES
|
|
Same as Custom DNS but for CNAMES only.
|
|
```python
|
|
get_custom_cname()
|
|
add_custom_cname(domain, target)
|
|
del_custom_cname(domain, target)
|
|
```
|
|
|
|
### Filter Lists
|
|
Read, add or delete a filter list.
|
|
Availible lists:
|
|
- white
|
|
- black
|
|
- regex_white
|
|
- regex_black
|
|
|
|
*white and black only match exact machtes!*
|
|
|
|
```python
|
|
get_list(list, entry)
|
|
""" aliases """
|
|
get_whitelist(entry)
|
|
get_regex_whitelist(entry)
|
|
get_blacklist(entry)
|
|
get_regex_blacklist(entry)
|
|
|
|
add_to_list(list, entry)
|
|
""" aliases """
|
|
add_to_whitelist(entry)
|
|
add_to_regex_whitelist(entry)
|
|
add_to_blacklist(entry)
|
|
add_to_regex_blacklist(entry)
|
|
|
|
del_from_list(list, entry)
|
|
""" aliases """
|
|
del_from_whitelist(entry)
|
|
del_from_regex_whitelist(entry)
|
|
del_from_blacklist(entry)
|
|
del_from_regex_blacklist(entry)
|
|
```
|
|
|
|
### Misc
|
|
Misc functions for:
|
|
- enable / disable filter
|
|
- get / check update status
|
|
- set temp unit from cpu
|
|
|
|
```python
|
|
enable()
|
|
disable()
|
|
get_version()
|
|
check_updates()
|
|
set_tmp_unit(unit)
|
|
``` |