[[PageOutline]]

= Ubuntu on Newport =
This page provides details on running Ubuntu on a Gateworks Newport Board.

Other references:
 * The Gateworks [wiki:newport#BoardSupportPackagesBSPSoftware Newport] software page for other Linux options on Newport products.
 * [wiki:/ubuntu Gateworks Ubuntu Page for generic notes]  


[=#prebuilt]
== Gateworks pre-built Ubuntu Disk Image ==
Gateworks provides a pre-built Ubuntu firmware images for the Newport Family:
 * [http://dev.gateworks.com/newport/images/bionic-newport.img.gz bionic-newport.img.gz] - '''(Recommended)''' Compressed Disk Image containing Firmware, Linux kernel, and Ubuntu 18.04 Bionic root filesystem. 
  * To update the firmware on the eMMC see [wiki:newport/firmware#UpdateFirmwareviaSerialConsoleandEthernet]
  * To update the firmware on a microSD card see [wiki:linux/blockdev#UsingaDiskImage]
 * [http://dev.gateworks.com/newport/kernel/linux-newport.tar.xz linux-newport.tar.xz] - Compressed TAR archive of pre-built Linux kernel
 * [http://dev.gateworks.com/ubuntu/bionic/bionic-newport.tar.xz bionic-arm64.tar.xz] - Compressed TAR archive of Ubuntu 18.04 Bionic arm64 root filesystem (does not include kernel)([http://dev.gateworks.com/ubuntu/bionic/bionic-newport.manifest package manifest])

'''Login Information (default)'''
 * Username: root
 * Password: root

Features:
- Ubuntu aarch64 core (created via debootstrap)
- Gateworks Newport Linux kernel
- eth0 dhcp with a 10 second timeout
- User: root password: root
- Packages installed on top of core including:
 * Updated modemmanager/libqmi-utils/libmbim-utils (see [wiki:ubuntu#modem ubuntu/modem])
 * Misc wireless: wpasupplicant iw 
 * Misc utils: vim can-utils i2c-tools usbutils pciutils screen watchdog binutils
 * Misc network: wget ethtool iperf iperf3 openssh-server iptables
 * Linux firmware
 * mmc-utils from https://packages.debian.org/sid/utils/mmc-utils
 * Gateworks [https://raw.githubusercontent.com/Gateworks/meta-gateworks/master/recipes-support/hostapd-conf/hostapd-conf/hostapd-conf hostapd-conf script]
 * Filesystem tools: e2fstools parted
- first-boot script to grow root filesystem partition and filesystem (useful when putting disk images on removable storage devices)
- use ifupdown tools instead of netplan (we find them easier to understand and configure)


To install the kernel and root filesystem on a removable block storage device see [#disk-images below].

== BSP ==

To build a complete Ubuntu image, including all the boot firmware, start with the [wiki:newport/bsp Newport BSP] page as the easiest option.


[=#debootstrap]
== Root filesystem ==
This is to build the rootfs ONLY. To easily build an entire system image, including the boot firmware and Ubuntu, consider the [wiki:newport/bsp Newport BSP] page.

A popular way to create an Ubuntu root filesystem is to use the {{{deboostrap}}} utility on a Debian or Ubuntu host. This tool provides a 2-stage install where the second stage is within a chroot environment using qemu.

Gateworks uses a script to do this which you may find at http://github.com/Gateworks/ubuntu-rootfs

Requirements:
- Linux Ubuntu or Debian System with network connection and sudo permissions

Important notes:
 * We set and use '''target''' and '''distro''' env variables in step 2 and use those env variables in the remaining steps to make this tutorial more version-agnostic. Please be aware of this and do not deviate from the steps unless or until you completely understand what you are doing.
 * These steps are not always exactly what we do in our script but give you an idea of how you would go about doing it yourself if you wanted to customize something

Steps:
1. Install pre-requisites:
{{{
#!bash
sudo apt-get install qemu-user-static debootstrap binfmt-support
}}}

2. Perform first stage install of minimal filesystem for {{{arm64}}} architecture:
{{{#!bash
distro=bionic
arch=arm64
target=${distro}-${arch}
qemu_arch=aarch64
sudo debootstrap --arch=$arch --foreign $distro $target
# copy qemu binary for the binfmt packages to find it and copy in resolv.conf from host
sudo cp /usr/bin/qemu-${qemu_arch}-static $target/usr/bin
}}}
 * See http://ports.ubuntu.com/ubuntu-ports/dists/ for a list of current Ubuntu releases: 18.04=bionic (latest LTS), 16.04=xenial
 * this minimal rootfs is still missing some core packages and configuration before it can be booted. These steps are taken care of in a 2nd stage install within a chroot shell
 * the chroot shell below will provide network support (inherited from the host)

3. We now have a minimal Ubuntu rootfs - chroot to it and perform the 2nd stage install:
{{{
#!bash
sudo chroot $target
# now we are in the chroot - setup env matching the distro above
distro=bionic
export LANG=C
# setup second stage
/debootstrap/debootstrap --second-stage
}}}
 * this is the most minimal rootfs we would recommend

4. (optional) add additional apt package repos:
{{{
#!bash
cat <<EOT > /etc/apt/sources.list
deb http://ports.ubuntu.com/ubuntu-ports $distro main restricted universe multiverse
deb http://ports.ubuntu.com/ubuntu-ports $distro-updates main restricted universe multiverse
deb http://ports.ubuntu.com/ubuntu-ports $distro-security main restricted universe multiverse
EOT
}}}
 * you may want to customize the above list, depending on your needs. See [#packages below] for more detail on Ubuntu package feeds

5. (optional) update package database and setup locales (do not skip this step if you are needing to install any packages for the steps below or otherwise)
{{{
#!bash
apt-get update
apt-get -f install # fixup missing package dependencies
apt-get install locales dialog
dpkg-reconfigure locales
}}}

6. Set hostname:
{{{
#!bash
echo ${distro}-$(uname -m) > /etc/hostname
}}}

7. set a root passwd so you can login
{{{
#!bash
passwd
}}}
 - or consider adding a user via {{{adduser}}}:
{{{
#!bash
adduser myuser
usermod -a -G tty myuser # add to tty group for tty access
usermod -a -G dialout myuser # add to dialout group for UART access
usermod -a -G sudo myuser # add to sudo group for root access
}}}

8. (optional) configure networking:
 - wired ethernet with DHCP on eth0
{{{#!bash
apt-get install net-tools ifupdown
cat <<EOF >> /etc/network/interfaces
allow-hotplug eth0
auto eth0
iface eth0 inet dhcp

EOF
}}}
 - or static IP:
{{{#!bash
apt-get install net-tools ifupdown
cat <<EOF >> /etc/network/interfaces
allow-hotplug eth0
auto eth0
iface eth0 inet static
address 192.168.1.1
netmask 255.255.255.0
gateway 192.168.1.254

EOF
}}}
 - or wireless (requires ~3MB of additional packages):
{{{
#!bash
apt-get install wpasupplicant iw
cat << EOF >> /etc/network/interfaces
# Wireless interface
auto wlan0
iface wlan0 inet dhcp
        wireless_mode managed
        wireless_essid any
        wpa-driver nl80211
        wpa-conf /etc/wpa_supplicant.conf

EOF
wpa_passphrase <myssid> <mypass> >> /etc/wpa_supplicant.conf
}}}

9. (optional) install some useful packages
{{{
#!bash
apt-get install openssh-server # ssh server for remote access
apt-get install can-utils i2c-tools usbutils pciutils # cmdline tools for various hardware support
}}}
 * Note that by default root ssh access is disabled for security. See [wiki:/ubuntu#SSHServer This link] for info on enabling it

10. Exit the chroot shell and remove files we no longer need
{{{
#!bash
exit
sudo rm $target/usr/bin/qemu-$qemu_arch-static
}}}

At this point you have a directory containing a root filesystem (without kernel) and likely want to install it onto removable storage or the on-board FLASH of a target board. Some intermediate formats that are useful to keep around would be a tarball, perhaps an ext4 filesystem image, or a compressed disk image suitable for flashing in the U-Boot bootloader.

To create a tarball which is the most flexible storage format and can be used for a variety of future installation uses:
{{{#!bash
sudo tar --keep-directory-symlink -cvJf bionic-newport.tar.xz -C rootfs/ .
}}}
 * '--numeric-owner' is required to store user/group as a number instead of a name, your specific use case may require this switch. 
 * the '-C rootfs/' is required to eliminate the rootfs directory prefix
 * the sudo is needed to be able to read the root owned files
 * '--keep-directory-symlink' will preserve symbolic links


=== Compressed Disk Image (for flashing onto a board)
To create a 'Compressed Disk Image' using this tarball see [wiki:newport/boot#disk-images newport/boot#disk-images] and to install this onto a board's embedded FLASH see [wiki:newport#serial-ethernet here].


=== ext4 filesystem ===
If desired you can create an ext4 filesystem from the directory or tarball. This requires you choose a size for the filesystem. This size can be increased at runtime using {{{resize2fs}}} as long as the partition table has room for it to grow. The advantage of using an as small as possible size is that the time necessary to flash it onto storage is reduced to a minimum (when flashing you have to write the entire ext4 fs but when formatting or resizing it only has to write periodic markers to FLASH).

For a given size (see SIZEMB variable below) you can create a rootfs with:
{{{#!bash
SIZEMB=1536 # 1.5GB - expandable later with resize2fs
OUT=bionic-newport.ext4
# create a file of specific size
truncate -s ${SIZEMB}M ${OUT}
# format it as an ext4 filesystem
mkfs.ext4 -q -F -L rootfs ${OUT}
# mount it to a temporary mount point
tmp_mnt=$(mktemp -d -p/tmp)
mount ${OUT} ${tmp_mnt}
# copy files to it
cp -rup rootfs/* ${tmp_mnt}
# and/or extract files from a tarball
tar -C ${tmp_mnt} -xf linux-newport.tar.xz
# unmount temporary mount point
umount ${tmp_mnt}
sync
# compress it
gzip -k -f ${OUT}
}}}

For automatically resizing the rootfs on boot you can create a one-shot init script before you unmount the filesystem above:
{{{#!bash
cat << EOF > /etc/init.d/resize2fs_once
#!/bin/sh
### BEGIN INIT INFO
# Provides:          resize2fs_once
# Required-Start:
# Required-Stop:
# Default-Start: 2 3 4 5 S
# Default-Stop:
# Short-Description: Resize the root filesystem to fill partition
# Description:
### END INIT INFO

. /lib/lsb/init-functions

ROOT=\$(cat /proc/cmdline | sed -e 's/^.*root=//' -e 's/ .*\$//')

case "\$1" in
  start)
    log_daemon_msg "Starting resize2fs_once" &&
    resize2fs \$ROOT &&
    update-rc.d resize2fs_once remove &&
    rm /etc/init.d/resize2fs_once &&
    log_end_msg \$?
    ;;
  *)
    echo "Usage: \$0 start" >&2
    exit 3
    ;;
esac

EOF
chmod +x /etc/init.d/resize2fs_once
systemctl enable resize2fs_once
}}}

Note that the pre-built Gateworks images create a minimal root filesystem as well as a partition table that assumes a specific size (matching the smallest eMMC device used on our boards). There is a script similar to the one above that runs on first-boot which expands the last partition to the extents of the device and grows the partition to fill it. See https://github.com/Gateworks/ubuntu-rootfs/blob/master/ubuntu-rootfs.sh and look for 'growpart' for details.

[=#disk-images]
== Building a Bootable Disk Image ==
You will want to build your own Ubuntu disk image if you want control over any of the following:
 * Contents of root filesystem (packages and configuration) (see [#debootstrap debootsrap below)
 * Configuration of the Linux kernel (see [wiki:newport/bsp#kernel newport/bsp/kernel])

See [wiki:newport/boot#disk-images newpowrt/boot/disk-images] for detailed instructions.