Introduction

We recommend using a UNIX-based computer (such as a Linux PC or Apple OS X) for carrying out data analysis. However FSL can be used on Windows via the Windows Subsystem for Linux (WSL, Windows 10 only, recommended option) or by running the Linux version of FSL inside a "virtual Linux machine" (a VM).

Windows Subsystem for Linux

This is the recommended option for using FSL on a Windows computer. Note due to recent changes in WSL2, we have some provisional changes to the existing ( WSL1 ) instructions.

Installation Video

We have created an installation video which gives an overview of the installation procedure for the Windows Subsystem for Linux using Windows 10.

System Requirements

• Windows 10

• The Windows Subsystem for Linux (WSL) can be installed by following these instructions. WSL build 17101 (February 2018) or newer is required.

• Dual core CPU (recommended minmum)
• 4GB RAM minimum (8GB+ recommended)
• Minimum 10GB, up to 75GB, of free disk space

Note: installation progress may not update in the terminal. If this occurs please be patient, and do not abort the installation.

1. Follow these steps to install the Ubuntu subsystem in Windows

   • enable WSL using windows PowerShell (need to run the PowerShell app as administrator). Paste this command in and press enter. Follow any prompts given.

   • Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux

   • Restart your computer
   • After restart, open the Microsoft Store and search for Ubuntu 18.04. Install Ubuntu and then Launch it.
   • Sep up a username and password for Ubuntu (only necessary the first time you launch it)
2. In an Ubuntu shell window enter these commands:

    sudo apt update; sudo apt -y upgrade; sudo apt-get install dc python mesa-utils gedit pulseaudio libquadmath0

3. use any browser installed on your Windows 10 computer to get the installer script as normal ( from here ). Download it to your downloads folder.

4. Install Xming in order to use FSL user interfaces: http://www.straightrunning.com/XmingNotes/. You will need to have XMING running in windows, before the linux GUIs will work. For WSL2 instead use the instructions below.

1. run downloaded script in Ubuntu shell via

    python /mnt/c/Users/<WindowsUserName>/Downloads/fslinstaller.py

   Say yes to all default install options
2. In ubuntu shell add

    echo "export DISPLAY=localhost:0.0" >> ~/.bashrc

   For WSL2 instead use the instructions below.

3. 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

   If fslmaths doesn't start, with a message referring to: libquadmath.so.0, then you will need to run (in case you didn't install it earlier):

    sudo apt-get install libquadmath0

4. It might be worth trying

    sudo apt-get install firefox

   to get native browser support. However, you can always just use a web bowser from your windows machine (not within Ubuntu) to view FSL report.html files.
5. 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.

WSL 2 Changes ( provisional )

1. We currently recommend installing VcXsrv instead of Xming. When running XLaunch, it is critical to deselect Native OpenGL and select Disable access control in the Extra Settings panel. XLaunch will need to be running for graphical applications to work.

2. The .bashrc changes should instead be:

export DISPLAY=$(ip route | awk '/default via / {print $3; exit}' 2>/dev/null):0
export LIBGL_ALWAYS_INDIRECT=1

• due to the quoting in the first line, it's easiest to make these changes via a text-editor.

Virtual Machine

The VM option requires 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.

System Requirements

• Windows 7,8,10
• Dual core CPU (recommended minmum)
• 4GB RAM minimum (8GB+ recommended)
• Minimum 10GB, up to 75GB, of free disk space (VM image expands as necessary up to the 75GB limit, if used)

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.

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 Installation

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.

Initial setup

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.

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.

Further steps

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:

1. Drag-and-drop

   • 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.

2. 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.

   Warning

   Do not attempt to modify the same files in this shared folder in both operating systems at once - bad things will happen!

3. 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.

Accessing ExFAT USB drives from the VM

If you wish to use an ExFAT-formatted USB drive, you will need to install an ExFAT driver into the virtual machine. Open a terminal and run these commands:

sudo yum -y install epel-release
sudo rpm -Uvh http://li.nux.ro/download/nux/dextop/el7/x86_64/nux-dextop-release-0-5.el7.nux.noarch.rpm
sudo yum install exfat-utils fuse-exfat

Network access

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.

Shutting down

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.

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.

1. Start with the drive disconnected
2. Click inside the running VM window so that you are controlling Linux
3. Connect the USB drive

4. 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.

5. Open a terminal and become the root user:

   su -

   • (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.

6. Run the partitioning tool:

   parted

   • You are now in an interactive partition editor.
7. Find your disk:

   print all

   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)

8. select /dev/sdX

   • (replace X with the letter you determined above)

9. rm Y

   • where Y is the partition number you noted. Repeat until you have deleted all the partitions on the disk

10. print

    • to confirm that they are all gone

11. mkpart primary 1 ZGB

    • where Z is the size of the disk in question (eg 250GB), hit return to any prompts

12. quit

13. Make a file system on the partition

    mkfs -t ext4 /dev/sdX

    • (X as above)

14. 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).