Initial Setup Of A Raspberry Pi

On a Linux system

• Run the lsblk command before the SD card has been inserted to list all known block devices.
• Insert the SD card into a card reader slot.
• Run the lsblk command once more to see which block device has become available when the SD card was inserted. This can be e.g. /dev/sde or /dev/sdi or something else.

In the command below, carefully replace /dev/sdX by the device node identified above. Be sure to use the right device node!

Using the wrong device node may overwrite your computer's hard disk and thus damage your computer's operating system!

dd if=2017-11-29-raspbian-stretch.img of=/dev/sdX bs=8M conv=fsync

The Raspbian image is not just small, so it may take some time until the dd command finishes.

After the Raspbian image has been copied to the SD card there are 2 partitions on the card that are accessible from your PC if you (re-)insert the SD card into your PC's card reader.

For a headless operation of the Raspberry Pi, i.e. without keyboard and monitor connector, it is useful to enable SSH access right from the beginning.

• Copy an empty text file ssh to the boot partition to enable ssh access

The file is removed when the Pi boots, but the ssh service is enabled then.

If the Raspberry Pi has only a WIFI interface (e.g. the Raspberry Pi Zero W) then it may be useful to copy a file with SSID and authentication parameters for the WIFI network to the SD card, so the Pi can automatically connect to the WIFI network immediately after initial power-up.

Create a text file wpa_supplicant.conf with a few lines similar to the example below:

country=DE   # omit if US
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
network={
       ssid="wifi-ssid"
       psk="secret-wifi-password"
       key_mgmt=WPA-PSK
}

Set the country=, wifi-ssid and secret-wifi-password as appropriate for your country and network, and copy the file to the SD card's boot partition.

When the Pi boots next time the file is moved to /etc/wpa_supplicant.conf, and the Pi should be visible on the WIFI network with hostname raspberrypi.

There have been reports that this may not work as expected if the Pi has both a WIFI and an RJ45 network interface (e.g. the Raspberry Pi 3), so if an RJ45 connector is available then the WIFI interface should be configured later, when the Pi is running.

If also ssh access has been enabled then the Pi should be accessible via WIFI with ssh after power-up.

Immediately after initial power-up the Pi should visible on the network, either via WIFI, or via the cable network, with hostname raspberrypi, and can be accessed by command ssh pi@raspberrypi, with default password raspberry.

Eventually, the user's ssh key should be copied to the target device to allow ssh access without password. On the local machine run:

ssh-copy-id pi@raspberrypi

Commands requiring root permissions have to be run with sudo.

At the first login as user pi the system should be upgraded to the current software version:

sudo apt update
sudo apt upgrade

etckeeper is a nice, optional tool used to track changes to the configuration files in /etc/ then the best choice is to install it next, so the initial changes made afterwards can already be tracked in git. First make sure git is installed:

sudo apt install git   # may already be installed

Set a git user name and email address for user pi and user root, but be sure to use the real hostname:

git config --global user.name "pi"
git config --global user.email "pi@`hostname`"
sudo su -
git config --global user.name "root"
git config --global user.email "root@`hostname`"
exit

Then install etckeeper, which automatically creates a git repo in /etc/ and checks in the current config files:

sudo apt install etckeeper

Once this has been done, configuration changes in /etc/ can easily be tracked.

Like with other git repos it's possible to use a remote repos, e.g. for a backup. If the etckeeper git repo is to be pushed to a remote machine then the remote repo needs to be specified:

sudo git remote add origin USER@HOSTNAME:REPONAME

The remote repo has to exist when the current state is pushed the first time:

sudo git push -u origin master

If new commits are to be pushed automatically to the remote machine, the following line should be present in /etc/etckeeper/etckeeper.conf:

PUSH_REMOTE="origin"

However, the drawback is that possibly local commits are pushed automatically while you're playing with configuration changes.

sudo raspi-config

should be run

