Sailfish OS - Command Line Interface & Customisation

Introduction to Sailfish OS.

Edits to already existing files in system directories could be overwritten by updates. Right now this is only the case for the pulseaudio tweaks below.
To avoid that, one could use Patchmanager patches to implement such changes. It isn’t hard to create one, they’re usually just tiny text files.

Convention
The default user’s home directory is /home/defaultuser. This string is stored in the environment variable $HOME and can be abbreviated with ~.

Connecting to the phone

MTP (the same protocol Android devices use) will expose the /home/defaultuser folder to the connecting computer, both to graphical and command line applications. But it hides some (system) files and folders from the connected system.

Assuming Remote connection is enabled in Settings -> Developer tools…

A more powerful way is to connect through a terminal via SSH:

SSH

Please be prepared that you might need to use the terminal app on the phone if you lock yourself out.

Don’t be root for any of these commands/edits, except where specified!

Another option is to enable Developer mode & Remote connection, then ssh into the device or scp files to/from it via WLAN. Example config section in ~/.ssh/config on the computer that wants to connect to the phone:

Host xa2 # make something up here
HostName 192.168.0.16
# Port XXX # your choice here
User defaultuser
IdentityFile /home/me/.ssh/name-of-id

The IP could be different - tell your router to give your phone always the same IP. Now entering

ssh xa2

should be enough to make a connection. It asks for the password you entered when enabling developer mode & remote connections.

I When this is working, I (along with 99% of all Linux users) highly recommend using an SSH key for connecting. Please also read this article.

Install user scripts

All my Linux systems live by the power of self-written scripts. These often end up in a special folder that makes them more accessible, as executables.

According to the default /home/defaultuser/.bash_profile the folder /home/defaultuser/bin is added to the PATH environment variable.

But I and many other people prefer /home/defaultuser/.local/bin.

• Edit /home/defaultuser/.bash_profile accordingly and create the directory.
• Log out and back in.

Now you can start putting your scripts there.
They need to be executable though: chmod +x ~/.local/bin/my_script_001.

Now I can type the name of an executable anywhere on the command line, and it will find it.

Shell configuration

I have long since abandoned the shell config files put in my home folder:

cd ~ && rm .bash_logout .bash_profile .bashrc

Instead I use a system-wide config described in a separate article. That way all configurations are available for all users.

Becoming root

devel-su asks for the user password and can be used for both single commands and to open a root shell. It is possible to install & use sudo, it does not interfere with devel-su.

Package management

PackageKit is a “high-level front end for a number of different package management systems.” It’s installed by default on SailfishOS. It uses the ZYpp package manager as a backend, which in turn uses rpm. Simply entering pkcon will list commands and options.

zypper

zypper is another package managament tool which, afaik, does not interfere with PackageKit because they use the same backend. In other words, it can be used for everything pkcon does, and more:

Useful commands

• Free form search for packages: pkcon search ..., zypper search --search-descriptions ...
• Sometimes it happens: you uninstall some software, but it leaves behind dependencies that are not needed anymore. You can find these with zypper pa --unneeded.
• In case you messed up un/installing something, the zypp history can be examined. E.g. all transactions for today: grep "^$(date '+%Y-%m-%d')" /var/log/zypp/history.
• List all repositories: zypper repos
• List all installed packages: zypper pa -i
• Find the package that owns a file: rpm -qf /full/path/to/file

nano

On your phone, you might want to install nano, a useful & ubiquitous CLI editor: devel-su pkcon install nano

It does not come with a nanorc file; I recommend copying one from another machine and moving it to /etc/nanorc. That way settings apply to all users. Make sure to enable syntax highlighting by adding this line: include "/usr/share/nano/*.nanorc"

If you build RPM files there’s a .spec file definition in the extra directory. Add: include "/usr/share/nano/extra/spec.nanorc"

Here is my /etc/nanorc (with most comments removed):

set autoindent
set historylog
set linenumbers
unset locking
set multibuffer

## Don't wrap text at all.
set nowrap
## soft wrap long lines
set softwrap

## Allows to use Ctrl-S for savinf
unset preserve

set smarthome
set tabsize 4
set tabstospaces

