mirror of https://github.com/opnsense/docs
update api docs
Ad Schellevis
4 weeks ago
parent
efa8b18e31
commit
13bb3d908c
@ -0,0 +1,28 @@
|
||||
Dhcrelay
|
||||
~~~~~~~~
|
||||
|
||||
.. csv-table:: Service (ServiceController.php)
|
||||
:header: "Method", "Module", "Controller", "Command", "Parameters"
|
||||
:widths: 4, 15, 15, 30, 40
|
||||
|
||||
"``POST``","dhcrelay","service","reconfigure",""
|
||||
|
||||
.. csv-table:: Resources (SettingsController.php)
|
||||
:header: "Method", "Module", "Controller", "Command", "Parameters"
|
||||
:widths: 4, 15, 15, 30, 40
|
||||
|
||||
"``POST``","dhcrelay","settings","addDest",""
|
||||
"``POST``","dhcrelay","settings","addRelay",""
|
||||
"``POST``","dhcrelay","settings","delDest","$uuid"
|
||||
"``POST``","dhcrelay","settings","delRelay","$uuid"
|
||||
"``GET``","dhcrelay","settings","get",""
|
||||
"``GET``","dhcrelay","settings","getDest","$uuid=null"
|
||||
"``GET``","dhcrelay","settings","getRelay","$uuid=null"
|
||||
"``*``","dhcrelay","settings","searchDest",""
|
||||
"``*``","dhcrelay","settings","searchRelay",""
|
||||
"``POST``","dhcrelay","settings","set",""
|
||||
"``POST``","dhcrelay","settings","setDest","$uuid"
|
||||
"``POST``","dhcrelay","settings","setRelay","$uuid"
|
||||
"``POST``","dhcrelay","settings","toggleRelay","$uuid,$enabled=null"
|
||||
|
||||
"``<<uses>>``", "", "", "", "*model* `DHCRelay.xml <https://github.com/opnsense/core/blob/master/src/opnsense/mvc/app/models/OPNsense/DHCRelay/DHCRelay.xml>`__"
|
||||
@ -0,0 +1,66 @@
|
||||
Caddy
|
||||
~~~~~
|
||||
|
||||
.. csv-table:: Service (GeneralController.php)
|
||||
:header: "Method", "Module", "Controller", "Command", "Parameters"
|
||||
:widths: 4, 15, 15, 30, 40
|
||||
|
||||
"``GET``","caddy","general","get",""
|
||||
"``POST``","caddy","general","set",""
|
||||
|
||||
"``<<uses>>``", "", "", "", "*model* `Caddy.xml <https://github.com/opnsense/plugins/blob/master/www/caddy/src/opnsense/mvc/app/models/OPNsense/Caddy/Caddy.xml>`__"
|
||||
|
||||
.. csv-table:: Resources (ReverseProxyController.php)
|
||||
:header: "Method", "Module", "Controller", "Command", "Parameters"
|
||||
:widths: 4, 15, 15, 30, 40
|
||||
|
||||
"``POST``","caddy","reverse_proxy","addAccessList",""
|
||||
"``POST``","caddy","reverse_proxy","addBasicAuth",""
|
||||
"``POST``","caddy","reverse_proxy","addHandle",""
|
||||
"``POST``","caddy","reverse_proxy","addHeader",""
|
||||
"``POST``","caddy","reverse_proxy","addReverseProxy",""
|
||||
"``POST``","caddy","reverse_proxy","addSubdomain",""
|
||||
"``POST``","caddy","reverse_proxy","delAccessList","$uuid"
|
||||
"``POST``","caddy","reverse_proxy","delBasicAuth","$uuid"
|
||||
"``POST``","caddy","reverse_proxy","delHandle","$uuid"
|
||||
"``POST``","caddy","reverse_proxy","delHeader","$uuid"
|
||||
"``POST``","caddy","reverse_proxy","delReverseProxy","$uuid"
|
||||
"``POST``","caddy","reverse_proxy","delSubdomain","$uuid"
|
||||
"``GET``","caddy","reverse_proxy","get",""
|
||||
"``GET``","caddy","reverse_proxy","getAccessList","$uuid=null"
|
||||
"``GET``","caddy","reverse_proxy","getBasicAuth","$uuid=null"
|
||||
"``GET``","caddy","reverse_proxy","getHandle","$uuid=null"
|
||||
"``GET``","caddy","reverse_proxy","getHeader","$uuid=null"
|
||||
"``GET``","caddy","reverse_proxy","getReverseProxy","$uuid=null"
|
||||
"``GET``","caddy","reverse_proxy","getSubdomain","$uuid=null"
|
||||
"``*``","caddy","reverse_proxy","searchAccessList","$add_empty='0'"
|
||||
"``*``","caddy","reverse_proxy","searchBasicAuth","$add_empty='0'"
|
||||
"``*``","caddy","reverse_proxy","searchHandle","$add_empty='0'"
|
||||
"``*``","caddy","reverse_proxy","searchHeader","$add_empty='0'"
|
||||
"``*``","caddy","reverse_proxy","searchReverseProxy","$add_empty='0'"
|
||||
"``*``","caddy","reverse_proxy","searchSubdomain","$add_empty='0'"
|
||||
"``POST``","caddy","reverse_proxy","set",""
|
||||
"``POST``","caddy","reverse_proxy","setAccessList","$uuid"
|
||||
"``POST``","caddy","reverse_proxy","setBasicAuth","$uuid"
|
||||
"``POST``","caddy","reverse_proxy","setHandle","$uuid"
|
||||
"``POST``","caddy","reverse_proxy","setHeader","$uuid"
|
||||
"``POST``","caddy","reverse_proxy","setReverseProxy","$uuid"
|
||||
"``POST``","caddy","reverse_proxy","setSubdomain","$uuid"
|
||||
"``POST``","caddy","reverse_proxy","toggleHandle","$uuid,$enabled=null"
|
||||
"``POST``","caddy","reverse_proxy","toggleReverseProxy","$uuid,$enabled=null"
|
||||
"``POST``","caddy","reverse_proxy","toggleSubdomain","$uuid,$enabled=null"
|
||||
|
||||
"``<<uses>>``", "", "", "", "*model* `Caddy.xml <https://github.com/opnsense/plugins/blob/master/www/caddy/src/opnsense/mvc/app/models/OPNsense/Caddy/Caddy.xml>`__"
|
||||
|
||||
.. csv-table:: Service (ServiceController.php)
|
||||
:header: "Method", "Module", "Controller", "Command", "Parameters"
|
||||
:widths: 4, 15, 15, 30, 40
|
||||
|
||||
"``POST``","caddy","service","reconfigure",""
|
||||
"``POST``","caddy","service","restart",""
|
||||
"``POST``","caddy","service","start",""
|
||||
"``GET``","caddy","service","status",""
|
||||
"``POST``","caddy","service","stop",""
|
||||
"``GET``","caddy","service","validate",""
|
||||
|
||||
"``<<uses>>``", "", "", "", "*model* `Caddy.xml <https://github.com/opnsense/plugins/blob/master/www/caddy/src/opnsense/mvc/app/models/OPNsense/Caddy/Caddy.xml>`__"
|
||||
@ -1,137 +0,0 @@
|
||||
.. _api_plugins_firewall:
|
||||
|
||||
Firewall
|
||||
~~~~~~~~
|
||||
|
||||
The firewall API plugin (**os-firewall**) offers a way for machine to machine interaction between custom applications and OPNsense, it can
|
||||
easily be installed like any other plugin via :menuselection:`System --> Firmware --> Plugins`.
|
||||
|
||||
Although the plugin does contains a basic user interface (in :menuselection:`Firewall --> Automation`), it's mirely intended
|
||||
as a reference and testbed. There's no relation to any of the rules being managed via the core system.
|
||||
|
||||
.. Tip::
|
||||
|
||||
Use your browsers "inspect" feature to compare requests easily, the user interface in terms of communication is exactly the same
|
||||
as offered by the API . Rules not visible in the web interface (:menuselection:`Firewall --> Automation`) will not be returned by the API either.
|
||||
|
||||
|
||||
|
||||
.. csv-table:: Abstract [non-callable] (FilterBaseController.php)
|
||||
:header: "Method", "Module", "Controller", "Command", "Parameters"
|
||||
:widths: 4, 15, 15, 30, 40
|
||||
|
||||
"``POST``","firewall","filter_base","apply","$rollback_revision=null"
|
||||
"``POST``","firewall","filter_base","cancelRollback","$rollback_revision"
|
||||
"``GET``","firewall","filter_base","get",""
|
||||
"``POST``","firewall","filter_base","revert","$revision"
|
||||
"``POST``","firewall","filter_base","savepoint",""
|
||||
"``POST``","firewall","filter_base","set",""
|
||||
|
||||
"``<<uses>>``", "", "", "", "*model* `Filter.xml <https://github.com/opnsense/plugins/blob/master/net/firewall/src/opnsense/mvc/app/models/OPNsense/Firewall/Filter.xml>`__"
|
||||
|
||||
.. csv-table:: Resources (FilterController.php) -- extends : FilterBaseController
|
||||
:header: "Method", "Module", "Controller", "Command", "Parameters"
|
||||
:widths: 4, 15, 15, 30, 40
|
||||
|
||||
"``POST``","firewall","filter","addRule",""
|
||||
"``POST``","firewall","filter","delRule","$uuid"
|
||||
"``GET``","firewall","filter","getRule","$uuid=null"
|
||||
"``*``","firewall","filter","searchRule",""
|
||||
"``POST``","firewall","filter","setRule","$uuid"
|
||||
"``POST``","firewall","filter","toggleRule","$uuid,$enabled=null"
|
||||
|
||||
.. csv-table:: Resources (SourceNatController.php) -- extends : FilterBaseController
|
||||
:header: "Method", "Module", "Controller", "Command", "Parameters"
|
||||
:widths: 4, 15, 15, 30, 40
|
||||
|
||||
"``POST``","firewall","source_nat","addRule",""
|
||||
"``POST``","firewall","source_nat","delRule","$uuid"
|
||||
"``GET``","firewall","source_nat","getRule","$uuid=null"
|
||||
"``*``","firewall","source_nat","searchRule",""
|
||||
"``POST``","firewall","source_nat","setRule","$uuid"
|
||||
"``POST``","firewall","source_nat","toggleRule","$uuid,$enabled=null"
|
||||
|
||||
|
||||
|
||||
-----------------------
|
||||
Concept
|
||||
-----------------------
|
||||
|
||||
The firewall plugin injects rules in the standard OPNsense firewall while maintaining visibility on them in the
|
||||
standard user interface.
|
||||
|
||||
We use our standard :code:`ApiMutableModelControllerBase` to allow crud operations on rule entries and offer a set of
|
||||
specific actions to apply the new configuration.
|
||||
Since firewall rules can be quite sensitive with a higher risk of lockout, we also support a rollback mechanism here,
|
||||
which offers the ability to rollback this components changes.
|
||||
|
||||
.. blockdiag::
|
||||
:scale: 100%
|
||||
|
||||
diagram init {
|
||||
savepoint [label = "savepoint()"];
|
||||
administration [label = "administration"];
|
||||
apply [label = "apply(savepoint)"];
|
||||
cancelRollback [label = "cancelRollback(sp)"];
|
||||
savepoint -> administration -> apply ;
|
||||
apply -> cancelRollback [label = ".. 60s", style = dashed];
|
||||
}
|
||||
|
||||
|
||||
The diagram above contains the basic steps to change rules, apply and eventually rollback if not being able to access the machine again.
|
||||
When calling :code:`savepoint()` a new config revision will be created and the timestamp will be returned for later use.
|
||||
If the :code:`cancelRollback(savepoint)` is not called within 60 seconds, the firewall will rollback to the previous state
|
||||
identified by the savepoint timestamp (if available).
|
||||
|
||||
|
||||
.. Note::
|
||||
|
||||
The examples in this document disable certificate validation, make sure when using this in a production environment to
|
||||
remove the :code:`verify=False` from the :code:`requests` calls
|
||||
|
||||
.. Tip::
|
||||
|
||||
The number of versions kept can be configured as "backup count" in :menuselection:`System -> Configuration -> History`.
|
||||
This affectively determines within how many configuration changes you can still rollback, if the backup is removed, a rollback
|
||||
will keep the current state (do nothing).
|
||||
|
||||
|
||||
-----------------------
|
||||
Administration example
|
||||
-----------------------
|
||||
|
||||
Administrative endpoints are pretty standard use of :code:`ApiMutableModelControllerBase`, the example below searches for
|
||||
a rule named "OPNsense_fw_api_testrule_1", when not found one will be added otherwise it will print the internal uuid.
|
||||
Inline you will find a brief description of the steps performed.
|
||||
|
||||
|
||||
.. literalinclude:: firewall.sample_create.py
|
||||
:language: python
|
||||
:linenos:
|
||||
:caption: administrative_example.py
|
||||
|
||||
|
||||
.. Tip::
|
||||
|
||||
Since our model contains default values for most attributes, we only need to feed the changes if we would like to keep the
|
||||
defaults. In this case the TCP/IP version was IPv4 by default for example. In most cases one would like to set all relevant properties
|
||||
in case defaults change over time.
|
||||
|
||||
-----------------------
|
||||
Apply / revert example
|
||||
-----------------------
|
||||
|
||||
This example will disable the rule created in the previous example and apply the changes using a savepoint, since we're not
|
||||
calling :code:`cancelRollback(savepoint)` it will revert after 60 seconds to the original state.
|
||||
|
||||
|
||||
.. literalinclude:: firewall.savepoint.py
|
||||
:language: python
|
||||
:linenos:
|
||||
:caption: savepoint_example.py
|
||||
|
||||
|
||||
.. Note::
|
||||
|
||||
The savepoint will only revert this components changes, other changes won't be affected by this revert, for example
|
||||
add an additional interface between savepoint and revert won't be affected.
|
||||
@ -1,114 +0,0 @@
|
||||
.. _api_plugins_firewall:
|
||||
|
||||
{{ title }}
|
||||
{{ title_underline }}
|
||||
|
||||
The firewall API plugin (**os-firewall**) offers a way for machine to machine interaction between custom applications and OPNsense, it can
|
||||
easily be installed like any other plugin via :menuselection:`System --> Firmware --> Plugins`.
|
||||
|
||||
Although the plugin does contains a basic user interface (in :menuselection:`Firewall --> Automation`), it's mirely intended
|
||||
as a reference and testbed. There's no relation to any of the rules being managed via the core system.
|
||||
|
||||
.. Tip::
|
||||
|
||||
Use your browsers "inspect" feature to compare requests easily, the user interface in terms of communication is exactly the same
|
||||
as offered by the API . Rules not visible in the web interface (:menuselection:`Firewall --> Automation`) will not be returned by the API either.
|
||||
|
||||
|
||||
{% for controller in controllers %}
|
||||
.. csv-table:: {{controller.type}} ({{controller.filename}}) {% if not controller.is_abstract %} -- extends : {{controller.base_class}} {% endif %}
|
||||
:header: "Method", "Module", "Controller", "Command", "Parameters"
|
||||
:widths: 4, 15, 15, 30, 40
|
||||
{% for endpoint in controller.endpoints %}
|
||||
"``{{endpoint.method}}``","{{endpoint.module}}","{{endpoint.controller}}","{{endpoint.command}}","{{endpoint.parameters}}"
|
||||
{%- endfor %}
|
||||
{%- if controller.uses %}
|
||||
{% for use in controller.uses %}
|
||||
"``<<uses>>``", "", "", "", "*{{use.type}}* `{{use.name}} <{{use.link}}>`__"
|
||||
{%- endfor %}
|
||||
{%- endif %}
|
||||
{% endfor %}
|
||||
|
||||
|
||||
-----------------------
|
||||
Concept
|
||||
-----------------------
|
||||
|
||||
The firewall plugin injects rules in the standard OPNsense firewall while maintaining visibility on them in the
|
||||
standard user interface.
|
||||
|
||||
We use our standard :code:`ApiMutableModelControllerBase` to allow crud operations on rule entries and offer a set of
|
||||
specific actions to apply the new configuration.
|
||||
Since firewall rules can be quite sensitive with a higher risk of lockout, we also support a rollback mechanism here,
|
||||
which offers the ability to rollback this components changes.
|
||||
|
||||
.. blockdiag::
|
||||
:scale: 100%
|
||||
|
||||
diagram init {
|
||||
savepoint [label = "savepoint()"];
|
||||
administration [label = "administration"];
|
||||
apply [label = "apply(savepoint)"];
|
||||
cancelRollback [label = "cancelRollback(sp)"];
|
||||
savepoint -> administration -> apply ;
|
||||
apply -> cancelRollback [label = ".. 60s", style = dashed];
|
||||
}
|
||||
|
||||
|
||||
The diagram above contains the basic steps to change rules, apply and eventually rollback if not being able to access the machine again.
|
||||
When calling :code:`savepoint()` a new config revision will be created and the timestamp will be returned for later use.
|
||||
If the :code:`cancelRollback(savepoint)` is not called within 60 seconds, the firewall will rollback to the previous state
|
||||
identified by the savepoint timestamp (if available).
|
||||
|
||||
|
||||
.. Note::
|
||||
|
||||
The examples in this document disable certificate validation, make sure when using this in a production environment to
|
||||
remove the :code:`verify=False` from the :code:`requests` calls
|
||||
|
||||
.. Tip::
|
||||
|
||||
The number of versions kept can be configured as "backup count" in :menuselection:`System -> Configuration -> History`.
|
||||
This affectively determines within how many configuration changes you can still rollback, if the backup is removed, a rollback
|
||||
will keep the current state (do nothing).
|
||||
|
||||
|
||||
-----------------------
|
||||
Administration example
|
||||
-----------------------
|
||||
|
||||
Administrative endpoints are pretty standard use of :code:`ApiMutableModelControllerBase`, the example below searches for
|
||||
a rule named "OPNsense_fw_api_testrule_1", when not found one will be added otherwise it will print the internal uuid.
|
||||
Inline you will find a brief description of the steps performed.
|
||||
|
||||
|
||||
.. literalinclude:: firewall.sample_create.py
|
||||
:language: python
|
||||
:linenos:
|
||||
:caption: administrative_example.py
|
||||
|
||||
|
||||
.. Tip::
|
||||
|
||||
Since our model contains default values for most attributes, we only need to feed the changes if we would like to keep the
|
||||
defaults. In this case the TCP/IP version was IPv4 by default for example. In most cases one would like to set all relevant properties
|
||||
in case defaults change over time.
|
||||
|
||||
-----------------------
|
||||
Apply / revert example
|
||||
-----------------------
|
||||
|
||||
This example will disable the rule created in the previous example and apply the changes using a savepoint, since we're not
|
||||
calling :code:`cancelRollback(savepoint)` it will revert after 60 seconds to the original state.
|
||||
|
||||
|
||||
.. literalinclude:: firewall.savepoint.py
|
||||
:language: python
|
||||
:linenos:
|
||||
:caption: savepoint_example.py
|
||||
|
||||
|
||||
.. Note::
|
||||
|
||||
The savepoint will only revert this components changes, other changes won't be affected by this revert, for example
|
||||
add an additional interface between savepoint and revert won't be affected.
|
||||
Loading…
Reference in New Issue