Using First Virtual Machine

Creating the virtual machine

The first step to using a virtual machine is to have an available virtual machine.

In theory, the data (typically stored in a “disk image” file) and configuration (which may be stored in some sort of “configuration file”, possibly in the form of a script) could be downloaded. That may, or might not, be rather simple to implement. (One factor would depend on what virtual machine is being used.)

The other approach is to create a new virtual machine from scratch. That is the approach that this guide is designed for.

  • See: Make first VM.
    • Follow all of the directions from that section.
Physical machine adjustments

Run: date

Fixing time

If time seems off, check to see if the project documentation specified a specific “time server” to contat. Otherwise, use:

time sudo rdate -v

(If that program seems to indicate that the time is set correctly, but the time still seems off, it may be that the machine is configured for a different time zone.)

Another option that can be done is to use NTPD.

Related topics:

Starting the virtual machine software
Pre-start: protect terminal

This “Pre-Start” section is unnecessary if using Qemu's “-vnc none” option and if the -monitor command is redirecting the monitor. In such cases, the program is not going to be using “standard output” at all. Also, if there are no display options, and the system is using SDL to display output to an X Windows session, then this is also unnecessary.

However, if the virtual machine software is configured so that interesting output may be sent to the “standard output” stream of the terminal/console, then it will be good for that terminal/console to not be lost just because of an incident like a temporary disconnection in network connectivity.

If you did specify to use the curses library for output, then do check out the section about virtual machine: protecting terminal.

Okay, so now that you've done all of this preparation (including installing software on the host system, and customizing the script file), go ahead and start the virtual machine software. Just know, ahead of time, that the virtual machine software might, or might not, make the virtual machine's video output be immediately visible. If the virtual machine's video output is not immediately visible, that doesn't necessarily mean that the virtual machine is not running. So, depending on the setup, you might, or might not, see much that is interesting.

With that introduction out of the way, go ahead and start the virtual machine. This is done as easily as simply running the script that has been created.

ls -l ${VMDirBas}/execbin/${VMGenNam}/${VMLILNAM}/sysstart/exc_${VMLILNAM}

One possibility is that a virtual machine's display output is being seen. The other possibility is that the virtual machine's display output is not being seen. There are multiple reasons why the display output might not be seen. Let's look at just what is happening, and what can be done if no output is seen.

Check for any error messages

Probably the first thing to do is the check if any error messages were reported. One key reason to do this first is because this is easiest to do while the message is still on the screen, before the message scrolls off.

The script's default output may be a bit verbose. Just look towards the end and see if there is anything that immediately looks like a problem. Here is an example of the end of the output from a time when there was an actual problem.

End of ps results (logged to ~/mygrep.res). Machine number ##
leaving /fullpath/exc_demomach
myShellPrompt$ qemu: -net user,,vlan=1: Invalid parameter 'user,,vlan=1'

If there were error messages, keep reading this section. If there weren't, you may wish to skim past this section, to the section that mentions checking if Qemu is running.

Analyzing the example output

(The reference to demomach was based on the value of the ${VMLILNAME} variable.)

This example was using a buggy version of the startup script, which occurred during the internal software development process. That exact error shouldn't occur now that the script has been fixed, but this does show what would happen if there was a typo in the Qemu command line (which is an error that may be a bit more likely to happen). For now, these instructions aren't focused on the specific error message, but are looking at how to identify where the useful error message is found.

So what happened here is that the script completed. The last thing the script did was to output the message, “leaving exc_demomach”. After that, the command line shell showed a prompt. One thing that the script did, before exiting, was to start a command in the background. That command tried to start up Qemu, and then reported the error code. Starting up Qemu failed, and so a message was displayed to the screen. Then, the background process reported the error code. That is the expected before of the /bin/ksh version of the script. This exact behavior would be a bit different if the ampersand was removed, which would have caused Qemu to be started in the foreground (instead of being started in the background). When Qemu is started in the background, as shown, then it may be satisfying to just press the Enter key so that additional typing looks like it is coming right after a prompt is displayed, which is, in fact, exactly how the command line shell is interpreting things.

So, with all that technical analysis mumbo jumbo out of the way, here's the simple and straightforward step to perform:

Look for the output that says “Err/Res=”. This shows the resulting “error level”/“return code” from the Qemu process, and should be “0” (a zero). If that is not a zero, then the Qemu process probably is not running. In that case, as shown in the above example, look for some output just above the error/response code, and see if that indicates the problem.

Actual specific error(s)
Disk image issue

e.g., if this is an error message:

qemu: -hda /filedir/filename.qc2: could not open disk image /filedir/filename.qc2: Could not open '/filedir/filename.qc2': No such file or directory

Wow! One problem, yet three times that the filename is reported. Well, let's just go check out that file.

ls -l /filedir/filename.qc2

The output of that command may very often be tell-tale.

If using the script file, then the following command might also provide some insight.

echo VMDirBas=${VMDirBas} VMGenNam=${VMGenNam} VMLILNAM=${VMLILNAM}
ls -l ${VMDirBas}/diskimgs/baseimgs/${VMGenNam}/${VMLILNAM}/${VMLILNAM}?.qc2

If the file exists, people who are familiar with Unix-style permissions may wish to just quickly check the permissions. The next thing to do is to check very, very carefully to see if the path of the filename that exists matches exactly with the path that Qemu said is not readable. When using the script file that this guide refers people to, a common reason might be that the file exists, but that one of the variable names isn't right in the script file. That causes the script to be unable to find the file, even if the file is right where it should be.

If the paths do match, exactly, a potential issue could be the Unix permissions. (Anyone who didn't check the permissions yet might want to learn a bit about interacting with Unix-style permissions.) See if the file can be copied. (A reference to a guide may be added here at a later time.)

If the file doesn't exist, check the earlier directories to try to narrow down just what part doesn't exist.

ls -l ${VMDirBas}/diskimgs/baseimgs/${VMGenNam}/${VMLILNAM}/${VMLILNAM}?.qc2
ls -ld ${VMDirBas}/
ls -ld ${VMDirBas}/diskimgs/
ls -ld ${VMDirBas}/diskimgs/baseimgs/
ls -ld ${VMDirBas}/diskimgs/baseimgs/${VMGenNam}/
ls -ld ${VMDirBas}/diskimgs/baseimgs/${VMGenNam}/${VMLILNAM}/
ls -l ${VMDirBas}/diskimgs/baseimgs/${VMGenNam}/${VMLILNAM}/

(Note that some of those commands use “ls -ld”.)

qemu: -net tap,...,ifname=tun###,script=/somepath/upif#,downscript=/somepath/dnif#: Device 'tap' could not be initialized

  • Make sure that the device specified by ,ifname= exists
  • Make sure that the device is available. No other virtual machine is allowed to be using it. (Use ps and grep to see if the device's name shows up with any other processes.)
  • Look for additonal error messages, such as: “/somepath/upif#: could not launch network script”. If that error message also exists, there is an issue with the network script. (Perhaps it does not have the right permissions, or it does not have a proper header line... or perhaps both of those are issues, because perhaps it might not even exist!) If that happens, the Qemu program will refuse to use the TUN/TAP device (because of the error that gets encountered earlier in the process), and then spits out that confusing error that makes it look like the problem is related to the TUN/TAP device. Fix the other problem first.
/somepath/upif#: could not launch network script
  • Make sure that the file has suitable permissions
  • Make sure that the header is proper. (It should start with “#!/”, and have more characters that help point to the path of a shell.)
    • If the line has a DOS-style “newline” character, nano can detect that fairly easily. If nano is not installed, many Unix systems have a command named tr that could be used to fix the issue. At the time of this writing, this is actually discussed more by configuring a new child.
  • Make sure that the script exits with a “errorlevel”/“return code” of zero. It could be that the script is executing (despite Qemu's error message), but the “return code” is not what is expected. If you have doubts about what “return code” is provided by the script, try adding “echo ${?} at the end of the script file. (That will return what the “return code” would have been. However, it will also adjust the “return code”, and cause the script to return a value of zero, if the line gets executed.)

If there are no error messages noticed, follow the next steps to verify that the software is running, and then to enable visibility of the display.

[#ckifqmrn]: See if it is running

See if Qemu is running. (Details are on a seperate page, since this process also gets referred to later. See: check if Qemu virtual machine is running.)

Seeing the virtual machine's (unpaused) display

See the virtual machine's display, and make sure the virtual machine is actively running (unpaused). These tasks are documented in more detail at: seeing the running virtual machine.


Determine some of the details that will be needed for installing the operating system. For example:

  • You should have decide upon a username and a password (if the operating system is a modern day multi-user operating system).
  • Determine networking details:
    • Determine how the machine will get any IP addresses it will use.
      • For a base operating system image, you will probably want to configure the operating system to rely on automatic addressing, because that will be the most useful configuration for most machines. This should be done if possible, even if automatic addressing requires some other network resources that are not available yet.
      • If you will be using static addressing, make sure you know what IP addresses and subnet mask will be used.
    • Determine routing information
      • For most setups/configurations, especially simple setups that new people will want to be using as they are learning how to use software, you'll probably just use a single gateway address, which will be known as the “default gateway”. This “default gateway” should be in the same subnet. The technicalities of that can be understood by those who have been trained in subnetting. For others, simply know that the “default gateway” will typically start with many bits identical to the IP address. This typically means that many numbers will be the same.
  • Know what to install
    • e.g.: install multiprocessor support and games, but not compilers. (Note: This is simply an example, and not a recommendation. Installing lots may be a perfectly fine idea.)
  • Know about how this installation will deviate from a common, straight-forward installation that uses defaults.
    • e.g., making /home/ a reasonable size in Unix. dirsver/1/mainsite/software/opsys/fullos/bsd/openbsd/obsdinst/obsdinst.htm provides some discussion, such as reasoning behind a decision to delete such a partition from a BSD disklabel
    • e.g.: in OpenBSD, /usr/obj/ has been known to be too small by default; OpenBSD size requirements for /usr/obj/
      • One way to make this larger may be to delete /home from the disklabel, and then make a smaller /home section at the end of the available disk space. Later, if /usr/obj is going to be used, the free space can allow an easier creation of a larger partition.

These decisions may be good to document, so that successful experiences can be reproduced (after some of these decisions may have been forgotten), and so that experts might be able to troubleshoot problems simply by looking at the logs.

Starting the virtual machines

If you've just completed the prior part of this tutorial, then the virtual machine may already be running. However, if you took a break and intentionally turned off the system, or some other event happened (such as accidentally losing electrical power), then it can be nice to know how to start up a virtual machine that has been previously started.

Install the operating system

At this point, it is time to install the operating system system.

There are a few things to keep in mind while installing the operating system. First, this guide references another tutorial about “installing the operating system”. However, that is a separate guide. So, if you do choose to refer to that other tutorial, remember to come back to this complete this tutorial.

While installing the operating system, also keep the following details in mind:

Key items during main installation process
Disk details
Multiple disks

This guide created virtual machines with multiple disks. Support for the second disks will be covered at a later part of this guide. So, for now, feel free to just focus on getting the first disk partitioned, and to have the operating system be installed onto the first disk.

Layout of primary disk

Presumably, some time has been spent determining the size of the operating system. This would have been done when determining how big to make the disk.


In Unix, some operating systems may have a directory for data for users (like /home/ or /users/). As an example, in OpenBSD, a lot of extra disk space may be utilized by that directory, by default. For example, gigabytes may be used for that purpose.

That may make some sense for a machine that lots of users will be logging into. However, for some other computer systems, it may make more sense to set aside only a small amount of space for the location where users will be storing data. If the installer will format locations that have a specified mount point (e.g., OpenBSD's installation process), this remaining space can be mounted to some spare location that doesn't normally get used (/tmp/sparedsk/, perhaps?). Otherwise, the disk space could just sit there unformatted. Even if the disk is formatted right away, then it can be left unmounted. Any of those options will be more convenient than having all of the space be in a large partition which is ineffectively used, storing only data that should be preserved before the space gets used up.

Then, if more space is needed for the home directories of users, the /home/ can be replaced with the larger amount of unused space (or, if just one user is using lots of space, perhaps just that user's directory could use the larger amount of space). However, for some systems that are simply servers, there might be a larger need for space in another location, like /usr/ or a subdirectory under that (like /usr/src/). By leaving the large amount of space available (and unmounted), the exact location that the space gets used can be flexible.

(Even more flexibly: if this large space gets left unused in a “base”/“parent” disk image, and multiple virtual machines are using different “child”/“snapshot” disk images, then these multiple machines could use the conveniently available space in two different locations.)

Steps to perform

For a Unix-style operating system, if the system is going to be a server that will not be having a bunch of users storing data in their own home directories, and if a large amount of space is deciated to a partition that will be mounted at /home/ or /users/ after other partitions, then just delete that partition. That will cause the directory (e.g. /home/ or /users/) to go to the parent mount point, which may be ideal, as the amount of space that will be used up by those directories will likely be very minimal.

By doing this, the extra disk space can then easily be manually manipulated at a later time, if desired.

Networking setup

If you're using Qemu's built-in “user mode” networking, there is a DHCP/IPv4 server built-in. So, when installing the operating system, don't be afraid to try using DHCP/IPv4 for easy network configuration.

Networking issues

Hopefully, networking issues will not be a problem that is encountered during the operating system's installation. If they are encountered, then some response will be needed so that things work okay.

If there are problems with the networking, consider possibilites that are likely. For instance, what DNS server is being used?

Qemu's “user mode networking” instance, which does not support IPv6 nor ICMP/IPv4 (or anything else over IPv4, except for UDP and TCP), relies on the host's first DNS server for details. If that single DNS server fails to respond, many programs are designed to work if the computer will use other available DNS servers. However, Qemu's “user mode networking” does not try other DNS servers.

Ways to handle the issue
Modifying the external DNS servers

You can try just adjusting the name resolution settings. With many operating systems, the installer boots off of a RAM drive, and so there is no substantial problem with overwriting the existing DNS configuration on that disk. Be warned that this approach could result in overwriting important configuratino data if this is done when booting from the hard drive. So, this approach is NOT good to do in all situations. In some situations, though, these instructions work marvelously.

We'll use OpenBSD as an example. With OpenBSD, first get to a command prompt. To do so, type ! (and press the Enter key).

Then, check out the existing configuration.

Type 'exit' to return to install.
# cat /etc/resolv.conf
lookup file bind

Change that, using an address that will work. For example, addresses from usable DNS servers can be used.

echo nameserver> /etc/resolv.conf
cat /etc/resolv.conf
Another approach

Another option may be to temporarily abort the attempt to install the operating system, shut down the virtual machine, and properly handle the task of setting up networking on the virtual machine. (That is a task that this guide recommends anyway. That task can be delayed, so that a user can enjoy the more thrilling excitement of completing the operating system's installation, if the default networking options are suitably working. However, if the default networking options are not suitably working, then implementing the other networking configuration, right away, might be best. There may be little to no benefit from procrastinating on the task that may well fix the issue.)

Wrapping up system installation

Read the final screen to see whether the installation program has any final messages, like any errors/complaints when it performs final checks. (With OpenBSD, sometimes a problem has been known to be reported with a task like installing the boot loader, and such an error message is likely to still be on the screen (rather than having been scrolled off). Sometimes such a potential issue is an impacting problem, and sometimes not. If there is a problem, then at least knowing of the high probability of a problem may be more pleasant than just being suddenly surprised after the reboot, at which time you may be left just wondering if there was an error message that might have been helpful.)

Read the final screen to see if there are any error messages witnessed.

MBR checking

For OpenBSD systems that are MBR-based, check the MBR after installing the operating system, but before rebooting. Doing so could result in noticing a problem that is quicker to fix before the reboot. Run:

# fdisk diskname


# fdisk sd0

is common. If that doesn't show an MBR, try:

# fdisk wd0
  • Verify that the disk signature is correct (0x55AA, which might show up as “0xAA55” like it does in OpenBSD's fdisk, as discussed at 511th and 512th bytes: Magic signature).
  • Also verify that at least one (possibly more, but probably only one) of the partitions is flagged (with an asterisk in the left column, which indicates the partition's “active flag” is set to 1).

If there are issues discovered by those checks, perhaps help may be at OpenBSD fdisk Partition Report and/or OpenBSD installation guide: Handling the boot record (MBR) data

Handle system boot

The post-installation process of an operating system onto a virtual machine may be a bit different than a physical machine.

If using a physical system

If the operating system was just installed to a physical machine that booted from a removable disc, you'll probably want to take the disc out of the drive and then reboot. On some Unix systems, this might possibly simply by running the following command:

# reboot
If the OS installed to a virtual machine

On a virtual machine, the equivilent action would be to remove the disc image from the virtual drive. In practice, that might or might not be super convenient to do. However, you might also need to adjust the virtual machine's configuration so that it doesn't try to boot from the same disc image. (Details may vary based on which virtual machine you're using.) That might be easier, or somehow more sensible, to do when the virtual machine is not running. So the most preferable course of action might be to have the machine shut down, and then adjust the script file.

On the virtual machine:
# halt -p

With the OpenBSD install media, that might not shut down the machine, even though the same command would shut down the machine when the system boots the installed copy of OpenBSD.

(Speculated reasons may include ACPI being less supported, or APM being (also) less supported... e.g., in a normal boot, “dmesg | grep -i acpibtn” may show up, or “dmesg | grep -i apm” may show something.

# sysctl
hw.model=QEMU Virtual CPU version #.#.#
hw.product=Standard PC (i440FX + PIIX, 1996)

(This is the entire sysctl output of the installation disc, so the hw.allowpowerdown setting does not seem to even exist at this point.)

After running the halt command, the following output may be seen:

syncing disks... done

The operating system has halted.
Please press any key to reboot.

Please do not follow the polite instruction to press a key to reboot the virtual machine. (If that is done, the machine will boot off of the CD. That is not desired.) Instead, the virtual machine needs to be powered off.

If the system is unable to power off, then after the “syncing disks... done” kernel message is shown, just use the Qemu monitor to “quit” the emulator, or use some other method of adjusting running software to close the “virtual machine” program on the physical system, as a way to “power off” the virtual machine (by completely stopping the software).

On the physical machine:
Close VNC

(If you had any VNC sessions connected to the virtual machine, but then shut down the virtual machine software, then the VNC software may show an error message. You might choose to close such software. Acknowledge the dialog box, which will complete the process of closing of that instance of the VNC client software.)

Standard variable check
echo VMDirBas=${VMDirBas} VMGenNam=${VMGenNam} VMLILNAM=${VMLILNAM}

The exact details will vary based on which virtual machine software is being used.

If using Qemu
ls -l ${VMDirBas}/execbin/${VMGenNam}/${VMLILNAM}/sysstart/exc_${VMLILNAM}

If the script file was created as root, then a non-root user might not have access to edit the file. In that case, use sudo, as shown in the next example. Edit the text file:

sudoedit ${VMDirBas}/execbin/${VMGenNam}/${VMLILNAM}/sysstart/exc_${VMLILNAM}

Find: -boot d

[ "X${VMOptBtD}" = "X" ]&&VMOptBtD=" -boot d "
# Boot secondary master, often CD-ROM but could be a hard drive

Change to: -boot c

[ "X${VMOptBtD}" = "X" ]&&VMOptBtD=" -boot c "
# Boot secondary master, often CD-ROM but could be a hard drive
Removing the optical disc

If the operating system CD is likely to remain useful, then maybe just leave it there for now. There may be some content on an operating system CD that may be useful to install after the main operating system installation. Some operating system discs have come with some software that is intended to be installed, or somehow used, after the operating system is installed. Many people have simply missed out on some good and helpful software offerings because they did not use some of the software that comes on the operating system's installation disc. Some examples from some older Microsoft Windows operating systems (XP and 98) are mentioned at: Software on installation disc: post-installation. (Even users of newer operating systems are recommended to check out that list, to become familiar with some of the features that are known to show up on operating system discs.)

Some of this software may also be obtainable by downloading software from the operating system vendor (Microsoft), and the downloadable software may even be a newer version than what comes on the CD. Some software may not fit that description, so keeping the disc accessible may be handy.

In other cases, an optical disc may have simply provided a way to conveniently start the operating system's installation. For an operating system installer that downloads most of the operating system from a network, the disc may contain very little content, and might clearly have no further expected usefulness.

If it is strongly believed that the operating system CD should not have any further use (such as if the operating system CD has no real purpose except for initiate an operating system installation), then remove the reference to the image. That way, the operating system CD image is not required for the Qemu software to start this virtual machine.

To do remove the optical disc: “ -cdrom /somepath/filename.iso ”, and simply remove that reference. (Then, in a multi-line script file, there is no need to leave a backslash on a line by itself. You can just erase the entire line if it contains just a backslash. Alternatively, if you're familiar with how to “comment out” the line, you can do that.) (Details on how to comment out a line are covered later at #qmusrmcd ; those details may go to a unique page, and then be hyperlinked to, from here.) (Those details are outdated...

Verify usability

Typically this test just takes a short time; maybe a few minutes. If there is some major problem with the operating system, or the user account (such as if the password was entered incorrectly (usually twice) or if the password simply got lost somehow, already), then these show-stopping situations must be corrected before the contents of the disk image are really going to be significantly useful in any way.

Verify that the system boots up, and that you can log in.

Compress disk image

This is not necessarily recommended, at this time. However, directions are provided here so that people can perform this step, at this time, if they so desire.


At this point, some people might wish to make a backup of the drive. Actually, this guide mentions this again later, after making a few more changes. Backing up a drive with less customizations, like setting up networking and ensuring that a new user account can gain superuser permissions, means that the backup ends up being a copy that is less customized. Some people may like to get that backup before things are customized, feeling like the drive is still in a “more original” state. Of course, anyone who starts to use that backed up copy will probably begin by performing some of the common, early customizations.

For anyone who wants a copy of the hard drive right after installing the operating system, directions for doing so are available:

ACTUALLY, these directions appear to be outdated. Please just skip them for now...

Secure the operating system

If there are any concerns about allowing the system to receive network traffic, such as having vulnerable services being automatically started by default, then fix those problems.

Note: this does not mean adjusting user accounts. That also should be done, but is described in the next section.

Then, the next section of the guide describes check network connections (including when the computer has software that is simply “listening” for new connections, even if there are no active connections). So, continuing on with this guide will help with that.