## Paint the interface elements of nano.
## These are examples; by default there are no colors.
set titlecolor black,cyan
set numbercolor cyan
set statuscolor black,cyan
set keycolor green
set functioncolor yellow

include "/usr/share/nano/*.nanorc"
include "/usr/share/nano/extra/*.nanorc"

SFOS’ version of nano is quite old, this config file is curated to make it fit.

Consider making nano the default editor.

I have now added a large bunch of *.nanorc files to my SFOS repository. See README.md in the nano folder.

bash

By default, /bin/bash is symlinked to busybox:

ls -l $(which $0)
lrwxrwxrwx  1 root root  18 Feb 13 2023  /bin/bash -> ../usr/bin/busybox

So even if you explicitely start bash, it starts busybox instead. This means that bashisms in scripts will throw errors.

We just need to remove one package:

devel-su pkcon remove busybox-symlinks-bash

This makes bash magically appear¹. Small problem: sh now also points to bash, which is less than ideal - busybox ash is much faster than bash, and a script without bashisms should use the faster/lighter shell. To remedy this, execute these command as root:

ln -sf /usr/bin/busybox /bin/sh
ln -sf /usr/bin/busybox /usr/bin/sh

The login shell for root & defaultuser is still bash. This might or might not be desired. If you want them to use busybox’ shell again (now /bin/sh), try this with elevated privileges:

chsh root
chsh defaultuser

sqlite3

To view & edit SQLITE databases directly on the phone. The sqlite3 executable is not installed, but the package sqlite is available. It does not show up in either Jolla or Openrepos appstores, but you can install it like this:

pkcon install sqlite

TODO: quick tutorial and useful commands

SSHFS

SSHFS can mount part of a remote filesystem locally via ssh or rather the sftp subsystem.

On SailfishOS this means that I can listen to music or watch video straight from that remote location - no more media servers! In fact I can access all files with both GUI and CLI applications.

Here’s how:

First, try to get normal ssh working from your phone to a server, preferably passwordless with an authentication key. Once this works reliably:

• Install sshfs-fuse-2 (OpenRepos/Storeman). Don’t be alarmed by its age, it uses OpenSSH’s binaries to make a secure connection!
• formulate a suitable command or use a toggle script like this one:

#!/bin/bash

exec 2>&1

# dependency checks
for dep in mount grep sshfs ssh fusermount; do
command -V $dep >/dev/null || exit 1
done

mountdir="/home/defaultuser/server" # just an example
location="remote_user@domain_or_IP:/path/to/dir"

port=XXX # preferably something other than 22!
identity="/home/defaultuser/.ssh/your_server_s_key_file"

sshfs_options="follow_symlinks,ServerAliveInterval=15,reconnect,\
IdentitiesOnly=yes,IdentityFile=$identity,port=$port,\
compression=yes,debug,sshfs_debug,loglevel=debug"

if [[  $(mount|grep -o "$mountdir") == "$mountdir" ]]
then
echo "$mountdir is already mounted. Unmounting..."
fusermount -u -z "$mountdir"
exit 0
fi

if sshfs -C -o "$sshfs_options" "$location" "$mountdir" &
then
echo "Mounted $location on $mountdir"
echo "Run $0 again to terminate connection."
exit 0
else
echo "Mounting $location failed"
fusermount -u -z "$mountdir"
exit 1
fi

Executing the script the first time will mount, executing it another time will unmount. It’s very chatty, if you need to use the terminal it was started in you might want to remove all three debug options. - Use qCommand to launch the script!

Ambiences

Ambiences can be quickly created from images/photos, but I find this process a little lacking: images are resized in a way that can reduce their quality, and I do not have enough control over the colours used. The default ambiences are stored in /usr/share/ambience. They are simple folders with a configuration file (*.ambience), a background image and optionally also sounds. Everything is straigthforward. You can create your own ambiences from scratch, however they need to be stored in /usr/share/ambience, I have not found a way to store them anywhere under /home/defaultuser.

Here’s an example:

