filed

Job queue using FUSE

git clone git://mccd.space/filed

commit b55247754a9993296fa932a860a773c87913791e
parent 7fbeedf34ebaafd796559297cb09d6836b870010
Author: Marc Coquand <marc@coquand.email>
Date:   Thu, 18 Dec 2025 10:02:59 +0100

Add filed.config man page

Diffstat:

M.gitignore | 2++


Mfiled.5.scd | 79+++++++++++++++++++++++++++++++------------------------------------------------


Afiled.config.5.scd | 39+++++++++++++++++++++++++++++++++++++++


3 files changed, 72 insertions(+), 48 deletions(-)
diff --git a/.gitignore b/.gitignore
@@ -1,2 +1,4 @@
 filed
 filed.[1-8]
+filed.config.[1-8]
+ 
diff --git a/filed.5.scd b/filed.5.scd
@@ -6,39 +6,44 @@ filed - queue jobs utility
 
 # SYNOPSIS
 
-*filed* _mountpoint_
+*filed* _mdir_
 
 # DESCRIPTION
 
-filed (file d'attente) is an inspectable job queue that operates on
-files. It mounts a directory _mountpoint_, which is where the user can add
-and inspect jobs.
+filed (file d'attente) is a pseudo-filesystem which provides an inspectable
+job queue that operates on files. It mounts a directory _mdir_, which is
+where the user can add and inspect jobs.
 
-filed exposes 4 directories to _mountpoint_, where each directory contains
-zero or more _jobs_. Job names must be unique across all four directories. The
-directories are:
+## Overview
 
-	*/pending* - jobs to be run. To create a new job, create a file
-	here with the command to run. The filename is the ID, and the content
-	is the command that will be executed with sh.
+Underneath _mdir_, there are the following groups of files and subdirectories:
 
-	*/active* - currently running jobs. It is possible to access logs of
+_mdir_/pending/[a-z]\*  
+	Jobs to be run. To create a new job, create a file here with
+	the command to run. The filename is the ID, and the content is
+	the command that will be executed with sh.
+
+_mdir_/active/[a-z]\* 
+	Currently running jobs. It is possible to access logs of
 	the running jobs by inspecting the files. It is also possible to 
 	remove an active job, which will kill the process.
 
-	*/failed* - jobs that exceeded retry count. You can retry a job by
+_mdir_/failed/[a-z]\* 
+	Jobs that exceeded retry count. You can retry a job by
 	moving them back to pending. You can also safely remove jobs here.
 
-	*/complete* - jobs that succeeded, with content being the job
-	output. Jobs here can safely be removed.
+_mdir_/complete/[a-z]\* 
+	Jobs that succeeded, with content being the job	output. Jobs
+	here can safely be removed.
 
-filed exposes 2 files: 
+_mdir_/new-id 
+	Contains a short unique id that can be sampled for job name
+	entropy. The id is guaranteed to be unique at creation.
 
-	*/new-id* contains a short unique id that can be sampled for job
-	name entropy. The id is guaranteed to be unique at creation.
+_mdir_/config.json 
+	Provides various settings. Changes made to this file are applied
+	immediately. See *filed.config*(5) for full list of options.  
 
-	*/config.json* provides various settings. Changes made to this file 
-	are applied immediately. See *CONFIGURATION* for full list of options.
 
 # SECURITY
 
@@ -54,13 +59,13 @@ principle of least access.
 
 Importantly, the system is intended for only trusted scripts: the job user
 has access to the state, and is thus able to rewrite access rights. It is
-recommended for the running scripts to use _namespaces(7)_ or _Landlock(7)_ to
+recommended for the running scripts to use *namespaces*(7) or *Landlock*(7) to
 drop further drop privileges. 
 
 Another aspect to be aware of is that File d'attente stores logs of all jobs.
 Care should be taken to ensure that no secrets are printed.
 
-Access rights can be modified using _CHOWN(1)_ and _CHMOD(1)_. 
+Access rights can be modified using *chown*(1) and *chmod*(1). 
 
 # MAINTENANCE
 
@@ -72,29 +77,6 @@ look like this, for example:
 	0 2 * * * find /path/to/filed/{complete,failed} -type f -mtime +7 -delete
 	```
 
-# CONFIGURATION
-
-## Max retries
-
-Maximum amount of retries before moving the job to failed. 
-
-## Max job count
-
-Maximum amount of concurrent jobs. It is recommended to not set this much
-higher than 20.
-
-## Backoff mult and backoff base
-
-The time in seconds to wait before retrying. The formula used is:
-
-	```
-	base * mult^attempts
-	```
-
-## Timeout 
-
-Time (in seconds) before the job will be killed by a signal.
-
 # ENVIRONMENT
 
 ## FILED_STATE_FILE
@@ -119,13 +101,14 @@ Inspect a currently running job:
 
 # SEE ALSO
 
-- Periodic jobs can be set up using _CRON(8)_.
-- Monitoring failures can be done with _WATCH(1)_
-- Limiting job privileges can be done with _bwrap(1)_ or _landrun_
+- *filed.config*(5)
+- Periodic jobs can be set up using *cron*(8).
+- Monitoring failures can be done with *watch*(1)
+- Limiting job privileges can be done with *bwrap*(1) or *landrun*
 
 # LIMITATIONS
 
-File d'attente does not work with _inotify(7)_.
+File d'attente does not work with *inotify*(7).
 
 # AUTHORS
 
diff --git a/filed.config.5.scd b/filed.config.5.scd
@@ -0,0 +1,39 @@
+FILED.CONFIG(5)
+
+# NAME
+
+_/mdir_/config.json - Configure the actively running _filed(5)_ daemon 
+
+# DESCRIPTION
+
+Mounted to _mdir_ is a pseudo-json configuration file that  can be used to
+configure the *filed*(5) job queue.
+
+When saving the file, the changes are applied immediately.
+
+# Overview
+
+## Max retries
+
+Maximum amount of retries before moving the job to failed. 
+
+## Max job count
+
+Maximum amount of concurrent jobs. It is recommended to not set this much
+higher than 20.
+
+## Backoff mult and backoff base
+
+The time in seconds to wait before retrying. The formula used is:
+
+	```
+	base * mult^attempts
+	```
+
+## Timeout
+
+Time (in seconds) before the job will be killed by a signal.
+
+# SEE ALSO
+
+	*filed*(5)