From XastirWiki
Jump to: navigation, search

Installing Xastir on a Windows System using VMware Player


Introduction

To install Xastir on a Windows machine, you will need several pieces of software. They are all FREE! This method of getting Xastir to work on a Windows system is easy to set-up and does not require emulators like Cygwin.

If you work for an employer of any size, chances are they are using VMware to “virtualize” their servers to make them more efficient and productive. 80% of the Fortune 100 companies are using VMware so the software is proven and reliable.

When you install VMware player on your current Windows system, you create a virtualization layer between the new operating system and the computer hardware. So, should Linux crash, hang, etc., it does not effect the Windows system at all. There is probably a slim chance of Linux crashing – it’s more probable that Windows will crash for some reason unrelated to VMware, Xastir, or the Linux Operating System.


Overview

Getting xastir running with vmware can be quick and easy. At this time there are two choices to make: run a pre-built virtual machine, or get a generic virtual machine and build xastir in it. This wiki tries to describe both methods. Here is the process for each, painted in the broadest strokes. You have to pick through the rest of the document to flesh out the details. If you're in a real hurry and want something that works right now then the pre-built virtual machine is probably your best bet. The generic virtual machine method requires more set-up, but is more flexible.

Quick start with pre-built virtual machine

  1. Install VMware player
  2. Run VMware player and accept its license agreement. This will create a folder called "My Virtual Machines" in your My Documents folder.
  3. Download the pre-built virtual machine from the sites listed below. Extract the zipfile into your My Virtual Machines folder. This will create a folder called "Xastir-basic" in your My Virtual Machines folder.
  4. Launch VMware Player. When it asks you what virtual machine to run, point it at the file "Xastir-basic" that is inside your "My Documents->My Virtual Machines->Xastir-basic" folder.
  5. Log in. The user ID and password are both "xubuntu", which you can remember because it appears on the login screen. This was meant to be easy, not secure.
  6. Read the "Getting Started" document that you'll see on the desktop. It explains how to start Xastir and how to get set up to use an internet server to get APRS data.
  7. Define other interfaces as needed.
  8. Run xastir.
  9. Read the rest of this document to fine-tune your set-up.

Quick start with a generic virtual machine

  1. Install VMware player
  2. Run VMware player and accept its license agreement. This will create a folder called "My Virtual Machines" in your My Documents folder.
  3. Download a generic Linux virtual machine from the VMware site. We recommend one of the Ubuntu virtual machines, especially the "Kubuntu" distribution. Extract it into your My Virtual Machines folder.
  4. Launch VMware Player. When it asks you what virtual machine to run, point it at the file you installed in your "My Documents->My Virtual Machines" folder.
  5. Log in.
  6. Follow the installation instructions for Xastir on the version of Linux that you installed. See the various HowTo's on this site to find them.
  7. Set up your interfaces.
  8. Run xastir.
  9. Read the rest of this document to fine-tune your set-up.



Installing the VMware Player

Obtaining VMware player

Go to the VMware web site and click the "Download" link at the top of the page. Navigate down the downloads page to find VMware player. You will have to register to get to the download page, but the registration is free and they don't bother you with email. They just want to keep track of who is using their software and how.

Note that even though VMware player is free, you cannot freely redistribute it. You can distribute an open source virtual appliance, but you cannot bundle the player with it unless you obtain written permission from VMware. If you create virtual machines for others to use, you can just ask the users to go to VMware's website and get the player themselves, as we're doing here..

Other VMware products

VMware player has no capabilities for editing virtual machines. The only parameters of a virtual machine you can change in vmware player are the amount of memory it can take up, and whether the various virtual devices (serial port, CD ROM, ethernet, audio) are connected or not. That should be sufficient for most casual users, but if you intend to do more complex work with virtual machines (such as creating a pre-made virtual appliance for others to use), VMware player isn't the tool of choice.

In order to change more than that, you need to use a different VMware product. There are two products of note:

  • VMware Workstation
  • VMware Server

VMware Server is also a free product and can be downloaded from the same site as VMware Player, but you have to obtain a free registration key for it. It is intended for a different purpose than the player, but can create and edit virtual machines as well as run them. At this time, nobody in the Xastir community has tried to use this version, but when that changes the wiki should be updated.

VMware Workstation is not a free product, it costs about $190-$200 depending on how you want it. For the lower cost, you download the program and then apply and pay for a registration key to unlock it. The higher cost product is a package with a CD and printed manual --- but beware, the CD contains a slightly older version of the product and you still have to download the newer version. What you're paying extra for is the very comprehensive printed manual. This is the version that one of the authors of this page (KM5VY) used to generate the Xastir virtual appliance, to be described later in the document.

Installing the player

Since it is a Windows .exe (executable) file, after you download the file, click on the file and install it according to the prompts.

It will install very easily. You should run the VMware player application once to get it set up --- it will create a folder called "My Virtual Machines" in your "My Documents" folder after you've accepted the End User License Agreement.

Install a virtual machine

