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/tmpTools, configuration, and logs for administration tasks that are not specific to an instance.
redsys/env/.seedTemplate 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>/dataLanding zone for files.
1.1.2.2. redftp Directory Tree¶
redftp/binAdministration 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 withredftpnor contain the instance name.Users are bound to the UID range 1200 – 1299 and share the group
redftp(GID 1200) withredsys.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 subdirectoryupload.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 thatredsyscan process them.All sFTP activity is logged to syslog (facility
LOCAL6, levelINFO).
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:
Comment out the default sFTP subsystem:
# Subsystem sftp /usr/libexec/openssh/sftp-server
Make sure that the drop-in directory is included (add it as last line if missing):
Include /etc/ssh/sshd_config.d/*.conf
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.pemprivate_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/etcof the instance, readable by the userredsys.Exactly one
*.licfile 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_JOBSREDSYS.ALL_ADM_JOB_LOGREDSYS.ALL_ADM_JOB_STATSREDSYS.ALL_ADM_JOB_STATUSREDSYS.ALL_ADM_WATCHERREDSYS.ALL_ADM_WATCHER_EXEC_ERRORREDSYS.ALL_ADM_WATCHER_EXEC_STATUSREDSYS.ALL_ADM_WATCHER_LOGREDSYS.ALL_ADM_WATCHER_STATUSREDSYS.ALL_LOG_MESSAGES