Whonix-Gateway System DNS

Whonix ®

Download

Windows Linux Mac VirtualBox KVM Qubes Intel / AMD64 ARM64 PPC64 USB ISO Raspberry Pi More options Source Code

About

Overview Features Whonix vs VPNs Why Open Source? Project Activities Contributors Mission & Vision

Docs

Documentation FAQ Troubleshooting

Community

Forums Forum Best Practices Contribute

Support

Self Support First Policy Search Engines, Docs and AI Support (Limited) Reporting Bugs Contact (Restricted)

Tools Upload file Special pages Recent changes Print Version Page meta What links here Related changes Page information

Page Read Edit History Move Protection Unwatch Watch Delete Purge

User Preferences Watchlist Contributions Logout Create account Login

Donate

Information about Whonix-Gateway System DNS, /etc/resolv.conf, and nslookup. Getting System DNS working on Whonix-Gateway.

Introduction

System DNS is defined as:

• Resolving DNS:
  • Without the use of a socksifier such as torsocks,
  • Without application proxy settings,
  • Without a Tor SocksPort.
• Using the standard mechanisms on Linux for DNS resolution.
• Typically configured through the configuration file /etc/resolv.conf.
• The process that occurs when running nslookup.

All traffic originating from Whonix-Workstation^™ and Whonix-Gateway^™ is routed to the Tor software.

For technical details, click on "Learn More" on the right side.

• Traffic from Whonix-Gateway also routed over Tor: Starting from Whonix version 0.2.1, traffic from Whonix-Gateway is also routed over Tor. This approach conceals the use of Whonix from entities monitoring the network.
• Gateway's own traffic not essential for anonymity: To preserve the anonymity of a user's Whonix-Workstation activities, it is not essential to route Whonix-Gateway's own traffic through Tor. (Note: The gateway is mainly a tool that helps route traffic; it does not typically contain personal activity data.)
• DNS configuration on Whonix-Gateway has limited impact: Altering DNS settings on Whonix-Gateway in /etc/resolv.conf only impacts DNS requests made by Whonix-Gateway's applications that utilize the system's default DNS resolver. (DNS is like the internet's phonebook - it translates website names to IP addresses.) By default, no applications on Whonix-Gateway that generate network traffic use this default resolver. All default applications on Whonix-Gateway that produce network traffic (like apt, systemcheck, sdwdate) are explicitly configured, or forced by uwt wrappers, to use their dedicated Tor SocksPort (refer to Stream Isolation).
• Whonix-Workstation DNS requests handled via Tor: Whonix-Workstation's default applications are configured to use dedicated Tor SocksPorts (see Stream Isolation), avoiding the system's default DNS resolver. Any applications in Whonix-Workstation not set up for stream isolation - such as nslookup - will use the default DNS server configured in Whonix-Workstation (through /etc/network/interfaces), which points to Whonix-Gateway. These DNS requests are then redirected to Tor's DnsPort by the Whonix-Gateway firewall. (This ensures DNS lookups still go through Tor even if they use the default method.) Changes in Whonix-Gateway's /etc/resolv.conf do not influence Whonix-Workstation's DNS queries.
• Tor process traffic allowed direct internet access: Traffic produced by the Tor process, which by Debian's default operates under the account debian-tor and originates from Whonix-Gateway, can access the internet directly. This is permitted because the Linux user account debian-tor is exempted in the Whonix-Gateway Firewall and allowed to use the "regular" internet. (This is necessary for Tor to establish its connections.)
• Tor mostly uses TCP traffic: As of Tor version 0.4.5.6 (with no changes announced at the time of writing), the Tor software predominantly relies on TCP traffic. (TCP is a common protocol used for stable internet connections.) For further details, see Tor wiki page, chapter UDP. For DNS, please refer to the next footnote.
• Tor's DNS independence and exceptions: Tor does not depend on, nor use, a functional (system) DNS for most of its operations. IP addresses of Tor directory authorities are hardcoded in the Tor software by Tor developers. (That means Tor knows important addresses in advance and doesn't need to look them up.) Exceptions include:
  • Proxy with domain name: Proxy settings that use proxies with domain names instead of IP addresses.
  • Pluggable transport domain resolution: Some Tor pluggable transports, such as meek lite, which resolve domains set in url= and front= to IP addresses, or snowflake's -front.

Whonix-Workstation^™ is configured to use various SocksPorts, DNSPort, and TransPort. See also Stream Isolation. By default, using system DNS on Whonix-Workstation^™ does not require Whonix-Gateway system DNS. Modifications to /etc/resolv.conf on Whonix-Gateway do not affect Whonix-Workstation.

Whonix-Gateway is only configured to use various SocksPorts. A global system DNS resolver for resolving DNS requests from applications running on Whonix-Gateway isn't necessary for most common use cases, so it isn't enabled by default. Potential use cases where this could be beneficial include:

• Resolving the hostname of a proxy specified in /usr/local/etc/torrc.d/50_user.conf via Tor.
• Resolving the hostname of a VPN. However, a VPN configuration using only IPs would be more suitable.
• One could consider using /etc/hosts for such scenarios instead of enabling system DNS.

Whonix-Gateway Default System DNS Setting

As of this writing, no DNS server is pre-configured.

To verify this, users can run the command below. This command will display all lines in the system DNS configuration file /etc/resolv.conf except those that are commented out (lines starting with a hash ("#")).

