Restructured port forward endpoint to be more efficient and organized, added update function to port forward endpoint, updated unit test for port forwards, updated documentation

Author: Jared Hendrickson

README.md

@@ -513,6 +513,7 @@ There is no limit to API calls at this time but is important to note that pfSens
   * [Create NAT Port Forwards](#1-create-nat-port-forwards)
   * [Delete NAT Port Forwards](#2-delete-nat-port-forwards)
   * [Read NAT Port Forwards](#3-read-nat-port-forwards)
+  * [Update NAT Port Forwards](#4-update-nat-port-forwards)
 
 * [FIREWALL/RULE](#firewallrule)
 
@@ -1044,7 +1045,6 @@ URL: https://{{$hostname}}/api/v1/firewall/nat/port_forward
 
 | Key | Value | Description |
 | --- | ------|-------------|
-| type | string | Set a firewall rule type (`pass`, `block`, `reject`) |
 | interface | string | Set which interface the rule will apply to. You may specify either the interface's descriptive name, the pfSense ID (wan, lan, optx), or the physical interface id (e.g. igb0). Floating rules are not supported.  |
 | protocol | string | Set which transfer protocol the rule will apply to. If `tcp`, `udp`, `tcp/udp`, you must define a source and destination port |
 | src | string | Set the source address of the firewall rule. This may be a single IP, network CIDR, alias name, or interface. When specifying an interface, you may use the physical interface ID, the descriptive interfance name, or the pfSense ID. To use only interface address, add `ip` to the end of the interface name otherwise the entire interface's subnet is implied. To negate the context of the source address, you may prepend the address with `!` |
@@ -1056,7 +1056,7 @@ URL: https://{{$hostname}}/api/v1/firewall/nat/port_forward
 | natreflection | string | Set the NAT reflection mode explicitly (optional) |
 | descr | string | Set a description for the rule (optional) |
 | disabled | boolean | Disable the rule upon creation (optional) |
-| top | boolean | Add firewall rule to top of access control list (optional) |
+| top | boolean | Add this port forward rule to top of access control list (optional) |
 
 
 
@@ -1146,6 +1146,65 @@ URL: https://{{$hostname}}/api/v1/firewall/nat/port_forward
 
 
 
+### 4. Update NAT Port Forwards
+
+
+Update an existing port forward rule.<br><br>
+
+_Requires at least one of the following privileges:_ [`page-all`, `page-firewall-nat-portforward-edit`]
+
+
+***Endpoint:***
+
+```bash
+Method: PUT
+Type: RAW
+URL: https://{{$hostname}}/api/v1/firewall/nat/port_forward
+```
+
+
+
+***Query params:***
+
+| Key | Value | Description |
+| --- | ------|-------------|
+| Id | Integer | Specify the ID of the port forward rule to update. |
+| interface | string | Update the interface the rule will apply to. You may specify either the interface's descriptive name, the pfSense ID (wan, lan, optx), or the physical interface id (e.g. igb0). Floating rules are not supported. (optional) |
+| protocol | string | Update which transfer protocol the rule will apply to. If `tcp`, `udp`, `tcp/udp`, you must define a source and destination port. (optional) |
+| src | string | Update the source address of the firewall rule. This may be a single IP, network CIDR, alias name, or interface. When specifying an interface, you may use the physical interface ID, the descriptive interfance name, or the pfSense ID. To use only interface address, add `ip` to the end of the interface name otherwise the entire interface's subnet is implied. To negate the context of the source address, you may prepend the address with `!` (optional) |
+| dst | string | Update the destination address of the firewall rule. This may be a single IP, network CIDR, alias name, or interface. When specifying an interface, you may use the physical interface ID, the descriptive interface name, or the pfSense ID. To only use interface address, add `ip` to the end of the interface name otherwise the entire interface's subnet is implied. To negate the context of the source address, you may prepend the address with `!` (optional) |
+| srcport | string or integer | Update the TCP and/or UDP source port of the firewall rule. This is only necessary if you have specified the `protocol` to `tcp`, `udp`, `tcp/udp` (optional) |
+| dstport | string or integer | Update the TCP and/or UDP destination port of the firewall rule. This is only necessary if you have specified the `protocol` to `tcp`, `udp`, `tcp/udp` (optional) |
+| target | string | Update the IP to forward traffic to (optional) |
+| local-port | string | Udate the TCP and/or UDP  port to forward traffic to. This is only necessary if you have specified the `protocol` to `tcp`, `udp`, `tcp/udp`. Port ranges may be specified using colon or hyphen. (optional) |
+| natreflection | string | Update the NAT reflection mode explicitly (optional) |
+| descr | string | Update a description for the rule (optional) |
+| disabled | boolean | Enable or disable the rule upon creation. True to disable, false to enable (optional) |
+| top | boolean | Move this port forward rule to top of access control list (optional) |
+
+
+
+***Body:***
+
+```js        
+{
+	"interface": "WAN",
+	"protocol": "tcp",
+	"src": "any",
+	"srcport": "433",
+	"dst": "em0ip",
+	"dstport": "443",
+	"target": "192.168.1.123",
+	"local-port": "443",
+	"natreflection": "purenat",
+	"descr": "Forward pb to lc",
+	"nosync": true,
+	"top": false
+}
+```
+
+
+
 ## FIREWALL/RULE
 
 

docs/documentation.json

@@ -2704,7 +2704,7 @@
 											}
 										},
 										"url": {
-											"raw": "https://{{$hostname}}/api/v1/firewall/nat/port_forward?type=string&interface=string&protocol=string&src=string&dst=string&srcport=string or integer&dstport=string or integer&target=string&local-port=string&natreflection=string&descr=string&disabled=boolean&top=boolean",
+											"raw": "https://{{$hostname}}/api/v1/firewall/nat/port_forward?interface=string&protocol=string&src=string&dst=string&srcport=string or integer&dstport=string or integer&target=string&local-port=string&natreflection=string&descr=string&disabled=boolean&top=boolean",
 											"protocol": "https",
 											"host": [
 												"{{$hostname}}"
@@ -2717,11 +2717,6 @@
 												"port_forward"
 											],
 											"query": [
-												{
-													"key": "type",
-													"value": "string",
-													"description": "Set a firewall rule type (`pass`, `block`, `reject`)"
-												},
 												{
 													"key": "interface",
 													"value": "string",
@@ -2780,14 +2775,113 @@
 												{
 													"key": "top",
 													"value": "boolean",
-													"description": "Add firewall rule to top of access control list (optional)"
+													"description": "Add this port forward rule to top of access control list (optional)"
 												}
 											]
 										},
 										"description": "Add a new NAT port forward rule.<br><br>\n\n_Requires at least one of the following privileges:_ [`page-all`, `page-firewall-nat-portforward-edit`]"
 									},
 									"response": []
 								},
+								{
+									"name": "Update NAT Port Forwards",
+									"request": {
+										"method": "PUT",
+										"header": [],
+										"body": {
+											"mode": "raw",
+											"raw": "{\n\t\"interface\": \"WAN\",\n\t\"protocol\": \"tcp\",\n\t\"src\": \"any\",\n\t\"srcport\": \"433\",\n\t\"dst\": \"em0ip\",\n\t\"dstport\": \"443\",\n\t\"target\": \"192.168.1.123\",\n\t\"local-port\": \"443\",\n\t\"natreflection\": \"purenat\",\n\t\"descr\": \"Forward pb to lc\",\n\t\"nosync\": true,\n\t\"top\": false\n}",
+											"options": {
+												"raw": {
+													"language": "json"
+												}
+											}
+										},
+										"url": {
+											"raw": "https://{{$hostname}}/api/v1/firewall/nat/port_forward?Id=Integer&interface=string&protocol=string&src=string&dst=string&srcport=string or integer&dstport=string or integer&target=string&local-port=string&natreflection=string&descr=string&disabled=boolean&top=boolean",
+											"protocol": "https",
+											"host": [
+												"{{$hostname}}"
+											],
+											"path": [
+												"api",
+												"v1",
+												"firewall",
+												"nat",
+												"port_forward"
+											],
+											"query": [
+												{
+													"key": "Id",
+													"value": "Integer",
+													"description": "Specify the ID of the port forward rule to update."
+												},
+												{
+													"key": "interface",
+													"value": "string",
+													"description": "Update the interface the rule will apply to. You may specify either the interface's descriptive name, the pfSense ID (wan, lan, optx), or the physical interface id (e.g. igb0). Floating rules are not supported. (optional)"
+												},
+												{
+													"key": "protocol",
+													"value": "string",
+													"description": "Update which transfer protocol the rule will apply to. If `tcp`, `udp`, `tcp/udp`, you must define a source and destination port. (optional)"
+												},
+												{
+													"key": "src",
+													"value": "string",
+													"description": "Update the source address of the firewall rule. This may be a single IP, network CIDR, alias name, or interface. When specifying an interface, you may use the physical interface ID, the descriptive interfance name, or the pfSense ID. To use only interface address, add `ip` to the end of the interface name otherwise the entire interface's subnet is implied. To negate the context of the source address, you may prepend the address with `!` (optional)"
+												},
+												{
+													"key": "dst",
+													"value": "string",
+													"description": "Update the destination address of the firewall rule. This may be a single IP, network CIDR, alias name, or interface. When specifying an interface, you may use the physical interface ID, the descriptive interface name, or the pfSense ID. To only use interface address, add `ip` to the end of the interface name otherwise the entire interface's subnet is implied. To negate the context of the source address, you may prepend the address with `!` (optional)"
+												},
+												{
+													"key": "srcport",
+													"value": "string or integer",
+													"description": "Update the TCP and/or UDP source port of the firewall rule. This is only necessary if you have specified the `protocol` to `tcp`, `udp`, `tcp/udp` (optional)"
+												},
+												{
+													"key": "dstport",
+													"value": "string or integer",
+													"description": "Update the TCP and/or UDP destination port of the firewall rule. This is only necessary if you have specified the `protocol` to `tcp`, `udp`, `tcp/udp` (optional)"
+												},
+												{
+													"key": "target",
+													"value": "string",
+													"description": "Update the IP to forward traffic to (optional)"
+												},
+												{
+													"key": "local-port",
+													"value": "string",
+													"description": "Udate the TCP and/or UDP  port to forward traffic to. This is only necessary if you have specified the `protocol` to `tcp`, `udp`, `tcp/udp`. Port ranges may be specified using colon or hyphen. (optional)"
+												},
+												{
+													"key": "natreflection",
+													"value": "string",
+													"description": "Update the NAT reflection mode explicitly (optional)"
+												},
+												{
+													"key": "descr",
+													"value": "string",
+													"description": "Update a description for the rule (optional)"
+												},
+												{
+													"key": "disabled",
+													"value": "boolean",
+													"description": "Enable or disable the rule upon creation. True to disable, false to enable (optional)"
+												},
+												{
+													"key": "top",
+													"value": "boolean",
+													"description": "Move this port forward rule to top of access control list (optional)"
+												}
+											]
+										},
+										"description": "Update an existing port forward rule.<br><br>\n\n_Requires at least one of the following privileges:_ [`page-all`, `page-firewall-nat-portforward-edit`]"
+									},
+									"response": []
+								},
 								{
 									"name": "Delete NAT Port Forwards",
 									"request": {

pfSense-pkg-API/files/etc/inc/api/endpoints/APIFirewallNATPortForward.inc

@@ -28,6 +28,10 @@ class APIFirewallNATPortForward extends APIEndpoint {
         return (new APIFirewallNATPortForwardCreate())->call();
     }
 
+    protected function put() {
+        return (new APIFirewallNATPortForwardUpdate())->call();
+    }
+
     protected function delete() {
         return (new APIFirewallNATPortForwardDelete())->call();
     }

pfSense-pkg-API/files/etc/inc/api/framework/APITools.inc

@@ -287,30 +287,25 @@ function enable_carp($enable) {
 }
 
 // Sorts nat rules by specified criteria and reloads the filter
-function sort_nat_rules($mode=null, $data=null) {
+function sort_nat_rules($top=false, $data=null) {
     // Variables
     global $config;
     $sort_arr = [];
-    $master_arr = [];
-    foreach ($config["nat"]["rule"] as $idx => $fre) {
-        $curr_iface = $fre["interface"];    // Save our current entries interface
-        // Create our interface array if does not exist
-        if (!isset($sort_arr[$curr_iface])) {
-            $sort_arr[$curr_iface] = [];
-        }
-        // Check if user requested this rule to be placed at the top of array
-        if ($mode === "top" and $idx === $data) {
-            array_unshift($sort_arr[$curr_iface], $fre);
+    $rules = (array_key_exists(0, $config["nat"]["rule"])) ? $config["nat"]["rule"] : [$config["nat"]["rule"]];
+
+    foreach ($rules as $idx => $fre) {
+        # Check if top mode is enabled, if so add this item to the start of the array
+        if ($top === true and $idx === $data) {
+            array_unshift($sort_arr, $fre);
         } else {
-            $sort_arr[$curr_iface][] = $fre;
+            $sort_arr[] = $fre;
         }
     }
-    foreach ($sort_arr as $if) {
-        foreach ($if as $rule) {
-            $master_arr[] = $rule;
-        }
+    if (!empty($config["nat"]["rule"])) {
+        $config["nat"]["rule"] = $sort_arr;
+    } else {
+        unset($config["nat"]["rule"]);
     }
-    $config["nat"]["rule"] = $master_arr;
 }
 
 # Input a physical interface ID, or a descriptive interface name, and return the pfSense interface ID (lan,wan,optx)