The json2file-go(1) is a mini-application that runs as a Web server and is used to store the information
sent by remote WebHooks in JSON format using the HTTP POST method.
Initially it has been used to process GitLab and Gitea WebHooks, but it can be used with other systems.
To verify that a caller has permission to store a file the program compares a JSON field or an HTTP
HEADER to the secret it has configured for the given PATH. If the secret matches the program verifies
that the data received is a valid JSON file and only stores it if it is.
The application is configured using environment variables and is designed to run inside a docker
container or supervised with systemd if we are on a regular Linux server.
The application reads two mandatory environment variables:
• J2F_BASEDIR: Working directory of the application, must exist before launching it.
The default value for this variable when using the systemd helper (see later) is
/var/spool/json2file-go. If we use the application inside a container the idea is to set the value to
/data (is a volume in the Dockerfile) and use a volume or mount a HOST directory there.
• J2F_DIRLIST: List of directories in which we allow one to save files and an optional token that must
be passed in a header or within the JSON to authorize the save operation for the file.
The variable is a string of the form: DIR1:TOKEN1;...;DIR#:TOKEN#
There is no default for this variable, it must be set.
Other optional variables include:
• J2F_SIGNATURE_HEADERS: Comma-separated list of names for the HTTP header containing the signature
hash (by default the list contains the name X-Hub-Signature)
• J2F_TOKEN_HEADERS: Comma-separated list of names for the HTTP header containing the token (by default
the list contains the names X-Auth-Token and X-Gitlab-Token)
• J2F_TOKEN_FIELDS: Comma-separated list of names for the received JSON field that contains the token
(by default we use secret)
• J2F_URL_PREFIX: Service base path on URLs, the directory names are computed removing this prefix
• J2F_HOST: IP address to bind to (default 0.0.0.0)
• J2F_PORT: TCP Port (80 if there are no certificates, 443 if there are any)
• J2F_BIND: Listen Address and Port (default $J2F_HOST:$J2F_PORT, if used replaces the other two
variables)
• J2F_CERTFILE and J2F_KEYFILE: public certificate and key file for TLS (if both are set it is assumed
that we are using TLS and the server uses that certificate and private key)
• J2F_SOCKET: UNIX Socket to listen on (has no default value, if passed the server listens for HTTP
requests on a UNIX socket ignoring the address, port and TLS settings); this is the preferred mode
when the service is accessed using NGINX as a reverse proxy
By default the system saves the JSON data received in the sub folder of J2F_BASEDIR that matches the
requested directory name using files with names of the form TIMESTAMP.json, where the format of TIMESTAMP
is YYYYmmdd-HHMMSS.MS.json.
While this program does nothing else, the files are usually processed by scripts launched by cron(8) or
incrond(8).
To be able to work with systemd.socket(5) when the application launches it checks if the variable
LISTEN_PID is set and in that case the J2F_HOST, J2F_PORT, J2F_BIND and J2F_SOCKET are ignored and the
program listens on the first file descriptor available after stdout (the one with value 3) ignoring other
descriptors if any (the daemon only listens on a file descriptor). Note that in this case the
J2F_CERTFILE and J2F_KEYFILE are NOT ignored (systemd can pass us a file descriptor where we should use
HTTPS).
If the program is launched without systemd and the variables J2F_HOST, J2F_PORT, J2F_BIND or J2F_SOCKET
have no value the program tries to listen on 0.0.0.0:80 (or 0.0.0.0:443 if we provide a certificate and a
key file).
Install Now
PNG Icons
