From ba479608f55963a6e69e1b950d473c2c8bc884f7 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Mon, 27 May 2019 17:54:39 -0500 Subject: [PATCH] Move core user docs back to appropriate sections Requested by: https://github.com/QubesOS/qubes-doc/pull/823#issuecomment-496316322 Related to: QubesOS/qubes-issues#4693 --- customization-guides/awesome.md | 187 -------------------------------- customization-guides/i3.md | 90 --------------- customization-guides/kde.md | 88 --------------- 3 files changed, 365 deletions(-) delete mode 100644 customization-guides/awesome.md delete mode 100644 customization-guides/i3.md delete mode 100644 customization-guides/kde.md diff --git a/customization-guides/awesome.md b/customization-guides/awesome.md deleted file mode 100644 index 4f95505..0000000 --- a/customization-guides/awesome.md +++ /dev/null @@ -1,187 +0,0 @@ ---- -layout: doc -title: awesome -permalink: /doc/awesome/ -redirect_from: -- /en/doc/awesome/ -- /doc/awesome/ ---- - -# Using awesome in dom0 - -## Qubes-specific features - -* support for the Qubes OS window colors -* rudimentary support for the Qubes application menu entries following the freedesktop standard -* support for custom filters and menu entries - -## Installation - -awesome can be installed with the standard dom0 installation mechanisms. - - $ sudo qubes-dom0-update awesome - -That's it. After logging out, you can select awesome in the login manager. - -## Development - -To [contribute code](/doc/contributing/) you may clone the awesome repository as follows: - - $ git clone https://github.com/QubesOS/qubes-desktop-linux-awesome - -For build instructions please check the repository _README_. - -The repository attempts to follow the upstream Fedora repository. - -## Common customizations - -This section focuses on Qubes-specific customizations. For generic awesome customizations you might want to have a look at the [awesome website](https://awesomewm.org). - -Customizations for awesome are usually done at `~/.config/awesome/rc.lua`. The default file can be found at `/etc/xdg/awesome/rc.lua`. - -### Application menu - -Starting from Qubes 4.0 application menu entries specific to awesome can be put into `~/.config/awesome/xdg-menu/` following the freedesktop standard. The folder might have to be created. - -### Focus steal hardening - -The default Qubes OS awesome installation comes with the defaults set by the awesome developers for focus changes. Some users may want more tight control over window focus changes - especially since focus changes can have security implications when sensitive data is provided to an incorrect application or even qube. - -#### Definition - -For the below example we'll define _wanted focus changes_ as one of the below: - -* mouse move & click afterwards -* workspace/tag change -* pre-defined key combinations for focus changes (e.g. Mod-j & Mod-k) -* tag assignments and unassignments - -Everything else is considered an unwanted _focus steal_. - -In particular the following events are not meant to cause a focus change: - -* new window created -* a window was closed -* application request -* mouse move without click (sloppy focus) - -For the below example other requests from applications to the window manager are meant to be ignored in general as well, e.g.: -* windows shouldn't be able to maximize themselves without the user giving a respective command to the WM (simple test: Firefox F11 next to another window) -* windows shouldn't be able to change their size themselves -* windows shouldn't be able to modify their borders in any way - -Users may want to adjust their definitions and respective implementations according to their needs. - -#### Implementation - -The implementation may be specific to the awesome version you're running. This guide refers to awesome version 3.5.9 which is available to Qubes 4.0 users. - -Please keep in mind that this guide may not be conclusive. Your mileage may vary. - -##### Change the autofocus implementation - -The line `require("awful.autofocus")` in your _rc.lua_ implements various focus-related features for your awesome instance. - -In order to customise these, you can copy the file `/usr/share/awesome/lib/awful/autofocus.lua` to e.g. `~/.config/awesome/autofocus_custom.lua` and replace the line above with `require("autofocus_custom")`. - -Then you can customise the focus behavior. According to our above definitions it would look as follows: - -```lua ----autofocus_custom.lua -local client = client -local screen = screen -local aclient = require("awful.client") -local atag = require("awful.tag") - ---- When loaded, this module makes sure that there's always a client that will have focus --- on events such as tag switching, client unmanaging, etc. --- awful.autofocus - --- Give focus when clients appear/disappear and no one else has focus. --- @param obj An object that should have a .screen property. -function check_focus(obj) - -- When no visible client has the focus... - if not client.focus or not client.focus:isvisible() then - local c = aclient.focus.history.get(obj.screen, 0) - if c then client.focus = c end - end -end - --- Give focus on tag selection change. --- @param tag A tag object -function check_focus_tag(t) - local s = atag.getscreen(t) - if not s then return end - check_focus({ screen = s }) - if client.focus and client.focus.screen ~= s then - local c = aclient.focus.history.get(s, 0) - if c then client.focus = c end - end -end - ---made above functions global & removed some focus switches below (user interaction required instead) - ---clear any focus -function clear_focus() - --unfortunately this doesn't work at the moment - --cf. https://github.com/awesomeWM/awesome/issues/164 - --(Qubes uses an older awesome version that doesn't have the fix yet) - --client.focus = nil -end - -atag.attached_connect_signal(nil, "property::selected", check_focus_tag) -client.connect_signal("unmanage", clear_focus) -client.connect_signal("tagged", check_focus) -client.connect_signal("untagged", check_focus) -client.connect_signal("property::hidden", clear_focus) -client.connect_signal("property::minimized", clear_focus) -``` - -##### Remove unwanted focus changing key bindings - -The mouse bindings - -```lua -awful.button({ }, 4, awful.tag.viewnext), -awful.button({ }, 5, awful.tag.viewprev) -``` - -in the default _rc.lua_ may cause tag and thus focus changes without keyboard interaction and tend to happen accidentally. This doesn't suit our definition from above and should therefore be removed or commented out. - -##### Adjust client rules - -The default client rule allows certain focus changes via `focus = awful.client.focus.filter`. These changes can be prevented entirely by setting `focus = false`. - -Alternatively users may provide their own focus filter functions. - -##### Disable sloppy focus - -In your _rc.lua_ you'll find a section such as - -```lua - -- Enable sloppy focus - c:connect_signal("mouse::enter", function(c) - if awful.layout.get(c.screen) ~= awful.layout.suit.magnifier - and awful.client.focus.filter(c) then - client.focus = c - end - end) -``` - -These enable _sloppy focus_ aka focus changes on mouse movements (without clicking) and should be removed or commented out to disable that behaviour. - -##### Ignore requests from applications to the window manager - -Handling of such requests is currently mostly implemented by awesome in the file `/usr/share/awesome/lib/awful/ewmh.lua`. You can either comment out the respective `client.connect_singal()` lines in that file (it will change back after each awesome update though) or disconnect the signals in your _rc.lua_. - -As of awesome 3.5.9 this however is apparently only possible for signals connected to global functions, i.e. currently only the below signals can be disconnected in the _rc.lua_: - -```lua -local ewmh = require("awful.ewmh") - -client.disconnect_signal("request::activate", ewmh.activate) -client.disconnect_signal("request::tag", ewmh.tag) -``` - -The signal names may change across awesome versions. - diff --git a/customization-guides/i3.md b/customization-guides/i3.md deleted file mode 100644 index a8de3b6..0000000 --- a/customization-guides/i3.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -layout: doc -title: i3 -permalink: /doc/i3/ -redirect_from: -- /en/doc/i3/ -- /doc/i3/ -- "/doc/UserDoc/i3/" -- "/wiki/UserDoc/i3/" ---- - -# i3 installation in dom0 - -i3 is part of the stable repository (as of Qubes R3.1) and can be installed by -using the [dom0 update mechanism](/doc/software-update-dom0/). To install the i3 -window manager and the its Qubes specific configuration: - - $ sudo qubes-dom0-update i3 i3-settings-qubes - -The Qubes-specific configuration (package `i3-settings-qubes`) can be installed -optionally in case you would prefer writing your own configuration (see -[customization](#customization) section for scripts and configuration). - -That's it. After logging out, you can select i3 in the login manager. - -### Customization - -* [xdg_autostart_script](https://gist.github.com/SietsevanderMolen/7b4cc32ce7b4884513b0a639540e454f) -* [i3bar_script](https://gist.github.com/SietsevanderMolen/e7f594f209dfaa3596907e427b657e30) -* [terminal_start_script](https://gist.github.com/SietsevanderMolen/7c6f2b5773dbc0c08e1509e49abd1e96) -* [i3 config with dmenu-i3-window-jumper](https://github.com/anadahz/qubes-i3-config/blob/master/config) - -## Compilation and installation from source - -Note that the compilation from source is done in a Fedora based domU (could -be dispvm). The end result is always an `.rpm` that is copied to dom0 and then -installed through the package manager. - -### Getting the code - -Clone the i3-qubes repository here: - - $ git clone https://github.com/QubesOS/qubes-desktop-linux-i3 - -In this case, the most interesting file is probably -`i3/0001-Show-qubes-domain-in-non-optional-colored-borders.patch` It's the patch -with changes that are necessary to make i3 work nicely with Qubes OS. The code -should not need much explanation, it just gets the vmname and label from Qubes -OS and changes some defaults so the user can't override decisions. - -If you want to make any changes to the package, this is the time and place to do -it. - -### Building - -You'll need to install the build dependencies, which are listed in -build-deps.list. You can verify them and then install them with: - - $ sudo dnf install -y $(cat build-deps.list) - -This used to be more complicated, but I finally redid this and use the same -buildsystem that's used by Qubes OS for XFCE. It's just a Makefile that helps -you get the sources and start off the build: - - $ make rpms - -### Installing - -**Warning**: Manually installing software in dom0 is inherently risky, and the method described here circumvents the usual security mechanisms of qubes-dom0-update. - -You should now have your i3 rpm in `./rpm/x86_64/i3-4.8-3.fc20.x86_64.rpm`. -Protip: copying this file to `~/i3.rpm` now will save you some typing in the -next step. - -Now in dom0, copy in the rpm: - - $ qvm-run --pass-io 'cat ' > i3.rpm - -Now that the rpm is in dom0 we can proceed with installing it. i3 has some -dependencies that we can easily install with: - - $ sudo qubes-dom0-update perl-AnyEvent-I3 xorg-x11-apps \\ - rxvt-unicode xcb-util-wm perl-JSON-XS xcb-util-cursor \\ - dzen2 dmenu xorg-x11-fonts-misc libev - -After that you can just install the generated rpm like any other local package: - - $ sudo yum localinstall i3.rpm - -Log out, select i3, then log in again. diff --git a/customization-guides/kde.md b/customization-guides/kde.md deleted file mode 100644 index bdc5492..0000000 --- a/customization-guides/kde.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -layout: doc -title: KDE -permalink: /doc/kde/ -redirect_from: /en/doc/kde/ ---- - -Using KDE in dom0 -================= - -Installation ------------- - -Prior to R3.2, KDE was the default desktop environment in Qubes. Beginning with -R3.2, however, [XFCE is the new default desktop environment](/doc/releases/3.2/release-notes/). Nonetheless, it is -still possible to install KDE by issuing this command in dom0: - - $ sudo qubes-dom0-update @kde-desktop-qubes - -You can also change your default login manager (lightdm) to the new KDE default: sddm - - * first you need to edit the `/etc/sddm.conf` to make sure if the custom X parameter is set according to Qubes needs: - -~~~ - [XDisplay] - ServerArguments=-nolisten tcp -background none -~~~ - - * disable the lightdm service: - -~~~ - $ sudo systemctl disable lightdm -~~~ - - * enable the sddm service: - -~~~ - $ sudo systemctl enable sddm -~~~ - - * reboot - -If you encounter performance issues with KDE, try switching back to LightDM. - -Window Management ------------------ - -You can set each window's position and size like this: - -~~~ -Right click title bar --> More actions --> Special window settings... - - Window matching tab - Window class (application): Exact Match: - Window title: Substring Match: - - Size & Position tab - [x] Position: Apply Initially: x,y - [x] Size: Apply Initially: x,y -~~~ - -You can also use `kstart` to control virtual desktop placement like this: - -~~~ - kstart --desktop 3 --windowclass -q --tray -a '' -~~~ - -(Replace "3" with whichever virtual desktop you want the window to be -on.) - -This can be useful for creating a simple shell script which will set up your -workspace the way you like. - -Removal ------------- - -If you decide to remove KDE do **not** use `dnf remove @kde-desktop-qubes`. You will almost certainly break your system. - -The safest way to remove (most of) KDE is: -~~~ -sudo dnf remove kdelibs,plasma-workspace -~~~ - - -Mailing List Threads --------------------- - - * [Nalu's KDE customization thread](https://groups.google.com/d/topic/qubes-users/KhfzF19NG1s/discussion)