API limitation: Cannot append individual IPs to existing firewall alias without hitting 128 IP limit

[rpaal10]

The API lacks endpoints to append individual IPs to existing firewall aliases, forcing users to replace the entire IP array. This becomes problematic when the total IPs exceed the 128 limit, causing 400 errors and preventing incremental updates.

To Reproduce
Steps to reproduce the behavior:

1. Create a firewall alias with 125+ existing IPs
2. Attempt to add 5+ new IPs using PATCH /api/v2/firewall/alias
3. Send payload with all existing IPs + new IPs (total > 128)
4. See error response with code 400

Expected behavior
Should be able to add individual IPs to an existing alias without needing to send the entire IP array, or have endpoints specifically for adding/removing individual IPs from aliases.

Screenshots or Response
API Response when trying to update alias with 133 IPs (130 existing + 3 new):

{
  "code": 400,
  "status": "bad request", 
  "response_id": "LENGTH_VALIDATOR_MAXIMUM_CONSTRAINT",
  "message": "Field `address` exceeds the maximum array length of 128.",
  "data": []
}



Additional context
Use Case: Automated synchronization of blocked IPs from security devices to pfSense firewall aliases.

Impact: This limitation prevents automated security systems from maintaining dynamic IP blocklists when approaching the 128 IP limit, requiring manual intervention or workarounds like creating multiple aliases.

Questions:

Is the 128 IP limit per alias configurable?
Are there plans to implement incremental IP management endpoints?
Would PRs be accepted for these features?

[jaredhendrickson13]

You can change the behavior of updates to array values to be incremental using the append control parameter. This parameter is available to all endpoints that support PATCH requests and have array fields. The remove control parameter is its counterpart that allows you to remove specific values from an array.

The 128 limit for alias entries doesn't seem warranted through, I'm assuming it was not intended to be an item limit and rather a character limit per item in the array. A PR is certainly welcome for that.

[rpaal10]

You can change the behavior of updates to array values to be incremental using the append control parameter. This parameter is available to all endpoints that support PATCH requests and have array fields. The remove control parameter is its counterpart that allows you to remove specific values from an array.

The 128 limit for alias entries doesn't seem warranted through, I'm assuming it was not intended to be an item limit and rather a character limit per item in the array. A PR is certainly welcome for that.

I'm using the append=true parameter as documented, but receiving a LENGTH_VALIDATOR_MAXIMUM_CONSTRAINT error when the target alias already has more than 128 IPs.

Current situation:

Alias currently has: 131 IPs
Attempting to append: 2 new IPs
Using: PATCH /api/v2/firewall/alias?append=true&apply=true
Request payload (only new IPs):

json
Copy
{
"id": 14,
"address": ["146.70.111.108", "45.79.190.74"]
}
Response received:

json
Copy
{
"code": 400,
"status": "bad request",
"response_id": "LENGTH_VALIDATOR_MAXIMUM_CONSTRAINT",
"message": "Field detail exceeds the maximum array length of 128.",
"data": []
}
Expected behavior:
According to the documentation, append=true should add the 2 new IPs to the existing array without replacing it. The validation should occur after the append operation, but it seems to be validating before allowing the append.

Question:
Is this the intended behavior, or should append=true work regardless of the current array size? If aliases are hard-limited to 128 IPs, the documentation should mention this limitation with the append parameter.

[jaredhendrickson13]

No the validation you are hitting is a field level validation; it's not request specific. In other words, it doesn't limit the number of array items you can add in a single request, it limits the total number of items an array field can have in the config. append would not be a valid solution for this as it simply appends the values you specify to the values already stored and validates the entire field's value. The limit just needs to be increased on those fields. I can get a patch out this week to increase the limits.

As a side node, in your request you must ensure you do not mix content-types. You'd need to move the apply and append parameters into your request body if you're using application/json, or move the values in your request body to URL parameters if using application/x-www-form-urlencoded. The REST API will only decode request data using your specified content-type.

[rpaal10]

You mentioned you can get a patch out this week to increase the limits - would you be able to do that? I would really appreciate it.

So what would the limit be then?

[jaredhendrickson13]

Yes, I'll try to have a patch out tonight. The real maximum limit for alias entries is defined by pf and ultimately varies between systems; so enforcing a static maximum for this field isn't really practical. In this case, the issue for firewall aliases was the maximum limit was undefined for those fields. The framework is designed to default array fields to a very conservative limit of 128 as a safety measure. The patch will define a limit of 0 for the address and detail fields, essentially excluding them from the maximum length validation altogether.

[rpaal10]

i cant see update for 2.5.4
its normal?

[jaredhendrickson13]

It hasn't been released quite yet. There are still a couple tests that need to be cleaned up first. Should be out later today assuming no additional issues pop up.

[rpaal10]

It hasn't been released quite yet. There are still a couple tests that need to be cleaned up first. Should be out later today assuming no additional issues pop up.

it works perfect now!
thank yoy so much!!

A separate question, compatibility of the API with the recent update of Pfsense CE 2.8.1?