Linux Console Basics

Console and Shell

MNT Reform ships with a lightly customized Debian GNU/Linux distribution on the provided SD card. With the SD card inserted, MNT Reform will boot to a login screen.

From here, you can reach a graphical desktop or the Linux console. If something goes wrong, you can always go back to the console and fix things—if you know a few basics of Linux administration. To reach the console from the login screen, you can use the key combination ALT+F1, or ALT+F2 to go to the second console, etc.

After logging in on the console, you are in control of a shell. The default shell is called bash [1], but there are many other shells available. You can use the shell to type in commands for your computer to execute, but also to write programs (scripts) that combine commands to do more complex tasks. For example, this handbook is generated by a bash script combining a few text and graphics related tools.

This chapter will introduce you to the basics of exploring and administering your MNT Reform system using the shell first and then a graphical desktop. You can also launch shells on the desktop to use tools that don’t have a graphical user interface. Using these tools, you can troubleshoot some problems with the operating system by yourself.

Root User

The most powerful user in the system is root. When logged in as root, you can modify but also destroy any file in the system. To prevent others from logging in as root, you should protect the account with a password (the Setup Wizard asks you to do this). In the shell, you execute all commands by typing them in and pressing ENTER. To set your password, execute this command:

passwd

The passwd command will ask you for a new password two times, but will not display it while typing (so it cannot be gleaned by onlookers).

During normal Linux usage you will rarely want to be root—only when performing changes to the system configuration, which includes adding or removing users or software and controlling background services. Instead, you should create a less privileged user account for yourself.

Create a New User and Password

You have created a user in the Setup Wizard after powering on your MNT Reform for the first time. In order to add another user account to the system, log in as root and execute the adduser command:

adduser kim

This will create a new user named kim, and add a new home directory for kim at /home/kim. The adduser command will ask you for a password and a few questions that you can skip by just pressing ENTER.

If you want to change the password for the user kim later, you can use the passwd command as before:

passwd kim

Logging In and Out

You can log out of the console or a terminal window by pressing CTRL+D. Alternatively, you can type exit in the terminal.

When logged out, you will see the login prompt. Type the username that you added in the previous step and press ENTER. Next, type your password (it is not displayed). Press ENTER to complete the login.

Sudo

To make bigger changes to the system you will often need to use a command that requires root (superuser) privileges. Logging out of your user account just to log back in as root is inconvenient. Instead, you can temporarily become root by either switching to it as su (switch user) or give your regular user account sudo privileges [2].

Sudo allows you to use a command as root by typing sudo command—but only if you are a member of the sudo group. To add your user to the sudo group, first log out and login as root. Then you can execute the following command:

usermod -a -G sudo kim

(Substitute your username for kim here).

The -a flag means “Append the user to the group”, while the -G option specifies the name of the group you want to add the user to: sudo.

Log out and login as your regular user again. From now on, you can execute commands which require root privileges using sudo. For example, to shut down your computer safely before turning it off, you can type:

sudo shutdown now

File System

Your system’s file storage is organized in a tree of directories. To move around in it, you use the cd command to change the current directory. The top of the hierarchy is called root (not to be confused with the superuser of the same name), but written as the symbol /. To go to the root directory, enter:

cd /

To see what’s here, use the ls (list) command:

ls

If you want to know more details, such as the modification times and permissions of files, use:

ls -l

You can also add the flag -h to get “human readable” file sizes instead of the raw number of bytes:

ls -lh

There are two virtual files in every directory, called “..” (two dots) and “.” (one dot). The single “.” means “here” (i.e. the current directory), and you can use it if you ever want to specify the current directory explicitly. For example, if you want to copy the file /tmp/myfile to the current directory, you can type:

cp /tmp/myfile .

To go to the parent directory (a top-level directory that contains subdirectories, the so-called “children”), use:

cd ..

Commands like ls have many options. To learn about them, you can read the built-in manual pages:

man ls

With man you can learn more about any command. You should make yourself familiar with the most important commands like cp (copy), mv (move), rm (remove), mkdir (make directory), mount and ln (link). Armed with this knowledge, you will be able to navigate any UNIX-like system, not only Linux.

Filesystem Hierarchy

When you issue ls at the root of the filesystem (/), you will see the following directories:

Directory

Purpose

/

Top (“root”) of the filesystem

/bin

Commands (“binaries”), such as ls, cp

/sbin

Commands usually only used by root

/lib

