# Fedora 34 i3 Spin Guide

i3wm is a Window Manager (WM) an not a Desktop Environment (DE). This makes it different from KDE, Gnome, etc. since the upstream project does not try to provide an all-encompassing unified desktop experience (they are desktop environments that include their own window manager). The most obvious impact of this is that there is no i3 "control panel" or "settings" application to configure the system like there is in most Desktop Environments.

Having said that, there is nothing that can't be configured, if you know how to do it. The solution in most cases is to adjust the configuration directly in linux without using the GUI abstraction that other Desktop Environments add which obfuscate what is actually happening under the hood.

This document is meant to describe the most common configuration issues that users of the Fedora i3 spin would need.

Also note that i3 only runs in the X11 windowing system. Wayland is an alternative to X11, and there is a different project called sway at https://swaywm.org/ which is designed to emulate i3 in Wayland. Sway is advertised as a drop in replacement for i3 in Wayland, however as many of the configuration topics in this document are specific to X11, your mileage may vary with respect to applying them to Sway or Wayland.

## First Steps

It is always a good idea to update the system after a fresh install by running the following command.

sudo dnf update

## Default Editor

The default editor for Fedora is now `nano` (since it is frendlier for people who don't know `vi`). If you prefer `vim` (or `nvim`) first install it, and then remove the "nano-default-editor" package. I prefer `nvim`, so I install the "neovim" package and then symlink `vim` to it.

sudo dnf install -y neovim
sudo ln -s /usr/bin/nvim /usr/local/bin/vim
sudo dnf remove -y nano-default-editor

There is also a "vim-default-editor" package, but it will pull in `vim`, which is not required if you prefer `nvim`. Also, it is not needed since the system seems to fall back to vim by default.

## Installing Software

The Fedora i3 spin does not come with a gui software application for installing software. You can install one if needed, or you can manage software in the terminal using the following methods.

### .RPM Packages

Fedora uses the .rpm package format and `dnf` utility to install packages from the fedora repositories. Here are some useful `dnf` commands:

- `dnf search <phrase>`: search available package names and descriptions and list the packages where <phrase> is found

- `sudo dnf install <pkg>`: install package <pkg>

- `sudo dnf remove <pkg>`: remove package <pkg>

- `dnf provides <cmd>`: search for which package provides command (or file) <cmd>

- `sudo dnf update`: update all installed packages

- `sudo dnf repoquery -l <pkg>`: list the contents of a package

- `sudo dnf repoquery --whatrequires <pkg>`: show which packages require <pkg>

Refer to the dnf manpage (`man dnf`) for additional information (such as alternatives to --whatrequires like --whatdepends).

### Flatpaks

Fedora also comes with the [`flatpak`](https://docs.flatpak.org/en/latest/introduction.html) utility and fedora flatpak repositories configured, which contain flatpaks built from the same manifest that the corresponding .rpm package is built from. Here are some useful `flatpak` commands:

- `flatpak search <phrase>`: search configured repositories for flatpaks with name or description containing <phrase>

- `flatpak install <pkg>`: install flatpak <pkg>

- `flatpak remove <pkg>`: remove flatpak <pkg>

- `flatpak run <pkg>`: run flatpak <pkg>

As an alternative to the [Fedora flatpak repo](https://fedoraproject.org/wiki/Flatpak), you can also use the [flathub repo](https://flatpak.org/setup/Fedora/).

### RPM Fusion

RPM Fusion provides software that the Fedora Project or Red Hat doesn't want to ship (typically due to licensing issues). Some of this software is necessary to get media to play correctly (ie. non-free codecs).

RPM Fusion is a 3rd party repository and not officially endorsed by the Fedora project.

Instructions for installing packages from RPM Fusion (including packages required to play some media correctly) is at [https://rpmfusion.org/Configuration](https://rpmfusion.org/Configuration).

## i3 Spin Orientation

The i3 user's guide is located at [https://i3wm.org/docs/userguide.html](https://i3wm.org/docs/userguide.html), and is concise, extremely well written, and definitely a recommended read.

Additionally, there is an article in Fedora Magazine called [Getting started with the i3 tiling window manager](https://fedoramagazine.org/getting-started-i3-window-manager/) which provides a more streamlined introduction to the basic functionality. I recommend to review it first if you aren't familiar with i3.

This document is not meant to duplicate the material in these references, such as how to add a keybinding to the i3 configuration file or navigate around windows. Instead, this document is focused on configuring your overall linux system to provide an optimized desktop environment with i3 to meet your needs.

### Configuration

When you boot into the i3 spin, you will be presented with a login screen. This login screen is provided by the LightDM Display Manager, which is the default for Fedora and not specific to the i3 spin.

Once you login LightDM will start i3 which will look for a configuration file at '~/.config/i3/config'. Since this file does not exist the first time you log in, you will be prompted to create it.

The most basic configuration option for i3 is which key to use as the "modifier". The default options are either the <alt> or <windows> key and you would typically select whichever one is directly on the left of the space bar on the keyboard you are using for easy access. This will be the modifier key typically used in combination with other keys to navigate and control i3 instead of the underlying focused application.

Although it is possible for i3 to intercept key combinations that don't include the modifier key (such as intercepting the volume up/down keys to adjust audio volume) typically you want keybindings to include the modifier key so they don't intercept commands meant to be sent to the underlying focused application.

Refer to the [i3 User’s Guide](https://i3wm.org/docs/userguide.html) to see how to add additional keybindings to i3, as well as execute programs and scripts when i3 starts.

Although you can include commands in the i3 configuration file to adjust things such as the keyboard layout or screen resolution when i3 starts, where possible, it is usually preferable to configure them at a lower level so they are set before i3 starts.

## Display Issues

### Scaling the Display at startup

Things on 4k monitors will be very small by default, so to scale everything by 2x you can create a script that uses the `xrandr` utility, and then configure lightdm (the display manager which shows the login screen) to run the script before it shows the login screen.

In the example below, the monitor to be scaled is 'eDP' (the screen on a macbook pro). To see which monitors are available run the `xrandr` command without any arguments and adjust the value of the --output argument in the script below.

# install xrandr which is used to change display properties
sudo dnf install xrandr

# create a shell script to scale the display
sudo cat > /usr/share/lightdm/display.sh <<EOF
#!/usr/bin/env sh
[ -n "$DISPLAY" ] && /usr/bin/xrandr --output eDP --scale 0.5x0.5
EOF
sudo chmod +x /usr/share/lightdm/display.sh

# configure lightdm to run the shell script before showing the login screen
sudo cat > /etc/lightdm/lightdm.conf.d/50-scale_display.conf <<EOF
[Seat:*]
greeter-setup-script=/usr/share/lightdm/display.sh
EOF

### Scaling the display in a Virtual Machine

It seems that something is missing so that the screen may not always scale to full screen properly when running in a virtual machine, so the method above can be used to get the screen to scale to full screen when running in a virtual machine (ie. with `virt-manager`).

### Scaling the display manually

The `xrandr` utility is a command line utility and useful for configuration scripts. In order to adjust monitors interactively, such as when connecting to a projector or external monitor, you can install and use the `arandr` display configuration gui program.

sudo dnf install arandr

### Compositor

The i3 window manager is a "tiling window manager" meaning that windows typically don't overlap (on purpose). But you may have seen other desktop environments where perhaps the background of a terminal window was semi-transparent so you could see what was on the screen behind the window. This functionality to "merge" or "blend" two overlapping windows in not built into the X11 system, but is instead provided by a "compositor".

A common example where this is relevant when using i3 is when sharing your screen using the "MS Teams" collaboration application. Specifically, the MS Teams application draws a window with a red border (to show what is being shared) and a translucent background (to allow you to see the content behind that is being shared). But without a compositor, the X11 system only shows a red border around a black background (because the X11 system does not allow transparent windows without a compositor).

To solve this issue, install the compositor `picom` (`sudo dnf install picom`), and add the following to your '~/.config/i3/config' file so it starts automatically when i3 starts:

exec --no-startup-id picom

In the specific case noted above, an alternative solution is to [disable the red border](https://docs.microsoft.com/en-us/answers/questions/42095/sharing-screen-not-working-anymore-bug.html), but the explanation above is provided in case you find any other situations where you determine you need a compositor.

## Session Management

Session management refers to an individual user session with a lifecycle starting when the user logs in and ending when the user logs out (or is logged out by reboot or poweroff).

The i3 spin uses the LightDM display manager which is the default for all Fedora spins and is responsible for displaying the login page and then starting i3 after the user is authenticated. Specifically, the login screen that you see when the computer boots up IS NOT i3, it is LightDM. Once you enter a valid username and password LightDM will start i3.

LightDM will start automatically when the computer is booted, and it will be shown when a user logs out.

The following lists methods for manipulating the user session while logged in. These are the command line methods which can either be typed into a terminal, or added to keybindings in the '~/.config/i3/config' file.

- Logout:

- key combination <$mod+Shift+e> (i3 default)

- `i3-msg exit`

- Suspend

- `loginctl suspend`
- Hibernate (not available by default in Fedora due to security concern)

- Reboot

- `loginctl reboot` or `reboot`
- Poweroff

- `loginctl poweroff` or `poweroff`
- Lock

- `loginctl lock-session`
- Session Switching

- `dm-tool switch-to-greeter`

### Session Lock

The `loginctl lock-session` command above is part of systemd, and doesn't actually do anything by itself other than to send a signal that the session should be locked, so something needs to listen for that signal and actually lock the screen.

The default i3 config file includes a line that runs the `xss-lock` program when i3 starts which listens for the signal to lock the session, and then start the `i3lock` program which is a screen lock program provided by the upstream i3 project.

The shell snippet below will install the `xss-lock` utility, and also add a keybinding to the i3 config so you can lock the session manually.

sudo dnf install xss-lock
echo 'bindsym $mod+Shift+p exec --no-startup-id loginctl lock-session' >> ~/.config/i3/config

## Terminal

The default i3 config file includes the <$mod+Enter> keybinding to open a new terminal. The `man i3-sensible-terminal` command describes how it works out which terminal emulator to open if you have more than one on your system.

Having said that, if you want to use a different terminal than the one the `i3-sensible-terminal` command opens, the easiest thing is to replace the `i3-sensible-terminal` command in your i3 config file to open whatever terminal emulator you want.

Some terminal emulators that the members of the i3 SIG have suggested are:

- `xfce4-terminal`

- `st` (usually with `tmux` to provide scrollback capabilities)

- `alacritty`

## Application Launcher

The default i3 config uses the `dmenu` program as an application launcher bound to the <$mod+d> key which appears at the top of the screen and shows every executable in your \$PATH.

The [freedesktop](https://www.freedesktop.org/wiki/) project has codified the [Desktop Entry Specification](https://specifications.freedesktop.org/desktop-entry-spec/latest/) which is a standard for applications to define some metadata about themselves in a .desktop file, and typically only applications that have a .desktop file would be shown in the application launcher. The default i3 configuration file includes a commented out keybinding below the `dmenu` keybinding to run the `i3-dmenu-desktop` program instead of `dmenu` which will only show applications with a .desktop file instead of all executables in your \$PATH.

Comments in the default i3 config file also note that `rofi` is a more modern replacement for `dmenu`.

To use `rofi` instead of `dmenu` you must install it with the `sudo dnf install rofi` command, and then comment the `dmenu` line in the i3 config and uncomment the `rofi` command.

`rofi` is very configurable and as an example of how to include all the ssh entries from your '~/.ssh/config' file along with all applications that have a .desktop file you could change the keybinding to 'bindsym $mod+d exec "rofi -show combi"' and then save the following snippet to '~/.config/rofi/config.rasi'.

configuration {
    modi: "combi";
    terminal: "xfce4-terminal";
    ssh-command: "{terminal} -e '{ssh-client} {host} [-p {port}]'";
    combi-modi: "drun,ssh";
}

With this configuration, when you press the <$mod+d> key rofi will appear with a list of all desktop programs and ssh hosts configured in your '~/.ssh/config' file and when you select a ssh host a new `xfce4-terminal` will open and connect.

This is just and example of what `rofi` can do. See `man rofi` for more details.

## Input Device Configuration

### Mouse/Trackpad

To configure a trackpad, save the following snippet at '/etc/X11/xorg.conf.d/40-trackpad.conf' and adjust the options as required. Restart X11 for changes to take effect.

Section "InputClass"
    Identifier "touchpad"
    Driver "libinput"
    MatchIsTouchpad "on"
    Option "Tapping" "True"
    Option "TappingDrag" "True"
    Option "NaturalScrolling" "True"
EndSection

Additional information about configuring libinput is at [libinput - ArchWiki](https://wiki.archlinux.org/title/Libinput).

### Keyboard

To temporarily change the keyboard layout use the `setxkbmap` command. For example, to use the US layout with the Dvorak programmer variant:

setxkbmap us dvp

To toggle between multiple layouts/variants, list them with commas, and include one of the "grp:*_toggle" options (use `localectl list-x11-keymap-options | grep 'grp:.*_toggle'` to see available options) to determine which keys are used to toggle between the layouts/variants. The following will configure the keyboard to switch between US Dvorak layout and US QWERTY layout by pressing both shift keys at the same time.

setxkbmap us,us dvp, grp:shifts_toggle

To configure the keyboard layout permanently, use the `localectl` command, and then restart the x server. For example, to make the changes above permanent use:

sudo localectl set-x11-keymap us,us "" dvp, grp:shifts_toggle

The command above will modify the '/etc/X11/xorg.conf.d/00-keyboard.conf' and adjust the options as required. The command above will result in the following file.

Section "InputClass"
    Identifier "system-keyboard"
    MatchIsKeyboard "on"
    Option "XkbLayout" "us,us"
    Option "XkbVariant" "dvp,"
    Option "XkbOptions" "grp:shifts_toggle"
EndSection

The benefit of setting the keyboard layout this way instead of in the i3 config file is that it will be set before i3 is launched (ie. at the login screen). You can also edit this file directly, and then restart X11.

### Power Button/Lid Switch

On my macbook pro the power button powers down the laptop without any delay, and I accidentally press it too often.

To make the power button suspend the computer (which is much safer) instead of powering it off, write the following to '/etc/systemd/logind.conf.d/10-power.conf', and then run `systemctl restart systemd-logind.service`.

[Login]
HandlePowerKey=suspend

This method may also be used to choose what to do when the lid is closed. See `man logind.conf` for details.

## Printing

To configure printing use the `system-config-printer` utility.

## Autostarting Applications

Although you can use the i3 config file to autostart applications at login there is a better way to autostart applications that are not specific to i3. If you only use i3 it may not make a difference, but if you have multiple desktop environments installed (such as KDE or Gnome and i3) you can use the freedesktop [autostart directory](https://specifications.freedesktop.org/autostart-spec/0.5/ar01s02.html) so the application will be started regardless of which desktop environment you log into.

i3 does not implement the autostart specification natively, but the [`dex-autostart`](https://faq.i3wm.org/question/2155/how-can-i-use-autostart-desktop-files-in-i3.1.html) program can be used instead (ie. `sudo dnf install dex-autostart`).

Add 'exec dex-autostart -ae i3' to '.config/i3/config' to start `dex-autostart` at login.

Either create or symlink an existing [.desktop](https://specifications.freedesktop.org/desktop-entry-spec/latest/) file into your '.config/autostart/' directory.

Although this may seem like a round-about way of doing something that can more easily be done in the i3 config file, installing `dex-autostart` will also autostart things where the package manager has chosen to use autostart files such as volume control widget. But be careful because, for instance, the default i3 config files starts `nm-applet`, but there is also an `nm-applet` autostart file. In cases like these I commented out the line in the i3 config file on the basis of deferring to what the package manager intended.

Typically, '.desktop' files are located in '/usr/share/applications/'.

For flatpak applications the '.desktop' file can be found in '/var/lib/flatpak/exports/share/applications/'.

## "Well Known" User Directories

In order to standardize directories across linux desktop environments, the freedesktop project has defined the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html), and further defined the [xdg-user-dirs](https://freedesktop.org/wiki/Software/xdg-user-dirs/) utility.

Install the "xdg-user-dirs" package, and run the `xdg-user-dirs-update` command from a terminal to create a complete set of "well known" user directories (Desktop, Documents, Downloads, Music, Pictures, Public, Templates, Videos) in your home directory. This command will also create the '~/.config/user-dirs.{dirs,locale} files if they don't exist. The '~/.config/user-dirs.dirs' file is required for Flatpaks to be able to access these directories.

sudo dnf install -y xdg-user-dirs
xdg-user-dirs-update #run as user

## Redshift

There is a package/program called `redshift` which reduces the blue light coming from the monitor at night (ie. make the screen "warmer" to help maintain your sleep schedule); and a related packgae `redshift-gtk` which adds a widget to the status bar to allow you to suspend the blue light reduction for a specified amount of time if desired.

The `redshift` program uses the 'geoclue2' package which provides the approximate location of your computer to clients (in this case `redshift`). Full desktop environments provide a "user agent" which interacts with `geoclue`, but i3 does not, so in order for `redshift` to talk to `geoclue` you need to run the demo agent that comes with the 'geoclue2-demos' package.

After installing the 'redshift-gtk' and 'geoclue2-demos' packages with `sudo dnf install redshift-gtk geoclue2-demos` add the following to your i3 config file to start the agent and redshift when you login:

exec --no-startup-id "/usr/libexec/geoclue-2.0/demos/agent & /usr/bin/redshift-gtk"

## Monitoring

The i3 spin does not include a graphical system analysis tool (although it is easy enough to install one).

Some useful monitoring tools are:

* `nmon`: general system monitor
* `htop`: process monitor
* `netstat`: network monitoring tool
* `iostat`: storage subsystem monitoring tool
* `s-tui`: cpu monitoring tool

## Flatpaks

The '~/.config/user-dirs.dirs' file is necessary for flatpak apps to get access to any of the default directories (read `man xdg-user-dirs-update` if you don't want all of the default directories)

Install the `Flatseal` program to configure flatpak application security.

flatpak install flathub com.github.tchx84.Flatseal

## Screenshots

Install screenshot utility and configure i3 to open it with the print screen button

flatpak install flathub org.flameshot.Flameshot
echo "bindsym Print exec flatpak run org.flameshot.Flameshot" >> ~/.config/i3/config

## Office Suite

Libre Office can be installed as a flatpak

flatpak install flathub org.libreoffice.LibreOffice

## Virtualization

To install `virt-manager` (ie. `libvirt` and `qemu`) install the '@virtualization' package group:

sudo dnf install @virtualization

## Containers

The `systemd-nspawn` and `machinectl` commands are available from the 'systemd-container' package (see [Container technologies in Fedora: systemd-nspawn - Fedora Magazine](https://fedoramagazine.org/container-technologies-fedora-systemd-nspawn/)):

sudo dnf install systemd-container

The `podman` utility is available in the '@container-management' package group:

sudo dnf install @container-management