wiki:newport/ubuntu

Version 13 (modified by Tim Harvey, 6 years ago) ( diff )

add net-tools and ifupdown and extra env to debootstrap instructions

Ubuntu on Newport

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

Other references:

Gateworks pre-built Ubuntu Disk Image

Gateworks provides a pre-built Ubuntu firmware images for the Newport Family:

Features:

To install the kernel and root filesystem on a removable block storage device see below.

BSP

To build a complete Ubuntu image, including all the boot firmware, start with the Newport BSP page as the easiest option.

Root filesystem

This is to build the rootfs ONLY. To easily build an entire system image, including the boot firmware and Ubuntu, consider the 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.

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.

Steps:

  1. Install pre-requisites:
    sudo apt-get install qemu-user-static debootstrap binfmt-support
    
  1. Perform first stage install of minimal filesystem for arm64 architecture:
    distro=xenial
    arch=arm64
    target=${distro}-${arch}
    qemu_arch=aarch64
    sudo debootstrap --arch=$qemu_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)
  1. we now have a minimal Ubuntu rootfs - chroot to it and perform the 2nd stage install:
    sudo chroot $target
    # now we are in the chroot - setup env matching the distro above
    distro=xenial
    export LANG=C
    # setup second stage
    /debootstrap/debootstrap --second-stage
    
    • this is the most minimal rootfs we would recommend
  1. (optional) add additional apt package repos:
    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 below for more detail on Ubuntu package feeds
  1. (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)
    apt-get update
    apt-get -f install # fixup missing package dependencies
    apt-get install locales dialog
    dpkg-reconfigure locales
    
  1. set hostname:
    echo ${distro}-$(uname -m) > /etc/hostname
    
  1. set a root passwd so you can login
    passwd
    
    • or consider adding a user via adduser:
      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
      
  1. (optional) configure networking:
    • wired ethernet with DHCP on eth0
      apt-get install net-tools ifupdown
      cat <<EOF >> /etc/network/interfaces
      allow-hotplug eth0
      auto eth0
      iface eth0 inet dhcp
      
      EOF
      
    • or static IP:
      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):
      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
      
  1. (optional) install some useful packages
    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 below for info on enabling it
  1. exit the chroot shell and remove files we no longer need
    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:

sudo tar --numeric-owner -cvJf xenial-newport.tar.xz -C rootfs/ .
  • the '--numeric-owner' is required to store user/group as a number instead of a name
  • the '-C rootfs/' is required to eliminate the rootfs directory prefix
  • the sudo is needed to be able to read the root owned files

Compressed Disk Image (for flashing onto a board)

To create a 'Compressed Disk Image' using this tarball see newport/boot#disk-images and to install this onto a board's embedded FLASH see 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:

SIZEMB=1536 # 1.5GB - expandable later with resize2fs
OUT=xenial-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}

Building a Bootable Disk Images

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 newport/bsp/kernel)

See newpowrt/boot/disk-images for detailed instructions.

Note: See TracWiki for help on using the wiki.