wlr-resize-watcher

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

wlr-resize-watcher can automatically adjust the Wayland compositor's screen resolution when the virtual graphics device reports a different native resolution (for example, after changing the VM window size in VirtualBox or KVM). For privacy reasons, dynamic resolution is disabled by default in Whonix-Workstation.

Introduction

wlr-resize-watcher watches for changes to the native display resolution of virtual displays and can updates the screen resolution to match.

Dynamic screen resolution adjustment is disabled by default inside Whonix-Workstation to enhance anonymity and reduce fingerprinting risk. Unusual or frequently changing resolutions can be used as a fingerprinting signal if the VM is compromised or if an application can learn the current resolution. Tor Browser attempts to mitigate some screen-size fingerprinting with letterboxing, but it does not fully remove resolution-based fingerprinting. See also Tor Browser Window Size and Why do I have White Bars around my Tor Browser Content?.

If you prefer usability over the privacy trade-off, you can enable dynamic resolution.

Enabling Dynamic Screen Resolution Adjustment

1 Sysmaint Notice

• A If using user-sysmaint-split: The user must boot into the sysmaint session. For details and instructions on how to do so, see user-sysmaint-split.
• B If using unrestricted admin mode: This sysmaint notice does not apply. Continue with the steps below.

2 Configure dynamic resolution.

A Using System Maintenance Panel

If you want to enable it, open the System Maintenance Panel and click Dynamic Resolution, which will start configure-dynamic-resolution with administrative ("root") rights.

B From the command line.

sudo configure-dynamic-resolution

3 Enable dynamic resolution.

When shown the configuration menu, type 1 and press Enter to select Enable or disable dynamic resolution. Then type true and press Enter to enable dynamic resolution.

4 Exit the configuration editor.

Type 5 and press Enter to select Exit configuration editor.

5 Trigger a resize event such as by maximzing the virtualizer (such as VirtualBox or virt-manager) VM window.

6 Done.

Disabling Dynamic Screen Resolution Adjustment

If you want to disable it again, run the same configuration tool and select the option to disable dynamic resolution.

sudo configure-dynamic-resolution

Alternatively, set enable_dynamic_resolution=false in your user configuration file (see below).

Configuration File Changes

wlr-resize-watcher can also be configured without configure-dynamic-resolution:

Open file /etc/wlr-resize-watcher.d/50_user.conf in an editor with administrative ("root") rights.

1 Select your platform.

Non-Qubes-Whonix

2 Notes.

• Sudoedit guidance: See Open File with Root Rights for details on why using sudoedit improves security and how to use it.
• Editor requirement: Close Featherpad (or the chosen text editor) before running the sudoedit command.

3 Open the file with root rights.

sudoedit /etc/wlr-resize-watcher.d/50_user.conf

Qubes-Whonix

2 Notes.

• Sudoedit guidance: See Open File with Root Rights for details on why using sudoedit improves security and how to use it.
• Editor requirement: Close Featherpad (or the chosen text editor) before running the sudoedit command.
• Template requirement: When using Qubes-Whonix, this must be done inside the Template.

3 Open the file with root rights.

sudoedit /etc/wlr-resize-watcher.d/50_user.conf

4 Notes.

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

Others and Alternatives

2 Notes.

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

3 Open the file with root rights.

sudoedit /etc/wlr-resize-watcher.d/50_user.conf

Configuration File Options

wlr-resize-watcher uses a drop-in configuration folder. Do not edit distribution defaults. Instead, place custom settings in the user override file.

Configuration Overview

Option	Description	Potential Values	Default
enable_dynamic_resolution	Enables or disables automatic resizing to the native resolution.	true or false	false in Whonix-Workstation (overrides the upstream default true)
warn_on_dynamic_resolution_refuse	Shows a one-time warning when a resolution change is detected but dynamic resolution is disabled.	true or false	true
standard_default_resolution	Default resolution used on most hypervisors when automatic resizing is not used.	A resolution string in the form WIDTHxHEIGHT (for example: 1920x1080, 1600x900, 1366x768)	1920x1080
small_default_resolution	Default resolution used on hypervisors known to default to low VRAM (currently affects Xen).	A resolution string in the form WIDTHxHEIGHT (for example: 1024x768, 1280x720)	1024x768
normal_wait_proc_list	Process names to wait for before attempting the first resize in a normal user session.	A list of process names as seen in ps axo comm output. Example: ["pcmanfm-qt"]	["pcmanfm-qt"]
sysmaint_wait_proc_list	Same as normal_wait_proc_list, but for the sysmaint session.	A list of process names as seen in ps axo comm output. Example: []	[]
wait_proc_timeout	Maximum time (in seconds) to wait for required processes.	Integer number of seconds (for example: 0, 5, 10, 30)	10

Additional Information

• Autostart: The autostart entry is located at /etc/xdg/autostart/wlr-resize-watcher.desktop.
• Package source: wlr-resize-watcher is part of Kicksecure vm-config-dist.
• Configuration folder: Configuration drop-ins are stored in /etc/wlr-resize-watcher.d.
• User override file: Place local overrides in /etc/wlr-resize-watcher.d/50_user.conf.
• Configuration tool output: configure-dynamic-resolution writes its configuration to /etc/wlr-resize-watcher.d/45_configure-dynamic-resolution.conf.
• Fallback default resolution: If dynamic resolution is disabled or unsupported, wlr-resize-watcher can set displays to a comfortable default resolution using standard_default_resolution (for most users) or small_default_resolution (for Xen).
• one-time-popup status file location: When file ~/.wlr-resize-watcher_one-time-popup exists, no one-time-popup will be shown. However, a passive popup will still be shown unless disabled in configuration. (See setting warn_on_dynamic_resolution_refuse.)

Troubleshooting

• If no resizing happens after enabling dynamic resolution, try logging out and logging in again (or reboot).
• If you are using an unsupported virtualizer, dynamic resolution may not work. In that case, the default resolution settings may still apply.
• If you keep seeing a warning that resizing is not happening, check that enable_dynamic_resolution is set to true and that warn_on_dynamic_resolution_refuse is enabled only if you want the warning.

Debugging

Run as non-root user such as under account user.

systemctl --no-pager --user status wlr-resize-watcher.service

journalctl --boot --no-pager --user -u wlr-resize-watcher.service

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- 2026 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!