# Overview

This page is for people will little or no Linux experience. It will give you enough information to install and use Allsky. If you are new to the Raspberry Pi see the Pi Basics page. The Allsky documentation assumes you know what's on these two pages. For example, you know how to log into the Pi, move around to various directories, view and edit files, and execute commands.

To get information on any Linux command, enter `man command_name`, for example, `man date` at a command prompt on your Pi.

## Logging into your Pi

There are several ways you can log into a Pi.

1. Plug a keyboard, mouse, and monitor directly into the Pi. Although this is the easiest way, it requires that you have access to the Pi, which when used with an allsky camera is rarely the case, except when you're initially setting up the Pi.
2. The Pi comes with a VNC (Virtual Network Connection) server, so you can access the Pi remotely by installing a VNC client on your PC, phone, tablet, or almost any other device. When using the VNC client, you see your Pi desktop and interact with it as if you were directly attached to the Pi.
3. SSH (secure shell) is used to log into the Pi from a remote devices, usually a PC or Mac but could be a tablet or phone. SSH needs to be enabled on the Pi - this should be done while imaging your SD card.
   Once SSH is enabled, do the following to use it:
   1. On the remote device, open a terminal window (`cmd` on Windows or `terminal` on Mac)
   2. Type `ssh pi@allsky.local`.
   3. Enter the password when prompted.
   4. You can now enter Linux commands.

## Linux Desktop

Linux is similar in many ways to Windows and MacOS - they all have a Desktop as well as a command-line interface (also called a "terminal window"). Most of the interactions you'll have with your Pi for Allsky-related tasks will be via the command-line, whereas in Windows and MacOS the terminal window is rarely used.

The screenshot below shows a typical Linux desktop. Starting from the far left are 5 icons followed by a file explore window and a terminal window showing the output of the `date` command. At the bottom is the taskbar.

Terminal Windows like the one above with a gray background have no graphics - only characters. They prompt for commands to enter, so are also called a "command-line interface". Windows' primary command-line interpreter is called `cmd` and looks like a DOS window. The command-line interpreter, also called a "shell", used by Allsky is called `bash`.

Notice the install.sh file in the left window above has an extension of `.sh` which signifies it's a shell script. Unlike in Windows, Linux commands don't actually need an extension, but the Allsky text-based commands have extensions so it's obvious what type of file they are.

Throughout the Allsky documentation you'll see instructions like:

Execute the following:

    cd
    ls -l

The `cd` and `ls -l` commands should be executed at the command-line.

## Executing commands

To execute a command type its name followed by any optional arguments:

    date
    sudo systemctl start allsky

In this example, `date` and `sudo` are the names of commands. `date` has no arguments and `sudo` has 3 arguments.

Just like in other operating systems, files and commands have permissions that determines who can view, edit, and execute them. By default, when you log into to the Pi, you are running as the "pi" login (or whatever you called it), which has limited permissions, e.g., it generally can't update system files. In Linux, the "root" login ("admin" in Windows) can do anything.
In the example above, the `date` command can be executed by anyone but the `systemctl` command can only be executed by the "root" login. The `sudo` command runs its first argument (`systemctl`) as "root" and passes the last 2 arguments to `systemctl`.

> An interesting fact - the "root" login is also called "super user", hence `sudo` - "super user do".

If an argument contains a space or other "special characters", it must be quoted, otherwise it's treated as multiple arguments:

    echo "Hello world!"
    echo         "Hello world!"
    echo "Hello    world!"
    echo Hello    world!

