Login Credentials

The iquery client program is a command line tool for issuing SciDB queries.  When SciDB is running in security mode, iquery must present login credentials (that is, username and password) in order to establish a database connection.  You specify login credentials using an authentication file.  If iquery cannot find an authentication file, or if it finds an authentication file containing a user-name entry but no user-password entry, it prompts you for a password on the terminal.

Legal Usernames

A valid username must meet these criteria:

• Cannot be empty.
• Cannot exceed 256 bytes in length.
• Must not contain whitespace.
• Must not contain control characters.
• Must not begin with a decimal digit.
• May contain hyphens (-, ASCII 0x2D) and underscores (_, ASCII 0x5F), but not at the beginning or end of the name.  No other punctuation is allowed.
• Must contain only 7-bit ASCII characters.

These same rules also apply to role names.

Legal Passwords

A valid password must meet these criteria:

• Cannot be empty.
• Cannot exceed 256 bytes in length.
• Must not contain control characters.
• Must contain only 7-bit ASCII characters.

Authentication File Format

SciDB authentication files may be in either of two formats: JSON or INI.  JSON is the preferred format.  The iquery program first tries to parse an authentication file as JSON, and if that fails, it tries to parse it as INI.

Both formats are case-sensitive.

JSON authentication files

Here is a sample JSON authentication file containing the factory default credentials for the scidbadmin user:

{
  "user-name": "scidbadmin",
  "user-password": "Paradigm4"
}

If your password contains characters that would cause a JSON parse error, you must escape them with backslashes.

INI authentication files

For compatibility with prior releases, iquery supports the INI authentication file format.

Here is an INI format authentication file containing the factory default credentials for the scidbadmin user:

[security_password]
user-name=scidbadmin
user-password=Paradigm4

How iquery Locates Authentication Files

The iquery program first looks for its authentication file on the command line, then tries to get it from an environment variable, and finally looks for it in a default location in your home directory.

Command line option: -A/--auth-file

You can specify a particular authentication file directly on the iquery command line using the -A/--auth-file command line option.  For example:

$ cat /tmp/alice.auth
{ "user-name": "alice", "user-password": "big secret" }
$ iquery -A /tmp/alice.auth -aq "show_user()"
{i} name
{0} 'alice'
$

Environment variable: SCIDB_AUTH_FILE

If no command line option is given, iquery next examines the value of the SCIDB_AUTH_FILE environment variable and uses its value as the name of the authentication file:

$ export SCIDB_AUTH_FILE=/tmp/alice.auth
$ iquery -aq "show_user()"
{i} name
{0} 'alice'
$

Default location: $HOME/.config/scidb/iquery.auth

If no explicit command line option is given and the SCIDB_AUTH_FILE environment variable is not set, iquery tries to use $HOME/.config/scidb/iquery.auth as the authentication file:

$ unset SCIDB_AUTH_FILE
$ cp /tmp/alice.auth ~/.config/scidb/iquery.auth
$ iquery -aq "show_user()"
{i} name
{0} 'alice'
$

Entering Passwords Via The Terminal

If iquery needs a password to connect to SciDB and none can be found in an authentication file, it prompts for a password on the terminal using getpass(3).

If iquery found an authentication file with only a user-name entry but no user-password entry, it uses that user name when connecting to the database.  Otherwise, if it finds no authentication file, it uses the name of the logged in user, taken from the $USER environment variable.

You have a limited time to respond to the password prompt before SciDB closes iquery's TCP connection.  The timeout is given by the SciDB client-auth-timeout configuration parameter.

About iquery Examples In The Security Documentation

Specifying the -A/--auth-file iquery command line option in every example quickly becomes tedious and distracts from the teaching value of the example.  The examples in the Security section assume that a proper $HOME/.config/scidb/iquery.auth authentication file is already set up, and forego mention of it unless it is directly relevant to the point of the example.