How to install NetBSD on Odroid XU4/HC1/HC2 from MacOS (beginners)
Tags: netbsd, odroid, devops
Published: 2020-08-07 17:14:34

# Intro

In this tutorial I will do my best to guide you through NetBSD installation on Odroid XU4/HC1/HC1 to the point where you can remotely log in into your system and obtain admin permissions so you can do anything you want with your Odroid device.

Although HC1 and HC2 conveniently support external drives (HDD or SSD) you can't boot directly from those drives and you will still need to create a bootable SD card.

## OS image

OS image is a file that contains exactly what should be written onto the target disk with the byte precision. It means that OS image will be copied onto the SD card byte-by-byte and it usually contains the operating system you can run out of the box without the need of running the installation procedure. So in basic terms you can say it's the entire preinstalled operating system contained in one file. 

After you write that file directly to the SD card it would produce runnable NetBSD with some basic user accounts, DHCP (system service that obtains IP address from your router) and SSH server (allows remote system management).

## Inserting the SD card

First, insert SD card into SD card reader. It does not matter if it contained anything before. You do not need to format it in advance.


After you insert a card into the SD card reader, there is a chance you will get some prompt from Finder that states that the card is either unreadable or Mac will mount the card like it would mount a pendrive. Don't worry about that, it is not important.


The important thing is to unmount the card if it was automatically mounted by the OS before writing the OS image into it. If you are unsure if it's mounted, then you should proceed with the next steps anyway. It won't harm anything.

First you need to determine how the MacOS sees the card. You can do that by typing `diskutil list` in the terminal.

This is the output I saw on my Mac.

```
➜  ~ diskutil list                  
/dev/disk0 (internal, physical):
   #:                       TYPE NAME                    SIZE       IDENTIFIER
   0:      GUID_partition_scheme                        *251.0 GB   disk0
   1:                        EFI EFI                     209.7 MB   disk0s1
   2:                 Apple_APFS Container disk1         250.8 GB   disk0s2

/dev/disk1 (synthesized):
   #:                       TYPE NAME                    SIZE       IDENTIFIER
   0:      APFS Container Scheme -                      +250.8 GB   disk1
                                 Physical Store disk0s2
   1:                APFS Volume Macintosh HD - Data     217.5 GB   disk1s1
   2:                APFS Volume Preboot                 82.1 MB    disk1s2
   3:                APFS Volume Recovery                528.6 MB   disk1s3
   4:                APFS Volume VM                      3.2 GB     disk1s4
   5:                APFS Volume Macintosh HD            11.3 GB    disk1s5

/dev/disk2 (internal, physical):
   #:                       TYPE NAME                    SIZE       IDENTIFIER
   0:     FDisk_partition_scheme                        *31.9 
```

The list contains three disks (`/dev/disk0`, `/dev/disk1`, `/dev/disk2`). I know that my SD card is a `/dev/disk2` because it is a 32GB storage and I do not have any other disk with that capacity. If you are not sure which of your disks listed here is the SD card, you should first remove your SD card, run `diskutil list` then insert your SD card again, run `diskutil list` again and check if the new disk appeared on the list. The new one is most probably your SD card.

It is *really important* you are 100% sure which of those devices is your SD card, because if you make a mistake in determinig that you will irreversibly erase the entire content of the incorrect disk.

## Unmounting the SD card from the OS

First, you need to unmount the SD card from the system, so you can be sure Finder and other applications won't be using it. You can do it by typing `diskutil unmountDisk /dev/disk2` in the terminal. 

This is the output I saw in my terminal:

```
➜  ~ diskutil unmountDisk /dev/disk2
Unmount of all volumes on disk2 was successful
```

## Obtaining the OS image

Now you need to obtain the NetBSD OS image. You can download it from this page:

https://www.armbsd.org/arm/

"Hardkernel ODROID-XU3/XU4" is the correct one to use with either Odroid XU4 or HC1/HC2, because HC1 and HC2 is basically Odroid XU4 under the hood.

