- Mac Os X
- System Requirements
- The FSL Virtual Machine
- FSLvm Installation
- VMware Workstation Player Usage and Configuration
- Accessing your Windows files
- Network access
- Shutting down
- Resetting a hung FSLvm
- Updating the FSLvm
- Increasing the amount of memory available to FSLvm
- Windows Subsystem for Linux
- Source Code
- Shell Setup
We recommend using a UNIX-based computer (such as a Linux PC or Apple OS X) for carrying out data analysis. However, if this is not available then you can use FSL on a Microsoft Windows computer by running the Linux version of FSL inside a "virtual Linux machine" (a VM), using a freely available program (free for non-commercial use only) called 'VMware Workstation Player' by VMware. This is fairly easy to setup, and we provide basic installation instructions below, but please note that we cannot in general offer further help for the setup and maintenance of the virtual machine itself - we just offer support on the running of FSL within it.
- Windows 7, 8 or 10 (32bit or 64bit)
- Dual core CPU (recommended minmum)
- 4GB RAM minimum (8GB+ recommended)
- Minimum 10GB, up to 75GB, of free disc space (VM image expands as necessary up to the 75GB limit)
The software package VMware Workstation Player emulates the core hardware of a PC allowing you to run a second operating system 'in a window'. Virtualisation technology allows the programs running in this VM to achieve speeds approaching that of programs running natively in Windows.
The FSL VM (FSLvm) is configured with 2GB of RAM, a virtual hard disk that can grow to 75GB in size, shared (NAT) networking (ie it shares the network connection of your local computer), virtual sound hardware and virtual CD/DVD drive.
Before you can run the FSL virtual machine, you need to install a Virtual Machine player package. We support the use of version 12+ of VMware's free* VMware Workstation Player software. Download the software from VMware's site and install this package by following VMware's instructions (or you can look at videos on youtube if you get stuck). Once it is installed and your computer has been restarted, launch VMware Workstation Player to complete initial setup.
* Workstation Player is free for non-commercial use. Academic users' institution must be a member of the VMWare Academic program to use this software for free. For details on the licensing arrangements see http://www.vmware.com/products/player/faqs.html
The FSL Virtual Machine
Once VMware Player is installed, download FSLvm from below. The FSLvm is compatible with Windows 7/8 and 10 and is 64 bit, so requires a 64 bit CPU. See http://kb.vmware.com/selfservice/microsites/search.do?language=en_US&cmd=displayKC&externalId=1003945 for information on how to check that your computer will be able to run the FSLvm.
Verifying the download
If you want to confirm that the FSLvm package has downloaded correctly please see this page.
FSLvm is a fairly minimal install of the CentOS 7 Linux distribution and is provided as a zip file. To install, decompress the downloaded FSLvm by double clicking on the zip file and clicking on Extract button in the Windows Explorer toolbar. Choose to extract all files, then choose a location to extract to. By default it will extract to a folder 'FSLVm7_64', remove this from the end of the expansion location so that an unnecessary 'FSLVm7_64' folder is not created.
VMware Workstation Player Usage and Configuration
Detailed VMware Workstation Player application usage instructions are available from the VMware Player menu's Help entry.
The installation of the FSL package requires an internet connection. Please ensure your computer has a working connection before continuing with the setup procedure.
Now that the FSLvm is installed, launch VMware Workstation Player from the Start menu and click on the Open icon. In the Open dialogue, browse to the uncompressed FSLvm folder, FSLVm7_64.vmware and double click on the FSLVm7_64 file within.
Subsequent to the initial launch, the FSLvm will appear in the list of Recent Virtual Machines allowing quick launching.
During the launch of a VM you may be prompted to download and upgrade the VMware Tools (updates for these appear periodically).
You should agree to this.
The first time FSLvm is started VMware Workstation Player will ask if the VM was moved or copied, choose I copied it (this sets up the network correctly).
Depending on your Windows computer's hardware, you may also receive additional messages about missing hardware. These can be dismissed.
The FSLvm will now boot, a process that may take several minutes.
Once the boot process has completed, you will be automatically logged into the account fsluser and the installation of FSL will begin. You will be prompted to choose a password for this account, make a note of this password as you will need it to use the 'sudo' command when you install FSL updates. Next FSL will be downloaded, installed and configured. Finally, the virtual machine will check for pending software updates, install them and reboot, please be patient this final step may take a while.
Recovering from a failed install If your computer loses it's network connection during the download phase the installer will quit. To restart the installation process run the command:
/usr/local/fsl_installer/fslinstaller.py You will be prompted for the account password you set during the initial phase of the install.
At this point the installation is complete. Read on if you want to find out how to modify the VM's settings to suit your keyboard layout, to enable file sharing and to increase the memory available to the VM.
The FSLvm is configured with a British keyboard; users with a different keyboard layout can change by clicking on the power symbol in the top right of the screen and clicking on the tools icon in the bottom left of the resulting window.
Click on the Region & Language icon in the settings window.
The Input Sources at the bottom of the window allow the addition of different keyboard layouts.
Accessing your Windows files
There are four options for transferring/accessing files stored on your Windows disk into the FSLvm, presented in order of ease of use:
The VMware Workstation Player application supports the dragging and dropping of files from Windows into the FSLvm. To transfer files select them in the Windows Explorer and then drag them into your FSLvm window and drop in the folder you would like it to reside in (or onto the Desktop). You may find that the first attempt to copy a file results in an error, click Retry which should complete. Subsequent drags/drops should then be fine.
- VMware Workstation Player file sharing
Before changing the sharing settings first create a folder to share. Put this folder somewhere appropriate in your home folder. To enable sharing and to point it to this new folder, start up the FSLvm and visit the VMware Workstation Player menu and open the Shared Folders... wizard. To enable sharing permanently select the Always Enabled radio button. Now select the pre-configured share and click on the Properties button. This will open another dialogue box allowing you to change the name the share will appear as in Linux and to change the Windows file path for the shared folder. Click on the Browse button and locate the folder you created earlier. Click on the OK buttons to dismiss the dialogues. You may now access files held within this shared folder through the path /mnt/hgfs. To navigate there through the graphical file browser, double click on Home on the desktop and then, in the resulting window, click on Computer. This will open a folder showing the folder / from where you can navigate to mnt and then hgfs. Within here will be the shared folder, named as specified in the Shared Folders dialogue. See below for help if the shared folders function stops working.
Do not attempt to modify the same files in this shared folder in both operating systems at once - bad things will happen!
- Using external media: If you connect a USB storage device whilst VMware Workstation Player is running and has the input focus it will allow Linux to see the storage device. In most cases it will automatically mount and an icon will appear on the Linux desktop. Linux has read-only support for NTFS, so you will need to create an ext4 (Linux support only) disk partition or use FAT32 format which can be read on both OSes.
FAT32 is not supported for storing files that you are actively accessing with the FSL tools and has a maximum file size of 4GB. The newer ExFAT format which does not suffer from these limitations can be supported by installing third-party tools. Search Google for ExFAT Centos 7.
The FSLvm is configured to share your network connection, and so has full access to any networks that your Windows computer can see. You can also access your FSLvm from Windows over this internal network with tools like puTTY (a SSH terminal client).
To identify the IP address of the FSLvm, in a terminal in the FSLvm type:
/sbin/ifconfig | grep -C 1 'eth0'
You are looking for the dotted quartet printed after inet addr:.
Connection to the host is now possible using this address as the hostname to connect to within puTTY.
Under normal circumstances you should just close the FSLvm window, this will suspend the FSLvm to disk allowing quick restoration of your session at a later date. However, sometimes it may be necessary to shutdown the FSLvm entirely (say if you are moving it to a new computer). To do this, click on the power icon in the top right of the desktop menu bar, click on the power icon (bottom left) and choose Shutdown. Once Linux has shut down VMware Workstation Player will exit.
Resetting a hung FSLvm
If the FSLvm appears to have frozen, you can force a reset by selecting Reset from the Troubleshooting menu.
Updating the FSLvm
From time to time the Linux vendor will issue security updates which in general should be installed to keep the FSLvm secure.
When updates are available a message window will appear in the top right of the Linux desktop advising you of what updated packages are available. Clicking on the icon associated with this message will open the package update utility which can be used to update the system. You will be asked for the root password that you set when installing the FSLvm before being allowed to install these updates.
Updating VMware Tools
If you find that the shared folder functionality stops working then you will need to update the VMware tools, to do this follow these instructions.
To update the tools choose Manage > Reinstall VMware Tools from the VMware Workstation Player menu, wait 30 seconds then open a terminal window in the FSLvm. Within this window type:
cd /tmp tar xf /media/VMware\ Tools/VMwareTools-*.tar.gz cd vmware-tools-distrib sudo ./vmware-config-tools.pl
Enter your account password when requested.
You will now be asked a series of questions. Hit return to accept the default to all of the questions. Once the installation is complete you should reboot the FSLvm to allow the changes to take effect.
Increasing the amount of memory available to FSLvm
Right click on My Computer in the Start menu and select Properties... the window that opens will tell you how much your computer has. The default allocation of 2GB is only suitable for light use of the FSL software suite. For more demanding analyses you will need to increase the amount of available memory allocated to the virtual machine. Before you change this setting you should find out how much memory your computer has.
With this in mind, you can calculate the amount of memory you can safely allocate to the FSLvm by following the advice below.
Take 2048MB off the value reported
Take 4096MB off the value reported
By way of example if you have a Windows 7 computer with 8GB of RAM you can safely increase the FSLvm memory allocation to 6GB.
To change the memory allocation of FSLvm, start the VM and then from the VMware Player menu, choose Manage > Virtual Machine Settings.... In the dialogue that opens type the value you have calculated as being optimal into the memory total box - the memory section will suggest some values for you. As indicated in this window once you have clicked OK you will need to restart the VM.
Increasing the size of the virtual disk is also possible, but not straightforward, so if you require additional disk space we would recommend adding an additional USB hard drive to your system and dedicating it's use to Linux. For correct FSL operation, the drive should be formatted with the Linux ext3 filesystem. Follow these steps to carry out this formatting process.
- Start with the drive disconnected
- Click inside the running VM window so that you are controlling Linux
- Connect the USB drive
If the drive mounts and appears on your Linux desktop, right click and choose to un-mount it. Most probably you will have a drive formatted as NTFS, so you may see this warning that Linux Cannot mount volume - Click OK. Unfortunately, Centos won't let you format the device at this point, so you need to format via the command line.
- Open a terminal and become the root user:
- (enter the root password when prompted)
Potential for data loss
The next step will destroy everything on the drive you specify, so make sure you are certain that this is the correct disk.
- Run the partitioning tool:
- You are now in an interactive partition editor.
- Find your disk:
Locate your external drive (look for the Model: entry that matches your disk) and note down the Disk field (/dev/sdX) (this will probably be /dev/sdb) and the numbers of any existing partition number(s)
- (replace X with the letter you determined above)
- where Y is the partition number you noted. Repeat until you have deleted all the partitions on the disk
- to confirm that they are all gone
mkpart primary 1 ZGB
- where Z is the size of the disk in question (eg 250GB), hit return to any prompts
- Make a file system on the partition
mkfs -t ext4 /dev/sdX
- (X as above)
Disconnect the drive and reconnect it and it should automatically mount. Open Computer on your desktop and you should see the drive, and it can be accessed at /media/disk (or some variant on that).
Windows Subsystem for Linux
FSL can be installed into the Windows Subsystem for Linux, although this is currently an experimental option
- Follow the directions here to install the Ubuntu subsystem in Windows
- Install XMING (in Windows) from here
- In an Ubuntu shell window:
sudo apt update sudo apt -y upgrade sudo apt-get install python mesa-utils gedit pulseaudio
- use windows browser to get the installer script as normal
- run downloaded script in Ubuntu shell via
python /mnt/c/path/to/fslinstaller.pyWhere /path/to/ is replaced with the windows 10 location of the installer script. Say yes to all default install options
- In ubuntu shell add
echo "export DISPLAY=localhost:0.0" >> ~/.bashrc
- try running fslmaths, fsl, fsleyes
If fsleyes doesn't start with a message referring to: libgtk-x11-2.0.so.0, then you will need to run:
sudo apt-get install libgtk2.0-0
- It might be worth trying
sudo apt-get install firefoxto get native browser support ( also can link to firefox.exe )
- If you want to mount other folders or drives ( e.g USB drives)
sudo mkdir /mnt/<usb>
<usb> can be whatever you want to call this new link
sudo mount -t drvfs <Letter of USB drive in Windows or path to some other subfolder> /mnt/<usb>e.g. if your USB drive appears as drive E:
sudo mount -t drvfs E: /mnt/<usb>the mount command will need to be rerun each time you start a new WSL session: the mount is safely unmounted when the last window of a WSL is closed.