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 .Pp
 197 .Bl -tag -width Ds
 198 .It Ic branch Ar name
 199 Protect the named branch.
 200 The branch may be created if it does not exist yet.
 201 Attempts to delete the branch or change its history will be denied.
 202 .Pp
 203 If the
 204 .Ar name
 205 does not already begin with
 206 .Dq refs/heads/
 207 it will be looked up in the
 208 .Dq refs/heads/
 209 reference namespace.
 210 .It Ic branch Ic namespace Ar namespace
 211 Protect the given reference namespace, assuming that references in
 212 this namespace represent branches.
 213 New branches may be created in the namespace.
 214 Attempts to change the history of branches or delete them will be denied.
 215 .Pp
 216 The
 217 .Ar namespace
 218 argument must be absolute, starting with
 219 .Dq refs/ .
 220 .It Ic tag Ic namespace Ar namespace
 221 Protect the given reference namespace, assuming that references in
 222 this namespace represent tags.
 223 New tags may be created in the namespace.
 224 Attempts to change or delete existing tags will be denied.
 225 .Pp
 226 The
 227 .Ar namespace
 228 argument must be absolute, starting with
 229 .Dq refs/ .
 230 .El
 231 .Pp
 232 The special reference namespaces
 233 .Dq refs/got/
 234 and
 235 .Dq refs/remotes/
 236 do not need to be listed in
 237 .Nm .
 238 These namespaces are always protected and even attempts to create new
 239 references in these namespaces will always be denied.
 240 .El
 241 .Sh FILES
 242 .Bl -tag -width Ds -compact
 243 .It Pa /etc/gotd.conf
 244 Location of the
 245 .Nm
 246 configuration file.
 247 .El
 248 .Sh EXAMPLES
 249 .Bd -literal -offset indent
 250 # Run as the default user:
 251 user _gotd
 252
 253 # Listen on the default socket:
 254 listen on "/var/run/gotd.sock"
 255
 256 # This repository can be accessed via ssh://user@example.com/src
 257 repository "src" {
 258         path "/var/git/src.git"
 259         permit rw flan_hacker
 260         permit rw :developers
 261         permit ro anonymous
 262
 263         protect branch "main"
 264         protect tag namespace "refs/tags/"
 265 }
 266
 267 # This repository can be accessed via
 268 # ssh://user@example.com/openbsd/ports
 269 repository "openbsd/ports" {
 270         path "/var/git/ports.git"
 271         permit rw :porters
 272         permit ro anonymous
 273         deny flan_hacker
 274
 275         protect {
 276                 branch "main"
 277                 tag namespace "refs/tags/"
 278         }
 279 }
 280
 281 # Use a larger request timeout value:
 282 connection request timeout 2h
 283
 284 # Some users are granted a higher concurrent connection limit:
 285 connection {
 286         limit user flan_hacker 16
 287         limit user anonymous 32
 288 }
 289 .Ed
 290 .Sh SEE ALSO
 291 .Xr got 1 ,
 292 .Xr gotsh 1 ,
 293 .Xr gotd 8