gotd/gotd.conf.5

   1 .\"
   2 .\" Copyright (c) 2022 Stefan Sperling <stsp@openbsd.org>
   3 .\"
   4 .\" Permission to use, copy, modify, and distribute this software for any
   5 .\" purpose with or without fee is hereby granted, provided that the above
   6 .\" copyright notice and this permission notice appear in all copies.
   7 .\"
   8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
   9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  15 .\"
  16 .Dd $Mdocdate$
  17 .Dt GOTD.CONF 5
  18 .Os
  19 .Sh NAME
  20 .Nm gotd.conf
  21 .Nd gotd configuration file
  22 .Sh DESCRIPTION
  23 .Nm
  24 is the run-time configuration file for
  25 .Xr gotd 8 .
  26 .Pp
  27 The file format is line-based, with one configuration directive per line.
  28 Any lines beginning with a
  29 .Sq #
  30 are treated as comments and ignored.
  31 .Sh GLOBAL CONFIGURATION
  32 The available global configuration directives are as follows:
  33 .Bl -tag -width Ds
  34 .It Ic connection Ar option
  35 Set the specified options and limits for connections to the
  36 .Xr gotd 8
  37 unix socket.
  38 .Pp
  39 The
  40 .Ic connection
  41 directive may be specified multiple times, and multiple
  42 .Ar option
  43 arguments may be specified within curly braces:
  44 .Pp
  45 .Ic connection Brq Ar ...
  46 .Pp
  47 Each option should only be specified once.
  48 If a given option is listed multiple times, the last line which sets this
  49 option wins.
  50 .Pp
  51 Valid connection options are:
  52 .Bl -tag -width Ds
  53 .It Ic request timeout Ar seconds
  54 Specify the inactivity timeout for operations between client and server.
  55 If this timeout is exceeded while a Git protocol request is being processed,
  56 the request will be aborted and the connection will be terminated.
  57 .Pp
  58 The timeout value may also have a suffix indicating its unit of measure.
  59 Supported suffixes are:
  60 .Pp
  61 .Bl -tag -compact -width tenletters
  62 .It Ar s No or Ar S
  63 seconds
  64 .It Ar m No or Ar M
  65 minutes
  66 .It Ar h No or Ar H
  67 hours
  68 .El
  69 .Pp
  70 The default timeout is 1h (3600 seconds, one hour).
  71 This should only be changed if legitimate requests are exceeding the default
  72 timeout for some reason, such as the server spending an extraordinary
  73 amount of time generating a pack file.
  74 .It Ic limit Ic user Ar identity Ar number
  75 Limit the maximum amount of concurrent connections by the user with
  76 the username
  77 .Ar identity
  78 to
  79 .Ar number .
  80 Numeric user IDs are also accepted.
  81 .Pp
  82 The default per-user limit is 4.
  83 This should only be changed if concurrent connections from a given user are
  84 expected to exceed the default limit, for example if an anonymous user
  85 is granted read access and many concurrent connections will share this
  86 anonymous user identity.
  87 .El
  88 .It Ic listen on Ar path
  89 Set the path to the unix socket which
  90 .Xr gotd 8
  91 should listen on.
  92 If not specified, the path
  93 .Pa /var/run/gotd.sock
  94 will be used.
  95 .It Ic user Ar user
  96 Set the
  97 .Ar user
  98 which will run
  99 .Xr gotd 8 .
 100 Initially,
 101 .Xr gotd 8
 102 requires root privileges in order to create its unix socket.
 103 Afterwards,
 104 .Xr gotd 8
 105 drops privileges to the specified
 106 .Ar user .
 107 If not specified, the user _gotd will be used.
 108 .El
 109 .Sh REPOSITORY CONFIGURATION
 110 At least one repository context must exist for
 111 .Xr gotd 8
 112 to function.
 113 For each repository, access rules must be configured using the
 114 .Ic permit
 115 and
 116 .Ic deny
 117 configuration directives.
 118 Multiple access rules can be specified, and the last matching rule
 119 determines the action taken.
 120 If no rule matches, access to the repository is denied.
 121 .Pp
 122 A repository context is declared with a unique
 123 .Ar name ,
 124 followed by repository-specific configuration directives inside curly braces:
 125 .Pp
 126 .Ic repository Ar name Brq ...
 127 .Pp
 128 .Xr got 1
 129 and
 130 .Xr git 1
 131 clients can connect to a repository by including the repository's unique
 132 .Ar name
 133 in the request URL.
 134 Clients appending the string
 135 .Dq .git
 136 to the
 137 .Ar name
 138 will also be accepted.
 139 .Pp
 140 If desired, the
 141 .Ar name
 142 may contain path-separators,
 143 .Dq / ,
 144 to expose repositories as part of a virtual client-visible directory hierarchy.
 145 .Pp
 146 The available repository configuration directives are as follows:
 147 .Bl -tag -width Ds
 148 .It Ic deny Ar identity
 149 Deny repository access to users with the username
 150 .Ar identity .
 151 Group names may be matched by prepending a colon
 152 .Pq Sq \&:
 153 to
 154 .Ar identity .
 155 Numeric IDs are also accepted.
 156 .It Ic path Ar path
 157 Set the path to the Git repository.
 158 Must be specified.
 159 .It Ic permit Ar mode Ar identity
 160 Permit repository access to users with the username
 161 .Ar identity .
 162 The
 163 .Ar mode
 164 argument must be set to either
 165 .Ic ro
 166 for read-only access,
 167 or
 168 .Ic rw
 169 for read-write access.
 170 Group names may be matched by prepending a colon
 171 .Pq Sq \&:
 172 to
 173 .Ar identity .
 174 Numeric IDs are also accepted.
 175 .It Ic protect Brq Ar ...
 176 The
 177 .Cm protect
 178 directive may be used to protect branches and tags in a repository
 179 from being overwritten by potentially destructive client-side commands,
 180 such as when
 181 .Cm got send -f
 182 and
 183 .Cm git push -f
 184 are used to change the history of a branch.
 185 .Pp
 186 To build a set of protected branches and tags, multiple
 187 .Ic protect
 188 directives may be specified per repository and
 189 multiple
 190 .Ic protect
 191 directive parameters may be specified within curly braces.
 192 .Pp
 193 The available
 194 .Cm protect
 195 parameters are as follows:
 196 .Bl -tag -width Ds
 197 .It Ic branch Ar name
 198 Protect the named branch.
 199 The branch may be created if it does not exist yet.
 200 Attempts to delete the branch or change its history will be denied.
 201 .Pp
 202 If the
 203 .Ar name
 204 does not already begin with
 205 .Dq refs/heads/
 206 it will be looked up in the
 207 .Dq refs/heads/
 208 reference namespace.
 209 .It Ic branch Ic namespace Ar namespace
 210 Protect the given reference namespace, assuming that references in
 211 this namespace represent branches.
 212 New branches may be created in the namespace.
 213 Attempts to change the history of branches or delete them will be denied.
 214 .Pp
 215 The
 216 .Ar namespace
 217 argument must be absolute, starting with
 218 .Dq refs/ .
 219 .It Ic tag Ic namespace Ar namespace
 220 Protect the given reference namespace, assuming that references in
 221 this namespace represent tags.
 222 New tags may be created in the namespace.
 223 Attempts to change or delete existing tags will be denied.
 224 .Pp
 225 The
 226 .Ar namespace
 227 argument must be absolute, starting with
 228 .Dq refs/ .
 229 .El
 230 .Pp
 231 The special reference namespaces
 232 .Dq refs/got/
 233 and
 234 .Dq refs/remotes/
 235 do not need to be listed in
 236 .Nm .
 237 These namespaces are always protected and even attempts to create new
 238 references in these namespaces will always be denied.
 239 .It Ic notify Brq Ar ...
 240 The
 241 .Ic notify
 242 directive enables notifications about new commits or tags
 243 added to the repository.
 244 .Pp
 245 Notifications via email require an SMTP daemon which accepts mail
 246 for forwarding without requiring client authentication or encryption.
 247 On
 248 .Ox
 249 the
 250 .Xr smtpd 8
 251 daemon can be used for this purpose.
 252 The default content of email notifications looks similar to the output of the
 253 .Cm got log -d
 254 command.
 255 .Pp
 256 Notifications via HTTP require a HTTP or HTTPS server which is accepting
 257 POST requests with or without HTTP Basic authentication.
 258 Depending on the use case a custom server-side CGI script may be required
 259 for the processing of notifications.
 260 HTTP notifications can achieve functionality
 261 similar to Git's server-side post-receive hook script with
 262 .Xr gotd 8
 263 by triggering arbitrary post-commit actions via the HTTP server.
 264 .Pp
 265 The
 266 .Ic notify
 267 directive expects parameters which must be enclosed in curly braces.
 268 The available parameters are as follows:
 269 .Bl -tag -width Ds
 270 .It Ic branch Ar name
 271 Send notifications about commits to the named branch.
 272 The
 273 .Ar name
 274 will be looked up in the
 275 .Dq refs/heads/
 276 reference namespace.
 277 This directive may be specified multiple times to build a list of
 278 branches to send notifications for.
 279 If neither a
 280 .Ic branch
 281 nor a
 282 .Ic reference namespace
 283 are specified then changes to any reference will trigger notifications.
 284 .It Ic reference Ic namespace Ar namespace
 285 Send notifications about commits or tags within a reference namespace.
 286 This directive may be specified multiple times to build a list of
 287 namespaces to send notifications for.
 288 If neither a
 289 .Ic branch
 290 nor a
 291 .Ic reference namespace
 292 are specified then changes to any reference will trigger notifications.
 293 .It Ic email Oo Ic from Ar sender Oc Ic to Ar recipient Oo Ic reply to Ar responder Oc Oo Ic relay Ar hostname Oo Ic port Ar port Oc Oc
 294 Send notifications via email to the specified
 295 .Ar recipient .
 296 This directive may be specified multiple times to build a list of
 297 recipients to send notifications to.
 298 .Pp
 299 The
 300 .Ar recipient
 301 must be an email addresses that accepts mail.
 302 The
 303 .Ar sender
 304 will be used as the From address.
 305 If not specified, the sender defaults to an email address composed of the user
 306 account running
 307 .Xr gotd 8
 308 and the local hostname.
 309 .Pp
 310 If a
 311 .Ar responder
 312 is specified via the
 313 .Ic reply to
 314 directive, the
 315 .Ar responder
 316 will be used as the Reply-to address.
 317 Setting the Reply-to header can be useful if replies should go to a
 318 mailing list instead of the
 319 .Ar sender ,
 320 for example.
 321 .Pp
 322 By default, mail will be sent to the SMTP server listening on the loopback
 323 address 127.0.0.1 on port 25.
 324 The
 325 .Ic relay
 326 and
 327 .Ic port
 328 directives can be used to specify a different SMTP server address and port.
 329 .It Ic url Ar URL Oo Ic user Ar user Ic password Ar password Oc
 330 Send notifications via HTTP.
 331 This directive may be specified multiple times to build a list of
 332 HTTP servers to send notifications to.
 333 .Pp
 334 The notification will be sent as a POST request to the given
 335 .Ar URL ,
 336 which must be a valid HTTP URL and begin with either
 337 .Dq http://
 338 or
 339 .Dq https:// .
 340 If HTTPS is used, sending of notifications will only succeed if
 341 no TLS errors occur.
 342 .Pp
 343 The optional
 344 .Ic user
 345 and
 346 .Ic password
 347 directives enable HTTP Basic authentication.
 348 If used, both a
 349 .Ar user
 350 and a
 351 .Ar password
 352 must be specified.
 353 The
 354 .Ar password
 355 must not be an empty string.
 356 .Pp
 357 The request body contains a JSON document with the following objects:
 358 .Bl -tag -width Ds
 359 .It { "notifications" : array }
 360 The top-level object contains an array of all notifications in this request.
 361 .El
 362 .El
 363 .El
 364 .Sh FILES
 365 .Bl -tag -width Ds -compact
 366 .It Pa /etc/gotd.conf
 367 Location of the
 368 .Nm
 369 configuration file.
 370 .El
 371 .Sh EXAMPLES
 372 .Bd -literal -offset indent
 373 # Run as the default user:
 374 user _gotd
 375
 376 # Listen on the default socket:
 377 listen on "/var/run/gotd.sock"
 378
 379 # This repository can be accessed via ssh://user@example.com/src
 380 repository "src" {
 381         path "/var/git/src.git"
 382         permit rw flan_hacker
 383         permit rw :developers
 384         permit ro anonymous
 385
 386         protect branch "main"
 387         protect tag namespace "refs/tags/"
 388 }
 389
 390 # This repository can be accessed via
 391 # ssh://user@example.com/openbsd/ports
 392 repository "openbsd/ports" {
 393         path "/var/git/ports.git"
 394         permit rw :porters
 395         permit ro anonymous
 396         deny flan_hacker
 397
 398         protect {
 399                 branch "main"
 400                 tag namespace "refs/tags/"
 401         }
 402
 403         notify {
 404                 branch "main"
 405                 reference namespace "refs/tags/"
 406                 email to openbsd-ports-changes@example.com
 407 .\"             url https://example.com/notify/ user "flan_announcer" password "secret"
 408         }
 409 }
 410
 411 # Use a larger request timeout value:
 412 connection request timeout 2h
 413
 414 # Some users are granted a higher concurrent connection limit:
 415 connection {
 416         limit user flan_hacker 16
 417         limit user anonymous 32
 418 }
 419 .Ed
 420 .Sh SEE ALSO
 421 .Xr got 1 ,
 422 .Xr gotsh 1 ,
 423 .Xr gotd 8