Virtual Plan 9 Cookbook — Section 2: Preparation

This recipe installs an up-to-date Debian Unstable (codename Sid—the breaker of toys in Toy Story) on the project computer to serve as the virtualization host operating system for the guest virtual machine to be installed in the next section. Sid has some attributes that make it more attractive for this situation than either Debian Stable (currently codename Wheezy) or Debian Testing (currently codename Jessie):

Sid is nowhere as buggy as its Unstable title suggests. Although it can break without warning, it seldom has, which bespeaks the consistent quality of the work performed by the Debian package maintainers. As this project is primarily educational and not production, stability is not the most important consideration. You do, however, have to be prepared for more package troubleshooting than when running Testing or Stable.

Sid has the most current software of the three distributions mentioned. This means it will support hardware the others cannot, and offers software enhancements the others do not.

Unstable is a rolling distribution—it never gets promoted to Testing or Stable or Unsupported (well, that last is not really a promotion). It merely gets updated (you should probably do that every 24 hours unless you aren't actually running it, but then updating it is the first thing you do when you bring it up again). An R&D project free from the distraction of non-trivial infrastructural migrations promotes the educational experience. A rolling release replaces scheduled major migrations once a year or so plus security patching with a little of all that every day (normally).

You may have requirements that make Sid unsuitable for your project and choose to use the Stable system installed from the Debian Live USB-stick without upgrading that to Unstable. If so, follow the 2014-07-31 GNU/Linux Host Preparation section to download a suitable Debian Live USB-stick, boot that, and install Debian Stable (Wheezy) into your project platform. However, you will have to configure its virtual networking on your own, as the recipe's incantations do not achieve the desired results. If you succeed, share what worked with me to add to this cookbook so others will not need to reinvent your wheel.

If any hardware in your project computer is less than two years old, it may not be able to use the latest Debian Installer, let alone the Debian Live system, to install the host system. For further details, refer to Jessie Beta 1 release of the Debian Installer and Supported Hardware in the x86_64 Debian GNU/Linux Installation Guide for Testing or whatever version is appropriate for your project computer).

Subsection 2-1: Build Debian Installer Jessie Beta 1 Media

Step 2-1-1: Download the ISO image

Point your browser at https://www.debian.org/devel/debian-installer/ using an appropriate computer (in my case, an earlier test of this project's Debian Sid p9host system on my project demo system, a four-core Gigabyte tower. The top of the page should look something like this (800x600):

