## 1. Project Overview & Quickstart (safing/angular.json) # angular.json Open-source repository safing/angular.json ### Repository Details - **Repository:** [safing/angular.json](https://github.com/safing/angular.json) - **Primary Language:** Code *Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.* ## 2. Official Technical Reference & Guides (safing/docs) ## File: README.md > **Check out the main project repository [safing/portmaster](https://github.com/safing/portmaster)** --- ## File: _data/README.md # Sourced Data ### Update all data ``` make update ``` ### Create faq/all.json ``` make faq/all.json ``` ### Create releases/all.json ``` make releases/all.json ``` ### Create versions/* ``` make versions-data ``` --- ## File: portmaster/guides/contribute/docs-guide.md --- title: Documentation Contributor Guide layout: base --- ### Getting Started **Pre-requisites** 1. [Get Docker](https://docs.docker.com/get-docker/) 2. Clone this repository via git command line or a graphical tool such as GitHub Desktop. 3. Fork this repository. **run the project** ```sh # inside this repository docker-compose up ``` ### Making Changes 1. Open the project in a project editor like VIM or an IDE such as Visual Studio Code. 2. Understand the project structure. 3. _data/menus.yml controls which markdown files will be displayed. 4. Leading folders such as portmaster, spn, and safing represent the main menu. 5. Additional folders and the menu structure can be understood from the _data/menus.yml 6. Add, delete and modify as needed. 7. Hopefully obviously, commit your changes when ready, create a pull request. [More Detailed Information](https://jekyllrb.com/docs) on the Jekyll project. --- ## File: portmaster/guides/contribute/portmaster-guide.md --- title: Portmaster Contributor Guide layout: base --- ## Getting Started * in progress --- ## File: portmaster/guides/contribute.md --- title: How To Contribute toc_max_header: 3 layout: base --- ###### Thanks For Participating! It is amazing to see you love Portmaster so much that you are checking out this guide. As a small team, **your contribution means the world to us.** We could not do it without you! ## Spread the Word > With [version 1.0](https://safing.io/blog/2022/10/27/portmaster-reaches-1.0/), Portmaster should be recommended as one of the first steps anybody should take within their privacy journey. As new software - too few people know about Portmaster. This is where your impact will be biggest! ### Ask Your Favorite Creators For Reviews A big help to us would be if you could think of your favorite creators and shows: It could be YouTubers, Newsletters, guides, podcasts and so on. Do these creators know about Portmaster already? Would they enjoy sharing a review on their show? Give them a ping and ask them what they think about Portmaster. This could domino effect into hundreds of thousands of people getting better privacy! ### Do You Have An Audience? If you are a creator or someone who gives recommendations, no matter what you think of Portmaster - we'd love for you to have a look and tell your audience what you think! Optionally, give us a ping after to brighten our day. ### Tell Your Friends We have no idea how you communicate with your friends on- and offline; and we do not want to know. But what we do know is that if you enjoy Portmaster somebody else will likely too. You know best whom to tell and how to tell them. Be it a private signal message or a recommendation on your favorite online forum. To all of you. Thanks for sharing, it makes all the difference! ## Financial Support The most direct way to [support Portmaster development]({{ site.pricing_url }}) is through an upgrade. The "Supporter" package gives you optional badges to show off your support, while ["Unlimited"]({{ site.spn_url }}) takes your privacy to the next level. ## While Using Portmaster {% include github_notification.html %} ### Report Bugs, Suggest Features and Improvements You can easily report bugs as you stumble upon them. It is best if you quickly check other reports to prevent duplicates. All reports are welcome and help us better understand where the Portmaster experience still needs to improve. While we are not at a stage where we can tackle all incoming issues and edge cases yet, please do note **we read every incoming report**. If you have any ideas we'd love to hear how you would improve things. | | Portmaster []({{ site.github_pm_url }}) | User Interface []({{ site.github_pm_ui_url }}) | Packaging []({{ site.github_pm_packaging_url }}) | |---|:---:|:---:|:---:| | 🐞 Bug Report | [report]({{ site.github_pm_url }}{{ site.github_report_bug_url }}) | [report]({{ site.github_pm_ui_url }}{{ site.github_report_bug_url }}) | [report]({{ site.github_pm_packaging_url }}{{ site.github_report_bug_url }}) | | 💡 Suggestion: New Feature | [suggest]({{ site.github_pm_url }}{{ site.github_suggest_feature_url }}) | [suggest]({{ site.github_pm_ui_url }}{{ site.github_suggest_feature_url }}) | [suggest]({{ site.github_pm_packaging_url }}{{ site.github_suggest_feature_url }}) | | 💡 Suggestion: Improvements | [suggest]({{ site.github_pm_url }}{{ site.github_suggest_feature_url }}) | [suggest]({{ site.github_pm_ui_url }}{{ site.github_suggest_feature_url }}) | [suggest]({{ site.github_pm_packaging_url }}{{ site.github_suggest_feature_url }}) | #### Report Linux Distribution Compatibility Help us understand Portmaster compatibility with different Linux distributions. Whether it works with your distro or not - your reports will help us massively to know where we stand. We will update the [Linux compatibility list](../install/linux#compatibility) accordingly. #### Report VPN Compatibility Help us understand Portmaster compatibility with different VPN clients. Whether the VPN client works together with the Portmaster or not - your reports will help us massively to know where we currently stand. All reports are collected, updated and easily accessible in the [VPN Compatibility section](../install/status/vpn-compatibility). #### Report Software Compatibility Have certain applications stopped working with the Portmaster? Or games? Or a special development tool? Your reports will help us massively to know where we currently stand. All reports are collected and easily accessible in the [Software Compatibility section](../install/status/software-compatibility). | 📝 Compatibility Report: VPN | [report]({{ site.github_pm_url }}{{ site.github_report_compatibility_url }}) | | 📝 Compatibility Report: Linux distro | [report]({{ site.github_pm_url }}{{ site.github_report_compatibility_url }}) | | 📝 Compatibility Report: General Software | [report]({{ site.github_pm_url }}{{ site.github_report_compatibility_url }}) | ### Contribute to the Code Overall, we do welcome code contributions - but here are two things you must know before starting: ###### 📑 A Code License Agreement Is Sometimes Required Our [Code License Agreement](https://gist.github.com/Raphty/e22b3c028c7ec07d995b3882f63d7ebb) gives us full legal flexibility, which we require for our main projects. The openness of the code is in no way hindered by this: Anyone can still fork and do whatever they want with the code according to its license. But if you want to change something in our main repositories we do require to keep ownership of the code. This also applies to small fixes or typos. ###### 🗣 For Anything Bigger Communication with Safing Is A Must We truly do not want you to spend a lot of your precious time and effort into a feature which would turn out to misalign with our current goals and focus. So please, *check with us first via GitHub or * before tackling a big pull request. | | Portmaster []({{ site.github_pm_url }}) | User Interface []({{ site.github_pm_ui_url }}) | Packaging []({{ site.github_pm_packaging_url }}) | |---|:---:|:---:|:---:| | ⚔️ Pull Request: Typos and Small Fixes | 📑 | 📑 | | | ⚔️ Pull Request: Feature Implementation | 📑🗣 | 📑🗣 | 🗣 | ### Assist with Documentation and the Website {% include github_notification.html %} #### Report Bugs, Inaccuracies and Typos We try our best to keep everything running and up-to-date - but you still might find bugs, inaccurate information or typos. In that case, it would be great if you could let us know. Or even create a pull request with a fix. #### Suggest New Sections Our Documentation and Website are living projects. We are happy to hear your ideas on what to add or how to improve: | | Documentation []({{ site.github_docs_url }}) | Website []({{ site.github_web_url }}) | |---|:---:|:---:| | 🐞 Bug Report | [report]({{ site.github_docs_url }}{{ site.github_report_bug_url }}) | [report]({{ site.github_web_url }}{{ site.github_report_bug_url }}) | | 🐞 Report: Inaccuracy/Typo | [report]({{ site.github_docs_url }}{{ site.github_report_bug_url }}) | [report]({{ site.github_web_url }}{{ site.github_report_bug_url }}) | | 💡 Suggestion: New Page/Segment | [suggest]({{ site.github_docs_url }}{{ site.github_suggest_feature_url }}) | [suggest]({{ site.github_web_url }}{{ site.github_suggest_feature_url }}) | | 💡 Suggestion: Improvements | [suggest]({{ site.github_docs_url }}{{ site.github_suggest_feature_url }}) | [suggest]({{ site.github_web_url }}{{ site.github_suggest_feature_url }}) | #### Contribute to the Web-Projects We welcome code contributions - still here are two things you must know before starting: ###### 📑 A Code License Agreement Is NOT Required for Docs & Website Opposed to our [main repositories](#contribute-to-the-code) we do not require full legal flexibility with these repositories. You can simply clone and set up a pull request with no legal jumbo in your way. ###### 🗣 For Anything Bigger Communication with Safing Is A Must However, we truly do not want you to spend a lot of your precious time and effort into a feature which would turn out to misalign with our current goals and focus. So please, *check with us first via GitHub or * before tackling a bigger pull request. | | Documentation []({{ site.github_docs_url }}) | Website []({{ site.github_web_url }}) | |---|:---:|:---:|:---:| | ⚔️ Pull Request: Typos and Small Fixes | | | | ⚔️ Pull Request: Feature Implementation | 🗣 | 🗣 | ### Other, Out-Of-Scope If you want to contribute beyond the listed guide it is best to check with us first. We as a team have limited resources and do not want your precious time and effort to go to waste. So please, _check with us first via GitHub or _. ### Appendix: Cheat Sheet {% include github_notification.html %} | | Portmaster []({{ site.github_pm_url }}) | User Interface []({{ site.github_pm_ui_url }}) | Packaging []({{ site.github_pm_packaging_url }}) | Docs []({{ site.github_docs_url }}) | Website []({{ site.github_web_url }}) | |---|:---:|:---:|:---:|:---:|:---:| | 🐞 Bug Report | [report]({{ site.github_pm_url }}{{ site.github_report_bug_url }}) | [report]({{ site.github_pm_ui_url }}{{ site.github_report_bug_url }}) | [report]({{ site.github_pm_packaging_url }}{{ site.github_report_bug_url }}) | [report]({{ site.github_docs_url }}{{ site.github_report_bug_url }}) | [report]({{ site.github_web_url }}{{ site.github_report_bug_url }}) | | 💡 Suggestion: New Feature | [suggest]({{ site.github_pm_url }}{{ site.github_suggest_feature_url }}) | [suggest]({{ site.github_pm_ui_url }}{{ site.github_suggest_feature_url }}) | [suggest]({{ site.github_pm_packaging_url }}{{ site.github_suggest_feature_url }}) | [suggest]({{ site.github_docs_url }}{{ site.github_suggest_feature_url }}) | [suggest]({{ site.github_web_url }}{{ site.github_suggest_feature_url }}) | | 💡 Suggestion: Improvements | [suggest]({{ site.github_pm_url }}{{ site.github_suggest_feature_url }}) | [suggest]({{ site.github_pm_ui_url }}{{ site.github_suggest_feature_url }}) | [suggest]({{ site.github_pm_packaging_url }}{{ site.github_suggest_feature_url }}) | [suggest]({{ site.github_docs_url }}{{ site.github_suggest_feature_url }}) | [suggest]({{ site.github_web_url }}{{ site.github_suggest_feature_url }}) | | 📝 Compatibility: VPN | [report]({{ site.github_pm_url }}{{ site.github_report_compatibility_url }}) | | | | | | 📝 Compatibility: Linux distro | [report]({{ site.github_pm_url }}{{ site.github_report_compatibility_url }}) | | | | | | 📝 Compatibility: Software | [report]({{ site.github_pm_url }}{{ site.github_report_compatibility_url }}) | | | | | | ⚔️ PR: Typos and Small Fixes | 📑 | 📑 | | | | | | | ⚔️ PR: Feature Implementation | 📑🗣 | 📑🗣 | 🗣 | 🗣 | 🗣 | --- ## File: portmaster/guides/dns-configuration.md --- title: DNS Configuration layout: base --- You can set the {% include setting/ref.html key="dns/nameservers" %} setting to a list of servers that you would like to use. By default, only the first server in the list will be used, unless it fails or does not meet other configured requirements. ### DNS Configuration URL Scheme DNS servers are configured using an URL scheme, the format is: ```plain protocol://ip:port?parameter=value¶meter=value ``` These are the possible values: ###### Protocols - `dot`: DNS-over-TLS (recommended) - `dns`: plain DNS - `tcp`: plain DNS over TCP ###### IP DNS Server configurations **must** use the server IP address instead of its hostname. Using a domain is not possible because there is no guarantee that there is another DNS Server available to resolve that domain. ###### Port You must specify the server port if non-standard. The standard ports are: - `dot`: 853 - `dns`: 53 - `tcp`: 53 ###### Parameters A DNS server configuration URL might have one or more the the following parameters configured. - `name`: Give your DNS server a name that is used for messages and logs. - `verify`: Domain name to verify for `dot` servers, required and only valid for `dot` servers. - `blockedif`: How to detect if the name server blocks a query. Different name servers handle blocked responses differently. - `empty`: Server replies with NXDomain status, but without any other record in any section. - `refused`: Server replies with Refused status. - `zeroip`: Server replies with an IP address, but it is zero (ie. `0.0.0.0` for IPv4). ### Common Server Settings Here are some common DNS Servers and their Portmaster configuration. Please note that we _do not_ recommend using IPv6 as the vast address space leads to increased trackability. #### Quad9 [Quad9](https://quad9.org/) is a public DNS service that provides malware protection and is run by a non-profit. ``` # Malware Protection: dot://9.9.9.9:853?verify=dns.quad9.net&name=Quad9&blockedif=empty dot://149.112.112.112:853?verify=dns.quad9.net&name=Quad9&blockedif=empty # Malware Protection, IPv6: dot://[2620:fe::fe]:853?verify=dns.quad9.net&name=Quad9&blockedif=empty dot://[2620:fe::9]:853?verify=dns.quad9.net&name=Quad9&blockedif=empty ``` #### AdGuard [AdGuard](https://adguard.com/) offers a freemium [public DNS service](https://adguard.com/en/adguard-dns/overview.html) that also blocks ads. Note: The Portmaster uses the publicly available ads blocklist from AdGuard in the Portmaster's Filter Lists by default. ``` # Ad Blocking: dot://94.140.14.14:853?verify=dns.adguard.com&name=AdGuard&blockedif=zeroip dot://94.140.15.15:853?verify=dns.adguard.com&name=AdGuard&blockedif=zeroip # Ad Blocking, IPv6: dot://[2a10:50c0::ad1:ff]:853?verify=dns.adguard.com&name=AdGuard&blockedif=zeroip dot://[2a10:50c0::ad2:ff]?verify=dns.adguard.com&name=AdGuard&blockedif=zeroip # Ad Blocking, Family Protection: dot://94.140.14.15:853?verify=dns.adguard.com&name=AdGuard&blockedif=zeroip dot://94.140.15.16:853?verify=dns.adguard.com&name=AdGuard&blockedif=zeroip # Ad Blocking, Familty Protection, IPv6: dot://[2a10:50c0::bad1:ff]:853?verify=dns.adguard.com&name=AdGuard&blockedif=zeroip dot://[2a10:50c0::bad2:ff]?verify=dns.adguard.com&name=AdGuard&blockedif=zeroip ``` #### Foundation for Applied Privacy (encrypted DNS) The [Foundation for Applied Privacy](https://applied-privacy.net/) is a small non-profit that also runs a [public DNS service](https://applied-privacy.net/services/dns/). ``` # No Filtering: dot://146.255.56.98:853?verify=dot1.applied-privacy.net&name=AppliedPrivacy # No Filtering, IPv6: dot://[2a02:1b8:10:234::2]:853?verify=dot1.applied-privacy.net&name=AppliedPrivacy ``` #### Cloudflare Cloudflare is a behemoth of the Internet. Next to its commercial offerings, it also provices a [public DNS service](https://1.1.1.1/dns/). ``` # Malware Protection: dot://1.1.1.2:853?verify=cloudflare-dns.com&name=Cloudflare&blockedif=zeroip dot://1.0.0.2:853?verify=cloudflare-dns.com&name=Cloudflare&blockedif=zeroip # Malware Protection, IPv6: dot://[2606:4700:4700::1112]:853?verify=cloudflare-dns.com&name=Cloudflare&blockedif=zeroip dot://[2606:4700:4700::1002]:853?verify=cloudflare-dns.com&name=Cloudflare&blockedif=zeroip # Malware and Family Protection: dot://1.1.1.3:853?verify=cloudflare-dns.com&name=Cloudflare&blockedif=zeroip dot://1.0.0.3:853?verify=cloudflare-dns.com&name=Cloudflare&blockedif=zeroip # Malware and Family Protection, IPv6: dot://[2606:4700:4700::1113]:853?verify=cloudflare-dns.com&name=Cloudflare&blockedif=zeroip dot://[2606:4700:4700::1003]:853?verify=cloudflare-dns.com&name=Cloudflare&blockedif=zeroip ``` ### Community Suggested Server Settings Needs are different, that is why we list settings suggested by the community down below. Is something missing or out of date? [Make a report](https://github.com/safing/docs/issues/new?assignees=&labels=suggestion&template=suggest-feature.md) or [create a pull request](https://github.com/safing/docs). #### BlahDNS [](https://blahdns.com/) ``` # Malware Protection, Ad Blocking 🇨🇭 Switzerland: dot://45.91.92.121:853?verify=dot-ch.blahdns.com&name=BlahDNSch&blockedif=zeroip 🇯🇵 Japan: dot://139.162.112.47:853?verify=dot-jp.blahdns.com&name=BlahDNSjp&blockedif=zeroip 🇸🇬 Singapore: dot://192.53.175.149:853?verify=dot-sg.blahdns.com&name=BlahDNSsg&blockedif=zeroip 🇩🇪 Germany: dot://78.46.244.143:853?verify=dot-de.blahdns.com&name=BlahDNSde&blockedif=zeroip 🇫🇮 Finland: dot://95.216.212.177:853?verify=dot-fi.blahdns.com&name=BlahDNSfi&blockedif=zeroip ``` #### LibreDNS [](https://libredns.gr/) ``` # No Filtering dot://116.202.176.26:853?verify=dot.libredns.gr&name=LibreDNS # Malware Protection, Ad & Tracker Blocking dot://116.202.176.26:854?verify=dot.libredns.gr&name=LibreDNS&blockedif=zeroip ``` #### NextDNS [](https://www.nextdns.io/) Please follow this guide to [set up NextDNS in the Portmaster](https://github.com/safing/portmaster/issues/291) #### Snopyta [](https://snopyta.org/service/dns/index.html) ``` # No Filtering: dot://95.216.24.230:853?verify=fi.dot.dns.snopyta.org&name=SnopytaDNS # No Filtering, IPv6: dot://[2a01:4f9:2a:1919::9301]:853?verify=fi.dot.dns.snopyta.org&name=SnopytaDNS ``` ### Community Requested Server Settings In contrast to the settings mentioned above, we do not recommend to use these servers. These providers are known to excessively collect user data. But as needs are different, we also list these settings requested by the community. Is something missing or out of date? [Make a report](https://github.com/safing/docs/issues/new?assignees=&labels=suggestion&template=suggest-feature.md) or [create a pull request](https://github.com/safing/docs). #### Google Public DNS [](https://developers.google.com/speed/public-dns/docs/using) Use at your own risk: ``` # No Filtering: dot://8.8.8.8:853?verify=dns.google&name=GoogleDNS&blockedif=zeroip dot://8.8.4.4:853?verify=dns.google&name=GoogleDNS&blockedif=zeroip # No Filtering, IPv6: dot://[2001:4860:4860::8888]?verify=dns.google&name=GoogleDNS&blockedif=zeroip dot://[2001:4860:4860::8844]?verify=dns.google&name=GoogleDNS&blockedif=zeroip ``` ### Disabling DNS Unfortunately, you cannot disable the Secure DNS module directly. This is because it is a crucial component: Through this the Portmaster can see which domains are being resolved by which application. This is vital information for the Portmaster to provide you with the promised privacy protection. However, if you would just rather use the plain DNS servers configured in your Operating System, you can just remove all configured {% include setting/ref.html key="dns/nameservers" %} from the settings in the Portmaster. This will leave the list of configured DNS Servers within Portmaster empty. In this case, the DNS queries will still go through the Portmaster, but will end up at the same DNS server as before. The Portmaster is then only somewhat transparently inserted in the chain of servers. While some systems are starting to offer DNS-over-TLS and DNS-over-HTTPS natively, these settings are usually not as integrated into the programming interfaces as the plain DNS servers. This means that the Portmaster will only pick up configured _plain DNS servers_ from the Operating System. You can of course always configure the same DNS-over-TLS server directly in the Portmaster. ### Further Readings - [How Safing Selects its Default DNS Providers](https://safing.io/blog/2020/07/07/how-safing-selects-its-default-dns-providers/) - [We Are Updating Portmaster's Default DNS Servers](https://safing.io/blog/2020/07/07/we-are-updating-portmasters-default-dns-servers/) --- ## File: portmaster/guides/network-rating.md --- title: Network Rating layout: base --- ### What Is the Network Rating? The [Network Rating]({{ site.portmaster_settings_url }}#core/enableNetworkRating) setting enables you to configure different Portmaster settings to be active in one environment but not in the other, like allowing sensitive connections at home but not at the public library. In earlier Portmaster days this complex system was the only way to configure certain settings, often leaving new users confused. Since then the default has been replaced by [Simple "On/Off" Toggles](https://safing.io/blog/2022/03/01/portmaster-0.8-simple-toggles/). Power users can still access this feature, but it is disabled by default on all new Portmaster installs. _Note: it is planned to replace the Network Rating by a superior and easier to understand system in the future._ ### How Do I Get the Simple Toggles? If you already have Portmaster installed you are likely to still see Network Rating System. In order to get the Simple Toggles, you have to: 1. Switch to the "Advanced Interface" in the top right 2. Go to Global Settings > Core > User Interface 3. **Disable** the Network Rating System ### How Do I Activate the Advanced Network Rating System? If you see the Simple Toggles but would like to make use of the advanced Network Rating System, you need to: 1. Switch to the "Advanced Interface" in the top right 2. Go to Global Settings > Core > User Interface 3. **Enable** the Network Rating System