Once installed, the next thing to do is get a virtual machine to run in it. You have several options here.

  • Install a specially-built virtual machine with xastir already installed
  • Install a generic linux virtual machine and build Xastir in it.

These two options are detailed in the two subsections below.

Install a pre-built xastir virtual machine

KM5VY has used VMware Workstation to construct a complete virtual machine with Xastir already built and installed in it, in a configuration that provides a virtual serial port to connect directly to serial TNCs, and a NAT connection that should allow use of internet servers. Thanks to Jason Winningham (KG4WSV), Gerry Creager (N5JXS), Bob Donnell (KD7NM), Tom Hayward (KD7LXL) and John Ronan (EI7IG) this virtual machine is available for download. Note that this is a huge download, over 700MB, and is available via FTP or HTTP.

For most efficient distribution, please pick a site that is geographically close to you. If you can provide download space for an additional download site, please contact KM5VY per his QRZ listing or on the Xastir mailing list.

For a while, Lee Bengston was updating this original Xastir virtual machine, but at the moment nobody is doing so. You may still be able to use the older version, which is getting pretty long in the tooth.

Xubuntu Hardy updated 3/7/2009 (Xastir-Hardy_090307.zip):

The older virtual machine is still available at numerous download sites:

Xubuntu Hardy updated 7/29/2008 (Xastir-Hardy_080729.zip):


NOTE: If you downloaded an older version of the Xastir-Hardy file, Xastir-Hardy_080516.zip, please note that shortly after VM was created, several errors were found in its set-up. These are easily fixed. Please see Fixing the Xastir-Hardy VM. If you don't want to bother with the fixes, simply download the updated version above in which the problems were fixed. If you haven't downloaded a VM yet, grab the newer version above that was updated on 7/29/08.

This file should be unzipped into your My Virtual Machines folder (it lives under My Documents). Just use WinZip or any other unzipper to extract the folder. When you're done, it should have created a folder called "Xastir-Hardy" under your My Virtual Machines folder.

Please note: The virtual machine in this zip file was created on 29 July 2008, and by the time you download it it might be somewhat behind the times. You should definitely update the system according to the instructions in the section Get Operating System Updates soon after you are up and running. Furthermore, the version of xastir might similarly be outdated by the time you download the file, and you should also update it by following the instructions in the section Updating xastir as soon as possible after you've got everything working.

This virtual machine provides a version of xastir that has been built with all optional libraries except festival, has all development headers and libraries needed to build Xastir, and a Git checkout of Xastir's source code so that you can keep Xastir up-to-date with little effort.

This virtual machine uses the "Xubuntu" linux distribution http://www.xubuntu.com/. Xubuntu is a somewhat minimalist version of Ubuntu that uses the Xfce desktop environment instead of the more popular Gnome or KDE desktops provided by Ubuntu and Kubuntu. This distribution is particularly targeted at bringing a useful Linux desktop environment to users of old, slow computers with very little memory --- and since VMware makes your regular computer share its resources with the virtual machine, this seemed an appropriate choice.

If you downloaded the virtual machine prior to 22 March 2007, you have something else important to update: the original version of the virtual machine was set up to use the "lesstif" widget library, which has since been shown to have some serious bugs that can lead to xastir crashing. Once you've got everything working, please go to the page HowTo:Ubuntu 6.10 and follow the instructions in the section Switching to OpenMotif. You need only take this step if you downloaded the older virtual machine that was linked to from this page prior to 22 March 2007. The newer version has this taken care of already.

If you downloaded the virtual machine prior to 11 June 2008, it is the Ubuntu 6.10, or Ubuntu 7.04 version, and you might consider upgrading to the newer machine, either by downloading a new one or following the upgrade instructions later on this page.

Install a generic linux distribution

If you are interested in getting a complete linux system and using it to build and run xastir, this is the approach for you.

Go to the the VMware website and look for the “virtual appliances.” That area of the VMware website can be found here:

http://www.vmware.com/vmtn/appliances/

Go down to the bottom of the screen and locate the link to “Operating Systems.”

Look for the the Linux Operating System of your choice. I have used and tested Ubuntu and Kubuntu. The only real difference between the two is that Ubuntu uses the Gnome desktop and Kubuntu uses the KDE desktop. I prefer Kubuntu because it looks and feels more like a Windows environment. Sometimes you may even find multiple listings for Ubuntu and Kubuntu. They are usually similar, it just means a different person created the “virtual appliance.” When you click on the particular “appliance” you are interested in downloading, make note of the default user name and passwords – you’ll need those later.

For instance, on the appliances I download, for Ubuntu, the user was “ubuntu” and the password was “ubuntu.” Same thing for Kubuntu in that the user is “kubuntu” and the password is “kubuntu” – difficult to remember ;-)

I would also suggest, that if you have never been a Linux user, find the downloads for Ubuntu and Kubuntu that say version 6.06LTS or just 6.06 – anything 6.06 will work fine.

