Merge pull request #4 from ji-podhead/main

v0.1.24

.docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

.docs/README.md

@@ -0,0 +1 @@
+../README.md

.docs/_build/html/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 8917fca747c6daf4a475360288b0fc01
+tags: 645f666f9bcd5a90fca523b33c5a78b7

.docs/_build/html/_sources/README.md.txt

@@ -0,0 +1,208 @@
+## about opnsense-helper
+<table>
+    <tr>
+       <td>
+          <a href="https://ji-podhead.github.io/opnsense-helper/.docs/_build/html/index.html"> 
+<img alt="Static Badge" src="https://img.shields.io/badge/Api%20Docs-%F0%9F%93%96%20-grey?style=for-the-badge&color=lightblue">        </td>
+        <td>
+            <a href="https://pypi.org/project/opnsense-helper/">
+            <img alt="PyPI - Version" src="https://img.shields.io/pypi/v/opnsense-helper?style=for-the-badge&link=https%3A%2F%2Fpypi.org%2Fproject%2Fopnsense-helper%2F">
+            </a>
+        </td>
+        <td>
+        <img alt="Static Badge" src="https://img.shields.io/badge/Ansible%20Collection-%F0%9F%9A%A7-darkgrey?style=for-the-badge&color=red">
+        </td>
+    </tr>
+</table>
+
+- create, assign and enable lan / phy interfaces and all the other stuff that is ***Not enabled*** in the opnsense api
+- use the config_manager to apply all your configs in runtime at once
+- uses the opnsense backend via shh 
+- configctl and pluginctl commands
+- around 80 opnsense scripts you can call
+- automatically configures your Vlan and Phy Interfaces after applying configuration
+
+
+## install 
+### pip
+```bash
+pip install opnsense-helper
+```
+## usage
+> -  you can run the provided snippets directly by pulling the [example file](https://github.com/the-pod-shop/opnsense-helper/blob/main/python/examples/add_vlans.py)
+> -  Please also have a look at:
+>    -   the [Api Docs](https://ji-podhead.github.io/opnsense-helper/.docs/_build/html/index.html)
+>    -   the corresponding [pip package](https://pypi.org/project/opnsense-helper/)
+>    -   and soon also the Ansible collection. 
+
+### required variables
+* import the package and define the needed variables for the main class
+
+```python
+from opnsense_helper.opnsense_helper import Opnsense_Helper
+from opnsense_helper.config_manager.config_manager import Vlan, Dhcpd, Interface
+
+host= "192.168.1.103"
+auth={
+"user":"root",
+"passw":"opnsense",
+}
+temp_path="./config.xml"
+helper=Opnsense_Helper(host=host,ssh_auth=auth,temp_path=temp_path, init=True)
+```
+### config_manager
+#### create the module objects
+> add  or change existing modules
+> - currently supports vlans, dhcpd, interfaces and soon routes, as well as firewall rules
+- create the objects of the modules you want to set
+```python
+vlans=[
+Vlan("vlan1","vtnet1","1"),
+Vlan("vlan2","vtnet1","2"),
+Vlan("vlan3","vtnet1","3")
+]
+
+interfaces=[
+Interface("opt1","router","vtnet1","1","200.1.0.1","24"),
+Interface("opt2","vlan1","vlan0.1", "1", '200.0.1.1', "24", '00:00:00:01:00:01'),
+Interface("opt3","vlan2","vlan0.2", "2", '200.0.2.1', "24", '00:00:00:01:00:02'),
+Interface("opt4","vlan3","vlan0.3", "3", '200.0.3.1', "24", '00:00:00:01:00:03'),
+]
+
+dhcp=[
+Dhcpd("opt1","1",{'from': '200.1.0.2', '_to': '200.1.0.2'}),
+Dhcpd("opt2","1",{'from': '200.0.1.1', '_to': '200.0.1.100'}),
+Dhcpd("opt3","1",{'from': '200.0.2.1', '_to': '200.0.2.100'}),
+Dhcpd("opt4","1",{'from': '200.0.3.1', '_to': '200.0.3.100'}),
+]
+```
+
+#### assign the config
+```python
+helper.set("interfaces",interfaces)
+helper.set("dhcpd",dhcp)
+helper.set("vlans",vlans)
+helper.save(temp_path)
+#helper.remove_items()
+```
+### scripts and commands
+> - you can run every script fron `/usr/local/opnsense/scripts/`
+> - you can use every `pluginctl` and `configctl` commands
+> - use `<command: str> <argument:str> <flags:arr>`
+> - besides command, argument may be required based on the method
+#### Example
+```python
+    helper.scripts.system.run("status")
+    helper.scripts.routes.run("show_routes")
+
+    helper.commands.pluginctl.run("ipv4")
+    helper.commands.pluginctl.run("service", "dhcpd status")
+    helper.commands.pluginctl.run("config", "dhcp")
+```
+##### Result
+```bash
+$ /usr/local/opnsense/scripts/system/status.php*  
+{"CrashReporter":{"statusCode":2,"message":"No problems were detected.","logLocation":"\/crash_reporter.php","timestamp":"0"},"Firewall":{"statusCode":-1,"message":"There were error(s) loading the rules: \/tmp\/rules.debug:25: syntax error - The line in question reads [25]: set loginterface \n","logLocation":"\/ui\/diagnostics\/log\/core\/firewall","timestamp":1731025409}}
+
+$ /usr/local/opnsense/scripts/routes/show_routes.py*  
+destination             gateway         flags           nhop#           mtu             netif           expire
+ipv4    default 192.168.0.1     UGS     5       1500    vtnet0
+ipv4    localhost       link#4  UH      2       16384   lo0
+ipv4    192.168.0.1     link#1  UHS     4       1500    vtnet0
+ipv4    192.168.1.0/24  link#1  U       1       1500    vtnet0
+ipv4    192.168.1.1     link#1  UHS     4       1500    vtnet0
+ipv4    192.168.1.103   link#1  UHS     3       16384   lo0
+ipv4    200.1.0.0/24    link#2  U       6       1500    vtnet1
+ipv4    200.1.0.1       link#2  UHS     7       16384   lo0
+ipv6    localhost       link#4  UHS     1       16384   lo0
+ipv6    fe80::%lo0/64   link#4  U       3       16384   lo0
+ipv6    fe80::1%lo0     link#4  UHS     2       16384   lo0
+
+$ pluginctl -4  
+{
+    "address": null,
+    "network": null,
+    "bits": null,
+    "device": null,
+    "interface": null
+}
+
+$ pluginctl -s dhcpd status 
+dhcpd is running as pid 16072.
+
+$ pluginctl -c dhcp 
+Starting DHCPv4 service...done.
+```
+
+
+### Frontend Api
+- you can download the config.xml and add vlans via api
+```python 
+def using_api():
+    vlans_api=[
+    {'if': 'vtnet1', 'tag': '1', 'pcp': '0', 'proto': None, 'descr': 'vlan1', 'vlanif': 'vlan0.1'},
+    {'if': 'vtnet1', 'tag': '2', 'pcp': '0', 'proto': None, 'descr': 'vlan2', 'vlanif': 'vlan0.2'}
+    ]
+    api_auth={
+    "api_key" :'ejl4fIU9yfNk+gaQmPk/rqIa15f1yX1snIKgcIEl2QNoJwhbekraWIE0ANRYceh9hey5IFGzlf3da4yJ',
+    "api_secret":'5JVVGoatPbaAA+FozLDQY92/T6sRlmKD1+aRNl/YI8KA9/0TNiTDboLveqvd9FU8wFeDo3D3DY5wrUtF',
+    "ssl": True,
+    "verify": False
+    }    
+    helper=Opnsense_Helper(host=host,api_auth=api_auth,filepath=output, verbose=False)
+    helper.vlans_api(vlans_api,"add")
+```
+
+
+
+#### config_manager manual usage
+
+* pull the config.xml from the firewall via ssh
+
+```python
+helper.config_manager.get_conf(conf_path)
+```
+
+* initialize the the Opnsense_Helper-class and parse the config.xml
+```python
+helper.config_manager.initialize()
+```
+- add the items
+```python
+helper.config_manager.add_Items("vlans",vlans)
+```
+
+* save the configuration as xml and copy it back to the firewall
+> this will also reconfigure your vlans for you, if you have any 
+```python
+helper.config_manager.save(output)
+helper.config_manager.put_file(output,conf_path)
+helper.config_manager.close_con()   
+```
+
+
+### contribute
+- clone, or fork `[email protected]:the-pod-shop/opnsense-helper.git`
+- build when made changes
+- make sure to use the right user
+```bash
+cd python
+python setup.py bdist_wheel \
+&& pip install --upgrade . \
+&& python3 -m pip install --upgrade build #--force 
+```
+- you can also use the build.sh script
+- create pull request
+
+## motivation
+- i couldnt find a single repo/collection/terraform provider/api that let me assign and enable lan interfaces
+- i decided to create one mself
+- opnsense api does not let me do it, it just replies with: controller not found
+- but /conf/config.xml has the answer.
+- however for phisical interfaces its the god damn conf.rc
+- my opnsense runs in a vm, so it really doesnt matter for me
+- i just add the interfaces via libvirt and all i need to do is to enable them, given the /conf/config.xml method
+xml has the answer.
+- however for phisical interfaces its the god damn conf.rc
+- my opnsense runs in a vm, so it really doesnt matter for me
+- i just add the interfaces via libvirt and all i need to do is to enable them, given the /conf/config.xml method

.docs/_build/html/_sources/index.rst.txt

@@ -0,0 +1,30 @@
+Opnsense-Helper
+==========================================
+
+**The backend framework for opnsense**
+
+* create, assign and enable lan / phy interfaces and all the other stuff that is ***Not enabled*** in the opnsense api
+
+* use the config_manager to apply all your configs in runtime at once
+
+* uses the opnsense backend via shh 
+
+* configctl and pluginctl commands
+
+* around 80 opnsense scripts you can call
+
+* automatically configures your Vlan and Phy Interfaces after applying configuration
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: About:
+
+   README.md
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Python API-Dokumentation
+
+   python_package.rst

.docs/_build/html/_sources/opnsense_helper/opnsense_helper.commands.commands.rst.txt

@@ -0,0 +1,15 @@
+opnsense\_helper.commands.commands
+==================================
+
+.. automodule:: opnsense_helper.commands.commands
+
+
+   .. rubric:: Classes
+
+   .. autosummary::
+
+      Commands
+      configctl
+      pluginctl
+      reconfigure
+

.docs/_build/html/_sources/opnsense_helper/opnsense_helper.commands.rst.txt

@@ -0,0 +1,13 @@
+opnsense\_helper.commands
+=========================
+
+.. automodule:: opnsense_helper.commands
+
+
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :recursive:
+
+   commands

.docs/_build/html/_sources/opnsense_helper/opnsense_helper.config_manager.config_manager.rst.txt

@@ -0,0 +1,15 @@
+opnsense\_helper.config\_manager.config\_manager
+================================================
+
+.. automodule:: opnsense_helper.config_manager.config_manager
+
+
+   .. rubric:: Classes
+
+   .. autosummary::
+
+      Config_Manager
+      Dhcpd
+      Interface
+      Vlan
+

.docs/_build/html/_sources/opnsense_helper/opnsense_helper.config_manager.rst.txt

@@ -0,0 +1,13 @@
+opnsense\_helper.config\_manager
+================================
+
+.. automodule:: opnsense_helper.config_manager
+
+
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :recursive:
+
+   config_manager

.docs/_build/html/_sources/opnsense_helper/opnsense_helper.opnsense_helper.rst.txt

@@ -0,0 +1,12 @@
+opnsense\_helper.opnsense\_helper
+=================================
+
+.. automodule:: opnsense_helper.opnsense_helper
+
+
+   .. rubric:: Classes
+
+   .. autosummary::
+
+      Opnsense_Helper
+

.docs/_build/html/_sources/opnsense_helper/opnsense_helper.rst.txt

@@ -0,0 +1,17 @@
+opnsense\_helper
+================
+
+.. automodule:: opnsense_helper
+
+
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :recursive:
+
+   commands
+   config_manager
+   opnsense_helper
+   scripts
+   utils

.docs/_build/html/_sources/opnsense_helper/opnsense_helper.scripts.rst.txt

@@ -0,0 +1,13 @@
+opnsense\_helper.scripts
+========================
+
+.. automodule:: opnsense_helper.scripts
+
+
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :recursive:
+
+   scripts