Skip to content

5. Troubleshooting

Jump to bottom
D3vil0p3r edited this page Jun 11, 2024 · 51 revisions

Main Athena OS

  • On the customization of shell prompt, in case the machine shows two IP addresses, it can affect negatively the graphics of the prompt. For solving it, the secondary IP address can be removed in the following manner ip -4 addr | grep -v '127.0.0.1' | grep -v 'secondary' | grep -oP '(?<=inet\s)\d+(\.\d+){3}'.

  • In case a script must be run by NetworkManager service at the login of the user, NetworkManager runs as root or nobody, and, on the script, environment variables as $HOME or $USER cannot be recognized because unknown.

  • On WMware, if the screen autosize is not working after a reboot, verify if vmtoolsd.service is running and add the following modules MODULES=(vsock vmw_vsock_vmci_transport vmw_balloon vmw_vmci vmwgfx) to /etc/mkinitcpio.conf and then execute sudo mkinitcpio -P and then reboot.

  • If the user would like to use Alacritty as terminal, amd the mouse pointer disappears across the terminal itself, it means that in /usr/share/icons/default/index.theme is set a non-existing cursor theme. For fixing it, change the cursor theme with the current existing cursor theme, for example:

    [Icon Theme]
Inherits=Breeze_Hacked

  • On Alacritty, the user can run Neofetch only at the startup of the terminal without executing it if you further call BASH or FISH. For doing it, add the following code in alacritty.yaml:

    shell:
  program: /usr/bin/fish
  args:
    - --login
    - --init-command
    - neofetch

  • After the installation of a new Athena version, if the screen freezes after login and need to resize the Virtual Machine window for seeing the update of the desktop, the issue could be in /usr/lib/calamares/modules/displaymanager/main.py that go to write XSession=gnome-xorg string inside /var/lib/AccountsService/users/*username*. This causes freezing because Athena uses Wayland instead of xorg. For solving it, need to change the main.py or dm_main.py file, scroll to the Desktop Environment section and change the variable from gnome-xorg to gnome. Usually, the new versions of Calamares have already this change, so the user can suffer this issue if it takes Calamares from a non-official source.

  • During the installation of Athena OS, if you get the following error:

     Installing for x86_64-efi platform.
Could not prepare Boot variable: No space left on device
grub-install: error: efibootmgr failed to register the boot entry: Input/output error.
WARNING: [PYTHON JOB]: "Command 'grub-install --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id=Athena --force' returned non-zero exit status 1." 
[PYTHON JOB]: "stdout:Installing for x86_64-efi platform.\nCould not prepare Boot variable: No space left on device\ngrub-install: error: efibootmgr failed to register the boot entry: Input/output error."

    install Athena by Manual partitioning.

  • To set a GRUB Theme for Live Environment generated by Archiso, you must not install the related theme package, but in archiso folder, you must store the theme files in archiso/grub/themes/ and edit the file archiso/grub/grub.cfg by changing the theme variable as:

    theme="/boot/grub/themes/<your-theme>/theme.txt"

  • When you create a new ISO and start Calamares, and you get an error like Module cannot be loaded: users@users, probably it is due to a old missing library (you can verify this error by running calamares -D8). Just recompile Calamares in a full updated environment.

  • To correctly synchronize your environment with time clock (in Live Environment or your installed system), you need to start the systemd-timesyncd service. Just note that it conflicts with ntpd service, so if you start the latter, the former will be interrupted. So use just the first one and verify it enables synchronization by running timedatectl. It prevents to have a time clock skew in Live Environment or in your installed system.

  • The update of GRUB by grub-mkconfig -o /boot/grub/grub.cfg must be executed only if a new kernel is installed or removed. It must not be executed by a hook when the kernel is upgraded because it is an useless operation. Source: https://bbs.archlinux.org/viewtopic.php?pid=2131453

  • About mkinitcpio hooks, you can set several hooks according to Arch Wiki. Even if Athena uses systemd as init, you can choose to set BusyBox or systemd hooks according to your needs. Just a warning: in Live ISO mkinitcpio.conf don't set systemd hook because you will get:

    Cannot open access to console, the root account is locked
Press ENTER to continue

    and you cannot boot. Instead, use udev. The installed system is not affected by this issue.

  • In case your are on GDM, and you set Wayland, and when you try to login, it does not and you are back to your user choice, the issue could be related to the fact that the executable /usr/bin/gnome-session cannot find the $SHELL among the shells specified in /etc/shells. If it is true, add the value of $SHELL in /etc/shells and reboot.

  • When you build a project by meson, remember that the file .in must have executable permissions otherwise the created binary by sudo ninja -C build install will not be executable.

  • In case n NVIDIA driver does not work, uninstall the current package, for example nvidia-open-dkms with the related dependencies as the following:

    sudo pacman -R nvidia-open-dkms nvidia-utils nvidia-settings cuda python-py3nvml gwe

    and try to install xf86-video-nouveau and add nouveau module in MODULES= of /etc/mkinitcpio.conf (not sure if removing NVIDIA modules) or try other NVIDIA driver packages.

  • During the ISO creation process, the users in /etc/passwd must be set with BASH shell and not FISH shell otherwise, when the user logs in, all the scripts in /etc/profile.d directory cannot be sourced or parsed because they are written in BASH language. BASH language differs from FISH language. In Athena the change of shells is performed only at the end in the run-once.sh script.

  • After the installation of a GNOME Extension, if the user would like to avoid to reboot the system, it can execute: busctl --user call org.gnome.Shell /org/gnome/Shell org.gnome.Shell Eval s 'Meta.restart("Restarting…")'.

  • If the user is experiencing a logout freezing, inside the Athena Repository, in the module athena-calamares-config/etc/calamares/modules/displaymanager.conf, set GDM as Display Manager if you the user is using it and gnome-wayland as XSession. Avoid to use gnome-xorg otherwise the user will suffer freezing at login when autologin is set.

  • For installing Firefox extension by CLI avoiding to interact with the "Install" popup message of the browser, the user can export $HOME/.mozilla/firefox-esr containing all the preferred extensions from the source machine and import it to the target machine. Do this operation in a fresh environment for avoiding to store user data in the browser.

  • If the Calamares modules don't change according the changes applied in the .conf files, pay attention to the first lines because some of them are pointing to a source not containing the last changes. Just comment the line with this source.

  • If .gresourcefile in /usr/share/gnome-shell can produce issues after a GNOME update (for example Icons in the system tray too big), just recompile it inside an environment with the new version of GNOME. Follow: https://wiki.archlinux.org/title/GDM#Login_screen_background_image. Before compiling, in gnome-shell.css, remember to set the background color as transparent by setting background-color: rgba(0,0,0,0.0); in the Top Bar section. Also find #lockDialogGroup and replace it by:

    #lockDialogGroup {
  background: url(night-city.jpg);
  background-size: cover;
  background-repeat: no-repeat;
}

  • For setting a new mouse pointer theme (i.e., Breeze_Hacked), download and compile it. After the compilation, the resulting files are moved to $HOME/.icons/Breeze_Hacked and, for storing it at the creation of ISO, copy it to airootfs/etc/skel/.icons. For setting it, dconf is needed to set this theme as explained in the related Wiki section. For setting it during the usual system usage, open "Gnome Tweaks" -> "Appareance"

  • After a package installation the user gets some "corrupted" error message, run sudo pacman -Syyu.

  • If the user chooses a different Display Manager for Live Environment instead of GDM, remember to apply this change inside Athena Repository in athena-system-installation/usr/local/bin/athena-displaymanager-check and set the chosen Display Manager as first IF condition above the other ones, otherwise the user choice will be overwritten. Remember also to link the right Display Manager service in /usr/lib/systemd/system to airootfs/etc/systemd/system.

  • During sudo pacman -Syy or similar, if you get an error containing:

    error: GPGME error: No data
error: failed to synchronize all databases (invalid or corrupted database (PGP signature))

    check what is the problematic repository by running sudo pacman -Syyu --debug. For example, if you get an error due to blackarch.db, it could be due to a problematic mirror, indeed, if you edit /etc/pacman.d/blackarch-mirrorlist and delete or comment the line of the problematic mirror, for example http://blackarch.pi3rrot.net/blackarch/$repo/os/$arch, then run sudo pacman -Syyu and it should work.

  • When Calamares Installer is run, if it cannot find a module, verify its presence in /usr/lib/calamares/modules. If it is there, the issue is the absence of a package that is not installed but it was built together Calamares in the source environment. In this case, once the package has been detected, if it is not needed, rebuild Calamares excluding this package by cmake arguments. For example, if the user developer built Calamares in a system with AppStream and it is not excluded by CMake, when the user runs Calamares Installer, it gets a packagechooser@packagechooser not loaded error despite packagechooser module is inside /usr/lib/calamares/modules. If AppStream is needed, the user can install it by sudo pacman -S appstream-qt. If AppStream is not needed, the developer must exclude it from CMake by uninstalling AppStream package before building Calamares or using the following CMake arguments:

    -DWITH_APPSTREAM=OFF -DWITH_APPDATA=OFF

  • During the makepkg -si process for installing a local package in the current system, if the user gets:

    ==> Starting pkgver()...
fatal: not a git repository (or any parent up to mount point /)
Stopping at filesystem boundary (GIT_DISCOVERY_ACROSS_FILESYSTEM not set).
fatal: not a git repository (or any parent up to mount point /)
Stopping at filesystem boundary (GIT_DISCOVERY_ACROSS_FILESYSTEM not set).
==> ERROR: A failure occurred in pkgver().
    Aborting...

    the issue could be related to the absence of the .git directory with its files that are needed for identifying the git version of the package, so execute a git clone <repository-URL>.

  • If on discordo application some fonts are weird, install gnu-free-fonts package package.

  • If Calamares cannot be started because packagechooser or other custom modules try to use an old version of a lib file that does not exist in the system because you have the updated version, and if you recompile Calamares, you are still getting the same error, it could be that you have Calamares custom modules on athena-calamares-config in /usr/lib/calamares/modules and you have .so files that were been generated with missing old version of that lib file. To solve this, instead of copying and pasting the new original packagechooser lib .so file in these modules, you can link them directly to this original file so they will refer directly to the working file.

  • If the user is getting these errors when is building a PKGBUILD: ERROR: ld.so: object 'libfakeroot.so' from LD_PRELOAD cannot be preloaded (cannot open shared object file): ignored. and touch: setting times of './etc': Operation not permitted could mean u are using sudo command inside the PKGBUILD. Remove it otherwise the owner will change to "root".

  • If a startup script is not run, check in profiledef.sh the presence of ["/<script-path>/<script-name>"]="0:0:744" or ["/<script-path>/<script-name>"]="0:0:755" based on the needed permissions.

  • In case on GitHub there is an icon of a folder with an arrow, and it is not possible to pull it, follow: https://stackoverflow.com/questions/62056294/github-folders-have-a-white-arrow-on-them

  • In case, during a sudo pacman -Syy you get an error related to a key that says unknown trust, just run:

    sudo pacman-key --lsign-key <key-id>

  • For preventing to get an error related to an old key of Athena Repository during the creation of the ISO, as:

    Package (2)                            Old Version  New Version  Net Change  Download Size

blackarch/blackarch-keyring            20140118-3   20180925-5    -0.02 MiB       0.02 MiB
athena-repository/mkinitcpio-openswap  0.1.0-1      0.1.0-3        0.00 MiB       0.01 MiB

Total Download Size:    0.03 MiB
Total Installed Size:   0.02 MiB
Net Upgrade Size:      -0.02 MiB

:: Proceed with installation? [Y/n] 
:: Retrieving packages...
 blackarch-keyring-20180925-5-any downloading...
 mkinitcpio-openswap-0.1.0-3-any downloading...
checking keyring...
downloading required keys...
:: Import PGP key E0CF5924036306BF, "Antonio Voza <vozaanthony@gmail.com>"? [Y/n] error: key "E0CF5924036306BF" could not be looked up remotely

error: required key missing from keyring
error: failed to commit transaction (unexpected error)
Errors occurred, no packages were upgraded.

    it means that the packages of the repository are still signed with the old key, so the current .zst and .zst.sig files must be deleted and the packages must be built again and signed with the new key and pushed to the repository. This task must be done for all the packages inside the repository. It is a good practice to execute pacman -Sc for flushing the pacman cache, and then execute pacman -Syyu for updating the repositories on the user machine.

  • After the building of a package, remember to delete src and pkg folder because they could contain some broken symbolic links that could block the deployment of the package on GitHub page repository.

  • For editing some messages in the GRUB at boot time, refer to archiso/syslinux and archiso/efiboot

  • If you get the error:

    ==> Signing package(s)...
==> WARNING: Failed to sign package file hyper-athena-config-1.0.0-1-x86_64.pkg.tar.zst.

    remember that the repository key must be both on pacman-key list keys but also on gpg list keys, so we need to:

    sudo pacman-key --recv-keys A3F78B994C2171D5 --keyserver keyserver.ubuntu.com
gpg --recv-keys 5A34EB551197A065F8A401AFA3F78B994C2171D5 keyserver.ubuntu.com

    Note: The signature checking implemented in makepkg does not use pacman's keyring, instead relying on the user's keyring. It means that is is related to keys in $HOME/.gnupg. When the user signs a package and gets ==> ERROR: The key A3F78B994C2171D5 does not exist in your keyring., it means the user didn't import correctly the private key. The private key must be imported with no sudo by gpg command, otherwise it will be imported with errors.

    Note: gpg import/recv-keys/list-keys commands are different by pacman-key import/recv-keys/list-keys commands.

    If the user gets an error saying the remote key cannot be fetched by the remote server, execute both of the commands above until you get the right response.

  • About GNOME extensions, usually, after installation, the user needs to logout/login and then enable then manually by gnome-extensions enable extension@name. If we are building a new ISO and we want automatically enable GNOME extensions, we need only to insert them inside the output file produced by dconf dump /org/gnome/shell/ > dconf-shell.ini command and add the name of the extension inside the enabled-extensions field. In this way, when the extensions added in that field will be effectively installed, after the logout/login, it will be automatically enabled without running the manual gnome-extensions enable extension@name command.

  • During the update of a new ISO, if GNOME extensions don't work, go to the Application Menu panel and search for Extensions. If the first checkbox is disabled, enable it and check if the extension checkboxes below are also enabled. If this method does not work, try to rebuild again the ISO file because probably some GNOME or GDM-related file has been corrupted. UPDATE: this issue should be now fixed by adding in /etc/profile.d/run-once.sh script the gsettings set org.gnome.shell disable-user-extensions false. In this way, if the system disables the GNOME extensions during the login, after the login they are again enabled automatically.

  • Currently the GNOME extensions packages install GNOME extensions at system level (so in the folder /usr/share/gnome-shell/extensions. If in the future we need to have a same extension separated for user, we should change the PKGBUILD and store the extension files in $HOME/.local/share/gnome-shell/extensions. Note that at the moment of the ISO creation, home folder is not defined.

  • If the developer has some sub-git modules in the Athena Repository, mostly when it downloads new themes and icons from GitHub, during the building of the repository ("Action" tab on GitHub), it can get an error like:

    Error: fatal: No url found for submodule path 'x86_64/packages/athena-graphite-theme/usr/share/themes/Graphite-gtk-theme' in .gitmodules
Error: The process '/usr/bin/git' failed with exit code 128

    For solving it, run:

    git rm --cached x86_64/packages/athena-graphite-theme/usr/share/themes/Graphite-gtk-theme -f

    where the folder path should be the one containing the .git folder.

  • In case the developer edits something on GitHub repository online, and the tries to commit and push some changes from the local repository without performing a pull, it can get an error and it is asked to choose on one kind of pull to execute. If the developer wants to merge the changes performed on GitHub website and on the local repository, execute:

    git pull --no-rebase

    Then, the developer can correctly push the changes from the local repository.

  • If the user is not able to access to the login page or it is frozen, open a text terminal by following: https://calcoen.web.cern.ch/Linux_keys.htm

  • If the user is working on a virtual machine where it has two separated logic volumes, for example lv_root and lv_home and it needs to resize them because on of them has consumed almost all available space: Let's guess the user would like to shrink lv_home from 59.51 GB to 10 GB and give all the resultant free space to lv_root. Logout and CTRL+ALT+F3 and login in the text terminal environment as root. Then

    umount -a #(we need to umount /home)
e2fsck -f /dev/volgroup0/lv_home
resize2fs /dev/volgroup0/lv_home 10G
lvresize -L -49.51G /dev/volgroup0/lv_home
lvresize -l 100%FREE /dev/volgroup0/lv_root #If getting Warning message because we are reducing the space, type "no" and go ahead
lvresize -L +20G /dev/volgroup0/lv_root
resize2fs /dev/volgroup0/lv_root

    Then reboot.

  • If the user needs to export to a new machine all the GNOME configuration:

    dconf dump / > dconf-settings.ini

    On the new machine, it can import this global settings by:

    cat dconf-settings.ini | dconf load /

    If you need to export and import only a subset of configuration, change the / path.

  • For enabling Shared Folders in VMware, enable it on the VM settings and then you should get the path /mnt/hgfs/<sharefolder-name>. If it is not working, execute:

    sudo mkdir -p /mnt/hgfs/
sudo /usr/bin/vmhgfs-fuse .host:/ /mnt/hgfs/ -o subtype=vmhgfs-fuse,allow_other

    In general, when the user reboots the machine, the Shared Folders cannot be accessed despite they are tagged as Enabled in VMware settings. For solving this issue, it is needed to create /etc/systemd/system/mnt-hgfs.mount file with the following content:

    [Unit]
Description=VMware mount for hgfs
DefaultDependencies=no
Before=umount.target
ConditionVirtualization=vmware
After=sys-fs-fuse-connections.mount

[Mount]
What=vmhgfs-fuse
Where=/mnt/hgfs
Type=fuse
Options=default_permissions,allow_other

[Install]
WantedBy=multi-user.target

    Then, create /etc/modules-load.d/open-vm-tools.conf with this content:

    fuse

    If the file already exists, add that line to the file. Enable the system service by sudo systemctl enable mnt-hgfs.mount. This will make sure the hgfs fdirectory will be mounted after a reboot. Make sure the 'fuse' module is loaded by running sudo modprobe -v fuse. In Workstation or Fusion, enable "Shared Folders" in "Virtual Machine Settings" > "Options", and set the folders to be shared. The shared folders should appear in the directory /mnt/hgfs. If that is not the case, start the service with sudo systemctl start mnt-hgfs.mount or reboot. In Athena this is managed automatically from the installation phase by athena-system-installation, when VMware is detected as virtualization platform. Source: https://kb.vmware.com/s/article/74650

  • If sudo command returns incorrect password despite it is correct, type faillock --user <your-username> --reset on the terminal.

  • If you need to color an ASCII art on the terminal for only specific characters, save it in a file, replace the single character, e.g., (, with itself between color codes, e.g., \033[0;92m(\033[0m (green color), and replace all. Then, encode your ASCII art and you can call it inside a bash script by: printf '%b\n' "$(base64 -d <<<"<encoded base64-gzip ASCII art>" | gunzip)".

  • If you are using a GNOME Extension like Desktop Icons NG or Desktop Icons Neo or Dash to Dock and some of their icons they spawn are opened wrongly by a terminal like Kitty, it means that a default application for inode/directory is not specified. You can fix it by executing xdg-mime default org.gnome.Nautilus.desktop inode/directory. Note that the list of default applications should be in $HOME/.config/mimeapps.list.

  • Adding Chaotic Repository will add a huge number of packages that pacman can retrieve. It means also that, if you are pressing TAB button for package name completion, it will take some seconds for searching a package name. The idea could be adding Chaotic repository on the host machine for making the ISO but not adding it to the target system.

  • If you write sudo pacman -S package-na and then you press TAB for autocompletion and get a [sudo] password for user:, the issue could be on your aliases, where a pacman alias is set as sudo pacman. Just delete sudo from that alias value.

  • If you are using VMware and the VMware extensions (autosize screen and clipboard) don't work, reboot the machine. If this method does not work, turn off the machine and turn on again.

  • Sometimes the GNOME extensions could be disabled for safety by GNOME, so you cannot open PenTOXIC and PWNage menus. For solving this issue, go to the Application Menu, search for "Extensions", open it, check the first option for enabling all the GNOME extensions that have been disabled by GNOME.

  • If tmux does not show any icons or emoji, as well as lsd folder and file icons, just use tmux -u.

  • For importing manually the TMUX plugins on a new ISO, remember to set all the file .sh ins tpm, bin and bindings folders (and maybe also the plugin scripts) with permission as 755 otherwise they won't be loaded and you will receive an error when TMUX TPM runs.

  • After the installation of the operating system, at first login, secret-login cannot store passwords due to a bug that freezes the insertion of a password. So you need to logout and login at least one time. For solving it in case you are distributing an ISO file, it is needed to create $HOME/.local/share/keyrings/default file containing HTB string.

  • At the beginning, for native installation the WiFi manager didn't work because the WiFi adapter was not recognized. For solving it, linux-firmware package has been installed. Then, click on the icons near the Power option on the top-right side of the screen and you will see the WiFi icon inside it.

  • During the test of new themes to be implemented, remember that if you set a non-compliant GNOME 42 theme, Adwaita theme is applied and, for testing the other themes you need to close gnome-tweaksand File Manager otherwise you cannot see the changes with the new theme.

  • If you are installing Athena in Dual Boot and Calamares Installer closes during the installation with no notice, or you get an error like:

    error: partition / too full: 63256 blocks needed, 61450 blocks free
error: not enough free disk space
error: failed to commit transaction (not enough free disk space) 
Errors occurred: no packages were upgraded.

    it means /run/archiso/cowspace is full (default size: 256MB). In this situation, Calamares is not able to work properly. For solving this issue, on Live Environment, open a terminal and type:

    sudo -S mount -o remount,size=2G /run/archiso/cowspace

    Source: https://wiki.archlinux.org/title/archiso#Adjusting_the_size_of_root_partition_on_the_fly For solving this issue automatically, you can make a script working only in the Live Environment, inside /etc/profile.d/ folder, that will be deleted after the installation of the final system. An example of this script could be:

    #!/bin/bash

sudo mount -o remount,size=2G /run/archiso/cowspace

    In Athena, this script has been added inside athena-system-installation package, so it can live only in the Live Environment and will be deleted when athena-system-installation is removed at the end of the installation of the final system.

  • During a partial installation, if Tmux is not applying theme color or plugin correctly and you try to run .tmux/plugins/tpm/scripts/install_plugins.sh and you get:

    Installing "tpm"
tmux-plugins/tpm
  "tpm" download fail
Already installed "tmux-sensible"
Already installed "tmux-power"
Already installed "tmux-window-name"
Already installed "tmux-mouse-swipe"
Already installed "tmux-notify"
Already installed "tmux-prefix-highlight"
Already installed "tmux-net-speed"
Already installed "tmux-yank"

    It could be cause by a fatal: destination path 'tpm' already exists and is not an empty directory.. Try to rename the .tmux/plugins/tpm folder as .tmux/plugins/tpmBAK and run .tmux/plugins/tpmBAK/scripts/install_plugins.sh, then run tmux, press CTRL+S and r for reloading Tmux, delete the tmpBAK folder and kill the remaining tmux running processes.

  • When you update the source code of athena-application-config package, remember to check the dconf-shell.ini file. It should not have anything inside the "Available Machines" submenu. So, the "children" field of "Available Machines" submenu must be [].

  • In case you would like to edit an application icon inside a .desktop file, in the Icon= field, you should type only the name of the icon without path and with no extensions. The system will search for all files with that name inside /usr/share/icons folder. It will search for first inside the set icon theme, and, if it does not exist there, it goes to search in other icon theme folders. If you have a .png file, remember to put it in the right folder with the related size NxN. If you have a .svg, the icon should be stored inside /scalable/apps folder. In case the icon on the desktop application does not appear, try to open the image with an image editor, because, mostly for .svg, if they are produced by Photoshop or GIMP, they could be visible in Windows but not in Linux. In this case it is better using a software as inkscape for getting the .png file and then save it as .svg. Furthermore, in case your .desktop file is executing a bash script that calls a Python GUI script, the icon specified in .desktop file won't be shown, because it is related to the specified script, that is the bash script but not the Python script. For solving this issue, avoid calling the Python script by a bash script, but, create a symbolic link to the Python script, put this symbolic link in a bin folder, and then make the Python script as executable by chmod +x.

  • Inside the creation of the ISO, for solving the issue related to the BlackArch and Athena key unknown inside the Live Environment, just take from a working environment the /etc/pacman.d/gnupg/trustdb.gpg and /etc/pacman.d/gnupg/pubring.kbx files and store them in archiso/airootfs/etc/pacman.d/gnupg/. Remember to execute this operation each time BlackArch or Athena keys change.

  • Remember that, in Archiso, the pacman.conf related to the live environment is in archiso/pacman.conf while the one related to the target system is in archiso/airootfs/etc/pacman.conf.

  • In a Virtual Machine environment, for resizing the window already in the GRUB and LightDM environment, edit /etc/default/grub and edit GRUB_GFXMODE=auto as GRUB_GFXMODE=1920x1080. In case the resolution applied is higher than the possibility of our graphic card, it is simply not applied, and it should work as auto.

  • In case there is a buggy package in its latest version, you can implement a previous stable version on your remote repository and store it at the beginning of the repository list in /etc/pacman.conf. In this way, it will be retrieved for first, regardless the version.

  • All the display managers use a service account for managing their activities. For setting an avatar stored in the home folder of the user (i.e., as /home/<user>/.face). by default, these accounts cannot access to the .face due to permission. In order to work correctly, the home folder of the users should be set at least as chmod 711 /home/*.

  • In Calamares, if there is some weird behavior, for example by clicking on "Install" button and the window freezes on "Summary" window instead to go to the "Install" window (despite the installation is going well under the hood), it could be caused by some updated packages that could affect some Calamares dependency. For example, in the last issue case, the problem was caused by mesa package at version 22.2.1-1 and we needed to downgrade to 22.1.7-1 for solving it. This issue impacted GNOME environment. When we tested on XFCE, we didn't have that issue. For similar issue, start the investigation by running pactree -u athena-calamares on an old working Athena ISO and check the version difference with respect to the latest version of those packages and try to downgrade them one by one and testing Calamares.

  • In case the microphone seems to not work, open pavucontrol and increase the dB value. Then try again if it works.

  • In case we are working on a VM and we need to set a static IP on it (remaining with DHCP enabled in the host machine), you can set your VM network settings as Bridged (with physical network connection state replication enabled), and inside the Arch VM run dhcpcd -S ip_address=<static-ip> -S routers=<default-gateway-ip> -S domain_name_servers=<DNS-server-IP> -s <static-ip>/32 <interface-name>. This command not only will set the ip addr entry for the static IP, but also routing rules showing by the ip route command. Note that if you are doing this assignment in Arch Install, you need to reapply the dhcpcd command also on the target system, so remember to add dhcpcd package during the Arch Install. Then, on the target system, delete the additional old IP address entry in ip addr by running sudo ip addr del old-ip-address/prefix dev <interface-name>.

  • During GNOME upgrades, also the themes should be reviewed because they could not work anymore. For example, migrating to GNOME 43 meant Athena themes working only with GTK-4.0, and it is needed that the themes are linked with libadwaita. Currently, the problem of themes has been solved by re-downloading them and placed in /usr/share/themes or $HOME/.themes. For GruvBox and TokyoNight, that have each one two separated archives, the content of archive with -G42.zip suffix must replace /usr/share/themes/<theme-name>/gtk-4.0/gtk.css. At the end, for linking libadwaita to the used theme, the following commands must be run (not everyone, just the set of commands related to the used theme):

    # GRAPHITE
mkdir -p "${HOME}/.config/gtk-4.0"
ln -sf "/usr/share/themes/Graphite-Dark-compact/gtk-4.0/assets" "${HOME}/.config/gtk-4.0/assets"
ln -sf "/usr/share/themes/Graphite-Dark-compact/gtk-4.0/gtk.css" "${HOME}/.config/gtk-4.0/gtk.css"
ln -sf "/usr/share/themes/Graphite-Dark-compact/gtk-4.0/gtk-dark.css" "${HOME}/.config/gtk-4.0/gtk-dark.css"

# SWEET DARK
mkdir -p "${HOME}/.config/gtk-4.0"
ln -sf "/usr/share/themes/Sweet-Dark/assets" "${HOME}/.config/assets"
ln -sf "/usr/share/themes/Sweet-Dark/gtk-4.0/gtk.css" "${HOME}/.config/gtk-4.0/gtk.css"
ln -sf "/usr/share/themes/Sweet-Dark/gtk-4.0/gtk-dark.css" "${HOME}/.config/gtk-4.0/gtk-dark.css"

# BLUE EYES SAMURAI
mkdir -p "${HOME}/.config/gtk-4.0"
ln -sf "/usr/share/themes/Tokyonight-Dark-B/gtk-4.0/assets" "${HOME}/.config/gtk-4.0/assets"
ln -sf "/usr/share/themes/Tokyonight-Dark-B/gtk-4.0/gtk.css" "${HOME}/.config/gtk-4.0/gtk.css"
ln -sf "/usr/share/themes/Tokyonight-Dark-B/gtk-4.0/gtk-dark.css" "${HOME}/.config/gtk-4.0/gtk-dark.css"

# CYBORG GRUVBOX
mkdir -p "${HOME}/.config/gtk-4.0"
ln -sf "/usr/share/themes/Gruvbox-Dark-B/gtk-4.0/assets" "${HOME}/.config/gtk-4.0/assets"
ln -sf "/usr/share/themes/Gruvbox-Dark-B/gtk-4.0/gtk.css" "${HOME}/.config/gtk-4.0/gtk.css"
ln -sf "/usr/share/themes/Gruvbox-Dark-B/gtk-4.0/gtk-dark.css" "${HOME}/.config/gtk-4.0/gtk-dark.css"

# Akame theme currently does not have GTK 4.0 files so legacy windows (like the File Manager) cannot use the theme.

  • In Calamares, if we choose to do "Manual Partition", remember that the main partition must have boot flag enabled.

  • If you add a new kernel in Calamares installer, remember to edit athena-kernel-check in athena-system-installation package.

  • When we set a new kernel type in Archiso for the Live Environment, remember to change also athena and linux.preset file contents in archiso/airootfs/etc/mkinitcpio.d folder (don't rename linux.preset), archiso_pxe-linux.cfg and archiso_sys-linux.cfg in archiso/syslinux folder, 01-archiso-x86_64-linux.conf, 02-archiso-x86_64-speech-linux.conf and 03-archiso-x86_64-ram-linux.conf in archiso/efiboot/loader/entries folder, and grub.cfg in archiso/grub folder. Also the /etc/calamares/modules/unpackfs.conf file should be edited by replacing vmlinuz-linux with vmlinuz-<kernel_name>. Note that by placing the kernel choice in Calamares is not a good approach, because it is not possible to uninstall the previous kernel type during the Calamares installation. It is better to remove the kernel choice from Calamares and use only one. It could be worth to have a Tweak Tool that allows to switch among kernels when the target system is already installed.

  • Sometimes both in Bare Metal and in VM scenarios, the Calamares unpackfs module could fail because the airootfs.sfs and vmlinuz-linux-zen files could not be in /run/archiso/bootmnt but they are in copytoram folder. It is possible to solve this issue by adding copytoram=no or copytoram=n to archiso_pxe-linux.cfg and archiso_sys-linux.cfg in archiso/syslinux folder at the end of each APPEND line, and 01-archiso-x86_64-linux.conf, 02-archiso-x86_64-speech-linux.conf in archiso/efiboot/loader/entries at the end of options line.

  • If you get graphic behavior on Burpsuite on VMware Workstation VM, it should be caused by 3D Acceleration + Wayland. In order to make it working, just use Xorg.

  • During the installation of the system, if you get the following error on Calamares logs:

    2022-11-13 - 19:37:34 [1]: void Calamares::ViewManager::onInstallationFailed(const QString&, const QString&)
  ERROR: Installation failed: "Package Manager error" 
2022-11-13 - 19:37:34 [6]:     .. - message: "Package Manager error" 
2022-11-13 - 19:37:34 [6]:     .. - details: The package manager could not prepare updates. The command <pre>pacman</pre> returned error code 1.

    just check if BlackArch or other repositories are reachable by your host.

  • For dual boot, in case you are using two different physical disks, for example one NTFS for Windows and another NTFS for data, and you want to install Athena on the last one, remember that the MBR used by Windows is in the first disk, but you must be sure that the first volume should be a FAT32 labelled NOT as "msftdata" but as "boot/efi" (or "boot"). You can check this by GParted. If it is "msftdata", delete the volume and create again a FAT32 with "boot/efi" (or "boot") flag. If you need to have a volume for "msfdata", it must be AFTER the boot volume. In Calamares, as Boot Loader to write, choose the one of the first disk. After the installation, in BIOS -> Boot, you should be able to manage the priority on the disk between Athena and Windows Boot Manager. Before this, if Windows Boot is broken, you can fix it by running a Windows boot USB, enter in Recovery Mode, open the Command Prompt and run "bootrec rebuildbcd" and "bootrec fixmbr" and then reboot and check on BIOS the Boot Priority of the disk. Link about flags: https://www.linux.org/threads/gparted-partition-and-filesystem-flags.11640/

  • In NeoVim, when you use NvChad and you want to enable the Hydra ASCII art, in ~/.config/nvim/lua/plugins/init.lua search for goolord piece of code and change its disable variable to false. Then, open nvimand runPackerSync`.

  • In NeoVim, the "leader" key is specified in ./lua/core/options.lua on the mapleader variable. It is " " () by default.

  • For XFCE Picom environment, at the beginning we set glx as backend of picom, but on VM with no 3D acceleration, it caused high CPU usage. According to some posts, it causes the same issue also on some NVIDIA proprietary drivers, and in general also excessive power consumption. For this reason in $HOME/.config/picom.conf we decided to set xrender instead of glx as picom backend.

  • In a PKGBUILD using make install, it could generate a Permission denied error. For fixing it, you need to identify the variable used in Makefile that specifies the root of the environment $pkgdir. For example, this variable could be DESTDIR or INSTALL_ROOT. If you use the right one, for example make INSTALL_ROOT="$pkgdir" install, you won't get the error anymore.

  • If you tried to push to the GitHub repository a package that is bigger than 100 MB, each push you will do will give the error due to bigger package, even if you delete this big file. It occurs because the information of the big file remains in the git history despite it has been deleted. For solving this, run sudo pacman -S git-lfs and then git lfs migrate import --include="<pkgname>.pkg.tar.zst" and it should convert this file to its hash string. After this, try to push again your modification to the remote repository. You should have a string saying the upload of a LFS but don't care about it. After this, try to re-push again and it should be well. NOTE: if you run git lfs migrate import on all files, don't do it, otherwise they will be all converted in text files containing their hash. If it happens just run git lfs migrate export --include="<affected-files>".

  • If VSCode themes are not applied after the installation, the issue could be related to the $HOME/.vscode-oss/extensions/extensions.json file that is pointing to a non-existing folder for each theme. For fixing this, just edit the path of the specified themes with the correct one. Note: the file cannot expand environment variables.

  • At boot time, if you cannot reach the Login Screen and you are freezing on a blinking cursor or on a "Starting udev kernel device" or similar message:

    • press CTRL+ALT+F2, login by the terminal, and remove /etc/X11/xorg.conf or some GPU related files (i.e., NVIDIA related) in /etc/X11/xorg.conf.d/ directory.
    • or don't install any NVIDIA packages at installation time. Mostly in case you don't have an integrated GPU (but a LLVMPIPE software rendering appears as graphics), once you installed the new baremetal system without NVIDIA packages, just verify if LLVMPIPE is managing your graphics by GNOME settings or glxinfo | grep OpenGL. Then, run sudo pacman -S nvidia-dkms and reboot. Now you should have NVIDIA working! It does not need NVIDIA Optimus because it is the case without integrated GPU. Tested on an ASUS ROG Strix GeForce RTX 3060 GPU.

  • In Linux environment, for making NVIDIA working there are several configurations to consider:

    • Add nvidia nvidia_modeset nvidia_uvm nvidia_drm in the modules in mkinitcpio.conf file and run the command for updating it
    • Add nvidia-drm.modeset=1 in the grub config file
    • Add VK_LAYER_NV_optimus=NVIDIA_only and __GLX_VENDOR_LIBRARY_NAME=nvidia in /etc/environment in order to enable NVIDIA for OpenGL renderer. Note that at the beginning I was using __NV_PRIME_RENDER_OFFLOAD but it has some issues on some applications as gnome-control-center (the GNOME settings) that is not able to show the window when we try to open it. Wayland does not support NVIDIA, so NVIDIA must be used mainly on Xorg by switching the Integrated CPU to the Dedicated NVIDIA GPU by optimus-manager-qt in Xorg environment. After enabling it in Xorg, we are pushed back to the login screen and:
    • if we select Xorg, ok. And here we can use several NVIDIA applications as envycontrol that are not usable in Wayland;
    • if we select Wayland, we should have a hybrid GPU set (Integrated and Dedicated GPUs) but this scenario is not supported and will be disable at reboot. NOTE: all the points above seem to be related only when you have both Integrated and Dedicated GPU in your computer.
    • some tools like bumblebee or nouveau (or maybe nvidia-optimus but not sure) can blacklist nvidia module, so don't install them if you want to use NVIDIA proprietary drivers.

  • In case your time clock and time zone is not set correctly, create a file /etc/NetworkManager/dispatcher.d/09-timezone with a similar content as the one in Athena OS.

  • If you want that a wallpaper is shown by default in GNOME Settings -> Appearance, under Background pane, you need to create an XML file in /usr/share/gnome-background-properties and write the properties you need. Remember that options tag has the following values: none, wallpaper, centered, scaled, stretched, zoom, spanned. If you change the values inside, in order to see the changes, you need to delete and re-create the .xml file.

  • In case you installed Athena in a VM and you try to press Athena Welcome buttons, or to open kitty and nothing happens, it could be related to the following "hidden" error:

    [021 23:28:32.704824] [glfw error 65543]: GLX: Failed to create context: GLXBadFBConfig
[021 23:28:32.704927] Failed to create GLFW temp window! This usually happens because of old/broken OpenGL drivers. kitty requires working OpenGL 3.3 drivers.

    This issue is caused by nvidia-utils package (that in a VM environment is useless). If it is uninstalled, kitty and the Athena Welcome buttons start to work again.

  • If you need to change the default version of JDK used in your system, detect which Java versions are installed by archlinux-java status and if you get, for example:

    java-17-openjdk
java-19-openjdk (default)

    you can run archlinux-java set java-17-openjdk and the system will use JDK17 as default version of Java.

  • On VMWare workstation, for enabling multiple monitor, go to the Login Screen, set Full Screen, enable Cycle Multiple Monitors and type the password for logging in.

  • By running users or w commands, if you see two sessions of your user instead of one, it should be common because GDM adds two sessions to /var/run/utmp. xterm will (by default) also add an entry, so if you run xterm, you'll get another "session" in users and w (on some pts).

  • During baremetal installation, if the installation fails for an error like:

    grub-install: warning: this GPT partition label contains no BIOS Boot Partition; embedding won't be possible.
grub-install: error: filesystem `btrfs' doesn't support blocklists.
2023-02-08 - 11:20:33 [2]: WARNING: [PYTHON JOB]: "Command 'grub-install --target=i386-pc --recheck --force /dev/nvme0n1' returned non-zero exit status 1."

    it should be caused because you boot Athena OS by BIOS/CSM/legacy-mode boot. This kind of boot is old and it could not work when you are installing Athena in dual boot with Windows because Windows uses EFI boot. For this reason, you too need to boot Athena OS from the USB key by EFI/UEFI mode and the installation won't have that error anymore. Source: https://superuser.com/questions/903112/grub2-install-this-gpt-partition-label-contains-no-bios-boot-partition

  • If you get the following error during sudo pacman -Syyu:

    error: blackarch: signature from "Levon 'noptrix' Kayan (BlackArch Developer) <noptrix@nullsecurity.net>" is invalid
error: failed to synchronize all databases (unexpected error)

    just run sudo rm /var/lib/pacman/sync/blackarch.db.sig and try again sudo pacman -Syyu. If it does not work, try to run:

    sudo pacman -Sy archlinux-keyring chaotic-keyring

    If it does not still work, run:

    sudo pacman-key --init
sudo pacman-key --populate
sudo rm /var/lib/pacman/sync/blackarch.db.sig
sudo pacman -Syyu

  • In baremetal with NVIDIA GPU, if you use Optimus Manager and you are working on Xorg, could happen that when you reboot and login on Wayland, the WiFi interface could disappear. At this point, just reboot and login on Xorg session.

  • If you run a docker container that uses a systemd in Xorg host, the entire host could crash. For avoiding this, switch the host to Wayland.

  • In case you remove manually all the containers from /var/lib/docker/overlay2 for freeing the disk space, docker and podman could not work properly anymore. Reinstall them, disable, enable, and start their services, and reboot the computer.

  • I noted that building the container by podman runs athena-motd correctly. If I build by sudo docker, it does not.

  • I needed to remove the install of chaotic-mirrorlist and blackarch-mirrorlist from the running script in Calamares because I noted that they could cause issues to some unstable mirrors like r2.garudalinux.org that produced an error like error: failed retrieving file 'gnome-shell-extension-appindicator-git-1:52+6+gf57dbd5-1-any.pkg.tar.zst.sig' from r2.garudalinux.org : The requested URL returned error: 404. By removing the installation of chaotic-mirrorlist from shellprocess@before, the issue has been fixed.

  • Maybe if I try to edit mirrorlists inside Calamares scripts during the installation by sed, I noted they don't change in the target installed system.

  • If going to Settings -> Applications tab you don't see any application, just install malcontent package.

  • I noted that, despite I have kitty as default terminal, some application icons as Fish or Vim or Nvim, when clicked, runs gnome-terminal. Currently I don't find a way to directly force them to run kitty, what I can do is to edit the related .desktop files as explained in https://unix.stackexchange.com/questions/365587/how-to-open-vim-in-terminator-by-default

  • Note that in Arch Linux, powershell package does not support the autocompletion and maybe some module misses. Use powershell-bin package because it implements these missing features.

  • During the build of a package, if git returns the following error:

    error: unable to normalize alternate object path: wrong path

    Reboot the machine. If it does not work, run git rm --cached and reboot the machine.

  • In case you note that some graphic tearing or issues, or Alacritty is not rendering the typed strings well (for example it freezes until you press a key or it freezes the opening of file by nano), it could be due to the usage of LLVMPIPE software rendering instead of your GPU or VM graphic adapter. On VMware, I solved it by enabling 3D Acceleration and providing 2GB of graphic memory.

  • For adding a delay on Plymouth boot animation, create the file /etc/systemd/system/plymouth-quit.service.d/super_long_splash.conf:

    [Unit]
Description=Longer Plymouth Boot Screen time

[Service]
ExecStartPre=/usr/bin/sleep 5

    and reboot.

  • During the compilation of an AUR package, when you run makepkg -si and you get this error:

    process: archiso git repo ... FAILED (unknown public key 5CE88535E188D369)

    Just run gpg --recv-key <key-id>. Source: https://wiki.archlinux.org/title/Arch_User_Repository#Acquire_a_PGP_public_key_if_needed

secret-tool

If you are using a Debian CLI host environment, to make secret-tool working correctly, as a standard user, run:

apt install gnome-keyring libsecret-tools dbus-x11

Store the 50-systemd-user.sh in /etc/X11/xinit/xinitrc.d/ by running:

export DISPLAY=:0
sudo mkdir -p /etc/X11/xinit/xinitrc.d
sudo wget -O /etc/X11/xinit/xinitrc.d/50-systemd-user.sh https://raw.githubusercontent.com/systemd/systemd/main/xorg/50-systemd-user.sh
source /etc/X11/xinit/xinitrc.d/50-systemd-user.sh
export $(dbus-launch)

Then, the object "/org/freedesktop/secrets/collection/login" must be created:

dbus-run-session -- bash
gnome-keyring-daemon --unlock

It will be asked for a password to protect the keyring. On the empty terminal row, type your password WITHOUT pressing Enter. Just press CTRL+D two times. Then, run again:

gnome-keyring-daemon --unlock

As before, type your password WITHOUT pressing Enter. Just press CTRL+D two times.

Now, you should see login.keyring and user.keystore files in ~/.local/share/keyrings.

You can store your secrets by secret-tool.

In case you forget the password to unlock the keyring, delete login.keyring and user.keystore files but you will lose your stored secrets.

To test the right password to unlock the keyring, download unlock.py and test the password by:

wget -O unlock.py https://codeberg.org/umglurf/gnome-keyring-unlock/raw/branch/main/unlock.py
chmod +x ./unlock.py
./unlock.py <<<YourKeyringPassword

If it does not return anything, the typed password is right, otherwise you will get "Unlock denied" message.

At each login or reboot, you need to unlock the keyring.

If you want to create a cronjob that uses dbus and secret-tool, create a script containing the following lines:

#!/usr/bin/env bash

# NOTE: to set the cron job at a specific time, check the right server timezone 
export DISPLAY=:0
export $(dbus-launch)
# DBUS cannot be retrieved on cron environment. For this reason we pass the user value directly
export DBUS_SESSION_BUS_ADDRESS="unix:path=/run/user/1000/bus"
echo $DBUS_SESSION_BUS_ADDRESS
# XDG_RUNTIME_DIR set to allow unlock.py to find control socket
export XDG_RUNTIME_DIR="/run/user/1000"
echo $XDG_RUNTIME_DIR
/home/gitsync/cronjob-builder/unlock.py <<<Password
<rest of the code>

Docker Container Athena OS

  • In docker container, we generated the user directly with the /bin/zsh (unlike the main OS) otherwise, when in the container we run a command by FlyPie, the $SHELL were expanded as /bin/sh instead of zsh. It occurred because it considered the origin shell of the user instead of parsing the .bashrc file containing the definition of SHELL variable. At this point, the definition of SHELL variable in .bashrc was useless so we deleted it.

  • In case you use a specific shell and you cannot login in the container because it responds by "failed password" message, be sure that your shell is inside /etc/shells.

  • Unlike the main OS, in Athena docker container, we call directly zsh and THEN we source .bashrc, indeed, inside .zshrc there is source ~/.bashrc in order to perform all the exports and the other rules defined in .bashrc when zsh is called.

  • Usually in a container with GUI, for power off, restart, suspend or hibernate the system it is asked to insert Administrator password. For avoiding this, edit /usr/share/polkit-1/actions/org.freedesktop.login1.policy file and change to yes the entries related to power off the system, reboot the system, suspend the system and hibernate the system.

WSL

  • If you start the WSL image and you get several errors at the beginning and systemd does not run, just exit from the WSL and run wsl --shutdown. Then, access again to the WSL environment.

  • If you are working on WSL and when you try to store a secret by secret-tool you get a message similar to:

    secret-tool: Could not connect: No such file or directory

    just run wsl --shutdown and run Athena OS again.

  • If you are working on WSL and when you try to store a secret by secret-tool you get a message similar to:

    secret-tool: Object does not exist at path “/org/freedesktop/secrets/collection/login”

    you need to execute source /etc/X11/xinit/xinitrc.d/50-systemd-user.sh. If you continue to get a similar message after wsl --shutdown, just exit from Athena OS WSL and re-enter and it should work again. For solving this issue, I inserted source /etc/X11/xinit/xinitrc.d/50-systemd-user.sh directly on htb-update.py if the running system is WSL.

  • On WSL, I noted that after the installation, VNC and RDP services worked correctly and gnome-shell was able to find a DISPLAY. When I shutdown WSL and restarted it, VNC and RDP services stopped to work, indeed xrdp crashed after the user login and TigerVNC reported gnome-session-check-accelerated: no X11 display found in log files. It occurs because of Wayland lock files. Just remove them by rm -rf /run/user/1000/wayland-0*.

Clone this wiki locally