From 0933880b2ba2990bc6a9ed14a4a44cfbfcc2154e Mon Sep 17 00:00:00 2001 From: Drew DeVault Date: Sat, 26 Sep 2020 16:43:34 -0400 Subject: [PATCH] Documentation --- Makefile | 24 +++++++++++++----- README.md | 39 +++++++++++++++++++++++++++- config.ini | 2 +- config.sh | 5 ++++ doc/gmnisrv.scd | 25 ++++++++++++++++++ doc/gmnisrvini.scd | 63 ++++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 150 insertions(+), 8 deletions(-) create mode 100644 doc/gmnisrv.scd create mode 100644 doc/gmnisrvini.scd diff --git a/Makefile b/Makefile index 7d37afd..d1141da 100644 --- a/Makefile +++ b/Makefile @@ -8,7 +8,10 @@ gmnisrv: $(gmnisrv_objects) @printf 'CCLD\t$@\n' @$(CC) $(LDFLAGS) -o $@ $(gmnisrv_objects) $(LIBS) -.SUFFIXES: .c .o .scd .1 +doc/gmnisrv.1: doc/gmnisrv.scd +doc/gmnisrvini.5: doc/gmnisrvini.scd + +.SUFFIXES: .c .o .scd .1 .5 .c.o: @printf 'CC\t$@\n' @@ -21,18 +24,27 @@ gmnisrv: $(gmnisrv_objects) @printf 'SCDOC\t$@\n' @$(SCDOC) < $< > $@ -# TODO: Docs -docs: - @true +.scd.5: + @printf 'SCDOC\t$@\n' + @$(SCDOC) < $< > $@ + +docs: doc/gmnisrv.1 doc/gmnisrvini.5 clean: - @rm -f gmnisrv $(gmnisrv_objects) + @rm -f gmnisrv $(gmnisrv_objects) doc/*.1 doc/*.5 distclean: clean @rm -rf "$(OUTDIR)" install: all - mkdir -p $(BINDIR) + mkdir -p \ + $(DESTDIR)$(BINDIR) \ + $(DESTDIR)$(SHAREDIR)/gmnisrv \ + $(DESTDIR)$(MANDIR)/man5 \ + $(DESTDIR)$(MANDIR)/man1 install -Dm755 gmnisrv $(DESTDIR)$(BINDIR)/gmnisrv + install -Dm644 $(SRCDIR)/config.ini $(DESTDIR)$(SHAREDIR)/gmnisrv/gmnisrv.ini + install -Dm644 doc/gmnisrv.1 $(DESTDIR)$(MANDIR)/man1/gmnisrv.1 + install -Dm644 doc/gmnisrvini.5 $(DESTDIR)$(MANDIR)/man5/gmnisrv.ini.5 .PHONY: clean distclean docs install diff --git a/README.md b/README.md index 0e6644b..b985751 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,40 @@ # gmnisrv -WIP, come back later +gmnisrv is a simple [Gemini](https://gemini.circumlunar.space) protocol server. + +## Installation + +``` +$ mkdir build +$ cd build +$ ../configure --prefix=/usr +$ make +# make install +``` + +## Configuration + +By default it reads from `/etc/gmnisrv.ini`, but this can be changed by passing +the `-C` flag to the `gmnisrv` daemon. A sample config.ini is provided at +`/usr/share/gmnisrv/gmnisrv.ini`: + +``` +# Space-separated list of hosts +listen=0.0.0.0:1965 [::]:1965 + +[:tls] +# Path to store certificates on disk +store=/var/lib/gemini/certs + +# Optional details for new certificates +organization=gmnisrv user + +[localhost] +root=/var/www +``` + +For full details on gmnisrv configuration, consult the *gmnisrv*(5) manual page. + +## Usage + +See *gmnisrv*(1). diff --git a/config.ini b/config.ini index f8cfca9..459085c 100644 --- a/config.ini +++ b/config.ini @@ -5,7 +5,7 @@ listen=0.0.0.0:1965 [::]:1965 # Path to store certificates on disk store=/var/lib/gemini/certs -# Details for new certificates +# Optional details for new certificates organization=gmnisrv user [localhost] diff --git a/config.sh b/config.sh index 0c8453b..cd0b505 100644 --- a/config.sh +++ b/config.sh @@ -26,6 +26,9 @@ do SYSCONFDIR=/etc fi ;; + --sharedir=*) + SHAREDIR=${arg#*=} + ;; --sysconfdir=*) SYSCONFDIR=${arg#*=} ;; @@ -138,7 +141,9 @@ run_configure() { LIBS=$LIBS PREFIX=${PREFIX:-/usr/local} OUTDIR=${outdir} + SRCDIR=${srcdir} BINDIR?=${BINDIR:-\$(PREFIX)/bin} + SHAREDIR?=${SHAREDIR:-\$(PREFIX)/share} SYSCONFDIR?=${SYSCONFDIR:-\$(PREFIX)/etc} LIBDIR?=${LIBDIR:-\$(PREFIX)/lib} MANDIR?=${MANDIR:-\$(PREFIX)/share/man} diff --git a/doc/gmnisrv.scd b/doc/gmnisrv.scd new file mode 100644 index 0000000..80de229 --- /dev/null +++ b/doc/gmnisrv.scd @@ -0,0 +1,25 @@ +gmnisrv(1) + +# NAME + +gmnisrv - serve clients over the gemini protocol + +# SYNPOSIS + +*gmnisrv* [-C _path_] + +# DESCRIPTION + +*gmnisrv* is a daemon which serves network clients over the gemini protocol. It +requires a config file; by default this shall be read from /etc/gmnisrv.ini +unless the installation was configured with a different SYSCONFDIR or the user +provides the -C flag. + +# OPTIONS + +*-C* _path_ + Specifies an alternate path to read the config file from. + +# SEE ALSO + +*gmnisrv.ini*(5) diff --git a/doc/gmnisrvini.scd b/doc/gmnisrvini.scd new file mode 100644 index 0000000..a140ad0 --- /dev/null +++ b/doc/gmnisrvini.scd @@ -0,0 +1,63 @@ +gmnisrv.ini(5) + +# NAME + +*gmnisrv.ini* - configuration file for *gmnisrv*(1) + +# SYNTAX + +*gmnisrv.ini* is an INI file. Each line is either a key/value pair, or a section +heading. Key/value pairs are specified as key=value, and sections as [section]. + +# CONFIGURATION KEYS + +The meaning of the key depends on the section. Anonymous keys (prior to the +first [section] directive) are used to specify parameters for the daemon itself. +Sections whose name is prefixed with ":", e.g. [:tls], are sub-categories of +the daemon configuration. Otherwise, section names refer to the hostnames of +domains serviced by the *gmnisrv* daemon. + +## ANONYMOUS KEYS + +*listen* + A space-separated list of addresses that the daemon shall bind to. Each + address shall take the format *address*:*port*. If :*port* is omitted, + 1965 (the default Gemini port) is presumed. To specify an IPv6 address, + enclose it in *[]*, e.g. *[::]*. + + +## TLS KEYS + +The following keys are accepted under the *[:tls]* section: + +*store* + Path to the certificate store on disk. This should be a persistent + directory writable by the daemon. The daemon manages its own + certificates - no user intervention is required, except in the case of + moving the daemon to another host, in which case the certificate store + must be copied to the new host. + +*organization* + An optional key used during certificate generation. Fill this in with + the name of the organization responsible for the host and it will be + filled in as the X.509 /O name. + +## HOST KEYS + +Hosts that *gmnisrv* is to serve shall be defined in *gmnisrv.ini* by +introducing config sections named after each host to provide service for. The +following keys apply: + +*root* + Configures the path on disk from which files shall be served for this + host. + +*index* + Configures the name of the index file which shall be served in the event + that a request for this host does not include the filename part. + Defaults to "index.gmi". + +*autoindex* + "on" to enable the auto-index feature, which presents clients with a + list of files in the requested directory when an index file cannot be + found. Off by default.