Linux Basics ============ The Console and Shell --------------------- With the provided SD card inserted, MNT Reform will boot to a Linux console, which is a pure text interface (opposed to a graphical windowing environment). This is so that you have a chance to learn about the lowest level of interaction with the operating system before moving on to more fully featured desktops. If something goes wrong, you can always go back to this level and fix things---if you know a few basics of Linux administration. After logging in on the console, you are in control of a **shell**. The default shell is called ``bash`` [#]_, 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. Even on a desktop you will find yourself launching shells to quickly perform tasks all the time. It is worth to invest the time to learn these basics, because you will be able to troubleshoot most problems by yourself, rather than relying only on graphical user interfaces that---while convenient---can obscure the system that lies beneath. .. [#] The "GNU Bourne-Again Shell". Set a Root Password ------------------- 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. In the shell, you execute all commands by typing them in and pressing *ENTER*. To set your password, execute this command: .. code-block:: none 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 ------------------------------ In order to add a new user account to the system, log in as ``root`` (you already have) and execute the ``adduser`` command (this will add a new user named ``kim``, and add a new home directory for ``kim`` at ``/home/kim``): .. code-block:: none adduser 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: .. code-block:: none passwd kim Logging In and Out ------------------ You can log out by pressing *CTRL+D*. Alternatively, you can type ``exit``. When logged out, you will see the login prompt. Enter the username that you added in the previous step and press *ENTER*. Next, enter 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 [#]_. Sudo allows you to use a command as ``root`` by typing ``sudo ``. To add your user to the ``sudo`` group, first log out and login as ``root``. Then you can execute the following command: .. code-block:: none 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: .. code-block:: none sudo shutdown now .. [#] ``sudo`` means "switch user and do". 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: .. code-block:: none cd / To see what's here, use the ``ls`` (list) command: .. code-block:: none ls If you want to know more details, such as the modification times and permissions of files, use: .. code-block:: none ls -l You can also add the flag ``-h`` to get "human readable" file sizes instead of the raw number of bytes: .. code-block:: none 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: .. code-block:: none cp /tmp/myfile . To go to the parent directory, use: .. code-block:: none cd .. Commands like ``ls`` have many options. To learn about them, you can read the built-in manual pages: .. code-block:: none 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 issued ``ls`` at the top of the filesystem (``/``) before, you might have asked yourself what the purpose of all the directories there are. ======== ============================== */* Top ("root") of the filesystem */bin* Essential commands ("binaries"), such as ``ls``, ``cp`` */sbin* Commands usually only used by ``root`` */lib* Libraries (common code shared between binaries) */usr* Files used by (non-essential) software */boot* Boot loader related files (like Linux kernel [#]_) */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 ======== ============================== .. [#] The kernel is the privileged core of the operating system. 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): .. code-block:: none 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: .. code-block:: none 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``: .. code-block:: none 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: .. code-block:: none 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: .. code-block:: none 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 the output of the kernel log: .. code-block:: none dmesg | less Or page through a long list of files: .. code-block:: none 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: .. code-block:: none dmesg | grep usb | tail -n 5 Links +++++ If you list the contents of ``/usr/lib`` with ``ls -l`` you will see a number of files that point to another file with an arrow (``->``). This is because the file on the left hand side is a "symbolic link" to the "real" file on the right hand side. Symbolic links and "hard links" can be created using the ``ln`` command as a means to point to a file using another name. This can be useful to create shortcuts. Refer to the manual page with ``man ln`` to learn about the details of links. 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``: .. code-block:: none 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: .. code-block:: none 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 +++++ 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: .. code-block:: none 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 stick. You'll see something like this appear in the kernel log: .. code-block:: none [...] 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 stick at ``/mnt``, do: .. code-block:: none 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 stick, you should **unmount** it. This makes sure any pending changes are written to the device (note that the command is ``umount``, not "unmount"): .. code-block:: none 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: .. code-block:: none echo Hello, $name. The output of this command changes depending on the value of the variable ``$name``. To change the variable, do: .. code-block:: none name=World If you now execute the same ``echo`` line as before, you'll see this output: .. code-block:: none Hello, World. Variables are often used to define an **environment** for other programs. To see all so called environment variables, you can use the ``env`` command. Among the output you will see some familiar things, for example: .. code-block:: none 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 ``/bin/ls`` if ``/bin`` is in your ``$PATH`` (which should always be the case). Work with Text Files -------------------- Most system configuration is done via by editing text files. The two most common text editors among Linux users are ``vim`` and ``emacs``. Both of them have a steep learning curve, which can be rewarding to climb---but the standard Reform system also ships with a simpler editor more suited for beginners. This editor is 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: .. code-block:: none 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: .. code-block:: none #!/bin/sh 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: .. code-block:: none 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``: .. code-block:: none 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: .. code-block:: none 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 (press q to quit): .. code-block:: none systemctl To inspect a unit in more detail, you can pass its name to systemctl, for example: .. code-block:: none 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: .. code-block:: none 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. =========== ====================================== To view of a structured list of all clock frequencies in use in the SoC: .. code-block:: none sudo cat /sys/kernel/debug/clk/clk_summary To see a table of interrupts: .. code-block:: none sudo cat /proc/interrupts Clock ----- 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. Usually, you want to use a convenient management tool like ``connman-gtk`` (preinstalled) or ``network-manager`` (available as Debian package) to easily manage your network connections. If you want to low-level troubleshoot, you can use the ``ip`` tool: ==================================== =============================================== Command Meaning ==================================== =============================================== ``ip addr`` Show the status of the network interfaces [#]_. ``ip route`` Show the network routing table. ==================================== =============================================== .. [#] ``eth0`` is the built-in Ethernet; ``wlp1s0`` is a WiFi interface. 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: .. code-block:: none sudo systemctl enable sshd You can then login to MNT Reform from another computer on your local network by executing: .. code-block:: none ssh kim@192.168.1.242 Substitute your username for ``kim`` and your IP address for ``192.168.1.242``. 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``. External Display ---------------- MNT Reform has an HDMI connector that has different functions depending on the installed CPU module. When using the i.MX8MQ module, you can connect an external HDMI display to this port. i.MX8MQ has two display engines, LCDIF and DCSS. In the default configuration, DCSS powers the internal display. If you want to use an external display, DCSS has to power HDMI instead. The internal display can then either be turned off or powered by LCDIF. At the time of writing, there is a limitation in i.MX8MQ that prevents the use of LCDIF together with PCIe devices like NVMe storage---the LCDIF output will glitch when the disk is accessed over PCIe. This means that if you want to use a dual display setup with i.MX8MQ and MNT Reform, you have to run your system from eMMC or SD card instead. You can also use external USB3.0 based storage. The HDMI controller of i.MX8MQ requires a piece of binary firmware that is signed by NXP and loaded by the CPU into the HDMI controller as part of the U-Boot bootloader. If you don't want to use HDMI, you can download an alternative version of U-Boot with the HDMI firmware stripped out at the MNT Reform website. The MNT Reform system software comes with a script to select your desired display output mode and reboot: .. code-block:: none reform-display-config Executing the script without any parameters will show you the available options. Shutdown -------- Before turning off MNT Reform, you should shut down the system cleanly by executing: .. code-block:: none shutdown -h now In the GNOME desktop environment, you can do this---without typing commands---from the menu that appears when you click the power button in the right corner of bar on top of the screen. 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 i.MX8MQ system-on-chip can enter a low power standby mode. At the time of writing, we consider this function experimental and are still optimizing it. Don't rely on the stability of this function and 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: .. code-block:: none reform-standby To make the system wake up from standby, select the "Wake" command from the keyboard OLED menu. Install and Remove 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): .. code-block:: none 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 at the online Debian "repository" (the library of packages), use the following command: .. code-block:: none sudo apt update If you have found a package you would like to install: .. code-block:: none sudo apt install firefox To remove (uninstall) the package from your system: .. code-block:: none 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 install ``synaptic``: .. code-block:: none sudo apt install synaptic