From e1026bae0d6280e70b0c7d187fa403258bca09a8 Mon Sep 17 00:00:00 2001 From: Augustin Fabre Date: Mon, 13 Apr 2020 19:25:14 +0200 Subject: [PATCH] Rework manual page * Renamed gophernicus.1.man to gophernicus.1, the standard name for section 1 manual pages. * Added synopsis of command. * Added markup for options, arguments, paths, authors, links. --- Makefile | 2 +- gophernicus.1 | 251 ++++++++++++++++++++++++++++++++++++++++++++++ gophernicus.1.man | 79 --------------- 3 files changed, 252 insertions(+), 80 deletions(-) create mode 100644 gophernicus.1 delete mode 100644 gophernicus.1.man diff --git a/Makefile b/Makefile index fa9b57e..0ccd3d8 100644 --- a/Makefile +++ b/Makefile @@ -14,7 +14,7 @@ DESTDIR = /usr OSXDIR = /usr/local SBINDIR = $(DESTDIR)/sbin DOCDIR = $(DESTDIR)/share/doc/$(PACKAGE) -MANPAGE = gophernicus.1.man +MANPAGE = gophernicus.1 MANDEST = $(DESTDIR)/share/man/man1/gophernicus.1 INSTALL = PATH=$$PATH:/usr/sbin ./install-sh -o 0 -g 0 diff --git a/gophernicus.1 b/gophernicus.1 new file mode 100644 index 0000000..f0f2d19 --- /dev/null +++ b/gophernicus.1 @@ -0,0 +1,251 @@ +.Dd April 13, 2020 +.Dt GOPHERNICUS 1 +.Os +.Sh NAME +.Nm gophernicus +.Nd A modern, full-featured and secure gopher server +.Sh SYNOPSIS +.Nm +.Op Fl h Ar hostname +.Op Fl p Ar port +.Op Fl r Ar port +.Op Fl t Ar type +.Op Fl g Ar mapfile +.Op Fl a Ar tagfile +.Op Fl c Ar dir +.Op Fl u Ar dir +.Op Fl l Ar file +.Op Fl w Ar width +.Op Fl o Ar charset +.Op Fl s Ar seconds +.Op Fl i Ar hits +.Op Fl k Ar KiB +.Op Fl e Ar ext Ns = Ns Ar type Oo Fl e Ar ext Ns = Ns Ar type Oc ... +.Op Fl R Ar old Ns = Ns Ar new Oo Fl R Ar old Ns = Ns Ar new Oc ... +.Op Fl D Ar text +.Op Fl L Ar text +.Op Fl U Ar paths +.Op Fl nv +.Op Fl nl +.Op Fl nh +.Op Fl nf +.Op Fl nd +.Op Fl nc +.Op Fl no +.Op Fl nq +.Op Fl ns +.Op Fl na +.Op Fl nt +.Op Fl nm +.Op Fl nr +.Op Fl np +.Op Fl nx +.Op Fl nu +.Op Fl nH +.Op Fl d +.Op Fl b +.Op Fl \&? +.Sh DESCRIPTION +.Nm +is a gopher server. It serves almost compliant RFC 1436, with small +changes to make it more modern. +.Nm +supports userdirs, executable gophermaps, CGI, and virtual hosting (in the +limits of the RFC). +.Pp +.Nm +can log to +.Xr syslog 3 +or per-server files in Apache format. +.Pp +The options are as follows: +.Bl -tag -width Dssmacro=value +.It Fl h Ar hostname +Changes the server hostname shown on the output menu. +The default is the fully qualified domain name of the machine. +.It Fl p Ar port +Changes the server port shown on the output menu. +The default is +.Pa 70 . +.It Fl T Ar port +Changes the SSL/TLS port. +The default is +.Pa 0 +(disabled). +.It Fl r Ar directory +Set the document root of the server. +The default is +.Pa /var/gopher . +.It Fl t Ar type +Set the default gopher filetype. +The default is +.Pa 0 . +.It Fl g Ar mapfile +Set the gophermap file name. +The default is +.Pa gophermap . +.It Fl a Ar tagfile +Set the gophertag file name. +The default is +.Pa gophertag . +.It Fl c Ar directory +Set the CGI script directory, under the document root. +The default is +.Pa /cgi-bin/ . +.It Fl u Ar directory +Set the name of the personal gopherspace directory. +Each user can deploy a personal gopherspace by creating a directory +.Pa directory +in their home directory. +The default is +.Pa public_gopher . +.It Fl l Ar file +Log to +.Pa file +in Apache-compatible combined format. Disabled by default. +.It Fl w Ar width +Set default page width. +The default is +.Pa 76 . +.It Fl o Ar charset +Select the output charset. It can be +.Ar UTF-8 , +.Ar US-ASCII , +or +.Ar ISO-9959-1 . +The default is +.Ar UTF-8 . +.It Fl s Ar seconds +Session timeout in seconds. +The default is +.Pa 1800 . +.It Fl i Ar hits +Maximum hits until throttling. +The default is +.Pa 4069 . +.It Fl k Ar kilobytes +Maximum transfer size in KiB until throttling. +The default is +.Pa 4194304 +(4 GiB). +.It Fl f Ar directory +Set directory where output filters are found. +Disabled by default. +.It Fl e Ar ext Ns = Ns Ar type +Map file extension +.Ar ext +to gopher filetype +.Ar type . +.It Fl R Ar old Ns = Ns Ar new +Rewrite the start of a selector. +.It Fl D Ar description +Set server description to appear in +.Pa /caps.txt . +If +.Ar description +looks like a filename (starts with a /), use the contents of the file. +.It Fl L Ar location +Set server location to appear in +.Pa /caps.txt . +If +.Ar location +looks like a filename (starts with a /), use the contents of the file. +.It Fl A Ar email +Set the email of the administrator to appear in +.Pa /caps.txt . +.It Fl U Ar paths +Set a colon-separated list of extra +.Xr unveil 2 +paths (only for OpenBSD). +.It Fl nv +Disable virtual hosting. +.It Fl nl +Disable parent directory links. +.It Fl nh +Disable menu header. +.It Fl nf +Disable menu footer. +.It Fl nd +Don't show date and size of files in menu. +.It Fl nc +Disable file content detection (similar to +.Xr magic 5 Ns ). +.It Fl no +Disable output charset conversion. +.It Fl nq +Disable HTTP-style query strings +.Ql ?foo=bar&baz=quux . +.It Fl ns +Disable logging to +.Xr syslog 3 . +.It Fl na +Disable autogenerated +.Pa /caps.txt . +.It Fl nt +Disable +.Pa /server-status . +.It Fl nm +Disable shared memory use (for debugging purposes). +.It Fl nr +Disable root user check (for debugging purposes). +By default, +.Nm +will refuse to run as root. +.It Fl np +Disable HAProxy proxy protocol. +.It Fl nx +Disable execution of gophermaps and scripts. +.It Fl nH +Disable HTTP response to HTTP GET and POST requests. +.It Fl d +Print debug output in +.Xr syslog 3 +and +.Pa /server-status . +.It Fl v +Display version information and build date. +.It Fl b +Display licensing information. +.It Fl \&? +Display help. +.El +.Pp +Default values may have been changed at compile time by +.Pa gophernicus.env . +.Sh STANDARDS +.Nm +mostly conforms to +.Lk https://tools.ietf.org/html/rfc1436 "RFC 1436" +.Sh AUTHORS +.An -nosplit +.An Kim Holviala. +wrote the original implementation (2009\(en2018). +.Pp +.An fosslinux +and +.An hb9kns +are the current maintainers (2019\(en). +.Pp +Code contributed by others. +.Pp +Developers can be reached at +.Mt gophernicus.AT.gophernicus.DOT.org +.Sh BUGS +Known bugs are listed as issues on +.Nm Ap s GitHub page: +.Lk https://github.com/gophernicus/gophernicus/issues +.Pp +Please report any bug you might experience there as well. +.Sh COPYRIGHT +Copyright \(co +.An Kim Holviala +2009\(en2018. +.Pp +Copyright \(co +.An Nm gophernicus Ns \& developers +2019. +.Pp +Licensed to you under the terms of the BSD 2-clause license. +Please see +.Pa LICENSE +for the full terms of the license. diff --git a/gophernicus.1.man b/gophernicus.1.man deleted file mode 100644 index 5db852e..0000000 --- a/gophernicus.1.man +++ /dev/null @@ -1,79 +0,0 @@ -.\" Manpage for gophernicus. -.TH man 1 "26 Oct 2019" "3.0.1" "gophernicus man page" -.SH NAME -gophernicus \- a modern, full-featured and secure gopher daemon -.SH SYNOPSIS -.B gophernicus -[options] -.SH DESCRIPTION -.B gophernicus -is a daemon that serves the gopher protocol. It serves almost fully -compliant RFC 1436, with a few very small changes to make it more modern. -gophernicus has many useful features, including userdirs, executable gophermaps, -virtual hosting as well as RFC supports it, unveil/pledge support on OpenBSD and -much more. It is fully FOSS, and licensed under the BSD 2-Clause license. -.SH OPTIONS - -h hostname Change server hostname (FQDN) [$HOSTNAME] - -p port Change server port [70] - -T port Change TLS/SSL port [0 = disabled] - -r root Change gopher root [/var/gopher] - -t type Change default gopher filetype [0] - -g mapfile Change gophermap file [gophermap] - -a tagfile Change gophertag file [gophertag] - -c cgidir Change CGI script directory [/cgi-bin/] - -u userdir Change users personal gopherspace [public_gopher] - -l logfile Log to Apache-compatible combined format logfile - - -w width Change default page width [76] - -o charset Change default output charset [UTF-8] - - -s seconds Session timeout in seconds [1800] - -i hits Maximum hits until throttling [4096] - -k kbytes Maximum transfer until throttling [4194304] - - -f filterdir Specify directory for output filters - -e ext=type Map file extension to gopher filetype - -R old=new Rewrite the beginning of a selector - - -D text|file Set or load server description for caps.txt - -L text|file Set or load server location for caps.txt - -A admin Set admin email for caps.txt - - -U paths Specify a colon-separated list of extra unveil(2) paths - (OpenBSD only). - - -nv Disable virtual hosting - -nl Disable parent directory links - -nh Disable menu header (title) - -nf Disable menu footer - -nd Disable dates and filesizes in menus - -nc Disable file content detection - -no Disable charset conversion for output - -nq Disable HTTP-style query strings (?query) - -ns Disable logging to syslog - -na Disable autogenerated caps.txt - -nt Disable /server-status - -nm Disable shared memory use (for debugging) - -nr Disable root user checking (for debugging) - -np Disable HAproxy proxy protocol - -nx Disable execution of gophermaps and scripts - -nu Disable personal gopherspaces - -nH Disable HTTP response to HTTP GET/POST requests. - - -d Debug output in syslog and /server-status - -v Display version number and build date - -b Display the BSD license - -? Display this help - -(Note: default options may have been changed through gophernicus.env file at compile time.) -.SH AUTHOR -fosslinux, hb9kns and others; -.SH REPORTING BUGS -Please report bugs on our GitHub page: -https://github.com/gophernicus/gophernicus. -.SH COPYRIGHT -Copyright (c) Kim Holviala 2009-2018 -Copyright (c) Gophernicus Developers 2019 - -Licensed to you under the terms of the BSD 2-Clause license, please see LICENSE -for the full terms of the license.