• Change User Password to change the password for user pi.
• Network Options to change the Hostname.
• Localisation Options:
  • Change Timezone, e.g. Europe –> Berlin for Germany.
  • Change Keyboard Layout, e.g. Generic 105 (intl) –> German (accept defaults).
  • Change Locale select additional languages to be supported for the user interface, e.g. de_DE.UTF-8 for Germany, and the default locale which should be en_GB.UTF-8 or en_US.UTF-8.
  • Change Wi-fi Country e.g. DE Germany for Germany unless this has already been done when the SD card was prepared.

When raspi-config is finished it asks to reboot now, and this should be done to let the changes come into effect.

It should be checked under Interfacing Options whether the serial port is to be used as a serial console or not, or whether the port and other interfaces are to be enabled or disabled.

Create a new text file e.g. burnicki-aliases.sh in subdirectory /etc/profile.d/

sudo nano /etc/profile.d/my-aliases.sh

and add the required alias commands, e.g.:

alias l="ls -lah"

The file can have attributes 644, there's no need to make it executable.

Users have to re-login to have the specified alias(es) come into effect.

Create user e.g. martin. If the user should be allowed to use sudo then it should be added to the group sudoers. If the user is also added to group staff then he can directly add own programs or scripts in /usr/local/bin, without the need to use sudo for this. The advantage is that you can see which user has put a file into that directory, and /usr/local/bin/ can even be turned into a git repo so changes can be done by any staff user and tracked normally

sudo adduser martin
sudo adduser martin sudo
sudo adduser martin staff

Please note that user pi is member of quite a few more different groups, e.g.
adm dialout cdrom audio video plugdev games users input netdev spi i2c gpio
so possibly the new user might be added to these groups, too.

Possibly you want to copy the user's public ssh key to the Pi to allow login without password. On the local machine run:

ssh-copy-id martin@raspberrypi

or use the hostname which has been specified before instead of raspberrypi.

Let the user be able to use sudo without entering a password, just like it's the defaut for user pi:

Change to directory /etc/sudoers.d. There should be a file for user pi, e.g. 010_pi-nopasswd

cd /etc/sudoers.d
sudo cp 010_pi-nopasswd 011_martin-nopasswd  # copy the existing file
sudo chmod +w 011_martin-nopasswd            # make the copied file writeable
sudo nano 011_martin-nopasswd                # edit the file to adjust the username
sudo chmod -w 011_martin-nopasswd            # Make the file readonly again''

After the change there should be 2 files with file attribute 440:

-r--r----- 1 root root  27 Oct 18  2016 010_pi-nopasswd
-r--r----- 1 root root  31 Jan 28 17:25 011_martin-nopasswd

If ssh agent forwarding is enabled on the target machine then there's no need to store a user's private SSH key on the target machine, even if e.g. a remote git repo is to be accessed via ssh with the user's key.

Instead, the user's private key only needs to be stored on the user's local machine from which the user first logs in to the target machine, e.g. the Raspberry Pi.

On the target machine it's then possible to access e.g. a remote git repo via ssh, using the original user's name and credentials with the remote git repo.

It's very helpful to have the keychain utility installed on the local machine which is the only location where the user's private key is stored.

Edit the file /etc/ssh/ssh_config, i.e., the ssh client configuration file:

sudo nano /etc/ssh/ssh_config

And edit or add the line ForwardAgent to read:

ForwardAgent yes

Note: This enables agent forwarding for all hosts, which can be a security risk. It's better to enable this only for specific, trusted hosts. See:

• http://www.unixwiz.net/techtips/ssh-agent-forwarding.html#fwd
• https://www.veit-schiele.de/dienstleistungen/hosting/dokumentation/ssh-agent-forwarding

Normally there are some simple scripts that can be used to send email.

However, if there is no network connection when the email is to be sent then the email may simply be dropped. If an MTA like postfix (or exim) is used then such emails are queued and can be delivered later, when the network connection is available again, so no emails get lost.

If emails are to be sent over the internet, and not just between nodes on the local network, then a smarthost should be configured, and real email addresses with valid domain names should be used. Otherwise emails might not be accepted by the recipient's email server.

So install postfix and some related utilities:

