Troubleshooting

This guide describes known issues and how to fix them.

Installation

Installation was incomplete

Installation process stopped before completion.

Problem

Installation freezes between 40% and 60%. If encryption is DISABLED, installation goes fine.

Solution

This can occur if the system has run out of entropy (“randomness”) while creating the encrypted partition. Don’t interrupt the setup, but simply open a text editor and start typing random text. You can also move the cursor around to generate more entropy.

If you wish to measure how much entropy you have available, you can run this commans on the command line:

cat /proc/sys/kernel/random/entropy_avail

Drivers

No touchpad settings available in GNOME control center

Problem

No touchpad settings are available in GNOME control center. This occurs when the BYD touchpad on Librem 13 rev1/Librem 15v2 is not detected/recognized.

Check

Check if the touchpad driver is loaded (execute this command in your terminal):

cat /sys/bus/serio/devices/serio1/protocol

If the command returns ImPS/2, then the BYD touchpad driver is not loaded.

Solution

Note

This only applies to laptops with BYD touchpads, notably Librem 13 rev1 and Librem 15 rev2.

Create a file (if doesn’t exist) /etc/rc.local with the following content:

#!/bin/bash
echo -n byd > /sys/bus/serio/devices/serio1/protocol

The file must be executable.

Terminal command to do all this:

sudo touch /etc/rc.local
sudo sh -c 'echo "#!/bin/bash\necho -n byd > /sys/bus/serio/devices/serio1/protocol" > /etc/rc.local'
sudo chmod +x /etc/rc.local

Restart the computer for this to take effect.

Missing firmware

Missing firmware for a device

Problem

A device on my computer does not work with PureOS. Logs say something about missing firmware.

Check

PureOS is designed to support only devices which do not require non-free/proprietary binary drivers or firmware, meaning it does not have such drivers/firmware. Check if your computer have such devices (AMD or nVidia graphics, Intel or newer Broadcom wireless LAN cards, etc).

Solution

Check if the firmware-linux-free package is installed. If it is not installed, install it. If the device requires non-free/proprietary binary drivers/firmware, it will not work in PureOS.

GNOME

Apps don’t see my folders for music, videos, etc.

Problem

Some of your apps cannot access your media directories (aka XDG directories). For example, you can’t choose picture from Pictures folder when setting background:

Solution

This usually happens if the xdg rules are missing. You can fix this by creating a file within $HOME/.config/user-dirs.dirs with the following content:

XDG_DESKTOP_DIR="$HOME/Desktop"
XDG_DOCUMENTS_DIR="$HOME/Documents"
XDG_DOWNLOAD_DIR="$HOME/Downloads"
XDG_MUSIC_DIR="$HOME/Music"
XDG_PICTURES_DIR="$HOME/Pictures"
XDG_PUBLICSHARE_DIR="$HOME/Public"
XDG_TEMPLATES_DIR="$HOME/Templates"
XDG_VIDEOS_DIR="$HOME/Videos"

Log out and then log back in. GNOME software will now detect your media files:

GNOME login screen does not appear

Problem

The system successfully booted, but the GNOME display manager (gdm3) login screen does not launch. Only a black screen with a login prompt appears:

Solution

In some cases it might help to reconfigure the GNOME login manager.

1. Login with your username/password at the prompt:

2. Run the following command:

sudo dpkg-reconfigure gdm3

Restart the computer to see if it fixes the problem.

See also

If the problem happened occurs a system upgrade, refer to Fixing broken system upgrade.

Right-clicking on the touchpad behaves as a left-click

Problem

Following a software update, the secondary touchpad button (right click) behaves like a primary (left click) button click when pressing on the right side of the touch pad.

Cause

This is an upstream issue. After an update, the upstream package overwrites the user preference (or changes the default behavior).

Solution

Change the mouse settings in GNOME Tweaks back to Area.

No logs displayed in GNOME Logs

Problem

GNOME Logs does not display any logs or crash reports. It may not launch at all (running gnome-logs from terminal may report a segfault).

Cause

Your user likely does not have permissions to read journal logs.

Solution

1. Add your user to the systemd-journal group:

sudo usermod -aG systemd-journal USERNAME

…where USERNAME is your username. You can find it by running the command:

whoami

Note

You must restart your computer for the group edit to be applied.

Application Menu Extension

Problem

You want to use the GNOME Applications menu but see in Tweaks that the GNOME Application Menu extension has not loaded and cannot be enabled.