ls /usr/share/ambience/white-on-black/*
/usr/share/ambience/white-on-black/white-on-black.ambience
/usr/share/ambience/white-on-black/images:
white-on-black.png
cat /usr/share/ambience/white-on-black/white-on-black.ambience
{
"displayName"               : "White on Black",
"wallpaper"                 : "black.png",
"highlightColor"            : "#ffffff",
"secondaryHighlightColor"   : "#dddddd",
"primaryColor"              : "#ffffff",
"secondaryColor"            : "#aaaaaa",
"ringerVolume"              : 100,
"colorScheme"               : "lightondark",
"favorite"                  : true,
"timestamp"                 : "2021-09-19T10:00:00",
"version"                   : 3
}

The image should be the height of your phone’s screen, and square. In my case: 1920x1920px.

You will need to be root (devel-su) to create & edit these files & folders. There’s also an option to create a package directly on your phone, but I haven’t gone to such lengths.

When ready, restart the ambience daemon: systemctl --user restart ambienced.

Also have a look at the other .ambience files:

Pulseaudio

Pulseaudio is the sound server that makes sure all the different sound sources and outputs are muted, paused, resumed properly. It’s also used on dektop Linux.

Disable High Volume Warning

Disclaimer: be aware that doing this you remove a safety feature and could damage your hearing. Use at your own risk.

It’s the same idiotic warning one used to get on Android phones when listening on headphones (or anything plugged into the audio jack). It blocks raising the volume above a certain level until some sort of OK button is tapped. Listening to audio while cycling, this gets very annoying, because it kicks in seemingly randomly once or twice a day.

To get rid of it, you can install Patchmanager 3.0 (now in CHUM) and look for “Volume Warning” in the Web catalog, install the patch, then Apply. There are several patches. At least one of them should still work, despite being listed as incompatible (no worries, if it really isn’t, it simply won’t patch). All of them use the same method: In the Lipstick UI, they mark the high volume warning dialog as checked. This means that the volume still gets reduced periodically, you just don’t have to tap OK to go higher.

This does not satisfy me; maybe pulseaudio can be told to not do it at all?

Edit /etc/pulse/mainvolume-listening-time-notifier.conf (also see “SSH” and “Becoming root” from the main article). Replace

mode-list = lineout,hs

with

#mode-list = lineout,hs
mode-list =

And reboot (or restart pulseaudio?).

Source.

It appears to be completely gone after that, I never get reminded, and the volume never drops by itself.

D: [pulseaudio] module-meego-mainvolume.c: Read long listening time notifier config from /etc/pulse/mainvolume-listening-time-notifier.conf
D: [pulseaudio] conf-parser.c: Parsing configuration file '/etc/pulse/mainvolume-listening-time-notifier.conf'
D: [pulseaudio] module-meego-mainvolume.c: Notifier conf role-list add: "x-maemo"
D: [pulseaudio] module-meego-mainvolume.c: Notifier conf mode-list add: "lineout"
D: [pulseaudio] module-meego-mainvolume.c: Notifier conf mode-list add: "hs"
D: [pulseaudio] listening-watchdog.c: Restore counter value 0 minutes (0 seconds)
D: [pulseaudio] module-meego-mainvolume.c: Long listening time notifier setup done.

pkcon install gdb alsa-utils

Flat volumes

Just like on my desktop, pulseaudio is very opinionated about adjusting volumes relatively to the master volume, which has sometimes undesired results (esp. after a phone call).

To disable this, I will try to edit /etc/pulse/daemon.conf.d/50-sfos.daemon.conf and replace flat-volumes = yes with flat-volumes = no.

(source)

And reboot (or restart pulseaudio?).

Internet sharing over USB

Requires installing and activating an extra package via command line. After that, the “Internet sharing” option will appear next time you connect to a computer via USB cable.

Instructions:

• Connect your Sailfish device to a WLAN network or to a mobile network (“Settings > System > Mobile network”), i.e., enable mobile data.
• You will need Developer mode for installing USB tethering.
• In a (remote) shell, enter:

devel-su
pkcon refresh
pkcon install usb-moded-connection-sharing-android-connman-config
systemctl restart usb-moded

mce-tools

Tools for interacting with mce (Mode Control Entity).

zypper install mce-tools

Provides the command line tool mcetool which allows to set and read various - well, modes on your phone. Try mcetool -h. E.g.: disable lock screen animation:

mcetool --set-lockscreen-animation=disabled