Libraries (common code shared between binaries)

/usr

Files managed only by the package manager

/boot

Boot loader related files (like Linux kernel [3])

/etc

System configuration files

/home

Home directories of user accounts

/root

Special home directory for root

/mnt

A place to mount other filesystems

/media

Another place to mount filesystems

/proc

Live information about processes

/sys

More live information from the kernel

/dev

Device files providing access to hardware

/run

Temporary files related to background services

/tmp

Temporary files—deleted on restarts

/srv

Files used by servers such as web servers

A good way to explore files and directories that take up disk space is using the ncdu program. It calculates the size of each (sub)directory and allows you to browse your filesystem and even delete unwanted files (you should only do this in your home directory, though):

ncdu /

Home Directory

If your username is kim, your home directory is located at /home/kim. There’s a shortcut for your home directory using the tilde symbol ~. To go to your home directory, you can type:

cd ~

If you list the contents of your home directory, you will see a number of directories with self-explanatory names, such as Pictures, Music, Documents and Downloads. The last one is used by web browsers to store downloaded files, for example. Feel free to create your own subdirectories in your home directory as needed.

Dot Files

Your home directory also contains a number of hidden files and directories called “dot files”. Their names start with a dot (.) and for tidiness, are usually hidden. To see them, use the -a flag with ls:

ls -a

Often times, dot files contain your personal configuration for certain programs. Many programs collect configuration files in the ~/.config subdirectory.

Permissions

As you are the owner of your home directory, your user account is allowed to modify any files and subdirectories contained in it. But you cannot change system configuration files in /etc or delete a command in /bin, except if you’re root. This is because of the ownership and permission settings on these files and directories.

If you list the contents of your home directory with ls -l, you will see your username twice in each row, after a cryptic-looking column of letters and dashes and a number:

drwxr-xr-x  4 kim kim 4096 Nov  2 20:52  Music
rw-r--r--   1 kim kim    8 Jan  9 20:03  notes.txt

The letters and dashes at the beginning describe the file mode bits of the file or directory. A “d” at the beginning signifies a directory. The following 9 letters are three triplets describing “user” (owner), “group”, and “all” permissions, in that order. “r” means read, “w” write and “x” execute. An “x” on a file means that this is an “executable”, a program that can be run, or in the case of a directory, that it can be entered.

The first occurrence of a username in each row is the owner of the file or directory. The first triplet of mode bits on notes.txt tells you that you, the owner, can read and write but not execute this file (after all, it is just a text file).

The second occurrence of kim names the group kim, not the user. When you create a new user, the system also creates a group with the same name and only you as a member. You could add other users to your group to share files with them, for example. The second triplet of mode bits, r--, tells you that members of this group can only read your file, not change it.

Lastly, the third mode triplet (r-- in this example) says that any other user logged into your system can read this file.

To change the mode bits of a file, you can use chmod. For example, to give nobody but yourself (assuming you’re the owner) the permission to read and write the file notes.txt, execute:

chmod a=,u=rw notes.txt

This invocation first sets an empty list of modes for all users (a=) and then read and write modes for the user/owner (u=rw) on the file.

To learn more about managing modes and ownership, be sure to read the man pages for chmod, chown, and chgrp.

Pipes

Linux features some advanced concepts that are central to the UNIX philosophy (Linux is a flavor of UNIX). One that you will often encounter is the pipe, symbolized by |. You can use pipes to feed the output of one program to the input of another program. For example, you can use the pager less to paginate a long stream of text, such as the output of dmesg. This tool prints all diagnostic messages of the operating system kernel, and using less lets you view it page-by-page instead of having to scroll back to the beginning:

dmesg | less

Or page through a long list of files:

ls -la ~/Downloads | less

You can also build more complex pipelines. The following command will output the last 5 lines containing the word “usb” in the kernel log:

dmesg | grep usb | tail -n 5

Finding Files

If you don’t remember where you put a file, or want to search a complex hierarchy of directories for something specific, you can use find:

find -name "notes*"

This will display any file or subdirectory whose name starts with “notes” in the current directory. man find will reveal many more options for finding files.

The rgrep command will look for words in the content of a file:

rgrep --color spice

This will look for any occurrence of the word “spice” in files in the current directory and its subdirectories, and display each line in which the word was found, with the word itself highlighted.

Mount Points

The root directory / is actually a collection of filesystems “mounted” into one virtual filesystem. These can be located on different disks, media or even the network—or be purely virtual in the case of /dev, /proc or /sys.