Solution

1. From Show Applications, open the Utilities folder and open a terminal emulator.

2. Copy and paste the following into the terminal emulator:

sudo apt install gnome-menus

3. Press Enter.

4. Enter your password and follow the prompts.

5. Once it has completed, log out and log back into PureOS.

6. After your computer has booted, go into Tweaks and you should now be able to enable the Applications menu extension for GNOME.

GNOME Web jumps to maximum audio volume

Problem

GNOME Web jumps to maximum audio volume when playing sound

Cause

This is an issue that can occur when watching videos in GNOME Web. It is due to a configuration in the PulseAudio Daemon configuration.

Solution

1. Open the terminal emulator and run the following command to edit the configuration file:

sudo nano /etc/pulse/daemon.conf

2. You will be prompted for your user password; type it and press Enter.

3. Edit this line, from:

; flat-volumes = yes

to:

flat-volumes = no

4. Press Ctrl+X to exit nano.

5. You will be prompted to save the file. Press y and then press Enter to save the file without modifying the filepath. The editor will close.

6. Reboot your device to apply the changes.

Power Management

Suspend-Resume issues

Problem

Suspend/resume do not work.

Cause

There was a kernel regression causing suspend/resume issues with certain hardware.

Solution

Some suspend/resume issues are fixed when downgrading your kernel to 4.9.x.

See also

https://forums.puri.sm/t/problem-with-librem-13-v2-and-samsung-960-pro-with-temp-fix

Network

No internet access when connected to WiFi

Problem

THe system is successfully connected to a wireless network, but there is no Internet connectivity. The same WiFi connection is working on other devices.

Check

Check DNS settings.

1. Run the following command in a terminal emulator:

cat /etc/resolv.conf

Solution

1. Run the following command in a terminal emulator:

dpkg-reconfigure resolvconf

2. If this does not help, you can try manually adding another DNS address to the resolv.conf file. This may fix your connection. For example, you can add Google’s public DNS (8.8.8.8) or choose a DNS from the OpenNIC DNS list here (simply choose the first address). 3. Execute the following command in a terminal emulator to add this new DNS address to your /etc/resolv.conf file:

sudo sh -c 'echo "nameserver 8.8.8.8" > /etc/resolv.conf'

The effect of this change will be visible immediately. If you now have internet access, the problem was your DNS (or the network stack that did not update it correctly). Make sure to update your system later!

PureOS 10 has new firewall tools

In PureOS 10, iptables was moved to nftables. nftables is the preferred in kernel packet filter and firewalld is the tool for controlling firewalls on the desktop.

System

Changing the default root password

1. Open a terminal emulator and execute the following command:

sudo su

2. Type in your user account password and press Enter. You are now in superuser (root) mode. You can recognize this by looking at the terminal prompt. Before entering root terminal your prompt looks something like this:

username@hostname:~$

and after:

root@hostname:/home/username/

3. To change root password run:

passwd

You will be prompted to Enter new UNIX password:.

4. Type your desired password (it will not be printed out to the screen) and press Enter.

5. Type it in again to confirm.

Your new root password is now set.

Cannot run commands as sudo

Problem

You receive the following error when trying to sudo run a command:

Warning

<USERNAME> is not in the sudoers file. This incident will be reported

Solution

To add your username to sudoers list, add your username to sudo group:

1. Open Terminal app and log into root session with:

su

2. Enter your password once prompted.

3. Run the following command:

usermod -a -G sudo username

…where username is your login name (username). 4. Log out and then log back in.

You can now run commands using sudo.

Fixing a failed/partial system upgrade

Problem 1

The system can boot but GNOME does not start.

Solution

1. Press Ctrl+Alt+F2 to open another virtual terminal. You will see this screen:

2. Login by entering your username (press Enter afterwards) and then enter your password (press Enter to login):

3. You are now logged in and you should see something like this:

4. Type in the following command and press Enter, then enter your password and press Enter:

