3. omnidb-server Usability¶
omnidb-server
comes with several command line arguments to facilitate usage:
Usage: omnidb-server [options]
Options:
--version show program's version number and exit
-h, --help show this help message and exit
General Options:
-d HOMEDIR, --homedir=HOMEDIR
home directory containing config and log files
-C CONF, --configfile=CONF
configuration file
-i, --init Create home directory containing config and log files
Webserver Options:
-H HOST, --host=HOST
listening address
-p PORT, --port=PORT
listening port
-P PATH, --path=PATH
path to access the application, other than /
Management Options:
Options to list, create and drop users and connections.
-M dbfile, --migratedatabase=dbfile
migrate users and connections from OmniDB 2 to 3: -M
dbfile
-r, --resetdatabase
reset user and session databases
-j, --jsonoutput format list output as json
-l, --listusers list users
-u username password, --createuser=username password
create user: -u username password
-s username password, --createsuperuser=username password
create super user: -s username password
-x username, --dropuser=username
drop user: -x username
-m username, --listconnections=username
list connections: -m username
-c username technology title host port database dbuser, --createconnection=username technology title host port database dbuser
create connection: -c username technology host port
database dbuser
-z connid, --dropconnection=connid
drop connection: -z connid
General Options
: Options to provision/specify configuration and directory locations.Webserver Options
: Webserver related settings.Management Options
: Several options to manage the currently configured backend database.
3.1. OmniDB User Files¶
omnidb-server
is supposed to be pointed to a directory that contains files
being used at execution time:
config.py
: Configuration file.omnidb.db
: Local database containing user session data and also OmniDB related metadata, if the user decides to deploy OmniDB using SQLite as backend database.omnidb.log
: Log file, automatically rotated.
A directory is specified with: omnidb-server -d /path/to/dir
. If not specified,
OmniDB will use the default ~/.omnidb/omnidb-server
.
When running omnidb-server
for the first time, or pointing to a directory that
does not contain existing files, OmniDB
will create them for you and run. Users
may prefer to run first omnidb-server --init
, which will just create the default
files allowing you can adjust settings before starting the application.
3.2. OmniDB Backend Database¶
OmniDB requires a database to store its metadata, containing user and connection details.
By default OmniDB uses SQLite, and will store its data in file omnidb.db
located
in the target runtime directory explained in the previous section.
Version 3.0 introduces the ability to deploy OmniDB using PostgreSQL
as the backend
database. This can be achieved by configuring config.py
with the following section:
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.postgresql_psycopg2',
'NAME': 'dbname',
'USER': 'postgres',
'PASSWORD': '',
'HOST': '127.0.0.1',
'PORT': '5432',
}
}
Adjust the connection parameters accordingly.
When running omnidb-server
, the target database will be configured and migrations
will be executed to create required objects.
3.3. Authentication Methods¶
By default OmniDB authenticates users using its backend database.
OmniDB 3 introduces the ability to use different authentication methods. Version
3.0.0 comes with AD/LDAP
, which is enabled by adding the following section in
config.py
:
import ldap
import django_auth_ldap.config
from django_auth_ldap.config import LDAPSearch
AUTH_LDAP_SERVER_URI = 'SERVER'
AUTH_LDAP_BIND_DN = "uid=example,dc=example,dc=com"
AUTH_LDAP_BIND_PASSWORD = "password"
AUTH_LDAP_USER_SEARCH = django_auth_ldap.config.LDAPSearch(
"uid=example,dc=example,dc=com", ldap.SCOPE_SUBTREE, "uid=%(user)s"
)
AUTHENTICATION_BACKENDS = [
'django_auth_ldap.backend.LDAPBackend',
'django.contrib.auth.backends.ModelBackend'
]
Parameters must be adjusted according to the LDAP server being used.
OmniDB’s LDAP
authentication uses django-auth-ldap
library, which contains several
customization options. More details in: https://django-auth-ldap.readthedocs.io/en/latest/
If additional settings are needed, just amend config.py
accordingly.
3.4. OmniDB Configuration File¶
Apart from database and authentication settings, the configuration file (config.py
)
contains all settings required to properly deploy OmniDB according to the user’s
environment.
LISTENING_ADDRESS
: specifies in what address the server will listen, the default value is127.0.0.1
.LISTENNING_PORT
: specifies in what port OmniDB server will listen, this is the port used in the browser’s URL if OmniDB is being accessed directly. The default value is8000
.CUSTOM_PATH
: specifies a custom path to access OmniDB in the browser URL. The default value is empty, meaning that no custom path is used. If user specifies'test'
in this setting, OmniDB will be accessible withhttp://127.0.0.1:8000/test
. This setting is useful when OmniDB is configured behindApache
orNGINX
, so that all requests to theCUSTOM_PATH
can be easily redirected to OmniDB.IS_SSL
,SSL_CERTIFICATE_FILE
,SSL_KEY_FILE
: settings to configure SSL connection. IfIS_SSL
isTrue
then certificate and key files must be provided.
The previous settings are enough to securely provision omnidb-server
. The Configuration
file contains additional settings for environments with additional configuration
requirements.