Configuration — FExec

/etc/fexec/fexec.confMain configuration file

INI key-value format. Every parameter can also be set via a CLI flag (--kebab-case-name) or environment variable (FEXEC_SNAKE_CASE_NAME). Precedence, highest first: CLI flag → environment variable → fexec.conf → built-in default.

Directories

Parameter	Default	Description
`AuthDir`	`/etc/fexec/auth.d`	Scanned for authentication YAML files
`AliasDir`	`/etc/fexec/alias.d`	Scanned for alias YAML files
`SharedDir`	`/tmp/fexec/`	Working area for per-execution temp files and Docker volume mounts
`ExternalDir`	(empty)	Host-side path of `SharedDir` when FExec itself runs inside a container

Network

Parameter	Default	Description
`ListenAddress`	`0.0.0.0`	IP address the HTTP server binds to
`ListenPort`	`80` / `443`	Defaults to 443 when SSL is enabled, 80 otherwise
`SslEnabled`	`false`	Enable TLS on the listening port
`SslCert` / `SslKey`	(empty)	PEM cert/key paths — mandatory when SSL is enabled
`PublicInfoEnabled`	`true`	Serve the landing page and API documentation; set `false` to disable both

Logging

Parameter	Default	Description
`LogLevel`	`warn`	Applied to `AppLog` and the interactive console fallback
`AuditLog`	`/var/log/fexec/audit.log`	Request audit log — one nginx-style line per request
`AppLog`	`/var/log/fexec/app.log`	Diagnostic log. Syntax: `AppLog <path> [level] [format]`, e.g. `AppLog /dev/stdout info plain`

Reload & execution

Parameter	Default	Description
`AuthReload` / `AliasReload`	`30`s	Poll interval for config changes; `0` disables. OS-level file events also trigger immediate reload, and `SIGHUP` forces one. `fexec.conf` itself requires a restart.
`MaxTimeout`	(no limit)	Ceiling on any alias's `timeout`; larger values are rejected at load time
`RefreshImage`	`no`	Default image-refresh policy for container aliases: `always`, `on-start`, `no`
`PrefetchImage`	`no`	Default image-prefetch policy: `on-start`, `on-config-change`, `no`

Example

ListenAddress = 0.0.0.0
ListenPort    = 8443
SslEnabled    = true
SslCert       = /etc/fexec/ssl/server.crt
SslKey        = /etc/fexec/ssl/server.key

LogLevel = info
AuditLog = /var/log/fexec/audit.log
AppLog   = /var/log/fexec/app.log info json

AuthDir     = /etc/fexec/auth.d
AliasDir    = /etc/fexec/alias.d
AuthReload  = 60
AliasReload = 60
MaxTimeout  = 300

/etc/fexec/auth.d/*.yamlAuthentication configuration

Each file is a YAML list mixing user definitions and JWT public keys.

# JWT public key
- public_key: |-
    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
    -----END PUBLIC KEY-----

# User
- username: alice
  api_keys:
    - alice-secret-key
  aliases:
    - generate-report
    - list-files

A user needs username and aliases; api_keys is required unless at least one JWT public key is configured. Usernames and API keys must each be unique across all auth files, and every user must have at least one alias.

For JWTs, the sub claim (if present) is looked up against configured users and merged with the token's own aliases claim; exp is enforced.

/etc/fexec/alias.d/*.yamlAlias configuration

Each file is a YAML mapping where every top-level key is an alias name, unique across all files.

Common fields

Field	Required	Description
`type`	yes	`process` (host command) or `container` (Docker)
`mode`	no	Default `inline` (blocks until completion) or `standalone` (starts a long-lived process/container and returns once it's up) — see Standalone Mode in CONFIGURATION.md
`parameters`	no	Parameter definitions, see below
`timeout`	no	Seconds, default `60`, capped by `MaxTimeout`
`output`	yes	How to format the response
`preserveStreams`	no	Copy stdout/stderr to `LogDir` past the request's lifetime
`exitCodeMap`	no	Overrides the default HTTP status resolution for the command's exit code

Parameters

my_alias:
  parameters:
    report_type:
      validator: "^pdf|csv|json$"
      description: "Output format"
    log_level:
      validator: "^$|^trace|debug|info|warn|error$"
      default: "info"

Each parameter has a validator regex the value must fully match — if the regex accepts the empty string, the parameter is optional. An optional parameter may also declare a default, which must itself satisfy the validator.

Full example

generate-report:
  type: process
  mode: inline
  description: "Generate a report"
  timeout: 120
  parameters:
    type:
      validator: "^pdf|csv|json$"
    date:
      validator: "^\d{4}-\d{2}-\d{2}$"
  output:
    stdout: body
  exitCodeMap:
    0: 200
    1-99: 422

Container-type aliases additionally support volume mounts (with optional preserve: flatten|yes to survive cleanup) and image refresh/prefetch policies. See the full Container Type reference for the complete field set.

Response statusExit code mapping

By default a zero exit code returns HTTP 200 and any other exit code returns 422 — the response body is always built from the alias's output config either way. Any alias can override this via exitCodeMap, mapping specific exit codes or ranges to different HTTP statuses, including back to 200.