Configuration¶

Most of the choices that HyperShell makes about timing, task bundling, coordination, logging, and such are configurable by the user. This configuration is loaded when the program starts and is constructed from several sources including an ordered merger of files, environment variables, and command-line options.

In order of precedence (lowest to highest), three files are loaded for system, user and local configuration. See below the section on file system paths for more details.

On Linux (for example):

Site	Path (Linux / POSIX)
System	`/etc/hypershell.toml`
User	`~/.hypershell/config.toml`
Local	`./.hypershell/config.toml`

The TOML format is modern and minimal.

Every configurable option can be set in one of these files. Further, every option can also be set by an environment variable, where the name aligns to the path to that option, delimited by underscores.

For example, set the logging level at the user level with a command:

Set user-level configuration option

hs config set logging.level info --user

The file should now look something like this:

~/.hypershell/config.toml

# File automatically created on 2022-07-02 11:57:29.332993
# Settings here are merged automatically with defaults and environment variables

[logging]
level = "info"

Alternatively, you can set an environment variable and the runtime configuration would be equivalent:

Define environment variable

export HYPERSHELL_LOGGING_LEVEL=INFO

Finally, any option defined within a configuration file that ends with _env or _eval is automatically expanded by the given environment variable or shell expression, respectively. This is useful as both a dynamic feature but also as a means to obfuscate sensitive information, such as database connection details.

~/.hypershell/config.toml

# File automatically created on 2022-07-02 11:57:29.332993
# Settings here are merged automatically with defaults and environment variables

[logging]
level = "info"

[database]
provider = "postgres"
database = "hypershell"
host = "my.instance.university.edu"
user = "me"
password_eval = "pass hypershell/database/password"  # Decrypt using GNU Pass

The edit command makes it easy to open the correct configuration file path for your platform using the default editor. Set the EDITOR environment variable (or VISUAL on Windows).

Open global user-level configuration file for editing

hs config edit --user

Filesystem Paths¶

The site refers to the locations on the file system from which configuration files are found and output files are written to. This entails a library (or lib) path for where to capture outputs; a log path for where to write logs and exceptions; and a config file path. There are two environment variables that play a role in modifying this behavior.

HYPERSHELL_SITE: The default site path for outputs is either the user or system site based on whether the program was run as root/admin. The local path is always the current working directory for the program. If this environment variable is set then it takes the place of the local site and used as the default.
HYPERSHELL_CONFIG_FILE: Under normal operations the program searches all three system, user, and local sites to load the full configuration in addition to all prefixed environment variables. This can actually cause issues for scenarios with many instances of the program running on the same file system, such as an HPC cluster. In order to protect against unintended crashes from incidental configuration changes, defining this environment variable specifies the one and only path to a configuration file and all others will be ignored. Setting this to empty results in no files being loaded (an environment only runtime).

The paths to these locations is platform specific. On Windows and macOS, the program abides by the conventions of that platform, just as on Linux (otherwise assumed POSIX). Below we have enumerated all variations with Library, Logs, and Config in each case.

Windows

System

%PROGRAMDATA%\HyperShell\Library
%PROGRAMDATA%\HyperShell\Logs
%PROGRAMDATA%\HyperShell\Config.toml

User

%APPDATA%\HyperShell\Library
%APPDATA%\HyperShell\Logs
%APPDATA%\HyperShell\Config.toml

Local

%HYPERSHELL_SITE%\Library
%HYPERSHELL_SITE%\Logs
%HYPERSHELL_SITE%\Config.toml

macOS

System

/Library/HyperShell
/Library/HyperShell/Logs
/Library/Preferences/HyperShell/config.toml

User

$HOME/Library/HyperShell
$HOME/Library/HyperShell/Logs
$HOME/Library/Preferences/HyperShell/config.toml

Local

$HYPERSHELL_SITE/Library
$HYPERSHELL_SITE/Logs
$HYPERSHELL_SITE/config.toml

Linux / POSIX

System

