Skip to content

Commit 7b57c77

Browse files
author
Jared Hendrickson
committed
Create endpoint to create, read, update and delete outbound NAT mappings, created unit test for outbound NAT mapping endpoint, updated documentation
1 parent 203d056 commit 7b57c77

14 files changed

Lines changed: 1548 additions & 9 deletions

‎README.md‎

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -520,6 +520,13 @@ There is no limit to API calls at this time but is important to note that pfSens
520520
* [Read Outbound NAT Settings](#1-read-outbound-nat-settings)
521521
* [Update Outbound NAT Settings](#2-update-outbound-nat-settings)
522522

523+
* [FIREWALL/NAT/OUTBOUND/MAPPING](#firewallnatoutboundmapping)
524+
525+
* [Create Outbound NAT Mappings](#1-create-outbound-nat-mappings)
526+
* [Delete Outbound NAT Mappings](#2-delete-outbound-nat-mappings)
527+
* [Read Outbound NAT Mappings](#3-read-outbound-nat-mappings)
528+
* [Update Outbound NAT Mappings](#4-update-outbound-nat-mappings)
529+
523530
* [FIREWALL/NAT/PORTFOWARD](#firewallnatportfoward)
524531

525532
* [Create NAT Port Forwards](#1-create-nat-port-forwards)
@@ -1277,6 +1284,211 @@ URL: https://{{$hostname}}/api/v1/firewall/nat/outbound
12771284

12781285

12791286

1287+
## FIREWALL/NAT/OUTBOUND/MAPPING
1288+
1289+
1290+
1291+
### 1. Create Outbound NAT Mappings
1292+
1293+
1294+
Create new outbound NAT mappings.<br><br>
1295+
1296+
_Requires at least one of the following privileges:_ [`page-all`, `page-firewall-nat-outbound-edit`]
1297+
1298+
1299+
***Endpoint:***
1300+
1301+
```bash
1302+
Method: POST
1303+
Type: RAW
1304+
URL: https://{{$hostname}}/api/v1/firewall/nat/outbound/mapping
1305+
```
1306+
1307+
1308+
1309+
***Query params:***
1310+
1311+
| Key | Value | Description |
1312+
| --- | ------|-------------|
1313+
| interface | string | Set which interface the mapping 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). |
1314+
| protocol | string | Set which transfer protocol the mapping will apply to. |
1315+
| src | string | Set the source address of the firewall rule. This must be an IP, CIDR, alias or any. |
1316+
| dst | string | Set the destination address of the firewall rule. This may be a single IP, network CIDR, or alias name. To negate the context of the address, you may prepend the address with `!` |
1317+
| srcport | string or integer | Set 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` |
1318+
| dstport | string or integer | Set 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` |
1319+
| target | string | Specify the external IP to map this traffic to. This may be an IP address, IP subnet, alias, or empty string to use the Interface address. |
1320+
| natport | string | Set the TCP and/or UDP port or port range to utilize when NATing (optional) |
1321+
| staticnatport | boolean | Enable or disable static NAT ports. When enabling this field, any existing `natport` value will be lost. Defaults to false. (optional) |
1322+
| descr | string | Set a description for the rule (optional) |
1323+
| poolopts | string | Set the outbound NAT pool option for load balancing. Options are `round-robin`, `round-robin sticky-address`, `random`, `random sticky-address`, `source-hash`, `bitmask` or empty string for default. (optional) |
1324+
| source_hash_key | string | Set a custom key hash to use when utilizing the `source-hash` NAT pool option. Value must start with `0x` following a 32 digit hex value. If this field is not specified, a random key hash will be generated. This field Is only available when `poolopts` Is set to `source-hash`. (optional) |
1325+
| disabled | boolean | Disable the rule upon creation. Defaults to false. (optional) |
1326+
| nonat | boolean | Enable or disable NAT for traffic that matches this rule. True for no NAT, false to enable NAT. Defaults to false. (optional) |
1327+
| top | boolean | Add this mapping to top of access control list. Defaults to false. (optional) |
1328+
| apply | boolean | Immediately apply this mapping after creation. Defaults to false. (optional) |
1329+
1330+
1331+
1332+
***Body:***
1333+
1334+
```js
1335+
{
1336+
"interface": "WAN",
1337+
"protocol": "tcp",
1338+
"src": "any",
1339+
"srcport": "433",
1340+
"dst": "em0ip",
1341+
"dstport": "443",
1342+
"target": "192.168.1.123",
1343+
"local-port": "443",
1344+
"natreflection": "purenat",
1345+
"descr": "Forward pb to lc",
1346+
"nosync": true,
1347+
"top": false
1348+
}
1349+
```
1350+
1351+
1352+
1353+
### 2. Delete Outbound NAT Mappings
1354+
1355+
1356+
Update existing outbound NAT mappings.<br><br>
1357+
1358+
_Requires at least one of the following privileges:_ [`page-all`, `page-firewall-nat-outbound-edit`]
1359+
1360+
1361+
***Endpoint:***
1362+
1363+
```bash
1364+
Method: DELETE
1365+
Type: RAW
1366+
URL: https://{{$hostname}}/api/v1/firewall/nat/outbound/mapping
1367+
```
1368+
1369+
1370+
1371+
***Query params:***
1372+
1373+
| Key | Value | Description |
1374+
| --- | ------|-------------|
1375+
| id | integer | Specify the ID of the outbound NAT mapping to update |
1376+
| apply | boolean | Immediately delete this outbound NAT mapping. Defaults to false. (optional) |
1377+
1378+
1379+
1380+
***Body:***
1381+
1382+
```js
1383+
{
1384+
"interface": "WAN",
1385+
"protocol": "tcp",
1386+
"src": "any",
1387+
"srcport": "433",
1388+
"dst": "em0ip",
1389+
"dstport": "443",
1390+
"target": "192.168.1.123",
1391+
"local-port": "443",
1392+
"natreflection": "purenat",
1393+
"descr": "Forward pb to lc",
1394+
"nosync": true,
1395+
"top": false
1396+
}
1397+
```
1398+
1399+
1400+
1401+
### 3. Read Outbound NAT Mappings
1402+
1403+
1404+
Read existing outbound NAT mode mappings.<br><br>
1405+
1406+
_Requires at least one of the following privileges:_ [`page-all`, `page-firewall-nat-outbound`]
1407+
1408+
1409+
***Endpoint:***
1410+
1411+
```bash
1412+
Method: GET
1413+
Type: RAW
1414+
URL: https://{{$hostname}}/api/v1/firewall/nat/outbound/mapping
1415+
```
1416+
1417+
1418+
1419+
***Body:***
1420+
1421+
```js
1422+
{
1423+
1424+
}
1425+
```
1426+
1427+
1428+
1429+
### 4. Update Outbound NAT Mappings
1430+
1431+
1432+
Update existing outbound NAT mappings.<br><br>
1433+
1434+
_Requires at least one of the following privileges:_ [`page-all`, `page-firewall-nat-outbound-edit`]
1435+
1436+
1437+
***Endpoint:***
1438+
1439+
```bash
1440+
Method: PUT
1441+
Type: RAW
1442+
URL: https://{{$hostname}}/api/v1/firewall/nat/outbound/mapping
1443+
```
1444+
1445+
1446+
1447+
***Query params:***
1448+
1449+
| Key | Value | Description |
1450+
| --- | ------|-------------|
1451+
| id | integer | Specify the ID of the outbound NAT mapping to update |
1452+
| interface | string | Update the interface the mapping 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) |
1453+
| protocol | string | Update the transfer protocol the mapping will apply to. (optional) |
1454+
| src | string | Update the source address of the firewall rule. This must be an IP, CIDR, alias or any. (optional) |
1455+
| dst | string | Update the destination address of the firewall rule. This may be a single IP, network CIDR, or alias name. To negate the context of the address, you may prepend the address with `!` (optional) |
1456+
| 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) |
1457+
| 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) |
1458+
| target | string | Update the external IP to map this traffic to. This may be an IP address, IP subnet, alias, or empty string to use the Interface address. (optional) |
1459+
| natport | string | Update the TCP and/or UDP port or port range to utilize when NATing (optional) |
1460+
| staticnatport | boolean | Enable or disable static NAT ports. When enabling this field, any existing `natport` value will be lost. Defaults to false. (optional) |
1461+
| descr | string | Update the description for the rule (optional) |
1462+
| poolopts | string | Update the outbound NAT pool option for load balancing. Options are `round-robin`, `round-robin sticky-address`, `random`, `random sticky-address`, `source-hash`, `bitmask` or empty string for default. (optional) |
1463+
| source_hash_key | string | Update the hash to a custom key hash to use when utilizing the `source-hash` NAT pool option. Value must start with `0x` following a 32 digit hex value. If this field is not specified, a random key hash will be generated. This field Is only available when `poolopts` Is set to `source-hash`. (optional) |
1464+
| disabled | boolean | Disable the rule upon creation. Defaults to false. (optional) |
1465+
| nonat | boolean | Enable or disable NAT for traffic that matches this rule. True for no NAT, false to enable NAT. Defaults to false. (optional) |
1466+
| top | boolean | Move this mapping to top of access control list. Defaults to false. (optional) |
1467+
| apply | boolean | Immediately apply this mapping after update. Defaults to false. (optional) |
1468+
1469+
1470+
1471+
***Body:***
1472+
1473+
```js
1474+
{
1475+
"interface": "WAN",
1476+
"protocol": "tcp",
1477+
"src": "any",
1478+
"srcport": "433",
1479+
"dst": "em0ip",
1480+
"dstport": "443",
1481+
"target": "192.168.1.123",
1482+
"local-port": "443",
1483+
"natreflection": "purenat",
1484+
"descr": "Forward pb to lc",
1485+
"nosync": true,
1486+
"top": false
1487+
}
1488+
```
1489+
1490+
1491+
12801492
## FIREWALL/NAT/PORTFOWARD
12811493

12821494

0 commit comments

Comments
 (0)