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

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. Access to datasets is ruled by project associations. Each EBAS user has access to a defined set of projects.

For EBAS Commandline your EBAS user name will generally be the same as your operating system user account (see 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 Commandline interface 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.

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.

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

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.

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 Configuration file for more information.