Skip to content

Commit

Permalink
Merge branch 'opnsense:master' into master
Browse files Browse the repository at this point in the history
  • Loading branch information
zenarmor committed Mar 13, 2023
2 parents e132115 + f3c6e5b commit e9d2a63
Show file tree
Hide file tree
Showing 93 changed files with 4,856 additions and 462 deletions.
2 changes: 1 addition & 1 deletion collect_api_endpoints.py
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#!/usr/local/bin/python
#!/usr/local/bin/python3
"""
Copyright (c) 2020 Ad Schellevis <ad@opnsense.org>
All rights reserved.
Expand Down
64 changes: 64 additions & 0 deletions collect_plugin_tiers.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
#!/usr/local/bin/python3
"""
Copyright (c) 2022 Ad Schellevis <ad@opnsense.org>
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
"""
import os
import argparse
import re
from jinja2 import Template

if __name__ == '__main__':
parser = argparse.ArgumentParser()
parser.add_argument('-template_filename', default='source/support.rst.in', help='')
parser.add_argument('source', help='source directory')
cmd_args = parser.parse_args()

# collect all plugins
plugin_tiers = dict()
for root, dirs, files in os.walk(cmd_args.source):
if 'Makefile' in files and 'pkg-descr' in files:
plugin_tier = 3
with open(os.path.join(root, 'Makefile'), 'rt') as f_in:
for line in f_in.read().split('\n'):
parts = line.split()
if len(parts) >= 2 and parts[0].startswith('PLUGIN_TIER') and parts[-1].isdigit():
plugin_tier = int(parts[-1])
plugin_name = root[len(cmd_args.source)+1:]
if plugin_tier not in plugin_tiers:
plugin_tiers[plugin_tier] = {}
plugin_tiers[plugin_tier][plugin_name] = {
'tier': plugin_tier,
'name': plugin_name
}
with open(os.path.join(root, 'pkg-descr'), 'rt') as f_in:
descr = f_in.read().strip().split('\n\n')[0].replace('\n', ' ').replace('"', "'")
plugin_tiers[plugin_tier][plugin_name]['descr'] = descr

template = Template(open(cmd_args.template_filename, "rt").read())
if cmd_args.template_filename.endswith('.in'):
with open(cmd_args.template_filename[:-3], 'w') as f_out:
f_out.write(template.render({'tiers': plugin_tiers}))
else:
print(template.render({'tiers': plugin_tiers}))
5 changes: 3 additions & 2 deletions source/CE_releases.rst
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@ Community Edition
:width: 600px
:align: center

As of January 2015 there have been *237* releases leading to the latest version *22.7.6*
named "Powerful Panther".
As of January 2015 there have been *247* releases leading to the latest version *23.1.2*
named "Quintessential Quail".



Expand All @@ -20,6 +20,7 @@ The list below contains all releases, ordered by version number categorized by m
:titlesonly:
:glob:

releases/CE_23.1
releases/CE_22.7
releases/CE_22.1
releases/CE_21.7
Expand Down
7 changes: 7 additions & 0 deletions source/development/api.rst
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,13 @@ The $key and $secret parameters are used to pass the API credentials using curl.
When using Postman to test an API call, use the 'basic auth' authorization type. The $key and $secret parameters go into Username/Password respectively.
.. note::
Always make sure the owner of the key is authorized to access the resource in question, the "Effective Privileges" set on the user
shows which resources are accessible. (Edit reveals the endpoints assigned to each resource).
ACL's are explained in :doc:`development/components/acl </development/components/acl>`).
Core API
--------
Expand Down
11 changes: 11 additions & 0 deletions source/development/api/core/diagnostics.rst
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,7 @@ Diagnostics
:header: "Method", "Module", "Controller", "Command", "Parameters"
:widths: 4, 15, 15, 30, 40

"``POST``","diagnostics","interface","CarpStatus","$status"
"``POST``","diagnostics","interface","delRoute",""
"``POST``","diagnostics","interface","flushArp",""
"``GET``","diagnostics","interface","getArp",""
Expand All @@ -53,9 +54,13 @@ Diagnostics
"``GET``","diagnostics","interface","getMemoryStatistics",""
"``GET``","diagnostics","interface","getNdp",""
"``GET``","diagnostics","interface","getNetisrStatistics",""
"``GET``","diagnostics","interface","getPfSyncNodes",""
"``GET``","diagnostics","interface","getProtocolStatistics",""
"``GET``","diagnostics","interface","getRoutes",""
"``GET``","diagnostics","interface","getSocketStatistics",""
"``GET``","diagnostics","interface","getVipStatus",""
"``GET``","diagnostics","interface","searchArp",""
"``GET``","diagnostics","interface","searchNdp",""

.. csv-table:: Resources (LvtemplateController.php)
:header: "Method", "Module", "Controller", "Command", "Parameters"
Expand Down Expand Up @@ -108,6 +113,12 @@ Diagnostics

"``<<uses>>``", "", "", "", "*model* `PacketCapture.xml <https://github.com/opnsense/core/blob/master/src/opnsense/mvc/app/models/OPNsense/Diagnostics/PacketCapture.xml>`__"

.. csv-table:: Resources (SystemController.php)
:header: "Method", "Module", "Controller", "Command", "Parameters"
:widths: 4, 15, 15, 30, 40

"``GET``","diagnostics","system","memory",""

.. csv-table:: Resources (SystemhealthController.php)
:header: "Method", "Module", "Controller", "Command", "Parameters"
:widths: 4, 15, 15, 30, 40
Expand Down
9 changes: 9 additions & 0 deletions source/development/api/core/firewall.rst
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
.. _api_core_firewall:

Firewall
~~~~~~~~

Expand All @@ -14,6 +16,7 @@ Firewall
"``GET``","firewall","alias","getItem","$uuid=null"
"``GET``","firewall","alias","getTableSize",""
"``POST``","firewall","alias","import",""
"``GET``","firewall","alias","listCategories",""
"``GET``","firewall","alias","listCountries",""
"``GET``","firewall","alias","listNetworkAliases",""
"``POST``","firewall","alias","reconfigure",""
Expand Down Expand Up @@ -56,3 +59,9 @@ Firewall
:widths: 4, 15, 15, 30, 40

"``GET``","firewall","filter_util","ruleStats",""


.. Tip::

In order to inject rules using an API, you may take a look at the :ref:`Firewall Plugin API <api_plugins_firewall>`,
currently the core system does not support rule modifications via the API for this topic.
22 changes: 22 additions & 0 deletions source/development/api/core/firewall.rst.in
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
.. _api_core_firewall:

{{ title }}
{{ title_underline }}
{% for controller in controllers %}
.. csv-table:: {{controller.type}} ({{controller.filename}})
: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 %}

.. Tip::

In order to inject rules using an API, you may take a look at the :ref:`Firewall Plugin API <api_plugins_firewall>`,
currently the core system does not support rule modifications via the API for this topic.
16 changes: 16 additions & 0 deletions source/development/api/core/interfaces.rst
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,22 @@ Interfaces

"``<<uses>>``", "", "", "", "*model* `Loopback.xml <https://github.com/opnsense/core/blob/master/src/opnsense/mvc/app/models/OPNsense/Interfaces/Loopback.xml>`__"

.. csv-table:: Resources (VipSettingsController.php)
:header: "Method", "Module", "Controller", "Command", "Parameters"
:widths: 4, 15, 15, 30, 40

"``POST``","interfaces","vip_settings","addItem",""
"``POST``","interfaces","vip_settings","delItem","$uuid"
"``GET``","interfaces","vip_settings","get",""
"``GET``","interfaces","vip_settings","getItem","$uuid=null"
"``GET``","interfaces","vip_settings","getUnusedVhid",""
"``POST``","interfaces","vip_settings","reconfigure",""
"``*``","interfaces","vip_settings","searchItem",""
"``POST``","interfaces","vip_settings","set",""
"``POST``","interfaces","vip_settings","setItem","$uuid"

"``<<uses>>``", "", "", "", "*model* `Vip.xml <https://github.com/opnsense/core/blob/master/src/opnsense/mvc/app/models/OPNsense/Interfaces/Vip.xml>`__"

.. csv-table:: Resources (VlanSettingsController.php)
:header: "Method", "Module", "Controller", "Command", "Parameters"
:widths: 4, 15, 15, 30, 40
Expand Down
81 changes: 81 additions & 0 deletions source/development/api/core/ipsec.rst
Original file line number Diff line number Diff line change
@@ -1,6 +1,42 @@
Ipsec
~~~~~

.. csv-table:: Resources (ConnectionsController.php)
:header: "Method", "Module", "Controller", "Command", "Parameters"
:widths: 4, 15, 15, 30, 40

"``POST``","ipsec","connections","addChild",""
"``POST``","ipsec","connections","addConnection",""
"``POST``","ipsec","connections","addLocal",""
"``POST``","ipsec","connections","addRemote",""
"``GET``","ipsec","connections","connectionExists","$uuid"
"``POST``","ipsec","connections","delChild","$uuid"
"``POST``","ipsec","connections","delConnection","$uuid"
"``POST``","ipsec","connections","delLocal","$uuid"
"``POST``","ipsec","connections","delRemote","$uuid"
"``GET``","ipsec","connections","get",""
"``GET``","ipsec","connections","getChild","$uuid=null"
"``GET``","ipsec","connections","getConnection","$uuid=null"
"``GET``","ipsec","connections","getLocal","$uuid=null"
"``GET``","ipsec","connections","getRemote","$uuid=null"
"``GET``","ipsec","connections","isEnabled",""
"``*``","ipsec","connections","searchChild",""
"``*``","ipsec","connections","searchConnection",""
"``*``","ipsec","connections","searchLocal",""
"``*``","ipsec","connections","searchRemote",""
"``POST``","ipsec","connections","set",""
"``POST``","ipsec","connections","setChild","$uuid=null"
"``POST``","ipsec","connections","setConnection","$uuid=null"
"``POST``","ipsec","connections","setLocal","$uuid=null"
"``POST``","ipsec","connections","setRemote","$uuid=null"
"``POST``","ipsec","connections","toggle","$enabled=null"
"``POST``","ipsec","connections","toggleChild","$uuid,$enabled=null"
"``POST``","ipsec","connections","toggleConnection","$uuid,$enabled=null"
"``POST``","ipsec","connections","toggleLocal","$uuid,$enabled=null"
"``POST``","ipsec","connections","toggleRemote","$uuid,$enabled=null"

"``<<uses>>``", "", "", "", "*model* `Swanctl.xml <https://github.com/opnsense/core/blob/master/src/opnsense/mvc/app/models/OPNsense/IPsec/Swanctl.xml>`__"

.. csv-table:: Resources (KeyPairsController.php)
:header: "Method", "Module", "Controller", "Command", "Parameters"
:widths: 4, 15, 15, 30, 40
Expand Down Expand Up @@ -30,6 +66,36 @@ Ipsec
"``POST``","ipsec","legacy_subsystem","applyConfig",""
"``GET``","ipsec","legacy_subsystem","status",""

.. csv-table:: Resources (ManualSpdController.php)
:header: "Method", "Module", "Controller", "Command", "Parameters"
:widths: 4, 15, 15, 30, 40

"``POST``","ipsec","manual_spd","add",""
"``POST``","ipsec","manual_spd","del","$uuid"
"``GET``","ipsec","manual_spd","get","$uuid=null"
"``GET``","ipsec","manual_spd","get",""
"``*``","ipsec","manual_spd","search",""
"``POST``","ipsec","manual_spd","set","$uuid=null"
"``POST``","ipsec","manual_spd","set",""
"``POST``","ipsec","manual_spd","toggle","$uuid,$enabled=null"

"``<<uses>>``", "", "", "", "*model* `Swanctl.xml <https://github.com/opnsense/core/blob/master/src/opnsense/mvc/app/models/OPNsense/IPsec/Swanctl.xml>`__"

.. csv-table:: Resources (PoolsController.php)
:header: "Method", "Module", "Controller", "Command", "Parameters"
:widths: 4, 15, 15, 30, 40

"``POST``","ipsec","pools","add",""
"``POST``","ipsec","pools","del","$uuid"
"``GET``","ipsec","pools","get","$uuid=null"
"``GET``","ipsec","pools","get",""
"``*``","ipsec","pools","search",""
"``POST``","ipsec","pools","set","$uuid=null"
"``POST``","ipsec","pools","set",""
"``POST``","ipsec","pools","toggle","$uuid,$enabled=null"

"``<<uses>>``", "", "", "", "*model* `Swanctl.xml <https://github.com/opnsense/core/blob/master/src/opnsense/mvc/app/models/OPNsense/IPsec/Swanctl.xml>`__"

.. csv-table:: Resources (PreSharedKeysController.php)
:header: "Method", "Module", "Controller", "Command", "Parameters"
:widths: 4, 15, 15, 30, 40
Expand Down Expand Up @@ -90,3 +156,18 @@ Ipsec
"``POST``","ipsec","tunnel","toggle","$enabled=null"
"``POST``","ipsec","tunnel","togglePhase1","$ikeid,$enabled=null"
"``POST``","ipsec","tunnel","togglePhase2","$seqid,$enabled=null"

.. csv-table:: Resources (VtiController.php)
:header: "Method", "Module", "Controller", "Command", "Parameters"
:widths: 4, 15, 15, 30, 40

"``POST``","ipsec","vti","add",""
"``POST``","ipsec","vti","del","$uuid"
"``GET``","ipsec","vti","get","$uuid=null"
"``GET``","ipsec","vti","get",""
"``*``","ipsec","vti","search",""
"``POST``","ipsec","vti","set","$uuid=null"
"``POST``","ipsec","vti","set",""
"``POST``","ipsec","vti","toggle","$uuid,$enabled=null"

"``<<uses>>``", "", "", "", "*model* `Swanctl.xml <https://github.com/opnsense/core/blob/master/src/opnsense/mvc/app/models/OPNsense/IPsec/Swanctl.xml>`__"
11 changes: 11 additions & 0 deletions source/development/api/core/unbound.rst
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,16 @@ Unbound
"``GET``","unbound","diagnostics","listlocalzones",""
"``GET``","unbound","diagnostics","stats",""

.. csv-table:: Resources (OverviewController.php)
:header: "Method", "Module", "Controller", "Command", "Parameters"
:widths: 4, 15, 15, 30, 40

"``GET``","unbound","overview","Rolling","$timeperiod,$clients=false"
"``GET``","unbound","overview","isBlockListEnabled",""
"``GET``","unbound","overview","isEnabled",""
"``GET``","unbound","overview","searchQueries",""
"``GET``","unbound","overview","totals","$maximum"

.. csv-table:: Service (ServiceController.php)
:header: "Method", "Module", "Controller", "Command", "Parameters"
:widths: 4, 15, 15, 30, 40
Expand Down Expand Up @@ -56,5 +66,6 @@ Unbound
"``POST``","unbound","settings","toggleForward","$uuid,$enabled=null"
"``POST``","unbound","settings","toggleHostAlias","$uuid,$enabled=null"
"``POST``","unbound","settings","toggleHostOverride","$uuid,$enabled=null"
"``POST``","unbound","settings","updateBlocklist",""

"``<<uses>>``", "", "", "", "*model* `Unbound.xml <https://github.com/opnsense/core/blob/master/src/opnsense/mvc/app/models/OPNsense/Unbound/Unbound.xml>`__"
16 changes: 13 additions & 3 deletions source/development/api/plugins/firewall.rst
Original file line number Diff line number Diff line change
@@ -1,9 +1,19 @@
.. _api_plugins_firewall:

Firewall
~~~~~~~~

The firewall API plugin is a first step into migrating the legacy firewall components from OPNsense, although it does contain
a user interface, it's main focus is only to provide machine to machine interaction between custom applications and OPNsense
for selected features.
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)
Expand Down
16 changes: 13 additions & 3 deletions source/development/api/plugins/firewall.rst.in
Original file line number Diff line number Diff line change
@@ -1,9 +1,19 @@
.. _api_plugins_firewall:

{{ title }}
{{ title_underline }}

The firewall API plugin is a first step into migrating the legacy firewall components from OPNsense, although it does contain
a user interface, it's main focus is only to provide machine to machine interaction between custom applications and OPNsense
for selected features.
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 %}
Expand Down
Loading

0 comments on commit e9d2a63

Please sign in to comment.