Advanced configuration
======================

.. topic:: 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.

First step: configuration properties
------------------------------------

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 :source:`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 :omerocmd:`config` command is
used to change those properties that you would like to customize.

Examples of doing this are on the main :doc:`Unix <unix/server-installation>` and
:doc:`Windows <windows/server-installation>` pages, as well as the :doc:`LDAP
installation <server-ldap>` page.

Here we list some options which you are most likely to want to modify.
See :source:`etc/omero.properties` for more details.

omero.sessions.timeout
^^^^^^^^^^^^^^^^^^^^^^

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
^^^^^^^^^^^^^^^^^

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"

Last resort: grid configuration
-------------------------------

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 :sourcedir:`etc/grid`.
"default.xml" is used on Unix systems, and "windefault.xml" is used on
Windows systems. Both, make use of "templates.xml".

Modifying the application descriptors
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

When you run :omerocmd:`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.

Targets
^^^^^^^

**Targets** are elements within the application descriptors which can
optionally turn on configuration. The target is only applicable until
the next invocation of :omerocmd:`admin start` or :omerocmd:`admin deploy`

.. note::
    You must remember to always apply the targets on each
    :omerocmd:`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.

Debugging
^^^^^^^^^

::

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

JMX configuration
^^^^^^^^^^^^^^^^^

::

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

Changing ports / multiple servers on a single host
--------------------------------------------------

Since changing all the references to port numbers (4061, 4063, 4064,
etc) in the grid configuration can be cumbersome, a 
:omerocmd:`admin` command is provided to make the modifications for 
you. See the :ref:`security_ssl`
section of the :doc:`/sysadmins/server-security` 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.

Extending 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 |ExtendingOmero|.