cat /etc/resolv.conf | grep --invert-match \#

Modifying this configuration may be safe, beneficial, and necessary for certain use cases such as Bridges, pluggable transports, simplified meek and snowflake support.

Whonix-Gateway System DNS Configuration

Whonix-Gateway System DNS over Clearnet

Setup

Notes:

• This is often unnecessary.
• However, it simplifies the setup when using:
  • Bridges with Snowflake.
  • connect to SSH before Tor (User → SSH → Tor → Internet)

Clearnet Whonix-Gateway System DNS.

1. Apply the following changes to Whonix-Gateway^™.

Open file /etc/resolv.conf.whonix in an editor with root rights.

Select your platform.

Non-Qubes-Whonix

See Open File with Root Rights for detailed instructions on why using sudoedit improves security and how to use it.

Note: Mousepad (or the chosen text editor) must be closed before running the sudoedit command.

sudoedit /etc/resolv.conf.whonix

Qubes-Whonix

Notes:

• When using Qubes-Whonix, this must be done inside the Template.

sudoedit /etc/resolv.conf.whonix

• After applying this change, shut down the Template.
• All App Qubes based on the Template need to be restarted if they were already running.
• This is a general procedure required for Qubes and is unspecific to Qubes-Whonix.

Others and Alternatives

Notes:

• This is just an example. Other tools could achieve the same goal.
• If this example does not work for you, or if you are not using Whonix, please refer to Open File with Root Rights.

sudoedit /etc/resolv.conf.whonix

2. Uncomment the line #nameserver 10.0.2.3.

Remove the hash ("#") before nameserver. This means you should change #nameserver 10.0.2.3 to nameserver 10.0.2.3.

3. Follow platform-specific steps:

• Non-Qubes-Whonix: Done.
• Qubes-Whonix^™: This should typically work. If not, refer to the footnote.

4. Done.

The configuration for Whonix-Gateway System DNS is complete.

5. Note for wiki editors.

Once Whonix 17.2.2.6 or above is released, anon-dns can be used and then the DNS enabling part can be simplified.

Test

Notes:

• If you're using Snowflake, testing this is typically unnecessary.

To test, use the Whonix-Gateway user named clearnet.

Be cautious: When using the clearnet user account, traffic will bypass Tor and use the standard internet, compromising anonymity!

Run bash as user clearnet.

sudo -u clearnet bash

To verify, you can use a tool like dig:

dig +short example.com

Whonix-Gateway System DNS over Tor

This approach is generally not recommended and is often unnecessary.

Torified Whonix-Gateway System DNS.

Undocumented.

Impact of enabling Whonix-Gateway System DNS

What is the impact of enabling Whonix-Gateway System DNS?

• Tor has always had full internet access: Tor running under account debian-tor on Whonix-Gateway has always had full internet access: TCP, UDP, DNS.
• System DNS enables internal DNS resolution: Tor could always have resolved DNS for any internal purpose if it had DNS resolving capability built-in. Enabling system DNS on Whonix-Gateway grants Tor the ability to resolve DNS for any internal purpose.
• Useful in specific scenarios: DNS is usually unnecessary, but in cases like Bridges, it can be useful. For example, domains used by meek such as 1098762253.rsc.cdn77.org or stun.voipgate.com can be resolved by Tor.
• No direct fingerprinting risk: Enabling system DNS on Whonix-Gateway does not directly leak to network observers that a user is using Tor or Whonix. However, this is a complex topic where other factors besides DNS play a role. See Hide Tor and Whonix from your ISP and Fingerprint.
• Disabling DNS does not provide anonymity: Keeping Whonix-Gateway system DNS disabled does not hide the fact that a user is using Tor or Whonix. Same rationale as above.
• Whonix-Workstation unaffected: Whonix-Workstation cannot resolve DNS over clearnet. It still has no method to use clearnet DNS whatsoever.
• Introduction chapter remains valid: Everything stated in Reliable IP Hiding and Introduction still applies. Also refer to the "learn more" button in the introduction chapter.
• Disabled by default for caution: Whonix-Gateway system DNS is disabled by default out of an abundance of caution. There are no practically known risks from enabling it.
• Expected in user systems: This behavior aligns with Tor and Linux distribution specifications, where a functional system DNS is reasonably expected on a typical user system.
• Forum discussion: https://forums.whonix.org/t/censorship-circumvention-tor-pluggable-transports/2601/37

See Also

• Enable Transparent Proxying for Whonix-Gateway own traffic

Footnotes

Whonix The most watertight privacy operating system in the world.

Dark mode

Follow us on social media

Supported by Power Up Privacy

Whonix is proudly supported until 2026 by Power Up Privacy, a privacy advocacy group that seeks to supercharge privacy projects with resources so they can complete their mission of making our world a better place. (Strictly subject to our sponsorship policy.)

At Whonix we value freedom and trust, supporting Open Source and Freedom Software

By using this website, you acknowledge you have read, understood, and agree to be bound by these agreements: Terms of Service, Privacy Policy, Cookie Policy, E-Sign Consent, DMCA, Imprint 2012- 2025 ENCRYPTED SUPPORT LLC

Your support makes
all the difference!

We believe security software like Whonix needs to remain open source and independent. Would you help sustain and grow the project? Learn more about our 13 year success story and maybe DONATE!