API 2.1.0 and "Reset the firewall state table"

[HovKlan-DH]

The main thing I have been awaiting for the new 2.1.0 release is the plural DELETE possibility with /api/v2/firewall/states. I did assume that would equal the UI, Diagnostics > States > Reset States > Reset the firewall state table, but I cannot get this working.

If I read the documentation for the API then I do have a couple of questions to its usage:

• Applies immediately: No

  • What does this mean? Does it mean that after I have deleted all states, then I need to reset/apply the table or alike? Maybe via /api/v2/firewall/apply or .. ?

• Query:

  • I do have the two paramters set and I do get a HTTP code 200:
    • query is empty
      • I assume this may not be the same as "all" - can someone help with some examples? E.g. how to delete all rules for a specific interface or alias, if this is possible?
    • limit is set to 0

Sorry, but I just need a little hint 😁

[jaredhendrickson13]

For the Applies immediately attribute, see this section in the documentation. It is really only applicable to endpoints that interact with the pfSense configuration like firewall rules, static routes, etc. For firewall states you do not need to apply anything because nothing gets written to the configuration. Admittedly it is a little misleading for some endpoints. I've been working on a better way to programmatically determine the relevance of that attribute for endpoints when the documentation is generated.

To reset all firewall states, you can make a DELETE query to /api/v2/firewall/states with all set to true to reset the table. For query deletions, it is required to have at least one parameter to help prevent accidental deletions. You can reference this section in the documentation for more info about using queries for DELETE requests.

If the desired effect was to kill all states with a specific interface, you could run this call for example:

curl -k -u admin:pfsense -H 'content-type: application/x-www-form-urlencoded' -X DELETE 'https://localhost/api/v2/firewall/states?interface=em0'

Or if you wanted to delete all firewall rules referencing a specific alias in the destination field:

curl -k -u admin:pfsense -H 'content-type: application/x-www-form-urlencoded' -X DELETE 'https://localhost/api/v2/firewall/rules?destination=MYALIASNAME'

DELETE queries also support query filters so you can construct some pretty powerful queries to target the objects you need.

[HovKlan-DH]

Great - thanks for the explanation and I now have it working 😁

However, you mention that I can use interface as a parameter - to set it to true, but I cannot see this from the documentation? I can see only 3 parameters documented:

• limit
• offset
• query

Documentation:

So what kind of other parameters could I also use here?

[jaredhendrickson13]

The specific parameters for queries for endpoints are not enumerated in the documentation because any field in the object's schema can be used as a query parameter with the exception of:

1. Field's with complex data structures like nested objects.
2. Write only fields that do not appear in the object's response schema.

Another reason these are not enumerated is because query filters make the parameter definition somewhat arbitrary (e.g. interface__startswith=em).

There are also common control parameters that control the behavior of the API call. In some cases these are relevant to queries such as the all parameter for DELETE queries, or the reverse parameter for GET queries.

In the Swagger docs, you can add any of your query parameters to the query object and they will be appended to the query string.

[HovKlan-DH]

I will try it out, but for sure I see this as answered - thank you very much for your great service and swift response! 👌