1. RED-PSS Guide

The RED Process Stack (RED-PSS) is the automation stack of the RED framework. It runs on a dedicated RED server based on Red Hat Enterprise Linux (RHEL) or Oracle Linux, versions 8 and 9 (tested).

Since RED 4 every environment is self-contained: the RED tools and services are delivered as compiled native executables. No separate Java, Python, or OpenSSL installation is required on the server. For installation and upgrades see the RED TV Deployment Guide.

RED-PSS is part of the RED Automation Module (see Automation Module).


1.1. RED-PSS Environment

1.1.1. Instances

A RED server may contain multiple independent RED-PSS instances (environments). Each instance controls one dedicated Exasol database with its corresponding RED Metadata Dictionary (RED-MDD). Different instances may run different versions.

1.1.2. Directory Structure

/app
├── exasol
│   ├── bin
│   ├── etc
│   └── ...
├── redftp
│   ├── bin
│   └── env
│       └── <instance>
│           └── <user>
└── redsys
    ├── bin
    ├── env
    │   ├── .seed
    │   └── <instance>
    │       ├── bin
    │       ├── cmd
    │       ├── cust
    │       ├── data
    │       ├── etc
    │       ├── lib
    │       ├── log
    │       ├── src
    │       └── tmp
    ├── etc
    ├── lib
    ├── log
    └── tmp

1.1.2.1. redsys Directory Tree

This tree contains the complete RED-PSS installation. All objects are owned by the user redsys.

redsys/bin, redsys/etc, redsys/lib, redsys/log, redsys/tmp

Tools, configuration, and logs for administration tasks that are not specific to an instance.

redsys/env/.seed

Template from which new instances are created and existing instances are upgraded.

redsys/env/<instance>

One directory per instance, each with the same subtree. Its content depends on the Technical Version (TV) of the instance.

redsys/env/<instance>/data

Landing zone for files.

1.1.2.2. redftp Directory Tree

redftp/bin

Administration tools for sFTP users.

redftp/env/<instance>/<user>

Home directory (change root) of an sFTP user of the instance. Both the instance directory and the user home directories are owned by root.

1.1.3. Environment Variables

VARIABLE

DESCRIPTION

REDHOME

/app/redsys

REDENV

the current instance (upper case)

REDENV_HOME

$REDHOME/env/


1.2. Security

1.2.1. Application Management

For administration purposes the Application Manager switches to the user redsys and enters the environment of the target instance:

Example: Enter an Environment

[user@red01 ~]$ sudo su - redsys
[redsys@red01 ~]$ tst1
---------------------------------
current environment: TST1
exit with CTRL-D
---------------------------------
TST1 [redsys@red01 tst1]$ pwd
/app/redsys/env/tst1

1.2.2. sFTP Users

External systems deliver files via sFTP. Each sFTP user belongs to exactly one instance:

  • User names follow the pattern redftp_<instance>_<user> (lower case). The <user> part must neither start with redftp nor contain the instance name.

  • Users are bound to the UID range 1200 – 1299 and share the group redftp (GID 1200) with redsys.

  • Authentication is by public key only.

  • Each user is locked into a change root environment (its home directory /app/redftp/env/<instance>/<user>). Files are uploaded into the subdirectory upload.

  • The upload directory is available to the instance as $REDENV_HOME/data/input/<user>.

sFTP users are restricted as follows:

  • sFTP access only: no login shell, no TCP or X11 forwarding.

  • Uploaded files are group-writable (umask 0002), so that redsys can process them.

  • All sFTP activity is logged to syslog (facility LOCAL6, level INFO).

1.2.2.1. Adding and Removing sFTP Users

The commands may be executed as redsys or root:

Example: Add an sFTP User

redftp_useradd -k /tmp/id_rsa.pub tst1 sap

This creates the user redftp_tst1_sap with the public key from /tmp/id_rsa.pub.

Example: Remove an sFTP User

redftp_userdel tst1 sap

Warning

