|
| 1 | +# SyneRBI Virtual Machine: Installation and running of pre-built machine |
| 2 | + |
| 3 | +If you have any problems, please first re-check this web-page. If you cannot solve your issue, please email syneRBI-USERS @ JISCMAIL.AC.UK |
| 4 | + |
| 5 | + |
| 6 | +## Initial download and installation |
| 7 | +This section assumes you want to use our pre-configured VM (which is recommended!). If you want to build a new VM yourself, then check the [README](README.md) for instructions. |
| 8 | + |
| 9 | +1. Make sure you have enough free disk-space on your laptop (~10GB for installation). |
| 10 | + |
| 11 | +2. Install VirtualBox (VB), our [Download page](http://www.ccpsynerbi.ac.uk/downloads) specifies the recommended version. |
| 12 | +(If it is older than the current default download from VB, you can [get an older version here](https://www.virtualbox.org/wiki/Download_Old_Builds)). Please note that this will require administrator permissions on your computer. The "host" operating system refers to your computer. |
| 13 | +You do not need to install the Oracle extensions to VirtualBox, although it might come in handy for USB support. |
| 14 | +Although other Virtual Machine software might work, we have not tried this and will not be able to help to get this going. |
| 15 | + Some extra pointers if you experience problems with installing VirtualBox |
| 16 | + - On older Ubuntu versions (e.g. 15.10), there were some problems installing VirtualBox related to `libvpx`, [check here for some help](https://forums.virtualbox.org/viewtopic.php?f=7&t=74050). |
| 17 | + - If your VirtualBox is too old, you might experience problems with networking etc. Please use at least 5.0.40 (at least 5.2.6 on a Mac). |
| 18 | + |
| 19 | + For Macs, the installation of Virtual Box might require you to alter your security settings. |
| 20 | + - If you receive an error along the lines of `kernel driver not installed (rc=-1908)`, the following might help. Click on the Apple icon in the top-left of your screen and then `System Preferences->Security & Privacy->General`. Click the padlock in the bottom-left and enter your password to be able to make changes to this page. Click `Allow` next to the Virtual Box text. Hopefully the problem will have been sorted. |
| 21 | + - If the installation takes you directly to the `Security and Privacy` window, select `Allow` (the VB is labelled as from Oracle). When the installer asks if it should Move to Trash, say `Keep` because you need to re-run the installation again with this revised security setting. Second time around, you can move it to trash. |
| 22 | + |
| 23 | +3. Download the preinstalled virtual machine from http://www.ccpsynerbi.ac.uk/downloads. |
| 24 | +Warning: this file can be ~4.9GB. (You can download to a USB stick or hard drive to save space on your hard-disk). |
| 25 | + |
| 26 | +4. Open the downloaded OVA file (double-click or whatever is appropriate for your system). This should start VirtualBox with the "Import" dialog box. |
| 27 | + |
| 28 | +5. Change settings of the virtual machine (you can still change this afterwards by using the Settings menu of VirtualBox). The only things that need your attention: |
| 29 | + - CPU: use the same number of CPUs (i.e. cores) as your laptop (or 1 less) |
| 30 | + - RAM: use about half the RAM of your laptop (assigning too much RAM will slow down your laptop dramatically, using not enough will slow down the virtual machine. 1.5GB seems to be enough for most things though.) |
| 31 | + - Virtual Disk Image: normally this filename is fine but you can save it somewhere else if you like |
| 32 | + |
| 33 | +6. If still present, tick the box "Reinitialise the MAC address of all network cards" |
| 34 | + |
| 35 | +7. Press Import and wait for a few minutes (everything will be decompressed etc). |
| 36 | + |
| 37 | +8. In the VirtualBox window, select your new VM and press the Settings icon. In the "General" category, "Advanced" tab, check that "Shared Clipboard" is set to "bidirectional". |
| 38 | + |
| 39 | +## Initial configuration of the virtual machine |
| 40 | + |
| 41 | +Now you can start your virtual machine. If it fails to start with an error like "*virtualbox vt-x is disabled in the bios*", [check here](http://www.howtogeek.com/213795/how-to-enable-intel-vt-x-in-your-computers-bios-or-uefi-firmware/). |
| 42 | +If you see a dialog box about "starting in scaled mode", you can press OK to allow VirtualBox to scale the display larger or smaller, or you can press Cancel and start the machine again without scaling. (See [the Virtualbox site](https://www.virtualbox.org/manual/) for some info on the Host-Key etc). |
| 43 | + |
| 44 | +1. You should get a window where Ubuntu 18.04 will be starting (might take a few minutes). Wait until you see the log-in prompt. |
| 45 | + |
| 46 | +2. Log in as user "sirfuser" with password "virtual" (please note that the default keyboard is with `en_GB` locale: if you have an Azerty-type keyboard, you will have to type "virtuql" until you change your VM keyboard settings). You should get the Gnome3 desktop. |
| 47 | + |
| 48 | +3. Adjust your Ubuntu settings: |
| 49 | + - Default settings should allow you to access the internet from in the virtual machine. |
| 50 | + If not, please check [the Virtual Box documentation](http://www.virtualbox.org/manual/ch03.html#settings-network). |
| 51 | + - The keyboard type is set to English-UK. There are currently a few preinstalled layouts, including en_GB, en_US, Portuguese, Spanish etc. |
| 52 | + You can change keyboard-type by clicking on the relevant icon in the top-right of the VM. |
| 53 | + If you cannot find the layout that you need (e.g. to switch to a Mac keyboard), open a terminal by clicking "Activities" at top left and type "terminal" in the search box, then use |
| 54 | + |
| 55 | + ``` |
| 56 | + sudo dpkg-reconfigure keyboard-configuration |
| 57 | + ``` |
| 58 | +
|
| 59 | + - To adjust other system settings you can click on the right top corner and then click on the tools icon (spanner and screwdriver) to start the settings app, or click on "Activities" on the top left corner and then type "settings" in the search box and it should open the settings apps. If the text and windows are so large it makes using the settings app difficult, try changing the scaling by pressing the small display icon near the bottom right of the VB window. |
| 60 | +
|
| 61 | +4. The VM has been created with a particular version of Virtual Box (see the Download page) and with the [VirtualBox Guest Additions](https://www.virtualbox.org/manual/ch04.html) (VGA) pre-installed. If you have a different (or even the same) version of Virtual Box you might experience [issues](https://github.com/SyneRBI/SyneRBI_VM/issues/9), especially [running the X server](https://github.com/SyneRBI/SyneRBI_VM/issues/60#issuecomment-367611385). If you are using a different version of VirtualBox we therefore strongly recommend to sync your VGA version as follows:\ |
| 62 | +In the menu-bar of the window that contains your VM, click on "Devices" and then "Insert Guest Additions CD". (On a Mac, with the VM window selected, this menu bar is at the top of the screen). If this generates a window inside your VM to run the software on this "CD", say OK. Otherwise, type |
| 63 | +
|
| 64 | + ``` |
| 65 | + sudo /home/sirfuser/devel/SyneRBI_VM/scripts/update_VGA.sh |
| 66 | + sudo shutdown -r now |
| 67 | + ``` |
| 68 | +The VM will reboot. (You will have to do this again if you upgrade your VirtualBox version). |
| 69 | +
|
| 70 | +5. On old VM versions (e.g. 20 April 2018, SIRF_1.0.0) people were reporting problems after the VM is shutdown or rebooted, but this problem no longer seems to exist. The VM windows system may fail to start and you are left with a flashing VM terminal window that stabilises after a few minutes. If your cursor has gone, it may be "in" this terminal window and can be released (press the Host Key (on most systems, right-ctrl, on a Mac the Apple command key). To restore proper functionality, follow the instructions in point 5 above, even if you already had the correct VGA installed. If you have previously 'inserted' the CD you may get an error message that you need to ignore. Then reboot. |
| 71 | +
|
| 72 | +## Usage |
| 73 | +Check our [wiki](https://github.com/SyneRBI/SyneRBI_VM/wiki) for usage instructions. |
| 74 | +
|
| 75 | +## How to shut down the VM |
| 76 | +
|
| 77 | +To shut down your VM when you are finished with it, use one of the following options. |
| 78 | +
|
| 79 | +1. Close the VM window and use "save machine state" (allowing you to resume from where you were). |
| 80 | +2. Shutdown the VM via the Ubuntu interface (arrow in top-right corner), or close the VM window |
| 81 | +and use "Send the shutdown signal". |
| 82 | +(It is not advisable to "power-off" the VM as that can leave the file system of the VM in an undefined state). |
| 83 | +3. Use the VirtualBox main window to do any of the above. |
| 84 | +
|
| 85 | +## Shared folders |
| 86 | + |
| 87 | +This section is optional. |
| 88 | + |
| 89 | +Warning: in VB versions before 6.0.6, we strongly recommend to copy data from a shared folder to a “local” folder (in your VM) to avoid a problem with [a VB bug](https://www.virtualbox.org/ticket/9485). |
| 90 | + |
| 91 | +After installing the VGA, you might want to configure a shared directory between the host and the guest machine such that your virtual machine can "see" your "normal" files. Please read [the Virtualbox documentation on Folder Sharing](http://www.virtualbox.org/manual/ch04.html#sharedfolders). |
| 92 | +Summary of steps (courtesy Nikos Efthimiou): |
| 93 | + |
| 94 | + 1. Right click on the SyneRBI VM in VirtualBox main window and choose Settings. |
| 95 | + 2. Choose "Shared Folders". |
| 96 | + 3. Add new folder (use small + button near the right edge of the dialog), select the folder you want, and give it a name, e.g. MyLaptop. |
| 97 | + 4. Select folder and check "make permanent" and "auto mount". |
| 98 | + 5. Start the SyneRBI VM (or switch to it) and open a terminal and type |
| 99 | + |
| 100 | + mkdir ~/MyLaptop |
| 101 | + sudo mount -t vboxsf -o rw,uid=1002,gid=1002 MyLaptop ~/MyLaptop |
| 102 | + The '1002's in the above refer to the user and group ids of the user. These are not always 1002 - to check, at the command line, type the command `id`. |
| 103 | + |
| 104 | + You will have to type the last command whenever you reboot your VM, or you could make this permanent by pasting the above command to /etc/rc.local before "exit 0" (non-trivial because of admin permissions). |
| 105 | +
|
| 106 | +If you want you can unmount the folder by typing |
| 107 | +
|
| 108 | + sudo umount -t vboxsf MyLaptop |
| 109 | +
|
| 110 | +## Using the VM as server |
| 111 | +
|
| 112 | +See [here](https://github.com/SyneRBI/SyneRBI_VM/blob/master/Using_VM_as_server.md) |
0 commit comments