Repository: saltstack/salt
Pull request: Add iptables doc example
### What does this PR do?

Adds a mention of `name` vs `name_` to iptables state docs.

### What issues does this PR fix or reference?

Fixes: #60880 

### Merge requirements satisfied?
**[NOTICE] Bug fixes or features added to Salt require tests.**
<!-- Please review the [test documentation](https://docs.saltproject.io/en/master/topics/tutorials/writing_tests.html) for details on how to implement tests into Salt's test suite. -->
- [x] Docs
- [x] Changelog - https://docs.saltproject.io/en/master/topics/development/changelog.html
- ~[ ] Tests written/updated~ docs change

### Commits signed with GPG?
Yes

Problem statement:
[BUG] `iptables.append` state does not pass `name` argument to iptables command
**Description**
The `iptables.append` state does not pass `-name: SSH` to iptables as `--name SSH`, instead of that `--name DEFAULT` is passed. Looks like the `name` argument is reserved by the state itself. Any other argument like `- foo: bar` is passed as `--foo bar`.

**Setup**
`test.sls`:
```
test iptables state:
  iptables.append:
    - table: filter
    - chain: INPUT
    - name: SSH
    - match:
      - comment
      - state
      - recent
      - tcp
    - comment: "test iptables state"
    - connstate: NEW
    - proto: tcp
    - dport: 22
    - save: True
```

Set-up details:

- [x] VM (Virtualbox, Vagrant, CentOS7)


  
**Steps to Reproduce the behavior**
Execute state above. `sudo salt-call state.apply test`

**Expected behavior**
Define iptables `--name` argument in the `iptables.append` state and pass it to the iptables rule.

**Versions Report**
<details><summary>salt --versions-report</summary>
(Provided by running salt --versions-report. Please also mention any differences in master/minion versions.) 

```
[vagrant@salt ~]$ sudo salt-call --version
salt-call 3003.2
[vagrant@salt ~]$ sudo salt --version
salt 3003.2
```
</details>

Hints from issue discussion:
Hi there! Welcome to the Salt Community! Thank you for making your first contribution. We have a lengthy process for issues and PRs. Someone from the Core Team will follow up as soon as possible. In the meantime, here’s some information that may help as you continue your Salt journey.
Please be sure to review our [Code of Conduct](https://github.com/saltstack/salt/blob/master/CODE_OF_CONDUCT.md). Also, check out some of our community resources including:

  - [Community Wiki](https://github.com/saltstack/community/wiki)
  - [Salt’s Contributor Guide](https://docs.saltproject.io/en/master/topics/development/contributing.html)
  - [Join our Community Slack](https://join.slack.com/t/saltstackcommunity/shared_invite/zt-3av8jjyf-oBQ2M0vhXOhJpNpRkPWBvg)
  - [IRC on LiberaChat](https://web.libera.chat/#salt)
  - [Salt Project YouTube channel](https://www.youtube.com/channel/UCpveTIucFx9ljGelW63-BWg)
  - [Salt Project Twitch channel](https://www.twitch.tv/saltprojectoss)

There are lots of ways to get involved in our community. Every month, there are around a dozen opportunities to meet with other contributors and the Salt Core team and collaborate in real time. The best way to keep track is by subscribing to the Salt Community Events Calendar.
If you have additional questions, email us at saltproject@vmware.com. We’re glad you’ve joined our community and look forward to doing awesome things with you!

@jbartak Looks like it should be `name_` (https://github.com/saltstack/salt/blob/master/salt/modules/iptables.py#L320 ), although it's not documented anywhere. But it seems to work fine:

```
test iptables state:
  iptables.append:
    - table: filter
    - chain: INPUT
    - name_: SSH
    - match:
      - comment
      - state
      - recent
      - tcp
    - comment: "test iptables state"
    - connstate: NEW
    - proto: tcp
    - dport: 22
    - save: True

```

```
local:
----------
          ID: test iptables state
    Function: iptables.append
      Result: False
     Comment: Failed to set iptables rule for test iptables state.
              Attempted rule was /usr/sbin/iptables --wait -t filter -A INPUT  -p tcp -m comment -m state -m recent --name SSH -m tcp --state NEW --dport 22 --comment "test iptables state" for ipv4
     Started: 10:49:37.566532
    Duration: 49.47 ms
     Changes:   
```
I had to miss this part of the code, anyway thank you this is working!
But maybe this can be added also to the docs?
Yeah, should be definitelly added into docs. If nobody from Salt team manages to do it before me, I will create PR for this (if you don't want to).

Commit message: Add iptables doc example

Fixes #60880

Patch to review:
diff --git a/changelog/60880.fixed b/changelog/60880.fixed
new file mode 100644
index 000000000000..c855e8db5307
--- /dev/null
+++ b/changelog/60880.fixed
@@ -0,0 +1 @@
+Added info to docs for iptables `- name_:` vs `- name:`.
diff --git a/salt/states/iptables.py b/salt/states/iptables.py
index 2ab20ebebb82..73b9e56992f5 100644
--- a/salt/states/iptables.py
+++ b/salt/states/iptables.py
@@ -189,6 +189,7 @@
     appearance of ``-m policy``, it is interpreted as the ``--proto`` option of
     the policy extension (see the iptables-extensions(8) man page).
 
+
 Example rules for IPSec policy:
 
 .. code-block:: yaml
@@ -231,6 +232,11 @@
           - iptables: accept_esp_out
         - chain: FORWARD
 
+.. note::
+
+    ``name`` is reserved for the Salt state name. To pass ``--name EXAMPLE`` to
+    iptables, provide it with ``- name_: EXAMPLE``.
+
 .. note::
 
     Various functions of the ``iptables`` module use the ``--check`` option. If


Code review comments:
diff_hunk: @@ -0,0 +1 @@
+Added info to docs for iptables `- name_:` vs `- name:`.
path: changelog/60880.fixed
text: @user1:
changelog files are not required for doc changes.

@author:
:fire: gone now :+1: