Settings Handbook

This page lists all settings of the Portmaster.

Badge Meaning
Global Setting is configured globally.
Per App Setting is configurable per app, but also has a configurable global default.
Requires Restart Setting requires a restart of the Portmaster to take effect.
Stackable Per-app setting that does not replace the global default, but adds to it.
Advanced Setting is only visible in the Portmaster if the UI Mode is set to Advanced.
Developer Setting is only visible in the Portmaster if the UI Mode is set to Developer. Be careful, you could break things!
Beta Setting is not deemed to be stable yet.
Experimental Setting is meant for experiments and debugging. Be careful, you could break things!
setting/key Internal identifier of the setting. These are also used as anchors in order to directly link to a setting on this page.
When hovering over a setting name - copy its name and URL formatted in markdown. This requires JavaScript.
API Keys Global Developer core/apiKeys

Define API keys for priviledged access to the API. Every entry is a separate API key with respective permissions. Format is <key>?read=<perm>&write=<perm>. Permissions are anyone, user and admin, and may be omitted.

API Keys need to be provided as a HTTP Basic or Bearer Authentication Header.
Usage of API Keys is only needed if you want to grant 3rd party software access to the Portmaster, or if you want to remotely manage the Portmaster via a Webbrowser. Be reminded that you are fully responsible yourself for the security and all implications of remote access.
On Linux, you can generate a new API Key like this: echo "$(tr -dc A-Za-z0-9 </dev/urandom | head -c 50)?read=user&write=user"

Automatic Updates Global Advanced core/automaticUpdates

Enable automatic checking, downloading and applying of updates. This affects all kinds of updates, including intelligence feeds and broadcast notifications.

Currently, updates are checked for every hour. This frequency was chosen to stay up to date with the ever-changing landscape of malware/tracker/phishing domains managed by the various filter lists.

Default Value: true (boolean)
Development Mode Global Developer core/devMode

In Development Mode, security restrictions are lifted/softened to enable unrestricted access for debugging and testing purposes.

Never enable this in production, as anything will be able to fully control the Portmaster.

Default Value: false (boolean)
Process Detection Global Developer core/enableProcessDetection

This option enables the attribution of network traffic to processes. Without it, app settings are effectively disabled.

Do not disable except for debugging purposes.

Default Value: true (boolean)
UI Mode Global core/expertiseLevel

Control the default amount of settings and information shown. Hidden settings are still in effect. Can be changed temporarily in the top right corner.

Relevant settings on this page are marked with Advanced and Developer accordingly.

Possible Values:
  • Default: Simple ( user ) : Hide complex settings and information.
  • Advanced ( expert ) : Show technical details.
  • Developer ( developer ) : Developer mode. Please be careful!
API Listen Address Global Requires Restart Developer core/listenAddress

Defines the IP address and port on which the internal API listens.

If you intend to access the Portmaster UI remotely, you can set this to 0.0.0.0:817. API Keys can be configured for access authentication. In addition to that, you will need to enable incoming connections in the Portmaster’s own App Settings. Be reminded that you are fully responsible yourself for the security and all implications of remote access.

Default Value: 127.0.0.1:817 (string)
Log Level Global Developer core/log/level

Configure the logging level.

Log output with levels trace, debug and info contain a considerable amount of network information; such as processes, domains and IP addresses. If you are concerned about privacy in your log files, please use levels warning, error or critical.

Possible Values:
  • Critical ( critical ) : The critical level only logs errors that lead to a partial, but imminent failure.
  • Error ( error ) : The error level logs errors that potentially break functionality. Everything logged by the critical level is included here too.
  • Warning ( warning ) : The warning level logs minor errors and worse. Everything logged by the error level is included here too.
  • Default: Info ( info ) : The info level logs the main events that are going on and are interesting to the user. Everything logged by the warning level is included here too.
  • Debug ( debug ) : The debug level logs some additional debugging details. Everything logged by the info level is included here too.
  • Trace ( trace ) : The trace level logs loads of detailed information as well as operation and request traces. Everything logged by the debug level is included here too.
Metrics Instance Name Global Requires Restart Advanced core/metrics/instance

Define the prometheus instance label for exported metrics. Please note that changing the instance name will reset persisted metrics.

See the prometheus label docs for more information. The key used for the label is instance.

Push Metrics Global Requires Restart Advanced core/metrics/push

Push metrics to this URL in the prometheus format.

See the prometheus exposition format docs for more information. The data is POST-ed to the configured URL.

Network Service Global Advanced Experimental core/networkService

Use the Portmaster as a network service, where applicable. You will have to take care of lots of network setup yourself in order to run this properly and securely.

This allows you to use the Portmaster as a network-wide privacy system, similar to a Pi-Hole. This possibility exists mainly for testing and is not officially supported. You are free to tinker around with it though.

Default Value: false (boolean)
Release Channel Global Requires Restart Advanced core/releaseChannel

Use “Stable” for the best experience. The “Beta” channel will have the newest features and fixes, but may also break and cause interruption. Use others only temporarily and when instructed.

Though the Portmaster has not reached the v1.0 release, it already uses the final release channels. This means that “Stable” is the current baseline and “Beta” is more unstable.

Possible Values:
  • Default: Stable ( stable ) : Production releases.
  • Beta ( beta ) : Production releases for testing new features that may break and cause interruption.
  • Special ( special ) : Special releases or version changes for troubleshooting. Only use temporarily and when instructed.
  • Staging ( staging ) : Dangerous development releases for testing random things and experimenting. Only use temporarily and when instructed.
Feature Stability Global Advanced core/releaseLevel

May break things. Decide if you want to experiment with unstable features. “Beta” has been tested roughly by the Safing team while “Experimental” is really raw. When “Beta” or “Experimental” are disabled, their settings use the default again.

Settings on this page are marked with Beta and Experimental accordingly.

Possible Values:
  • Default: Stable ( stable ) : Only show stable features.
  • Beta ( beta ) : Show stable and beta features.
  • Experimental ( experimental ) : Show all features
Desktop Notifications Global core/useSystemNotifications

In addition to showing notifications in the Portmaster App, also send them to the Desktop. This requires the Portmaster Notifier to be running.

You can read more on the Portmaster Notifier for additional information.

Default Value: true (boolean)
Block Unofficial TLDs Global Advanced dns/dontResolveSpecialDomains

Block .onion, .bit. Unofficial domains may pose a security risk. This setting does not affect .onion domains in the Tor Browser.

Look at the dns querying deep dive for more information.

Possible Values:
  • Off ( 0 ) : Setting is always disabled.
  • Default: Trusted / Home Network ( 7 ) : Setting is always enabled.
  • Untrusted / Public Network ( 6 ) : Setting is enabled in untrusted and dangerous networks.
  • Danger / Hacked Network ( 4 ) : Setting is enabled only in dangerous networks.
Internal DNS Server Listen Address Global Requires Restart Developer dns/listenAddress

Defines the IP address and port on which the internal DNS Server listens.

localhost is a special value, which will make the Portmaster listen on both 127.0.0.1:53 and ::1.

The shown default value localhost:53 is used on Linux. The default for Windows is 0.0.0.0:53, since on Windows requests are redirected to the same interface, not the loopback device.

Default Value: localhost:53 (string)
Retry Timeout Global Advanced dns/nameserverRetryRate

Timeout between retries when a DNS server fails.

The Portmaster keeps track of the availablity of configured DNS servers. If requests to a server fail too often, it will be marked as failed and the Portmaster will stop sending requests to it for the duration set by this setting.

Default Value: 300 seconds (integer)
DNS Servers Global Advanced dns/nameservers

DNS Servers to use for resolving DNS requests.

If you prefer to use other DNS servers than the pre-configured ones, you can configure them here. See our guide on DNS Server Configuration for extended details.

Default Value: dot://1.1.1.2:853?verify=cloudflare-dns.com&name=Cloudflare&blockedif=zeroip (string array)
Ignore System/Network Servers Global Advanced dns/noAssignedNameservers

Ignore DNS servers configured in your system or network. This may break domains from your local network.

This does not affect a special set of domains for testing connectivity. Look at the dns querying deep dive for more information.

Possible Values:
  • Trusted / Home Network ( 7 ) : Setting is always enabled.
  • Default: Untrusted / Public Network ( 6 ) : Setting is enabled in untrusted and dangerous networks.
  • Danger / Hacked Network ( 4 ) : Setting is enabled only in dangerous networks.
Enforce Secure DNS Global Advanced dns/noInsecureProtocols

Never resolve using insecure protocols, ie. plain DNS.

This effectively disables mDNS as well as any DNS Server configured in your system or network.
This does not affect a special set of domains for testing connectivity. Look at the dns querying deep dive for more information.

