debian/gigi.properties.5

   1 .\"                                      Hey, EMACS: -*- nroff -*-
   2 .\" (C) Copyright 2014-2017 WPIA Software Team <software@wpia.club>,
   3 .\"
   4 .TH GIGI.PROPERTIES 5 "March 21, 2017" WPIA
   5 .\" Please adjust this date whenever revising the manpage.
   6 .SH NAME
   7 gigi.properties \- Gigi configuration file
   8 .SH SYNOPSIS
   9 .I /etc/gigi.properties
  10 .SH DESCRIPTION
  11 The file
  12 .I gigi.properties
  13 contains the configuration for the WPIA
  14 .BR gigi (1)
  15 system.
  16 It is a Java properties file with \fIname=value\fR assignments and \fI# comment lines\fR.
  17
  18 The following options can be set:
  19 .TP
  20 .B appName
  21 The name of the main application, for example \fISomeCA\fR.
  22 .TP
  23 .B appIdentifier
  24 The
  25 .B \%appName
  26 in a format suitable for inclusion in Internet domain names and HTTP URLs,
  27 used in challenges to verify Internet domain name ownership via DNS or HTTP.
  28 This identifier should be limited to lowercase ASCII letters, numbers and perhaps hyphens.
  29 .TP
  30 .B name.suffix
  31 The main Internet domain name suffix of the application.
  32 Used for administrative email addresses (e.g., \fIsupport@\fBname.suffix\fR)
  33 and for all other domain names that are not explicitly specified (see \fBname.*\fR below).
  34 Defaults to \fIwpia.local\fR.
  35 .TP
  36 .B host
  37 The IP address that Gigi listens on, for example 127.0.0.1.
  38 .TP
  39 .B http.port
  40 The port on which Gigi is reachable from outside via HTTP
  41 (that is, the port it uses to refer to itself in hyperlinks),
  42 and also the port on which Gigi listens unless
  43 .B \%http.bindPort
  44 is specified.
  45 Usually 80.
  46 .TP
  47 .B https.port
  48 The port on which Gigi is reachable from outside via HTTPS
  49 (that is, the port it uses to refer to itself in hyperlinks),
  50 and also the port on which Gigi listens unless
  51 .B \%https.bindPort
  52 is specified.
  53 Usually 443.
  54 .TP
  55 .B http.bindPort
  56 The port on which Gigi listens for HTTP requests, or
  57 .IR stdin
  58 to specify that Gigi has received a socket on file descriptor 0 (standard input)
  59 which it should use for HTTP
  60 (for example, via
  61 .BR \%systemd.socket (5)
  62 or
  63 .BR inetd (1)).
  64 .TP
  65 .B https.bindPort
  66 The port on which Gigi listens for HTTPS requests, or
  67 .IR stdin
  68 to specify that Gigi has received a socket on file descriptor 0 (standard input)
  69 which it should use for HTTPS
  70 (for example, via
  71 .BR \%systemd.socket (5)
  72 or
  73 .BR inetd (1)).
  74 Not used if
  75 .B \%proxy
  76 is
  77 .IR true .
  78 .TP
  79 .B proxy
  80 If
  81 .IR true ,
  82 Gigi expects to sit behind a proxy server that handles HTTPS,
  83 for example
  84 .BR \%apache2 (8)
  85 or
  86 .BR \%nginx (1).
  87 The real client IP, real protocol and (if present) real client certificate
  88 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.
  89 .B \%https.bindPort
  90 is not used.
  91 .TP
  92 .B sql.driver
  93 The JDBC driver used for connecting to the database.
  94 As PostgreSQL is currently the only supported database,
  95 the only value that really makes sense is \fI\%org.postgresql.Driver\fR.
  96 .TP
  97 .B sql.url
  98 The database URL that Gigi connects to,
  99 for example \fI\%jdbc:postgresql://localhost/gigi\fR.
 100 .TP
 101 .B sql.user
 102 The user name that Gigi uses to connect to the database.
 103 .TP
 104 .B sql.password
 105 The password that Gigi uses to connect to the database.
 106 .TP
 107 .B emailProvider
 108 The fully-qualified name of a Java class that Gigi uses to send emails.
 109 The only value available in production is \fIclub.wpia.gigi.email.Sendmail\fR.
 110 .TP
 111 .B emailProvider.smtpHost
 112 The host to which the
 113 .B \%emailProvider
 114 should try to connect.
 115 Defaults to \fI\%localhost\fR.
 116 .TP
 117 .B emailProvider.smtpPort
 118 The port to which the
 119 .B \%emailProvider
 120 should try to connect.
 121 Defaults to \fI25\fR.
 122 .TP
 123 .B highFinancialValue
 124 A path to a plain text file of Internet domain names, one per line,
 125 which Gigi should refuse to issue certificates to.
 126 .TP
 127 .B knownPasswordHashes
 128 A path to a file of SHA-1 hashes of known passwords.
 129 The file should contain the hashes in binary format, without any separators, and should be sorted.
 130 Gigi will refuse user passwords with hashes that are found in this file.
 131 If this option is specified, Gigi will refuse startup if the file cannot be opened,
 132 otherwise it will attempt to use the file
 133 .I /usr/share/pwned-passwords/pwned-passwords.bin
 134 (provided by the \fBpwned-passwords-bin\fR package)
 135 but continue startup if the file cannot be opened.
 136 .TP
 137 .B time.testValidMonths
 138 The maximum time, in months, for which a passed agent quiz is considered recent.
 139 Defaults to \fI12\fR.
 140 .TP
 141 .B time.reverificationDays
 142 The minimum time, in days, that needs to pass before a name can be verified by the same agent again.
 143 Defaults to \fI90\fR.
 144 .TP
 145 .B time.verificationMaxAgeMonths
 146 The maximum time, in months, for which a verification is considered recent.
 147 Defaults to \fI24\fR.
 148 .TP
 149 .B time.verificationFreshMonths
 150 The maximum time period, in months, in which a verification can be entered into the system after it took place.
 151 Defaults to \fI39\fR.
 152 .TP
 153 .B time.emailPingMonths
 154 The maximum time period, in months, in which an email address can be used to create client certificates
 155 before it must be verified again.
 156 Defaults to \fI6\fR.
 157 .TP
 158 .B gigi.uid
 159 Gigi will try to change to this user ID (see
 160 .BR \%setuid (2))
 161 after opening its communication sockets.
 162 This allows Gigi to bind to privileged ports as the superuser
 163 and then drop privileges and run as a normal user.
 164 This should rarely be necessary: it is much safer to not start Gigi as superuser in the first place
 165 and instead only run it with the \fBCAP_NET_BIND_SERVICE\fR capability (see
 166 .BR \%capabilities (7)),
 167 or to have a privileged parent process (for example
 168 .BR \%systemd (1))
 169 create the socket and pass it to Gigi (see
 170 .BR \%http.bindPort ).
 171 If
 172 .B \%gigi.uid
 173 and
 174 .B \%gigi.gid
 175 are both \fI-1\fR, this mechanism is disabled.
 176 Defaults to \fI65534\fR, the user ID of the \fInobody\fR user on Debian GNU/Linux systems.
 177 .TP
 178 .B gigi.gid
 179 Analogous to
 180 .BR \%gigi.uid :
 181 Gigi will try to change to this group ID (see
 182 .BR \%setgid (2))
 183 after opening its communication sockets.
 184 Defaults to \fI65534\fR.
 185 .TP
 186 .B scrypt.params
 187 The parameters to the scrypt password hashing function.
 188 Defaults to \fI14;8;1\fR.
 189 .TP
 190 .B name.www
 191 The Internet domain name for the main application, served both via HTTP and HTTPS.
 192 Defaults to \fI\%www.\fBname.suffix\fR.
 193 .TP
 194 .B name.secure
 195 The Internet domain name for the forced-secure version of the application.
 196 Gigi only serves this domain via HTTPS,
 197 and requires authentication via a client certificate.
 198 Defaults to \fI\%secure.\fBname.suffix\fR.
 199 .TP
 200 .B name.static
 201 The Internet domain name for static resources,
 202 like CSS style sheets and JS resources.
 203 Defaults to \fI\%static.\fBname.suffix\fR.
 204 .TP
 205 .B name.api
 206 The Internet domain name for the Gigi API,
 207 which is used to issue certificates and receive quiz results.
 208 Defaults to \fI\%api.\fBname.suffix\fR.
 209 .TP
 210 .B name.link
 211 The Internet domain name of a link redirector service.
 212 Gigi does not provide this service itself,
 213 but links to it as a place for external documentation.
 214 Defaults to \fI\%link.\fBname.suffix\fR.
 215 .TP
 216 .B name.g2.crt
 217 The Internet domain name of a server that hosts a certificate repository
 218 containing the certificates generated during the NRE procedure.
 219 This service is also not provided by Gigi.
 220 Defaults to \fI\%g2.crt.\fBname.suffix\fR.
 221 .SH SEE ALSO
 222 .BR gigi (1)