/var/lib/hypershell
/var/log/hypershell
/etc/hypershell.toml

User

$HOME/.hypershell/lib
$HOME/.hypershell/log
$HOME/.hypershell/config.toml

Local

$HYPERSHELL_SITE/lib
$HYPERSHELL_SITE/log
$HYPERSHELL_SITE/config.toml

Runtime Package Resolution¶

The following environment variable may be set to harden the installation against accidentally polluting the package resolution of HyperShell itself from user software.

HYPERSHELL_PYTHONPATH: As a Python application HyperShell may be exposed to PYTHONPATH. This can happen in instances where the user tasks themselves are Python based. To avoid possible collisions we can guard HyperShell by explicitly setting the path list (sys.path). This environment variable may be set in a similar fashion as the standard PYTHONPATH. Or it may instead contain a file path, in which case the content of the file should have one path per line.

Parameter Reference¶

[logging]

Logging configuration. See also logging section.

.level

One of TRACE, DEBUG, INFO, WARNING, ERROR, or CRITICAL (default: INFO)

INFO level messages are reserved for clients when tasks begin running. There are numerous WARNING events (e.g., non-zero exit status of a task). DEBUG level messages signal component thread start/stop and individual task level behavior. TRACE contains detailed information on all other behavior, particular iterative messages while components are waiting for something.

ERROR messages track when things fail but the application can continue; e.g., when command template expansion fails on an individual task.

CRITICAL messages are emitted when the application will halt or crash. Some of these are expected (such as incorrect command-line arguments) but in the event of an uncaught exception within the application a full traceback is written to a file and logged.

.datefmt

