Configuration

The Scrippy main configuration file is a YAML file defining the directories used by Scrippy and by the scripts written with it.

Table of content

• The main configuration file
• Configuration files and precedence
• The Scrippy directories
• Scripts executed with elevated privileges

The main configuration file

The main configuration file defines the seven Scrippy directories in its env section:

env:
  confdir: /home/luiggi/.local/share/scrippy/conf
  datadir: /home/luiggi/.local/share/scrippy/data
  histdir: /home/luiggi/.local/share/scrippy/hist
  logdir: /home/luiggi/.local/share/scrippy/log
  reportdir: /home/luiggi/.local/share/scrippy/reports
  templatedir: /home/luiggi/.local/share/scrippy/templates
  tmpdir: /home/luiggi/.local/share/scrippy/tmp

• All seven keys are mandatory: A script fails at startup with a ScrippyCoreError: Missing configuration key: <key> error if any of them is not defined.
• Paths must be absolute: scrippy-core does not expand ~ nor environment variables. The installer writes absolute paths.
• Any other section (such as the packages section written by the installer) is ignored by the scripts.

Configuration files and precedence

At the start of each script, Scrippy looks for its main configuration file at the following locations:

When several files exist, they are merged key by key, in the order above: Each file only overrides the keys it defines, so that a file may define only a subset of the keys.

As a result:

• A user can override the vendor configuration.
• A user can not override a key defined in the system administrator configuration.

Example:

# /etc/scrippy/scrippy.yml (vendor)
env:
  confdir: /etc/scrippy/conf
  datadir: /etc/scrippy/data
  histdir: /etc/scrippy/hist
  logdir: /etc/scrippy/log
  reportdir: /etc/scrippy/reports
  templatedir: /etc/scrippy/templates
  tmpdir: /etc/scrippy/tmp

# ~/.config/scrippy/scrippy.yml (user)
env:
  confdir: /home/luiggi/scrippy/conf
  logdir: /home/luiggi/scrippy/log

# /usr/local/etc/scrippy/scrippy.yml (system administrator)
env:
  logdir: /var/log/scrippy

The resulting configuration for the user luiggi is:

The Scrippy directories

The directories that are not created automatically must exist before being used. The installer creates all of them.

Within a script, every directory is available through the _context.env dictionary (see the tutorial):

with scrippy_core.ScriptContext() as _context:
  reportdir = _context.env["reportdir"]

The examples below are given for a script named disk_watch.py, run by the user luiggi with the default user installation.

confdir

The directory where the configuration files of the scripts are stored. A script automatically loads the file named after the script, with the .conf extension, if it exists:

/home/luiggi/.local/share/scrippy/conf/disk_watch.conf
'-------------- confdir --------------'- name -'.conf'

logdir

The directory where the execution logs are stored. Each execution writes its own log file in a subdirectory named after the script. The log file name contains the session identifier of the execution:

/home/luiggi/.local/share/scrippy/log/disk_watch/disk_watch_1791446705.884451_27893.log
'------------- logdir ---------------'- name ---'- name ---'------ session ------'.log'

histdir

The directory where the execution histories are stored. Each script has its own SQLite3 database, named after the script:

/home/luiggi/.local/share/scrippy/hist/disk_watch.db
'------------- histdir ---------------'- name -'.db'

tmpdir

The directory where the temporary workspaces are created. Each execution gets its own workspace, named after the script and the session identifier, deleted at the end of the execution:

/home/luiggi/.local/share/scrippy/tmp/disk_watch_1791446705.884451_27893
'------------- tmpdir ---------------'- name ---'------ session ------'

The tmpdir also holds the files used to manage concurrent executions: disk_watch.pids and disk_watch.pids.lock.

reportdir

The directory where scripts store the data they produce and that must persist after the execution: Reports, exports, archives...

Scrippy does not enforce any organization of this directory. Using a subdirectory per script (i.e: <reportdir>/disk_watch/) is a good practice.

datadir

The directory where scripts find the static data they need: Reference files, lists, keys...

While not enforced, the datadir is meant to be read only for the scripts. Data generated by the scripts goes into the reportdir.

templatedir

The directory where scripts find their template files, typically used with the scrippy-template module.

Scripts executed with elevated privileges

When a script is allowed to be executed with elevated privileges (i.e: with sudo), it is up to the system administrator to ensure that the user executing the script can not alter its environment:

• The system administrator configuration file (/usr/local/etc/scrippy/scrippy.yml) should define all the env keys. Any key left undefined may be provided by the user configuration file.
• The HOME environment variable should not be preserved (no sudo -E, no env_keep of HOME, Defaults always_set_home in sudoers). Otherwise, the user configuration file (~/.config/scrippy/scrippy.yml) of the calling user is read by the privileged script.
• The Scrippy directories should not be writable by other users than the ones allowed to execute the scripts.