Scroll to the precise ISO file (for me, amd64) under major heading Installing with the Debian-Installer, minor heading Official release, and media heading netinst (generally 150-280MB) CD images and copy its link to the clipboard. It should look something like the following image before you click to copy (under XFCE, that pop-up menu is produced by a right-click on the link you're interested in).

In a root terminal session, first change the working directory to /tmp using a {cd /tmp} command. Second, type {wget -c '}, paste the clipboard where the cursor is (with XFCE, I right-click on the terminal session and left-click on the Paste item in the pop-up menu):

and type the closing apostrophe {'}—it should look something like this:

Press the Enter key (henceforth referred to as Enter—all such keyboard keynames should be understood as a noun or a verb depending upon the context) to start the download of about 220 MB. When that completes, launch a {ls -lh debian-jessie*} command to verify the downloaded file. At the end the screen should look something like this (your bandwidth is probably different and you should adjust the expected elapsed time accordingly):

Step 2-1-2: Copy the ISO image to a USB-stick

Insert a big enough USB-stick (aka pen-drive, thumb-drive) into a USB port of the correct speed for the media, and, if necessary, determine the block device assigned to it (in my case, /dev/sdh). Copy the ISO image byte-for-byte to it (I used the command {dd if=/tmp/debian-jessie-DI-b1-amd64-netinst.iso of=/dev/sdh bs=8192}). This will require a number of minutes—USB-1 is not recommended. When it ends it should not have displayed any error messages and indictate no short blocks were processed; e.g.,

Run the approrpiate cfdisk command to verify the USB-stick looks bootable (in my case, {cfdisk /dev/sdh}). If a screen appears that mentions GPT, just ignore it and Enter). The output should look pretty much like this (this screen has been edited to reverse the video):

This is what it looks like when the media is ready. Tab twice and Enter to exit cfdisk. Then run the appropriate command to prepare the system for removal of the stick from the USB port; e.g., {eject /dev/sdh}. Now the USB-stick can be removed. I affixed an external label to mine that says, "Debian Installer Jessie Beta 1 X86_64 Netinst Aug 2014". Last of all, delete the ISO file from /tmp unless you want to keep it around for some reason.

You now have a portable Debian Installer system you can boot from any computer compatible with the flavor you selected and that supports booting from a USB-stick (some BIOS and/or boot loader reconfiguration might be necessary for that to function).

Subsection 2-2: Install Jessie Using Debian Installer

With your bootable USB-stick in hand, we move to the keyboard of the X86 platform you have made available to install the host and guest operating systems of this project. This move may be merely a figure of speech if the same physical system that was used to build the Debian install media in the previous subsection is also the computer into which you intend to install the Debian and Plan 9 systems of this project. Either way, it may have no software already installed that that you intend to retain (that is, already or soon-to-be empty non-volatile storage) or there may be storage areas and/or one or more bootable operating systems that you want to co-exist with the new Debian host and its Plan 9 guest(s).

If, when you're done, only the new systems will be resident, you have a relatively simple installation ahead and can probably get away with just following this cookbook's recipes relatively blindly (although you are strongly urged to read and understand everything to come before you continue actually cooking your project—it's a great way to avoid starting over again). If, however, this project will not be taking over the computer completely, you have the responsibility to effectively utilize your system administration skills to tailor the steps in the rest of this section to produce the needed host environment to install the Plan 9 guest systems starting in the next section.

Step 2-2-1: Backup the Project Platform As Needed

If there is nothing already resident on the project computer that will ever be missed by anyone for the rest of time, you are being reasonable if you skip this step. Otherwise, back up everything not already backed up somewhere that would induce some degree of despair if it disappeared, even if there's no way it could disappear. If you do not know how to back up such data and are uninterested in learning how to do that, you are strongly urged to drop this project—even more so if it never occurred to you that you ought to back up such data (whether or not you proceed, you should study BOFH: The Great Backup BACKDOWN and the comments it spawned to get some really useful enlightenment).

Step 2-2-2: Boot From the Debian Live USB-Stick

If an operating system is currently running on the project platform, shut it down now. If the BIOS and/or boot loader of the project computer's firmware need to be reconfigured to permit booting from a USB-stick, do that now. Insert the Debian Installer USB-stick in a suitable USB port, then start a reboot. In response to the Debian GNU/Linux installer boot menu, press the ArrowDown key twice so Advanced options is highlighted:

and Enter. Now ArrowDown once so Expert install is highlighted:

and Enter. If anything prevents something very much like the following image from manifesting on the computer's screen, use your system administration skills to resolve the issue(s) (the Debian Support portal is an excellent place to begin seeking help).

Did you ask, "What happened to the GUI?"

But you asked for the expert install. </joke>

If you want pretty but noticably slower, opt for the Graphical expert install (but don't expect this cookbook to cater to your aesthetic tastes with graphical screenshots for this phase). But before you reboot the installer to choose the GUI, finish reading up to the next step—you might reconsider and save save yourself a minute or two.

What you see is the initial high level menu of the Debian Installer. As you progress through the installation steps, the options in this menu will change, but the concept remains the same: work your way down to some conclusion. The current line will be what the installer thinks you should do next, but you can navigate with ArrowUp and ArrowDown before you make the selection via Enter (but some steps you will not be allowed to re-do—those will be pointed out along the way). Tab will cycle through the buttons at the bottom and the main data entry area.

Does this non-GUI appearance and keyboard-centric interface strike you as deplorably unsexy?

As the saying goes, "You ain't seen nothin' yet."

You are proceding toward interacting with Plan 9. It does not support Chrome or even FireFox. There are in fact one or two good reasons for that condition. Plan 9 is unashamably not UNIX and certainly not GNU; similar in many ways, but significantly different. Never forget Plan 9 exists primarily for researching operating system design. While it is highly usable in its way as well as stable, and learning how it is different and why are worthy goals, do not get it into your head that it needs to be "improved" to be more like modern day UNIX. Rather, it would be you that needs to be improved to be able to appreciate the positive qualities of the design and paradigms Plan 9 offers. Then you would be able to show proper respect to the guys who created, fix, and extend it (many of whom also created UNIX before they created Plan 9—I daresay they know more than you do). They do tend to be more inclined to help newbies who are respectful, probably just like you are.

Step 2-2-3: Choose Language, Location, and Locales

Now Enter to proceed to, like it says, choose the language (please be aware that to date I have not worked through these recipes using a non-default locale—if you do that, I can't guarantee you will encounter no surprises, but if you try it, please let me know how that goes). That should present the following:

The note here regards the C locale at the top that you might be inclined to use. Plan 9 is a UTF-8 environment, not C (those guys invented UTF-8 for Plan 9), so you may find the host in C responsible for subtle problems when communicating with Plan 9 guest consoles and terminals. If you normally want to be in C, remember to change to a UTF-8 locale before connecting to a Plan 9 service. If you want C at all, you must choose it here—it is not available when choosing additional locales later.

Choose your language and Enter to proceed to:

Choose your location and Enter to proceed to:

Choose your default locale and Enter to proceed to:

Choose your additional locales, if any, then Tab to the <Continue> button and Enter to return to the main menu:

Step 2-2-4: Configure the Keyboard

Next Enter to configure the keyboard:

Configure your keyboard, and Enter to return to the main menu:

Step 2-2-5: Detect and Mount CD-ROM

Get this right the first time; otherwise, you will need to reboot the installer.

Enter to let the installer find the USB-stick:

Once the installer has the correct media identified and selected (the asterisk within the brackets), Tab to the <Continue> button and Enter:

Verify this is the correct CD-ROM image (if not, you will need to reboot the installer to try again), and Enter to return to the main menu:

Step 2-2-6: Load Installer Components From CD

Enter to begin defining what the installer will load to analyze your platform's storage areas and allocate space for host system. The installer will display the options for you to select. ArrowDown, pressing the space bar (hereafter referred to as Space) to mark each component that needs to be loaded for your install. I selected choose-mirror, mbr-udev, and parted-udev.

After you have looked at all the options and selected what you need, Tab to the <Continue> button and Enter to let the installer load the modules and return to the main menu.

Step 2-2-7: Detect Network Hardware

Enter to allow the installer to probe the platform's network hardware and return to the main menu.

Step 2-2-8: Configure the Network

Enter to begin configuring the network interface for the installation and installed host machine:

My project computer will use its only wired Ethernet port for network access by the host system as well as all guest virtual machines of that host system. All these systems will be visible to the LAN inside my home catenet by the magic of virtual bridging; however, that cannot be configured at this time—prerequisite software will be installed later in this subsection. For now the NIC will be configured to use static IPv4 (the external DNS server already knows about these new host systems).

Thus, I Tab to the <No> button and Enter, key in my IP address/CIDR netmask, Tab to the <Continue> button:

and Enter. Since the installer correctly calculated my gateway address, I simply Tab to the <Continue> button:

and Enter. I replace the installer's bad guess with my network's DNS server address, Tab to the <Continue> button:

and Enter. My review of the configuration finds nothing to go back and change, so I ensure the <Yes> button is highlighted:

I'm happy with the default here, so there's nothing more to do than Tab to the <Continue> button and Enter. I see the installer correctly surmised the host name for this IP address from the DNS server, and hopefully you had the same experience. If not, replace the suggestion with the host name that your host system will go by. In either case, Tab to the <Continue> button:

and Enter. I key in the domain name that my host system will found by in my catenet (no trailing period), Tab to the <Continue> button:

and Enter, returning to the main menu:

Step 2-2-9: Choose a Mirror of the Debian Archive

The reason to use a mirror is to reduce the load on the Debian repository servers and hopefully increase the download speed you are afforded. This option requires you already know which mirror you want to use (in my case, debian.csail.mit.edu). Find yours at the Debian mirror list web page.

Now I Enter to begin the selection, then ArrowDown once to select FTP:

and Enter. We replace the suggested name with the name of the chosen mirror, Tab to the <Continue> button:

and Enter. The default directory is correct for me, but if it is not for you, replace it with what it should be, making sure the trailing slash is present. Then we ensure the <Continue> button is highlighted and Enter:

My project environment does not require proxy specifications, but if you do, fill in the information required by your environment. Then we Tab to the <Continue> button:

and Enter, returning to the main menu.

Step 2-2-10: Set Up Users and Passwords

Enter to start defining the root and vmadm users for the host system.

Enter to simply accept the default to enable shadow passwords and proceed to:

Enter to simply accept the default to enable root to logon and not force the non-root user to have sudo powers. Now key in the root password for the host system, Tab to the <Continue> button:

and Enter. Key in the root password again, Tab to the <Continue> button:

and Enter. Since we want to create the vmadm user, for this screen:

we simply Enter. I key in {VM Administrator} for my user's full name (you can use whatever you wish) and Tab to the <Continue> button:

and Enter. I use vmadm for my user's name, but you can use whatever you wish (I suspect maint could be a popular choice in some circles even though it would be the name of a Linux account, not a VM/370 or z/VM virtual machine) but remember to change occurances of vmadm in this cookbook to that name. Since the installer guessed I would call the account vm, all I need to type in is {adm}, then Tab to the <Continue> button:

and Enter. Key in the password you will use for this account, Tab to the <Continue> button:

and Enter. Key in the password again, Tab to the <Continue> button:

and Enter, which returns us to the main menu again.

Step 2-2-11: Configure the Clock

Enter to start configuring the hardware clock:

The only reasons I can think of to not use NTP (or something better) to maintain the hardware and system clocks is the host (1) cannot network to any NTP servers or (2) will be running in a virtual machine that will be hosted by an OS that is using NTP (or something better) to manage the clocks. So we simply Enter and are presented with the opportunity to change the default NTP server:

Having no need to do so, we merely Tab to the <Continue> button and Enter, bringing up:

Once you have the default system time zone you want highlighted, Enter to return to the main menu.

Step 2-2-12: Detect Disks

This step involves no iteraction with you and should take a very short time to return after you Enter, returning you to the main menu again.

Step 2-2-13: Partition Disks

Enter to begin the process of defining the filesystems this Sid system will use.

After the installer loads some modules and attends to other house-keeping for a little while, you are presented with the choice of just how automagically you wish to mess with the project platform's non-volatile storage. This recipe takes the hands-on approach, so we ArrowDown to the Manual option:

and here my deception is revealed: I am actually running this install in a virtual machine, not on the bare project hardware! This is how I am able to capture these screenshots. This virtual disk is actually a partition on a real hard drive, but it could be a mounted filesystem or even a file in a filesystem. It exists only to capture the partitioning screenshots so you can know what to expect when you carve up your project's real disks—it will not be used in the actual project.

The space to be allocated will be a very small Linux swap partition, a Linux root partition (which will include everything but swap), and the MBR to receive the GRUB boot loader. You would leave at least 20 GB free for Plan 9 but this demonstration ignores that requirement.

We ArrowDown three times to highlight the virtual disk and Enter, taking us to:

The installer sees a hard drive that doesn't even have a partition table. It is unaware how that drive is really provisioned—it (and the system to be installed on it) will interact with it no differently than with a real physical hard drive. This status is according to expectation, so we Tab to the <Yes> button and Enter, bringing up:

No Redmond OS has been invited to this party, so we ArrowUp twice to specify we want GPT organization and Enter, leading to the partition management screen. We ArrowDown to highlight the FREE SPACE line:

and Enter which brings forth:

We want to carve it up ourselves so we simply Enter, getting:

The default is everything, but we want a small swap partition, so we ArrowLeft three times, Backspace three times, Tab to the <Continue> button:

and Enter, producing:

We accept the default location at the beginning of the drive via Enter, provoking a brief flurry of activity ending with:

Since Name is already highlighted and showing blank, we Enter to supply a name. I type {VS} (for virtual swap—call yours what you like), Tab to the <Continue> button:

and Enter, producing:

Now we ArrowDown once and then Enter to change the default Use as parameter, bringing up:

We ArrowDown eight times to highlight swap area and Enter, which returns us the the partition definition screen. It has changed as a result of the updated usage, leaving us nothing more to do with the definition. So we use ArrowDown to get to the bottom:

and Enter, which returns us to the disks definition screen, wherein we press ArrowDown once to start carving up the remaining free space:

Again we want to define it ourselves so we simply Enter, leading to another partition size definition screen, which this time we want to default to taking all the available space, so we Tab to the <Continue> button:

and Enter. As there is no need for location information this time, we are not asked, the installer goes straight into the short flurry of activity prior to starting another partition definition dialog. This time (not shown—you can do it without help) we define the Name and Label both as {VV} and let the other options default, so that when we're ready to return to the disks definition menu, it looks like this:

and we Enter, which shows our handiwork. Since it appears as it ought to (those two f characters indicate the partitions will be formated), we ArrowDown to the bottom:

Here is our final chance to change the plan. If what you see it is what you want, Tab to the <Yes> button and Enter to change the disk. When the installer stops showing you stuff like this:

we are finally returned to the main menu:

Step 2-2-14: Install the Base System

Enter to allow the installer to begin installing the base system.

This will take some time, but you don't need to watch it like a hawk.

Eventually it will bring you here:

Unless you have a good reason not to, use Enter to take the default:

After a little of that, you will get to the next question, and, again, unless you have a good reason not to, take the default:

This, too, will take some unattended time, but when it's done, you will be back at the main menu:

Step 2-2-15: Configure the Package Manager

Enter to allow the installer to begin configuring the package manager (dpkg and apt). After a little activity, it will pop-up this question:

In this case, we are only using the Jessie installer to enable us to get enough on the hard drive to be able to upgrade to Sid, thus we would like to avoid double-installations of packages. So we Tab to the <No> button and Enter, leading to the next question:

Again, as we are only using the Jessie installer to enable us to upgrade to Sid that does not use either of the repositories selected by default, we Space, then ArrowDown, then Space again, and Tab to the <Continue> button:

and Enter to finish configuring the package manager and return to the main menu:

Step 2-2-16: Select and Install Software

Enter to allow the installer to begin selecting and installing additional software. After some activity, it will pop-up this question:

This can be done, if you wish, after Sid is installed, so take the default via Enter, which continues (after a little activity) to this question:

Enter to accept this default, which will bring up:

This group of packages is not necessary to upgrade to Sid, so Space to unselect it, Tab to the <Continue> button, and Enter, causing return to the main menu after a slight delay:

Step 2-2-17: Install the GRUB Boot Loader on the Hard Disk

If Install the LILO boot loader on the hard drive is highlighted instead of Install the GRUB boot loader on the hard drive, you're on your own for this task. Enter to begin installing GRUB, which will cause some processing, sometimes without visual feedback, including at the end searching all disk areas for bootable systems, before it finally asks a question:

Your text may vary from this, especially if you have other bootable systems on your project computer. This dialog needs to determine where to install the bootstrap for GRUB and it does its level best to figure out the most useful and least disruptive place. It's up to you, however, to know where it needs to be installed. Tab to the <No> button if the MBR of what GRUB believes to be the "first" hard drive is wrong before Enter, thus indicating the installer needs to ask you where to park it. Since the installer's guess is correct for both my true project computer and this virtual demonstrator, I simply ensure <Yes> is highlighted before Enter.

If you select <No> or the installer wants to have you decide where to install the bootstrap, this screen will be displayed:

If you select Enter device manually, you will be shown:

Regardless how the question is answered, once it has been answered, the installer will finish installing GRUB in short order and return to the main menu:

Step 2-2-18: Finish the Installation

Enter to allow the installer to begin preparing to reboot the system using the newly installed system. After a short amount of processing, the installer will inquire about:

Again, there being nothing from Redmond in the vicinity, we take the sensible approach of keeping the hardware and system clocks at legislation-immune UTC by using Enter to default to <Yes>. A little more processing and it is complete:

Enter, remove the USB-stick, and cross your fingers.

Subsection 2-3: Upgrade the New Host System to Sid

[Note some of these screenshots were taken from the reboot of the same virtual system used in the previous subsection, not the bare project computer, again, to enable capturing screenshots until the XFCE environment of the project system is available. So if you see a host named vp9cb associated with IP 10.220.186.205, just imagine it's really p9host at 10.220.186.202, please, and also ignore any time and date information.]

After getting your project computer to begin booting up, interact with your BIOS/boot loader as needed to get your system to use the correct boot device for your project. When the GRUB menu appears, make sure it advertises the system you installed in the previous subsection:

If it does, you can let it default to a normal boot, or you can ArrowDown and ArrowUp to explore and test the other boot options. To demonstrate, I press ArrowDown once and Enter to examine the advertised Advanced options for Debian GNU/Linux:

After you get it doing a normal boot (in this case by just Enter), it should display a bit of activity. Note that you may see a kernel error message regarding module vmwgfx that complains about hardware not having a pitchlock. This can be ignored (see kernel bug 46711 for the details). Before too long a non-GUI logon identifying the hostname you installed should manifest:

That being so, login to the vmadm account specifying the password your defined during the installation dialogs. If that goes according to plan, you should shortly see a non-root user command prompt:

Now enter an {su -l} command and offer the root password you defined during the installation. You should be rewarded with a root user command prompt. If so, we are ready to tell the package manager to stop using the Jessie package repositories and start using Sid's. Enter the following commands:

cd /etc/apt
cp -p sources.list sources.original
echo 'deb ftp://debian.csail.mit.edu/debian/ sid main' >sources.list
cat sources.list

Now verify the cat command output matches what is in this display:

The next step is to update what the package manager knows about the state of the repositories it is using. This can be accomplished using the {aptitude update} command, which should produce error-free results like this:

The next step is huge: upgrade the system to the Sid level. This can be accomplished using the {aptitude dist-upgrade} command, which should produce lots of messages after a little dialog with you, starting with:

You can scroll back and forth through the session log using the Shift-PageUp, Shift-PageDown, Shift-ArrowUp, and Shift-ArrowDown key combos.

First note your display will invariably differ from this because Sid is always changing, so what needs to be upgraded is not the same as any other upgrade. Next notice that because we skipped additional package installations before, not that many packages need to be modified in some way.

If your question is not the one displayed here in the cookbook, you have encountered a conflict that needs to be resolved before aptitude will ask you the question shown in the cookbook. Now the suggested conflict resolution is almost always the way to go, because you're not really running this system yet, so if it does break something, it won't be a major problem. So Enter to accept the Y default answer, and keep resolving anything that comes up until you get to the question shown.

Less that 100 MB download to upgrade a whole distribution? Such a deal!

Again, Enter to accept the Y default answer. This leads to downloading those packages. If any downloads fail, aptitude will press on. Shortly you'll be shown how to deal with that. After the downloads are over, we may get some action requests again, such as notifications of changes or configuration dialogs. If so, note what needs to be noted and choose what needs to be chosen for your project environment.

Once aptitude starts doing lots of unpacking and setting up, you can usually just sit back and wait to finally get a command prompt:

"Houston, we've had a problem." —Apollo 13

And to think I experienced a textbook, flawless upgrade doing this very process on this very platform just a few days ago (that, too, is unusual). Well, something has changed for the worse. It is unlikely you will experience any issues of this magnitude, so just enjoy the show and glean what you can from this problem resolution process.

Scrolling back finds reports of configuration failures, the first for udev shortly after systemd reported a journald.service watchdog timeout (with an exclamation point). Then we see kernel messages informing us that systemd is experiencing some difficulties:

[I hope you forgive the sudden lapse of screenshots starting about now.] I tried to use {telinit s} to drop down into single user mode but that didn't work.

Sid has seriously broken our toy.

I was able to get the magic SysRq key feature recognized by systemd using the standard Reboot Even If System Utterly Broken sequence to reboot without needing to manually force power-off by keeping the physical Power push-button depressed for four seconds. When I got the initial GRUB screen I used {e} to start editing the configuration for a normal boot:

I scrolled to the bottom with ArrowDown:

then ArrowUp twice, ArrowLeft once, Backspace six times over ( quiet), and typed {single init=/sbin/init}:

and used Ctrl-X to load the kernel into single user maintenance mode hopefully using the faithful UNIX System V init module, not the default and now problematic systemd module. Rewarded with the opportunity desired, I entered the root user password in response, then started aptitude to attempt to permenently replace systemd with sysvinit:

Since this is not the place for the aptitude tutorial in the flow of this cookbook, I will only describe what I did supported with minimal screenshots which you may not understand—that's okay, study those details after you have been through the tutorial and for now just consider this magic.

I quickly reconfigured the Preferences, then marked systemd-sysv to be purged and systemd-shim and sysvinit-core to be installed:

then requested the changes be performed, which, thankfully, caused everything to be installed as we had originally expected:

After Enter to return to aptitude and then exiting aptitude, we're where we should have been when we realized we had a problem.

I type these words a day later after having opened bug report 762146 in which I reported my findings based upon a reproducible scenario that I executed in a virtual machine, and even though I marked the severity grave, there has been nothing added by the developer thus far. That means there's a chance it will not have been fixed when you try this yourself.

We now return you to your regularly scheduled recipe…

If a new kernel has been installed (linux-image-*), as it was in this case, you need to reboot to load it, so issue the {telinit 6} command to shutdown and reboot.

When the GRUB menu is displayed during the boot up, chose the Advanced options and ensure the new kernel is now the default (if it's not, {update-grub} will need to be run after the boot up, but not before you determine why the new default was not established and resolve that issue). Whether or not it is the default, ensure you boot up with it.

We get a normal logon prompt, so we login as root. A few commands indicate it's official—we're running Debian Unstable now:

Subsection 2-4: Install Needed Packages

It's time to get interactive with package selection again, but this time we will do it using aptitude instead of the Debian Installer.

We launch it so with a plain {aptitude} command, producing:

The first thing to do with aptitude is adjust its settings. Go to the menu bar via Ctrl-T, which causes the menu bar on the first line to activate, dropping down the submenu for the left-most item, Actions:

Next, move left or right through the menu bar using ArrowLeft or ArrowRight (they wrap) to the Options item, which will drop down the Preferences item, already highlighted:

Enter the Preferences subpanel in a new tab:

The display will change as we modify many of these options. You may tailor them as you like but what you see may start varying with what will be depicted in this cookbook. My choices eliminate unnecessary characters in the interest of putting more useful data on a screen and help the work flow. Some will be toggled as we go when that is helpful.

This is what I change at this time:

Next, we exit the Preferences list by typing one {q}, then another to exit this invocation of aptitude.

Now run the {aptitude} command again and the screen should look pretty close to this:

After a distribution upgrade, just about every package is new to the package manager, an unhelpful state, but typing an {f} tells aptitude to forget the newness of all packages so marked.

If you are already comfortable using aptitude, you can skip down to Step 2-4-3: Mark Needed Packages For Installation now to start selecting needed packages.

Step 2-4-1: Introduction to Aptitude and Packages

Let's show you how to navigate the Packages tab. All the lines currently showing are collapsed group markers with numbers in parentheses to indicate the number of packages in the group. The reversed video line is the current line which can be changed via ArrowDown (also {j}), ArrowUp (also {k}), PageDown (also Ctrl-F), PageUp (also Ctrl-B), Home (also Ctrl-A), and End (also Ctrl-E). Go ahead and try these out now.

To expand a group, make it the highlighted line then either Enter to expand just the next lower layer in the group or {[} to expand all the lower layers. To collapse a group, highlight the group line and either Enter or {]}. {^} will make the group line of the next higher group current, helpful for setting up collapses.

So, to see all layers of the Installed Packages top-level group, invoke Home (if necessary) and {[}, producing:

Three layers are revealed now. The next lower level groups packages by similar function; e.g., admin, doc, editors (these are specified in all packages' Section definitions—each package has only one). Below that, packages are grouped by license types, which are main, contrib, and non-free, in decreasing quality of libre-ness (these are selected in /etc/apt/sources.list—note we have only included main, so we don't see anything about the contrib and non-free repositories). At the bottom are the actual packages—each package summary line represents one or perhaps more .deb files that share the package's name (a .deb filename also includes the specific platform and package release the file applies to). Some packages are meta-packages that simplify selection of groups of related packages.

Notice the Installed Packages top-level line is still highlighted. Now use {]} or Enter to collapse its entire hierarchy again, then Enter to expand just the next lower layer:

So you see all the functional groups and associated number of installed packages for which at least one package is currently (in this top-level group) installed. Now collapse the tree again via {]} or Enter.

Let's look at an uninstalled package to orient you to how Debian organizes these entities and their relationships. Navigate to the Not Installed Packages top-level group and Enter, producing:

Clearly there are more sections than we saw in Installed Packages. Let's look at a package named libreoffice-common by using {/} to define a search downward argument (use {\} to define an upward search argument). The dialog pops up, we type in {libreoffice-common}, Tab to the [OK] button:

Were this not the package we are looking for, we would use {n} to see the next (in the same direction) match (or use {N} to search in the opposite direction); however, it is the package we want. If you want to search for the exact package specified, use a {^} prefix and a {$} suffix to match only that exact name (yes, the parameter is a regular expression—for definitive explanation, see regex(7) for Debian and regex(6) for Plan 9):

Now Enter to open a libreoffice-common info subtab.

Note that although the current package summary line remains at the top and it appears that the new information was expanded into the Packages tab, we cannot scroll above that line—we are in a separate subtab. That package summary line does rightly imply, however, that its information is also hierarchical and subgroups can be expanded and collapsed just like in the Packages tab.

Now {]} and Enter to expand just the next lower level:

This is probably a good time to mention the question mark {?} subcommand displays a scrollable list of subcommands available in various contexts as well as (at the end) an explanation of the status codes at the front of the package summary lines (you've already seen "i " and "p " and probably figured they mean installed and purged, respectively). You exit the help tab via the {q} subcommand.

Now End to scroll to the bottom of the info display:

We will skip the fairly self-explanatory items in front and go right to the relationship definitions: Depends, PreDepends, Suggests, Enhances, Recommends, Conflicts, Breaks, Replaces, Package names provided by…, and Packages which depend on…. I chose this package because it has almost all of these—if there are no packages defined for a particular relationship, the info display omits the category. Refer to Chapter 7 - Declaring relationships between packages of the Debian Policy Manual for the details of all these categories. What follows is a quick explanation.

Both depends types identify required packages for this package (PreDepends must already installed, but Depends can be installed concurrently). Recommends are packages that are important to this package, and are normally automatically marked for installation if uninstalled when this package is marked for installation (you might remember we configured aptitude to not automatically install recommended packages). Suggests are packages this package can make use of but will not be ever be automatically installed on the behalf of this package. Enhances are effectively packages that suggest this package. Breaks and Conflicts are packages that normally prevent installation of this package. Replaces are packages that are partially or fully superseded by this package. Package names provided by … are virtual package names satisfied by installation of this package (usually multiple packages are available to provide such facility—provides eliminates lots of pkgA | pkgB | … | pkgX definitions). Packages which depend on … shows all packages, grouped by type of dependency, that Depend, PreDepend, Recommend, or Suggest this package.

Now let's see what all that means to libreoffice-common beginning with Depends which we expand by one level via Enter:

The first red line shows a single dependency that can be satisfied by either libreoffice-style-default or libreoffice-style. We ArrowDown to that line, Enter, and End:

we now see the set of actual packages available to meet this required dependency (UNSATISFIED means aptitude knows of a package that can be installed to meet the dependency, vis-à-vis UNAVAILABLE which means the current set of repositories contain no package that can satisfy the dependency). Since there are two entries for libreoffice-style-galaxy, we don't need to look at the libreoffice-style-default package to discern what it contains—if none of the candidates has been selected by the moment of truth, libreoffice-style-galaxy will be automatically installed because libreoffice-style-default is first in the OR expression.

Now collapse the Depends group and fully expand the PreDepends group:

The dpkg package, a crucial package managing component, is required to be installed at its 1.15.7.2 version or higher before this version of libreoffice-common can be installed (there is something about the way this version of libreoffice-common was made into a Debian package that the older versions of dpkg cannot install correctly). We are then shown the currently installed version of dpkg is up to this task, which is why its line is white, not red.

Now collapse the PreDepends group and expand the next layer of the Suggests group:

Only style packages here, and libreoffice-style-galaxy is not among them. These will never be automatically installed because libreoffice-common was installed—they are merely suggestions.

Now collapse the Suggests group and expand the next layer of the Recommends group:

We see a preference for a newer version of python3-uno over any other python-uno version. We also see a dependency on an xfont-mathml package that is not in the known repositories.

Now collapse the Recommends group and fully expand the Conflicts group:

For all four packages, no version information is displayed; thus, none is in a state to interfere with the installation of this package. But we could surmise that from the color of the Conflicts group line.

Now collapse the Conflicts group and fully expand the Breaks group:

and scrolling to the next screen:

For all 27 packages, no version information is displayed; thus, none is in a state to interfere with the installation of this package, and that is congruent with the color of the Breaks group line.

Now collapse the Breaks group and fully expand the Replaces group:

Neither of these packages is installed, so all is white here.

Now collapse the Replaces group and fully expand the Package names provided by libreoffice-common group:

We see that libreoffice-common will satisfy any dependency upon libreoffice-l10n-en-us.

Now collapse the Package names provided by libreoffice-common group and expand the next layer of the Packages which depend on libreoffice-common group:

Here we see of the 100 dependencies, three do not require this package. Now fully expand this group and scroll down to the end:

Again there is nothing installed already and no red lines to deal with.

Collapse the Packages tab—it's almost time to fill the shopping cart with necessary packages for this project.

Step 2-4-2: Resolving Dependency Conflicts

If the two blue lines at the bottom of the screen ever expand into four lines with the two in the middle backed in red, your last subcommand has caused a conflict. That change announces a conflict resolution dialog has been created to deal with one or more dependency issues that the change has caused. It does not require immediate attention, but serves to warn you there is at least one problem with the current set of marked actions aptitude is slated to perform that will have to be resolved before aptitude will attempt to carry those actions out. The first red line summarizes the solution set aptitude has calculated can resolve the problem(s) and the second tells what additional commands are now enabled to aid you in resolving the problems.

Use Ctrl-U to undo that last subcommand to get back to the unconflicted state if you wish to back out of the situation.

This subsection was extracted from the alpha version of the cookbook to show you how to resolve dependency conflicts should any arise. It is a sidebar tutorial that is not part of this recipe—you cannot perform this precisely with your current environment, so just read the material herein.

Use {e} to open the Resolve Dependencies subtab:

The solution requires removal of the core of the traditional UNIX System V init facility? We ArrowDown to highlight the sysvinit-core package summary line and see:

Debian is changing the default init facility for Stable from sysvinit to systemd, so even though the alpha version of the Debian Installer still installs the old, tried-and-true default, at this juncture aptitude wants to switch to the new default. It is your choice, but as this recipe will permit systemd to take over, if you install sysvinit instead, be prepared to deal with any differing results. You should know there has been significant and emotional discussion about this policy change on the Debian Developers [archive] mailing list, and you really should subscribe to debian-devel, debian-devel-announce, and debian-user (visit this link to learn how to subscribe) while you're running Sid. Also, the debian-boot list will keep you updated on Debian Installer developments and releases, if you're interested. And while I'm throwing out tips, consider installing the apt-listbugs package—it will match your package choices against bug reports in the Debian Bug Tracker facility while you are running aptitude and warn you of any serious outstanding bugs for any package you are attempting to install or update, giving you the opportunity to change your mind.

Having decided this proposed solution is acceptable, we use {!} to inform aptitude of the decision:

which returns us to the Package tab with everything resolved.

Here ends the extraction from the alpha cookbook. If multiple solutions are possible, you can scroll "sideways" through them using the {,} (comma) subcommand for left and the {.} (period) subcommand for right. You can also end the Resolve Dependencies subtab at any time without accepting any solution via {q}.

Step 2-4-3: Mark Needed Packages For Installation

[Note: in this step's commentary, packages that need to be explicitly marked for installation are rendered in bold charcters the first time they are mentioned.] Search for and open the task-desktop metapackage:

You can see what other packages would be marked for installation if we marked task-desktop for installation (remember aptitude is currently configured not to mark recommended packages for installation, so for now only the Depends packages will be marked for installation automatically). PageDown to see the next page, then ArrowDown to the Packages which depend on task-desktop group line and fully expand it:

Notice that this package will always be automatically marked for installation if any of those four packages are marked for installation.

Now ArrowUp twice to the Depends containing the pipe characters and expand its next lower level:

It contains the same packages as the Packages which depend upon task-desktop group.

For this recipe we will use the task-xfce-desktop flavor of the common task-desktop install. But choose what suits you and be prepared for how those inclusions cause your results to differ from those in this recipe.

To mark an uninstalled package for installation, apply the {+} subcommand to it, either directly by highlighting its package summary line first, or as part of an entire group by highlighting the group line first. So we ArrowDown four times to highlight the first task-xfce-desktop package summary line, then {+}:

Okay, what just happened? If you have left aptitude configured to automatically install Recommends, your display will be somewhat different and I'll leave it to you to figure out the differences on the screen and in this recipe.

First, notice the current line has changed color (green on black) and has replaced the space to the right of the "p" (uninstalled) status character with a lowercase "i" (marked for installation). Next, observe the other package summary line for task-xfce-desktop in the Packages which depend on task-desktop group has changed identically except it is the normal black on green for packages that are marked for installation—the current line is reversed video, remember? Next, that package summary line for the task-desktop package at the bottom of the screen is also now marked for installation but it sports an uppercase "A" in the third byte of its status—it is now marked for automatic uninstallation (removal) if all packages which depend upon (or recommend or suggest) it are removed. Also, the change of the libgli-mesa-dri and pipe group lines that were black on red to white on black indicates they are no longer indicating any warnings—the change was advantageous from their perspectives.

In addition to the top package summary line indicating it is the current line and marked for installation and automatic removal just like the line at the end of the subtab, also notice all the Depends lines are now white on black—they have all been marked for installation, too.

Now End and ArrowUp twice to highlight a task-xfce-desktop line and Enter to open a task-xfce-desktop info subtab:

All the Depends lines are white on black. Not so the Recommends lines since aptitude is not currently configured to automatically mark them for installation. The reason for that is this package's 24 Recommends add up to hundreds of megabytes of download that are not essential for this project, notably libreoffice and gimp. In the upper right of the screen, aptitude tells you the total DL (download) size for all packages currently marked for installation. The Compressed Size field of each package shows you only the value for that package, not any other packages it might require. So it is easier to simply monitor that DL Size value as you mark packages for installation and balance needs against costs.

Therefore, the minimum set of packages to select here includes iceweasel (Debian came up with this name when Mozilla would not permit their packaging of Firefox to be so named) and xfce4-goodies—mark them for installation now (note that xfce4-terminal is depended on by xfce4-goodies):

Those and their requirements added ~50 MB to the download. Now {q} twice to return to the Packages tab, search for task-ssh-server, and mark it for installation:

Now find and mark for installation bzip2, parted, qemu-kvm, drawterm, bridge-utils, and ed, the text editor that is distributed in both Debian and Plan 9 and is the venerable tool in which much of UNIX and C was developed, where grep began as a subcommand and became a verb before its elevation to a stand-alone program, and is still supported by the patch program. If you want to be able to format the vfat USB-stick in the last section, you probably want to install the dosfstools package, too.

Next we search for virt-manager and open its virt-manager info subtab:

While this GUI interface is fairly new, the underlying virtualization this package depends upon is not. If you want to be a purist and avail yourself of the virsh CLI, fine. Perhaps future editions of this cookbook will provide the precise incantations you will require in addition to the GUI screenshots.

PageDown, ArrowDown to the ask-sshpass Suggestion, fully expand it, ArrowDown to the package summary line (it's unnamed), and {+}:

Lastly, PageDown to the Recommends lines and mark gnome-icon-theme and libvirt-bin for installation, and last of all, End and {+} to mark virt-manager itself for installation:

Our shopping cart has grown to ~200 MB of downloads and we're ready to install it all.

If you need to install any other packages, it is your responsibility to make certain nothing you add will interfere with the cookbook project's required packages. This especially applies to the network-manager and resolvconf packages—do not use either (unless you can get them to play nicely with the virtual bridge, in which case you need to share how to get them working so that can be added to this document for the benefit of others).

Collapse everything in the Packages tab to provide an uncluttered screen before continuing.

Step 2-4-4: Update the Repository Information

It's been some time since the repository status was updated, so before we attempt to install our choices, we make certain the list is up-to-date with a {u} subcommand. We can watch aptitude check for and download as necessary updated repository metadata files, then pause as we requested:

and Enter returns us to the Packages menu:

Nothing new and nothing to update—the core packages must be experiencing some inattention at this time (unlikely) or the mirror is getting behind (less unlikely).

Your experience will likely be different. Know that any new packages are highly unlikely to represent security patches; however, updates should be investigated and most likely be marked for installation. If you choose to install all updates, simply issue the {U} subcommand (this works from anywhere) to mark all the updates for installation. Alternatively, you can mark individual updates for installation using the {+} subcommand on the update's summary line. Take a look at Subsection 2-6: Install Package Updates for details about this process if this is new to you.

Step 2-4-5: Processing the Preview

It's time to checkout, to tell aptitude to "make it so", so issue {g} to open the Preview subtab:

Here we see all the packages that will be processed if we do not modify this list prior to a second {g} subcommand while in the Preview subtab (note the Preview display can be toggled off in the Preferences subtab, in which case, go does not pass Go but proceeds directly to downloading the needed packages). The list groups the packages in collating sequence within similar activity types. As you scroll through, marvel at all the packages that are being automatically installed while looking for omissions or inclusions that might be problematic for your project, and make adjustments as needed, if possible. Look very closely at the group Packages which are recommended by other packages (but are not marked for installation) unless you haven't selected any additional packages for installation.

The final line of suggestions is not expanded, so you need to do that to review them as shown here:

Home and {_} (underscore) to mark all the packages to be removed to instead be purged, which adds deletion of their configuration files to the removal process (there's no benefit to keeping them, and purging them simplifies some tasks package management must handle while reducing cruft in your system):

In the same way, the more packages can be marked auto-remove, the easier it is for package management to develop good conflict resolution solutions. To do this, collapse the first two top-level groups to bring the non-automatically installed group near the top, highlight the first package in the list (most likely drawterm), and mark it for automatic removal with {M}:

If, as is the case for drawterm, that causes it to unselect for installation, then no other package already installed or marked for installation depends on (or recommends or suggests) it, so it cannot be marked for automatic removal, and you need to undo the {M} subcommand with Ctrl-U:

Otherwise it will set the third status byte to "A" and remain marked for installation. Attempt to mark each package in this group for automatic removal:

We are ready to start the actual installation.

Step 2-4-6: Download and Install

When you're finished with changes to the Preview subtab, {g} starts the downloads and installation. If your bandwidth is not exceptionally good, this is a great time to go eat a big meal (or perhaps get a good night's sleep). If aptitudes's Pause after downloading files preference is currently set to Always or When an error occurs and a download error occurs, aptitude will ask for approval to continue after the downloads have ended, so if you want the entire process to run without any interaction with you, you must first set that preference to Never; however, keep in mind it is possible additional packages you have marked for installation will require configuration input from you.

Once past this point, installation proper begins.

After unpacking completes, setting up begins:

Eventually it will finish installing:

Enter to return to aptitude's Packages tab:

Ctrl-T to open the menu bar:

{c} to request the package cache be cleaned of the downloaded packages:

and Enter to acknowledge the pop-up message and return to the Packages tab. Then Ctrl-T and {o} to tidy up obsolete files, if any:

and Enter to acknowledge the pop-up message, then use either {q} or {Q} to finally exit aptitude.

Step 2-4-7: Add vmadm to libvirt Group

The final step in installing the needed software is to make the vmadm user (or whatever you named the account) a member of the libvirt group that was created when the software was being installed. Run the command {adduser vmadm libvirt} (with the user modified as needed) from the root session.

Subsection 2-5: Reboot and Verify Virt-Manager Setup

The time has come to test the installed packages, especially the GUI and virtual management/infrastructure packages. This begins with rebooting the system although technically it shouldn't be necessary to reload the kernel (but it may simplify any trouble-shooting that is needed).

Run the command {telinit 6} from the root terminal session. The system should shutdown in short order and begin rebooting. Let it invoke the default kernel without interference. If XFCE was installed properly, a GUI login screen should presently materialize much like this:

Logon to the vmadm account you created. When asked about the desktop panel configuration:

opt for the default:

If that bottom panel annoys you as it does me, get rid of it by right-clicking on the vertical bar between its two left-most icons (neither icon can be highlighted), mouse-over the Panel menu item that pops up, and left-click on the Panel Preferences that pops up:

ensure Panel 2 is selected and click on the minus sign icon item therein:

Left-click on the Remove button of the confirmation dialog that pops up:

and close the Panel pop-up by a left-click on the Close button:

The icon in the top right corner of the screen should contain the full name of your vmadm user. If you left-click on it, various session management options drop down (this is how to log off):

Don't do that now, instead Esc or just left-click someplace other than inside the drop-down window.

Now left-click on the Applications Menu icon, mouse-over the System item that drops down, and left-click on the Virtual Machine Manager item that drops down to start a virt-manager session:

then verify the Virtual Machine Manager window opens and its localhost (QEMU) line displays as shown:

Here is what one common failure looks like:

If this happens to you, make certain your vmadm user was added to the libvirt group by running a {grep '^libvirt:' /etc/group} command:

If you do not see your vmadm userid, something went wrong in Step 2-4-7: Add vmadm to libvirt Group so figure out what that was and try running virt-manager again. If that resolves your problem, great; if not, like it said, verify libvirtd is running using a {ps -axw | grep virt} pipeline. If it looks pretty much like this:

that's not the problem. Were there any unexpected things that occurred? Could there be a fix needed that the mirror didn't have yet? If so, then switching to the official Debian repository would prove that is so. So the following incantations in a root shell set the stage to test this hypothesis:

cd /etc/apt
cp -p sources.list sources.mirror
echo 'deb ftp://ftp.debian.org/debian/ sid main' >sources.list
cat sources.list

and make sure it looks like this:

If so, issue an {aptitude} command, issue the {u} subcommand to start a repository update, and acknowledge the download completion via Enter, and:

Indeed, the mirror is somewhat dated and the solution may be found by installing these updates.

Subsection 2-6: Install Package Updates

So now we will go through the actual process that Step 2-4-4: Update the Repository Information briefly discussed. If you already understand this process, you can skip down to the last two paragraphs prior to Subsection 2-7: Reconfigure Networking To Support Guests after you have installed any updates.

Expand the New Packages group and look for anything that might be interesting to you. At this time, however, it's probably better to make a note to install it after the dust has settled rather than mark it for installation now.

Then {f} to forget their newness, followed by fully expanding the Upgradable Packages group, then scrolling through to note anything interesting:

Nothing exceptional is obvious; nonetheless, we invoke {U} to mark them all for installation:

There being no conflicts appearing, we Home, collapse the group, and {g} to preview the work to be done:

Now mark all possible packages for automatic removal as possible while looking for any concerns, especially the uninstalled recommends (but first toggle on the Advance to the next item after changing the state of a package preference to eliminate the need to ArrowDown after every {M} subcommand—there is no need to ArrowUp when Ctrl-U is necessary to undo an unworkable {M}):

There being nothing obvious we need to change, nor any Suggestions to expand and possibly mark for installation, we confirm the plan via {g} again and monitor progress (not all output is shown):

Remember to scroll back using the Shift key combos to verify no problems were revealed, as was the case for this run, then Enter:

Now clean up via Ctrl-T {c} and Enter, then {Q} or {q} to exit aptitude.

The new updates now being in place, attempt the virt-manager localhost connection again. If the updates didn't fix the problem, at least you are current when you begin looking for assistance with this problem.

Once the localhost connection has opened successfully, close it again—we will hopefully be back to it very soon.

Subsection 2-7: Reconfigure Networking To Support Guests

It is time to convert the eth0 wired LAN interface dedicated to the p9host system into the LAN side of a virtual bridge provisioned by the p9host system into which guest operating systems may be connected, thus appearing to the LAN as real computers physically connected to the same IPv4 subnet. This cookbook recipe provides a magical incantation to make this change. For understanding study:

http://wiki.debian.org/BridgeNetworkConnections

http://wiki.libvirt.org/page/Networking#Debian.2FUbuntu_Bridging

http://backreference.org/2010/03/26/tuntap-interface-tutorial/

Step 2-7-1: Create New Configuration Files (with ed Tutorial)

We need to edit the Debian network configuration files /etc/network/interfaces and /etc/resolv.conf to redefine the eth0 interface as the br0 interface and ensure DNS resolution is set up properly. We will use the ed command to familiarize you with this tool that will also work on the Plan 9 system that we will build in the next section. The {man ed} and {info ed} commands will provide you with the references you might need to fully understand this tool (if you need help using man and info, there are {man man} and {man info} commands for that).

As installed into your system (presuming you are using the wired eth0 interface this recipe expects), the /etc/network/interfaces file should have the following format:

This will be edited into the following formats of two files: (1) /etc/network/interfaces.next:

and (2) /etc/resolv.conf:

In a root terminal session, we change the working directory to the /etc/network directory, create copies of the current files, edit them, and display the results as shown by the following commands, beginning with:

cd /etc/network
cat interfaces
cat /etc/resolv.conf
cp -p interfaces interfaces.next
cp -p /etc/resolv.conf /etc/resolv.conf.next

Next we start the ed command, which reads the new interfaces file into ed's editing buffer in RAM and begins reading ed subcommands from the current stdin file of the shell:

ed interfaces.next

The first ed subcommand, change, replaces the first ten lines in the buffer with the literal lines following the subcommand up to but not including an input line that contains just a single period:

1,10c
auto lo br0
iface lo inet loopback
iface br0 inet static
.

The next subcommand, delete, searches down from the current line in the buffer (called dot in ed parlance), wrapping at the end of the buffer if needed, to the first line that contains the regular expression (regex for short) {# dns-}, which in this case means that exact sequence of characters (since no regex metacharacters are in that regex—well, - can be but in this context it is not). Since only one line in the buffer matches, it doesn't matter from where the search commences. To that line (target in ed parlance) the d subcommand is applied, causing that target to be elided from the ed buffer. The line immediately preceding it becomes dot (note that in the Plan 9 version of ed, dot is assigned to what follows—there's a good reason for that, but for now, just make a mental note of the behavioral difference):

The substitute subcommand that follows identifies an inclusive range of lines to be edited by the subcommand, starting with the last line in the buffer minus 1 (the next to last line) and ending with the last line in the buffer; thus, two lines. Substitute finds the substring in the target lines that matches the regex delimited by the first and second slash characters (/).

That regex begins with the hat (^) metacharacter that, as the first character of the regex, is taken to mean the beginning of the line—this is called an anchor in regex parlance as it does not match a character, but rather a location.

The next character in the regex is period aka dot (.), another metacharacter that matches any character in its position in the regex (in this case, the first character of the line) except the non-printing end-of-line character (aka newline, LineFeed or LF), which is also associated with Ctrl-J. Thus, so far this regex will match any line that is not empty or null, that has at least one non-LF character (contiguous LFs define a null line).

The dot metacharacter is connected to the asterisk aka star (*) metacharacter after it. The effect is to match zero or more contiguous occurrances of the preceding pattern (in this case, a single non-LF character). The extent of the target substring matched by the (.*) expression is limited by a match of the next expression in the regex.

That would be the {dns-} sequence which completes this regex, which, as was true of the previous delete subcommand's regex, matches that exact sequence of characters anywhere in the rest of the line (again, the (-) in this context is not interpreted as a metacharacter).

Thus it has been shown that what will be substituted for in each target line is the substring starting with the first character and ending immediately after the (last or only) (dsn-) substring. If there is no (dns-) substring in a target line to match, the entire regex does not match—the substring to be replaced is null, and no substitution is performed for that target line, and is not considered an error (errors are signified by the display of a line containing a single question mark (?)—if that's too terse, the {H} subcommand toggles the display of somewhat more helpful feedback).

The second and third slash characters in the substitute subcommand delimit the string that is to replace the matched substring in the target line. In this case, it is null, so the matched substring is simply removed from the target line—the character (if any) after the matched substring becomes the first character in the line.

Dot is set to the last line that was modified or it remains unchanged:

$-1,$s/^.*dns-//

This copy subcommand duplicates the last line, setting dot to the new last line:

The next subcommand changes the (search) substring in the next-to-last line to (domain) and sets dot to that line:

$-1s/^search/domain/

The next subcommand, move, relocates the line just before dot to the end of the file and sets dot to the new last line:

The next subcommand changes the first plural word in the current last line to its singular form; i.e., its trailing (s) is eliminated (in this case dot is not changed):

The write subcommand writes the last three lines of the buffer into the existing file /etc/resolv.conf.next, completely replacing the data in the file but not changing the file's permissions or ownership. Note that writes do not affect dot.

$-2,$w /etc/resolv.conf.next

The next subcommand replaces those three lines just written with those following the subcommand up to the single period input delimiting line, producing a new dot at the end of the buffer (if you are using a different name for vmadm, be sure to replace vmadm in the text to that name). Be very careful typing (in this case, mind your "p"s and "b"s):

$-2,$c
bridge_ports eth0 tap0
bridge_stp on
bridge_maxwait 0
bridge_fd 0
pre-up ip tuntap add dev tap0 mode tap user vmadm
pre-up ip link set tap0 up
post-up sysctl net.bridge.bridge-nf-call-ip6tables=0
post-up sysctl net.bridge.bridge-nf-call-iptables=0
post-up sysctl net.bridge.bridge-nf-call-arptables=0
post-down ip link set tap0 down
post-down ip tuntap del dev tap0 mode tap
.

This write subcommand writes the entire buffer into the default file. Since we have not used the (f) subcommand to change the default, it has remained the file that was initially read into the ed buffer:

This form of the quit subcommand terminates ed even if it the buffer contains changes that have not been written to a file:

These shell commands display the results of the editing:

cat interfaces.next
cat /etc/resolv.conf.next

Your ed terminal session should look very much like this:

Step 2-7-2: Stop the eth0 Interface

Run the command {ifdown eth0} from the root session, which will halt all network traffic to and from the LAN.

Step 2-7-3: Replace the Old Network Configuration Files

Run the following commands from the root session to save and replace the network configuration files:

mv interfaces interfaces.prev
mv interfaces.next interfaces
mv /etc/resolv.conf /etc/resolv.conf.prev
mv /etc/resolv.conf.next /etc/resolv.conf

Step 2-7-4: Start the br0 Interface

Run the command {ifup br0} from the root session, which will restart all network traffic to and from the LAN. Note that, depending on the phase of the moon, every once is a while br0 can take as long as half a minute to come up (this probably has something to do with the spanning tree protocol). In some cases, {ifdown br0} followed by {ifup br0} gets things straightened out. A hard failure is usually a typo in the interfaces file, though.

Once the messages have stopped, run the command {ip link} and confirm the eth0 and br0 link addresses are both set to the MAC address of your physical NIC:

If not, try the ifdown/ifup fix. So far this anomaly has only been observed the first time br0 is brought up.

Then check that pinging your external DNS server returns echos using the {ping} command specifying the IP address of your external DNS server (terminate the command by interrupting it, normally via Ctrl-C):

Lastly run an {aptitude update} command and verify it actually checks the Debian repository (and most likely downloads one or more updates—in my case, many since it takes time to capture and edit these screen shots, not to mention writing this commentary around them):

Once these test complete nominally, the host system is ready for you to proceed to the next section and create the Plan 9 virtual machine. However, you should probably install any updates you just downloaded first (whoa—linux-image-3.16-1? I guess so…).

Virtual Plan 9 Cookbook
Section 2: GNU/Linux Host Preparation

Subsection 2-0: Introduction

Subsection 2-1: Build Debian Installer Jessie Beta 1 Media

Step 2-1-1: Download the ISO image

Step 2-1-2: Copy the ISO image to a USB-stick

Subsection 2-2: Install Jessie Using Debian Installer

Step 2-2-1: Backup the Project Platform As Needed

Step 2-2-2: Boot From the Debian Live USB-Stick

Step 2-2-3: Choose Language, Location, and Locales

Step 2-2-4: Configure the Keyboard

Step 2-2-5: Detect and Mount CD-ROM

Step 2-2-6: Load Installer Components From CD

Step 2-2-7: Detect Network Hardware

Step 2-2-8: Configure the Network

Step 2-2-9: Choose a Mirror of the Debian Archive

Step 2-2-10: Set Up Users and Passwords

Step 2-2-11: Configure the Clock

Step 2-2-12: Detect Disks

Step 2-2-13: Partition Disks

Step 2-2-14: Install the Base System

Step 2-2-15: Configure the Package Manager

Step 2-2-16: Select and Install Software

Step 2-2-17: Install the GRUB Boot Loader on the Hard Disk

Step 2-2-18: Finish the Installation

Subsection 2-3: Upgrade the New Host System to Sid

Subsection 2-4: Install Needed Packages

Step 2-4-1: Introduction to Aptitude and Packages

Step 2-4-2: Resolving Dependency Conflicts

Step 2-4-3: Mark Needed Packages For Installation

Step 2-4-4: Update the Repository Information

Step 2-4-5: Processing the Preview

Step 2-4-6: Download and Install

Step 2-4-7: Add vmadm to libvirt Group

Subsection 2-5: Reboot and Verify Virt-Manager Setup

Subsection 2-6: Install Package Updates

Subsection 2-7: Reconfigure Networking To Support Guests

Step 2-7-1: Create New Configuration Files (with ed Tutorial)

Step 2-7-2: Stop the eth0 Interface

Step 2-7-3: Replace the Old Network Configuration Files

Step 2-7-4: Start the br0 Interface

Virtual Plan 9 Cookbook Section 2: GNU/Linux Host Preparation

Subsection 2-0: Introduction

Subsection 2-1: Build Debian Installer Jessie Beta 1 Media

Step 2-1-1: Download the ISO image

Step 2-1-2: Copy the ISO image to a USB-stick

Subsection 2-2: Install Jessie Using Debian Installer

Step 2-2-1: Backup the Project Platform As Needed

Step 2-2-2: Boot From the Debian Live USB-Stick

Step 2-2-3: Choose Language, Location, and Locales

Step 2-2-4: Configure the Keyboard

Step 2-2-5: Detect and Mount CD-ROM

Step 2-2-6: Load Installer Components From CD

Step 2-2-7: Detect Network Hardware

Step 2-2-8: Configure the Network

Step 2-2-9: Choose a Mirror of the Debian Archive

Step 2-2-10: Set Up Users and Passwords

Step 2-2-11: Configure the Clock

Step 2-2-12: Detect Disks

Step 2-2-13: Partition Disks

Step 2-2-14: Install the Base System

Step 2-2-15: Configure the Package Manager

Step 2-2-16: Select and Install Software

Step 2-2-17: Install the GRUB Boot Loader on the Hard Disk

Step 2-2-18: Finish the Installation

Subsection 2-3: Upgrade the New Host System to Sid

Subsection 2-4: Install Needed Packages

Step 2-4-1: Introduction to Aptitude and Packages

Step 2-4-2: Resolving Dependency Conflicts

Step 2-4-3: Mark Needed Packages For Installation

Step 2-4-4: Update the Repository Information

Step 2-4-5: Processing the Preview

Step 2-4-6: Download and Install

Step 2-4-7: Add vmadm to libvirt Group

Subsection 2-5: Reboot and Verify Virt-Manager Setup

Subsection 2-6: Install Package Updates

Subsection 2-7: Reconfigure Networking To Support Guests

Step 2-7-1: Create New Configuration Files (with ed Tutorial)

Step 2-7-2: Stop the eth0 Interface

Step 2-7-3: Replace the Old Network Configuration Files

Step 2-7-4: Start the br0 Interface

Virtual Plan 9 Cookbook
Section 2: GNU/Linux Host Preparation