Skip to content

Changes

Page history
Add instructions on how to resize the ZRAM authored by gondolyr's avatar gondolyr
Hide whitespace changes
Inline Side-by-side
Tips-&-Tricks.md
View page @ 080a0a00
Since more and more people will start exploring their **Evergreen devices**, the same questions will most likely arise as in this first forum thread [here](https://forums.puri.sm/t/received-my-librem-5-evergreen/10877/12).
The intention of this section is to collect and conserve knowledge with respect to Tips & Tricks in dealing with the Librem 5 while ramping up and constantly improving.
[[_TOC_]]
## First steps for new Librem 5 users
Check out this post and watch the [Librem 5 Video Walkthrough](https://puri.sm/posts/librem-5-visual-walkthrough/).
**WARNING:** **Always** shut down the Librem 5 before inserting or removing either a SIM card or a uSD card.
## Known issues
For a full list of PureOS-related issues see the [issue tracker](https://source.puri.sm/Librem5/OS-issues/-/issues) entries.
### WiFi does not connect
If the Librem 5 won't connect to your network, [verify that the phone's date, time, and time zone are set correctly](https://forums.puri.sm/t/why-is-there-no-wifi/11107) in `Settings` > `Details` > `Date & Time`. At present, it's necessary to turn off the automatic date/time settings and set these manually. After successful connection, you can return the settings to automatic. If you're using MAC filtering on your router, don't forget to allow your Librem 5 in the router settings first. Using hidden SSID on your router may cause intermittent disconnection.
### PureOS updates fail after first setup
This is caused by an improper timezone or date/time setting required to configure the WiFi connection initially. Solution: [Re-enable the "Automatic Date & Time" setting](https://forums.puri.sm/t/myl5-unable-to-download-updates-for-librem-5-not-valid-yet-invalid-for-another-2h/12119) in `Settings` > `Details` > `Date & Time`
This issue has been solved in more recent versions of PureOS
### Standby mode
Currently the standby / suspend mode isn't enabled by default. Screen just gets dark.
Enable the suspend mode in `Settings` > `Power` > `Automatic Suspend`, see this [blog post](https://puri.sm/posts/librem-5-suspend-preview/).
### Battery fuel meter
[Needs adjustments](https://source.puri.sm/Librem5/linux-next/-/merge_requests/198) and for the time being is not precise. E.g. when fully loaded, the red charging led turns off and battery fuel meter indicates 70%. Recent improvements have synced the battery level indicator in the notifications area to the level in the Power settings panel.
To check the battery state from a shell use `upower -d`. Or read technical details with:
```plaintext
cd /sys/class/power_supply/max170xx_battery
cat capacity
65
cat temp
432
```
### Show battery percentage
By default the Phosh interface shows the battery level as a graphic.
You can show the battery percentage from the Settings app under the "Power" tab and under the the "Suspend & Power Button" section and enabling the "Show Battery Percentage" toggle.
To show the battery level as a percentage, use this command:\
`gsettings set org.gnome.desktop.interface show-battery-percentage true`
### GPS
GPS: Seems to work internally but user interfaces in PureOS are still missing (except switching GPS on and off in `Settings` > `Privacy` > `Location Services`). See <https://forums.puri.sm/t/app-for-gps-settings-on-librem-5/12136>
`Phosh` now acts as a `geoclue` agent so applications like `GNOME maps` and `Pure Maps` can use use location services with the internet connection to show your location on the maps; see: <https://puri.sm/posts/librem-5-news-summary-april-2021/>
### Reflashing Doesn't Use the Entire eMMC Storage - "Root partition is not enlarged"
Related Mobian issue and workaround: <https://gitlab.com/mobian1/issues/-/issues/440#note_1018769896>
[Reflashing the Librem 5](https://developer.puri.sm/Librem5/Development_Environment/Phone/Troubleshooting/Reflashing_the_Phone.html) may end up creating a root partition that does not use up the entire eMMC storage, usually with only 4GB with the rest being unallocated free space when this happens.
You can use the "Disks" app on the Librem 5 to check; select the "31 GB Disk" option when the app opens and it is usually listed as "Partition 2"; alternatively, you can use `df -h` to see and look for the line that says `/` in the "Mounted on" column.
This limited storage space can cause errors when attempting to install additional apps from the PureOS Store because there would not be enough space to install the apps or any system updates.
If the root partition isn't using all of the eMMC storage, these steps will resize the partition to use the entire eMMC capacity.
**Warning**: Before starting to resize a volume or its partition, a backup should be created. Follow these steps at your own risk!
1. From the Librem 5, open up the Terminal app.
2. Check to see the total size of the root partition by entering `df -h`. If the partition is only about 4 GB, then you have this issue.
```sh
$ df -h
Filesystem Size Used Avail Use% Mounted on
/dev/dm-0 3.6G 3.4G 54M 99% /
overlay 3.6G 3.4G 54M 99% /usr/lb/firmware
```
3. Use GNU Parted to resize the root partition. The following command will enter an interactive prompt.
```sh
$ sudo parted /dev/mmcblk0
```
4. Enter the following lines while in the GNU Parted prompt to resize the partition.
```sh
resizepart 2 30.5GB
quit
```
This will look like the following in the terminal app:
```sh
(parted) resizepart 2 30.5GB
(parted) quit
```
5. If the disk is encrypted, run the 3 following commands:
```sh
sudo cryptsetup resize /dev/mapper/crypt_root
sudo resize2fs /dev/mapper/crypt_root
```
6. Reboot the device.
```sh
sudo reboot
```
7. After the Librem 5 has rebooted, open up the Terminal app and check the partition size again with `df -h` to confirm that the root partition has a capacity of around 31 GB.
### Battery Drops to 0 in a Few Minutes
Original forum thread: https://forums.puri.sm/t/battery-dropping-from-40-to-0-in-a-few-minutes/19240
![image](uploads/e4298f2900e5fb7ec9172138cd9bf514/image.png)
This may happen due to the battery calibration getting out of sync.
The following steps should reset it:
1. Power off the device
2. Remove the battery
3. Re-insert the battery
4. Do a full discharge/charge cycle.
According to Kyle Rankin:
> over time my battery calibration skewed because I mostly have this phone plugged in at my desk or at a laptop dock, and it only runs for an extended time on battery when I run quick errands, As a result the battery monitor eventually became inaccurate
## General
### WiFi
To find out which WiFi card you have, enter the following command:
`nmcli -f GENERAL.DRIVER d show wlan0 | tr -s ' '`
For the Redpine Systems card, the field value that is output will be `RSI-SDIO WLAN`
For the SparkLAN card, the field value that is output will be `brcmfmac`
Note that the pipe through `tr` in the above command is just because the output of the command may be too wide for the default terminal window. You can leave off the pipe through `tr` _if_ your phone is in landscape mode _or_ you use `ssh` into your phone from another computer and therefore type the command from another computer.
### Backup
See this thread: <https://forums.puri.sm/t/new-post-app-showcase-backups/11459>. Alternatively: [Example of a quick backup solution](https://forums.puri.sm/t/received-my-librem-5-evergreen/10877/195) using rsync and a systemd timer
You can alternatively connect your phone to a host computer via USB, and boot Jumpdrive on the Librem 5. This will expose your phone's main (eMMC) drive and, if you have a uSD card in your phone, also your phone's uSD card as USB disk devices on the host computer. Then you can use any backup tool that is available on the host computer to backup the contents of your phone's disks using the host computer.
### Boot from SD card
A recent-enough version of u-boot is required before booting from the SD card is possible. The minimum supported version of u-boot is `2022.10`. To update you can either reflash a recent image, or install a deb from CI artifacts at <https://source.puri.sm/Librem5/uboot-imx> and invoke `sudo u-boot-install-librem5 /dev/mmcblk0` afterwards. A reboot is necessary to apply the update.
A compatible image can be written to the SD card and **during boot, hold volume-down**.
Beware that if you put the same image into eMMC and SD, you’ll end up with partitions with duplicated UUIDs, which may cause unexpected behavior during mounting.
**If** this applies then you can fix this by executing<br/>
<br/>
for x equal to 1 and then 2 (i.e. for each of the two partitions on the uSD card)
1. While the specific partition on the uSD card is **not** mounted, `sudo tune2fs -U random /dev/sdax`
2. `sudo tune2fs -l /dev/sdax | grep UUID` (in order to see what UUID was generated)
then
1. Mount `/dev/sda2` (i.e. mount the root partition of the uSD card) - let's say that you mount it at `/mnt`
2. Edit (as root) `/mnt/etc/fstab` (i.e. the `/etc/fstab` that is **on the uSD card**) to put the _new_ UUID value in on the line where the corresponding partition is mounted (the line that is mounting `/boot` for the first partition - gets the first new UUID value; the line that is mounting `/` for the second partition - gets the second new UUID value).
### Convergence
Purism Posts:
- <https://puri.sm/posts/my-first-week-of-librem-5-convergence/>
- <https://puri.sm/posts/my-first-year-of-librem-5-convergence/>
Convergence works with lapdocks such as the [NexDock 360](https://nexdock.com/support-nexdock-360/) and [UPERFECT X Mini](https://www.uperfectmonitor.com/products/uperfect-x-mini-lapdock-11-6).
See the "[Tested Accessories](https://source.puri.sm/Librem5/community-wiki/-/wikis/Tested-Accessories#laptop-shells)" wiki page for more devices.
### Dark mode
Not available out-of-the-box. Can be tweaked by using GNOME Tweaks app and set any theme you want there.
Alternatively, use [gsettings](http://manpages.ubuntu.com/manpages/trusty/man1/gsettings.1.html): `gsettings set org.gnome.desktop.interface gtk-theme "Adwaita-dark"`
UPDATE: See detailed tutorial below.
### Firewall
To enable [ufw](https://en.wikipedia.org/wiki/Uncomplicated_Firewall) (**u**ncomplicated **f**ire**w**all), open terminal and enter `sudo ufw status` and if it's not yet enabled, enter `sudo ufw enable`. The default is usually all you need, but you have the options of adding additional rules. Use `sudo ufw disable` to disable the firewall. To call up a graphical interface inside the terminal, first install gufw and install x11-xserver-utils. Next type the following command: `DISPLAY=:0 xhost +` and hit enter, resulting in: `access control disabled, clients can connect from any host`.\
Now type: `DISPLAY=:0 GDK_BACKEND=x11 sudo gufw` and the graphical version will appear right in the terminal. Note that after you close the terminal, the app icon in the phone's app list will not be operational unless you repeat the above process, at least unless someone adapts it later.
### Flash Mode (USB Download Mode)
Flash mode, or USB download mode, is useful for [reflashing your Librem 5](https://developer.puri.sm/Librem5/Development_Environment/Phone/Troubleshooting/Reflashing_the_Phone.html) or for enabling [Jumpdrive](https://github.com/dreemurrs-embedded/Jumpdrive) to mount the internal storage as a USB disk.
1. Ensure that the phone is powered off.
2. Turn off **all** Hardware-Kill-Switches.
3. Remove the battery.
4. Hold volume-up.
5. Insert the USB-c cable to the Librem 5 and connect it to a computer (red light blinks, no green light).
6. Reinsert the battery (red light is constantly on).
7. Release volume-up.
**Note**
From <https://forums.puri.sm/t/cant-use-l5-after-update/16245/229>:
> Technically, you don’t need to do the battery dance, but the instructions tell you to do so because it increases the chances of it working in some edge cases, like battery being flat, or SoC being stuck in some weird state. This helps because of the LED feedback you get when there’s no battery in - so you can match the LED output you see with the instructions and know that things are going well, there’s enough power available for phone to actually run etc. Without that, there’s no indication of progress, as the only feedback USB download mode gives that informs you it actually booted into USB download can only be seen over USB, so if you don’t see it on your PC you’re pretty much in the dark and figuring out why it’s not working is mostly trail-and-error. With these slightly more annoying instructions, we can at least weed some common failure cases out early
### IMEI
To find the IMEI of your Librem 5, go to `Settings` > `Mobile` > `Modem Details`.
You can also get this information with: `mmcli -m any | grep imei`
### Notifications
Accessed by touching the battery icon at the top right corner of the screen.
### Ringtones
The [phosh-mobile-settings](https://gitlab.gnome.org/guidog/phosh-mobile-settings) app now allows customizing the phone call ringtone, SMS, and instant messages alerts as of 0.27.0. It can be found under the Feedback tab. Only OGG files are supported right now.
Customize rintones following this [blog post](https://sspaeth.de/2021/03/customizing-the-librem5-ringtone/).
### Root account
Locked by default. So there is no root password available. More technical details [here](https://source.puri.sm/Librem5/image-builder/-/merge_requests/123). Unlock root account with `sudo passwd`, check out [this discussion](https://forums.puri.sm/t/what-does-locking-the-root-password-do/10895) for more background.
You can start a shell as `root` by running the command: `sudo -s`
### Terminal
Access additional Terminal keyboard controls by clicking on the globe icon (reveals Ctrl, Alt, and arrow keys, plus other symbols, controls, and Function keys - including Esc and Tab; press the `>_` key to see the extras).
Here's a quick and fun introduction to basic Terminal commands: <https://ubuntu.com/tutorials/command-line-for-beginners#1-overview>
### Username
Default user name is: `purism`. Additional user names can be added from the terminal; at present this is not supported in the `Settings` GUI.
### Auto-mounting directories
When manually adding entries in /etc/fstab, specify the `nofail` option (in the 4th field) so that any problem with the device will not prevent the operating system from booting.
### Screen Orientation
`Phosh` supports automatic screen orientation. To enable or disable it toggle the button in the notifications area.
### Hostname
The default hostname is `pureos`. In order to change the hostname you need to edit, as root, both `/etc/hostname` and `/etc/hosts`
### Lock delay
To delay requiring a password for 60 minutes after the Power button is pressed to blank the screen, issue [this command](https://gitlab.gnome.org/World/Phosh/phosh/-/merge_requests/1012) from the terminal:
`gsettings set org.gnome.desktop.screensaver lock-delay 3600`
Note: If the Librem 5 is coming out of suspension, it will still require the password.
## Software installations and updates (apps and OS)
### Install Software
In case installing software from PureOS store does not work --> Do it from terminal, e.g. `sudo apt install firefox-esr`. Note that PureOS store, by default, lists software that has been adapted to the Librem 5's screen. Other packages can be found and installed using the search tool within the store, but may not scale well to the screen without further modification. You can use the application `Mobile Settings` in the `Compositor` section, to scale the specific application. For this to work the application in question needs to be open at the same time as the `Mobile Settings` app.
### System/Software Updates
Click `Updates` tab within the PureOS Store (and per [this issue](https://source.puri.sm/Librem5/pureos-store/-/issues/20 'First press of "Restart & Update" button does not work, only second attempt works'), hit the `Restart & Update` button _twice_); or, install from the **Terminal** by entering:\
`sudo apt update && sudo apt upgrade`\
(sudo = superuser do / i.e. admin level action)
### Enable Flatpak with Flathub repository
Flatpak support and PureOS store integration are installed by default. Only need to add the Flathub repository via the terminal as described in their setup description [step 3](https://flatpak.org/setup/Debian/) For example:\
`flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo`
#### Customize Flatpak Installation Location
Source: <https://docs.flatpak.org/en/latest/tips-and-tricks.html#adding-a-custom-installation>
> By default Flatpak installs apps system-wide, and can also be made to install per-user with the --user option accepted by most commands. A third option is to set up a custom installation, which could be stored on an external hard drive.
>
> First ensure that the config directory exists:
>
> ```sh
> $ sudo mkdir -p /etc/flatpak/installations.d
> ```
>
> Then open a file in that directory as root:
>
> ```sh
> $ sudoedit /etc/flatpak/installations.d/extra.conf
> ```
>
> And write something like this:
>
> ```ini
> [Installation "extra"]
> Path=/media/purism/mysdcard/flatpak/
> DisplayName=Extra Installation
> StorageType=sdcard
> ```
>
> [...] Replace the path with the actual path you want to use.
>
> Then you can add a remote using a command like:
>
> ```sh
> $ flatpak --installation=extra remote-add flathub https://flathub.org/repo/flathub.flatpakrepo
> ```
>
> And install to it with:
>
> ```sh
> $ flatpak --installation=extra install flathub org.inkscape.Inkscape
> ```
If you use Flatseal to manage Flatpak permissions, [apps may not be listed](https://github.com/tchx84/Flatseal/issues/502) and you will need to grant Flatseal the `host:ro` filesystem permission.
[Flatseal Documentation](https://github.com/tchx84/Flatseal/blob/master/DOCUMENTATION.md#use-custom-flatpak_user_dir)
```sh
flatpak --user override --filesystem=host:ro com.github.tchx84.Flatseal
```
### Add App to favorites:
To add an app from your app list to the Favorites section (i.e. pin to the top of the list), long-press on the app, then select `Add to Favorites`. The Favorites section expands to accommodate the new favorite app. To remove an app from Favorites, long-press the app, then select `Remove from Favorites`.
### Web Apps
You can create an app icon from a web page in the browser as shown in the [Video Walkthrough](https://puri.sm/posts/librem-5-visual-walkthrough/) at position 2m:20s. Deletion / adaption via [Web Application Manager](https://docs.puri.sm/Librem_5/Web.html#web-applications).
### Android Apps (Waydroid)
See: https://source.puri.sm/Librem5/community-wiki/-/wikis/Software/Waydroid
## Recommended applications for common use cases
See this [comprehensive list of mobile-optimized apps](https://tracker.pureos.net/w/pureos/mobile_optimized_apps). A sampling of tested applications, including screenshots, can be found at: <https://forums.puri.sm/t/list-of-apps-that-fit-and-function-well-post-them-here/11361>
### File manager
Nautilus is adaptive on both Amber and Byzantium.
Alternative: [nemo](https://en.wikipedia.org/wiki/Nemo\_%28file_manager%29) scales well without additional tweaks, especially in landscape. It can be installed with the command: `sudo apt install nemo`, or search and install within PureOS store.
You can also install `Portfolio` file manager.
[GNOME Files](https://wiki.gnome.org/Apps/Files) is adaptive since [version 43](https://release.gnome.org/43/#files-refresh).
### Screenshots
Install `librem5-goodies` (e.g. in the terminal with the command `sudo apt install librem5-goodies`). After the installation it will add several apps to the app tray: `Screen Shot` ... along with other included apps.
## Application life-cycle
* To **close an application** touch the "roof" symbol on the bottom of the screen which shows a carousel of open apps. From there you can close an app by tipping and swiping it up to the upper part/top of the mobile phone
* To [close a blocked/hanging application](https://forums.puri.sm/t/how-to-kill-stop-a-blocked-non-responding-app-on-librem-5/12133) you can use the terminal and the `killall` command or use the app `Usage` (installed by default) where you can find the process of the app if you scroll down, tip on the app name and choose "Force quit".
## USB
### Mount USB sticks
USB drives are automatically recognized and mounted (you get a notification where you can open the mounted folder in a file manager).
### Unmount (eject) USB sticks
This requires to use the `umount` command in the terminal or (easier) eject via the `nautilus` or [`nemo` file manager](https://forums.puri.sm/t/how-to-eject-usb-drive-from-librem-5-with-a-gui/12132): Select the mounted USB drive in the device tree node in `nautilus` or `nemo`, the choose `eject` in the `File` menu so safely unmount the USB drive
## Calls
### Calls/Voice quality
Adjust Internal Microphone volume in `Settings` > `Sound` for optimal clarity.
### Calls from terminal
`xdg-open tel://<phone-number>` as seen [here](https://social.librem.one/@eliasr/105243293093757846).
### Mobile Settings
While Mobile is disabled, either by the settings toggle or by the kill switch, granular Mobile Settings are inaccessible. Also, at the moment, saved messages in Chats cannot be viewed, nor new messages composed; a fix for this is being worked on, and the issue does not affect other installed messaging apps, and also not other chat protocols used by chatty (e.g xmpp), if any.
### Send SMS (text message) from terminal
At the current time, this is a bit untidy but it can be done.
```plaintext
# Pause chatty
killall -STOP chatty
# Create SMS and save its id
id=`sudo mmcli -m any --messaging-create-sms="text='your-content',number='dest-phone-number'"`
# id is e.g. Successfully created new SMS: /org/freedesktop/ModemManager1/SMS/6
id=${id/?*\/*\/*\/*\/*\/}
# strip that back to just the number e.g. 6
echo id = $id
# Send SMS
sudo mmcli -s $id --send
# Resume chatty
killall -CONT chatty
```
In my testing, the dest-phone-number did not have to be a full international-format mobile number. Your mileage may vary.
Unless you are a bash wiz it would be best to avoid any quote characters (\` " ') in your-content.
If scripting this then it might be wise to wait until the text message is actually sent before resuming `chatty`. You can get the status of the message with: `mmcli -m any --messaging-list-sms`
As an aside, if your Librem 5 becomes gummed up with an MMS that you can't receive and process (yet) then you can list it with the previous command and then delete with: `sudo mmcli -m any --messaging-delete-sms=index` where `index` is replaced with the message number to delete.
## Mail (Geary)
* If the incoming mail server or the outgoing mail server require a port number then specify the hostname as `hostname:portnumber`
* There is no support for the POP protocol. Mail can only be received using the IMAP protocol.
* Config information is stored in `/home/purism/.config/geary/account_01/geary.ini` (or replace `_01` with subsequent numbers if more than one account)
## Contacts
### Import contacts
The default contact application `gnome-contacts` supports importing and exporting contacts from a vcard (`.vcf`) file. To import contacts from a `.vcf` file via Bluetooth the `librem5-goodies` package that you can install from the command line, can do this. It also has two scripts (`l5-contacts-importer` and `l5-contacts-exporter`) that you can use to import and export contacts from a terminal.
Import from SIM card is currently not supported. But it is possible to extract the contacts in the SIM card to a text file, with the following command:
`echo AT+CPBR=1,250 | socat - /dev/ttyUSB3,crnl > sim-contacts.txt`
If your user is not added to the dialout group then you will need to run the above command with `sudo`
`echo AT+CPBR=1,250 | sudo socat - /dev/ttyUSB3,crnl > sim-contacts.txt`
Contacts information appears to be stored in:\
`/home/purism/.local/share/evolution/addressbook/system/contacts.db`
### General Carddav and Caldav functionality
Install the `evolution` package from the command line, add regular Carddav and Caldav accounts via Evolution interface, attach [external screen](https://forums.puri.sm/t/myl5-librem-5-evergreen-first-impressions/11217/59?u=5a54a) (Evolution is not adaptive for Librem 5).
## Locale
If you have set a specific locale (e.g. en_AU.UTF-8) then you will probably get warnings all over the place (e.g. from `man`, `locale` itself, from `perl` during an install). The solution appears to be:\
`sudo dpkg-reconfigure locales`\
Then page down to your chosen locale, press the space bar to select it - `[ ]` will change to `[*]`, then Tab to move to Ok then Enter.\
That will then take an eternity generating all the selected locales and eventually doing the one that you just selected.
## Network Config
Network Manager stores the configuration in `/etc/NetworkManager`. Specifically, information that is per-connection is stored in the `system-connections` subdirectory in files called `xyz.nmconnection` where xyz is the connection name.\
The proper way to 'get' and 'set' per-connection settings, if wanting to do from the command line, is via the `nmcli` command.
* Show the connections that exist: `nmcli conn show`
* Show a specific connection where uuid is as listed by the first command:\
`nmcli conn show uuid | grep whatever`
* Retrieve a specific field: `nmcli -g fieldname conn show uuid`
* Modify a specific field: `nmcli conn modify uuid fieldname fieldvalue`
## Modem Manager
To get modem information:
* Using the command: `mmcli -m any` will display information on all modems installed on the device, in the case of the Librem 5, there is only one.
Likewise to get SIM information, you can use the command: `mmcli -i any` That will show you your IMSI and your ICCID, among other pieces of information.
But you can also search explicitly to get modem indexes and SIM indexes.
* Firstly, `mmcli -L` to list the modems. For example, gives: /org/freedesktop/ModemManager1/Modem/**1**
- so the modem index to use at this moment in time is ‘1’.
* Then, `mmcli -m M` where M is replaced with the modem index.
* You can check, in passing, your own phone number (`mmcli -m M | grep own:`) and get the SIM index (`mmcli -m M | grep SIM`)
* You can also check what mobile network you are on with `mmcli -m M | grep operator`. The operator id comprises three digits for the Mobile Country Code (MCC) followed by two or three digits for the Mobile Network Code (MNC).
* The output for the SIM index looks like: SIM | dbus path: /org/freedesktop/ModemManager1/SIM/**1** - so the SIM index is 1.
* Finally, `mmcli -i S` where S is replaced with the SIM index.
* `-i` and `-m` are abbreviated forms of `--sim` and `--modem` respectively.
## Executing an AT command on the modem
There are two ways of doing this.
Method A:
`mmcli` can execute an AT command for you but Modem Manager has to be in "debug" mode for that to work. So:
change the ExecStart line in the file `/lib/systemd/system/ModemManager.service` by adding `--debug` so that the line looks like this:
`ExecStart=/usr/sbin/ModemManager --debug`
After that, run the following commands to make the change take effect:
```plaintext
sudo systemctl daemon-reload
sudo systemctl restart ModemManager.service
```
Then Modem Manager should be running in debug mode, and you can execute an AT command on the modem e.g.
`sudo mmcli -m any --command=ATI`
The `ATI` command is useful to identify the make and model of modem e.g. what variant of the Broadmobi 818 you have.
This approach has the advantage that if you want to execute the same command more than once, you can repeat the command in the shell.
It is _recommended_ that you take Modem Manager out of debug mode once you have finished i.e. revert the change to the file that you edited above and re-execute the two `systemctl` commands.
Method B:
You can communicate directly with the modem. This involves installing a program like `minicom`, so do that first:
`sudo apt install minicom`
Then `mmcli -m any | grep ttyUSB`
The output will look like:
```plaintext
| ports: cdc-wdm0 (qmi), ttyUSB0 (qcdm), ttyUSB1 (at), ttyUSB2 (at),
| ttyUSB3 (at), wwan0 (net)
```
Pick any `ttyUSBn` device that is followed by `(at)` e.g. in the above output 1, 2 and 3 are good to use.
`sudo minicom -D /dev/ttyUSBn`
Type Ctrl/A and then E in order to enable local echo.
Type your AT command(s) e.g.
`ATI`
Type Ctrl/A and then X in order to exit from `minicom`.
## Mobile Country Reference Data
* Reference data for APNs (used to access the internet on the mobile network) is stored in the directory `/usr/share/mobile-broadband-provider-info`
* Reference data for international dialling is stored in the locale file, in the LC_TELEPHONE section e.g. `/usr/share/i18n/locales/ll_CC` where `ll` is the language code and `CC` is the country code.
## Managing Journals
By default, the Librem 5 uses `journald` for system journaling.
The system journal can get very big, which consumes significant scarce disk space and makes the journal slow to find things in. Use
`journalctl --disk-usage`
to see how much disk space is being used by all journal files.
To have the system journal automatically cleaned periodically, edit the file `/etc/systemd/journald.conf` and set values for `SystemMaxUse` and `MaxFileSec`. Unless you are specifically trying to troubleshoot an infrequent problem, values of `500M` and `1month` are reasonable.
By default `journald` will forward to `syslogd` but by default a suitable `syslogd` won't be running and so the forwarded messages won't go anywhere. If you prefer to use `syslogd`, rather than `journald`, for examining logged messages then
`sudo apt install rsyslog`
or such other implementation of `syslogd` as you prefer.
Note that the command to examine logged messages via `journald` is `journalctl` whereas messages logged by `syslogd` go in `/var/log/syslog` (unless you configure otherwise).
## Tutorials
### SECURE SHELL (`ssh`)
_Note that using the L5's passcode to log in remotely provides relatively weak security. See related tutorials for better authentication solutions._
SECURE SHELL Logging in remotely to the L5’s terminal in order to execute commands
On your computer (the client): `sudo apt update && sudo apt upgrade`
Then:
`sudo apt install openssh-client`
On the Librem 5 (the remote device, the server): `sudo apt update && sudo apt upgrade`
Then:
`sudo apt install openssh-server`
Confirm that it worked (i.e. is “active”): `sudo systemctl status ssh`
If not active: `sudo systemctl enable ssh`
If firewall blocks `ssh` on the remote device: `sudo ufw allow ssh`
Other firewall options available: `stop` `start` `disable`
Determine IP address of the remote device (L5):
Available in the `What IP` app, or via the L5’s terminal:\
`ip address` or `ifconfig`
or log in to your router to find the L5’s IP address.
To log in over WiFi to the remote device (L5) from your computer:\
`ssh Librem5-username@REMOTE.IP.ADDRESS.HERE`
Example: `ssh purism@192.168.xxx.xxx`
For clarity, if you omit the `Librem5-username@` then `ssh` will default the remote username (the username on the Librem 5) to the local username (the username on your computer). Unless your computer is _another_ Librem 5, this is unlikely to be what you want. Hence, in most cases, you **must** specify in the `ssh` command the username on the Librem 5, which is `purism` on a new (unmodified) install of the Librem 5 software.
Type the word “yes” at the next terminal question, then provide the password to your L5. The following prompt will appear:\
`purism@pureos:~$`
You are now logged into your L5 from your computer’s terminal, and can easily execute any terminal commands remotely. This also makes it easy to copy terminal output and paste it here in the forum or elsewhere.
You can also connect your L5 to your computer over USB and use `ssh` via a `Shared Connection` in your computer’s network settings.
In the settings panel of the L5, under `Sharing`, you should now see that Remote Login is `On`. At the top of this panel, you can use the toggle to enable or disable remote sharing for security purposes.
To exit `ssh`, use the command `exit` in the terminal.
### SSH File Transfer Protocol (`sftp`)
Once `ssh` is set up, a simpler way to remotely access files on the Librem 5 is with `sftp`.
With both devices powered on, from the host machine:
\-Open the file browser
\-Type `Control`+`L` to bring up the location bar
\-Enter `sftp://xxx.xxx.xxx.xxx` (filling in the IP address of the L5
\-Authenticate with the L5's password
This will mount the L5's file system. Navigate to the `Home` directory and the desired sub-directory to copy, cut, or paste as you like.
TIP: Bookmark the L5's IP in your file browser to access it with a mouse click whenever you want (as long as the L5 is powered on).
### SECURE COPY (`scp`)
Copying files and folders remotely between devices on your network
_Note that using the L5's passcode to log in remotely is relatively weak security. See related tutorials for better authentication solutions._
With `ssh` enabled, you can use the Secure Copy command (`scp`) to copy files or entire folders from the L5 to your computer, and vice versa. Note that in order to perform `scp`, you _do not_ log in to the L5 via `ssh` first.
The syntax is:\
`scp remote_username@REMOTE.IP.ADDRESS.HERE:/remote/file.txt /local/directory`
Examples:
`scp purism@192.168.xxx.xxx:/home/purism/example.txt /home/yourusername/Desktop` would copy the file example.txt located in the L5’s Home folder to the desktop of your computer.
`scp purism@192.168.xxx.xxx:/home/purism/Pictures/2021-04-12-example.png /home/yourusername/Desktop` would copy the image 2021-04-12-example.png located in the L5’s Pictures folder to the desktop of your computer.
To copy an entire folder from the L5 to your computer:
`scp -r purism@192.168.xxx.xxx:/home/purism/Pictures /home/yourusername/Desktop` will copy the folder “Pictures" from the L5 to your computer. (More convenient than copying individual images or files one at a time, in case there are many to copy.) The `-r` after `scp` stands for “recursive,” indicating that the copy action should continue until all is copied.
To copy a file from your computer to the L5, the syntax is:
`scp file.txt remote_username@REMOTE.IP.ADDRESS.HERE:/remote/directory`
If the file is not located in your computer’s Home directory, first change directory to the location of the file, using the command `cd`, for example `cd Desktop`, if the file is on your desktop, and so on.
Example, from your Home directory:
`scp example.txt purism@192.168.xxx.xxx:` (Use the actual ip address of your L5. This places the file in the L5’s Home directory.)
`scp example.txt purism@192.168.xxx.xxx:/home/purism/Documents` (This goes to the L5’s Documents folder.)
**TIP:** Although you perform `scp` without logging in to the other device with `ssh`, it may be helpful to use `ssh` first in order to list (`ls`) the contents of a folder so that it will be easy to copy and paste the name of a file or files for `scp`. Just be sure to exit `ssh` before you use `scp` or you’ll get an error.
(Related discussion on this topic can be found in the community forum: <https://forums.puri.sm/t/tutorial-using-ssh-and-scp/13080>)
### ENHANCING SECURITY FOR SECURE SHELL (`ssh`)
Relying on the L5's passcode when using `ssh` for remote access provides relatively weak security. See below for more secure options.
* **_Option 1:_** Use private/public key-pair authentication, and disable password-based authentication for remote login.
These instructions will also work with a Unix/Linux-based server, or the Pinephone.
Enable ssh access to your Librem 5. (See related tutorial.)
On computer, generate the public/private RSA keys.
Open a Terminal session on your computer and type the following command:
`ssh-keygen -t rsa` OR `ssh-keygen`
```plaintext
Enter file in which to save the key (/home/{YOUR_ID}/.ssh/id_rsa):
Created directory ‘/home/{YOUR_ID}/.ssh’.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/{YOUR_ID}/.ssh/id_rsa.
Your public key has been saved in /home/{YOUR_ID}/.ssh/id_rsa.pub.
```
On computer, copy the contents of the id_rsa.pub key onto the Librem 5. The following command will log into your Librem 5, and configure the keys to grant access via the authorized_keys file.
`ssh-copy-id -i ~/.ssh/id_rsa.pub purism@host`
(example: `192.168.xxx.xxx`, substitute with your ip address)
You will be asked for your password into the Librem 5 in this step. Only your public key is copied. Always keep your private key private.
Restart your phone.
On computer, login to your phone using key-based authentication
`ssh purism@host` (ex. `ssh purism@192.168.xxx.xxx`)
On Librem 5, disable password-based authentication
`ssh purism@host`
Use an editor like `nano` or `vim` to edit the following `/etc/ssh/sshd_config`, using admin rights.
`sudo nano /etc/ssh/sshd_config`
Find the following line:
`PasswordAuthentication yes`
And change it to:
`PasswordAuthentication no`
If there is a # (this means "commented out", that is, excluded from the command/script) at the beginning of that line, remove it.
Save the file after making these changes and restart the SSH service using this command:
`systemctl restart ssh`
To test that password-based authentication is actually disabled, from computer, try to `ssh` into the Librem 5 using a different (or non-existent) id:
`ssh otherid@host`
You should get the following error: `otherid@host: Permission denied (publickey)`
You have now successfully disabled password based authentication in `ssh`.
(Related discussion on this topic can be found in the community forum: <https://forums.puri.sm/t/tutorial-enable-key-based-authentication-via-ssh-on-your-librem-5/13137>)
### Setting a Custom Background in Phosh
Selected background image can be a .jpg or a .png, possibly other file types.
In the terminal, create the file `gtk.css` (if it doesn't already exist) using any installed text editor: `nano ~/.config/gtk-3.0/gtk.css`. Alternately, you can create the file manually in the `Files` app.
Then add the following to the `gtk.css` file. (Change the path to point to your chosen image.)
```plaintext
/*
* Set a background for the lockscreen.
*/
phosh-lockscreen, .phosh-lockshield {
background-image: linear-gradient(rgba(0, 0, 0, 0.7), rgba(0, 0, 0, 0.7)),
url('file:///home/purism/Pictures/mybackground.jpg');
background-size: cover;
background-position: center;
}
/*
* Set a background for the app grid.
*/
phosh-app-grid {
background-image: linear-gradient(rgba(0, 0, 0, 0.7), rgba(0, 0, 0, 0.7)),
url('file:///home/purism/Pictures/mybackground.jpg');
background-size: cover;
background-position: center;
}
```
Then: `sudo systemctl restart phosh`.
The background image can be set to different levels of transparency by changing the "0.7" entries above to anything on the scale of "0.0" (fully transparent) to "1.0" (fully opaque). It’s a linear-gradient effect, so the first 0.7 is transparency starting on top, and the second 0.7 is transparency ending at bottom.
You can also change the gnome background. (This is not needed in pureos-byzantium, as a graphical option is present.):
```plaintext
`gsettings set org.gnome.desktop.background picture-uri file:///path/to/picture_file`
```
e.g. `gsettings set org.gnome.desktop.background picture-uri file:///home/purism/Pictures/image.png`
### Creating a Shortcut to Execute a Terminal Command
As an [example](https://forums.puri.sm/t/tutorial-create-a-shortcut-to-modem-info/16886), the following will create a shortcut to modem info, similar to using Android's `*#*#INFO#*#*` service code.
First, find an appropriate icon, edit it if desired, name it (e.g. modem.png), and save it to `.local/share/icons`, creating the `icons` folder if it doesn't exist already.
Next, create the shortcut button in `.local/share/applications`, naming it e.g. `ModemInfo.desktop`. This will insert the icon/launcher into the home screen's app grid.
In the terminal, enter `mmcli -L` to retrieve the modem's single-digit identifier. In this example, the command returns `/org/freedesktop/ModemManager1/Modem/0 [QUALCOMM INCORPORATED] 0`, which indicates "0" as the identifier. We can now run `mmcli --modem=0` to manually retrieve the detailed modem and mobile network information. (If there is only one modem installed, you can skip `mmcli -L` and change `mmcli --modem=0` to `mmcli --modem=m any`.)
Next, to enable the app screen launcher to run `mmcli --modem=0` (or `mmcli --modem=m any`), copy the following text into the `ModemInfo.desktop` file, which was created previously in `.local/share/applications`:
\[Desktop Entry\] Name=ModemInfo Exec=gnome-terminal -x bash -c “mmcli --modem=0 | tee modeminfo.txt; exec bash” StartupNotify=true Terminal=false Type=Application Categories=Utilities; Icon=/home/purism/.local/share/icons/modem.png
The above automates opening the terminal, running the command, and also saves the terminal output to a text file (`modeminfo.txt`) in the home folder, as well as setting the icon to use as the launcher, all from a single tap on the app icon. The text file will be overwritten every time.
At this point, either view the output in the terminal opened by the launcher, or close the terminal and view the text file instead.
For another example, see how to create a launcher to [quick-dial a frequent telephone number](https://forums.puri.sm/t/howto-make-a-quickdial-button/12560).
### Enable Adwaita-dark theme using `GNOME Tweaks`
A convenient way to enable dark mode:
Find and install `Adwaita dark GTK theme` from the PureOS software app.
Find and install `GNOME Tweaks`. `Tweaks` doesn’t (currently) fit the screen unless you run this:
`gsettings set sm.puri.phoc.application:/sm/puri/phoc/application/org-gnome-tweaks/ scale-to-fit true`
The above command should work with any GNOME app that needs permanent scaling down; just change the package name as applicable. Use `...scale-to-fit false` to turn it off again.
Alternatively, you can use the Displays sub-menu in the Librem 5’s Settings app to scale to different resolutions on an _ad hoc_ basis.
Tap the `Tweaks` app icon. Only landscape view is completely usable (currently)…and the text will be tiny; activate Adwaita-dark in the Themes sub-menu.
GNOME apps will now display in dark mode. To revert to Adwaita (light theme), select it in the Tweaks app.
### Add a Swap File
**Please consider reading https://www.kernel.org/doc/html/latest/admin-guide/blockdev/zram.html#optional-feature about _writeback_ if you already configured _zramswap_ like described in the forums. This entry might need additional information/correction about the advantages and disadvantages of zramswap and traditional swap on disk.**
If you find yourself running out of RAM, you may want to consider creating a Swap file.
From [this Linuxize tutorial](https://linuxize.com/post/create-a-linux-swap-file/):
> Swap is a space on a disk that is used when the amount of physical RAM memory is full. When a Linux system runs out of RAM, inactive pages are moved from the RAM to the swap space.
>
> Swap space can take the form of either a dedicated swap partition or a swap file. In most cases, when running Linux on a virtual machine, a swap partition is not present, so the only option is to create a swap file.
1. Create a file that will be used for swap. The example below will add 1GB of swap; if you want more, such as 2GB, substitute `1G` with the desired amount (e.g. `2G` for 2GB).
```sh
sudo fallocate -l 1G /swapfile
```
2. Only the root user should be able to write and read the swap file. To set the correct permissions type:
```sh
sudo chmod 600 /swapfile
```
3. Use the `mkswap` utility to set up the file as Linux swap area:
```sh
sudo mkswap /swapfile
```
4. Enable the swap with the following command:
```sh
sudo swapon /swapfile
```
To make the change permanent, open the `/etc/fstab` file and append the following line:
```
/swapfile swap swap defaults 0 0
```
5. To verify that the swap is active, use either the `swapon` or the `free` command as shown below (The output values shown are just samples):
```sh
$ sudo swapon --show
NAME TYPE SIZE USED PRIO
/swapfile file 1024M 507.4M -2
```
```sh
$ sudo free -h
total used free shared buff/cache available
Mem: 488M 158M 83M 2.3M 246M 217M
Swap: 1.0G 506M 517M
```
### Resize Swap File Size
If you find that the swap file is too large or too small, you can resize it.
1. Before you resize the swap file, you should turn the swap off. You should also make sure that you have enough free RAM available to take the data from swap file. Otherwise, create a temporary swap file.
```sh
sudo swapoff /swapfile
```
2. Now use the `fallocate` command in Linux to change the size of the swap file. The example below will resize the swap file to 4GB of swap; if you want more, such as 8GB, substitute `4G` with the desired amount (e.g. `8G` for 8GB).
```sh
sudo fallocate -l 4G /swapfile
```
3. Mark the file as a swap file:
```sh
sudo mkswap /swapfile
```
4. Enable the swap file:
```sh
sudo swapon /swapfile
```
To make the change permanent, open the `/etc/fstab` file and append the following line:
```
/swapfile swap swap defaults 0 0
```
This may already exist from creating a swap file before so don't add a duplicate entry if that's the case.
\ No newline at end of file
Since more and more people will start exploring their **Evergreen devices**, the same questions will most likely arise as in this first forum thread [here](https://forums.puri.sm/t/received-my-librem-5-evergreen/10877/12).
The intention of this section is to collect and conserve knowledge with respect to Tips & Tricks in dealing with the Librem 5 while ramping up and constantly improving.
[[_TOC_]]
## First steps for new Librem 5 users
Check out this post and watch the [Librem 5 Video Walkthrough](https://puri.sm/posts/librem-5-visual-walkthrough/).
**WARNING:** **Always** shut down the Librem 5 before inserting or removing either a SIM card or a uSD card.
## Known issues
For a full list of PureOS-related issues see the [issue tracker](https://source.puri.sm/Librem5/OS-issues/-/issues) entries.
### WiFi does not connect
If the Librem 5 won't connect to your network, [verify that the phone's date, time, and time zone are set correctly](https://forums.puri.sm/t/why-is-there-no-wifi/11107) in `Settings` > `Details` > `Date & Time`. At present, it's necessary to turn off the automatic date/time settings and set these manually. After successful connection, you can return the settings to automatic. If you're using MAC filtering on your router, don't forget to allow your Librem 5 in the router settings first. Using hidden SSID on your router may cause intermittent disconnection.
### PureOS updates fail after first setup
This is caused by an improper timezone or date/time setting required to configure the WiFi connection initially. Solution: [Re-enable the "Automatic Date & Time" setting](https://forums.puri.sm/t/myl5-unable-to-download-updates-for-librem-5-not-valid-yet-invalid-for-another-2h/12119) in `Settings` > `Details` > `Date & Time`
This issue has been solved in more recent versions of PureOS
### Standby mode
Currently the standby / suspend mode isn't enabled by default. Screen just gets dark.
Enable the suspend mode in `Settings` > `Power` > `Automatic Suspend`, see this [blog post](https://puri.sm/posts/librem-5-suspend-preview/).
### Battery fuel meter
[Needs adjustments](https://source.puri.sm/Librem5/linux-next/-/merge_requests/198) and for the time being is not precise. E.g. when fully loaded, the red charging led turns off and battery fuel meter indicates 70%. Recent improvements have synced the battery level indicator in the notifications area to the level in the Power settings panel.
To check the battery state from a shell use `upower -d`. Or read technical details with:
```plaintext
cd /sys/class/power_supply/max170xx_battery
cat capacity
65
cat temp
432
```
### Show battery percentage
By default the Phosh interface shows the battery level as a graphic.
You can show the battery percentage from the Settings app under the "Power" tab and under the the "Suspend & Power Button" section and enabling the "Show Battery Percentage" toggle.
To show the battery level as a percentage, use this command:\
`gsettings set org.gnome.desktop.interface show-battery-percentage true`
### GPS
GPS: Seems to work internally but user interfaces in PureOS are still missing (except switching GPS on and off in `Settings` > `Privacy` > `Location Services`). See <https://forums.puri.sm/t/app-for-gps-settings-on-librem-5/12136>
`Phosh` now acts as a `geoclue` agent so applications like `GNOME maps` and `Pure Maps` can use use location services with the internet connection to show your location on the maps; see: <https://puri.sm/posts/librem-5-news-summary-april-2021/>
### Reflashing Doesn't Use the Entire eMMC Storage - "Root partition is not enlarged"
Related Mobian issue and workaround: <https://gitlab.com/mobian1/issues/-/issues/440#note_1018769896>
[Reflashing the Librem 5](https://developer.puri.sm/Librem5/Development_Environment/Phone/Troubleshooting/Reflashing_the_Phone.html) may end up creating a root partition that does not use up the entire eMMC storage, usually with only 4GB with the rest being unallocated free space when this happens.
You can use the "Disks" app on the Librem 5 to check; select the "31 GB Disk" option when the app opens and it is usually listed as "Partition 2"; alternatively, you can use `df -h` to see and look for the line that says `/` in the "Mounted on" column.
This limited storage space can cause errors when attempting to install additional apps from the PureOS Store because there would not be enough space to install the apps or any system updates.
If the root partition isn't using all of the eMMC storage, these steps will resize the partition to use the entire eMMC capacity.
**Warning**: Before starting to resize a volume or its partition, a backup should be created. Follow these steps at your own risk!
1. From the Librem 5, open up the Terminal app.
2. Check to see the total size of the root partition by entering `df -h`. If the partition is only about 4 GB, then you have this issue.
```sh
$ df -h
Filesystem Size Used Avail Use% Mounted on
/dev/dm-0 3.6G 3.4G 54M 99% /
overlay 3.6G 3.4G 54M 99% /usr/lb/firmware
```
3. Use GNU Parted to resize the root partition. The following command will enter an interactive prompt.
```sh
$ sudo parted /dev/mmcblk0
```
4. Enter the following lines while in the GNU Parted prompt to resize the partition.
```sh
resizepart 2 30.5GB
quit
```
This will look like the following in the terminal app:
```sh
(parted) resizepart 2 30.5GB
(parted) quit
```
5. If the disk is encrypted, run the 3 following commands:
```sh
sudo cryptsetup resize /dev/mapper/crypt_root
sudo resize2fs /dev/mapper/crypt_root
```
6. Reboot the device.
```sh
sudo reboot
```
7. After the Librem 5 has rebooted, open up the Terminal app and check the partition size again with `df -h` to confirm that the root partition has a capacity of around 31 GB.
### Battery Drops to 0 in a Few Minutes
Original forum thread: https://forums.puri.sm/t/battery-dropping-from-40-to-0-in-a-few-minutes/19240
![image](uploads/e4298f2900e5fb7ec9172138cd9bf514/image.png)
This may happen due to the battery calibration getting out of sync.
The following steps should reset it:
1. Power off the device
2. Remove the battery
3. Re-insert the battery
4. Do a full discharge/charge cycle.
According to Kyle Rankin:
> over time my battery calibration skewed because I mostly have this phone plugged in at my desk or at a laptop dock, and it only runs for an extended time on battery when I run quick errands, As a result the battery monitor eventually became inaccurate
## General
### WiFi
To find out which WiFi card you have, enter the following command:
`nmcli -f GENERAL.DRIVER d show wlan0 | tr -s ' '`
For the Redpine Systems card, the field value that is output will be `RSI-SDIO WLAN`
For the SparkLAN card, the field value that is output will be `brcmfmac`
Note that the pipe through `tr` in the above command is just because the output of the command may be too wide for the default terminal window. You can leave off the pipe through `tr` _if_ your phone is in landscape mode _or_ you use `ssh` into your phone from another computer and therefore type the command from another computer.
### Backup
See this thread: <https://forums.puri.sm/t/new-post-app-showcase-backups/11459>. Alternatively: [Example of a quick backup solution](https://forums.puri.sm/t/received-my-librem-5-evergreen/10877/195) using rsync and a systemd timer
You can alternatively connect your phone to a host computer via USB, and boot Jumpdrive on the Librem 5. This will expose your phone's main (eMMC) drive and, if you have a uSD card in your phone, also your phone's uSD card as USB disk devices on the host computer. Then you can use any backup tool that is available on the host computer to backup the contents of your phone's disks using the host computer.
### Boot from SD card
A recent-enough version of u-boot is required before booting from the SD card is possible. The minimum supported version of u-boot is `2022.10`. To update you can either reflash a recent image, or install a deb from CI artifacts at <https://source.puri.sm/Librem5/uboot-imx> and invoke `sudo u-boot-install-librem5 /dev/mmcblk0` afterwards. A reboot is necessary to apply the update.
A compatible image can be written to the SD card and **during boot, hold volume-down**.
Beware that if you put the same image into eMMC and SD, you’ll end up with partitions with duplicated UUIDs, which may cause unexpected behavior during mounting.
**If** this applies then you can fix this by executing<br/>
<br/>
for x equal to 1 and then 2 (i.e. for each of the two partitions on the uSD card)
1. While the specific partition on the uSD card is **not** mounted, `sudo tune2fs -U random /dev/sdax`
2. `sudo tune2fs -l /dev/sdax | grep UUID` (in order to see what UUID was generated)
then
1. Mount `/dev/sda2` (i.e. mount the root partition of the uSD card) - let's say that you mount it at `/mnt`
2. Edit (as root) `/mnt/etc/fstab` (i.e. the `/etc/fstab` that is **on the uSD card**) to put the _new_ UUID value in on the line where the corresponding partition is mounted (the line that is mounting `/boot` for the first partition - gets the first new UUID value; the line that is mounting `/` for the second partition - gets the second new UUID value).
### Convergence
Purism Posts:
- <https://puri.sm/posts/my-first-week-of-librem-5-convergence/>
- <https://puri.sm/posts/my-first-year-of-librem-5-convergence/>
Convergence works with lapdocks such as the [NexDock 360](https://nexdock.com/support-nexdock-360/) and [UPERFECT X Mini](https://www.uperfectmonitor.com/products/uperfect-x-mini-lapdock-11-6).
See the "[Tested Accessories](https://source.puri.sm/Librem5/community-wiki/-/wikis/Tested-Accessories#laptop-shells)" wiki page for more devices.
### Dark mode
Not available out-of-the-box. Can be tweaked by using GNOME Tweaks app and set any theme you want there.
Alternatively, use [gsettings](http://manpages.ubuntu.com/manpages/trusty/man1/gsettings.1.html): `gsettings set org.gnome.desktop.interface gtk-theme "Adwaita-dark"`
UPDATE: See detailed tutorial below.
### Firewall
To enable [ufw](https://en.wikipedia.org/wiki/Uncomplicated_Firewall) (**u**ncomplicated **f**ire**w**all), open terminal and enter `sudo ufw status` and if it's not yet enabled, enter `sudo ufw enable`. The default is usually all you need, but you have the options of adding additional rules. Use `sudo ufw disable` to disable the firewall. To call up a graphical interface inside the terminal, first install gufw and install x11-xserver-utils. Next type the following command: `DISPLAY=:0 xhost +` and hit enter, resulting in: `access control disabled, clients can connect from any host`.\
Now type: `DISPLAY=:0 GDK_BACKEND=x11 sudo gufw` and the graphical version will appear right in the terminal. Note that after you close the terminal, the app icon in the phone's app list will not be operational unless you repeat the above process, at least unless someone adapts it later.
### Flash Mode (USB Download Mode)
Flash mode, or USB download mode, is useful for [reflashing your Librem 5](https://developer.puri.sm/Librem5/Development_Environment/Phone/Troubleshooting/Reflashing_the_Phone.html) or for enabling [Jumpdrive](https://github.com/dreemurrs-embedded/Jumpdrive) to mount the internal storage as a USB disk.
1. Ensure that the phone is powered off.
2. Turn off **all** Hardware-Kill-Switches.
3. Remove the battery.
4. Hold volume-up.
5. Insert the USB-c cable to the Librem 5 and connect it to a computer (red light blinks, no green light).
6. Reinsert the battery (red light is constantly on).
7. Release volume-up.
**Note**
From <https://forums.puri.sm/t/cant-use-l5-after-update/16245/229>:
> Technically, you don’t need to do the battery dance, but the instructions tell you to do so because it increases the chances of it working in some edge cases, like battery being flat, or SoC being stuck in some weird state. This helps because of the LED feedback you get when there’s no battery in - so you can match the LED output you see with the instructions and know that things are going well, there’s enough power available for phone to actually run etc. Without that, there’s no indication of progress, as the only feedback USB download mode gives that informs you it actually booted into USB download can only be seen over USB, so if you don’t see it on your PC you’re pretty much in the dark and figuring out why it’s not working is mostly trail-and-error. With these slightly more annoying instructions, we can at least weed some common failure cases out early
### IMEI
To find the IMEI of your Librem 5, go to `Settings` > `Mobile` > `Modem Details`.
You can also get this information with: `mmcli -m any | grep imei`
### Notifications
Accessed by touching the battery icon at the top right corner of the screen.
### Ringtones
The [phosh-mobile-settings](https://gitlab.gnome.org/guidog/phosh-mobile-settings) app now allows customizing the phone call ringtone, SMS, and instant messages alerts as of 0.27.0. It can be found under the Feedback tab. Only OGG files are supported right now.
Customize rintones following this [blog post](https://sspaeth.de/2021/03/customizing-the-librem5-ringtone/).
### Root account
Locked by default. So there is no root password available. More technical details [here](https://source.puri.sm/Librem5/image-builder/-/merge_requests/123). Unlock root account with `sudo passwd`, check out [this discussion](https://forums.puri.sm/t/what-does-locking-the-root-password-do/10895) for more background.
You can start a shell as `root` by running the command: `sudo -s`
### Terminal
Access additional Terminal keyboard controls by clicking on the globe icon (reveals Ctrl, Alt, and arrow keys, plus other symbols, controls, and Function keys - including Esc and Tab; press the `>_` key to see the extras).
Here's a quick and fun introduction to basic Terminal commands: <https://ubuntu.com/tutorials/command-line-for-beginners#1-overview>
### Username
Default user name is: `purism`. Additional user names can be added from the terminal; at present this is not supported in the `Settings` GUI.
### Auto-mounting directories
When manually adding entries in /etc/fstab, specify the `nofail` option (in the 4th field) so that any problem with the device will not prevent the operating system from booting.
### Screen Orientation
`Phosh` supports automatic screen orientation. To enable or disable it toggle the button in the notifications area.
### Hostname
The default hostname is `pureos`. In order to change the hostname you need to edit, as root, both `/etc/hostname` and `/etc/hosts`
### Lock delay
To delay requiring a password for 60 minutes after the Power button is pressed to blank the screen, issue [this command](https://gitlab.gnome.org/World/Phosh/phosh/-/merge_requests/1012) from the terminal:
`gsettings set org.gnome.desktop.screensaver lock-delay 3600`
Note: If the Librem 5 is coming out of suspension, it will still require the password.
## Software installations and updates (apps and OS)
### Install Software
In case installing software from PureOS store does not work --> Do it from terminal, e.g. `sudo apt install firefox-esr`. Note that PureOS store, by default, lists software that has been adapted to the Librem 5's screen. Other packages can be found and installed using the search tool within the store, but may not scale well to the screen without further modification. You can use the application `Mobile Settings` in the `Compositor` section, to scale the specific application. For this to work the application in question needs to be open at the same time as the `Mobile Settings` app.
### System/Software Updates
Click `Updates` tab within the PureOS Store (and per [this issue](https://source.puri.sm/Librem5/pureos-store/-/issues/20 'First press of "Restart & Update" button does not work, only second attempt works'), hit the `Restart & Update` button _twice_); or, install from the **Terminal** by entering:\
`sudo apt update && sudo apt upgrade`\
(sudo = superuser do / i.e. admin level action)
### Enable Flatpak with Flathub repository
Flatpak support and PureOS store integration are installed by default. Only need to add the Flathub repository via the terminal as described in their setup description [step 3](https://flatpak.org/setup/Debian/) For example:\
`flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo`
#### Customize Flatpak Installation Location
Source: <https://docs.flatpak.org/en/latest/tips-and-tricks.html#adding-a-custom-installation>
> By default Flatpak installs apps system-wide, and can also be made to install per-user with the --user option accepted by most commands. A third option is to set up a custom installation, which could be stored on an external hard drive.
>
> First ensure that the config directory exists:
>
> ```sh
> $ sudo mkdir -p /etc/flatpak/installations.d
> ```
>
> Then open a file in that directory as root:
>
> ```sh
> $ sudoedit /etc/flatpak/installations.d/extra.conf
> ```
>
> And write something like this:
>
> ```ini
> [Installation "extra"]
> Path=/media/purism/mysdcard/flatpak/
> DisplayName=Extra Installation
> StorageType=sdcard
> ```
>
> [...] Replace the path with the actual path you want to use.
>
> Then you can add a remote using a command like:
>
> ```sh
> $ flatpak --installation=extra remote-add flathub https://flathub.org/repo/flathub.flatpakrepo
> ```
>
> And install to it with:
>
> ```sh
> $ flatpak --installation=extra install flathub org.inkscape.Inkscape
> ```
If you use Flatseal to manage Flatpak permissions, [apps may not be listed](https://github.com/tchx84/Flatseal/issues/502) and you will need to grant Flatseal the `host:ro` filesystem permission.
[Flatseal Documentation](https://github.com/tchx84/Flatseal/blob/master/DOCUMENTATION.md#use-custom-flatpak_user_dir)
```sh
flatpak --user override --filesystem=host:ro com.github.tchx84.Flatseal
```
### Add App to favorites:
To add an app from your app list to the Favorites section (i.e. pin to the top of the list), long-press on the app, then select `Add to Favorites`. The Favorites section expands to accommodate the new favorite app. To remove an app from Favorites, long-press the app, then select `Remove from Favorites`.
### Web Apps
You can create an app icon from a web page in the browser as shown in the [Video Walkthrough](https://puri.sm/posts/librem-5-visual-walkthrough/) at position 2m:20s. Deletion / adaption via [Web Application Manager](https://docs.puri.sm/Librem_5/Web.html#web-applications).
### Android Apps (Waydroid)
See: https://source.puri.sm/Librem5/community-wiki/-/wikis/Software/Waydroid
## Recommended applications for common use cases
See this [comprehensive list of mobile-optimized apps](https://tracker.pureos.net/w/pureos/mobile_optimized_apps). A sampling of tested applications, including screenshots, can be found at: <https://forums.puri.sm/t/list-of-apps-that-fit-and-function-well-post-them-here/11361>
### File manager
Nautilus is adaptive on both Amber and Byzantium.
Alternative: [nemo](https://en.wikipedia.org/wiki/Nemo\_%28file_manager%29) scales well without additional tweaks, especially in landscape. It can be installed with the command: `sudo apt install nemo`, or search and install within PureOS store.
You can also install `Portfolio` file manager.
[GNOME Files](https://wiki.gnome.org/Apps/Files) is adaptive since [version 43](https://release.gnome.org/43/#files-refresh).
### Screenshots
Install `librem5-goodies` (e.g. in the terminal with the command `sudo apt install librem5-goodies`). After the installation it will add several apps to the app tray: `Screen Shot` ... along with other included apps.
## Application life-cycle
* To **close an application** touch the "roof" symbol on the bottom of the screen which shows a carousel of open apps. From there you can close an app by tipping and swiping it up to the upper part/top of the mobile phone
* To [close a blocked/hanging application](https://forums.puri.sm/t/how-to-kill-stop-a-blocked-non-responding-app-on-librem-5/12133) you can use the terminal and the `killall` command or use the app `Usage` (installed by default) where you can find the process of the app if you scroll down, tip on the app name and choose "Force quit".
## USB
### Mount USB sticks
USB drives are automatically recognized and mounted (you get a notification where you can open the mounted folder in a file manager).
### Unmount (eject) USB sticks
This requires to use the `umount` command in the terminal or (easier) eject via the `nautilus` or [`nemo` file manager](https://forums.puri.sm/t/how-to-eject-usb-drive-from-librem-5-with-a-gui/12132): Select the mounted USB drive in the device tree node in `nautilus` or `nemo`, the choose `eject` in the `File` menu so safely unmount the USB drive
## Calls
### Calls/Voice quality
Adjust Internal Microphone volume in `Settings` > `Sound` for optimal clarity.
### Calls from terminal
`xdg-open tel://<phone-number>` as seen [here](https://social.librem.one/@eliasr/105243293093757846).
### Mobile Settings
While Mobile is disabled, either by the settings toggle or by the kill switch, granular Mobile Settings are inaccessible. Also, at the moment, saved messages in Chats cannot be viewed, nor new messages composed; a fix for this is being worked on, and the issue does not affect other installed messaging apps, and also not other chat protocols used by chatty (e.g xmpp), if any.
### Send SMS (text message) from terminal
At the current time, this is a bit untidy but it can be done.
```plaintext
# Pause chatty
killall -STOP chatty
# Create SMS and save its id
id=`sudo mmcli -m any --messaging-create-sms="text='your-content',number='dest-phone-number'"`
# id is e.g. Successfully created new SMS: /org/freedesktop/ModemManager1/SMS/6
id=${id/?*\/*\/*\/*\/*\/}
# strip that back to just the number e.g. 6
echo id = $id
# Send SMS
sudo mmcli -s $id --send
# Resume chatty
killall -CONT chatty
```
In my testing, the dest-phone-number did not have to be a full international-format mobile number. Your mileage may vary.
Unless you are a bash wiz it would be best to avoid any quote characters (\` " ') in your-content.
If scripting this then it might be wise to wait until the text message is actually sent before resuming `chatty`. You can get the status of the message with: `mmcli -m any --messaging-list-sms`
As an aside, if your Librem 5 becomes gummed up with an MMS that you can't receive and process (yet) then you can list it with the previous command and then delete with: `sudo mmcli -m any --messaging-delete-sms=index` where `index` is replaced with the message number to delete.
## Mail (Geary)
* If the incoming mail server or the outgoing mail server require a port number then specify the hostname as `hostname:portnumber`
* There is no support for the POP protocol. Mail can only be received using the IMAP protocol.
* Config information is stored in `/home/purism/.config/geary/account_01/geary.ini` (or replace `_01` with subsequent numbers if more than one account)
## Contacts
### Import contacts
The default contact application `gnome-contacts` supports importing and exporting contacts from a vcard (`.vcf`) file. To import contacts from a `.vcf` file via Bluetooth the `librem5-goodies` package that you can install from the command line, can do this. It also has two scripts (`l5-contacts-importer` and `l5-contacts-exporter`) that you can use to import and export contacts from a terminal.
Import from SIM card is currently not supported. But it is possible to extract the contacts in the SIM card to a text file, with the following command:
`echo AT+CPBR=1,250 | socat - /dev/ttyUSB3,crnl > sim-contacts.txt`
If your user is not added to the dialout group then you will need to run the above command with `sudo`
`echo AT+CPBR=1,250 | sudo socat - /dev/ttyUSB3,crnl > sim-contacts.txt`
Contacts information appears to be stored in:\
`/home/purism/.local/share/evolution/addressbook/system/contacts.db`
### General Carddav and Caldav functionality
Install the `evolution` package from the command line, add regular Carddav and Caldav accounts via Evolution interface, attach [external screen](https://forums.puri.sm/t/myl5-librem-5-evergreen-first-impressions/11217/59?u=5a54a) (Evolution is not adaptive for Librem 5).
## Locale
If you have set a specific locale (e.g. en_AU.UTF-8) then you will probably get warnings all over the place (e.g. from `man`, `locale` itself, from `perl` during an install). The solution appears to be:\
`sudo dpkg-reconfigure locales`\
Then page down to your chosen locale, press the space bar to select it - `[ ]` will change to `[*]`, then Tab to move to Ok then Enter.\
That will then take an eternity generating all the selected locales and eventually doing the one that you just selected.
## Network Config
Network Manager stores the configuration in `/etc/NetworkManager`. Specifically, information that is per-connection is stored in the `system-connections` subdirectory in files called `xyz.nmconnection` where xyz is the connection name.\
The proper way to 'get' and 'set' per-connection settings, if wanting to do from the command line, is via the `nmcli` command.
* Show the connections that exist: `nmcli conn show`
* Show a specific connection where uuid is as listed by the first command:\
`nmcli conn show uuid | grep whatever`
* Retrieve a specific field: `nmcli -g fieldname conn show uuid`
* Modify a specific field: `nmcli conn modify uuid fieldname fieldvalue`
## Modem Manager
To get modem information:
* Using the command: `mmcli -m any` will display information on all modems installed on the device, in the case of the Librem 5, there is only one.
Likewise to get SIM information, you can use the command: `mmcli -i any` That will show you your IMSI and your ICCID, among other pieces of information.
But you can also search explicitly to get modem indexes and SIM indexes.
* Firstly, `mmcli -L` to list the modems. For example, gives: /org/freedesktop/ModemManager1/Modem/**1**
- so the modem index to use at this moment in time is ‘1’.
* Then, `mmcli -m M` where M is replaced with the modem index.
* You can check, in passing, your own phone number (`mmcli -m M | grep own:`) and get the SIM index (`mmcli -m M | grep SIM`)
* You can also check what mobile network you are on with `mmcli -m M | grep operator`. The operator id comprises three digits for the Mobile Country Code (MCC) followed by two or three digits for the Mobile Network Code (MNC).
* The output for the SIM index looks like: SIM | dbus path: /org/freedesktop/ModemManager1/SIM/**1** - so the SIM index is 1.
* Finally, `mmcli -i S` where S is replaced with the SIM index.
* `-i` and `-m` are abbreviated forms of `--sim` and `--modem` respectively.
## Executing an AT command on the modem
There are two ways of doing this.
Method A:
`mmcli` can execute an AT command for you but Modem Manager has to be in "debug" mode for that to work. So:
change the ExecStart line in the file `/lib/systemd/system/ModemManager.service` by adding `--debug` so that the line looks like this:
`ExecStart=/usr/sbin/ModemManager --debug`
After that, run the following commands to make the change take effect:
```plaintext
sudo systemctl daemon-reload
sudo systemctl restart ModemManager.service
```
Then Modem Manager should be running in debug mode, and you can execute an AT command on the modem e.g.
`sudo mmcli -m any --command=ATI`
The `ATI` command is useful to identify the make and model of modem e.g. what variant of the Broadmobi 818 you have.
This approach has the advantage that if you want to execute the same command more than once, you can repeat the command in the shell.
It is _recommended_ that you take Modem Manager out of debug mode once you have finished i.e. revert the change to the file that you edited above and re-execute the two `systemctl` commands.
Method B:
You can communicate directly with the modem. This involves installing a program like `minicom`, so do that first:
`sudo apt install minicom`
Then `mmcli -m any | grep ttyUSB`
The output will look like:
```plaintext
| ports: cdc-wdm0 (qmi), ttyUSB0 (qcdm), ttyUSB1 (at), ttyUSB2 (at),
| ttyUSB3 (at), wwan0 (net)
```
Pick any `ttyUSBn` device that is followed by `(at)` e.g. in the above output 1, 2 and 3 are good to use.
`sudo minicom -D /dev/ttyUSBn`
Type Ctrl/A and then E in order to enable local echo.
Type your AT command(s) e.g.
`ATI`
Type Ctrl/A and then X in order to exit from `minicom`.
## Mobile Country Reference Data
* Reference data for APNs (used to access the internet on the mobile network) is stored in the directory `/usr/share/mobile-broadband-provider-info`
* Reference data for international dialling is stored in the locale file, in the LC_TELEPHONE section e.g. `/usr/share/i18n/locales/ll_CC` where `ll` is the language code and `CC` is the country code.
## Managing Journals
By default, the Librem 5 uses `journald` for system journaling.
The system journal can get very big, which consumes significant scarce disk space and makes the journal slow to find things in. Use
`journalctl --disk-usage`
to see how much disk space is being used by all journal files.
To have the system journal automatically cleaned periodically, edit the file `/etc/systemd/journald.conf` and set values for `SystemMaxUse` and `MaxFileSec`. Unless you are specifically trying to troubleshoot an infrequent problem, values of `500M` and `1month` are reasonable.
By default `journald` will forward to `syslogd` but by default a suitable `syslogd` won't be running and so the forwarded messages won't go anywhere. If you prefer to use `syslogd`, rather than `journald`, for examining logged messages then
`sudo apt install rsyslog`
or such other implementation of `syslogd` as you prefer.
Note that the command to examine logged messages via `journald` is `journalctl` whereas messages logged by `syslogd` go in `/var/log/syslog` (unless you configure otherwise).
## Tutorials
### SECURE SHELL (`ssh`)
_Note that using the L5's passcode to log in remotely provides relatively weak security. See related tutorials for better authentication solutions._
SECURE SHELL Logging in remotely to the L5’s terminal in order to execute commands
On your computer (the client): `sudo apt update && sudo apt upgrade`
Then:
`sudo apt install openssh-client`
On the Librem 5 (the remote device, the server): `sudo apt update && sudo apt upgrade`
Then:
`sudo apt install openssh-server`
Confirm that it worked (i.e. is “active”): `sudo systemctl status ssh`
If not active: `sudo systemctl enable ssh`
If firewall blocks `ssh` on the remote device: `sudo ufw allow ssh`
Other firewall options available: `stop` `start` `disable`
Determine IP address of the remote device (L5):
Available in the `What IP` app, or via the L5’s terminal:\
`ip address` or `ifconfig`
or log in to your router to find the L5’s IP address.
To log in over WiFi to the remote device (L5) from your computer:\
`ssh Librem5-username@REMOTE.IP.ADDRESS.HERE`
Example: `ssh purism@192.168.xxx.xxx`
For clarity, if you omit the `Librem5-username@` then `ssh` will default the remote username (the username on the Librem 5) to the local username (the username on your computer). Unless your computer is _another_ Librem 5, this is unlikely to be what you want. Hence, in most cases, you **must** specify in the `ssh` command the username on the Librem 5, which is `purism` on a new (unmodified) install of the Librem 5 software.
Type the word “yes” at the next terminal question, then provide the password to your L5. The following prompt will appear:\
`purism@pureos:~$`
You are now logged into your L5 from your computer’s terminal, and can easily execute any terminal commands remotely. This also makes it easy to copy terminal output and paste it here in the forum or elsewhere.
You can also connect your L5 to your computer over USB and use `ssh` via a `Shared Connection` in your computer’s network settings.
In the settings panel of the L5, under `Sharing`, you should now see that Remote Login is `On`. At the top of this panel, you can use the toggle to enable or disable remote sharing for security purposes.
To exit `ssh`, use the command `exit` in the terminal.
### SSH File Transfer Protocol (`sftp`)
Once `ssh` is set up, a simpler way to remotely access files on the Librem 5 is with `sftp`.
With both devices powered on, from the host machine:
\-Open the file browser
\-Type `Control`+`L` to bring up the location bar
\-Enter `sftp://xxx.xxx.xxx.xxx` (filling in the IP address of the L5
\-Authenticate with the L5's password
This will mount the L5's file system. Navigate to the `Home` directory and the desired sub-directory to copy, cut, or paste as you like.
TIP: Bookmark the L5's IP in your file browser to access it with a mouse click whenever you want (as long as the L5 is powered on).
### SECURE COPY (`scp`)
Copying files and folders remotely between devices on your network
_Note that using the L5's passcode to log in remotely is relatively weak security. See related tutorials for better authentication solutions._
With `ssh` enabled, you can use the Secure Copy command (`scp`) to copy files or entire folders from the L5 to your computer, and vice versa. Note that in order to perform `scp`, you _do not_ log in to the L5 via `ssh` first.
The syntax is:\
`scp remote_username@REMOTE.IP.ADDRESS.HERE:/remote/file.txt /local/directory`
Examples:
`scp purism@192.168.xxx.xxx:/home/purism/example.txt /home/yourusername/Desktop` would copy the file example.txt located in the L5’s Home folder to the desktop of your computer.
`scp purism@192.168.xxx.xxx:/home/purism/Pictures/2021-04-12-example.png /home/yourusername/Desktop` would copy the image 2021-04-12-example.png located in the L5’s Pictures folder to the desktop of your computer.
To copy an entire folder from the L5 to your computer:
`scp -r purism@192.168.xxx.xxx:/home/purism/Pictures /home/yourusername/Desktop` will copy the folder “Pictures" from the L5 to your computer. (More convenient than copying individual images or files one at a time, in case there are many to copy.) The `-r` after `scp` stands for “recursive,” indicating that the copy action should continue until all is copied.
To copy a file from your computer to the L5, the syntax is:
`scp file.txt remote_username@REMOTE.IP.ADDRESS.HERE:/remote/directory`
If the file is not located in your computer’s Home directory, first change directory to the location of the file, using the command `cd`, for example `cd Desktop`, if the file is on your desktop, and so on.
Example, from your Home directory:
`scp example.txt purism@192.168.xxx.xxx:` (Use the actual ip address of your L5. This places the file in the L5’s Home directory.)
`scp example.txt purism@192.168.xxx.xxx:/home/purism/Documents` (This goes to the L5’s Documents folder.)
**TIP:** Although you perform `scp` without logging in to the other device with `ssh`, it may be helpful to use `ssh` first in order to list (`ls`) the contents of a folder so that it will be easy to copy and paste the name of a file or files for `scp`. Just be sure to exit `ssh` before you use `scp` or you’ll get an error.
(Related discussion on this topic can be found in the community forum: <https://forums.puri.sm/t/tutorial-using-ssh-and-scp/13080>)
### ENHANCING SECURITY FOR SECURE SHELL (`ssh`)
Relying on the L5's passcode when using `ssh` for remote access provides relatively weak security. See below for more secure options.
* **_Option 1:_** Use private/public key-pair authentication, and disable password-based authentication for remote login.
These instructions will also work with a Unix/Linux-based server, or the Pinephone.
Enable ssh access to your Librem 5. (See related tutorial.)
On computer, generate the public/private RSA keys.
Open a Terminal session on your computer and type the following command:
`ssh-keygen -t rsa` OR `ssh-keygen`
```plaintext
Enter file in which to save the key (/home/{YOUR_ID}/.ssh/id_rsa):
Created directory ‘/home/{YOUR_ID}/.ssh’.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/{YOUR_ID}/.ssh/id_rsa.
Your public key has been saved in /home/{YOUR_ID}/.ssh/id_rsa.pub.
```
On computer, copy the contents of the id_rsa.pub key onto the Librem 5. The following command will log into your Librem 5, and configure the keys to grant access via the authorized_keys file.
`ssh-copy-id -i ~/.ssh/id_rsa.pub purism@host`
(example: `192.168.xxx.xxx`, substitute with your ip address)
You will be asked for your password into the Librem 5 in this step. Only your public key is copied. Always keep your private key private.
Restart your phone.
On computer, login to your phone using key-based authentication
`ssh purism@host` (ex. `ssh purism@192.168.xxx.xxx`)
On Librem 5, disable password-based authentication
`ssh purism@host`
Use an editor like `nano` or `vim` to edit the following `/etc/ssh/sshd_config`, using admin rights.
`sudo nano /etc/ssh/sshd_config`
Find the following line:
`PasswordAuthentication yes`
And change it to:
`PasswordAuthentication no`
If there is a # (this means "commented out", that is, excluded from the command/script) at the beginning of that line, remove it.
Save the file after making these changes and restart the SSH service using this command:
`systemctl restart ssh`
To test that password-based authentication is actually disabled, from computer, try to `ssh` into the Librem 5 using a different (or non-existent) id:
`ssh otherid@host`
You should get the following error: `otherid@host: Permission denied (publickey)`
You have now successfully disabled password based authentication in `ssh`.
(Related discussion on this topic can be found in the community forum: <https://forums.puri.sm/t/tutorial-enable-key-based-authentication-via-ssh-on-your-librem-5/13137>)
### Setting a Custom Background in Phosh
Selected background image can be a .jpg or a .png, possibly other file types.
In the terminal, create the file `gtk.css` (if it doesn't already exist) using any installed text editor: `nano ~/.config/gtk-3.0/gtk.css`. Alternately, you can create the file manually in the `Files` app.
Then add the following to the `gtk.css` file. (Change the path to point to your chosen image.)
```plaintext
/*
* Set a background for the lockscreen.
*/
phosh-lockscreen, .phosh-lockshield {
background-image: linear-gradient(rgba(0, 0, 0, 0.7), rgba(0, 0, 0, 0.7)),
url('file:///home/purism/Pictures/mybackground.jpg');
background-size: cover;
background-position: center;
}
/*
* Set a background for the app grid.
*/
phosh-app-grid {
background-image: linear-gradient(rgba(0, 0, 0, 0.7), rgba(0, 0, 0, 0.7)),
url('file:///home/purism/Pictures/mybackground.jpg');
background-size: cover;
background-position: center;
}
```
Then: `sudo systemctl restart phosh`.
The background image can be set to different levels of transparency by changing the "0.7" entries above to anything on the scale of "0.0" (fully transparent) to "1.0" (fully opaque). It’s a linear-gradient effect, so the first 0.7 is transparency starting on top, and the second 0.7 is transparency ending at bottom.
You can also change the gnome background. (This is not needed in pureos-byzantium, as a graphical option is present.):
```plaintext
`gsettings set org.gnome.desktop.background picture-uri file:///path/to/picture_file`
```
e.g. `gsettings set org.gnome.desktop.background picture-uri file:///home/purism/Pictures/image.png`
### Creating a Shortcut to Execute a Terminal Command
As an [example](https://forums.puri.sm/t/tutorial-create-a-shortcut-to-modem-info/16886), the following will create a shortcut to modem info, similar to using Android's `*#*#INFO#*#*` service code.
First, find an appropriate icon, edit it if desired, name it (e.g. modem.png), and save it to `.local/share/icons`, creating the `icons` folder if it doesn't exist already.
Next, create the shortcut button in `.local/share/applications`, naming it e.g. `ModemInfo.desktop`. This will insert the icon/launcher into the home screen's app grid.
In the terminal, enter `mmcli -L` to retrieve the modem's single-digit identifier. In this example, the command returns `/org/freedesktop/ModemManager1/Modem/0 [QUALCOMM INCORPORATED] 0`, which indicates "0" as the identifier. We can now run `mmcli --modem=0` to manually retrieve the detailed modem and mobile network information. (If there is only one modem installed, you can skip `mmcli -L` and change `mmcli --modem=0` to `mmcli --modem=m any`.)
Next, to enable the app screen launcher to run `mmcli --modem=0` (or `mmcli --modem=m any`), copy the following text into the `ModemInfo.desktop` file, which was created previously in `.local/share/applications`:
\[Desktop Entry\] Name=ModemInfo Exec=gnome-terminal -x bash -c “mmcli --modem=0 | tee modeminfo.txt; exec bash” StartupNotify=true Terminal=false Type=Application Categories=Utilities; Icon=/home/purism/.local/share/icons/modem.png
The above automates opening the terminal, running the command, and also saves the terminal output to a text file (`modeminfo.txt`) in the home folder, as well as setting the icon to use as the launcher, all from a single tap on the app icon. The text file will be overwritten every time.
At this point, either view the output in the terminal opened by the launcher, or close the terminal and view the text file instead.
For another example, see how to create a launcher to [quick-dial a frequent telephone number](https://forums.puri.sm/t/howto-make-a-quickdial-button/12560).
### Enable Adwaita-dark theme using `GNOME Tweaks`
A convenient way to enable dark mode:
Find and install `Adwaita dark GTK theme` from the PureOS software app.
Find and install `GNOME Tweaks`. `Tweaks` doesn’t (currently) fit the screen unless you run this:
`gsettings set sm.puri.phoc.application:/sm/puri/phoc/application/org-gnome-tweaks/ scale-to-fit true`
The above command should work with any GNOME app that needs permanent scaling down; just change the package name as applicable. Use `...scale-to-fit false` to turn it off again.
Alternatively, you can use the Displays sub-menu in the Librem 5’s Settings app to scale to different resolutions on an _ad hoc_ basis.
Tap the `Tweaks` app icon. Only landscape view is completely usable (currently)…and the text will be tiny; activate Adwaita-dark in the Themes sub-menu.
GNOME apps will now display in dark mode. To revert to Adwaita (light theme), select it in the Tweaks app.
### Add a Swap File
**Please consider reading https://www.kernel.org/doc/html/latest/admin-guide/blockdev/zram.html#optional-feature about _writeback_ if you already configured _zramswap_ like described in the forums. This entry might need additional information/correction about the advantages and disadvantages of zramswap and traditional swap on disk.**
If you find yourself running out of RAM, you may want to consider creating a Swap file.
From [this Linuxize tutorial](https://linuxize.com/post/create-a-linux-swap-file/):
> Swap is a space on a disk that is used when the amount of physical RAM memory is full. When a Linux system runs out of RAM, inactive pages are moved from the RAM to the swap space.
>
> Swap space can take the form of either a dedicated swap partition or a swap file. In most cases, when running Linux on a virtual machine, a swap partition is not present, so the only option is to create a swap file.
1. Create a file that will be used for swap. The example below will add 1GB of swap; if you want more, such as 2GB, substitute `1G` with the desired amount (e.g. `2G` for 2GB).
```sh
sudo fallocate -l 1G /swapfile
```
2. Only the root user should be able to write and read the swap file. To set the correct permissions type:
```sh
sudo chmod 600 /swapfile
```
3. Use the `mkswap` utility to set up the file as Linux swap area:
```sh
sudo mkswap /swapfile
```
4. Enable the swap with the following command:
```sh
sudo swapon /swapfile
```
To make the change permanent, open the `/etc/fstab` file and append the following line:
```
/swapfile swap swap defaults 0 0
```
5. To verify that the swap is active, use either the `swapon` or the `free` command as shown below (The output values shown are just samples):
```sh
$ sudo swapon --show
NAME TYPE SIZE USED PRIO
/swapfile file 1024M 507.4M -2
```
```sh
$ sudo free -h
total used free shared buff/cache available
Mem: 488M 158M 83M 2.3M 246M 217M
Swap: 1.0G 506M 517M
```
### Resize Swap File Size
If you find that the swap file is too large or too small, you can resize it.
1. Before you resize the swap file, you should turn the swap off. You should also make sure that you have enough free RAM available to take the data from swap file. Otherwise, create a temporary swap file.
```sh
sudo swapoff /swapfile
```
2. Now use the `fallocate` command in Linux to change the size of the swap file. The example below will resize the swap file to 4GB of swap; if you want more, such as 8GB, substitute `4G` with the desired amount (e.g. `8G` for 8GB).
```sh
sudo fallocate -l 4G /swapfile
```
3. Mark the file as a swap file:
```sh
sudo mkswap /swapfile
```
4. Enable the swap file:
```sh
sudo swapon /swapfile
```
To make the change permanent, open the `/etc/fstab` file and append the following line:
```
/swapfile swap swap defaults 0 0
```
This may already exist from creating a swap file before so don't add a duplicate entry if that's the case.
### Resize ZRAM
1. Before you resize the swap file, you should turn the swap off. You should also make sure that you have enough free RAM available to take the data from swap file. Otherwise, create a temporary swap file.
```sh
sudo swapoff /dev/zram0
```
2. Reset and resize the ZRAM.
```sh
sudo zramctl --reset /dev/zram0
sudo zramctl --find --size 5G
3. Mark and enable the ZRAM.
```sh
sudo mkswap /dev/zram0
sudo swapon /dev/zram0
```
\ No newline at end of file