troubleshooting.md
1 # Troubleshooting 2 3 - [An application does not work, is old and unsupported](#an-application-does-not-work-is-old-and-unsupported) 4 - [Failed to open squashfs image](#failed-to-open-squashfs-image) 5 - [Cannot download or update an application](#cannot-download-or-update-an-application) 6 - [Cannot mount and run AppImages](#cannot-mount-and-run-appimages) 7 - [Spyware, malware and dangerous software](#spyware-malware-and-dangerous-software) 8 - [Stop AppImage prompt to create its own launcher, desktop integration and doubled launchers](#stop-appimage-prompt-to-create-its-own-launcher-desktop-integration-and-doubled-launchers) 9 - [The script points to "releases" instead of downloading the latest stable](#the-script-points-to-releases-instead-of-downloading-the-latest-stable) 10 - [Ubuntu mess](#ubuntu-mess) 11 - [Wrong download link](#wrong-download-link) 12 13 ------------------------------------------------------------------------ 14 ### An application does not work, is old and unsupported 15 Use the `-a` option and go to the developer's site to report the problem. The task of "AM" is solely to install / remove / update the applications managed by it. Problems related to the failure of an installed program or any related bugs are attributable solely to its developers. 16 17 ------------------------------------------------------------------------ 18 19 | [Back to "Troubleshooting"](#troubleshooting) | [Back to "Main Index"](../README.md#main-index) | 20 | - | - | 21 22 ------------------------------------------------------------------------ 23 ### Cannot download or update an application 24 There can be many reasons: 25 - check your internet connection; 26 - if the app is hosted on github.com, you have probably exceeded the hourly limit of API calls; 27 - the referring link may have been changed, try the `--rollback` option or `downgrade`; 28 - the reference site has changed, report any changes at https://github.com/ivan-hc/AM/issues 29 ------------------------------------------------------------------------ 30 31 | [Back to "Troubleshooting"](#troubleshooting) | [Back to "Main Index"](../README.md#main-index) | 32 | - | - | 33 34 ------------------------------------------------------------------------ 35 ### Cannot mount and run AppImages 36 If by running it in the terminal you get an error message about "FUSE" or "libfuse"/"libfuse2" missing, take a look at the official documentation: 37 38 https://docs.appimage.org/user-guide/troubleshooting/fuse.html 39 40 If your distro does not provide `libfuse2`, you can install it using the command: 41 ``` 42 am -i libfuse2 43 ``` 44 or 45 ``` 46 appman -i libfuse2 47 ``` 48 NOTE, in AppMan you still need to use your password (`sudo` or `doas`) to install the library at system level, in /usr/local/lib 49 50 Alternatively you can use the "`nolibfuse`" option to "try" to convert old Type2 AppImages to a new generation one, so as not to depend on `libfuse2`. In most cases it works, but sometimes it can give errors, depending on how the package was manufactured. 51 52 However, I suggest contacting the upstream developers to convince them to upgrade their packages. 53 54 * **If you cannot run some AppImages on Ubuntu 23.10+ or its derivatives, then refer to [Restricted unprivileged user namespaces are coming to Ubuntu 23.10 | Ubuntu](https://ubuntu.com/blog/ubuntu-23-10-restricted-unprivileged-user-namespaces) for possible causes and remedies or jump to "[Ubuntu mess](#ubuntu-mess)".** 55 * **If you cannot run chrome/chromium/electron-based AppImages, then refer to [Troubleshooting/Electron-sandboxing](https://docs.appimage.org/user-guide/troubleshooting/electron-sandboxing.html) for possible causes and remedies.** 56 57 ------------------------------------------------------------------------ 58 59 | [Back to "Troubleshooting"](#troubleshooting) | [Back to "Main Index"](../README.md#main-index) | 60 | - | - | 61 62 ------------------------------------------------------------------------ 63 ### Failed to open squashfs image 64 When installing a script for an AppImage, you may see an error like this 65 ``` 66 This doesn't look like a squashfs image. 67 Failed to open squashfs image 68 sed: can't read ./appname.desktop: No such file or directory 69 mv: cannot stat './appname.desktop': No such file or directory 70 ``` 71 Basically, the installation process encounters errors while trying to extract the .deskto launcher and icon from the AppImage, and most likely, the entire application execution via terminal may fail, especially if installed locally, via AppMan. 72 73 Here's what you need to check: 74 - the installation status via your distribution repositories of the "squashfs-tools" package; 75 - the installation status of FUSE (whether it is version 2, 3 or higher); 76 - whether AppImageLauncher is installed or present on the system, if so remove it. 77 78 In the case of AppImageLauncher, as I write (today September 20, 2024), the repository has not been updated for a couple of years and the runtime used in the AppImages has changed. AppImageLauncher uses mechanisms to identify the AppImages present in the system, asking you to integrate them if you launch one. It acts a bit like a system daemon in effect, and could cause problems while you tend to manage the AppImages with different tools, and therefore even the execution via terminal can be problematic. 79 80 Remove AppImageLauncher and its files, then reboot the system (see also [issues/955](https://github.com/ivan-hc/AM/issues/955) and [issues/107](https://github.com/ivan-hc/AM/issues/107)). 81 82 ------------------------------------------------------------------------ 83 84 | [Back to "Troubleshooting"](#troubleshooting) | [Back to "Main Index"](../README.md#main-index) | 85 | - | - | 86 87 ------------------------------------------------------------------------ 88 ### Spyware, malware and dangerous software 89 Before installing any application, try to know where it comes from first. This program provides you with two basic options for this purpose: 90 - Option `-a` or `about` (medium safety), allows you to read a short description and know the links from the pages of the site [https://portable-linux-apps.github.io](https://portable-linux-apps.github.io) locally, however these links may be inaccurate due to continuous updates of the initial scripts (you can provide additional info yourself by modifying the pages of the site, [here](https://github.com/Portable-Linux-Apps/Portable-Linux-Apps.github.io), it is also open source); 91 - Option `-d` or `download` (absolute safety), this allows you to get the installation script directly on your desktop, so you can read the mechanisms and how it performs the downloads from the sources (in most cases there is a header for each step that explains what the listed commands do). 92 93 “AM” and AppMan are just tools to easily install all listed programs, but what you choose to install is your complete responsibility. **Use at your own risk**! 94 95 ------------------------------------------------------------------------ 96 97 | [Back to "Troubleshooting"](#troubleshooting) | [Back to "Main Index"](../README.md#main-index) | 98 | - | - | 99 100 ------------------------------------------------------------------------ 101 ### Stop AppImage prompt to create its own launcher, desktop integration and doubled launchers 102 Some developers insist on creating Appimages that create their own launcher on first launch (like WALC and OpenShot). If the official solution proposed [here](https://discourse.appimage.org/t/stop-appimage-from-asking-to-integrate/488) doesn't work, you have two options to escape this trouble: "`-H`" and "`--sandbox`". 103 104 **1. Option "-H" or "home": create a .home directory for the AppImage** 105 106 Use the option `-H`, then launch the app and accept the request. Dotfiles and launcher will be saved in the $APP.home near the AppImage: 107 ``` 108 am -H $APP 109 $APP 110 ``` 111 or 112 ``` 113 appman -H $APP 114 $APP 115 ``` 116 you can also use the AppImage's builtin option `--appimage-portable-home` from the terminal: 117 ``` 118 $APP --appimage-portable-home 119 ``` 120 This method works in the 99% of cases. 121 122 **2. Option "--sandbox": run the AppImage into a Aisap/bubblewrap sandbox** 123 124 Use the option `--sandbox`, then launch the app and accept the request. Dotfiles and launcher will be saved in the dedicated sandbox: 125 ``` 126 am ---sandbox $APP 127 $APP 128 ``` 129 or 130 ``` 131 appman --sandbox $APP 132 $APP 133 ``` 134 This is the best method, since you decide wheter to allow the use of user's directories or not. 135 136 For more details, see "[**Sandbox an AppImage**](guides-and-tutorials/#sandbox.md)". 137 138 ------------------------------------------------------------------------ 139 140 | [Back to "Troubleshooting"](#troubleshooting) | [Back to "Main Index"](../README.md#main-index) | 141 | - | - | 142 143 ------------------------------------------------------------------------ 144 ### The script points to "releases" instead of downloading the latest stable 145 This is a choice I made as many developers have abandoned support for AppImage or GNU/Linux in general. My aim here is to introduce you to other developers' applications, then it's up to you to contact them, support them, help improve the software through forks and pull requests, opening issues and encouraging developers to keep the software in the format you prefer. 146 147 In case you are sure that the upstream developer will maintain the package for each stable release, you can fix this in several ways: 148 #### Method 1: Direct installation by combining `-i` and `--force-latest` options 149 ``` 150 am -i --force-latest $PROGRAM 151 ``` 152 #### Method 2: "Downgrade" the installed app to "latest" 153 Use the option `--force-latest` to patch the AM-updater and perform the "update"/"downgrade": 154 ``` 155 am --force-latest $PROGRAM 156 ``` 157 or do it manually: 158 ``` 159 sed -i 's#releases -O -#releases/latest -O -#g' /opt/$PROGRAM/AM-updater 160 am -u $PROGRAM 161 ``` 162 163 See also "[Install the "latest" stable release instead of the latest "unstable"](#install-the-latest-stable-release-instead-of-the-latest-unstable)". 164 165 ------------------------------------------------------------------------ 166 167 | [Back to "Troubleshooting"](#troubleshooting) | [Back to "Main Index"](../README.md#main-index) | 168 | - | - | 169 170 ------------------------------------------------------------------------ 171 ### Ubuntu mess 172 As the author of [this article](https://ubuntu.com/blog/ubuntu-23-10-restricted-unprivileged-user-namespaces) states, "*Ubuntu Desktop firmly places security at the forefront, and adheres to the principles of security by default*". Bullsh*t! 173 174 User namespaces are a feature of the kernel. It's a feature which is supported by the Linux kernel. When a vulnerability is found, it's given a CVE and the code is fixed appropriately. If the kernel developers wanted to disable this feature by default, or restrict it, they could do so themselves. 175 176 Introducing namespace restrictions via AppArmor is an additional security layer, but not required, since we already have more flexible sandboxing systems in the Linux world, in particular "[Bubblewrap](https://github.com/containers/bubblewrap)", used mainly by Flatpak and othe projects, including this and my other one, "[Archimage](https://github.com/ivan-hc/ArchImage)". 177 178 **Canonical has only one interest in applying all these restrictions to Ubuntu: to enforce the use of Snap!** 179 180 It's not that the Snapcraft database is that secure, it's not uncommon for some malicious user to have introduced malicious code into distributed applications. The reason they disable namespaces is due to some older privilege escalation bugs, but the problem with that is that it doesn't matter on desktop usage, any malware can just wait for you to enter your sudo password when updating, not to mention that it can already do everything the regular user can do, including deleting everything owned by the user. 181 182 But as expected, Ubuntu is a distribution that knows how to attract criticism and disapproval. I say this as a former user (I started with Ubuntu 9.04): Canonical doesn't give a damn about Ubuntu users! 183 184 There are two solutions to this problem, one simple and one a little more complex: 185 1. The simple solution is to stop using Ubuntu, completely! Change distribution! 186 2. The slightly more complex solution is to disable restrictions, via the command line. If you decide to adopt this one, see below. 187 188 #### How to disable Apparmor restrictions 189 If you chose number two and you feel happy with Ubuntu, follow these steps (as suggested [here](https://github.com/linuxmint/mint22-beta/issues/82)): 190 1. run the following command to disable AppArmor restrictions (the file name is relative) 191 ``` 192 echo 'kernel.apparmor_restrict_unprivileged_userns = 0' | sudo tee /etc/sysctl.d/20-apparmor-mint.conf 193 ``` 194 2. Reboot. 195 196 ------------------------------------------------------------------------ 197 198 | [Back to "Troubleshooting"](#troubleshooting) | [Back to "Main Index"](../README.md#main-index) | 199 | - | - | 200 201 ------------------------------------------------------------------------ 202 ### Wrong download link 203 The reasons may be two: 204 - the referring link may have been changed, try the `--rollback` option or `downgrade`; 205 - the reference site has changed, report any changes at https://github.com/ivan-hc/AM/issues 206 ------------------------------------------------------------------------ 207 208 | [Back to "Troubleshooting"](#troubleshooting) | [Back to "Main Index"](../README.md#main-index) | 209 | - | - | 210 211 ------------------------------------------------------------------------