Possible Values:
  • Trusted / Home Network ( 7 ) : Setting is always enabled.
  • Default: Untrusted / Public Network ( 6 ) : Setting is enabled in untrusted and dangerous networks.
  • Danger / Hacked Network ( 4 ) : Setting is enabled only in dangerous networks.
Ignore Multicast DNS Global Advanced dns/noMulticastDNS

Do not resolve using Multicast DNS. This may break certain Plug and Play devices and services.

Queries for mDNS Domains such as .local will be sent to a System/Network DNS Server instead. Look at the dns querying deep dive for more information.

Possible Values:
  • Trusted / Home Network ( 7 ) : Setting is always enabled.
  • Default: Untrusted / Public Network ( 6 ) : Setting is enabled in untrusted and dangerous networks.
  • Danger / Hacked Network ( 4 ) : Setting is enabled only in dangerous networks.
Prompt Timeout Global filter/askTimeout

How long the Portmaster will wait for a reply to a prompt notification. Please note that Desktop Notifications might not respect this or have their own limits.

Regardless of the timeout configured here, the Portmaster will block the connection after a short timeout in order to keep a clean state and report the connection to the UI. Applications waiting for a prompt may report that they were not able to connect. In this case just ask the application to reconnect after handling the prompt.

Default Value: 60 seconds (integer)
Prompt Desktop Notifications Global filter/askWithSystemNotifications

In addition to showing prompt notifications in the Portmaster App, also send them to the Desktop. This requires the Portmaster Notifier to be running. Requires Desktop Notifications to be enabled.

Requires enabled Desktop Notifications.

Default Value: true (boolean)
Block Incoming Connections Per App filter/blockInbound

Connections initiated towards your device from the LAN or Internet. This will usually only be the case if you are running a network service or are using peer to peer software. Is stronger than Rules (see below).

In order to accept incoming connections, they must also be allowed by the Incoming Rules.

Possible Values:
  • Trusted / Home Network ( 7 ) : Setting is always enabled.
  • Default: Untrusted / Public Network ( 6 ) : Setting is enabled in untrusted and dangerous networks.
  • Danger / Hacked Network ( 4 ) : Setting is enabled only in dangerous networks.
Block Internet Access Per App filter/blockInternet

Block connections from and to the Internet. Is stronger than Rules (see below).

You can use this setting to completely lock out an application from the Internet. Alternatively, you can block access globally while allowing specific apps as an exception in their respective per-app settings.

Possible Values:
  • Default: Off ( 0 ) : Setting is always disabled.
  • Trusted / Home Network ( 7 ) : Setting is always enabled.
  • Untrusted / Public Network ( 6 ) : Setting is enabled in untrusted and dangerous networks.
  • Danger / Hacked Network ( 4 ) : Setting is enabled only in dangerous networks.
Block LAN Per App filter/blockLAN

Block all connections from and to the Local Area Network. Is stronger than Rules (see below).

You can use this setting to completely lock out an application from your local network. Alternatively, you can block access globally while allowing specific apps as an exception in their respective per-app settings.

Possible Values:
  • Off ( 0 ) : Setting is always disabled.
  • Trusted / Home Network ( 7 ) : Setting is always enabled.
  • Default: Untrusted / Public Network ( 6 ) : Setting is enabled in untrusted and dangerous networks.
  • Danger / Hacked Network ( 4 ) : Setting is enabled only in dangerous networks.
Block Device-Local Connections Per App Advanced filter/blockLocal

Block all internal connections on your own device, ie. localhost. Is stronger than Rules (see below).

Internal connections on your device are usually not a threat. There are however cases where it makes sense to restrict localhost communication, such as for Browsers, if not needed.

Possible Values:
  • Default: Off ( 0 ) : Setting is always disabled.
  • Trusted / Home Network ( 7 ) : Setting is always enabled.
  • Untrusted / Public Network ( 6 ) : Setting is enabled in untrusted and dangerous networks.
  • Danger / Hacked Network ( 4 ) : Setting is enabled only in dangerous networks.
Block P2P/Direct Connections Per App filter/blockP2P

These are connections that are established directly to an IP address or peer on the Internet without resolving a domain name via DNS first. Is stronger than Rules (see below).

This setting is set to “Danger” by default because there is lots of software that directly communicates with IPs.

If P2P connections are not needed widely, we recommend setting this to “Trusted” to greatly increase security. For exceptions in that case you can easily allow P2P connections for specific apps in their respective per-app setting.

