Skip to content

Commit 77bd033

Browse files
author
Jared Hendrickson
committed
Added create, update and delete for routing gateway endpoint, updated routing gateway unit test, updated docs, included bug fix for blank alias entry bug
1 parent 7b57c77 commit 77bd033

11 files changed

Lines changed: 1681 additions & 165 deletions

File tree

‎README.md‎

Lines changed: 176 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -577,7 +577,10 @@ There is no limit to API calls at this time but is important to note that pfSens
577577

578578
* [ROUTING/GATEWAY](#routinggateway)
579579

580-
* [Read Routing Gateways](#1-read-routing-gateways)
580+
* [Create Routing Gateways](#1-create-routing-gateways)
581+
* [Delete Routing Gateways](#2-delete-routing-gateways)
582+
* [Read Routing Gateways](#3-read-routing-gateways)
583+
* [Update Routing Gateways](#4-update-routing-gateways)
581584

582585
* [ROUTING/STATIC_ROUTE](#routingstatic_route)
583586

@@ -962,7 +965,7 @@ URL: https://{{$hostname}}/api/v1/firewall/alias/entry
962965
| --- | ------|-------------|
963966
| name | string | Name of alias to add new address values |
964967
| address | string or array | Array of values to add to alias. A single value may be specified as string. |
965-
| detail | string or array | Array of descriptions for alias values. Descriptions must match the order the that they are specified in the `address` array. Single descriptions may be specified as string |
968+
| detail | string or array | Array of descriptions for alias values. Descriptions must match the order the that they are specified in the `address` array. Single descriptions may be specified as string. If you pass In less `detail` values than `address` values, a default auto-created detail will be applied to the remaining values. (optional) |
966969

967970

968971

@@ -2534,7 +2537,103 @@ URL: https://{{$hostname}}/api/v1/interface/vlan
25342537

25352538

25362539

2537-
### 1. Read Routing Gateways
2540+
### 1. Create Routing Gateways
2541+
2542+
2543+
Create new routing gateways.<br><br>
2544+
2545+
_Requires at least one of the following privileges:_ [`page-all`, `page-system-gateways-editgateway`]
2546+
2547+
2548+
***Endpoint:***
2549+
2550+
```bash
2551+
Method: POST
2552+
Type: RAW
2553+
URL: https://{{$hostname}}/api/v1/routing/gateway
2554+
```
2555+
2556+
2557+
2558+
***Query params:***
2559+
2560+
| Key | Value | Description |
2561+
| --- | ------|-------------|
2562+
| interface | string | Set which interface the gateway 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). |
2563+
| ipprotocol | string | Set what IP protocol this gateway will serve. Options are `inet` for IPv4, or `inet6` for IPv6. |
2564+
| name | string | Set a descriptive name for this gateway. This name must be unique, and can only contains alphanumeric characters and underscores. |
2565+
| gateway | string | Set the IP address of the gateway. This value must be a valid IPv4 address If you have set your `ipprotocol` value to `inet`, or it must be a valid IPv6 address if you have set your `ipprotocol` value to `inet6`. Unlike the pfSense webConfigurator, this address Is not restricted to an address within the interfaces subnet by default. |
2566+
| monitor | string | Set the IP address used to monitor this gateway. This is usually only necessary if the `gateway` IP does not accept ICMP probes. Defaults to the `gateway` address. (optional) |
2567+
| disabled | boolean | Disable this gateway upon creation. Defaults to false. (optional) |
2568+
| monitor_disable | boolean | Disable gateway monitoring for this gateway. Defaults to false. (optional) |
2569+
| action_disable | boolean | Disable any action taken on gateway events for this gateway. This will consider the gateway always up. Defaults to false. (optional) |
2570+
| force_down | boolean | Force this gateway to always be considered down. Defaults to false. (optional) |
2571+
| descr | string | Set a description for this gateway (optional) |
2572+
| weight | integer | Set this gateways weight when utilizing gateway load balancing within a gateway group. This value must be between 1 and 30. Defaults to 1. (optional) |
2573+
| data_payload | integer | Set a data payload to send on ICMP packets sent to the gateway monitor IP. This value must be a positive integer. Defaults to 1. (optional) |
2574+
| latencylow | integer | Set the low threshold in milliseconds for latency. Any packet that exceeds this threshold will be trigger a minor latency gateway event. This value must be a positive integer that is less than the `latencyhigh` value. Defaults to 200. (optional) |
2575+
| latencyhigh | integer | Set the high threshold in milliseconds for latency. Any packet that exceeds this threshold will be trigger a major latency gateway event. This value must be a positive integer that is greater than the `latencylow` value. Defaults to 500. (optional) |
2576+
| losslow | integer | Set the low threshold for packet loss In %. If total packet loss exceeds this percentage, a minor packet loss gateway event will be triggered. This value must be greater or equal to 1 and be less than the `losshigh` value. Defaults to 10. (optional) |
2577+
| losshigh | integer | Set the high threshold for packet loss In %. If total packet loss exceeds this percentage, a major packet loss gateway event will be triggered. This value must be greater than the `losslow` value and be less or equal to 100. Defaults to 20. (optional) |
2578+
| interval | integer | Set how often gateway monitor ICMP probes will be sent in milliseconds. This value must be greater than or equal to 1 and less than or equal to 3600000. Defaults to 500. (optional) |
2579+
| loss_interval | integer | Set how long the gateway monitor will wait (in milliseconds) for response packets before considering the packet lost. This value must be greater than or equal to the `latencyhigh` value. Defaults to 2000. (optional) |
2580+
| time_period | integer | Set the time period In milliseconds for gateway monitor metrics to be averaged. This value must be greater than twice the probe interval plus the loss interval. Defaults to 60000. (optional) |
2581+
| alert_interval | integer | Set the time interval in milliseconds which alert conditions will be checked. This value must be greater than or equal to the `interval` value. Defaults to 1000. (optional) |
2582+
2583+
2584+
2585+
***Body:***
2586+
2587+
```js
2588+
{
2589+
"interface": "wan",
2590+
"name": "TEST_GATEWAY",
2591+
"ipprotocol": "inet",
2592+
"gateway": "172.16.209.1",
2593+
"monitor": "172.16.209.250",
2594+
"descr": "Test gateway"
2595+
}
2596+
```
2597+
2598+
2599+
2600+
### 2. Delete Routing Gateways
2601+
2602+
2603+
Delete existing routing gateways.<br><br>
2604+
2605+
_Requires at least one of the following privileges:_ [`page-all`, `page-system-gateways-editgateway`]
2606+
2607+
2608+
***Endpoint:***
2609+
2610+
```bash
2611+
Method: DELETE
2612+
Type: RAW
2613+
URL: https://{{$hostname}}/api/v1/routing/gateway
2614+
```
2615+
2616+
2617+
2618+
***Query params:***
2619+
2620+
| Key | Value | Description |
2621+
| --- | ------|-------------|
2622+
| id | integer | Specify the ID of the gateway to delete |
2623+
2624+
2625+
2626+
***Body:***
2627+
2628+
```js
2629+
{
2630+
2631+
}
2632+
```
2633+
2634+
2635+
2636+
### 3. Read Routing Gateways
25382637

25392638

25402639
Read routing gateways.<br><br>
@@ -2556,8 +2655,80 @@ URL: https://{{$hostname}}/api/v1/routing/gateway
25562655

25572656
```js
25582657
{
2559-
"client-id": "admin",
2560-
"client-token": "pfsense"
2658+
2659+
}
2660+
```
2661+
2662+
2663+
2664+
### 4. Update Routing Gateways
2665+
2666+
2667+
Update existing routing gateways.<br><br>
2668+
2669+
_Requires at least one of the following privileges:_ [`page-all`, `page-system-gateways-editgateway`]
2670+
2671+
2672+
***Endpoint:***
2673+
2674+
```bash
2675+
Method: PUT
2676+
Type: RAW
2677+
URL: https://{{$hostname}}/api/v1/routing/gateway
2678+
```
2679+
2680+
2681+
2682+
***Query params:***
2683+
2684+
| Key | Value | Description |
2685+
| --- | ------|-------------|
2686+
| interface | string | Update the interface the gateway 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). (optional) |
2687+
| ipprotocol | string | Update the IP protocol this gateway will serve. Options are `inet` for IPv4, or `inet6` for IPv6. If you are changing the protocol, you will also be required to update the `gateway` and/or `monitor` values to match the specified protocol. (optional) |
2688+
| name | string | Update the descriptive name for this gateway. This name must be unique, and can only contain alphanumeric characters and underscores. (optional) |
2689+
| gateway | string | Update the IP address of the gateway. This value must be a valid IPv4 address If you have set your `ipprotocol` value to `inet`, or it must be a valid IPv6 address if you have set your `ipprotocol` value to `inet6`. Unlike the pfSense webConfigurator, this address Is not restricted to an address within the interfaces subnet by default. (optional) |
2690+
| monitor | string | Set the IP address used to monitor this gateway. This is usually only necessary if the `gateway` IP does not accept ICMP probes. Defaults to the `gateway` address. (optional) |
2691+
| disabled | boolean | Enable or disable this gateway upon update. True to disable, false to enable. (optional) |
2692+
| monitor_disable | boolean | Enable or disable gateway monitoring for this gateway. True to disable, false to enable. (optional) |
2693+
| action_disable | boolean | Enable or disable any action taken on gateway events for this gateway. If disabled, this will consider the gateway always up. True for disabled, false for enable. (optional) |
2694+
| force_down | boolean | Enable or disable forcing this gateway to always be considered down. True for enable, false for disable. (optional) |
2695+
| descr | string | Update the description for this gateway (optional) |
2696+
| weight | integer | Update this gateways weight when utilizing gateway load balancing within a gateway group. This value must be between 1 and 30. (optional) |
2697+
| data_payload | integer | Update the data payload to send on ICMP packets sent to the gateway monitor IP. This value must be a positive integer. (optional) |
2698+
| latencylow | integer | Update the low threshold in milliseconds for latency. Any packet that exceeds this threshold will be trigger a minor latency gateway event. This value must be a positive integer that is less than the `latencyhigh` value. (optional) |
2699+
| latencyhigh | integer | Update the high threshold in milliseconds for latency. Any packet that exceeds this threshold will be trigger a major latency gateway event. This value must be a positive integer that is greater than the `latencylow` value. (optional) |
2700+
| losslow | integer | Update the low threshold for packet loss In %. If total packet loss exceeds this percentage, a minor packet loss gateway event will be triggered. This value must be greater or equal to 1 and be less than the `losshigh` value. (optional) |
2701+
| losshigh | integer | Update the high threshold for packet loss In %. If total packet loss exceeds this percentage, a major packet loss gateway event will be triggered. This value must be greater than the `losslow` value and be less or equal to 100. (optional) |
2702+
| interval | integer | Update how often gateway monitor ICMP probes will be sent in milliseconds. This value must be greater than or equal to 1 and less than or equal to 3600000. (optional) |
2703+
| loss_interval | integer | Update how long the gateway monitor will wait (in milliseconds) for response packets before considering the packet lost. This value must be greater than or equal to the `latencyhigh` value. (optional) |
2704+
| time_period | integer | Update the time period In milliseconds for gateway monitor metrics to be averaged. This value must be greater than twice the probe interval plus the loss interval. (optional) |
2705+
| alert_interval | integer | Update the time interval in milliseconds which alert conditions will be checked. This value must be greater than or equal to the `interval` value. (optional) |
2706+
2707+
2708+
2709+
***Body:***
2710+
2711+
```js
2712+
{
2713+
"id": 0,
2714+
"name": "UPDATED_TEST_GATEWAY",
2715+
"ipprotocol": "inet6",
2716+
"gateway": "2001:0db8:85a3:0000:0000:8a2e:0370:7334",
2717+
"monitor": "2001:0db8:85a3:0000:0000:8a2e:0370:7334",
2718+
"descr": "Updated Unit Test",
2719+
"disabled": true,
2720+
"action_disable": true,
2721+
"monitor_disable": true,
2722+
"weight": 2,
2723+
"data_payload": 5,
2724+
"latencylow": 300,
2725+
"latencyhigh": 600,
2726+
"interval": 2100,
2727+
"loss_interval": 2500,
2728+
"action_interval": 1040,
2729+
"time_period": 66000,
2730+
"losslow": 5,
2731+
"losshigh": 10
25612732
}
25622733
```
25632734

0 commit comments

Comments
 (0)