For example, if you want to access files stored on a USB stick, you would first mount one of the filesystems contained on the USB stick into an empty directory called a mount point. This could be something like /mnt or /media/usb-stick. Usually, desktop environments can help you to automatically mount removable media, but it’s useful to know how to do the same process manually.

First, you need to find the block device of the media you want to mount. For this, you can use the command lsblk. An example (partial) lsblk output could be:

NAME          MAJ:MIN RM   SIZE RO TYPE  MOUNTPOINT
sda             8:0    1  28.9G  0 disk
  sda1          8:1    1  28.9G  0 part

Here, sda1 is the block device of the first partition on the USB stick. If you are unsure which is the right device, you can issue dmesg -w and then plug in the USB stick. You’ll see something like this appear in the kernel log:

[...] sd 0:0:0:0: [sda] Attached SCSI removable disk

Which tells you that sda (or in your case, something else) is the block device you’re looking for.

To mount the partition on the USB stick at /mnt, do:

sudo mount /dev/sda1 /mnt

If successful, this will—in UNIX tradition—output nothing, and you can find your files by navigating to /mnt with the usual commands.

Before unplugging your USB stick, you should unmount it. This makes sure any pending changes are written to the device (note that the command is umount, not “unmount”):

sudo umount /mnt

Environment Variables

As the shell is not only a command interpreter but also a programming environment, it supports variables. These are placeholder names that contain a value that can be changed at any time. For example, you could make a universal greeting command like this:

echo Hello, $name.

The output of this command changes depending on the value of the variable $name. To change the variable:

name=World

If you now execute the same echo line as before, you’ll see this output:

Hello, World.

Variables are often used to define an environment for other programs. This means that a program can change its behavior according to these variables. These so called environment variables are set before starting the program. To see all currently defined environment variables, you can use the env command. You will see a few specific ones among the output:

HOME=/home/kim
PWD=/home
SHELL=/bin/bash
USER=kim

This means that another way to reach your home directory is cd $HOME, and another way to refer to your username is $USER. A critically important variable is $PATH, which is a list of directories (separated by “:”) that the shell searches when looking for a command that you want it to execute. For example, when you type ls, your shell will only find it if /bin is in your $PATH, because ls actually resides at /usr/bin/ls.

Working with Text Files

Most system configuration is done by editing text files.

The two most common text editors in Linux are vim and emacs, which both have a steep (but rewarding) learning curve. Thus, Reform system provides an editor more suited for beginners called micro.

You can create, view, and edit files using the micro text editor. To edit a file in the current directory named file.txt, use:

micro file.txt

While in micro, you can use CTRL+S to save, CTRL+Q to quit, and CTRL+G to display a help menu.

Scripts

By now you know most of the ingredients to be able to write shell scripts: programs interpreted by the shell. By writing shell scripts, you can create your own commands to extend the capabilities of your computer. Here is an example script that greets the user:

#!/bin/bash

day=$(date +%A)
echo Hello, $USER. Today is $day.

The first line of the script, called the “shebang” line is important to tell the operating system that this script is to be interpreted by the shell /bin/sh. Save the script to a file named greet.sh. Mark the file executable and execute it:

chmod a+x ./greet.sh
./greet.sh

You can learn more about programming the shell by reading its manual page man sh. The more advanced bash shell is documented in man bash.

What Is My Computer Doing?

You can check your RAM usage, CPU usage, and processes currently running by using htop:

htop

Hit F1 to display the built-in help screen.

You will see that there are a few processes running that you didn’t start yourself. These are background processes, also called services, daemons, or units. They are controlled by systemd, the so-called “init system”. It is the first program started by the Linux kernel, and it spawns all other programs including services. You can learn more about systemd by reading the manual page:

man systemd

The most important commands to manage systemd are systemctl and journalctl. Their manual pages are worth a look, too. To see the list of known units and their status, you can use:

systemctl

To inspect a unit in more detail, you can pass its name to systemctl. For example:

systemctl status ssh

Instead of status, you can use verbs like start, stop or restart to control units.

The Linux kernel itself outputs a lot of diagnostic information at boot and when hardware changes (e.g. new devices are plugged in). To see the kernel log, you can (as superuser) use:

sudo dmesg -H

Inspect Hardware

The following commands are useful to inspect devices connected internally or externally:

Command

Description

lsblk