You have to download these virtual appliances as torrents. This is the longest part of the process. These virtual appliances are full Linux Operating Systems. Usually over 600MBs so the download takes quite a while – especially since they are torrents. If you don’t know what a torrent is, or how to download a torrent file, do a Google search to learn more about it.

I let both Ubuntu and Kubuntu download overnight. The next morning both torrents downloaded as .rar files. Not knowing what a .rar file was, I did a search on the Internet and found out this was a compression scheme similar to a .zip file that we all mostly encounter.

Now I did not have a program to unzip a .rar file (or would it be unrar a .rar file?) so I had to download that program and install it. The program I found and used was Winrar. It has a free trial period, so this is also a no cost item. You can download it here:

http://www.download-zone-free.com/winrar/

Go to the download button, click on it and install.

Now Winrar works just like Winzip. So find the .rar file(s) you downloaded using torrent, and unzip or unrar them to a directory. I set up a directory called “VMware Appliances” and then subdirectories of “Ubuntu” and “Kubuntu” to store each unzipped or unrared virtual appliance.

Now, the fun begins – and I really mean fun.

Starting Linux with VMware Player

Start the previously installed VMware Player. When it starts, it will ask you for the virtual appliance file you just unzipped/unrared. Navigate to the directory where you have these installed (you may only have one of course Ubuntu or Kubuntu). Click on the file, and the Linux booting process will start – well almost. When you are doing this for the first time, VMware Player is going to ask you a question that is something like "This virtual machine has moved, do you want to create a new UUID or keep the original?". Just choose the first one – “create” since this is the first time you are using this virtual appliance on your machine, and it will create a new unique identifier for your virtual machine.

