##########################################
Configuring a BeagleBone Black the ACM Way
##########################################

This is still somewhat beta; these machines have not yet been brought
into production, but better to have notes than nothing at all.

Initial Configuration
#####################

Flashing the latest firmware, the BeagleBone Way
------------------------------------------------

.. warning:: The installer is not to be considered secure.  Do this without
   network access.

.. note:: Apparently the install images are single-use; please re-pave the
   micro-SD card and do not attempt batch installs.

.. note:: The BeagleBone installer images will create USB networking devices
   using the ``192.168.7.0/24`` subnet; installation should not take place on
   a host where that CIDR range is significant.

1. Grab the Debian image from `<http://beagleboard.org/latest-images>`_
2. Uncompress it and toss it on a micro-SD card.
3. Remove all power from the BeagleBone to be flashed.
4. Insert the micro-SD card.
5. Push and hold the ``S2`` button (the one nearest the micro-SD card slot)
   and, while holding, apply power.
6. You may release the button after the four USER LEDs are no longer all
   on solid.

   The device will now boot off of the micro-SD image and pave over its eMMC.
   If you have damaged the bootloader, more invasive fixes may be necessary.

7. Watch the installation carefully.  Some installer images apparently do
   not stop installing after the first time, causing them to be booted again,
   which causes them to pave over the install, again.  Blech.  Thankfully,
   it doesn't take *too* long.

Common
------

Early Configuration
```````````````````

Authentication
^^^^^^^^^^^^^^

.. warning:: **DO THIS BEFORE CONNECTING TO THE NETWORK**!

The default image is woefully insecure, by design, we assume.  There is a
trivial password for the ``debian`` user and ``root`` can log in via SSH
without a password at all.

At a minimum: land your SSH key (or the entire bundle of ACM admin keys from
``/afs/acm.jhu.edu/group/admins.pub/authorized_keys``), run ``passwd debian``,
adjust ``/etc/ssh/sshd_config`` to set ``PermitRootLogin without-password``,
run ``/etc/init.d/ssh restart`` now.

Better would be to follow the steps in :ref:`install-common_config_ssh` and
prohibit password-based login entirely.

SSH keys
^^^^^^^^

.. warning:: YOU **MUST** GENERATE NEW SSH KEYS!

The firmware flasher apparently creates a set of SSH keys for itself and copies
them over.  This means that if you use the same installer image more than once,
you'll get the same host keys on multiple machines, and that's bad.
Thankfully, it's easy to cause them to be recreated.  We ignore the
``/etc/ssh/ssh.regenerate`` mechanism provided by boot scripts (because that's
entirely not standard) and do it ourselves::

  rm -rf /etc/ssh/ssh_host_*
  dpkg-reconfigure openssh-server

Date
^^^^

.. note:: At this point, we are going to connect to the network.  If you are
   paranoid, now would be an excellent time to skip ahead to pruning packages
   and come back here after you're sure that nothing unintended is listening
   on the network.  (Use ``netstat -lnp`` to check, for example.)

The BeagleBone has no RTC.  Once you're connected to the network, run
``ntpdate pool.ntp.org`` to get the right time.

Repository Setup
----------------

We're going to point at the rcn-ee.net repos::

    wget http://repos.rcn-ee.net/debian/conf/repos.rcn-ee.net.gpg.key
    gpg --with-fingerprint ./repos.rcn-ee.net.gpg.key

Check that that matches the expected fingerprint of
``A72A B0B9 0B86 85C9 1777  A377 D284 E608 A4C4 6402``.  If so, proceed::

    apt-key add repos.rcn-ee.net.gpg.key
    echo 'deb [arch=armhf] http://repos.rcn-ee.net/debian wheezy main' \
      >> /etc/apt/sources.list
    apt-get update
    apt-get dist-upgrade
    apt-get install rcn-ee-archive-keyring

.. note ::
   The key used to have fingerprint ``2F36 8DF5 F926 A8AF 538D  CFC1 4D60 3614 FADF B657``;
   this is a stale key, apparently.  Installing the ``rcn-ee-archive-keyring`` package will
   allow them to roll it forward as needed.

We're short on space and really want very few things running on our behalf,
so go ahead and eliminate recommended packages.  This is taken from
`<http://askubuntu.com/questions/351085/how-to-remove-recommended-and-suggested-dependencies-of-uninstalled-packages>`_. ::

    cat >>/etc/apt/apt.conf.d/99_norecommends <<HERE
    APT::Install-Recommends "false";
    APT::AutoRemove::RecommendsImportant "false";
    APT::AutoRemove::SuggestsImportant "false";
    HERE

Packages
````````

First, go follow the procedure below to update the kernel, since we're about
to build a kernel module.

Pretty much everything we would ever use these for should go ahead and grab
some common packages.  For these, be sure to set our realm (ACM.JHU.EDU) and
cell (acm.jhu.edu).  Set the AFS cache size to 5M or so; we're going to make it
a memcache later. ::

  apt-get install krb5-user krb5-config kstart \
    openafs-client openafs-modules-dkms openafs-krb5 haveged

Installing ``haveged`` will allow us to more reliably obtain entropy on these
distressingly deterministic devices.

Go ahead and tweak ``/etc/openafs/afs.conf`` to set ``OPTIONS=-memcache``
even though we haven't built the kernel module yet.  You might also want
to go look at the desktop configuration for additional AFS tweaks.

