Settings Handbook

API Keys Global Developer core/apiKeys

Define API keys for privileged 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 Intelligence Data Updates Global Advanced core/automaticIntelUpdates

Automatically check for and download intelligence data updates. This includes filter lists, geo-ip data, and more. Does not include software updates.

Automatic Software Updates Global Advanced core/automaticUpdates

Automatically check for and download software updates. This does not include intelligence data updates.

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.

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.

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.

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.

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.

Time and Date Format Global core/locale

Configures the time and date format for the user interface. Selection is an example and correct formatting in the UI is a continual work in progress.

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.

Metrics Comment Label Global Requires Restart Advanced core/metrics/comment

Define a metrics comment label, which is added to the info metric.

Metrics Instance Name Global Requires Restart Advanced core/metrics/instance

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

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

Push Prometheus 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.

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.

Feature Stability Global Developer 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.

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.

Block Unofficial TLDs Global Advanced dns/dontResolveSpecialDomains

Block .onion, .i2p, .loki, .bit, .eth, .888, .bitcoin, .coin, .crypto, .dao, .nft, .wallet, .x, .zil, .bazar, .coin, .emc, .lib, .bbs, .chan, .dyn, .free, .fur, .geek, .glue, .gopher, .indy, .libre, .neo, .null, .o, .oss, .oz, .parody, .pirate, .ku, .te, .ti, .uu. 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.

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.

Retry Failing DNS Servers Global Developer dns/nameserverRetryRate

Duration in seconds how often failing DNS server should be retried. This is done continuously in the background.

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.

DNS Servers Global 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.

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.

Use Secure Protocols Only Global Advanced dns/noInsecureProtocols

Never resolve using insecure protocols, ie. plain DNS. This may break certain local DNS services, which always use 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.

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.

Always Use DNS Cache Global dns/useStaleCache

Always use the DNS cache, even if entries have expired. Expired entries are refreshed afterwards in the background. This can improve DNS resolving performance a lot, but may lead to occasional connection errors due to outdated DNS records.

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.

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.

Force 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.

Force Block Internet Access Per App filter/blockInternet

Force 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.

Force Block LAN Per App filter/blockLAN

Force 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.

Force Block Device-Local Connections Per App Advanced filter/blockLocal

Force 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.

Force 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.

Custom Filter List Global Advanced filter/customListFile

Specify the file path to a custom filter list (.txt), which will be automatically refreshed. Any connections matching a domain, IP address, Country or ASN in the file will be blocked.

Default Network Action Per App filter/defaultAction

The default network action is applied when nothing else allows or blocks a connection. This affects both outgoing and incoming connections. This setting is the weakest of all and is commonly overruled by Force Block settings or Rules.

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.

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.

Seamless DNS Integration Global Developer Experimental filter/dnsQueryInterception

Intercept and redirect astray DNS queries to the Portmaster’s internal DNS server. This enables seamless DNS integration without having to configure the system or other software. However, this may lead to compatibility issues with other software that attempts the same.

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.

Enable Privacy Filter Global Developer Experimental filter/enable

Enable the Privacy Filter. If turned off, all privacy filter protections are fully disabled on this device. Not meant to be disabled in production - only turn off for testing.

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”.

Outgoing Rules Per App Stackable filter/endpoints

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

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.

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.

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.

Block Secure DNS Bypassing Per App filter/preventBypassing

Prevent apps from bypassing Portmaster’s Secure DNS resolver. If disabled, Portmaster might have reduced information to correctly enforce rules and filter lists. Important: Portmaster’s firewall itself cannot be bypassed.

Current Features:

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

Please note that DNS bypass attempts might be additionally blocked in the System DNS Client App.

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.

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.

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.

Incoming Rules Per App Stackable Advanced filter/serviceEndpoints

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

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.

Enable Network History Global history/enable

Save connections in a database (on disk) in order to view and search them later. Changes might take a couple minutes to apply to all connections.

In order to reduce noise optimize performance, internal and device-only (localhost) connections are not saved to history.

Keep Network History Global history/keep

Specify how many days the network history data should be kept. Please keep in mind that more available history data makes reports (coming soon) a lot more useful.

Older data is deleted in intervals and cleared from the database continually. If in a hurry, shutdown or restart Portmaster to clear deleted entries immediately.

Set to 0 days to keep network history forever. Depending on your device, this might affect performance.

DNS Exit Node Rules Global Requires Restart Advanced spn/dnsExitPolicy

Customize which countries should or should not be used as DNS Exit Nodes.

By default, the Portmaster will exit DNS requests directly at your Home Node in order to keep them fast and close to your location. This is important, as DNS resolution often takes your approximate location into account when deciding which optimized DNS records are returned to you. As the Portmaster encrypts your DNS requests by default, you effectively gain a two-hop security level for your DNS requests in order to protect your privacy.

This setting mainly exists for when you need to simulate your presence in another location on a lower level too. This might be necessary to defeat more intelligent geo-blocking systems.

SPN Module Global spn/enable

Start the Safing Privacy Network module. If turned off, the SPN is fully disabled on this device.

Exit Node Rules Per App Stackable spn/exitHubPolicy

Customize which countries should or should not be used for your Exit Nodes. Exit Nodes are used to exit the SPN and establish a connection to your destination.

By default, the Portmaster tries to choose the node closest to the destination as the Exit Node. This reduces your exposure to the open Internet. Exit Nodes are chosen for every destination separately.

Home Node Rules Global Requires Restart Advanced spn/homePolicy

Customize which countries should or should not be used for your Home Node. The Home Node is your entry into the SPN. You connect directly to it and all your connections are routed through it.

By default, the Portmaster tries to choose the nearest node as your Home Node in order to reduce your exposure to the open Internet.

Reconnect to the SPN in order to apply new rules.

Select SPN Routing Algorithm Per App spn/routingAlgorithm

Select the routing algorithm for your connections through the SPN. Configure your preferred balance between speed and privacy. Portmaster may automatically upgrade the routing algorithm if necessary to protect your privacy.

Special Access Code Global spn/specialAccessCode

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

Transit Node Rules Global Stackable Advanced spn/transitHubPolicy

Customize which countries should or should not be used as Transit Nodes. Transit Nodes are used to transit the SPN from your Home to your Exit Node.

Trust Nodes Global Advanced spn/trustNodes

Specify which community nodes to additionally trust. These nodes may then also be used as a Home Node, as well as an Exit Node for unencrypted connections.

SPN Rules Per App Stackable spn/usagePolicy

Customize which websites should or should not be routed through the SPN. Only active if “Use SPN” is enabled.

Use SPN Per App spn/use

Protect network traffic with the Safing Privacy Network. If the SPN is not available or the connection is interrupted, network traffic will be blocked.

Use Community Nodes Global Requires Restart spn/useCommunityNodes

Use nodes (servers) not operated by Safing themselves. The use of community nodes is recommended as it diversifies the ownership of the nodes you use for your connections and further strengthens your privacy. Plain connections (eg. http, smtp, …) will never exit via community nodes, making this setting safe to use.