Commit 08bc3b9e authored by Daniel Wolf's avatar Daniel Wolf
Browse files
parents e597f36f f2956249
Pipeline #7392 passed with stage
in 4 minutes and 24 seconds
......@@ -2,13 +2,22 @@
A selection of common questions and a collection of technical aspects of Nebulo. Feel free to ask a question in the issues and I'll add it here as well.
## Non-VPN mode
(Go [here](docs/NONVPNMODE.md) for documentation)
Since 1.4.0 Nebulo can run without requiring the dummy VPN. In this mode Nebulo hosts a DNS server locally, which forwards all DNS queries it receives according to the settings you configured in Nebulo.<br>
In this mode you manually have to forward all the DNS queries your decice creates to Nebulos local DNS server (normally this is what the dummy VPN is used for).<br>
If your device is rooted Nebulo has an inbuilt solution using `iptables`. If it isn't rooted you have to use third-party apps which are able to forward the DNS queries to Nebulo.
Known third-party apps this works with are NetGuard and V2Ray (although there might be others). You can find instructions on how to configure these apps to work together with Nebulo in the settings.<br>
In this mode you manually have to forward all the DNS queries your device creates to Nebulos local DNS server (normally this is what the dummy VPN is used for).<br><br>
If your device is rooted Nebulo has an inbuilt solution using iptables. If it isn't rooted you have to use third-party apps which are able to forward the DNS queries to Nebulo.<br>
Known third-party apps this works with are NetGuard and V2Ray (although there might be others). You can find instructions on how to configure these apps to work together with Nebulo in the settings or by clicking [here](docs/NONVPNMODE.md).<br>
Please note that the App exclusion setting inside the general category won't have any effect in non-VPN mode. You have to configure excluded apps inside the third-party app you are using.
## Query logging
Query logging is feature inside Nebulo. If enabled (Settings -> Query logging), it can be found in the navigation drawer.
### What does it do?
When Query logging is enabled Nebulo saves all DNS queries it receives while it is running.
This allows you to see the DNS queries your device has made in the past.
The list updates in realtime when Nebulo is active.\n
You can search for hosts in the query log.
### What do the icons mean in the query log?
There are 4 icons in the query log:
- Database/server icon: cache is enabled and the DNS response came from cache
......@@ -21,4 +30,77 @@ There are 4 icons in the query log:
Currently no. The Android platform and the libraries I am using lack support for ESNI (https://git.frostnerd.com/PublicAndroidApps/smokescreen/-/issues/237)
### Do I need ESNI?
Most likely no. It would make it harder for government/ISPs to block access to a DNS server though.
\ No newline at end of file
Most likely no. It would make it harder for government/ISPs to block access to a DNS server though.
## DNS rules
DNS rules are a feature inside Nebulo. You can find the page for them in the navigation drawer.
### What are DNS rules?
You can use DNS rules to either redirect a host to some IP addresses of your choice, or to block that host completely.\n
By blocking the host it isn't reachable from your phone anymore, which you can use to block ads, tracking (even inside apps).
You can even block websites you don't want to be able to visit anymore;
for example, you could set up your childs phone to block porn pages.
### How do I use DNS rules?
There are two options on how to use the DNS rules:<br>
You can either define your own rules - for example to block single hosts - or import *rule sources* which contain a list of rules.<br><br>
There are multiple lists maintained by independent people you can use in Nebulo.
They cover different topics, from blocking ads, tracking to blocking porn or social media.<br>
I recommend checking out [Energized](energized.pro).
It has multiple types of lists, covering use cases mentioned above.
If you have the F-Droid version the Energized lists are already added as sources.
#### Own (custom) rules
To create custom DNS rules scroll the list until you see this entry (without the numbers in red of course):<br><br>
<img width=500px height=136px src="material/faq/custom_dns_rule.png" alt="Project logo"></a>
<br>
Click on the switch (1) to disable or enable custom rules.<br>
Click on the trash bin (2) to delete all custom rules<br>
Click on the plus (3) to add a new rule<br>
Click on the chevron (4) to expand the list of custom rules
#### Rule sources
If you use the F-Droid version of Nebulo there are already a number of rule sources added by default.<br>
If not, click on the plus button in the round circle to add a new source. You can either input an URL or choose a file from your phone.<br>
If you define a source as whitelist source by selecting the checkbox the hosts in this source will never be blocked by other DNS rules.<br>
Newly added sources are enabled by default and you can toggle them by clicking on the switch of each row.
To delete a source click on the trashcan.<br>
Any of those actions requires a refresh (explained in the next text).
#### Refreshing the sources
After changing the rule sources (enabling, deleting, adding or disabling a rule source) you have to refresh the DNS rules.
This is required because Nebulo has to download and parse the rule sources.<br>
When Nebulo is importing the sources a notification appears in which you can see the current progress.<br><br>
To refresh the sources click on the round refresh icon located in the center at the bottom.
A dialog will appear where you can either schedule a recurring refresh or click on 'Refresh now' to process the changes instantly.<br>
If you want to schedule a recurring refresh select the checkbox, choose your desired time between refreshes and click ok to save (clicking 'refresh now' or cancel won't save it!)
<br>
Alternativly to process every source you also can just refresh a single source.
To do that click on the refresh icon of a single row instead of the one at the bottom in the circle.<br>
You do not have to refresh the sources if you only changed custom rules.
You might have to restart the app though if Nebulo is running (by clicking stop and then start) because the rule might be cached (either by Nebulo or the system)
#### Can I edit sources/custom rules after creating them?
Sure! Just click on them once.
### How do I check whether a host is blocked?
To check whether a host is blocked click on the magnifying glass in the top bar.<br>
A dialog will appear where you can input a host.
After a few moments a text will appear telling you whether this host is part of a rule and which source it is a part of (if any)
### Can I export my combined rules?
Yes, you can!<br>
To do that click on the arrow-up icon in the circle at the bottom of the page.<br>
A dialog will appear asking you what you want to export.
Whitelist and normal DNS rules cannot be combined and have to be exported separately.
### What are whitelists for?
By whitelisting a custom rule (or setting a source as whitelist source), the host(s) are never blocked by any other DNS rule.
It allows you to unblock hosts, which might have been blocked by accident.
### Can I block multiple hosts at once with a single DNS rule? (Wildcards)
Yes, you can!<br>
Nebulo supports wildcards which allows you to specify a pattern of hosts you want to block or whitelist.
With this you can for example block/whitelist every host which contains a certain word or ends in a certain host.<br>
To see some examples of what you have to input for the host when creating a custom rule, click [here](docs/DNSRULE_WILDCARDS.md).<br>
It's a really powerful method of blocking hosts which have a common pattern (for example ad-servers which most of the time end in the same host, but do have random subdomains)
\ No newline at end of file
......@@ -128,7 +128,7 @@ dependencies {
implementation 'com.frostnerd.utilskt:preferences:1.5.29' // https://git.frostnerd.com/AndroidUtils/preferenceskt
implementation 'com.frostnerd.utilskt:navigationdraweractivity:1.4.0' // https://git.frostnerd.com/AndroidUtils/navigationdraweractivity
implementation 'com.frostnerd.utilskt:encrypteddnstunnelproxy:1.6.2' // https://git.frostnerd.com/AndroidUtils/encrypteddnstunnelproxy
implementation 'com.frostnerd.utilskt:encrypteddnstunnelproxy:1.6.3' // https://git.frostnerd.com/AndroidUtils/encrypteddnstunnelproxy
implementation 'com.frostnerd.utilskt:general:1.0.25' // https://git.frostnerd.com/AndroidUtils/generalkt
implementation 'com.frostnerd.utilskt:adapters:1.2.0' // https://git.frostnerd.com/AndroidUtils/Adapters
......
......@@ -4,10 +4,7 @@ import android.app.Activity
import android.app.AlarmManager
import android.app.KeyguardManager
import android.app.PendingIntent
import android.content.BroadcastReceiver
import android.content.Context
import android.content.Intent
import android.content.IntentFilter
import android.content.*
import android.hardware.fingerprint.FingerprintManager
import android.net.ConnectivityManager
import android.net.Network
......@@ -15,6 +12,7 @@ import android.net.NetworkCapabilities
import android.net.Uri
import android.os.Build
import android.os.PowerManager
import android.widget.Toast
import androidx.appcompat.app.AppCompatActivity
import androidx.fragment.app.Fragment
import androidx.lifecycle.Lifecycle
......@@ -423,4 +421,17 @@ val Context.isPrivateDnsActive: Boolean
if (it.activeNetwork == null) false
else it.getLinkProperties(it.activeNetwork)?.isPrivateDnsActive ?: false
}
}
\ No newline at end of file
}
fun Context.tryOpenBrowser(withLink:String) {
try {
startActivity(
Intent(
Intent.ACTION_VIEW,
Uri.parse(withLink)
)
)
} catch (e: ActivityNotFoundException) {
Toast.makeText(this, R.string.error_no_webbrowser_installed, Toast.LENGTH_LONG).show()
}
}
\ No newline at end of file
......@@ -175,9 +175,9 @@ class DnsRuleDialog(context: Context, dnsRule: DnsRule? = null, onRuleCreated: (
}
}
isBlockHost = dnsRule.target == "0.0.0.0" && dnsRule.ipv6Target == "::1"
if(!isBlockHost) {
view.blockHost.isChecked = false
}
}
if(!isBlockHost) {
view.blockHost.isChecked = false
}
}
}
......
......@@ -118,17 +118,7 @@ class AboutFragment : Fragment() {
true
}
view.faq.setOnClickListener {
try {
startActivity(
Intent(
Intent.ACTION_VIEW,
Uri.parse("https://nebulo.app/faq")
)
)
} catch (e: ActivityNotFoundException) {
Toast.makeText(requireContext(), R.string.error_no_webbrowser_installed, Toast.LENGTH_LONG)
.show()
}
requireContext().tryOpenBrowser("https://nebulo.app/faq")
}
}
}
\ No newline at end of file
......@@ -325,6 +325,10 @@ class SettingsFragment : PreferenceFragmentCompat() {
)
true
}
findPreference("nonvpn_help_faq").setOnPreferenceClickListener {
requireContext().tryOpenBrowser("https://nebulo.app/faq#non-vpn-mode")
true
}
}
@SuppressLint("NewApi")
......
......@@ -427,6 +427,9 @@
<string name="changelog_build_66_6">Added BraveDNS and Cloudflare security</string>
<string name="changelog_build_66_7">Added introduction screens when first launching the app</string>
<string name="changelog_build_66_8">Added a server selection screen when first launching the app</string>
<string name="changelog_build_66_9">Added a notification shown when the current server has a bad connection</string>
<string name="changelog_build_66_10">Added a filter to the query log</string>
<string name="changelog_build_66_11">Added a field showing how many queries have been resolved with DNS rules</string>
<string-array name="changelog_build_66">
<item>Version 1.5.0 (Build 66)</item>
<item>@string/changelog_build_66_1</item>
......@@ -435,5 +438,10 @@
<item>@string/changelog_build_66_4</item>
<item>@string/changelog_build_66_5</item>
<item>@string/changelog_build_66_6</item>
<item>@string/changelog_build_66_7</item>
<item>@string/changelog_build_66_8</item>
<item>@string/changelog_build_66_9</item>
<item>@string/changelog_build_66_10</item>
<item>@string/changelog_build_66_11</item>
</string-array>
</resources>
......@@ -219,4 +219,9 @@
<string name="dialog_dnsrules_status_userrule">This host is part of the DNS rules defined by you.</string>
<string name="dialog_dnsrules_status_fromsource">This host is part of the source %1s</string>
<string name="dialog_dnsrules_status_sourcenotfound">This host is in the DNS rules, but the source is unknown.</string>
<string name="querylog_filter_title">Filter query log</string>
<string name="querylog_filter_info">Select which types of queries you want to see</string>
<string name="querylog_filter_type_forwarded">Resolved by the DNS server</string>
<string name="querylog_filter_type_blocked_by_server">Blocked by the DNS server</string>
</resources>
......@@ -156,7 +156,7 @@
<string name="preference_category_nonvpnmode">Non-VPN mode</string>
<string name="summary_category_nonvpnmode">Configure Nebulo to act as a DNS server on the device instead of using a dummy VPN. When enabled you manually have to forward DNS queries to Nebulo using third party apps.\n\nThis feature is experimental.</string>
<string name="summary_category_nonvpnmode">Configure Nebulo to act as a DNS server on the device instead of using a dummy VPN. When enabled you manually have to forward DNS queries to Nebulo using third party apps</string>
<string name="summary_category_nonvpnmode_forwardinfo">Server will be hosted on localhost:%1s</string>
<string name="title_run_without_vpn">Run without VPN</string>
......@@ -183,6 +183,8 @@
<string name="nonvpn_help_generic_title">Generic VPN apps</string>
<string name="summary_nonvpn_help_generic">Click here to get instructions on how to configure VPN apps</string>
<string name="title_nonvpn_help_faq">Documentation</string>
<string name="summary_nonvpn_help_faq">Click here to open a browser window with help and documentation for non-VPN mode</string>
<string-array name="languages">
<item>System language</item>
......
......@@ -109,4 +109,20 @@
<string name="window_querylog_information">Information</string>
<string name="about_help_faq">Frequently asked questions</string>
<string name="warning_server_currently_unstable">The server %1s seems to be unstable right now.</string>
<string name="warning_server_currently_unstable_expanded">The server %1s seems to be unstable right now, impacting your browsing speed. Consider switching to a more stable server.</string>
<plurals name="dnsrule_total_resolve_count">
<item quantity="zero">%1d queries have been handled by DNS rules this far</item>
<item quantity="one">%1d query has been handled by DNS rules this far</item>
<item quantity="other">%1d queries have been handled by DNS rules this far</item>
</plurals>
<plurals name="dnsrule_total_resolve_count_block">
<item quantity="zero">%1d queries have been blocked this far</item>
<item quantity="one">%1d query have been blocked this far</item>
<item quantity="other">%1d queries have been blocked this far</item>
</plurals>
</resources>
......@@ -3,6 +3,11 @@
<androidx.preference.Preference android:summary="@string/summary_category_nonvpnmode" />
<androidx.preference.Preference
android:summary="@string/summary_nonvpn_help_faq"
android:key="nonvpn_help_faq"
android:title="@string/title_nonvpn_help_faq" />
<androidx.preference.PreferenceCategory android:title="@string/preference_category_nonvpnmode">
<androidx.preference.CheckBoxPreference
android:defaultValue="false"
......
As mentioned in the [FAQ](../FAQ.md#dns-rules) DNS rules in Nebulo support wildcards.<br>
They can be used to block/whitelist a number of hosts at once.<br>
This is useful if you have a single domain (let's say `example.com`) but with a lot of subdomains (let's say it has a lot of random subdomains like `aahwz.example.com`) which you all want to block.
Without wildcards you would have to create a rule for every domain.<br>
You can also use it to block all hosts which contain a defined word. Let's say you want to child-proof your phone and block every webpage which contains the word `porn` in the host.
Wildcards are your friend for that.<br>
Wildcards in Nebulo work by either including a single asterisk (\*) or double asterisk(\*\*) in the host when creating a custom rule.<br>
The single asterisk (\*) substitutes for any number of letters and numbers, except for a period (.).<br>
The double asterisk (\*\*) substitutes for any number of letters and numbers, including the period (.).
<br><br>
Below this you can find some examples of wildcards and what they block (or whitelist). Feel free to ask questions if something is unclear.
<br>
- `google.com` to block `google.com` and `www.google.com`
- `*google.com` to block `abcgoogle.com`, `google.com`, ... but not `abc.google.com`
- `*.google.com` to block `abc.google.com`, `abxdefg.google.com` but not `abc.xyz.google.com or `google.com`
- `**.google.com` to block `abc.google.com`, `abc.xyz.google.com` but not `google.com`
- `**google.com` to block everything which ends in google.com (`abc.google.com`, `google.com`, `abc.xyz.google.com`, `abcgoogle.com`, ...)
- `google.*` to block `google.com`, `google.de`, `www.google.de` but not `xyz.google.de` or `xyz.google.com` (the `www.` has a special role)
- `google**` to block everything which starts with google
- `**google**` to block everything which contains google (`google.com`, `google.de`, `hellogoogle.xyz`, `xyz.hellogoogle.com`, ...)
- `google**facebook` to block everything which contains google and facebook in the same host (`google-loves-facebook.com` but not `facebook-loves-google.com` or `facebook.com` or `google.com`)
<br>
Coming back to the examples above: if you want to block every domain which contains `porn` in the host, use `**porn**` as the host.
For blocking all subdomains of `example.com` use `**.example.com`.
\ No newline at end of file
# Non-VPN mode
As explained in the [FAQ](../FAQ.md) Nebulo has a non-VPN mode where it does not require the dummy VPN.<br>
As this dummy VPN is normally used to force Android to send all DNS queries to Nebulo you have to configure this yourself.<br>
If your phone is rooted you simply have to enable the iptables setting (which you also only see when your phone is rooted). If you want to know how it works scroll down.<br><br>
If your phone is not rooted you have to use third-party apps to forward DNS queries to Nebulo.
## Server port
Use this setting to configure the port Nebulo hosts the DNS server on.
It cannot be lower than `1024` and not higher than `65534`.<br>
The default is `11053`.
## Supported third-party apps
Some apps which can be used to forward the DNS queries from the device to Nebulo in non-VPN mode.<br>
This list is not exhaustive and there might be more apps.
Feel free to let me know if you found another one which does :)
### NetGuard
[NetGuard](https://github.com/M66B/NetGuard) is a firewall app you can use to block internet access of apps on your device.
It has a lot of customization options.<br>
By using it together with Nebulo you greatly increase your privacy and security as you now can keep your DNS queries safe while also controlling what your apps do with their internet access.
<br><br>
To combine Nebulo in non-VPN mode with NetGuard, first make sure you have the F-Droid version of NetGuard installed (or the one from their website).<br>
Then follow these steps (Click on the step for a screenshot):
- Open the settings of Netguard, go to Advanced options
- [Enable the settings "Filter traffic" and "Filer UDP traffic"](../material/faq/netguard_step2.png)
- [Click on "Port forwarding"](../material/faq/netguard_step3.png)
- [Add the following rule (plus button in the top bar)](../material/faq/netguard_step4.png):
- Protocol UDP
- Source port: 53
- Destination address: 127.0.0.1
- Destination port: The port you configured in the settings for Nebulos non-VPN mode (default 11053)
- Destination app: nobody
- Repeat, but use TCP as protocol
- Go back to Advanced options
- [Scroll down, set both "VPN DNS" fields to `127.0.0.1`](../material/faq/netguard_step7.png)
- Start both Nebulo (with non-VPN mode enabled) and NetGuard
That's it, now both are running at the same time! You should see the query count increase in Nebulos notification.
### V2Ray
[V2Ray](https://github.com/hetykai/V2Ray-Android) is an app supporting multiple protocols like Shadowsocks to hide your identity and anonymize your browsing.<br>
To use Nebulo with it you manually have to edit your config file to use the DNS server Nebulo hosts in non-VPN mode.
It is available at 127.0.0.1 and the port you configured in the settings (default 11053).<br>
You can use [this documentation](https://www.v2ray.com/en/configuration/dns.html) from V2Ray to see how you have to configure it.<br><br>
After configuring both apps simply start them and the query count in Nebulos notification should increase.
## Battery usage
There shouldn't be any difference in Nebulos battery usage when using non-VPN mode.
If you use third-party apps to forward DNS queries to Nebulo they do use battery though.
## Iptables
As mentioned above you can use iptables on a rooted phone to forward DNS queries to Nebulo in non-VPN mode (iptables mode).<br>
When enabled it creates a few iptable rules when Nebulo is started and removes them when it is stopped.
A notification will appear if anything goes wrong when creating the rules, warning you about it.<br>
### IPv6 support
At this time close to all devices don't have the proper version of ip6tables to allow Nebulo to forward DNS queries with it.<br>
If your device has IPv6 this most likely causes all DNS queries to bypass Nebulo.
This is of course not desired.<br>
To mitigate this problem I suggest to activate the "Disable IPv6" setting in iptables mode.
It prevents _all_ IPv6 connections on Port 53 (IPv6 connectivity is still going to work!).
This forces Android to fallback to IPv4, where Nebulo is going to receive the queries.
### Checking support
It is recommended to check for iptables support before enabling the iptables mode.
To do that click on the "Check for iptables" entry.<br>
It will tell you whether your device supports iptables, iptables for IPv4 only or doesn't support iptables at all.
### Rules used
The rules Nebulo uses in iptables mode:
- Creating redirect for IPv4: `iptables -t nat -I OUTPUT -p udp --dport 53 -j DNAT --to-destination 127.0.0.1:<port>"` and `iptables -t nat -I OUTPUT -p tcp --dport 53 -j DNAT --to-destination 127.0.0.1:<port>"`
- Creating redirect for IPv6: `ip6tables -t nat -I PREROUTING -p udp --dport 53 -j DNAT --to-destination [::1]:<port>"` and `ip6tables -t nat -I PREROUTING -p tcp --dport 53 -j DNAT --to-destination [::1]:<port>"` (As mentioned most devices don't support this command)
- Disabling IPv6 for Port 53: `ip6tables -A OUTPUT -p udp --destination-port 53 -j DROP` and `ip6tables -A OUTPUT -p tcp --destination-port 53 -j DROP`
- Removing redirect for IPv4: `iptables -t nat -D OUTPUT -p udp --dport 53 -j DNAT --to-destination <ip>:<port>"` and `iptables -t nat -D OUTPUT -p tcp --dport 53 -j DNAT --to-destination <ip>:<port>"`
- Removing redirect for IPv6: `ip6tables -t nat -D PREROUTING -p udp --dport 53 -j DNAT --to-destination [::1]:<port>` and `ip6tables -t nat -D PREROUTING -p tcp --dport 53 -j DNAT --to-destination [::1]:<port>`
- Re-enabling IPv6 for Port 53: `ip6tables -D OUTPUT -p udp --destination-port 53 -j DROP` and `ip6tables -D OUTPUT -p tcp --destination-port 53 -j DROP`
### iptables cleanup
As mentioned Nebulo automatically cleans up after itself, removing the iptables rules it created.<br>
If Nebulo is force-stopped (either by you or by the system) it isn't able to cleanup after itself.
This causes the rules to remain and because Nebulo doesn't host the DNS server anymore will cause you to not have any connection.<br>
To remove the rules simply open Nebulo again (you don't have to start it, opening the app is enough).
It detects that the rules were not properly removed and will delete them.
\ No newline at end of file
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment