path: root/guides/setups/operating-systems/debian.org

* Installation
** Step-by-step recap (Bullseye)
*** Setup keyboard
Turn CapsLock key into Control (cf. keyboard(5)):
- add =ctrl:nocaps= to =XKBOPTIONS= in =/etc/default/keyboard=
- run =udevadm trigger --subsystem-match=input --action=change=
- run =setupcon= in a TTY
*** Install stuff
**** Distro-provided packages
#+begin_src sh
packages=(
    # To clone & update dotfiles.
    git
    # Look & feel.
    elementary-xfce-icon-theme greybird-gtk-theme
    # Enable volume management with Thunar.
    gvfs-backends gvfs-fuse
    # System monitoring.
    htop powertop wavemon
    # Documentation:
    # - info pages,
    gcc-doc make-doc tar-doc info
    # - manpages,
    manpages-dev manpages-posix manpages-posix-dev
    # - text & HTML pages.
    git-doc python3-doc
    # Writing helpers.
    aspell-fr verbiste wordnet
    # CLI helpers.
    mlocate ripgrep vim
    # Fonts.
    fonts-noto-color-emoji
    # Miscellaneous applications.
    ffmpeg gimp pandoc terminator vlc
)
sudo apt install ${packages[@]}
#+end_src
**** Latest and greatest
***** Firefox
- download most recent release from from <https://www.mozilla.org>
- unpack it =$SOMEWHERE=
- make sure everyone can find it:

#+begin_src sh
$ sudo update-alternatives --install $(which x-www-browser) x-www-browser \
                           ${SOMEWHERE}/firefox/firefox 1
$ sudo update-alternatives --set x-www-browser ${SOMEWHERE}/firefox/firefox
$ ln -s ${SOMEWHERE}/firefox/firefox ~/.local/bin/
#+end_src

- paste backuped profile into =~/.mozilla/firefox/${profile}=
***** Symbola
- grab the archive from <http://users.teilar.gr/~g1951d/>
- drop the TTF files in =~/.local/share/fonts=
- run =fc-cache -fv=
***** youtube-dl
#+begin_src sh
$ sudo apt install python3-pip
$ pip3 install --user youtube-dl
#+end_src
*** Setup dotfiles
**** Clone versioned dotfiles
- create new SSH key for GitLab
- follow instructions in dotfiles README
**** Tweak non-versioned dotfiles
- set EMAIL in =.profile=
- add =~/.local/bin= to PATH
- copy =.profile= to =.xsessionrc=
- in =.bashrc=
  - enable globstar and autocd
  - uncomment grep and ls aliases
  - source =~/.bash_prompt=
*** Setup Emacs
- clone from Savannah
- =apt build-dep emacs=
- =apt install libgconf2-dev libwebkit2gtk-4.0-dev=
  (optional build dependencies for ≥27)
- comment out .emacs below =(load custom-file)=
#+begin_src elisp
(package-refresh-contents)
(package-install-selected-packages)
#+end_src
*** Setup XFCE
**** Appearance
***** Style
Greybird-dark
***** Icons
elementary Xfce darker
***** Fonts
- Rendering
  - [X] Enable anti-aliasing
  - Hinting: Slight
  - Sub-pixel order: RGB (trusting the [[http://www.lagom.nl/lcd-test/subpixel.php][Lagom LCD test pages]])
**** File Manager
***** View
- Side Pane: Tree
- View as Detailed List
**** Panel
***** Top panel
****** Items
******* Whisker Menu
******* Window Buttons
******* Separator
******* Workspace Switcher
******* Separator
******* Status Tray Plugin
******* PulseAudio Plugin
******* Power Manager Plugin
- Show label: None
******* Notification Plugin
******* Separator
******* Clock
***** Bottom panel
Delete.
**** Window Manager
***** Keyboard
- Move window to previous workspace: Shift+Super+Left
- Move window to next workspace: Shift+Super+Right
- Tile window to the left: Super+Left
- Tile window to the right: Super+Right
- Show desktop: Super+D
**** Window Manager Tweaks
***** Accessibility
- [X] Hide title of windows when maximized
***** Compositor
- [ ] Show shadows under…
**** Terminal
***** General
- Scrolling
  - [ ] Scroll on output
  - Scrollbar is: Disabled
  - [X] Unlimited scrollback
***** Appearance
- Font
  - [X] Use system font
- Opening New Windows
  - [ ] Display menubar in new windows
***** Advanced
- Shortcuts
  - [X] Disable all menu access keys (such as Alt+f) /for readline/
  - [X] Disable menu shortcut key (F10 by default) /for htop &
        wavemon/
  - [X] Disable help window shortcut key (F1 by default) /for htop &
        wavemon/
- Misc
  - [X] Automatically copy selection to clipboard
**** Keyboard
***** Application shortcuts
- emacs: Super+E
- exo-open --launch FileManager: Super+F
- exo-open --launch TerminalEmulator: Super+T
- exo-open --launch WebBrowser: Super+W
- xfce4-popup-whiskermenu: Alt+F1
- xfce4-screenshooter: Print
- xfce4-screenshooter --fullscreen: Shift+Print
- xfce4-screenshooter --region: Control+Print
- xfce4-screenshooter --window: Super+Print
- xfce4-session-logout: Super+X
- xflock4: Super+L
**** Mouse and Touchpad
***** Devices
- =… Touchpad=
  - Touchpad
    - [X] Tap touchpad to click
**** Power Manager
***** System
- On battery / Plugged in
  - When laptop lid is closed: Suspend
**** Removable Drives and Media
***** Storage
- [X] Mount removable drives when hot-plugged
- [X] Mount removable media when inserted

*** Setup more stuff
**** lightdm
Show my account on startup:
#+begin_src conf
# /usr/share/lightdm/lightdm.conf.d/99_custom.conf
[Seat:*]
greeter-hide-users=false
#+end_src
**** system groups
#+begin_src sh
groups=(
    adm         # Access /var/log journals.
    dialout     # Sync my phone.
)
for g in ${groups[@]}
do
    sudo adduser ${USER} ${g}
done
#+end_src
** Live reactions
*** Samsung NC10 (Buster)
**** installer
Touchpad is not recognized, for some reason.
**** first boot
#+BEGIN_QUOTE
A start job is running for Load AppArmor profiles
#+END_QUOTE
Disappeared after ≈30s 🤷

Wooh touchpad works!  Although the sensitivity is a bit low.
*NB: solved below.*

Wifi LED is on, whatever that means.

Brightness function keys do not work on the login screen.

Using default XFCE config to get four workspaces.

Brightness and sound function keys work! 🙌

Touchpad click and scroll do not work.
*NB: solved below.*

Wifi function key does not work.

Battery life seems somewhat shorter than with Bunsenlabs, even after
applying all powertop tricks in the book.
**** apt install (1/n)
git greybird-gtk-theme elementary-xfce-icon-theme emacs

git suggests git-doc: why of course, good idea!

emacs suggests emacs-common-non-dfsg: right, what was that again?
Documentation, IIRC?  What does APT have to say?

#+BEGIN_EXAMPLE
$ apt show emacs-common-non-dfsg
Package: emacs-common-non-dfsg
State: not a real package (virtual)
N: Can't select candidate version from package emacs-common-non-dfsg as it has no candidate
N: Can't select versions from package 'emacs-common-non-dfsg' as it is purely virtual
N: No packages found
#+END_EXAMPLE

… What does https://packages.debian.org/emacs-common-non-dfsg say?

#+BEGIN_QUOTE
*[non-free]*
#+END_QUOTE

[[https://www.debian.org/vote/2006/vote_001][Oh.]]  Well then,

#+begin_src sh
$ sudo sed -ri 's/^([^#].+ main)$/\1 contrib non-free/' /etc/apt/sources.list
$ # While in there…
$ sudo sed -ri 's/^(deb|deb-src) http:/\1 https:/' /etc/apt/sources.list
#+end_src

What now?

#+BEGIN_EXAMPLE
$ sudo apt update
[…]
Err:4 https://security.debian.org/debian-security buster/updates Release
  Certificate verification failed: The certificate is NOT trusted. The certificate issuer is unknown. The name in the certificate does not match the expected.  Could not handshake: Error in the certificate verification. [IP: 217.196.149.233 443]
[…]
E: The repository 'https://security.debian.org/debian-security buster/updates Release' no longer has a Release file.
N: Updating from such a repository can't be done securely, and is therefore disabled by default.
N: See apt-secure(8) manpage for repository creation and user configuration details.
#+END_EXAMPLE

🤨

#+begin_src sh
$ sudo sed -ri 's/security\.debian\.org/deb.debian.org/' /etc/apt/sources.list
#+end_src

[[https://wiki.debian.org/SourcesList#Example_sources.list][🤷]]

**** tweak dotfiles
Set EMAIL in .profile; copy .profile to .xsessionrc (AFAICT XFCE does
not read ~/.config/environment.d) to get PATHs.

In .bashrc, enable globstar and autocd, uncomment grep and ls aliases,
source personal .bash_prompt.

Fun fact!  git can guess user.email from $EMAIL and user.name from the
[[https://en.wikipedia.org/wiki/Gecos_field][GECOS field]].
**** apt install (2/n)
#+BEGIN_QUOTE
E: Package 'gcc-doc' has no installation candidate
#+END_QUOTE
gcc-doc is only available in /backports/?
**** configure XFCE
***** Mouse and Touchpad
- Move sliders a bit to no avail, restore defaults.
- Google around.
- Why do my XFCE settings not have this "Touchpad" tab?
- apt install xserver-xorg-input-synaptics
- Log out and in again.
- Woah the pointer is much faster now.
- And the "Touchpad" tab is here now!
🎉
***** Panels
Remove bottom panel: I'd rather remember a few Super-… shortcuts to
launch these applications rather than waste all this vertical space.
***** Appearance
****** Style
Greybird

Patch the xfwm-tabwin style to prevent the mouse from screwing with
Alt-Tab:

#+begin_src diff
diff -u /usr/share/themes/Greybird/gtk-2.0/gtkrc.bkp /usr/share/themes/Greybird/gtk-2.0/gtkrc
--- /usr/share/themes/Greybird/gtk-2.0/gtkrc.bkp
+++ /usr/share/themes/Greybird/gtk-2.0/gtkrc
@@ -897,8 +897,8 @@
 
 	bg[NORMAL]	= shade (0.15, @text_color)
 	bg[ACTIVE]	= shade (0.65, @selected_bg_color)
-	bg[PRELIGHT]	= shade (0.75, @selected_bg_color)
-	bg[SELECTED]	= shade (0.55, @bg_color)
+	bg[PRELIGHT]	= shade (0.55, @bg_color)
+	bg[SELECTED]	= shade (0.75, @selected_bg_color)
 
 	fg[NORMAL]	= shade (0.8, @base_color)
 	fg[ACTIVE]	= @base_color
#+end_src
**** configure more stuff
***** lightdm
Debian [[https://wiki.debian.org/LightDM#Enable_user_list][hides the list of users]] on the login screen; Bunsenlabs [[https://github.com/BunsenLabs/bunsen-configs/blob/9.6-1/lightdm.conf.d/50_bunsen.conf][enables
it]] and I kind of like it (fewer keystrokes, and a cute avatar).
*** Dell 3190 (Buster)
**** groundwork
Using instructions from <https://wiki.debian.org/Firmware>.
***** Get netinst image from <https://www.debian.org/CD/netinst/>
***** Get firmware archive from <https://cdimage.debian.org/cdimage/unofficial/non-free/firmware/stable/current/>
So that the installer can use the wireless network card.  Extract all
.deb files to a top-level =firmware= folder on a USB key.
***** Shrink the MS partition
Had to "optimize the disk", otherwise some free space remained
unavailable.
**** installer
Everything went smoothly:
- if the USB key holding the firmware isn't plugged in, the installer
  requests it, otherwise it finds the firmware automatically;
- Secure Boot supported transparently;
- dual-booting too.
**** package repositories
Non-free repositories automatically added during the installation,
because of the WiFi firmware I presume.
**** kernel issues
***** i915/glk_dmc_ver1_04.bin
kern.log:
#+begin_quote
i915 0000:00:02.0: firmware: failed to load i915/glk_dmc_ver1_04.bin (-2)
#+end_quote
apt install firmware-misc-nonfree seems to quiet that down.
***** i2c_hid_get_input: incomplete report
kern.log:
#+begin_quote
i2c_hid i2c-MSFT0001:00: i2c_hid_get_input: incomplete report (14/65535)
#+end_quote
About one message for every half-second spent touching the touchpad.

"Solved" with:
#+begin_src sh
$ apt install -t buster-backports \
      linux-image-amd64           \
      firmware-iwlwifi            \
      firmware-misc-nonfree
#+end_src
* Maintenance
** upgrades
*** Bookworm
**** research
***** [[https://www.debian.org/releases/bookworm/amd64/release-notes/ch-information.en.html#non-free-split][Release notes § Issues to be aware of]]
****** minutiae
- ~sed s/non-free/non-free-firmware/~
- =youtube-dl= ⇒ =yt-dlp=
- clear =GRUB_DISABLE_OS_PROBER=
****** System logs ([[https://www.debian.org/releases/bookworm/amd64/release-notes/ch-information.en.html#changes-to-system-logging][ref]])
1. ~apt-mark auto rsyslog ; apt autoremove~
2. double-check that journalctl config saves to persistent storage
3. finally learn ~journalctl~
****** Reduced accessibility from GTK 3⇒4 transition ([[https://www.debian.org/releases/bookworm/amd64/release-notes/ch-information.en.html#gnome-has-reduced-accessibility-support-for-screen-readers][ref]])
Not a huge deal for me (though [[https://github.com/transmission/transmission/discussions/5065][other aspects]] of the transition are
irksome), but [[https://tech.lgbt/@xogium/110507457689374019][dang]].
****** "Externally-managed" Python installation ([[https://www.debian.org/releases/bookworm/amd64/release-notes/ch-information.en.html#python3-pep-668][ref]])
1. inventory & clear out stuff installed with ~pip install --user~
2. upgrade
3. install =pipx=
4. reinstall
****** VLC support for VA-API disabled ([[https://www.debian.org/releases/bookworm/amd64/release-notes/ch-information.en.html#vlc-ffmpeg-5][ref]])
- [[https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1021601][Debian bug#1021601]] =vlc: VAAPI hardware acceleration no more available=
- [[https://code.videolan.org/videolan/vlc/-/issues/26772][VLC#26772]] =VAAPI is disabled with ffmpeg5 on vlc-3x=
  - "we won't support full FFmpeg5 in 3.0" ([[https://code.videolan.org/videolan/vlc/-/issues/26772#note_316827][ref]])
- [[https://code.videolan.org/videolan/vlc/-/merge_requests/1245][VLC!1245]] =[VLC3] Support FFmpeg 5.0 (except for VAAPI)=
  - "it seems that the VAAPI part is far from trivial and requires
    invasive changes (contrary to the other fixes)" ([[https://code.videolan.org/videolan/vlc/-/merge_requests/1245#note_302474][ref]])
- user reports: [[https://old.reddit.com/r/debian/comments/z5ectb/vlc_delaying_frames_on_a_fresh_debian_12_install/][2022-11]], [[https://old.reddit.com/r/debian/comments/119x7tr/debian_12_bookworm_no_hw_acceleration_in_vlc_h264/][2023-02]]

No idea how much that will affect little =hirondell=.  If push comes
to shove, I guess I can either
- build VLC 4,
- learn mpv.
****** systemd naming for Xen network interfaces ([[https://www.debian.org/releases/bookworm/amd64/release-notes/ch-information.en.html#xen-network][ref]])
=eth0= changes to =enX0=.  No idea if my VPS is impacted or not; it
does have an interface named =eth0=, and that name also shows up in
=/etc/network/interfaces=.
****** Known severe bugs ([[https://www.debian.org/releases/bookworm/amd64/release-notes/ch-information.en.html#rc-bugs][ref]])
- [[https://bugs.debian.org/1036041][bug#1036041]]: =upgrade-reports: Dell XPS 9550 fails to boot after
  bullseye to bookworm upgrade - grub/bios interaction bug?=
** impromptu IBus
Installing [[https://zoom.us/][Zoom]]'s Debian package somehow enabled IBus[fn:: AFAICT
because ibus recommends im-config, and the latter autostarts the
former by default], which unconditionally set my keyboard to English
for some reason[fn:: Before properly running ~apt install
./zoom_amd64.deb~, I had mistakenly run ~dpkg -i zoom_amd64.deb~,
which failed because of missing dependencies.  Perhaps apt omitted
some post-installation configuration hooks because the first dpkg run
had left an error marker somewhere?].  Steps taken:

1. Tweak IBus preferences, unset shortcuts (Emacs has a better
   interface for searching/inserting Unicode characters), check "use
   system defaults" for the keyboard layout.

2. Go on a hunt for whoever spawns ibus-daemon(1); AFAICT it's
   im-launch(1), which can be told not to use IBus through im-config
   (which eventually just writes ~run_im none~ in =~/.xinputrc=).

3. Eventually, maybe I should just uninstall im-config.
** random lag
*** DONE diagnosing
Since… a few days? weeks? one month? everything randomly becomes
"choppy":

- typing (Emacs, Terminator, Firefox): I can type in a bunch of words,
  sit back, wait a few seconds, then watch the words finally write
  themselves letter by letter.
- launching programs: ~while time $aprogram ; do sleep 0.5 ; done~,
  where ~aprogram~ just starts then exits, shows wildly varying times.
- scrolling a PDF with the touchpad (Evince): the pages stay stuck for
  a few seconds, then the reader jumps to the new location; the mouse
  pointer does change during this delay, as text and whitespace
  (invisibly) scroll by.

I can't remember changing anything recently, nor seeing any scary
update passing by.  journalctl, htop and dmesg do not show any obvious
suspects.  Some things I considered:

- Disabling some services e.g. tor or speech-dispatcher ⇒ no effect.
- Uninstalling xserver-xorg-video-intel ⇒ no effect.
- Upgrading systemd from backports ⇒ no effect.
- htop sometimes shows pulseaudio acting up despite no application
  playing or recording sound?
- Maybe I should try reinstalling Debian's stable kernel?
  - Luckily 5.7 was not uninstalled when upgrading to 5.8; booting on
    5.7 solves all of the "choppiness" issues listed above.

Now to pinpoint what's wrong with 5.8…
*** TODO fixing
Found a way to "quantify" the problem; asked around on the
debian-kernel mailing list, to no avail.

- [[https://lists.debian.org/debian-kernel/2020/11/msg00084.html][2020-11]] - original report that 5.8 from backports triggers the
  issue: "wait for 5.9 to be available from backports or even 5.10"
  (LTS for the next Debian stable version)
- [[https://lists.debian.org/debian-kernel/2020/12/msg00040.html][2020-12]] - quick report that 5.9 from backports does not improve
  things: 🦗
- [[https://lists.debian.org/debian-kernel/2021/02/msg00231.html][2021-02]] - quick report that 5.10 from backports does not improve
  things *✨with scripts & numbers✨*: 🦗

#+begin_quote
    for ((i=0; i<100; i++)); do
        time -p terminator -x 'bash -c exit'
    done &> time-$(uname -r)

    grep $mode time-$(uname -r) | sort -k2

Where $mode is either real, user or sys.  Here are the extrema:

                        real            user            sys
                        min     max     min     max     min     max
5.7                     0.44    0.48    0.29    0.35    0.02    0.08
5.10                    0.47    3.30    0.31    2.87    0.02    0.30
5.10-after-suspend      0.46    0.50    0.30    0.36    0.03    0.08

Averages & standard deviations:

                        real            user            sys
5.7                     0.454±0.006     0.322±0.013     0.046±0.013
5.10                    0.961±0.607     0.559±0.518     0.074±0.052
5.10-after-suspend      0.469±0.005     0.332±0.012     0.050±0.011

These results feel consistent with the stutter I observe: 5.7 and
5.10-after-suspend have roughly the same performance, while
freshly-booted 5.10 is overall very jittery: terminator startup is twice
as slow on average, with 100× more variance.


Some more stats, eyeballed from /proc/cpuinfo and
/sys/devices/system/cpu/cpufreq/policy*/scaling_governor:

                        idle frequency  CPU governor
5.7                     <  800 MHz      powersave
5.10                    > 1900 MHz      ondemand
5.10 (after suspend)    <  900 MHz      ondemand
#+end_quote

- [[https://lists.debian.org/debian-kernel/2021/08/msg00278.html][2022-08]] - quick report that 5.10 from a fresh bullseye install does
  not improve things: 🦗
* Someday
** fix xfce4-terminal opening links with firefox-esr
** fix Thunar opening images with Firefox instead of Ristretto
** fix Ristretto thumbnails
** Samsung NC10
*** fix Ethernet after suspend
Workaround:
#+begin_src sh
$ sudo modprobe -r sky2 && sudo modprobe -i sky2
#+end_src
References:
- https://bugs.launchpad.net/ubuntu/+source/linux/+bug/1841304
- https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=895378
- https://bugs.launchpad.net/ubuntu/+source/linux/+bug/1798921
- https://bugs.launchpad.net/ubuntu/+source/linux/+bug/1809843
- https://askubuntu.com/questions/1029620/ubuntu-18-04-lts-sky2-ethernet-stops-working-after-system-resume-from-suspend
- https://bbs.archlinux.org/viewtopic.php?id=234725