# Manage sessions

The omero sessions plugin manage user sessions stored locally on disk. Several sessions can be active simultaneously, but only one will be used for a single invocation of omero:

    $ omero sessions -h

## Login

The omero login command is a shortcut for the omero sessions login subcommand which creates a connection to the server. If no argument is specified, the interface will ask for the connection credentials:

    $ omero login
    Previously logged in to localhost:4064 as root
    Server: [localhost:4064]
    Username: [root]
    Password:

Some of the options available to the omero login command are:

connection

  Pass a connection string under the form `[USER@]SERVER[:PORT]` to instantiate a connection:

      $ omero login username@servername
      Password:
      $ omero login username@servername:14064
      Password:

-s SERVER, --server SERVER

  Set the name of the server to connect to:

      $ omero login -s servername
      Username: [username]

-u USER, --user USER

  Set the name of the user to connect as:

      $ omero login -u username -s servername
      Password:

-p PORT, --port PORT

  Set the port to use for connection. Default: 4064:

      $ omero login -u username -s servername -p 14064
      Password:

-g GROUP, --group GROUP

  Set the group to use for initalizing a connection:

      $ omero login -u username -s servername -g my_group
      Password:

-k KEY, --key KEY

  Use a valid session key to join an existing connection.

  This option only requires a server argument:

      $ omero login servername -k 22fccb8b-d04c-49ec-9d52-116a163728ca

-w PASSWORD, --password PASSWORD

  Set the password to use for the connection. Since 5.4.1, the password can be set using the `OMERO_PASSWORD` environment variable. The variable will be ignored if `-w` or `--password` is used.

--sudo ADMINUSER|GROUPOWNER

  Create a connection as another user.

  The sudo functionality is available to administrators as well as group owners

      $ omero login --sudo root -s servername -u username -g groupname
      Password for root:
      $ omero login --sudo owner -s servername -u username -g groupname
      Password for owner:

## Multiple sessions

Stored sessions can be listed using the omero sessions list command:

    $ omero sessions list
     Server    | User | Group           | Session                              | Active    | Started
    -----------+------+-----------------+--------------------------------------+-----------+--------------------------
     localhost | test | read-annotate-2 | 22fccb8b-d04c-49ec-9d52-116a163728ca | Logged in | Fri Nov 23 14:55:25 2012
     localhost | root | system          | 1f800a16-1dc2-407a-8a85-fb44005306be | True      | Fri Nov 23 14:55:18 2012
    (2 rows)

Session keys can then be reused to switch between stored sessions using the `omero login -k` option:

    $ omero sessions login -k 22fccb8b-d04c-49ec-9d52-116a163728ca
    Server: [localhost]
    Joined session 1f800a16-1dc2-407a-8a85-fb44005306be (root@localhost:4064).
    $ omero sessions list
     Server    | User | Group           | Session                              | Active    | Started
    -----------+------+-----------------+--------------------------------------+-----------+--------------------------
     localhost | test | read-annotate-2 | 22fccb8b-d04c-49ec-9d52-116a163728ca | True      | Fri Nov 23 14:55:25 2012
     localhost | root | system          | 1f800a16-1dc2-407a-8a85-fb44005306be | Logged in | Fri Nov 23 14:55:18 2012
    (2 rows)

## Sessions directory

By default sessions are saved locally on disk under the OMERO user directory located at `~/omero/sessions`. The location of the current session file can be retrieved using the omero sessions file command:

    $ omero sessions file
    /Users/ome/omero/sessions/localhost/root/aec828e1-79bf-41f3-91e6-a4ac76ff1cd5

To customize the OMERO user directory, use the `OMERO_USERDIR` environment variable:

       $ export OMERO_USERDIR=/tmp/omero_dir
       $ omero login root@localhost:4064 -w omero
       Created session bf7b9fee-5e3f-40fa-94a6-1e23ceb43dbd (root@localhost:4064). Idle timeout: 10.0 min. Current group: system
       $ omero sessions file
    /tmp/omero_dir/omero/sessions/localhost/root/bf7b9fee-5e3f-40fa-94a6-1e23ceb43dbd
       $ omero logout

If you want to use a custom directory for sessions exclusively, use the `OMERO_SESSIONDIR` environment variable:

    $ export OMERO_SESSIONDIR=/tmp/my_sessions
    $ omero login root@localhost:4064 -w omero
    Created session bf7b9fee-5e3f-40fa-94a6-1e23ceb43dbd (root@localhost:4064). Idle timeout: 10.0 min. Current group: system
    $ omero sessions file
    /tmp/my_sessions/localhost/root/bf7b9fee-5e3f-40fa-94a6-1e23ceb43dbd
    $ omero logout

Note

The `OMERO_SESSION_DIR` environment variable introduced in 5.1.0 to specify a custom sessions directory is deprecated in 5.1.1 and above in favor of `OMERO_SESSIONDIR`.

If you have been using `OMERO_SESSION_DIR` and want to upgrade your custom sessions directory without losing locally stored sessions:

- either set `OMERO_SESSIONDIR` to point at the same location as `OMERO_SESSION_DIR/omero/sessions`

- or move all local sessions stored under the `OMERO_SESSION_DIR/omero/sessions` directory under the `OMERO_SESSION_DIR` directory and replace `OMERO_SESSION_DIR` by `OMERO_SESSIONDIR`.

## Switching current group

The sessions group command can be used to switch the group of your current session:

    $ omero group list          # list your groups
    $ omero sessions group 2    # switch to group by ID or Name