Date/time format, standard codes apply (default: '%Y-%m-%d %H:%M:%S'`)

.format

Log message format.

Default set by the “default” logging.style. See the available attributes defined by the underlying Python logging interface.

Additional attributes provided beyond the standard include app_id, hostname, hostname_short, relative_name, time formats in elapsed, elapsed_ms, elapsed_delta, and elapsed_hms, as well as all ANSI colors and formats as ansi_x where x is one of reset, bold, faint, italic, underline, black, red, green, yellow, blue, magenta, cyan, white, and ansi_level contains the standard color for the current message severity level.

.style

Presets for logging.format which can be difficult to define correctly. Options are default, detailed, detailed-compact, system, and short.

.color

Enable ANSI color and formatting in console output (default: true).

Colors are emitted only when stderr is a TTY and are always stripped from file-based logs. See also the NO_COLOR and FORCE_COLOR environment variables.

[file]

File-based logging (disabled unless at least one parameter is set). See the logging section for full details on rotation and compression.

As a shorthand, logging.file may be set directly to "enabled" (or true) to log to the default per-process file, or to a path to log there; both forms disable rotation and compression.

.path: Destination file path. Defaults to a per-process, host-scoped file in the site log directory (e.g. server-<host>.log, client-<host>.log, or main.log). Parent directories are created as needed.
.level: Minimum severity written to the file (default: TRACE). Accepts the same names as logging.level, independent of the console level.
.style: Format preset for the file (default: system). Accepts the same options as logging.style; a format may be given instead. ANSI color is always stripped.
.rotate: Rotation policy (default: never). Either a size threshold such as 512MB (units KB/MB/GB/TB, powers of 1024; a bare number is bytes) or a cron expression such as @daily, @midnight, or 0 1 * * 0 (requires the croniter package). Sending SIGHUP rotates on demand.
.compress: Compression for rotated files (default: none). One of gzip, bzip, lzma, or zstd (the last requires the optional zstandard package). Extensions .gz, .bz2, .xz, and .zstd respectively.
.keep: Number of uncompressed rotated files to retain (default: 0). Only applies when compression is enabled; without compression, rotated files are never deleted.

[database]

Database configuration and connection details. See also database section.

.url

Full database connection URL (default: none).

When provided, this takes precedence over and short-circuits the individual .provider/.host/.port/.user/.password fields below.

.provider

Database provider (default: ‘sqlite’). Supported alternatives include ‘postgres’ (or compatible). Support for other providers may be considered in the future.

.file

Only applicable for SQLite provider. SQLite does not understand any other connection detail.

.database

Name for database. Not applicable for SQLite.

.schema

Not applicable for all RDMS providers. For Postgres the default schema is public. Specifying the schema may be useful for having multiple instances within the same database.

.host

Hostname or address of database server (default: localhost).

.port

Port number to connect with database server. The default value depends on the provider, e.g., 5432 for Postgres.

.user

Username for databaser server account. If provided a password must also be provided. Default is the local account.

.password

Password for database server account. If provided a user must also be provided. Default is the local account.

Task Environment¶

A few common environment variables are defined for every task.

TASK_ID: Universal identifier (UUID) for the current task.
TASK_ARGS: Original input command-line argument line. Equivalent to {}, see templates section.
TASK_SUBMIT_ID: Universal identifier (UUID) for submitting application instance.
TASK_SUBMIT_HOST: Hostname of submitting application instance.
TASK_SUBMIT_TIME: Timestamp task was submitted.
TASK_SERVER_ID: Universal identifier (UUID) for server application instance.
TASK_SERVER_HOST: Hostname of server application instance.
TASK_SCHEDULE_TIME: Timestamp task was scheduled by server.
TASK_CLIENT_ID: Universal identifier (UUID) for client application instance.
TASK_CLIENT_HOST: Hostname of client application instance.
TASK_COMMAND: Final command line for task.
TASK_ATTEMPT: Integer number of attempts for current task (starts at 1).
TASK_PREVIOUS_ID: Universal identifier (UUID) for previous attempt (if any).
TASK_CWD: Current working directory for the current task.
TASK_START_TIME: Timestamp task began execution.
TASK_WAITED: Time in seconds between task submit time and schedule time.
TASK_OUTPATH: Absolute file path where standard output is directed (if defined).
TASK_ERRPATH: Absolute file path where standard error is directed (if defined).

Any user-defined tags are included as environment variables as well with TASK_TAG_ as a prefix. For example, some tag site:us-west-1 would be exposed as TASK_TAG_SITE=us-west-1.

Further, any environment variable defined by the user with HYPERSHELL_EXPORT_ will be injected into the task environment sans prefix; e.g., HYPERSHELL_EXPORT_FOO would define FOO in the task environment. You can also define such variables in the export section of your configuration file(s); e.g.,

~/.hypershell/config.toml

# File automatically created on 2022-07-02 11:57:29.332993
# Settings here are merged automatically with defaults and environment variables

[logging]
level = "info"

# Options defined as a list will be joined with a ":" on BSD/Linux or ";" on Windows
# Environment variables will be in all-caps (e.g., FOO and PATH).
[export]
foo = "value"
path = ["/some/bin", "/some/other/bin"]

We also respect setting the following environment variables to force disable/enable the use of colors in all console output.

NO_COLOR: If this variable is set to anything but a blank string, all colors are disabled. See no-color.org for details.
FORCE_COLOR: If this variable is set to anything but a blank string, colors will be enabled regardless of whether stdout or stderr are a TTY.

Signals¶

HyperShell traps the following UNIX signals (does not apply on Microsoft Windows).

SIGUSR1: Sending the SIGUSR1 signal will trigger the schedulers to halt and begin shutdown procedures. On the client side, this means that all current tasks (and any in the local queue) will be allowed to complete, but the system will drain and shutdown at the completion of these tasks.
SIGUSR2: Sending the SIGUSR2 signal implies the same, but on the client side will set a flag to send local interrupts to tasks to come down faster. As described in the previous release with regard to the task.timeout feature, we send SIGINT, SIGTERM, and SIGKILL in an escalating fashion to halt running tasks.
SIGHUP: Sending the SIGHUP signal triggers an immediate rotation of the process’s log file, when file-based logging is enabled. This is the conventional way to rotate logs on demand from an external tool. See the logging section.