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 Oo Ic insecure Oc 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 Unless the
 357 .Ic insecure
 358 option is specified the notification target
 359 .Ar URL
 360 must be a
 361 .Dq https://
 362 URL to avoid leaking of authentication credentials.
 363 .Pp
 364 The request body contains a JSON object with a
 365 .Dq notifications
 366 property containing an array of notification objects.
 367 The following notification object properties are always present:
 368 .Bl -tag -width authenticated_user
 369 .It Dv repo
 370 The repository name as a string.
 371 .It Dv authenticated_user
 372 The committer's user account as authenticated by
 373 .Xr gotd 8
 374 as a string.
 375 .It Dv type
 376 The notification object type as a string.
 377 .El
 378 .Pp
 379 Each notification object carries additional type-specific properties.
 380 The types and their type-specific properties are:
 381 .Bl -tag -width Ds
 382 .It Dv commit
 383 The commit notification object has the following fields.
 384 Except where noted, all are optional.
 385 .Bl -tag -width Ds
 386 .It Dv short
 387 Boolean, indicates whether the object has all the fields set.
 388 When several commits are batched in a single send operation, not all of
 389 the fields are available for each commit object.
 390 .It Dv id
 391 The commit ID as string, may be abbreviated.
 392 .It Dv committer
 393 An object with the committer information with the following fields:
 394 .Pp
 395 .Bl -tag -compact -width Ds
 396 .It Dv full
 397 Committer's full name.
 398 .It Dv name
 399 Committer's name.
 400 .It Dv mail
 401 Committer's mail address.
 402 .It Dv user
 403 Committer's username.
 404 This is the only field guaranteed to be set.
 405 .El
 406 .It Dv author
 407 An object with the author information.
 408 Has the same fields as the
 409 .Sq committer
 410 but may be unset.
 411 .It Dv date
 412 Number, representing the number of seconds since the Epoch in UTC.
 413 .It Dv short_message
 414 The first line of the commit message.
 415 This field is always set.
 416 .It Dv message
 417 The complete commit message, may be unset.
 418 .It Dv diffstat
 419 An object with the summarized changes, may be unset.
 420 Contains a
 421 .Sq files
 422 field with an array of objects describing the changes per-file and a
 423 .Sq total
 424 field with the cumulative changes.
 425 The changes per-file contains the following fields:
 426 .Pp
 427 .Bl -tag -compact -width removed
 428 .It Dv action
 429 A string describing the action, can be
 430 .Dq added ,
 431 .Dq deleted ,
 432 .Dq modified ,
 433 .Dq mode changed ,
 434 or
 435 .Dq unknown .
 436 .It Dv file
 437 The file path.
 438 .It Dv added
 439 The number of lines added.
 440 .It Dv removed
 441 The number of lines removed.
 442 .El
 443 .Pp
 444 The
 445 .Sq total
 446 object contains two fields:
 447 .Sq added
 448 and
 449 .Sq removed
 450 which are the number of added and removed lines respectively.
 451 .El
 452 .It Dv branch-deleted
 453 The branch deleted notifications has the following fields, all guaranteed
 454 to be set:
 455 .Bl -tag -width Ds
 456 .It Dv ref
 457 The removed branch reference.
 458 .It Dv id
 459 The hash of the commit pointed by the deleted branch.
 460 .El
 461 .It Dv tag
 462 The tag notification has the following fields, all guaranteed to be set:
 463 .Bl -tag -width Ds
 464 .It tag
 465 The tag reference.
 466 .It tagger
 467 The user information, with the same format of the
 468 .Sq committer
 469 field for the
 470 .Sq commit
 471 notification but with all the field guaranteed to be set.
 472 .It Dv date
 473 Number, representing the number of seconds since the Epoch in UTC.
 474 .It Dv object
 475 The object being tagged.
 476 It contains the fields
 477 .Sq type
 478 with the object type and
 479 .Sq id
 480 with the object id being tagged.
 481 .It Dv message
 482 The tag message.
 483 .El
 484 .El
 485 .El
 486 .El
 487 .Sh FILES
 488 .Bl -tag -width Ds -compact
 489 .It Pa /etc/gotd.conf
 490 Location of the
 491 .Nm
 492 configuration file.
 493 .El
 494 .Sh EXAMPLES
 495 .Bd -literal -offset indent
 496 # Run as the default user:
 497 user _gotd
 498
 499 # Listen on the default socket:
 500 listen on "/var/run/gotd.sock"
 501
 502 # This repository can be accessed via ssh://user@example.com/src
 503 repository "src" {
 504         path "/var/git/src.git"
 505         permit rw flan_hacker
 506         permit rw :developers
 507         permit ro anonymous
 508
 509         protect branch "main"
 510         protect tag namespace "refs/tags/"
 511 }
 512
 513 # This repository can be accessed via
 514 # ssh://user@example.com/openbsd/ports
 515 repository "openbsd/ports" {
 516         path "/var/git/ports.git"
 517         permit rw :porters
 518         permit ro anonymous
 519         deny flan_hacker
 520
 521         protect {
 522                 branch "main"
 523                 tag namespace "refs/tags/"
 524         }
 525
 526         notify {
 527                 branch "main"
 528                 reference namespace "refs/tags/"
 529                 email to openbsd-ports-changes@example.com
 530 .\"             url https://example.com/notify/ user "flan_announcer" password "secret"
 531         }
 532 }
 533
 534 # Use a larger request timeout value:
 535 connection request timeout 2h
 536
 537 # Some users are granted a higher concurrent connection limit:
 538 connection {
 539         limit user flan_hacker 16
 540         limit user anonymous 32
 541 }
 542 .Ed
 543 .Sh SEE ALSO
 544 .Xr got 1 ,
 545 .Xr gotsh 1 ,
 546 .Xr gotd 8