# Libknot API in Python
A Python interface for managing the Knot DNS daemon.
# Table of contents
* [Introduction](#introduction)
* [Control module](#control-module)
+ [Control usage](#control-usage)
+ [Control examples](#control-examples)
* [Probe module](#probe-module)
+ [Probe usage](#probe-usage)
+ [Probe examples](#probe-examples)
* [Dname module](#dname-module)
+ [Dname usage](#dname-usage)
+ [Dname examples](#dname-examples)
## Introduction<a id="introduction"></a>
If the shared `libknot.so` library isn't available in the library search path, it's
necessary to load the library first, e.g.:
```python3
import libknot
libknot.Knot("/usr/lib/libknot.so")
```
## Control module<a id="control-module"></a>
Using this module it's possible to create scripts for efficient tasks that
would require complex shell scripts with multiple calls of `knotc`. For
communication with the daemon it uses the same mechanism as the `knotc` utility,
i.e. communication via a Unix socket.
The module API is stored in `libknot.control`.
### Control usage<a id="control-usage"></a>
The module usage consists of several steps:
* Initialization and connection to the daemon control socket.
* One or more control operations. An operation is called by sending a command
with optional data to the daemon. The operation result has to be received
afterwards.
* Closing the connection and deinitialization.
### Control examples<a id="control-examples"></a>
```python3
import json
import libknot.control
# Initialization
ctl = libknot.control.KnotCtl()
ctl.connect("/var/run/knot/knot.sock")
ctl.set_timeout(60)
try:
# Operation without parameters
ctl.send_block(cmd="conf-begin")
resp = ctl.receive_block()
# Operation with parameters
ctl.send_block(cmd="conf-set", section="zone", item="domain", data="test")
resp = ctl.receive_block()
ctl.send_block(cmd="conf-commit")
resp = ctl.receive_block()
# Operation with a result displayed in JSON format
ctl.send_block(cmd="conf-read", section="zone", item="domain")
resp = ctl.receive_block()
print(json.dumps(resp, indent=4))
except libknot.control.KnotCtlError as exc:
# Print libknot error
print(exc)
finally:
# Deinitialization
ctl.send(libknot.control.KnotCtlType.END)
ctl.close()
```
```python3
# List configured zones (including catalog member ones)
ctl.send_block(cmd="conf-list", filters="z")
resp = ctl.receive_block()
for zone in resp['zone']:
print(zone)
```
```python3
# Print expirations as unixtime for all secondary zones
ctl.send_block(cmd="zone-status", filters="u")
resp = ctl.receive_block()
for zone in resp:
if resp[zone]["role"] == "master":
continue
expiration = resp[zone]["expiration"]
if expiration == "-":
print("Zone %s not loaded" % zone)
else:
print("Zone %s expires at %s" % (zone, resp[zone]["expiration"]))
```
## Probe module<a id="probe module"></a>
Using this module it's possible to receive traffic data from a running daemon with
active probe module.
The module API is stored in `libknot.probe`.
### Probe usage<a id="probe-usage"></a>
The module usage consists of several steps:
* Initialization of one or more probe channels
* Periodical receiving of data units from the channels and data processing
### Probe examples<a id="probe-examples"></a>
```python3
import libknot.probe
# Initialization of the first probe channel stored in `/run/knot`
probe = libknot.probe.KnotProbe("/run/knot", 1)
# Array for storing up to 8 data units
data = libknot.probe.KnotProbeDataArray(8)
while (True):
# Receiving data units with timeout of 1000 ms
if probe.consume(data, 1000) > 0:
# Printing received data units in the default format
for item in data:
print(item)
```
## Dname module<a id="dname-module"></a>
This module provides a few dname-related operations.
The module API is stored in `libknot.dname`.
### Dname usage<a id="dname-usage"></a>
The dname object is initialized from a string with textual dname.
Then the dname can be reformatted to wire format or back to textual format.
### Dname examples<a id="dname-examples"></a>
```python3
import libknot.dname
dname1 = libknot.dname.KnotDname("knot-dns.cz")
print("%s: wire: %s size: %u" % (dname1.str(), dname1.wire(), dname1.size()))
dname2 = libknot.dname.KnotDname("e\\120ample.c\om.")
print("%s: wire: %s size: %u" % (dname2.str(), dname2.wire(), dname2.size()))
dname3 = libknot.dname.KnotDname(dname_wire=b'\x02cz\x00')
print("%s: wire: %s size: %u" % (dname3.str(), dname3.wire(), dname3.size()))
```
```bash
knot-dns.cz.: wire: b'\x08knot-dns\x02cz\x00' size: 13
example.com.: wire: b'\x07example\x03com\x00' size: 13
cz.: wire: b'\x02cz\x00' size: 4
```
Raw data
{
"_id": null,
"home_page": "https://gitlab.nic.cz/knot/knot-dns/-/tree/master/python/libknot",
"name": "libknot",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.5",
"maintainer_email": null,
"keywords": null,
"author": "CZ.NIC, z.s.p.o.",
"author_email": "\"CZ.NIC, z.s.p.o.\" <knot-dns@labs.nic.cz>",
"download_url": "https://files.pythonhosted.org/packages/ff/f1/2162b24f9e7351b7078697a021eaf86e3040d511ba2746d11c871293ef41/libknot-3.4.3.tar.gz",
"platform": null,
"description": "# Libknot API in Python\n\nA Python interface for managing the Knot DNS daemon.\n\n# Table of contents\n\n* [Introduction](#introduction)\n* [Control module](#control-module)\n + [Control usage](#control-usage)\n + [Control examples](#control-examples)\n* [Probe module](#probe-module)\n + [Probe usage](#probe-usage)\n + [Probe examples](#probe-examples)\n* [Dname module](#dname-module)\n + [Dname usage](#dname-usage)\n + [Dname examples](#dname-examples)\n\n## Introduction<a id=\"introduction\"></a>\n\nIf the shared `libknot.so` library isn't available in the library search path, it's\nnecessary to load the library first, e.g.:\n\n```python3\nimport libknot\nlibknot.Knot(\"/usr/lib/libknot.so\")\n```\n\n## Control module<a id=\"control-module\"></a>\n\nUsing this module it's possible to create scripts for efficient tasks that\nwould require complex shell scripts with multiple calls of `knotc`. For\ncommunication with the daemon it uses the same mechanism as the `knotc` utility,\ni.e. communication via a Unix socket.\n\nThe module API is stored in `libknot.control`.\n\n### Control usage<a id=\"control-usage\"></a>\n\nThe module usage consists of several steps:\n\n* Initialization and connection to the daemon control socket.\n* One or more control operations. An operation is called by sending a command\n with optional data to the daemon. The operation result has to be received\n afterwards.\n* Closing the connection and deinitialization.\n\n### Control examples<a id=\"control-examples\"></a>\n\n```python3\nimport json\nimport libknot.control\n\n# Initialization\nctl = libknot.control.KnotCtl()\nctl.connect(\"/var/run/knot/knot.sock\")\nctl.set_timeout(60)\n\ntry:\n # Operation without parameters\n ctl.send_block(cmd=\"conf-begin\")\n resp = ctl.receive_block()\n\n # Operation with parameters\n ctl.send_block(cmd=\"conf-set\", section=\"zone\", item=\"domain\", data=\"test\")\n resp = ctl.receive_block()\n\n ctl.send_block(cmd=\"conf-commit\")\n resp = ctl.receive_block()\n\n # Operation with a result displayed in JSON format\n ctl.send_block(cmd=\"conf-read\", section=\"zone\", item=\"domain\")\n resp = ctl.receive_block()\n print(json.dumps(resp, indent=4))\nexcept libknot.control.KnotCtlError as exc:\n # Print libknot error\n print(exc)\nfinally:\n # Deinitialization\n ctl.send(libknot.control.KnotCtlType.END)\n ctl.close()\n```\n\n```python3\n # List configured zones (including catalog member ones)\n ctl.send_block(cmd=\"conf-list\", filters=\"z\")\n resp = ctl.receive_block()\n for zone in resp['zone']:\n print(zone)\n```\n\n```python3\n # Print expirations as unixtime for all secondary zones\n ctl.send_block(cmd=\"zone-status\", filters=\"u\")\n resp = ctl.receive_block()\n for zone in resp:\n if resp[zone][\"role\"] == \"master\":\n continue\n\n expiration = resp[zone][\"expiration\"]\n if expiration == \"-\":\n print(\"Zone %s not loaded\" % zone)\n else:\n print(\"Zone %s expires at %s\" % (zone, resp[zone][\"expiration\"]))\n```\n\n## Probe module<a id=\"probe module\"></a>\n\nUsing this module it's possible to receive traffic data from a running daemon with\nactive probe module.\n\nThe module API is stored in `libknot.probe`.\n\n### Probe usage<a id=\"probe-usage\"></a>\n\nThe module usage consists of several steps:\n\n* Initialization of one or more probe channels\n* Periodical receiving of data units from the channels and data processing\n\n### Probe examples<a id=\"probe-examples\"></a>\n\n```python3\nimport libknot.probe\n\n# Initialization of the first probe channel stored in `/run/knot`\nprobe = libknot.probe.KnotProbe(\"/run/knot\", 1)\n\n# Array for storing up to 8 data units\ndata = libknot.probe.KnotProbeDataArray(8)\nwhile (True):\n # Receiving data units with timeout of 1000 ms\n if probe.consume(data, 1000) > 0:\n # Printing received data units in the default format\n for item in data:\n print(item)\n```\n\n## Dname module<a id=\"dname-module\"></a>\n\nThis module provides a few dname-related operations.\n\nThe module API is stored in `libknot.dname`.\n\n### Dname usage<a id=\"dname-usage\"></a>\n\nThe dname object is initialized from a string with textual dname.\nThen the dname can be reformatted to wire format or back to textual format.\n\n### Dname examples<a id=\"dname-examples\"></a>\n\n```python3\nimport libknot.dname\n\ndname1 = libknot.dname.KnotDname(\"knot-dns.cz\")\nprint(\"%s: wire: %s size: %u\" % (dname1.str(), dname1.wire(), dname1.size()))\n\ndname2 = libknot.dname.KnotDname(\"e\\\\120ample.c\\om.\")\nprint(\"%s: wire: %s size: %u\" % (dname2.str(), dname2.wire(), dname2.size()))\n\ndname3 = libknot.dname.KnotDname(dname_wire=b'\\x02cz\\x00')\nprint(\"%s: wire: %s size: %u\" % (dname3.str(), dname3.wire(), dname3.size()))\n```\n\n```bash\nknot-dns.cz.: wire: b'\\x08knot-dns\\x02cz\\x00' size: 13\nexample.com.: wire: b'\\x07example\\x03com\\x00' size: 13\ncz.: wire: b'\\x02cz\\x00' size: 4\n```\n",
"bugtrack_url": null,
"license": "GPL-3.0",
"summary": "Python bindings for libknot",
"version": "3.4.3",
"project_urls": {
"Documentation": "https://www.knot-dns.cz/documentation",
"Homepage": "https://gitlab.nic.cz/knot/knot-dns/-/tree/master/python/libknot",
"Issues": "https://gitlab.nic.cz/knot/knot-dns/-/issues",
"Source": "https://gitlab.nic.cz/knot/knot-dns/-/tree/master/python/libknot"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fff12162b24f9e7351b7078697a021eaf86e3040d511ba2746d11c871293ef41",
"md5": "c157fa3bbdf2c555f48fefb4ba86dcb1",
"sha256": "4a6dd61d9742a73d05feda4641ceedbe98dcc5f3dcd9c300c9cd2b5639ba8b4e"
},
"downloads": -1,
"filename": "libknot-3.4.3.tar.gz",
"has_sig": false,
"md5_digest": "c157fa3bbdf2c555f48fefb4ba86dcb1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.5",
"size": 11251,
"upload_time": "2024-12-06T06:58:31",
"upload_time_iso_8601": "2024-12-06T06:58:31.768328Z",
"url": "https://files.pythonhosted.org/packages/ff/f1/2162b24f9e7351b7078697a021eaf86e3040d511ba2746d11c871293ef41/libknot-3.4.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-06 06:58:31",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "libknot"
}
JSON