Update private VM management scripts

5 files changed, 86 insertions, 13 deletions

diff --git a/etc/private/systemd-networkd/30-br0-dhcp.network b/etc/private/systemd-networkd/30-br0-dhcp.network
index 864fe3d..211d870 100644
--- a/etc/private/systemd-networkd/30-br0-dhcp.network
+++ b/etc/private/systemd-networkd/30-br0-dhcp.network
@@ -10,5 +10,8 @@ IPForward=yes
 [DHCPv4]
 #UseHostname=yes
 
+#SendHostname=yes
+#Hostname=example.lan
+
 [Link]
 RequiredForOnline=yes
diff --git a/etc/private/systemd-networkd/README b/etc/private/systemd-networkd/README
index 2db3904..48bb7cd 100644
--- a/etc/private/systemd-networkd/README
+++ b/etc/private/systemd-networkd/README
@@ -5,12 +5,14 @@ that appears as a real machine on the host's Ethernet network.
 
 Assumptions:
 
- - The host's Ethernet interface is eth0.
+ - The host uses Ethernet for networking.
+
  - The host uses IPv4 DHCP for network configuration.
 
 Note: only perform the following steps over a physical login to the host since
 the configuration involves bringing the host's networking down.
 
+Note: commands that start with the `#` prompt must be executed as root.
 
 1. Switch to systemd-networkd for network configuration.
 
@@ -51,14 +53,18 @@ the comment at the beginning of each file for its purpose):
 
 Note: if you are already using systemd-networkd, then you may already have
 some configuration in /etc/systemd/network/. If the existing configuration
-conflicts with this setup (for example, you already have a configuration
-for eth0), then you will need to remove the relevant files.
+conflicts with this setup (for example, you already have a configuration for
+the Ethernet interface), then you will need to remove the relevant files.
 
 Then adjust the following to match your setup:
 
   - Ethernet interface name if not eth0: 20-br0-eth0.network (both name and
     content)
 
+    Use the following command to list all network interfaces:
+
+    # ip link show
+
   - Bridge MAC address: 10-br0.netdev
 
     Use your Ethernet interface's address as your bridge address, which
diff --git a/etc/private/vm-gen-macaddress b/etc/private/vm-gen-macaddress
new file mode 100755
index 0000000..c13a993
--- /dev/null
+++ b/etc/private/vm-gen-macaddress
@@ -0,0 +1,60 @@
+#! /usr/bin/env bash
+
+# Generate a locally administered MAC address (LAA) number <num> based on the
+# specified universally administered address <mac> (UAA, for example, an
+# address corresponding to the host's physical Ethernet interface).
+#
+# Specifically, the resulting address is formed by combining the
+# LAA-conforming first octet with the subsequent five octets from <mac>:
+#
+# x[26ae]:xx:xx:xx:xx:xx
+#
+# The first octet is derived from <num> as follows:
+#
+#  0-15 : 02-f2
+# 16-31 : 06-f6
+# 32-47 : 0a-fa
+# 48-63 : 0e-fe
+#
+# For example, <num> can correspond to the interface number, such as tap0, for
+# which the resulting MAC address will be used.
+#
+usage="usage: $0 <mac> <num>"
+
+owd="$(pwd)"
+trap "{ cd '$owd'; exit 1; }" ERR
+set -o errtrace # Trap in functions.
+
+function info () { echo "$*" 1>&2; }
+function error () { info "$*"; exit 1; }
+
+if [ -z "$1" ]; then
+  error "$usage"
+fi
+
+o='[0-9a-fA-F]'
+mac="$(sed -nr -e "s/^$o$o:($o$o:$o$o:$o$o:$o$o:$o$o)$/\1/p" <<<"$1")"
+
+if [ -z "$mac" ]; then
+  error "invalid MAC address '$1'"
+fi
+
+if [ -z "$2" ]; then
+  error "$usage"
+fi
+
+num="$2"
+
+if (( num < 0 || num > 63 )); then
+  error "number '$num' is out of 0-63 range"
+fi
+
+if   (( num < 16 )); then
+  printf "%x2:%s\n" $(( num      )) "$mac"
+elif (( num < 32 )); then
+  printf "%x6:%s\n" $(( num - 16 )) "$mac"
+elif (( num < 48 )); then
+  printf "%xa:%s\n" $(( num - 32 )) "$mac"
+else
+  printf "%xe:%s\n" $(( num - 48 )) "$mac"
+fi
diff --git a/etc/private/vm-login b/etc/private/vm-login
index 3b501ca..4573cba 100755
--- a/etc/private/vm-login
+++ b/etc/private/vm-login
@@ -1,6 +1,8 @@
 #! /usr/bin/env bash
 
-# Get virtual machine console.
+# Get virtual machine console (using screen).
+#
+# Note: use Ctrl-a k to exit screen (or Ctrl-a a k if running inside screen).
 #
 usage="usage: $0 <console-socket>"
 
@@ -22,7 +24,9 @@ pty="$(dirname "$con")/$(basename -s .sock "$con").pty"
 socat "UNIX-CONNECT:$con" "PTY,link=$pty" &
 pid="$!"
 
-screen "$pty"
+# Hack around terminal permission issue when running under `su - <user>`.
+#
+script -q -c "screen $pty" /dev/null
 
 # Note: socat may have already terminated (e.g., VM was shut down).
 #
diff --git a/etc/private/vm-start-base b/etc/private/vm-start-base
index df59d6a..a88ea2d 100755
--- a/etc/private/vm-start-base
+++ b/etc/private/vm-start-base
@@ -16,10 +16,10 @@
 #   MAC address to use for the machine.
 #
 # --monitor <path>
-#   Monitor UNIX socket path, /tmp/machine-<tap>-mon.sock if unspecified.
+#   Monitor UNIX socket path, /tmp/vm-<tap>-mon.sock if unspecified.
 #
 # --console <path>
-#   Console UNIX socket path, /tmp/machine-<tap>-con.sock if unspecified.
+#   Console UNIX socket path, /tmp/vm-<tap>-con.sock if unspecified.
 #
 # --stdio
 #   Connect both console and monitor to stdio (multiplexed).
@@ -27,7 +27,7 @@
 # --stdio-monior
 #   Connect only monitor to stdio.
 #
-usage="usage: $0 [<options>] <machine-img> [<extra-qemu-options>]"
+usage="usage: $0 [<options>] <vm-img> [<extra-qemu-options>]"
 
 owd="$(pwd)"
 trap "{ cd '$owd'; exit 1; }" ERR
@@ -103,11 +103,11 @@ img="$1"
 shift
 
 if [ -z "$img" ]; then
-  error "missing machine image"
+  error "missing virtual machine image"
 fi
 
 if [ ! -f "$img" ]; then
-  error "machine image '$img' does not exist"
+  error "virtual machine image '$img' does not exist"
 fi
 
 # Open the reading file descriptor and lock the machine image. Fail if unable
@@ -119,7 +119,7 @@ fi
 exec {lfd}<"$img"
 
 if ! flock -n "$lfd"; then
-  error "machine is already running"
+  error "virtual machine image is already in use"
 fi
 
 del_tap=
@@ -134,11 +134,11 @@ if [ -z "$tap" ]; then
 fi
 
 if [ -z "$mon" ]; then
-  mon="/tmp/machine-$tap-mon.sock"
+  mon="/tmp/vm-$tap-mon.sock"
 fi
 
 if [ -z "$con" ]; then
-  con="/tmp/machine-$tap-con.sock"
+  con="/tmp/vm-$tap-con.sock"
 fi
 
 ops=(\