****************
Getting started
****************
This chapter should help you to get started with using EBAS Commandline.
It will guide you through some preparation (getting accounts and passwords),
help you to connect to an operational server with the EBAS programs installed,
and show you how to set up your environment to work with the EBAS Commandline
programs most conveniently.
Although you could install and use the EBAS Commandline programs on your local
computer (Linux, Windows or Mac OS X), the most convenient solution is to
connect to an operational server with the EBAS software already installed, and
use the software there.
The server *ratatoskr* is dedicated to users of EBAS Commandline, there is
always the latest release of the software installed.
Unless you are an EBAS software developer, don't bother installing EBAS on your
machine locally.
The rest of this chapter will focus on using *ratatoskr* as an application
server. Local installations are out of scope for this manual.
Preparation: getting credentials
================================
In order to use *EBAS Commandline* you will need several credentials on
different levels. Sometimes this might be confusing for new users, but those
levels of security have their reasons and will soon feel quite naturally.
Operating system user account
-----------------------------
The first level of authentication towards using EBAS Commandline programs is
logging in as a user on a computer with a working EBAS Commandline installation.
The Linux server *ratatoskr* is a dedicated machine for interactive work with
EBAS Commandline tools. We recommend using this machine.
Before you can connect to ratatoskr, you need a user account. Most people at
NILU have such an account automatically (It's called the DMZ account or
*outside* account). If you are not sure, get in contact with
`IT support <support@nilu.no>`_ and ask for help.
For executing EBAS Commandline programs at *ratatoskr* you need to be a member
of the group *nilu* (which is also the default for NILU employees).
Database login
--------------
EBAS commandline programs need access to the relational database
behind EBAS in order to serve you with the stored data and metadata.
For getting access to this relational database, yet another username/password
combination is needed in the programs.
For getting such a *database login* please contact `PE <pe@nilu.no>`_.
.. _EBAS user account:
EBAS User account
-----------------
A third level of authentication is maintained inside the EBAS domain and governs
access to different datasets in EBAS.
This level of access is the same as the login mechanism in the
`EBAS Web Application <http://ebas.nilu.no>`_.
Access to :term:`datasets<Dataset>` is ruled by :term:`project` associations.
Each *EBAS user* has access to a defined set of :term:`projects <project>`.
For *EBAS Commandline* your EBAS user name will generally be the same as your
`operating system user account`_ (see :option:`dbUser` for ways to change this).
Connecting to ratatoskr
=======================
The easiest way to work with the EBAS commandline tools is to remotely connect
to the server *ratatoskr*. There is an operational installation of the latest
release of the software available for general use.
If you are not an EBAS developer, don't bother installing EBAS on your machine
locally.
Secure shell
------------
You need to use a *secure shell* (*ssh*) client program in order to connect to
ratatoskr. Secure shell clients handle a secured (encrypted) network connection
to the server and run a *shell* (command line interface program) on the server
which is relayed to your client computer commandline interface.
See :ref:`EbasCommandlineInterface` for more information.
When you use a UNIX like system on your computer (e.g. Linux, Mac OS X, BSD,
...), you most probably have already a secure shell program installed. Just
try this::
ssh your-dmz-username@ratatoskr
When you use a Windows machine, download *PuTTY* from the
`project home page <http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html>`_.
Be sure to have your `operating system user account`_ credentials ready in
order to connect to ratatoskr.
Setting up EBAS for your account
================================
After being connected to a shell on a computer having EBAS Commandline installed
(recommended server *ratatoskr*), you can continue customizing your account
for using EBAS Commandline.
.. _EbasCommandlineDatabaseAuthentication:
Database Authentication
-----------------------
EBAS Commandline programs need to authenticate themselves whenever accessing data
form the central EBAS database for you. See `database login`_
for more information.
Those login credentials are not
hard-coded in the EBAS programs, and are not stored in a central place. It's a
secret you share only with your EBAS commandline programs when you run them
(they won't remember).
Every user has to provide those credentials to the EBAS Commandline programs
when using them.
EBAS Commandline knows several alternative ways to obtain your database
credentials.
Interactive database login procedure
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The default procedure, if you did not setup one of the advanced procedures below
is that the EBAS Commandline programs would ask you for your database *username*
and *password* when they start up.
This way is chosen whenever EBAS has no other means to access your credentials.
To use this way of authentication, make sure you do *not* have a ``.netrc`` file
in your home directory. Additionally you should check that your
:ref:`configuration file<EBASCommandlineConfigurationFile>` does not contain
``dbUser`` and ``dbPasswd`` settings (if you use a configuration file).
Finally you just call any EBAS Commandline program without the ``--dbUser`` and
``--dbPasswd`` arguments.
The program will ask you for your database username and password and you can
provide them interactively. The password input will be hidden.
Example::
$ ebas_list_ds
user name for database ebas_new: myname
password for user myname at database ebas_new:
Semi-interactive database login procedure
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You can specify the database user name as a commandline argument ``--dbUser``.
Which means, the EBAS Commandline programs will only ask you for the password.
The same can be achieved by setting ``dbUser`` in your
:ref:`configuration file<EBASCommandlineConfigurationFile>` .
Example::
$ ebas_list_ds --dbUser myname
password for user myname at database ebas_new:
.. warning::
Please do **NOT** use the ``--dbPasswd`` argument!
On multi-user UNIX systems, each users is able to see the command used to
start any program on the system.
Therefore, including sensitive information in commands is generally
**strongly discouraged** on UNIX systems.
When the database password (argument ``--dbPasswd``) is omitted like in the
example above, the program will ask for the password interactivley and you
can enter the password in an invisible input field.
Automatic database login procedure (recommended)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This is the recommended way of transferring your database credentials to the
EBAS Commandline programs.
It uses a traditional authentication technique on UNIX systems: The netrc
authentication, which is simple to use, yet moderately secure.
Users put all their credentials in a file called ``.netrc`` in their home
directory and **make sure the file has only read access rights for the
respective user (no group or other access!)**.
Example for a *.netrc* file::
machine ebas_db
login myname
password *secret*
Example for *.netrc* access rights::
$ ls -al ~/.netrc
-rw------- 1 me group 223 Aug 25 2014 .netrc
Configuration file
==================
The final step for setting up your account for using EBAS is to generate a
configuration file.
This step is not mandatory, but a configuration file is convenient if you want
to set defaults for your EBAS commandline programs.
See :ref:`EBASCommandlineConfigurationFile` for more information.