sudo apt install postfix bsd-mailx sasl2-bin

It's important to install also sasl2-bin if a smarthost with authentication is to be used.

General type of mail configuration:  Satellite system
The "mail name":                     raspi-martin  (unchanged)
SMTP relay host:                     (hostname of the smarthost) 

If the machine hasn't been configured to support IPv6, or emails are to be sent globally but the internet connection doesn't support IPv6 then the postfix should be configured to use IPv4 interfaces only.

Edit /etc/postfix/main.cf

sudo nano /etc/postfix/main.cf

Add the following line to configure usage of IPv4 interfaces only:

# Use only IPv4
inet_protocols = ipv4

Possibly there is already a line reading inet_protocols = all, which has to be commented out then.

Edit /etc/postfix/main.cf

sudo nano /etc/postfix/main.cf

Add the following lines to enable sasl authentication:

# Enable SASL authentication
smtp_sasl_auth_enable = yes 

# Don't use 'noplaintext' below if passwords have to be sent as plain text
smtp_sasl_security_options = noplaintext noanonymous

# Specify the file that contains the credentials for the smarthost(s)
smtp_sasl_password_maps = hash:/etc/postfix/sasl_password  

Create the file /etc/postfix/sasl_password with a text editor:

sudo nano /etc/postfix/sasl_password

and add the credentials required to log into the smarthost:

smtp.netzmafia.de username:geheimespasswort

Change the access permissions to 600 and run postmap to create an associated data base file:

sudo chmod 600 /etc/postfix/sasl_password 
sudo postmap hash:/etc/postfix/sasl_password 

Edit /etc/postfix/main.cf

sudo nano /etc/postfix/main.cf

Add the following lines:

# Specifiy the file that maps user names to valid email addresses
sender_canonical_maps = hash:/etc/postfix/sender_canonical

Create the file /etc/postfix/sender_canonical with a text editor:

sudo nano /etc/postfix/sender_canonical

Add one line for each user to be assigned a valid email address:

pi pi@example.de
root status@example.de
martin martin.burnicki@burnicki.net

Run postmap to create an associated data base file:

sudo postmap hash:/etc/postfix/sender_canonical 

Don't forget to restart the postfix service after any configuration has been changed.

The mailx program that has be installed above with postfix can be used to send a test email, e.g.:

echo "Hello world" | mailx -s "Test email sent by `whoami`@`hostname`" martin.burnicki@meinberg.de

• If an email couldn't be sent then it is held in a queue, and mailq can be run to show the queued emails. The output usually shows the reason why an email couldn't be delivered. Error and warning messages can also be found in the files /var/log/mail.err and /var/log/mail.warn.

• If there's an error saying SASL authentication failed; cannot authenticate to server …: no mechanism available or No worthy mechs found then possibly a package providing SASL hasn't been installed, or the SASL authentication hasn't been configured correctly. The keyword noplaintext may have to be removed from the smtp_sasl_security_options in /etc/postfix/main.cf.

• The command postqueue -f can be used to retry sending queued emails immediately.

• If an email could be sent correctly but doesn't reach the recipient then it may be queued or rejected by the smarthost / relay server. If the "from" address of such an email isn't valid then there's not even a bounce message returned to the sender. It may be helpful to inspect the mail queue on the smarthost, if possible.

To forward all email for local users to external email accounts, edit /etc/aliases/

sudo nano /etc/aliases

and add appropriate entries. For example there is already one entry that forwards all email for postmaster to root, and we add another one that forwards all email for root to me:

postmaster:    root
## Added by martin:
root:          martin.burnicki@burnicki.net

When finished, run

sudo newaliases

to let the changes come into effect.

If all email from an embedded device is to be sent using a standard From: header, e.g.

From: raspberrypi <noreply@burnicki.net>

and the mailx program is used to send emails, then a sender address with real name and valid email address can be added to the mailx configuration file:

sudo nano /etc/mail.rc

Add the line:

set from='raspberrypi <noreply@burnicki.net>'

— Martin Burnicki martin.burnicki@burnicki.net 2018-02-23