Possible Values:
  • Trusted / Home Network ( 7 ) : Setting is always enabled.
  • Untrusted / Public Network ( 6 ) : Setting is enabled in untrusted and dangerous networks.
  • Default: Danger / Hacked Network ( 4 ) : Setting is enabled only in dangerous networks.
Default Action Per App filter/defaultAction

The default action when nothing else allows or blocks an outgoing connection. Incoming connections are always blocked by default.

If set to “Prompt”, the Portmaster will prompt you in the User Interface as well as via Desktop Notifications (if enabled) to make a decision about a connection. You can also allow or block prompts in bulk in the UI.

Possible Values:
  • Default: Allow ( permit ) : Allow all connections
  • Block ( block ) : Block all connections
  • Prompt ( ask ) : Prompt for decisions
Disable Auto Allow Per App Beta filter/disableAutoPermit

Auto Allow searches for a relation between an app and the destination of a connection - if there is a correlation, the connection will be allowed.

This setting is meant to reduce noise when using prompting. Currently, this feature is still rather primitive - comparing paths and names - but will become smarter in the future.
Auto allowing is disabled by default because it is a convenience and not a privacy feature.

Possible Values:
  • Default: Trusted / Home Network ( 7 ) : Setting is always enabled.
  • Untrusted / Public Network ( 6 ) : Setting is enabled in untrusted and dangerous networks.
  • Danger / Hacked Network ( 4 ) : Setting is enabled only in dangerous networks.
Enable Domain Heuristics Per App Advanced filter/domainHeuristics

Checks for suspicious domain names and blocks them. This option currently targets domain names generated by malware and DNS data exfiltration channels.

If this setting blocks benign connections, you can turn it off for single applications, but we highly recommend you leave it on globally. Domains generated by malware are an easy way to evade blocklists and slip through security systems.

Possible Values:
  • Off ( 0 ) : Setting is always disabled.
  • Default: Trusted / Home Network ( 7 ) : Setting is always enabled.
  • Untrusted / Public Network ( 6 ) : Setting is enabled in untrusted and dangerous networks.
  • Danger / Hacked Network ( 4 ) : Setting is enabled only in dangerous networks.
Privacy Filter Global Beta filter/enable

Enable the DNS and Network Filter.

Turning this off will completely disable the privacy filter and allow any connection. You should never use this in production. Instead, consider changing the default action to “Allow”.

Default Value: true (boolean)
Outgoing Rules Per App Stackable filter/endpoints

Rules that apply to outgoing network connections. Cannot overrule Network Scopes and Connection Types (see above).

Formatting Help:

Rules are checked from top to bottom, stopping after the first match. They can match:

  • By address: 192.168.0.1
  • By network: 192.168.0.1/24
  • By domain:
    • Matching a distinct domain: example.com
    • Matching a domain with subdomains: .example.com
    • Matching with a wildcard prefix: *xample.com
    • Matching with a wildcard suffix: example.*
    • Matching domains containing text: *example*
  • By country (based on IP): US
  • By filter list - use the filterlist ID prefixed with L:: L:MAL
  • Match anything: *

Additionally, you may supply a protocol and port just behind that using numbers (6/80) or names (TCP/HTTP).
In this case the rule is only matched if the protocol and port also match.
Example: 192.168.0.1 TCP/HTTP

Block Domain Aliases Per App Advanced filter/includeCNAMEs

Block a domain if a resolved CNAME (alias) is blocked by a rule or filter list.

This is used to block the new “unblockable” trackers that use a first-party subdomain CNAME’d (alias’d) to the tracking company.

Possible Values:
  • Default: Trusted / Home Network ( 7 ) : Setting is always enabled.
  • Untrusted / Public Network ( 6 ) : Setting is enabled in untrusted and dangerous networks.
  • Danger / Hacked Network ( 4 ) : Setting is enabled only in dangerous networks.
Block Subdomains of Filter List Entries Per App filter/includeSubdomains

Additionally block all subdomains of entries in selected filter lists.

This makes it easier to block trackers that change their subdomain often in an attempt to avoid being caught by filter lists.

Possible Values:
  • Default: Trusted / Home Network ( 7 ) : Setting is always enabled.
  • Untrusted / Public Network ( 6 ) : Setting is enabled in untrusted and dangerous networks.
  • Danger / Hacked Network ( 4 ) : Setting is enabled only in dangerous networks.
Filter Lists Per App filter/lists

Block connections that match enabled filter lists.

In the Portmaster UI you can easily select lists you want to activate. The filter lists are gathered and merged by us in order to be able to send hourly incremental updates. You can view all lists the Portmaster subscribes to here.