sudo dpkg --configure -a`

5. When the above command finishes, run the command to upgrade your system again:

sudo apt update && sudo apt full-upgrade

6. Re-install the pureos-gnome package:

sudo apt-get install pureos-gnome

Problem 2

The system cannot boot at all. Only a black screen is shown after the disk is unlocked.

Solution

1. Restart your computer, then wait until BIOS/Coreboot messages disappear and immediately press ESC to enter the boot loader menu.

2. Using the UP and DOWN arrow keys in the keyboard to navigate, select the Advanced Options menu item and press Enter.

3. Select one of the older kernel options from the list (lower on the list) and press Enter to boot it.

4. If you manage to boot into graphical interface, open your terminal and run:

sudo update-initramfs -u

5. Restart the system to see if it will boot normally.

Slow system startup

Problem

The system takes several minutes to start, but eventually it does get to the graphical user interface.

Check

You can check how much time the system exactly needed to start if you run this command in terminal:

systemd-analyze

It will output something like this:

mladen@librem13:~$ systemd-analyze
Startup finished in 3.517s (kernel) + 21.498s (userspace) = 25.015s
graphical.target reached after 21.490s in userspace
mladen@librem13:~$

To see how long each of the services took to start, run:

systemd-analyze blame

which should give:

Use the UP and DOWN arrow keys on your keyboard to scroll the output. Press the q key to exit the command.

To output this into a text file, use:

systemd-analyze blame > startup.log

which will create a startup.log text file in the directory you are currently in.

Solution

If you see some service took suspiciously longer time to start, you have to search the system logs to see if there is any particular problem. For example, running:

sudo journalctl -x -b -u NetworkManager-wait-online.service

will list logs just for this service, while running:

sudo journalctl -x -b

will allow you to examine all logs for the current boot session to see if there is any particular problem causing the slow system start.

Failed boot

Problem

The system is not booting.. It hangs after successful unlock of the disk encryption, and the Purism logo is displayed. Pressing the ESC key only shows a black screen with cryptsetup (sda5_crypt): set up successfully in the upper left corner.

Cause

This can happen when the system upgrade was interrupted or otherwise unsuccessful. Please see this section for a solution.

Cryptsetup setting deprecated

Problem

The following warning is displayed in a terminal emulator following a system update:

Warning

Setting CRYPTSETUP in /etc/initramfs-tools/initramfs.conf is deprecated and will stop working in the future. Use /etc/cryptsetup-initramfs/conf-hook instead.

Solution

1. Add CRYPTSETUP=y in /etc/cryptsetup-initramfs/conf-hook using the following command:

sudo sh -c 'echo "CRYPTSETUP=y" >> /etc/cryptsetup-initramfs/conf-hook'

Forgotten user password

Problem

You have forgotten your user password.

Solution

Reset your user password.

1. Boot PureOS in recovery mode.

Note

If you are using PureBoot, it is quite simple to enter to a recovery mode. From the main menu, select: Options → Boot options → Show OS boot menu → select “recovery” mode to boot (don’t make it default).

You will be asked to enter your disk password, type it in and press Enter. You will see this text:

You are in rescue mode. After logging in, type "journalctl -xb" to view
system logs, "systemctl reboot" to reboot, "systemctl default" or "exit"
to boot into default mode.
Press Enter for maintenance
(or press Control-D to continue):

2. Press Enter.

3. You will get into a terminal session. Type:

passwd USERNAME

…where USERNAME is your username (NOT your full name). If you forgot your username, type:

ls /home

…which will show your home folder. Its path contains your username.

4. Type the new password and press Enter.

5. Type it again to confirm and press Enter.

6. Type:

systemctl reboot

…and press Enter to reboot. Proceed as usual.

Browser

Firefox ESR consumes excessive CPU

Problem

Firefox ESR shows high CPU usage.

Solution

Try to enable hardware acceleration:

1. Open a new tab in Firefox ESR

2. Navigate to about:config

3. Accept the warning to continue

4. Search for vaapi (Video Acceleration API)

5. Change the flag to true (from false)

6. Fully close and restart Firefox ESR

Note

Make sure you have the gstreamer1.0-vaapi package installed.

PureBrowser to Firefox ESR

This guide describes the migration from a PureBrowser Profile (bookmarks, history, addons, etc) into Firefox ESR.

Method 1 (Command Line)

1. Launch PureBrowser

2. Click the menu button on the top right - Help - Troubleshooting Information.

The Troubleshooting Information tab will open. You r Profile Directory will be listed under the Application Basics section. Take note of path to the profile directory: /home/USER/.purism/purebrowser/USERSTRING.default

• If you have already migrated to Firefox, run cd ~/.purism/purebrowser/ and ls -al. This will list all files and directories. The directory named USERSTRING.default is the one you are looking for.

• If you have multiple USERSTRING.default, find the one with the date of the last time you used PureBrowser.

3. Open a terminal emulator and run cd ~/.purism/purebrowser/ and find the USERSTRING.default directory.

4. Run the update in Software, or apt, to now migrate to Firefox ESR.

5. Run cp -r USERSTRING.default ~/.mozilla/firefox/ to move the profile folder.

6. Now run firefox -P

7. Select Create Profile and then Next

8. Enter a profile name or leave as it. Then select Choose Folder.

9. Click on your the USERSTRING.default directory that you just moved over and press Open.

10. Click Finish and Start Firefox.

11. Firefox should load with all the tabs you had open before and everything else will have come over from PureBrowser. You are done!

Note

If wanting to use a search engine other than Google, you’ll need to go into the menu button on the top right - Preferences - Search - select your Search Engine of choice from the drop down.

Note

We have transitioned from uBlock Origin to EFF’s Privacy Badger. That should be the only difference in addons you see.

See also

Mozilla Firefox Knowledge Base

Method 2 (GUI)

Another way to move your old Purebrowser profile, to the new Firefox one is to move some parts of the Purebrowser profile folder to Firefox.

To do this:

1. Open your Files manager in your home folder and press Ctrl+h. This will show you the hidden folders.

Tip

Hidden folders/files always start with a . before the name.

You will see the folders .purism and .mozilla

Caution

Make a copy of both these folders as a backup before proceeding.

2. Close Firefox if it is open. If you need to have access to this tutorial during this process then, print this page as a PDF.

3. Open the .mozilla folder, then Firefox, then open the folder that has a name ending in default-esr

4. Delete the content of the folder that has a name ending in default-esr but do not delete the folder itself.

5. Open the folder .purism and then purebrowser and you will see a folder that also has a name that ends in default. Copy the contents of that folder to inside the folder default-esr in .mozilla/firefox/somestring.default-esr

6. Restart Firefox.

You should now see:

Note

Firefox uses Google as its default search engine. We recommand you select DuckDuckGo to replace Google as the default search engine.

Firefox compatibility mode

Cannot install Firefox add-ons

Enable Firefox Compatibility Mode to install add-ons from Mozilla add-ons website.

Note

You can search for web extensions available from the PureOS repo by running apt search webext in a terminal emulator.

1. Open PureBrowser and type about:config into the location bar, then press Enter. A warning will appear:

2. Click the I’ll be careful, I promise! button.

3. Type //useragent.compat// into the search bar.

4. Double-click the preference to change its value to true:

Note

This is already set to true in recent versions of PureBrowser, so you don’t have to change it.

5. Change your useragent string to install Firefox addons.

   1. Open about:config, right-click, select New -> String , enter general.useragent.override, and enter Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Firefox/68.0.2 as a string value.

   2. Click Okay and reload the page.

Testing PureBrowser first start issues

Question

I noticed an issue with PureBrowser the first time I started it and reported it. Since then I have been using PureBrowser and modified my browser profile such that the issue no longer occurs.

An update has landed and I want to confirm the fix. How can I do this without losing my new profile settings?

Answer

You can create a fresh profile. Launch PureBrowser, then delete the profile:

1. Close any running instances of PureBrowser

2. Start with purebrowser --ProfileManager

3. In the profile manager window, create a new profile “temp”

4. Click Start PureBrowser

You can now test for the first-start issue. When you are done…

1. Close any running instances

2. Start with urebrowser --ProfileManager

3. Delete the profile “temp” (delete profile and files)

4. Close the profile manager window

Miscellaneous

Screen flickering with Intel graphics

Problem

The screen is flickering on devices with Intel graphics.

Solution

A possible cause can be buggy Intel graphics power management. You can try disabling it by adding the i915.enable_rc6=0 boot flag.

1. To do this from a running system and make it permanent, run the following terminal command:

EDITOR=gedit sudo -e /etc/default/grub

The file /etc/default/grub will be opened in gedit with administrator privileges (so be careful with the next step).

2. Locate the GRUB_CMDLINE_LINUX line

3. Change it to look like this:

GRUB_CMDLINE_LINUX="i915.enable_rc6=0"

4. Save the file.

5. Run the following command in your terminal application:

sudo update-grub

5. Restart for this to take effect.

Note

Instead of gedit, you can use a text editor of your choice.

HP printer not working after upgrade

Problem

After upgrading from PureOS 9 to PureOS 10, an HP printer does not work despite being recognized properly.

Solution

It has been reported that removing ipp-usb is a workaround for this problem. Run this command:

sudo apt remove ipp-usb && sudo apt install hplip-gui