You will download archived image (named something like `NetBSD-9-earmv7hf-odroid-xu3.img.gz`). You need to unpack it first, so you will get just the `*.img` file. You can do that using Mac unarchiver or using command prompt with `gunzip` command (you need to invoke that command afer `cd`'ing into the directory that contains the archive):

```
➜  ~ gunzip ./NetBSD-9-earmv7hf-odroid-xu3.img.gz
```

Your downloaded filename might be different than `NetBSD-9-earmv7hf-odroid-xu3.img` (for example it might be something like `NetBSD-9-earmv7hf-202008061850Z-odroid-xu3.img.gz`). Don't worry about that, just use your filename instead of `NetBSD-9-earmv7hf-odroid-xu3.img`. I will stick to that one in this tutorial though.

## Writing the OS image into the SD card

After you obtain the OS image, you need to write it into your SD card. Please keep in mind that after this step, the entire content of your SD card will be irreversibly erased and replaced by NetBSD.

Writing an image requires admin permissions, you can do this using `sudo` and `dd` command. `dd` will copy the OS image byte-by-byte onto the SD card.

You need to invoke this command in the directory that contains the NetBSD OS image:

```
➜  ~ sudo dd if=./NetBSD-9-earmv7hf-odroid-xu3.img of=/dev/rdisk2 bs=4m
```

You can notice that I used `/dev/rdisk2/` instead of `/dev/disk2`. It is not a typo, `rdisk2` is a raw device and writing to that device with tools like `dd` is faster. I don't want to get into details of that here. In short, this way is faster.

Also notice that I used `*.img` file and not the `*.img.gz` file.

Running `dd` can take a few minutes and there is no progress bar. If you want to see progress after running the command, you can press `CTRL+T` in the terminal window while the command is running.

MacOS might show you this prompt just after you run `sudo dd ...`. You can just allow the MacOS to proceed.

![You can just allow the MacOS to proceed](https://dev-to-uploads.s3.amazonaws.com/i/ltsixianz2ayh4r9te9a.png)

Do not eject your SD card yet.

## Setting up credentials

After `dd` finishes, you need to create the `creds.txt` file (as stated here: https://wiki.netbsd.org/ports/evbarm/) on the SD card to insert your initial user credentials. Usernames and passwords you type into that file will be the default initial user accounts in the NetBSD. You can change those later from the NetBSD, but you can't add `creds.txt` file later.

To do that you need to mount the newly created partition into the OS. First you need to find out it's device name. You can do that by typing `diskuti list` again in the terminal. You should see something like this under your equivalent of mine `disk2` device:

```
/dev/disk2 (internal, physical):
   #:                       TYPE NAME                    SIZE       IDENTIFIER
   0:     FDisk_partition_scheme                        *31.9 GB    disk2
   1:             Windows_FAT_32 NETBSD                  83.9 MB    disk2s1
   2:                     NetBSD                         1.1 GB     disk2s2
```

`creds.txt` file needs to created on the `Windows_FAT_32` partition. You need to mount it first using the command `diskutil mount /dev/disk2s1` (`disk2s1` is the partition identifier listed above). This is the terminal output I saw:

```
➜  ~ diskutil mount /dev/disk2s1
Volume NETBSD on /dev/disk2s1 mounted
```

You should see the `NETBSD` removable drive in the Finder now. You can create `creds.txt` file by just creating a new file in the finder or via terminal by typing those commands and editing the file:

```
➜  ~ cd /Volumes/NETBSD/
➜  ~ nano creds.txt
```

`nano` is the editor I am using here, but you can choose your own (more on nano here: https://wiki.gentoo.org/wiki/Nano/Basics_Guide).

In the end my `creds.txt` file looks like this:

```
useradd tempuser test123
```

It means that NetBSD will create `tempuser` with password `test123` after you insert your SD card into the odroid and run it. You can add as many users as you want, each one in the new line of the file. You can also name the user as you want.

After creating `creds.txt` file you need to unmount your SD card again by typing `diskutil unmountDisk /dev/disk2` in the terminal. 

If you get an error message like this:

```
➜ ~ diskutil unmountDisk /dev/disk2
Unmount of disk2 failed: at least one volume could not be unmounted
Unmount was dissented by PID 1318 (/bin/zsh)
Dissenter parent PPID 1315 (/usr/bin/login)
```

You need to first move into a any different folder in the terminal (for example type just `cd` and try again). The message above means that the disk cannot be unmounted because it's in use. It's in use because you are in this directory in the terminal. To be safe you can also close Finder window and then use `diskutil unmountDisk /dev/disk2` command again.

You can remove your SD card now.

## Running Odroid with NetBSD

Before inserting the SD card into the Odroid, power it off first (just unplug the device), insert the SD card, insert the network cable connected to the router and power it on.

Give NetBSD a several minutes to spin up and start.

## Determine the Odroid IP address

NetBSD will obtain the IP address from your router automatically using DHCP. To determine it's IP address you need to open your router interface. This step depends entirely on your router, so you will need to determine this on your own. Just google something like `router {insert your router model here} how to list dhcp clients`. By default, NetBSD will have `armv7` hostname.

In my router it looks like this (I censored my other IP's and mac addresses with black squares):

![Determining Odroid IP](https://dev-to-uploads.s3.amazonaws.com/i/99vf1bfgefji1s68kerp.png)

## Logging in into the NetBSD

Now you can log in into your NetBSD. On Mac, open the terminal and use the command:

```
➜ ~ ssh tempuser@192.168.1.212
```

Replace `tempuser` with your username you entered into the `creds.txt` file and `192.168.1.212` with your device IP address.

You should see something like this when you use `ssh` for the first time:

```
The authenticity of host '192.168.1.212 (192.168.1.212)' can't be established.
ECDSA key fingerprint is SHA256:sOmeThingSomeThingSomething.
Are you sure you want to continue connecting (yes/no/[fingerprint])?
```

Just type `yes`. Then you will be prompted for password. If everything went well, you should see NetBSD's terminal. Congratulations!

```
NetBSD 9.0_STABLE (GENERIC) #0: Wed Aug 5 15:20:21 UTC 2020

Welcome to NetBSD!

Thank you for helping us test and improve this NetBSD branch.

armv7$ 
```

By default it does not have `sudo` installed. To login as root, just type `su`.

```
armv7$ su
armv7# whoami 
root
armv7# 
```

## Summary

Thats all. You should be able to happily use NetBSD on your Odroid device now. You can follow official NetBSD docs to learn more about the system and how to use it and secure it further:
https://www.netbsd.org/docs/