snare.1

.Dd 2020-02-10
.Dt SNARE 1
.Os
.Sh NAME
.Nm snare
.Nd GitHub webhooks runner
.Sh SYNOPSIS
.Nm snare
.Op Fl c Ar config-file
.Op Fl d
.Op Fl v
.Sh DESCRIPTION
.Nm
is a GitHub webhooks daemon.
When
.Nm
receives a webhook event from
a given repository, it authenticates the request, and then executes a
user-defined
.Dq per-repo program
with information about the webhook event.
The
.Dq per-repo program
is run in a freshly created temporary directory which is removed once it has
completed.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl c Ar config-file
is a path to a
.Pa snare.conf
configuration file.
If not specified,
.Nm
assumes the configuration file is located at
.Pa /etc/snare/snare.conf/ .
.It Fl d
tells
.Nm snare
not to daemonise: in other words, `snare` stays in the foreground and logs
errors to stderr.
This can be useful for debugging.
.It Fl v
enables more verbose logging.
.Fl v
may be specified multiple times, with each increasing the quantity of logging.
.El
.Sh INTEGRATION WITH GITHUB
.Nm
runs an HTTP server which GitHub can send webhook requests to.
Configuring a webhook for a given GitHub repository is relatively simple: go to
that repository, then
.Eo “
Settings > Webhooks > Add webhook
.Ec ” .
For
.Dq payload ,
specify
.Dq http://yourmachine.com:port/ ,
specify a
.Dq secret
(which you will then reuse as the
.Sy secret
in
.Xr snare.conf 5 )
and then choose which events you wish
GitHub to deliver.
.Sh HTTPS/TLS
.Nm
runs an HTTP server.
If you wish, as is recommended, to send your
webhooks over an encrypted connection, you will need to run a proxy in front of
.Nm .
.Sh DIAGNOSTICS
When run as a daemon,
.Nm
logs to
.Xr syslogd 8
under the
.Dq daemon
facility.
.Sh SEE ALSO
.Xr snare.conf 5
.Pp
.Lk https://tratt.net/laurie/src/snare