You probably want to set up ``unattended-upgrades`` too; see
:ref:`install-common_unattended`.

Additional Configuration
````````````````````````

Adjust ``/etc/default/tmpfs`` to set ``RAMTMP=yes`` and ``TMP_SIZE=10%``.

Apparently, there is some small glitch in USB client support which will
cause the machine to reboot randomly roughly every 12-24 hours.  The thread
at
https://groups.google.com/forum/#!searchin/beagleboard/reset/beagleboard/5qSJ4dQdar4/rBKaUMOQDhsJ
has more details, but the short form as far as we can make out is: keep the
machines connected via USB, or manually remove the ``g_multi`` module after
boot (blacklisting seems not to work?).

Client Configurations
---------------------

One answer is to follow the desktop howto.  Another would be to go it alone
without things like LDAP UIDs.

Server Configurations
---------------------

Installing Packages
```````````````````

Server-ish packages you may wish to install include ::

  apt-get install deborphan keyutils lsof lxc strace

For the servers in particular that you want to run, we refer you to
other sections.

Pruning Packages
````````````````

To minimize the amount of software running on these when they're used as
servers, consider following the instructions here or some closely-related
variant.  This section is almost surely stale, but hopefully provides a
good start.

Remove cloud9 ::

  systemctl disable cloud9.socket
  systemctl stop cloud9.socket
  rm /lib/systemd/system/cloud9.{socket,service}
  rm /etc/default/cloud9
  rm -rf /var/lib/cloud9
  systemctl daemon-reload

Remove bonescript ::

  systemctl disable bonescript.socket
  systemctl stop bonescript.socket
  systemctl disable bonescript-autorun.service
  systemctl stop bonescript-autorun.service
  rm -rf /lib/systemd/system/bonescript*
  rm -rf /usr/local/lib/node_modules/bonescript

Remove winston node module ::

  rm -rf /usr/local/lib/node_modules/winston

Remove beaglebone ruby gem ::

  gem uninstall beaglebone 

Remove python-pip packages ::

  pip uninstall distribute setuptools
  rm -rf /usr/local/lib/python*

Mark some packages as manually installed::

  apt-mark manual am335x-pru-package psmisc

And now, start pruning things::

  dpkg --purge beaglebone
  apt-mark auto \
    apache2 apache2-utils avahi-daemon desktop-file-utils evtest \
    fbset gksu hexedit hostapd leafpad \
    libnewt0.52 libopencv-core-dev libopencv-dev libsdl1.2-dev libxss1 \
    lightdm lowpan-tools lxde-common lxde-core lxpanel lxterminal \
    pastebinit pcmanfm python-opencv read-edid \
    wicd-cli wicd-curses wicd-gtk wireless-tools wpasupplicant wvdial \
    x11-xserver-utils xchat xinput xrdp xscreensaver xserver-xorg \
    xserver-xorg-video-fbdev xserver-xorg-video-modesetting \
    atmel-firmware firmware-ralink libertas-firmware zd1211-firmware \
    tasksel tasksel-data 
  apt-get autoremove
  dpkg -l | awk '/^rc/{print $2}' | xargs dpkg --purge
  deborphan --guess-all | xargs dpkg --purge

Though note that `deborphan` is not available by default and so will have to
wait.

Recurring Tasks
###############

Upgrading the Kernel
--------------------

Sadly, landing the kernel on this thing is a real pain in the ass.  We inline
the procedure here rather than invoking shell-scripts obtained by wget.  For
details, look at the script at, for example,
`<http://rcn-ee.net/deb/wheezy-armhf/v3.8.13-bone63/install-me.sh>`_ and the
``thirdparty`` file that sits next to it.  What a mess.  We ignore thirdparty
modules since we don't actually care for the RT2870 driver they provide.

In practice, you want to replace the value of ``kv`` below with the newest
available kernel; use ``apt-cache search linux-image`` to see what's around,
perhaps.  There doesn't seem to be a meta-package.  ::

  kv=3.8.13-bone63
  
  apt-get install \
    linux-firmware-image-${kv} \
    linux-image-${kv} \
    linux-headers-${kv}
  
  BOOTDIR=/boot/uboot
  mv ${BOOTDIR}/uImage{,.old}     || true
  mv ${BOOTDIR}/zImage{,.old}     || true
  mv ${BOOTDIR}/uInitrd{,.old}    || true
  mv ${BOOTDIR}/initrd.img{,.old} || true
  ( . ${BOOTDIR}/SOC.sh
  mkimage -A arm -O linux -T kernel -C none -a ${zreladdr} -e ${zreladdr} \
    -n ${kv} -d /boot/vmlinuz-${kv} ${BOOTDIR}/uImage
  mkimage -A arm -O linux -T ramdisk -C none -a 0 -e 0 \
    -n initramfs -d /boot/initrd.img-${kv} ${BOOTDIR}/uInitrd
  )
  cp /boot/vmlinuz-${kv} ${BOOTDIR}/zImage
  cp /boot/initrd.img-${kv} ${BOOTDIR}/initrd.img
  
  rm -rf ${BOOTDIR}/dtbs
  mkdir -p ${BOOTDIR}/dtbs
  cp -r /boot/dtbs/${kv}/* ${BOOTDIR}/dtbs
  
  sync
  reboot