Skip to content

docs: migrate getting-started network setup to nft/iptables-nft - #6166

Open
AdaAibaby wants to merge 1 commit into
firecracker-microvm:mainfrom
AdaAibaby:docs/getting-started-nftables
Open

AdaAibaby wants to merge 1 commit into
firecracker-microvm:mainfrom
AdaAibaby:docs/getting-started-nftables

Conversation

@AdaAibaby

@AdaAibaby AdaAibaby commented Aug 31, 2026

Copy link
Copy Markdown

Summary

Replace bare iptables commands in docs/getting-started.md with dual
nft (recommended) and iptables-nft alternatives, consistent with the
pattern already established in docs/network-setup.md.

  • Split the monolithic bash block at the network-setup step to present
    both nft and iptables-nft options as separate, labelled sections
  • Replace sudo sh -c "echo 1 > /proc/sys/net/ipv4/ip_forward" with
    echo 1 | sudo tee /proc/sys/net/ipv4/ip_forward (safer, consistent
    with network-setup.md)
  • Remove the idempotent delete-before-add iptables pattern; nft
    table/chain creation handles fresh setup cleanly

Fixes #4874 (Part A: docs/getting-started.md)

Hi @Manciukic @JackThomson2 @kanpov , this PR addresses part of #4874 (getting-started docs migration to nft/iptables-nft). Would you mind taking a look when you have a chance? Thanks!

Replace bare `iptables` commands in the network setup section of
getting-started.md with dual `nft` (recommended) and `iptables-nft`
alternatives, consistent with the pattern in docs/network-setup.md.

Also replace `sudo sh -c "echo 1 > /proc/..."` with the safer
`echo 1 | sudo tee /proc/...` form.

Closes firecracker-microvm#4874 (Part A)
@Manciukic

Copy link
Copy Markdown
Contributor

Hey @AdaAibaby, thanks for the contribution! What is the goal with this change? Did you find any issues with the current getting started guide? I think we should keep it as simple as possible for new people to use the guide and defer to the specific documentation for different set ups.

@AdaAibaby

Copy link
Copy Markdown
Author

Hey @AdaAibaby, thanks for the contribution! What is the goal with this change? Did you find any issues with the current getting started guide? I think we should keep it as simple as possible for new people to use the guide and defer to the specific documentation for different set ups.

Hi @Manciukic, thanks for the quick look, and I fully agree the getting-started guide should stay as simple as possible.

The motivation isn't to add options for their own sake — it's that the current guide uses bare iptables, which is exactly what #4874 is tracking for removal. On recent distros (current Ubuntu/Debian/Fedora) the legacy iptables backend is
often absent or aliased to nftables, so a new user following the guide today can hit failures or silent no-ops on the iptables steps. So this is less "new feature" and more "keep the happy path working for newcomers."

That said, your simplicity point is well taken. I'm happy to trim this down so getting-started shows only the recommended nft path (a single, clean block), and we defer the iptables-nft alternative to network-setup.md where the detailed
setups already live. That keeps the guide short while making sure the commands actually run on a fresh modern host.

Want me to push that simpler single-path version?

@zulinx86 zulinx86 added the Status: Awaiting assignee Indicates that an issue or pull request is awaiting action from its assignee. label Sep 9, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Status: Awaiting assignee Indicates that an issue or pull request is awaiting action from its assignee.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature Request] Migrate networking documentation to nftables

4 participants