WitteShadovv: Add first draft of Portmaster package and module entry

2026-08-18T13:03:19Z

Add first draft of Portmaster package and module entry

New page

'''Portmaster''' is a free and open source application firewall developed by [https://safing.io Safing].<ref>https://safing.io/</ref> It monitors and controls network connections per application, so rules follow the program rather than the port. A package and a service module are available on the unstable channel and will ship with NixOS 26.11.

== Installation ==

==== System setup ====

Add the following to your system configuration:

<syntaxhighlight lang="nix">
services.portmaster.enable = true;
</syntaxhighlight>

This starts the <code>portmaster.service</code> daemon, installs the desktop client into the system environment, and loads the <code>nfnetlink_queue</code> kernel module. The desktop client starts in the background with graphical sessions and authenticates against the package's read-only binary directory, so it works without any further setup. When the service stops, leftover iptables rules are cleaned up automatically.

For all module options, refer to {{nixos:option|services.portmaster}}.

== Configuration ==

==== Basic ====

Global settings can be managed declaratively through {{nixos:option|services.portmaster.settings}}:

<syntaxhighlight lang="nix">
services.portmaster = {
enable = true;
settings = {
"core/log/level" = "warning";
"dns/nameservers" = [
"dot://dns.quad9.net?ip=9.9.9.9&name=Quad9&blockedif=empty"
];
};
};
</syntaxhighlight>

Settings are merged from three sources, where later sources override earlier ones: <code>settings</code>, then <code>settingsFile</code>, then <code>secretsFile</code>. Use <code>secretsFile</code> for values that must not be copied to the world-readable Nix store.

{{note|When any of these options or declarative profiles are used, the module owns Portmaster's runtime <code>config.json</code>. Global settings changed only through the UI are replaced at the next service start, so keep all global settings in your NixOS configuration.}}

Portmaster stores its mutable state, configuration, and logs under {{nixos:option|services.portmaster.stateDir}}, which defaults to <code>/var/lib/portmaster</code>. Changing it does not migrate existing state.

Set <code>services.portmaster.settings.devmode</code> to <code>true</code> only when you need unrestricted browser or debugging access to the local API at <code>http://127.0.0.1:817</code>. The packaged desktop client does not need it.

==== Advanced ====

Application profiles can be declared in your NixOS configuration. The module derives fingerprints from packages using regular expressions that ignore the Nix store hash and the package version, and that also match Nix generated <code>.program-wrapped</code> executables. Profiles therefore keep working across rebuilds and package updates. They are imported through Portmaster's local API, and rebuilds update existing profiles in place instead of creating duplicates.

<syntaxhighlight lang="nix">
services.portmaster = {
enable = true;
profilePrefix = "[NixOS] ";

profiles = {
Firefox = {
packages = [ pkgs.firefox ];
settings.filter.defaultAction = "permit";
};

Vesktop = {
fingerprints = [
{
type = "env";
key = "CHROME_DESKTOP";
operation = "equals";
value = "vesktop.desktop";
}
];
};
};
};
</syntaxhighlight>

Some packages start their real executable outside <code>bin</code>. Describe those layouts explicitly:

<syntaxhighlight lang="nix">
services.portmaster.profiles.Brave.packages = [
{
package = pkgs.brave;
directory = "opt/brave.com/brave";
}
];
</syntaxhighlight>

A package entry accepts <code>package</code>, <code>type</code>, <code>storeNameRegex</code>, <code>directory</code>, <code>name</code>, <code>wrapped</code>, <code>strictHead</code>, and <code>strictLast</code> fields. Manual fingerprints support the types <code>path</code>, <code>cmdline</code>, <code>env</code>, and <code>tag</code> with the operations <code>equals</code>, <code>prefix</code>, and <code>regex</code>. The <code>packages</code> and <code>fingerprints</code> lists are merged, and at least one of them must be non-empty.

{{warning|Package name matching is a convenience, not a security boundary against local Nix users. Anyone who can add arbitrary store paths can create a derivation with a matching name. Use manually chosen fingerprints when that threat is relevant to your setup.}}

Fingerprints are alternatives: a process matches when any fingerprint matches, so broad regular expressions can match unintended applications. Removing a profile declaration does not remove a profile that Portmaster has already imported. Changing fingerprints changes the derived profile identity, which can leave the previous imported profile behind.

== Tips and tricks ==

* Use <code>profilePrefix</code> to make module managed profiles easy to recognize in the Portmaster UI.
* The binary self-updater is disabled in the NixOS package because Nix owns the installed files. Intelligence and filter list data updates keep working and are stored under <code>stateDir</code>.

== Troubleshooting ==

==== Port 53 conflicts ====

Portmaster runs its own local nameserver on port 53 of localhost.<ref name="osint">https://docs.safing.io/portmaster/architecture/os-integration</ref> The module does not disable [[systemd-resolved]] or other DNS services for you. If another service already listens on port 53, resolve the conflict yourself, for example by disabling systemd-resolved or its stub listener.

DNS queries that arrive through systemd-resolved cannot be attributed to the originating process, which weakens per-application filtering.<ref name="osint" /> Setups using systemd-networkd have also seen VPN provided split DNS zones fail to resolve.<ref>https://github.com/safing/portmaster/issues/655</ref>

==== firewalld ====

The Portmaster service declares a systemd conflict with <code>firewalld.service</code>. The two cannot run at the same time.

==== First start ====

Portmaster downloads its intelligence and filter list data on first start, so the first run needs a working network connection. If the download fails, filtering can be impaired until the data is fetched. Restarting the service retries the download.

==== Declarative profiles fail to import ====

The import runs in a separate unit, <code>portmaster-managed-profiles.service</code>, which waits up to 60 seconds for the Portmaster API to become ready. Check its status and the reason for a rejected profile with:

<syntaxhighlight lang="console">
# journalctl -u portmaster-managed-profiles
</syntaxhighlight>

==== Logs ====

The daemon logs to the journal and to <code>logs</code> under <code>stateDir</code>:

<syntaxhighlight lang="console">
# journalctl -u portmaster
</syntaxhighlight>

== See also ==

* [https://safing.io/portmaster/ Portmaster upstream] – official website
* [https://docs.safing.io/ Portmaster documentation] – upstream manual, including OS integration details
* [https://github.com/safing/portmaster safing/portmaster] – source repository
* [https://nixos.org/manual/nixos/unstable/#module-services-portmaster NixOS manual chapter] – module documentation with more configuration examples
* [[OpenSnitch]] – another application firewall available on NixOS

== References ==

[[Category:Applications]]
[[Category:Security]]
[[Category:Networking]]

Portmaster - Revision history

WitteShadovv: Add first draft of Portmaster package and module entry