command-line-interface.txt

OMERO Command Line Interface
============================

.. seealso::

    :doc:`/users/command-line-interface`
        User documentation for the Command Line Interface

    :doc:`/developers/command-line-interface`
        Developer Documentation for the Command Line Interface

When first beginning to work with the OMERO server, the :omerocmd:`db`,
:omerocmd:`config`, and :omerocmd:`admin` commands will be the first you will
need.

Database tools
--------------

Rather than try to provide the functionality of a RDBM tool like ``psql``, the
:omerocmd:`db script` command helps to generate SQL scripts for building your 
database. You can then use those scripts from whatever tool is most 
comfortable for you::

    $ bin/omero db script OMERO4 0 secretpassword
    Using OMERO4 for version
    Using 0 for patch
    Using password from commandline
    Saving to /omero/OMERO4__0.sql
    $ psql omero < OMERO4__0.sql

Server configuration
--------------------

The :omerocmd:`config` command is responsible for reading / writing
user-specific profiles stored under :file:`etc/grid/config.xml`. To get
the current profile, use the :omerocmd:`config def` command::

    $ bin/omero config def
    default

You can then examine the current profile keys using :omerocmd:`config get`
and set key-value pairs using :omerocmd:`config set`::

    $ bin/omero config get

    $ bin/omero config set example "my first value"

    $ bin/omero config get
    example=my first value

You can use the :envvar:`OMERO_CONFIG` environment variable to point at a
different profile, e.g.::

    $ OMERO_CONFIG=another bin/omero config def
    another

    $ OMERO_CONFIG=another bin/omero config get

    $ OMERO_CONFIG=another bin/omero config set example "my second value"

    $ OMERO_CONFIG=another bin/omero config get
    example=my second value

The values set via :omerocmd:`config set` override those compiled into the
server jars. The default values which are set can be seen in
:file:`etc/omero.properties`. To add several values to a configuration, you
can pipe them via standard in using :omerocmd:`config load`::

    $ grep omero.ldap etc/omero.properties | OMERO_CONFIG=ldap bin/omero config load

    $ OMERO_CONFIG=ldap bin/omero config get
    omero.ldap.attributes=objectClass
    omero.ldap.base=ou=example,o=com
    omero.ldap.config=false
    omero.ldap.groups=
    omero.ldap.keyStore=
    omero.ldap.keyStorePassword=
    omero.ldap.new_user_group=default
    omero.ldap.password=
    omero.ldap.protocol=
    omero.ldap.trustStore=
    omero.ldap.trustStorePassword=
    omero.ldap.urls=ldap://localhost:389
    omero.ldap.username=
    omero.ldap.values=person

Each of these values can then be modified to suit your local setup. To
remove one of the key-value pairs, pass no second argument::

    $ OMERO_CONFIG=ldap bin/omero config set omero.ldap.trustStore

    $ OMERO_CONFIG=ldap bin/omero config set omero.ldap.trustStorePassword

    $ OMERO_CONFIG=ldap bin/omero config set omero.ldap.keyStore

    $ OMERO_CONFIG=ldap bin/omero config set omero.ldap.keyStorePassword

    $ OMERO_CONFIG=ldap bin/omero config get
    omero.ldap.attributes=objectClass
    omero.ldap.base=ou=example,o=com
    omero.ldap.config=false
    omero.ldap.groups=
    omero.ldap.new_user_group=default
    omero.ldap.password=
    omero.ldap.protocol=
    omero.ldap.urls=ldap://localhost:389
    omero.ldap.username=
    omero.ldap.values=person

If you will be using a particular profile more frequently you can set it
as your default using the :omerocmd:`config def` command::

    $ bin/omero config def ldap

And finally, if you would like to remove a profile, for example to wipe a
given password off of a system, use :omerocmd:`config drop`::

    $ bin/omero config drop

Server administration
---------------------

Server start
^^^^^^^^^^^^

Once your database has been properly configured and your config profile
is set to use that database, you are ready to start your server using the
:omerocmd:`admin start` command::

    $ bin/omero admin start

Server diagnostics
^^^^^^^^^^^^^^^^^^

::

    $ bin/omero admin diagnostics

User/group management
---------------------

The :omerocmd:`user` and :omerocmd:`group` commands provide functionalities to 
add and manage users and groups on your database.

User creation
^^^^^^^^^^^^^

New users can be added to the database using the :omerocmd:`user add` command::

    $ bin/omero user add -h

During the addition of the new user, you will need to specify the first and
last name of the new user and their username as well as the groups the user
belongs to. To add John Smith as a member of group 2 identified as jsmith,
enter::

    $ bin/omero user add jsmith John Smith 2

Additional parameters such as the email address, institution, middle name etc 
can be passed as optional arguments to the :omerocmd:`user add` command.

Group creation
^^^^^^^^^^^^^^

New groups can be added to the database using the :omerocmd:`group add` 
command::

    $ bin/omero group add -h

During the addition of the new group, you need to specify the name of the new
group::

    $ bin/omero group add newgroup

The permissions of the group are set to `private` by default. Alternately you
can specify the permissions using :option:`--perms` or :option:`--type` 
optional arguments::

    $ bin/omero group add read-only-1 --perms='rwr---'
    $ bin/omero group add read-annotate-1 --type=read-annotate

.. seealso::

    :doc:`server-permissions` 
        Description of the three group permissions levels (private, read-only, 
        read-annotate). 

Lists of users/groups on the OMERO server can be queried using the
:omerocmd:`user list` and :omerocmd:`group list` commands::

    $ bin/omero user list
    $ bin/omero group list

Group management
^^^^^^^^^^^^^^^^

Users can be added to existing groups using the :omerocmd:`user joingroup` or 
:omerocmd:`group adduser` commands. Similarly, users can be removed from 
existing groups using the :omerocmd:`user leavegroup` or 
:omerocmd:`group removeuser` commands::

    # Add jsmith to group read-annotate-1
    $ bin/omero group adduser jsmith --name=read-annotate-1
    # Remove jsmith from group read-annotate-1
    $ bin/omero group removeuser jsmith --name=read-annotate-1
    # Add jsmith to group read-only-1
    $ bin/omero user joingroup read-only-1 --name=jsmith
    # Remove jsmith from group read-only-1
    $ bin/omero user leavegroup read-only-1 --name=jsmith

By passing the :option:`--as-owner` option, these commands can also be used to manage group owners ::

    # Add jsmith to the owner list of group read-annotate-1
    $ bin/omero group adduser jsmith --name=read-annotate-1 --as-owner
    # Remove jsmith from the owner list of group read-annotate-1
    $ bin/omero user leavegroup read-annotate-1 --name=jsmith --as-owner

Group copy
^^^^^^^^^^

To create a copy of a group, you must first create a new group using the
:omerocmd:`group add` command::

    $ bin/omero group add read-only-2 --perms='rwr---'

Then you can use the :omerocmd:`group copyusers` command to copy all group 
members from one group to  another::

    $ bin/omero group copyusers read-only-1 read-only-2

To copy the group owners, use the same command with the :option:`--as-owner` optional argument::

    $ bin/omero group copyusers read-only-1 read-only-2 --as-owner