List block devices (storage).

lsusb

List USB devices.

lspci

List devices connected to PCIe ports.

lscpu

Get information about the processors.

free -h

Get information about system memory.

Clock

To see the current date and time, you can use the date command. The date and time are set by the ntp (“Network Time Protocol”) service by synchronizing to time servers on the internet.

The motherboard of MNT Reform has a battery-backed real-time clock chip (PCF8523T, U5). This chip saves the date and time even if your system is shut down or loses power. You can interact (as root) with the clock using the hwclock tool. Review man hwclock for the details.

Network

MNT Reform has a built-in Gigabit Ethernet (1 GbE) port for networking. Additionally, you can install a Wi-Fi card in the mPCIe slot (depending on your Processor Module), or the module itself comes with a Wi-Fi chip.

Usually, you want to use a convenient management tool like network-manager (preinstalled) and the tool nmtui to manage your network connections.

To see and change details of your network connections, you can use the ip tool:

Command

Meaning

ip addr

Show the status of the network interfaces [4].

ip route

Show the network routing table.

You can trigger an automatic configuration of an interface via DHCP by executing dhclient eth0, and you can change the DNS servers by editing the file /etc/resolv.conf.

To connect to a remote computer via a secure shell connection, try ssh followed by the IP address of the computer you want to connect to. If you want to login to MNT Reform over the network, you can enable the secure shell daemon service as follows:

sudo systemctl enable sshd

You can then login to MNT Reform from another computer on your local network by executing:

ssh kim@192.168.1.242

Replace the username kim``with your own username and the IP address ``192.168.1.242 with your own IP address. You can find your IP address by looking for the inet entries in the output of the ip addr command.

Before using SSH functionality, you should generate a public/private key pair by executing ssh-keygen.

Bluetooth

Some Processor Modules, such as the RCM4 with A311D, feature integrated Bluetooth. This technology lets you connect to wireless devices that are close to your MNT Reform (usually a few meters), such as headsets, speakers or mobile phones. If you ever need to troubleshoot Bluetooth, you can try restarting its service using systemctl restart bluetooth or interact with blueman on the command line using bluetoothctl.

Dual Display

MNT Reform has an HDMI connector that has different functions depending on the installed Processor Module:

Module

Dual Display

i.MX8MQ

Yes

i.MX8MPlus

Yes

LS1028A

No

RCM4 for Raspberry Pi

Yes

RCM4 with A311D

No

RK3588

Yes

To activate dual display with i.MX8MQ, for example, run the following command:

reform-display-config --dual

Other modules that support dual display will activate this function automatically.

Shutdown

To turn off MNT Reform, you should shut down the system cleanly by executing:

systemctl poweroff

or

sudo shutdown -h now

On the graphical desktop, you can click the reform-tray icon and select shutdown.

In the Debian system shipped with MNT Reform, the shutdown process will ask the System Controller to turn off the power. The OLED display will then show an animation of a disappearing MNT Research logo. In case you have to turn off the power manually (for example if the system is unresponsive or you are using an alternative OS), press Circle and then 0 (zero).

Standby

The standby function works with only some of our Processor Modules.

LS1028A doesn’t support standby, and at the time of writing, it is still in development for A311D. The i.MX8MQ system-on-chip, on the other hand, can enter a low power standby mode. This function is stable for this module, but always save your work to disk regardless. In our tests, the power consumption in standby mode is roughly halved compared to the normal working mode.

To enter standby mode, execute the provided reform-standby script:

reform-standby

You can also use the reform-tray icon and select standby mode.

To make the system wake up from standby, select the Wake item from the keyboard OLED menu.

Installing and Removing Software

The Debian GNU/Linux distribution has access to a large number of software packages. No matter which desktop you use, these are centrally managed by apt, the package manager. Generally, on a Linux system you rarely download executables from the internet and launch them. Instead, you can cleanly install and remove software packages by using the package manager. apt also has the ability to search for keywords (or regular expression patterns):

apt search browser

This will list all packages in the apt cache that contain the keyword “browser”. To refresh apt’s list of packages available in the online Debian repository (the library of packages), use the following command:

sudo apt update

If you have found a package you would like to install:

sudo apt install firefox

To remove (uninstall) the package from your system:

sudo apt remove firefox

To explore all of apt’s functionality, read the man pages for apt and apt-cache. If you are more comfortable with a graphical user interface for managing apt packages, you can use the command reform-synaptic.