Note

This documentation is for OMERO 5.2. This version is now in maintenance mode and will only be updated in the event of critical bugs or security concerns. OMERO 5.3 is expected in the first quarter of 2017.

Working with OMERO virtual appliance

Now that your VM is up and running you have a choice about how to interact with it.

• You can connect to OMERO.web from your host browser. Go to http://localhost:8080/webclient.
• You can use OMERO.clients from within your host OS. This will allow you to import data via a GUI and manage that data once imported. To do so, download the OMERO.insight client and follow the instructions below. More information can be found on our help website which provides workflow-based guides to using the OMERO.clients.
• Alternatively, you can interact with the server command line interface by SSH‘ing into the guest VM or by opening a console within the VM itself. Administrators may need to use one of these methods to restart the server and/or change configuration parameters. In this case, you must have an SSH client installed on your host machine to use to connect to the OMERO.server.

Note

The following examples assume that the OMERO VM is up and running on the same machine that you are working on.

OMERO.web

Go directly to http://localhost:8080/webclient to log in with user: “root” / pw: “omero”.

Note

If you receive a 502 nginx error on first attempting to connect to the web app on http://localhost:8080/webclient/ please restart the virtual machine and try again.

OMERO.insight

You can run regular OMERO clients on your host machine and connect to the server in the VM. Our example uses OMERO.insight running on Mac OS X to connect to the VM.

• Download and install OMERO.insight
• Start OMERO.insight
• Click the spanner icon situated above the password box to enter the server settings box shown below.

Setting OMERO.insight server address and port number

• Use the + icon to add a new server entry with the address localhost and the port 4064 then click apply
• You can now use the login credentials given above to log into OMERO.insight using the login window shown below (user: “root” / pw: “omero”).

OMERO.insight login window

• OMERO.insight should now load up and display the main window.

You can now use OMERO.insight to import and manage images on a locally running virtual server just like you would use the standard remote server.

Note

A Getting Started guide is available for OMERO.insight on our help website if you need further assistance to download and install the software.

Secure Shell

You can log into your VM using SSH, allowing you to use the Command Line Interface as an OMERO client. In the following example, we assume that you have an SSH client installed on your host machine and also that your VM is up and running.

You can log into the VM using the above credentials and the following command typed into a terminal:

$ ssh omero@localhost -p 2222

This invokes the SSH program telling it to login to the localhost on port 2222 using the username omero. Remember that earlier you set up port forwarding to forward port 2222 on the host machine to port 22 (the default SSH port) on the guest VM. You should be prompted for a password. Once you have successfully entered your password, you should be greeted by a prompt similar to the following:

omero@omerovm:~$

There are two potential complications to this method, (1) if you have used a VM before then there could be old SSH fingerprints set up, (2) the first time that you log into the VM you will be asked to confirm that you wish to continue connecting. If you get the following message after you invoke SSH, you need to remove the old fingerprints:

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@    WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!     @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!
Someone could be eavesdropping on you right now (man-in-the-middle attack)!
It is also possible that the RSA host key has just been changed.
The fingerprint for the RSA key sent by the remote host is
60:e0:d2:e8:fb:25:bf:09:53:9d:9d:59:59:45:cf:aa.
Please contact your system administrator.
Add correct host key in /Users/rleigh/.ssh/known_hosts to get rid of this message.
Offending key in /Users/rleigh/.ssh/known_hosts:14
RSA host key for localhost has changed and you have requested strict checking.
Host key verification failed.

You can do this using the following command typed into the terminal:

$ ssh-keygen -R [localhost]:2222 -f ~/.ssh/known_hosts

This should produce output similar to:

$ ssh-keygen -R [localhost]:2222 -f ~/.ssh/known_hosts
/Users/rleigh/.ssh/known_hosts updated.
Original contents retained as /Users/rleigh/.ssh/known_hosts.old

The first time that you log into the VM you will also be asked to confirm that you wish to connect to this machine by a message similar to the following:

$ ssh omero@localhost -p 2222
The authenticity of host '[localhost]:2222 ([127.0.0.1]:2222)' can't be established.
RSA key fingerprint is 60:e0:d2:e8:fb:25:bf:09:53:9d:9d:59:59:45:cf:aa.
Are you sure you want to continue connecting (yes/no)?

You should confirm that you wish to continue connecting, after which you will be prompted for your password as usual:

Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added '[localhost]:2222' (RSA) to the list of known hosts.
omero@localhost's password:

After which, you should have a prompt indicating that you have a shell open and logged into the VM:

omero@localhost's password:
Linux omerovm 2.6.32-5-686 #1 SMP Mon Jun 11 17:24:18 UTC 2012 i686

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
Last login: Thu Apr  5 10:32:18 2012 from 10.0.2.2
omero@omerovm:~$ _

Log into the VM directly

Note

Due to the frequent changes in the VirtualBox Guest Additions, key mappings between the host and guest OS do not always work. We recommend using SSH as the primary way of interacting with the Virtual Appliance CLI.

When you start your VM using the VirtualBox GUI, as outlined above, a window will be displayed showing the boot process for the machine as it starts up, just like with a real piece of hardware. Once the boot process has finished you will see a prompt displayed in this window like so:

[System startup messages]

Debian GNU/Linux 6.0 omerovm tty1

omerovm login: _

You can log into the console of the VM directly using the user account credentials above.

omerovm login: omero
Password: _

There is no GUI on the current OMERO virtual appliance so you will have to use the Bash shell which looks like this:

omero@omerovm:~$ _

From here you can interact with OMERO.server via the Command Line Interface as an OMERO client. You will need to login as the ‘omero’ user to access the OMERO CLI (user: “omero” / pw: “omero”). Logout using Ctrl-D.