The first line above has a single space between `echo` and the argument and the second line has several spaces. Those spaces are considered "white space", and unless quoted, the shell doesn't care if there's one white space or a million. Hence, both those lines are treated the same. The output from all four lines is below. The first three commands have one argument (it's surrounded by double quotes) and the forth command has two arguments since there are no quotes.

    Hello world!
    Hello world!
    Hello    world!
    Hello world!

## Moving around the filesystem

Windows has multiple "drives", each with its own letter, e.g., C:, D:, etc., and each drive has a topmost, or "root" directory, called \, e.g., C:\. Linux does not use drive letters but has a single "root" directory, called /. Windows uses \ to separate directories and Linux uses /, for example: /home/pi/allsky
The above string is called a "path name" since it names the path to a file or directory, in this case, the "allsky" directory.

Using /home/pi/allsky as an example:

- The first / is the root directory.
- home is a directory under the root directory, and contains home directories for all the users on your Pi (on most machines, just the "pi" login).
- The second and third / characters separate directories.
- pi is a sub-directory in the home directory that contains all the "pi" login's files and directories and is called pi's HOME directory.
- allsky is the name of a directory that contains the Allsky files, commands, images, etc.

To move from one location to another, use the `cd` (change directory) command. In the examples below, it's assumed you're logged in as "pi". `~` stands for pi's HOME directory, and anything after the `#` is a comment which is ignored.

    cd           # goes to the HOME directory of whatever login you are
    cd ~/allsky  # goes to pi's "allsky" directory
    cd /         # goes to the root directory
    cd -         # goes to the previous directory
    cd ../..     # goes up two directories - ".." is called a "parent" directory
    pwd          # displays the current or working directory - print working directory

## Listing files and directories

To see the contents of a directory, type `ls` (list files) (called `dir` in Windows). Like most commands, `ls` takes a bunch of arguments. A common one is `-l` which produces long output.

Note that the output is in color:

- Green indicates the file can be executed (i.e., is a command).
- Blue indicates the object is a directory.
- Black indicates the file is an "ordinary" one.

The long view includes the following 7 columns of data:

1. Permissions. All Linux files have an owner as well as a group the file is in. There are three sets of permissions:
   1. The owner of the file.
   2. The group of the file.
   3. Everyone else, called other.

   A typical listing of the permissions is `-rwxr-xr-x`. If an object is a directory, the first character is `d`, otherwise it's `-`.
   The owner, group, and other entities have three permission flags each (read, write, and execute) for a total of 9 more characters, in groups of 3:

   1. The first character of each group determines if the entity can read the file. `r` means yes; `-` means no.
      For directories, read permission means the entity can view the contents of a directory.
   2. The second character determines if the entity can write to the file. `w` means yes; `-` means no.
      For directories, write permission means the entity can add to, or delete from, the directory, e.g., create a file in the directory.
   3. The third character determines if the entity can execute the file. `x` means yes; `-` means no. Commands must have this flag set, otherwise they can't be executed.
      For directories, execute permissions mean the entity can `cd` into it; "executing" a directory doesn't make sense.

   In our example (`-rwxr-xr-x`), the object is a file, the owner can read, write, and execute it (which implies it's a command), anyone in the group the file is in can read and execute the command but not write, i.e., change it, and everyone else can also read and execute it.

2. Number of links to the file. You can normally ignore this field.
3. Name of the owner of the file.
4. Name of the group the file is in.
5. Size in bytes of the file. Directories are usually a multiple of 4096.
6. Date the file was last modified.
7. Name of the file.

In the screenshot above all the objects are owned by the `pi` login, and all but one object is also in the `pi` group. Note this entry:
It's in the `www-data` group, which is the group that the web server runs in. Because the web server (which runs the WebUI) creates configuration files in that directory, it also has `rwx` group permissions so it can look in the directory and create files there.

## Viewing / editing files

The `cat` (catenate) command outputs the contents of a file. For small files this is fine, but what if the file is larger than the size of your terminal window? In that case, use `more` which will display the file one page at a time. Pressing the space bar will move to the next page. If you only want to see the beginning or end of a file, use `head` or `tail`. They default to displaying 10 lines but if you want more or less add an argument such as:

    head -20 some_file

to display, for example, the first 20 lines.

The most common text-file editor is `nano`. Before using it you'll probably want to view its manual page by typing `man nano`.

## Standard in, standard out

By default, commands that expect input read it from the keyboard (referred to as "standard input" or "stdin") and write to the terminal window ("standard output" or "stdout").
If you want the input to come from a file, or the output to go to a file, use `<` or `>`:

    # This create a file called /tmp/x and writes "Hello World!" to it.
    echo "Hello World!" > /tmp/x

    # This displays the contents of /tmp/x, which is "Hello World!".
    cat < /tmp/x

> Many commands, including `cat` also accept a filename as an argument, and process that file, so these are functionally the same:

>     cat < /tmp/x
>     cat /tmp/x

## Shutting down the Pi

Most operating systems, including Linux and Windows, don't like it when you simply unplug the power to the device. On the Pi you should instead use the button on the WebUI's System page or via the command prompt:

    sudo shutdown -r now

You won't know when the Pi has fully shutdown so wait 30 or so seconds before turning the power off.

## Getting help

You can get information on all Linux commands via the `man` command. Most commands also take a `--help` option (including the Allsky commands that can be run manually):