Soon after booting, you will get the log-in screen. Now enter the user name (usually already there) and the password (remember, I told you to save those – usually ubuntu/ubuntu or kubuntu/kubuntu. If you are using the pre-built Xastir virtual machine described above, the user ID and password are both "xubuntu".

In a few short minutes, you will now have Linux running fully as a virtual system on your Windows system. VMware might tell you something to the effect that "This virtual machine has been moved" and ask you something about a "UUID." Choose "Create" to create a new machine id for this copy of the virtual machine if it does.

Note: In the pre-built Xastir VM, you will see two windows open: a terminal window and a VMware Tools window. Click the "close" button at the bottom right of the VMware tools window.

To navigate between Windows and Linux with the cursor, click anywhere in the VMware Player/Kubuntu/Ubuntu window. Now your cursor will only work in the Linux system. Control-G will also do this for you. Need to get out of the Linux system and go back to Windows? Control-Alt will do that for you. So you can easily go back and forth between Windows and Linux.

Adjusting the window size

Next, there may be a problem with your display. Your display may be “bigger” than the VMware Player window. You will need to adjust this and it depends on the size of your monitor. Mine is 1280x1024, but I still needed to adjust my display – Within Linux that is – not Windows.

In the pre-built Xastir machine

If you're using the very latest virtual machine (running Ubuntu Hardy/8.04) this section is no longer pertinent. That version of the virtual machine has new and improved VMware tools that automatically resize the desktop to your window size as soon as you log in.

If you are using an older virtual machine (with 6.10, 7.04, or 7.10) then you will need to manually resize the desktop upon logging in. Here's how: You should see a terminal window open. In this window, type: 

   sudo vmware-config-tools.pl

It will ask you if you want to change your display resolution. Type "yes", then choose the resolution you want by typing the number next to that resolution in the list that will be printed. You will then need to log off by clicking the little "open door" icon at the top right of the screen, and when the login box shows up again you need to restart the X server by typing "control-alt-backspace" (NOT control-alt-delete!). Log back in, and your VMware session will be at the new resolution.

In the Kubuntu version

If this is the case with your system, click on the VMware Player window, the scroll the horizontal and vertical window bars so that the K with a Gear (the equivalent of the Windows Start button) is at the bottom left hand corner.

Click on it once, and the menu appears. Go to system settings and then under Hardware, click on Display. To adjust the display, you will need to click on “administrator mode.” Adjust display to 800x600 or bigger if you have a big monitor. It will give you a preview. If it works for you, click accept. If not, try something else. Once that is completed, close that window.

Stopping the virtual machine

You should shut down the virtual machine by using the Linux shutdown command inside the virtual machine. Just quitting the player will leave the virtual machine's files in a "suspended" state as if you'd shut the lid of a laptop.

In the pre-built xastir virtual machine this is done by clicking the little "Open Door" icon in the top right corner, and then choosing "Quit", then by choosing "Shut Down" in the dialog box that pops up.

In the Kubuntu distribution, you would do this using the "K with a Gear" button.

Downloading and Installing Xastir

If you installed the pre-built Xastir virtual machine you can skip this section. You need to follow the instructions in this section only if you downloaded a generic Linux virtual appliance from the VMware web site.

The next item is to download and install Xastir. I am only going to give instructions for Kubuntu right now since there are two methods to do this with each Linux distribution. Adept is the installer for Kubuntu and Synaptic is the installer for Ubuntu. If you can follow along with Adept, you can probably figure it out with Synaptic in Ubuntu.

In the bottom left hand corner of the Kubuntu/VMware Player window, is a K with a Gear. That’s like the start button with Windows. One click on that and the menu will come up. Go to “System” and then over to “Adept.” Click on Adept to start the installer.

A small pop-up window will emerge and ask for a password. Use the previous “ubuntu” or “kubuntu” password. Once started, you may not see it come up in the window. Look down at the bottom and see if you see “Adept” in the task bar at the bottom. When you do, click on it, and Adept will fill your screen.

Near the top of the Adept installer, you will see a search box. Type in “xastir” (you do not have to hit return, it starts searching by itself). In the bottom left hand window, you should see “xastir” show up after being located. Click on “xastir” once and a more detail screen shows up. Click on “request install.”

Now go back up into the search box and type in “Imagem.” You should see a listing of applications come up in the bottom left hand window. See if “ImageMagick” says it is installed. If not, do the same thing – click on it to expand it, and then click on “request install.”

Next, go back to the search area and type “festival” to see if that is installed. If it is fine. If not, follow the same routine as above to request install.

Next and last, go to the search box and type “shapelib.” If it does not say it is installed, then expand it like before and click “request install.”

Now, you have all the packages you need to install and get Xastir working. So now go up to the top of the Adept window and click “Apply Changes” Now everything should start downloading and installing – automatically.

When everything has finished, the Adept screen should go back to looking like it did when you first brought up the application. Click on the blue X at the top right hand corner to close Adept.

Starting Xastir

Pre-built Xastir virtual machine

Double click the Xastir icon on the desktop, and xastir will start.

Note that there is a little "Getting Started" icon with some documentation in it available on the desktop, too. Please note that in the initial version of the document I mistakenly claimed that there are three skeletal interfaces set up. This is not true in the version I distributed, but rather a different VM I have to distribute to local folks. You'll have to set up your own interfaces in the version that is available for download. The getting started document will walk you through getting Xastir connected to an internet server, although it presupposes the existence of the skeletal Internet Server interface that isn't there. Create an internet server interface per the Xastir documentation in the Help Menu, and that should work.

Duffy's explanation below about how to get Xastir working with AGWPE will work if you set AGWPE up, or if you choose to use an Internet server or serial TNC you can do that, too.

Kubuntu-based virtual machine

Now the easy way to start Xastir. Go to the K start button. Click on it to bring up the menu. Go to System and then Konsole. When Konsole starts, type “xastir” and xastir will start as a little 1” by 1” box usually in the top left hand corner of the screen. Don’t know why it starts this way for the first time, it just does. Use the mouse/cursor to expand it like you would any window on Windows. There are other ways to start Xastir, but I will leave that for later.

When Xastir starts, there are a few things you need to do. Enter your call and coordinates and the Interfaces. I think you all can figure out how to do that on your own. However, to get Xastir to use the AGWPE application under Windows, use the IP address of the Windows system. To find out what that IP address is for the Windows system (assumes you have only one Ethernet card), go to the “C” prompt and type “ipconfig” and hit Return – the IP address of the Ethernet card should be display. Use that in Xastir when setting up the interface to AGWPE.

This looks like a long process, but it really is not. Except for the download of the virtual appliance (the Linux Operating System), it really goes very quickly.

Good Luck and let me know how you make out.

Duffy www.wb8nut.com

Defining your interfaces

There are several ways to get set up so that Xastir will be able to communicate. One method, advocated by Duffy (WB8NUT) is to set up AGWPE on your windows machine, and let xastir communicate only with the AGWPE server. This is certainly a good option, but is not strictly necessary. Another method is to set up your virtual machine so that it can access virtual serial ports. This can easily be done with VMWware Workstation or VMware Server. VMware player can do it if the virtual appliance you've got is already set up to probe for serial ports.

Installing AGWPE

The first thing you need to do is download AGWPE from SV2AGW's web site. Click the AGW Packet Engine link on the left of the page and follow the instructions from there. (There used to be a link directly to the AGWPE zip file on this Wiki page, but KM5VY changed it to a link to the SV2AGW page instead --- installing AGWPE requires a lot more than just unzipping the file, and the web site provides instructions that the zip file does not).

Unzip the program and install it. Configure it to work with your TNC. The advantage of using AGWPE between your APRS programs (windows or otherwise) is that it allows multiple programs to “talk” to the TNC at the same time. If you don’t have a TNC, AGWPE still works with most if not all sound card interfaces. Configure AGWPE.

Once AGWPE is installed and working, you can get Xastir to talk to it. See the documentation in Xastir's help menu for details.

Using virtual serial ports

If the virtual machine you intend to use has been set up to use virtual serial ports, you have several additional possibilities.

If your computer has real serial ports, you might luck out and find that the virtual machine detects the right one immediately, and you can just connect to it from the linux side using /dev/ttyS0 as if it were connected directly to linux. If so, you can set up regular TNCs according to Xastir's help files.

If your computer has no serial ports, you can purchase a USB <-> Serial adapter and use it. In testing this, KM5VY found that the most reliable way to get this working is to install the windows driver for the serial adapter and plug the serial adapter into the computer before starting the virtual machine. Doing so tricks the VMware player into thinking you have a real serial port, and it just works the same as if you did. According the the VMware documentation, it should be possible instead to plug the serial adapter into the computer while the virtual machine is running and let the virtual machine's drivers handle things. At this time this approach has not been seen to work properly, but more testing is necessary.

If you are unlucky, vmware player will autodetect your computer's modem as if it were a serial port, and connect the virtual machine's virtual port to that instead. There are several approaches to fixing that problem, the easiest of which is to disable the modem through Window's Device Manager before starting the virtual machine. The harder way is to tweak the virtual machine file manually. That approach is described later in this page, in the Troubleshooting and Enhancing sections.

Troubleshooting the pre-built Xastir virtual machine

Unfortunately, the first time I helped a Windows user install the pre-built virtual machine we encountered some unexpected problems.

Internet connection woes

Zone Alarm interacts in a fishy way with the NAT setup that the virtual machine uses. I did not have the same problem with Norton Internet Security. If you're running Zone Alarm, you will have to add the two VMware Virtual Adapters to the "Trusted" zone or the virtual machine will not be able to reach the internet. Zone Alarm should show the two VMware virtual adapters immediately after you install the player --- please add the adapters to the trusted zone BEFORE booting the virtual machine, because they have to work at boot time in order to get to the internet.

The virtual machine uses a NAT device (Network Address Translation) to set up a virtual network inside your computer that uses your computer's internet connection to get out to the internet, and it does so by using the same IP address that your machine has. To your computer, it looks like there is an ethernet card that communicates with the virtual machine, and your computer acts as a router. If you don't add the VMware virtual adapter to Zone Alarm, then it will refuse to route packets between the virtual machine and the internet.

The "Getting Started" document has a link to the Xastir web site in it for you to click to double check that your internet connection is working properly from the virtual machine. Please check your internet connection to the virtual machine before trying to set Xastir up to use an internet server! If you can't get to the Xastir home page from the getting started document, check Zone Alarm, and take other steps to diagnose the issue before taking the next step.

Troubleshooting serial port problems

The pre-built virtual machine has a single virtual serial port, and that port is set to "autodetect" serial ports on your computer. Unfortunately, it doesn't always seem to find the right serial port.

If your computer has more than one serial port, make sure that the virtual machine connects to the right one. In the virtual machine's folder, look for a notepad file called "vmware" and open it in notepad. It is the log of what the virtual machine did while booting. Scan for where it detects the serial port, and check that COM1 or COM2 or whatever is the one that is connected.

Enhancing and changing the pre-built virtual machine

The pre-built xastir virtual machine is a complete, usable linux system with a simple desktop environment and a pre-built version of xastir on it. It is usable as-is immediately, and should perform reasonably well even on old, slow, memory-poor computers running Windows. But there are many ways that you might want to change it to make it suit your needs better. Here are a few suggestions for ways to enhance it.

Fixing the Xastir-Hardy VM

Several minor issues were detected in the Xastir-Hardy virtual machine released in May of 2008. They were fixed in the version that was released in July of 2008 If you downloaded the version from May of 2008 and don't want to download the new one, you can fix these flaws yourself. These errors interfere with using the Map Caching feature, updating Xastir, and possibly networking. If you downloaded the version called "Xastir-Hardy_080729.zip" these steps are unnecessary.

Fix permissions error in xastir directory

The version of xastir last built in the virtual machine was accidentally built as superuser, so the files in it cannot be modified by you until the permissions error is fixed. Just do this: 

 cd ~/src/XASTIR
 sudo chown -R xubuntu:xubuntu .

The last command will prompt you for your password (the same one that you used to log in).

Fix Map Caching

There is a mismatch between the header and library files for Berkeley DB. To fix this, issue the following commands: 

 sudo apt-get remove libdb4.5-dev
 sudo apt-get install libdb4.6-dev

You will then need to rebuild xastir. 

 cd ~/src/XASTIR/build
 make clean
 ../xastir/configure
 make && sudo make install

The final command will prompt you for your password (the same one you used to log in.)

Getting networking started

Sometimes the network manager does not automatically detect and initialize the virtual network as it should. This is not a problem for every user --- if networking works out of the box for you, then it ain't broke, so don't try to fix it. Only if you find network manager not automatically connecting should you bother with this section. There are two approaches to fixing this.

If your virtual machine shows that there is no network enabled (there is a red "x" over the icon of two computer terminals in the top right of the menu bar), then you can click that icon and choose "wired network." Do this even if your real network connection is a wireless card --- VMware doesn't know that, and thinks the virtual machine has a wired connection to the network regardless.

If you find that you have to re-establish this connection manually every time you start the virtual machine, you can disable the automatic connection through network manager and use a manual connection instead. To do this, click on the network manager icon (the icon of two computers in the top right menu bar) and choose "Manual Configuration." This will bring up a window with network configuration options. Click the "Unlock" button and enter your password when requested. Then click on "Wired Connection" and then "Properties." In the properties dialog box, click the "Enable roaming mode" to turn off the check box, and then choose "Automatic Configuration(DHCP)". Click "OK" and from this point forward networking will automatically be connected.

Get Operating System Updates

From time to time you should check to see if there are important updates to the OS. These can be security updates, bug fixes, or enhancements. Getting updates requires that your system be hooked up to the internet, and that your virtual machine can access the internet. See the troubleshooting section if the VM can't get to the internet.

In the Applications menu, choose the System menu and then the "Update Manager." Check for updates, review the changes they include, and then install them.

It's not a great idea to let this slide for very long. Keep your system patched for security and stability. You might even want to enable automatic updating in the update manager.

Note: Ubuntu 8.04, "Hardy Heron" was released in April of 2008. The latest virtual pre-installed virtual machine uses this version of Ubuntu. If you downloaded the virtual machine prior to 11 June 2008, you got an older version of Ubuntu.

The upgrade of Xubuntu is sufficiently complex that we do not recommend upgrading it yourself. It is necessary to make modifications to the VMware tools installation, and the upgrade is simply too involved to describe on the wiki. Please download the updated virtual machine instead.

Change the memory allocation

The pre-built xastir virtual machine is set up to act like a computer with a mere 256MB of RAM. The intent was to make a virtual machine that would run on even the most memory-deprived computer, but if you have tons of extra memory and find tha the virtual machine is having trouble fitting in that 256MB, you can change the allocation through vmware player. Simply pull down the "Player" menu, choose "Troubleshooting" and then "Change memory allocation." Set it somewhere between the minimum and maximum recommended values, and away you go. Try not to pick allocations that are too big, or you might find your Windows machine thrashing trying to satisfy the memory needs of your virtual machine and Windows at the same time.

Copy files from your Windows folders to your virtual machine

Note While VMware tools and VMware do support copy/paste between host and guest machines, it turns out that this feature does NOT work between Windows and Xubuntu, despite early claims by KM5VY here and on the Xastir mailing list that it would work. We're trying to figure out why, but for the moment you still have to jump through hoops to get files transferred between Windows host and Linux guest.

Until drag-and-drop and copy-and-paste work, there are two ways to copy files from regular Windows folders to your virtual machine. It is not particularly straightforward, because the whole virtual machine runs off of a fake hard drive simulated by a set of files that make up a "virtual hard drive" --- you can't just drag and drop files from windows to the virtual machine. VMware does support drag-and-drop between host and guest operating systems, but only when both host and guest are Windows! So you have to be a little tricky. The first way is the easiest for occasional transfers, the second is the easier for regular transferring.

The main reason you might want to transfer files like this is if you already had a Cygwin install of xastir with a bunch of maps, and wanted to transfer those maps to the new virtual machine instead. That is the exact application a friend needed that inspired me to figure out how to do this stuff.

Using a USB removable drive

The pre-build xastir Xubuntu virtual machine is actually set up so that you can plug in a USB flash drive (or even a USB hard drive) while the virtual machine is active (i.e. you've hit "Control-G" or clicked in the window) and the virtual machine will see it instead of windows. So to copy a file from windows to linux via a thumb-drive, you'd do this:

  • If your virtual machine is active, hit Control-Alt to return control of the mouse to Windows
  • Plug in your thumb drive. Windows should see it, and you should be able to drag and drop files into it.
  • Use the taskbar tool to eject the thumb drive. You can leave it in the usb port --- just make sure windows thinks it's safe to remove.
  • Look at the title bar of your virtual machine. You should see that a new button is there referring to your USB drive. Click that button. You might have to wait a few seconds for anything to happen. If you're impatient and want to see that it's actually doing something, you can type "tail -f /var/log/messages" in a terminal window --- you should see messages scrolling by as the system detects and mounts your USB drive. This is also where you'd see if it's having trouble and failing to do so.
  • After a little pause, your USB drive should now show up on the Linux desktop. Right-click that and choose "Mount Volume"
  • Double click the drive icon on the Linux desktop. It should open a Thunar File Manager window that shows the files you have on your USB drive.You should now be able to use the Thunar File Manager to copy files off the thumb drive and into your Linux directories. You could also use the command line --- the new drive will be mounted under the "/media" directory. For example, when I plug in my FIRELITE SmartDisk, it's mounted as /media/FIRELITE, so I could do things like: 
 sudo cp /media/FIRELITE/*  /usr/local/share/xastir/maps/new_maps/
  • To return control of your USB drive to windows, right-click on the drive icon in Linux, choose "Unmount Volume", then click the button in the title bar of the virtual machine so it's unhighlighted. Windows will now act as if you've just plugged the device back in, and will attach it again.
  • In order to remove the device completely from your computer, you must use the "Unplug or Eject Hardware" in Windows again --- remember that Windows thinks you reinserted it as soon as Linux let go of it.

You can only use the USB device from one side of vmware at a time. In order to use it in linux, you have to tell Windows to "Unplug or Eject" it first, and in order to use it in Windows you have to make sure it's "unmounted" from linux and the button in the title bar is unhighlighted.


Getting the Xubuntu virtual machine to access your windows shares

This is a way to make a longer-term way to transfer files back and forth between your Linux virtual machine and Windows. Use this method if you have to do this sort of thing a lot. Use the USB method above if you don't need this sort of constant interaction between Windows and Linux.

This is still only preliminary documentation, and applies specifically to the Xubuntu xastir virtual machine

Because the virtual machine thinks it has a whole machine to itself, it doesn't know your windows machine exists, except through the virtual ethernet "card." If you want to be able to copy files from your windows computer to the "linux computer" you have to do it with Windows shares.

This is not true if you have VMware Workstation, and might not be true for VMware Server.' VMware Workstation will allow you to share a folder without using a windows share, and you don't have to install any special software in the linux virtual machine to use them. Duffy: Please update this section if this is also the case for VMware Server. But if you're only using VMware player, read on.

To share a folder between your windows machine and the linux virtual machine, you first need to enable sharing of that folder on the windows side. You then need to install some additional software in the virtual machine. I recommend the "linneighborhood" software, because it has a nice graphical interface, but you can also do it with the "smbclient" tool if you're comfortable with command line interfaces. I'm only going to describe the linneighborhood method. Here's how to do it. You need to be connected to the internet for this installation to work.

Note: In recent versions of Ubuntu, "linneighborhood" has been replaced by a newly rewritten version called "pyneighborhood." It works exactly the same way, so if you have a later version of Ubuntu (e.g. Hardy), then just use "pyNeighborhood" everywhere where this text mentions "linneighborhood."


In the top left menu bar, find the "Synaptic Package Manager" --- it should be in the system menu. Open this, enter the password for the user you're logged in as, and when the package manager starts up click the "Search" button. Enter "linneighborhood" and wait till it shows you a list of matching packages. Click the little box next to "linneighborhood" and choose "mark for installation." Then click the little "Apply" button near the top of the dialog box. It will then download and install linneighborhood and the other packages it depends on. This is a small download and won't take long even on a dial-up connection.

Once it's finished, exit the package manager.

At this point, you can run the program: 

  sudo LinNeighborhood

You can now use this tool to connect to your windows computer. I have only done this once, there might be an easier way, but at this point I found I needed to click the "Add" button to tell LinNeighborhood the name of my windows computer. Once you have your computer's name in the list of local computers in LinNeighborhood, you can right click on the computer's name and choose "Scan as user" --- enter the username and password you use on windows, and LinNeighborhood should show you all the shares that that user has access to on that computer. Click on the share you want to access from Linux and choose the "Mount" option. This will make that share appear as a directory under /root/mnt. That is, if you have a share on your windows machine called "MyShare" and mount it in this way, you can find it on your linux virtual machine as a directory called "/root/mnt/MyShare/" --- you can then use either the Thunar File Manager or command line tools to copy files from that directory.

Adding Maps

The easiest way to add maps to the virtual machine is to download them using ftp or firefox within the virtual machine. If you have existing maps (say from a previous Cygwin install of Xastir), or download them using windows tools outside of the virtual machine then you have to use the windows share or removable drive methods above.

All of the maps xastir uses are stored in /usr/local/share/xastir/maps and directories below those. To add new maps, you must copy them here. See the file /usr/local/share/doc/xastir/README.MAPS for more information about getting and installing maps for xastir to use.

Make sure that your new maps have the proper permissions set, otherwise Xastir will not be able to find them. 

 sudo chmod -R a+rX /usr/local/share/xastir/maps

will set the permissions for all files in the maps directory and all sub-directories.

Change the desktop environment

The Xubuntu distribution was deliberately chosen for its small size and lightweight desktop environment --- it should run very nicely even on old computers under vmware. And if all you ever plan to use it for is to run xastir, it should be sufficient. But if you're Jonesin' for a more elaborate environment like KDE or Gnome you have not been shut out of that experience. You simply have to do a little work to add your preferred desktop environment to the virtual machine's installation. Unfortunately, there are some issues that make it a little more difficult than it should be, but a clear step-by-step process is documented in this article on the Ubuntu forums web site. Duffy prefers the KDE desktop since it provides what seems to him a more Windows-like environment. According to the article mentioned previously, installing the KDE desktop on top of an Xubuntu install is easier than installing Gnome --- in the article KDE install is referred to as installing the "Kubuntu desktop" and the Gnome install is referred to as the "Ubuntu-desktop".

Adding virtual devices to the virtual machine

The virtual machine was built to probe for and attach a single virtual serial port --- this port can be a real serial port built into your computer, or a USB to Serial adapter already plugged into Windows. If you want more serial ports available to xastir, you have to modify the virtual machine.

The simplest way to modify the virtual machine is to do so in VMware Workstation or VMware Server. That means installing either a fairly costly piece of software, or a free, but fairly large piece of software. Either way, there is a simple GUI method for adding devices to an existing virtual machine.

If you're impatient, cheap, or otherwise don't want to install a big program just to change one simple thing: be aware that the virtual machine definition file is just a plain text file that you can edit and add other devices to. IF YOU ARE NOT CAREFUL YOU CAN RENDER YOUR VIRTUAL MACHINE UNUSABLE but if you are careful it is not difficult. Here's how to add a single serial port to the original pre-built VM.

The zip file you unpacked should have created a folder called "Xastir-basic" in your My Virtual Machines folder. In that folder is a file called Xastir-basic.vmx. This is the text file you need to edit. MAKE A BACKUP COPY OF THIS FILE NOW! (Note: In the newer virtual machine both files are called "Xastir-Feisty" instead.)

Open this file in notepad. Please do not open it in any other editor! It is particularly important that you not use Word or Wordpad. The file must remain a plain-text document, and editing with anything fancy will screw it up. Note also that if you open this file in notepad before you have ever booted the virtual machine, it'll all be one big line due to differences between Linux (where the machine was first built) and Windows. So boot the virtual machine at least once before attempting this procedure.

MAKE SURE THE VIRTUAL MACHINE IS "POWERED OFF" before making these changes. Doing these edits on the .vmx file while the machine is running will probably be a Bad Thing, and I have warned you.

Now look for three lines of text in the document: 

 serial0.present = "TRUE"
 serial0.fileName = "Auto detect"
 serial0.autodetect = "TRUE"

These are the lines that tell VMware that there is one serial port in the virtual machine, and to probe for it. Let's say you want to add a second virtual serial port, and want it always to be COM4, where your USB to Serial adapter will be. Simply add a few extra lines right after these: 

 serial1.present = "TRUE"
 serial1.filename = "COM4"
 serial1.autodetect = "FALSE"

You will now have two serial ports in your virtual machine. They will be called /dev/ttyS0 and /dev/ttyS1 to Linux.

If your virtual machine refuses to boot after this change, restore from your backup copy and try again.

Working around broken autodetection of serial ports

Earlier, I mentioned that sometimes VMware autodetects your modem as a serial port instead of the serial port you wanted to use. You can use the method I just described for adding a serial port and adapt it to make the machine always use exactly the port you want instead of trying to autodetect every time.

If your serial port is COM1 and you always want /dev/ttyS0 to be COM1, then just find the same three lines in your Xastir-basic.vmx (or Xastir-Feisty.vmx) file: 

 serial0.present = "TRUE"
 serial0.fileName = "Auto detect"
 serial0.autodetect = "TRUE"

and change them USING NOTEPAD, AFTER YOU'VE MADE A BACKUP to read: 

 serial0.present = "TRUE"
 serial0.fileName = "COM1"
 serial0.autodetect = "FALSE"

Now the virtual machine will boot up and attach exactly the device you specified instead of trying to figure it out.

Updating xastir

The pre-built xastir virtual machine has a full Git checkout version of xastir, and updating xastir to the latest-greatest is simple. Xastir's source code is under the home directory of the default user (xubuntu). All you need to do is navigate down to it and issue a few simple commands: 

 cd ~/src/XASTIR/xastir
 git pull
 ./bootstrap.sh
 cd ../build
 ../configure
 make && sudo make install

The "./bootstrap.sh" command is not always necessary, but until you know enough about how the Xastir build set-up works and how to tell when it is necessary, it's best to just go ahead and issue it every time. Skipping it when it is needed can lead to some annoying and confusing error messages. The last command will require you to type the password (which is also xubuntu). Your Xastir is now updated to the latest version from Git. If you want to save disk space, do a 

 make distclean

in the build directory.

Naturally, this will only work if your computer is connected to the internet, and your firewall is set up to allow the virtual machine to connect to the internet, too. By the time you get to this point of this document, you should already have seen how to test and troubleshoot that aspect of virtual machine usage.

For Further Reading

While we think the "Linux-in-a-virtual-machine" approach is far easier than the Cygwin approach go getting started with Xastir on a Windows machine, there are some things to be aware of.

First and foremost, remember that you are now running Xastir in a completely different operating system than the one with which you're familiar. Getting Xastir running this way will be fast and easy, but working effectively with your new set up might have a bit of a learning curve. If you're going to be trying anything fancy, eventually you're going to need to learn what Linux is all about and how to work with it.

I recommend getting yourself a book or two. One that I've just recently found is called "Ubuntu Linux for Non-Geeks." It is aimed directly at those who are starting to use Linux, but aren't already steeped in the geek culture of Linux. I'd recommend starting there, and expanding your horizons as you get more into it.

Feel free to edit this section and add more book and web site recommendations to it, so that our Windows users can get the maximum benefit out of the virtual machine option.

Retrieved from "http://xastir.org/index.php?title=HowTo:VMware&oldid=6142"