From: Lucas Werkmeister Date: Wed, 22 Mar 2017 21:42:43 +0000 (+0100) Subject: Merge "add: gigi.properties(5) manpage" X-Git-Url: https://code.wpia.club/?p=gigi.git;a=commitdiff_plain;h=5e75c08b32119d8b45ed0a1d900ad523f4503bb3;hp=28b216e0a027c8d82b4db179d79974bd8d3c0aff Merge "add: gigi.properties(5) manpage" --- diff --git a/debian/gigi-proxy.service b/debian/gigi-proxy.service index b9503599..61e6b045 100644 --- a/debian/gigi-proxy.service +++ b/debian/gigi-proxy.service @@ -1,5 +1,6 @@ [Unit] Description=Gigi Webserver module +Documentation=gigi.properties(5) Wants=postgresql@9.4-main.service After=postgresql@9.4-main.service Conflicts=gigi-standalone.service diff --git a/debian/gigi.1 b/debian/gigi.1 index d7eaa369..ad04d188 100644 --- a/debian/gigi.1 +++ b/debian/gigi.1 @@ -47,3 +47,5 @@ Run the usual webdb (not forking). You will need to pipe the config into this pr .TP .B start-daemon Run the usual webdb (forking). You will not need to pipe the config into this program. It reads the config from /etc/wpia/gigi/conf.tar +.SH SEE ALSO +.BR gigi.properties (5) diff --git a/debian/gigi.properties.5 b/debian/gigi.properties.5 new file mode 100644 index 00000000..8f14e28e --- /dev/null +++ b/debian/gigi.properties.5 @@ -0,0 +1,212 @@ +.\" Hey, EMACS: -*- nroff -*- +.\" (C) Copyright 2014-2017 WPIA Software Team , +.\" +.TH GIGI.PROPERTIES 5 "March 21, 2017" WPIA +.\" Please adjust this date whenever revising the manpage. +.SH NAME +gigi.properties \- Gigi configuration file +.SH SYNOPSIS +.I /etc/gigi.properties +.SH DESCRIPTION +The file +.I gigi.properties +contains the configuration for the WPIA +.BR gigi (1) +system. +It is a Java properties file with \fIname=value\fR assignments and \fI# comment lines\fR. + +The following options can be set: +.TP +.B appName +The name of the main application, for example \fISomeCA\fR. +.TP +.B appIdentifier +The +.B \%appName +in a format suitable for inclusion in Internet domain names and HTTP URLs, +used in challenges to verify Internet domain name ownership via DNS or HTTP. +This identifier should be limited to lowercase ASCII letters, numbers and perhaps hyphens. +.TP +.B name.suffix +The main Internet domain name suffix of the application. +Used for administrative email addresses (e.g., \fIsupport@\fBname.suffix\fR) +and for all other domain names that are not explicitly specified (see \fBname.*\fR below). +Defaults to \fIwpia.local\fR. +.TP +.B host +The IP address that Gigi listens on, for example 127.0.0.1. +.TP +.B http.port +The port on which Gigi is reachable from outside via HTTP +(that is, the port it uses to refer to itself in hyperlinks), +and also the port on which Gigi listens unless +.B \%http.bindPort +is specified. +Usually 80. +.TP +.B https.port +The port on which Gigi is reachable from outside via HTTPS +(that is, the port it uses to refer to itself in hyperlinks), +and also the port on which Gigi listens unless +.B \%https.bindPort +is specified. +Usually 443. +.TP +.B http.bindPort +The port on which Gigi listens for HTTP requests, or +.IR stdin +to specify that Gigi has received a socket on file descriptor 0 (standard input) +which it should use for HTTP +(for example, via +.BR \%systemd.socket (5) +or +.BR inetd (1)). +.TP +.B https.bindPort +The port on which Gigi listens for HTTPS requests, or +.IR stdin +to specify that Gigi has received a socket on file descriptor 0 (standard input) +which it should use for HTTPS +(for example, via +.BR \%systemd.socket (5) +or +.BR inetd (1)). +Not used if +.B \%proxy +is +.IR true . +.TP +.B proxy +If +.IR true , +Gigi expects to sit behind a proxy server that handles HTTPS, +for example +.BR \%apache2 (8) +or +.BR \%nginx (1). +The real client IP, real protocol and (if present) real client certificate +are expected to be transferred in the \fI\%X-Real-IP\fR, \fI\%X-Real-Proto\fR and \fI\%X-Client-Cert\fR HTTP headers. +.B \%https.bindPort +is not used. +.TP +.B sql.driver +The JDBC driver used for connecting to the database. +As PostgreSQL is currently the only supported database, +the only value that really makes sense is \fI\%org.postgresql.Driver\fR. +.TP +.B sql.url +The database URL that Gigi connects to, +for example \fI\%jdbc:postgresql://localhost/gigi\fR. +.TP +.B sql.user +The user name that Gigi uses to connect to the database. +.TP +.B sql.password +The password that Gigi uses to connect to the database. +.TP +.B emailProvider +The fully-qualified name of a Java class that Gigi uses to send emails. +The only value available in production is \fIclub.wpia.gigi.email.Sendmail\fR. +.TP +.B emailProvider.smtpHost +The host to which the +.B \%emailProvider +should try to connect. +Defaults to \fI\%localhost\fR. +.TP +.B emailProvider.smtpPort +The port to which the +.B \%emailProvider +should try to connect. +Defaults to \fI25\fR. +.TP +.B highFinancialValue +A path to a plain text file of Internet domain names, one per names, +which Gigi should refuse to issue certificates to. +.TP +.B time.testValidMonths +The maximum time, in months, for which a passed agent quiz is considered recent. +Defaults to \fI12\fR. +.TP +.B time.reverificationDays +The minimum time, in days, that needs to pass before a name can be verified by the same agent again. +Defaults to \fI90\fR. +.TP +.B time.verificationMaxAgeMonths +The maximum time, in months, for which a verification is considered recent. +Defaults to \fI24\fR. +.TP +.B time.verificationFreshMonths +The maximum time period, in months, in which a verification can be entered into the system after it took place. +Defaults to \fI39\fR. +.TP +.B time.emailPingMonths +The maximum time period, in months, in which an email address can be used to create client certificates +before it must be verified again. +Defaults to \fI6\fR. +.TP +.B gigi.uid +Gigi will try to change to this user ID (see +.BR \%setuid (2)) +after opening its communication sockets. +This allows Gigi to bind to privileged ports as the superuser +and then drop privileges and run as a normal user. +This should rarely be necessary: it is much safer to not start Gigi as superuser in the first place +and instead only run it with the \fBCAP_NET_BIND_SERVICE\fR capability (see +.BR \%capabilities (7)), +or to have a privileged parent process (for example +.BR \%systemd (1)) +create the socket and pass it to Gigi (see +.BR \%http.bindPort ). +If +.B \%gigi.uid +and +.B \%gigi.gid +are both \fI-1\fR, this mechanism is disabled. +Defaults to \fI65534\fR, the user ID of the \fInobody\fR user on Debian GNU/Linux systems. +.TP +.B gigi.gid +Analogous to +.BR \%gigi.uid : +Gigi will try to change to this group ID (see +.BR \%setgid (2)) +after opening its communication sockets. +Defaults to \fI65534\fR. +.TP +.B scrypt.params +The parameters to the scrypt password hashing function. +Defaults to \fI14;8;1\fR. +.TP +.B name.www +The Internet domain name for the main application, served both via HTTP and HTTPS. +Defaults to \fI\%www.\fBname.suffix\fR. +.TP +.B name.secure +The Internet domain name for the forced-secure version of the application. +Gigi only serves this domain via HTTPS, +and requires authentication via a client certificate. +Defaults to \fI\%secure.\fBname.suffix\fR. +.TP +.B name.static +The Internet domain name for static resources, +like CSS style sheets and JS resources. +Defaults to \fI\%static.\fBname.suffix\fR. +.TP +.B name.api +The Internet domain name for the Gigi API, +which is used to issue certificates and receive quiz results. +Defaults to \fI\%api.\fBname.suffix\fR. +.TP +.B name.link +The Internet domain name of a link redirector service. +Gigi does not provide this service itself, +but links to it as a place for external documentation. +Defaults to \fI\%link.\fBname.suffix\fR. +.TP +.B name.g2.crt +The Internet domain name of a server that hosts a certificate repository +containing the certificates generated during the NRE procedure. +This service is also not provided by Gigi. +Defaults to \fI\%g2.crt.\fBname.suffix\fR. +.SH SEE ALSO +.BR gigi (1) diff --git a/debian/wpia-gigi-testing.manpages b/debian/wpia-gigi-testing.manpages index 3de344bc..4ba0b4db 100644 --- a/debian/wpia-gigi-testing.manpages +++ b/debian/wpia-gigi-testing.manpages @@ -1 +1,2 @@ debian/gigi.1 +debian/gigi.properties.5 diff --git a/debian/wpia-gigi.manpages b/debian/wpia-gigi.manpages index 3de344bc..4ba0b4db 100644 --- a/debian/wpia-gigi.manpages +++ b/debian/wpia-gigi.manpages @@ -1 +1,2 @@ debian/gigi.1 +debian/gigi.properties.5