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 time.testValidMonths
 128 The maximum time, in months, for which a passed agent quiz is considered recent.
 129 Defaults to \fI12\fR.
 130 .TP
 131 .B time.reverificationDays
 132 The minimum time, in days, that needs to pass before a name can be verified by the same agent again.
 133 Defaults to \fI90\fR.
 134 .TP
 135 .B time.verificationMaxAgeMonths
 136 The maximum time, in months, for which a verification is considered recent.
 137 Defaults to \fI24\fR.
 138 .TP
 139 .B time.verificationFreshMonths
 140 The maximum time period, in months, in which a verification can be entered into the system after it took place.
 141 Defaults to \fI39\fR.
 142 .TP
 143 .B time.emailPingMonths
 144 The maximum time period, in months, in which an email address can be used to create client certificates
 145 before it must be verified again.
 146 Defaults to \fI6\fR.
 147 .TP
 148 .B gigi.uid
 149 Gigi will try to change to this user ID (see
 150 .BR \%setuid (2))
 151 after opening its communication sockets.
 152 This allows Gigi to bind to privileged ports as the superuser
 153 and then drop privileges and run as a normal user.
 154 This should rarely be necessary: it is much safer to not start Gigi as superuser in the first place
 155 and instead only run it with the \fBCAP_NET_BIND_SERVICE\fR capability (see
 156 .BR \%capabilities (7)),
 157 or to have a privileged parent process (for example
 158 .BR \%systemd (1))
 159 create the socket and pass it to Gigi (see
 160 .BR \%http.bindPort ).
 161 If
 162 .B \%gigi.uid
 163 and
 164 .B \%gigi.gid
 165 are both \fI-1\fR, this mechanism is disabled.
 166 Defaults to \fI65534\fR, the user ID of the \fInobody\fR user on Debian GNU/Linux systems.
 167 .TP
 168 .B gigi.gid
 169 Analogous to
 170 .BR \%gigi.uid :
 171 Gigi will try to change to this group ID (see
 172 .BR \%setgid (2))
 173 after opening its communication sockets.
 174 Defaults to \fI65534\fR.
 175 .TP
 176 .B scrypt.params
 177 The parameters to the scrypt password hashing function.
 178 Defaults to \fI14;8;1\fR.
 179 .TP
 180 .B name.www
 181 The Internet domain name for the main application, served both via HTTP and HTTPS.
 182 Defaults to \fI\%www.\fBname.suffix\fR.
 183 .TP
 184 .B name.secure
 185 The Internet domain name for the forced-secure version of the application.
 186 Gigi only serves this domain via HTTPS,
 187 and requires authentication via a client certificate.
 188 Defaults to \fI\%secure.\fBname.suffix\fR.
 189 .TP
 190 .B name.static
 191 The Internet domain name for static resources,
 192 like CSS style sheets and JS resources.
 193 Defaults to \fI\%static.\fBname.suffix\fR.
 194 .TP
 195 .B name.api
 196 The Internet domain name for the Gigi API,
 197 which is used to issue certificates and receive quiz results.
 198 Defaults to \fI\%api.\fBname.suffix\fR.
 199 .TP
 200 .B name.link
 201 The Internet domain name of a link redirector service.
 202 Gigi does not provide this service itself,
 203 but links to it as a place for external documentation.
 204 Defaults to \fI\%link.\fBname.suffix\fR.
 205 .TP
 206 .B name.g2.crt
 207 The Internet domain name of a server that hosts a certificate repository
 208 containing the certificates generated during the NRE procedure.
 209 This service is also not provided by Gigi.
 210 Defaults to \fI\%g2.crt.\fBname.suffix\fR.
 211 .SH SEE ALSO
 212 .BR gigi (1)