redftp_userdel deletes the home directory of the user including all uploaded files that have not been processed yet.

1.2.2.2. SSH Daemon Configuration

The installer deploys the sFTP settings to /etc/ssh/sshd_config.d/98-red.conf, but it does not modify the main configuration file. The following manual changes in /etc/ssh/sshd_config are required once per server:

  1. Comment out the default sFTP subsystem:

    # Subsystem sftp /usr/libexec/openssh/sftp-server
    
  2. Make sure that the drop-in directory is included (add it as last line if missing):

    Include /etc/ssh/sshd_config.d/*.conf
    
  3. Check the configuration and reload the SSH daemon:

    sshd -t && systemctl reload sshd
    

redftp_useradd verifies the configuration and fails if the change root environment is not active.

1.2.3. REST API

The REST API is available via HTTPS only. Certificate and private key are taken from $REDENV_HOME/etc/ssl/REST:

  • certificate.pem

  • private_key.pem

RED Vision uses the same certificates (etc/ssl/VIS is a link to etc/ssl/REST).

If the files are missing, expired, or do not match, restctl start and visctl start create a self-signed certificate (valid for 10 years) and log a warning; existing files are kept as *.pem.<timestamp>.bak. A valid certificate, e.g. issued by a CA, is never replaced.

Note

Browsers warn about self-signed certificates. To use a CA-issued certificate, overwrite both files and restart the REST API and RED Vision (restctl restart, visctl restart).


1.3. Start and Stop of RED-PSS

The complete stack is started automatically on server start-up by systemd (redsys.service). Only instances where the (empty) file $REDENV_HOME/.autostart exists are started.

redsys.service calls $REDHOME/bin/redsysctl, which can also be used by redsys to start and stop one or all instances:

DEV1 [redsys@red01 bin]$ redsysctl -h
USAGE:

Manage the current instance (uses REDENV):
redsysctl {start | stop | status | restart}

Manage a specific instance:
redsysctl {start | stop | status | restart} <instance>

Start/stop all instances:
redsysctl {start-all | stop-all | restart-all | status-all}

For each instance redsysctl calls redctl (RED-PSS services), restctl (REST API), and visctl (RED Vision).

1.3.1. Licence File

Each environment instance needs a valid RED licence. The licence file (*.lic) is provided by Sphinx IT Consulting.

  • Place the licence file in the directory $REDENV_HOME/etc of the instance, readable by the user redsys.

  • Exactly one *.lic file must exist in this directory. When renewing the licence, replace the old file instead of adding a second one.

The licence limits either the RAM or the raw data size; the limit must be at least the corresponding limit of the Exasol licence. A licence can also be issued as Unlimited, which covers any Exasol limit.

The licence is checked when RED-PSS starts, daily at about 8:00, and when the DB jobs are resumed. If the licence is missing, invalid, or expired, all DB jobs are suspended, and resuming them is rejected until a valid licence file is in place.

With redctl check -l a new licence file can be verified before the DB jobs are resumed. The check is read-only and does not suspend any jobs.

Example: Renew the Licence

TST1 [redsys@red01 tst1]$ mv etc/<old licence>.lic /tmp/
TST1 [redsys@red01 tst1]$ cp /tmp/<new licence>.lic etc/
TST1 [redsys@red01 tst1]$ redctl check -l
TST1 [redsys@red01 tst1]$ redctl resume

The licence status (validity, expiration date, licensed limits) is shown in REDSYS.STA_RED_LICENSE_INFO and on the licence page of RED Vision. Its column ALERT is 1 if the licence expires within 30 days and 2 if it expires within 10 days, has expired, or is invalid; monitor it to renew the licence in time.

1.3.2. Suspended Mode

redctl can be started in suspended mode with option -S. In this case all DB jobs and watchers remain suspended, so no load processes are executed. All other services are up and running.

The suspended mode is ended with redctl resume or by restarting redctl without -S.

1.3.3. Cloning a Database into an Existing Environment

Before the Exasol database of an instance is replaced (e.g. by restoring a backup of another database) you must execute redctl preclone. This

  • stops the RED-PSS services,

  • saves important data (e.g. the REST users) in $REDENV_HOME/tmp/preclone,

  • removes all password wallets of the instance, including the REST wallet.

preclone fails if $REDENV_HOME/tmp/preclone already exists. REST API and RED Vision are not stopped.

On the next start redctl restores the saved data into the clone and cleans up all logs in the database and on the filesystem.

Important

After the restore of the clone the SYS user must reset the passwords for REDSYS and TU_REST to their default values and truncate the audit logs. The DBA may use the script $REDENV_HOME/etc/postclone.sql as is.

In addition the SYS password itself should be changed.


1.4. Command Line Tools

1.4.1. redctl

redctl is the main command line utility of RED-PSS. It starts and stops the RED-PSS services of an instance and manages DB jobs and watchers.

redctl [-h] command [command-options]

COMMAND

OPTIONS

DESCRIPTION

version

show versions of database, TV, and BV

start

-S

start all services; -S: DB jobs suspended

start_trace

-S

like start, with output on STDOUT and STDERR

stop

stop all services gracefully

abort

kill all services immediately

restart

-S

restart all services

status

show the status of the services

reload

reload the job configuration

suspend

suspend all DB jobs

resume

resume all DB jobs

show

{jobs,ps}

show scheduled jobs or RED processes

watch

{jobs,ps} [-i SECONDS]

like show, refreshed every -i seconds (default 5)

we_list_error

[-s SCHEMA] [-w WATCHER] [-j JOB]

list errors of watcher executors

we_reset_error

-s SCHEMA [-w WATCHER] [-j JOB]

reset errors of watcher executors (reschedule)

start_db_job

-s SCHEMA -j JOB

start a DB job immediately

list_db_jobs

[-s SCHEMA]

list DB jobs

toggle_db_job

-s SCHEMA -j JOB (-a | -i)

set a DB job active (-a) or inactive (-i)

list_db_watcher

[-s SCHEMA]

list DB watchers

toggle_db_watcher

-s SCHEMA -j WATCHER (-a | -i)

set a DB watcher active (-a) or inactive (-i)

start_job

-j JOB_ID

start an already scheduled job immediately

preclone

save the state before the database is replaced by a clone

check

[-l | -o]

read-only check of the licence and the framework objects, no job suspension; -l: licence only, -o: objects only

redctl check does not need running services and writes nothing. It lists framework objects that differ from the delivered technical version or are missing. Exit code: 0 all checks OK, 1 licence check failed, 2 only the object check failed.

Example: redctl

redctl start -S
redctl watch ps -i 10
redctl toggle_db_job -s SCURTY -j rep_refresh -i
redctl we_list_error -s CFIADM
redctl check

1.4.2. restctl

restctl starts and stops the application server of the REST API.

restctl {start | stop | restart | status}

1.4.3. visctl

visctl starts and stops RED Vision, the web GUI of RED, together with its background cache process.

visctl {start | stop | restart | status}

1.4.4. redenv_info

redenv_info prints a summary of the current environment: TV and BV, database connection, status of RED-PSS, REST API and RED Vision, autostart setting, and the configured ports. With option -p only the port assignments are printed.


1.5. Process Architecture

1.5.1. JMON

The job monitor reads the views REDSYS.ALL_ADM_JOBS and REDSYS.ALL_ADM_WATCHER every 60 seconds and schedules the jobs and watchers defined therein. New, changed, activated, or deactivated jobs and watchers are picked up automatically within this cycle. JMON also processes the suspend and resume commands and writes statistics into REDSYS.ADM_JMON_LOAD and REDSYS.ADM_JMON_JOBLOG.

When a job or watcher is due, JMON hands it over to the scheduler (SCHED), which executes it in a worker pool.

1.5.2. SCHED

The scheduler runs jobs in four worker pools:

  • D – default pool for DB jobs and watchers (sched_default_pool_size)

  • L – loader pool for all load processes (sched_loader_pool_size)

  • A – action pool for application actions (sched_action_pool_size)

  • C – CDC group worker pool (sched_cdcg_w_pool_size)

Jobs and watchers log information into ADM_JOB_LOG and ADM_WATCHER_LOG of the target schema. Watcher executor errors are logged into ADM_WATCHER_EXEC_ERROR.

1.5.3. DBLS

The database log server receives log messages from the database and writes them into $REDENV_HOME/log/DB/<SCHEMA>. Errors and alerts are recorded in the database table LOG_MESSAGES of the schema as well.

1.5.4. JEXEC

The job executor runs external jobs as defined in an application action. Based on the action definition the corresponding script in $REDENV_HOME/cmd is executed.

1.5.5. SEXEC

The script executor runs LUA scripts as defined in an application action.

1.5.6. CFISRV

The CFI server presents files in the data tree to the RED framework in the database. Internally it uses the FTPS protocol for communication with the database. CFISRV is optional and can be deactivated (cfi_enabled).

1.5.7. JSON2CSV

The JSON-to-CSV process converts JSON input files into CSV format before they are processed by CFISRV. JSON2CSV is active only if CFISRV is active.

1.5.8. PARQ2CSV

The Parquet-to-CSV process converts Parquet input files into CSV format before they are processed by CFISRV. PARQ2CSV is active only if CFISRV is active.

1.5.9. SENDMAIL

The sendmail server sends messages received from the database to the configured mail relay.

1.5.10. SENDFILE

The sendfile server exports a CSV or Parquet file from a table or view in the database and sends it via mail or sFTP to the defined destination.

1.5.11. MAIL2CMD

The mail-to-command interface receives mails and passes them to the RED framework. MAIL2CMD is optional and can be deactivated (mail2cmd_enabled).

1.5.12. REST API

The REST API server provides the RED REST interface via HTTPS. It is controlled by restctl.

1.5.13. RED Vision

RED Vision is the web GUI of RED. It consists of a web server and a cache process that periodically refreshes the dashboard data from the database. It is controlled by visctl.


1.6. Configuration

The configuration of an instance is stored in $REDENV_HOME/etc/red_params.conf. Parameters of the [DEFAULT] section apply to all other sections unless they are overridden there. Changes take effect after restarting the affected service (redctl, restctl, or visctl).

For host parameters (service_host, gu_host, vis_host) the values 0.0.0.0, localhost, and 127.0.0.1 resolve to the primary IP address of the server.

1.6.1. [DEFAULT] Section

PARAMETER

DESCRIPTION

log_level

DEBUG, INFO, WARNING, ERROR

exa_connection

Exasol connection string (DSN)

exa_dbname

database name; installations abort if the connected database has a different name

1.6.2. [redctl] Section

PARAMETER

DESCRIPTION

service_base_port

base port for internal services (reserve at least 10 ports per instance)

service_host

IP address or host name for internal services

node_ip_list

comma-separated IP addresses of the Exasol nodes that may connect to the internal services, e.g. 10.0.3.4…5

sched_default_pool_size

number of workers in the default pool

sched_loader_pool_size

number of workers in the loader pool

sched_action_pool_size

number of workers in the action pool

sched_cdcg_w_pool_size

number of workers in the CDC group worker pool

wetx_zombie_tmout

seconds after which a lost watcher executor is reset (default 7200)

sendmail_smtp_host

SMTP server (mail relay) for outgoing mails

sendmail_smtp_port

port of the SMTP server

sendmail_smtp_encr

transport encryption for outgoing mails: STARTTLS (with login) or PLAIN (no TLS, no login)

sendmail_smtp_user

SMTP login user (STARTTLS only)

sendmail_smtp_pass

SMTP password (STARTTLS only); may be Base64-encoded as e’’

sendmail_smtp_from

sender address for outgoing mails

sendmail_env_desc

environment label used in mails

cfi_enabled

enable or disable CFISRV, JSON2CSV, and PARQ2CSV: true/false

cfi_pasv_port_start

start of the passive FTP port range (optional)

cfi_pasv_port_end

end of the passive FTP port range (optional)

json2csv_json_suffix

suffix of incoming JSON files

json2csv_csv_suffix

suffix of converted CSV files

json2csv_retention

retention (in days) of JSON input files

parq2csv_parq_suffix

suffix of incoming Parquet files

parq2csv_csv_suffix

suffix of converted CSV files

parq2csv_retention

retention (in days) of Parquet input files

mail2cmd_enabled

enable or disable MAIL2CMD: true/false

mail2cmd_host

listener address of MAIL2CMD

mail2cmd_port

listener port of MAIL2CMD

log_retention

retention (in days) of all log files in $REDENV_HOME/log

log_level

log level for all RED-PSS services

Note

red_params.conf contains secrets such as the SMTP password. The Base64 form of sendmail_smtp_pass is an obfuscation, not an encryption.

1.6.3. [REST] Section

PARAMETER

DESCRIPTION

gu_host

listener interface of the REST API

gu_port

listener port of the REST API

gu_workers

number of workers

gu_timeout

worker timeout in seconds (default 30)

jwt

true: impersonation via JWT; false: via API key (default false)

expiration

JWT expiration in minutes (default 1)

log_level

log level for the REST API

1.6.4. [REDVIS] Section

PARAMETER

DESCRIPTION

vis_host

listener interface of RED Vision (default 0.0.0.0)

vis_port

listener port of RED Vision (default 8080)

vis_workers

number of workers (default 4)

vis_timeout

worker timeout in seconds (default 180)

ssl_enabled

true: HTTPS with the certificates in $REDENV_HOME/etc/ssl/VIS; a self-signed certificate is created if they are missing or invalid (default false)

cache_interval

refresh interval of the dashboard cache in seconds (default 30)

llm_tls_verify

verify the TLS certificate of the LLM endpoint (default true)

llm_ca_bundle

CA bundle file for the LLM endpoint, e.g. a corporate proxy CA

log_level

log level for RED Vision

1.6.5. [REDLIN] Section

PARAMETER

DESCRIPTION

num_processes

number of worker processes for lineage harvesting (default 1)

max_task_per_child

views per worker process before it is replaced (default 50)

max_worker_memory_mb

additional memory in MB per worker process; a view exceeding it is reported as failed and skipped (default 0 = unlimited)

trim_selects

true: legacy parsing mode with high memory usage (default false)

push

list of push targets, e.g. [‘dataspot_interface’]

log_level

log level for data lineage


1.7. Logging

All logs of an instance are stored in $REDENV_HOME/log.

LOCATION

CONTENT

redctl.log

RED-PSS services and JMON

DB/

database logs per target schema

REST

REST API (restctl, server, and access logs)

redvis

RED Vision (visctl, server, access, and cache logs)

ERROR and ALERT messages of database processes (i.e. LUA scripts) are also written into the LOG_MESSAGES table of the respective schema. All log messages of all schemas are available in REDSYS.ALL_LOG_MESSAGES.


1.8. Monitoring Views

The status of RED-PSS can be queried directly from the database:

  • REDSYS.ALL_ADM_JOBS

  • REDSYS.ALL_ADM_JOB_LOG

  • REDSYS.ALL_ADM_JOB_STATS

  • REDSYS.ALL_ADM_JOB_STATUS

  • REDSYS.ALL_ADM_WATCHER

  • REDSYS.ALL_ADM_WATCHER_EXEC_ERROR

  • REDSYS.ALL_ADM_WATCHER_EXEC_STATUS

  • REDSYS.ALL_ADM_WATCHER_LOG

  • REDSYS.ALL_ADM_WATCHER_STATUS

  • REDSYS.ALL_LOG_MESSAGES