Overview
Describes configuration options that not everyone will need, but may be useful for optimizing, customizing, or monitoring your server.
The OMERO server provides several different configuration/extension points that you may want to make use of.
The primary form of configuration is via the use of key/value properties, stored in etc/grid/config.xml and read on server startup. Backing and copying these properties is as easy as moving this file to a new server version.
The etc/omero.properties file of your distribution defines all the default configuration properties used by the server. Changes made to the file are not recognized by the server. Instead, the omero config command is used to change those properties that you would like to customize.
Examples of doing this are on the main Unix and Windows pages, as well as the LDAP installation page.
Here we list some options which you are most likely to want to modify. See etc/omero.properties for more details.
omero.sessions.timeout sets the duration of inactivity in milli-seconds after which a login is required (default is 600000, or 10 minutes). To change the default, for example, to 1 hour use:
$ bin/omero config set omero.sessions.timeout 3600000
omero.db.poolsize sets the number of connections to PostgreSQL which will be used by OMERO (default is 10):
$ bin/omero config set omero.db.poolsize 50
Your database installation will need to be configured to accept at least as many, preferably more, connections as the value of “omero.db.poolsize”
In some cases, the configuration properties will not suffice to fully configure your server. In that case, it may be necessary to make use of IceGrid’s XML configuration files. Like the config.xml file mentioned above, these are stored under etc/grid. “default.xml” is used on Unix systems, and “windefault.xml” is used on Windows systems. Both, make use of “templates.xml”.
When you run omero admin start without any other arguments, it looks up the default application descriptor for your platform:
~/git/dist $ bin/omero admin start
No descriptor given. Using etc/grid/default.xml
Waiting on startup. Use CTRL-C to exit
The “start” and “deploy” command, however, take several other parameters:
$ bin/omero admin start --help
usage: bin/omero admin start [-h] [-u USER] [file] [targets [targets ...]]
Start icegridnode daemon and waits for required components to come up, i.e. status == 0
If the first argument can be found as a file, it will
be deployed as the application descriptor rather than
etc/grid/default.xml. All other arguments will be used
as targets to enable optional sections of the descriptor
Positional Arguments:
file Application descriptor. If not provided, a default will be used
targets Targets within the application descriptor which should be activated.
If a file is passed in as the first argument, then that application descriptor as opposed to default.xml will be used. You can also modify the default application descriptors in place.
Note
The largest issue with using your own application descriptors or modifying the existing ones is that they tend to change between versions, and there is no facility for automatically merging your local changes. You should be prepared to re-make whatever changes you perform directly on the new files.
The most likely change you will need to make to your application descriptors is increasing the memory settings. This is not done by default since it would prevent starting the server on some sites’ test instance, but for production use a setting higher than 512MB is highly recommended.
You can either edit the file manually, or use a small script such as:
perl -i -pe 's/Xmx512M/Xmx2048M/' etc/grid/templates.xml
perl -i -pe 's/XX:MaxPermSize=128m/XX:MaxPermSize=256M/' etc/grid/templates.xml
Targets are elements within the application descriptors which can optionally turn on configuration. The target is only applicable until the next invocation of omero admin start or omero admin deploy
Note
You must remember to always apply the targets on each omero admin command. If not, the target will not be removed. Therefore, they are often better used for debugging purposes; however, as opposed to alternative application descriptors, using the pre-existing targets should not require any special effort during upgrades.
<properties id="PythonServer">
<property name="Ice.ImplicitContext" value="Shared"/>
<!-- Default logging settings for Python servers. -->
<property name="omero.logging.timedlog" value="False"/>
<property name="omero.logging.logsize" value="5000000"/>
<property name="omero.logging.lognum" value="9"/>
<property name="omero.logging.level" value="20"/>
<target name="debug">
<property name="omero.logging.level" value="10"/>
</target>
Here, the “debug” target allows increasing the logging output of the Python servers without modifying any files.
<server-template id="BlitzTemplate">
<parameter name="index"/>
<parameter name="config" default="default"/>
<parameter name="jmxhost" default=""/>
<parameter name="jmxport" default="3001"/>
...
<target name="jmx">
<!-- Be sure to understand the consequences of enabling JMX.
It allows calling remote methods on your JVM -->
<option>-Dcom.sun.management.jmxremote=${jmxhost}</option>
<option>-Dcom.sun.management.jmxremote.port=${jmxport}</option>
<option>-Dcom.sun.management.jmxremote.authenticate=false</option>
<option>-Dcom.sun.management.jmxremote.ssl=false</option>
</target>
The JMX target activates the monitoring of the Blitz server via JMX. If you need to modify the “jmxport” or “jmxhost” variables, you will need to do so directly in the application descriptor XML.
Since changing all the references to port numbers (4061, 4063, 4064, etc) in the grid configuration can be cumbersome, a omero admin command is provided to make the modifications for you. See the SSL section of the Server security and firewalls page for more information.
By modifying the default OMERO ports, it is possible to run multiple OMERO servers on the same physical machine.
# First server
cd /usr/local/omero-4.2
bin/omero admin ports --prefix=1
bin/omero admin start
# Second server
cd /usr/local/omero-4.3
bin/omero admin ports --prefix=2
bin/omero admin start
Clients will need to use the appropriate port (either 14064 or 24064) to connect to OMERO.
Finally, if configuration does not suffice, there are also options to extending OMERO with your own code. These are described on the development site under Extending OMERO.