Permanent Verdicts Global Developer Experimental filter/permanentVerdicts

The Portmaster’s system integration intercepts every single packet. Usually the first packet is enough for the Portmaster to set the verdict for a connection - ie. to allow or deny it. Making these verdicts permanent means that the Portmaster will tell the system integration that is does not want to see any more packets of that single connection. This brings a major performance increase.

Do not disable except for debugging purposes.

Default Value: true (boolean)
Block Bypassing Per App Beta filter/preventBypassing

Prevent apps from bypassing the privacy filter.
Current Features:

  • Disable Firefox’ internal DNS-over-HTTPs resolver
  • Block direct access to public DNS resolvers

Please note that if you are using the system resolver, bypass attempts might be additionally blocked there too.

This is primarily to prevent software that plays nice from circumventing the Portmaster. While we will do it where it makes sense, this is not geared towards malware that is specifically made for circumenventing protection.

Possible Values:
  • Default: Trusted / Home Network ( 7 ) : Setting is always enabled.
  • Untrusted / Public Network ( 6 ) : Setting is enabled in untrusted and dangerous networks.
  • Danger / Hacked Network ( 4 ) : Setting is enabled only in dangerous networks.
Reject Blocked IPs Per App Developer filter/removeBlockedDNS

Reject blocked IP addresses directly from the DNS response instead of handing them over to the app and blocking a resulting connection. This settings does not affect privacy and only takes effect when the system resolver is not in use.

Should a DNS response contain multiple IP addresses, and some of them would not be allowed to be connected to, the Portmaster will remove these answers in order to make it more likely for a connection to succeed within the permitted parameters.

Possible Values:
  • Default: Trusted / Home Network ( 7 ) : Setting is always enabled.
  • Untrusted / Public Network ( 6 ) : Setting is enabled in untrusted and dangerous networks.
  • Danger / Hacked Network ( 4 ) : Setting is enabled only in dangerous networks.
Enforce Global/Private Split-View Per App Developer filter/removeOutOfScopeDNS

Reject private IP addresses (RFC1918 et al.) from public DNS responses. If the system resolver is in use, the resulting connection will be blocked instead of the DNS request.

DNS Rebinding attacks allow an attacker to circumvent security policies. This feature blocks DNS Rebinding attacks on local systems.

Possible Values:
  • Default: Trusted / Home Network ( 7 ) : Setting is always enabled.
  • Untrusted / Public Network ( 6 ) : Setting is enabled in untrusted and dangerous networks.
  • Danger / Hacked Network ( 4 ) : Setting is enabled only in dangerous networks.
Incoming Rules Per App Stackable Advanced filter/serviceEndpoints

Rules that apply to incoming network connections. Cannot overrule Network Scopes and Connection Types (see above). Also note that the default action for incoming connections is to always block.

If you need to accept incoming connections, try to narrow down from where you need to accept connections. A great way to start is to only accept connections from an organization via its AS number (find it here) or to only accept connections from specific countries. While potentially dangerous, you can allow any incoming connection by adding + * to the Incoming Rules.

Default Value: + Localhost (string array)
Formatting Help:

Rules are checked from top to bottom, stopping after the first match. They can match:

  • By address: 192.168.0.1
  • By network: 192.168.0.1/24
  • By domain:
    • Matching a distinct domain: example.com
    • Matching a domain with subdomains: .example.com
    • Matching with a wildcard prefix: *xample.com
    • Matching with a wildcard suffix: example.*
    • Matching domains containing text: *example*
  • By country (based on IP): US
  • By filter list - use the filterlist ID prefixed with L:: L:MAL
  • Match anything: *

Additionally, you may supply a protocol and port just behind that using numbers (6/80) or names (TCP/HTTP).
In this case the rule is only matched if the protocol and port also match.
Example: 192.168.0.1 TCP/HTTP

Enable SPN Global spn/enable

Enable the Safing Privacy Network.

Extended documentation will be written when exact behavior is finalized

Default Value: false (boolean)
Special Access Code Global spn/specialAccessCode

Special Access Codes grant access to the SPN for testing or evaluation purposes.

Extended documentation will be written when exact behavior is finalized

Default Value: none (string)
Use SPN Per App spn/useSPN

Route connections through the Safing Privacy Network. If it is disabled or unavailable for any reason, connections will be blocked.

Extended documentation will be written when exact behavior is finalized

Default Value: true (boolean)