1 3efd8e31 2022-10-23 thomas .\"
  2 3efd8e31 2022-10-23 thomas .\" Copyright (c) 2022 Stefan Sperling <stsp@openbsd.org>
  3 3efd8e31 2022-10-23 thomas .\"
  4 3efd8e31 2022-10-23 thomas .\" Permission to use, copy, modify, and distribute this software for any
  5 3efd8e31 2022-10-23 thomas .\" purpose with or without fee is hereby granted, provided that the above
  6 3efd8e31 2022-10-23 thomas .\" copyright notice and this permission notice appear in all copies.
  7 3efd8e31 2022-10-23 thomas .\"
  8 3efd8e31 2022-10-23 thomas .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  9 3efd8e31 2022-10-23 thomas .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 10 3efd8e31 2022-10-23 thomas .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 11 3efd8e31 2022-10-23 thomas .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 12 3efd8e31 2022-10-23 thomas .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 13 3efd8e31 2022-10-23 thomas .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 14 3efd8e31 2022-10-23 thomas .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 15 3efd8e31 2022-10-23 thomas .\"
 16 3efd8e31 2022-10-23 thomas .Dd $Mdocdate$
 17 3efd8e31 2022-10-23 thomas .Dt GOTD.CONF 5
 18 3efd8e31 2022-10-23 thomas .Os
 19 3efd8e31 2022-10-23 thomas .Sh NAME
 20 3efd8e31 2022-10-23 thomas .Nm gotd.conf
 21 3efd8e31 2022-10-23 thomas .Nd gotd configuration file
 22 3efd8e31 2022-10-23 thomas .Sh DESCRIPTION
 23 3efd8e31 2022-10-23 thomas .Nm
 24 3efd8e31 2022-10-23 thomas is the run-time configuration file for
 25 3efd8e31 2022-10-23 thomas .Xr gotd 8 .
 26 3efd8e31 2022-10-23 thomas .Pp
 27 3efd8e31 2022-10-23 thomas The file format is line-based, with one configuration directive per line.
 28 3efd8e31 2022-10-23 thomas Any lines beginning with a
 29 3efd8e31 2022-10-23 thomas .Sq #
 30 3efd8e31 2022-10-23 thomas are treated as comments and ignored.
 31 3efd8e31 2022-10-23 thomas .Sh GLOBAL CONFIGURATION
 32 3efd8e31 2022-10-23 thomas The available global configuration directives are as follows:
 33 3efd8e31 2022-10-23 thomas .Bl -tag -width Ds
 34 0781db0e 2023-01-06 thomas .It Ic connection Ar option
 35 0781db0e 2023-01-06 thomas Set the specified options and limits for connections to the
 36 0781db0e 2023-01-06 thomas .Xr gotd 8
 37 0781db0e 2023-01-06 thomas unix socket.
 38 0781db0e 2023-01-06 thomas .Pp
 39 0781db0e 2023-01-06 thomas The
 40 0781db0e 2023-01-06 thomas .Ic connection
 41 0781db0e 2023-01-06 thomas directive may be specified multiple times, and multiple
 42 0781db0e 2023-01-06 thomas .Ar option
 43 0781db0e 2023-01-06 thomas arguments may be specified within curly braces:
 44 0781db0e 2023-01-06 thomas .Pp
 45 0781db0e 2023-01-06 thomas .Ic connection Brq Ar ...
 46 0781db0e 2023-01-06 thomas .Pp
 47 0781db0e 2023-01-06 thomas Each option should only be specified once.
 48 0781db0e 2023-01-06 thomas If a given option is listed multiple times, the last line which sets this
 49 0781db0e 2023-01-06 thomas option wins.
 50 0781db0e 2023-01-06 thomas .Pp
 51 0781db0e 2023-01-06 thomas Valid connection options are:
 52 0781db0e 2023-01-06 thomas .Bl -tag -width Ds
 53 0781db0e 2023-01-06 thomas .It Ic request timeout Ar seconds
 54 0781db0e 2023-01-06 thomas Specify the inactivity timeout for operations between client and server.
 55 0781db0e 2023-01-06 thomas If this timeout is exceeded while a Git protocol request is being processed,
 56 0781db0e 2023-01-06 thomas the request will be aborted and the connection will be terminated.
 57 0781db0e 2023-01-06 thomas .Pp
 58 77d755e8 2023-01-06 thomas The timeout value may also have a suffix indicating its unit of measure.
 59 77d755e8 2023-01-06 thomas Supported suffixes are:
 60 77d755e8 2023-01-06 thomas .Pp
 61 77d755e8 2023-01-06 thomas .Bl -tag -compact -width tenletters
 62 77d755e8 2023-01-06 thomas .It Ar s No or Ar S
 63 77d755e8 2023-01-06 thomas seconds
 64 77d755e8 2023-01-06 thomas .It Ar m No or Ar M
 65 77d755e8 2023-01-06 thomas minutes
 66 77d755e8 2023-01-06 thomas .It Ar h No or Ar H
 67 77d755e8 2023-01-06 thomas hours
 68 77d755e8 2023-01-06 thomas .El
 69 77d755e8 2023-01-06 thomas .Pp
 70 77d755e8 2023-01-06 thomas The default timeout is 1h (3600 seconds, one hour).
 71 0781db0e 2023-01-06 thomas This should only be changed if legitimate requests are exceeding the default
 72 0781db0e 2023-01-06 thomas timeout for some reason, such as the server spending an extraordinary
 73 0781db0e 2023-01-06 thomas amount of time generating a pack file.
 74 0781db0e 2023-01-06 thomas .It Ic limit Ic user Ar identity Ar number
 75 0781db0e 2023-01-06 thomas Limit the maximum amount of concurrent connections by the user with
 76 0781db0e 2023-01-06 thomas the username
 77 0781db0e 2023-01-06 thomas .Ar identity
 78 0781db0e 2023-01-06 thomas to
 79 0781db0e 2023-01-06 thomas .Ar number .
 80 0781db0e 2023-01-06 thomas Numeric user IDs are also accepted.
 81 0781db0e 2023-01-06 thomas .Pp
 82 0781db0e 2023-01-06 thomas The default per-user limit is 4.
 83 0781db0e 2023-01-06 thomas This should only be changed if concurrent connections from a given user are
 84 0781db0e 2023-01-06 thomas expected to exceed the default limit, for example if an anonymous user
 85 0781db0e 2023-01-06 thomas is granted read access and many concurrent connections will share this
 86 0781db0e 2023-01-06 thomas anonymous user identity.
 87 0781db0e 2023-01-06 thomas .El
 88 3efd8e31 2022-10-23 thomas .It Ic unix_socket Ar path
 89 3efd8e31 2022-10-23 thomas Set the path to the unix socket which
 90 3efd8e31 2022-10-23 thomas .Xr gotd 8
 91 3efd8e31 2022-10-23 thomas should listen on.
 92 3efd8e31 2022-10-23 thomas If not specified, the path
 93 3efd8e31 2022-10-23 thomas .Pa /var/run/gotd.sock
 94 3efd8e31 2022-10-23 thomas will be used.
 95 3efd8e31 2022-10-23 thomas .It Ic unix_group Ar group
 96 3efd8e31 2022-10-23 thomas Set the
 97 3efd8e31 2022-10-23 thomas .Ar group ,
 98 3efd8e31 2022-10-23 thomas defined in the
 99 3efd8e31 2022-10-23 thomas .Xr group 5
100 3efd8e31 2022-10-23 thomas file, which is allowed to access
101 3efd8e31 2022-10-23 thomas .Xr gotd 8
102 3efd8e31 2022-10-23 thomas via
103 3efd8e31 2022-10-23 thomas .Xr gotsh 1 .
104 3efd8e31 2022-10-23 thomas The
105 3efd8e31 2022-10-23 thomas .Xr gotd 8
106 3efd8e31 2022-10-23 thomas user must be a secondary member of this group.
107 3efd8e31 2022-10-23 thomas If not specified, the group _gotsh will be used.
108 3efd8e31 2022-10-23 thomas .It Ic user Ar user
109 3efd8e31 2022-10-23 thomas Set the
110 3efd8e31 2022-10-23 thomas .Ar user
111 3efd8e31 2022-10-23 thomas which will run
112 3efd8e31 2022-10-23 thomas .Xr gotd 8 .
113 3efd8e31 2022-10-23 thomas Initially,
114 3efd8e31 2022-10-23 thomas .Xr gotd 8
115 414e37cb 2022-12-30 thomas requires root privileges in order to create its unix socket.
116 3efd8e31 2022-10-23 thomas Afterwards,
117 3efd8e31 2022-10-23 thomas .Xr gotd 8
118 3efd8e31 2022-10-23 thomas drops privileges to the specified
119 3efd8e31 2022-10-23 thomas .Ar user .
120 3efd8e31 2022-10-23 thomas If not specified, the user _gotd will be used.
121 3efd8e31 2022-10-23 thomas .El
122 3efd8e31 2022-10-23 thomas .Sh REPOSITORY CONFIGURATION
123 3efd8e31 2022-10-23 thomas At least one repository context must exist for
124 3efd8e31 2022-10-23 thomas .Xr gotd 8
125 3efd8e31 2022-10-23 thomas to function.
126 729a7e24 2022-11-17 thomas For each repository, access rules must be configured using the
127 729a7e24 2022-11-17 thomas .Ic permit
128 729a7e24 2022-11-17 thomas and
129 729a7e24 2022-11-17 thomas .Ic deny
130 729a7e24 2022-11-17 thomas configuration directives.
131 729a7e24 2022-11-17 thomas Multiple access rules can be specified, and the last matching rule
132 729a7e24 2022-11-17 thomas determines the action taken.
133 729a7e24 2022-11-17 thomas If no rule matches, access to the repository is denied.
134 3efd8e31 2022-10-23 thomas .Pp
135 3efd8e31 2022-10-23 thomas A repository context is declared with a unique
136 3efd8e31 2022-10-23 thomas .Ar name ,
137 3efd8e31 2022-10-23 thomas followed by repository-specific configuration directives inside curly braces:
138 3efd8e31 2022-10-23 thomas .Pp
139 3efd8e31 2022-10-23 thomas .Ic repository Ar name Brq ...
140 3efd8e31 2022-10-23 thomas .Pp
141 3efd8e31 2022-10-23 thomas .Xr got 1
142 3efd8e31 2022-10-23 thomas and
143 3efd8e31 2022-10-23 thomas .Xr git 1
144 3efd8e31 2022-10-23 thomas clients can connect to a repository by including the repository's unique
145 3efd8e31 2022-10-23 thomas .Ar name
146 3efd8e31 2022-10-23 thomas in the request URL.
147 3efd8e31 2022-10-23 thomas Clients appending the string
148 3efd8e31 2022-10-23 thomas .Dq .git
149 3efd8e31 2022-10-23 thomas to the
150 3efd8e31 2022-10-23 thomas .Ar name
151 3efd8e31 2022-10-23 thomas will also be accepted.
152 3efd8e31 2022-10-23 thomas .Pp
153 3efd8e31 2022-10-23 thomas If desired, the
154 3efd8e31 2022-10-23 thomas .Ar name
155 3efd8e31 2022-10-23 thomas may contain path-separators,
156 3efd8e31 2022-10-23 thomas .Dq / ,
157 3efd8e31 2022-10-23 thomas to expose repositories as part of a virtual client-visible directory hierarchy.
158 3efd8e31 2022-10-23 thomas .Pp
159 3efd8e31 2022-10-23 thomas The available repository configuration directives are as follows:
160 3efd8e31 2022-10-23 thomas .Bl -tag -width Ds
161 729a7e24 2022-11-17 thomas .It Ic deny Ar identity
162 729a7e24 2022-11-17 thomas Deny repository access to users with the username
163 729a7e24 2022-11-17 thomas .Ar identity .
164 729a7e24 2022-11-17 thomas Group names may be matched by prepending a colon
165 729a7e24 2022-11-17 thomas .Pq Sq \&:
166 729a7e24 2022-11-17 thomas to
167 729a7e24 2022-11-17 thomas .Ar identity .
168 729a7e24 2022-11-17 thomas Numeric IDs are also accepted.
169 3efd8e31 2022-10-23 thomas .It Ic path Ar path
170 3efd8e31 2022-10-23 thomas Set the path to the Git repository.
171 88f1bb6d 2023-01-02 thomas Must be specified.
172 729a7e24 2022-11-17 thomas .It Ic permit Ar mode Ar identity
173 729a7e24 2022-11-17 thomas Permit repository access to users with the username
174 729a7e24 2022-11-17 thomas .Ar identity .
175 729a7e24 2022-11-17 thomas The
176 729a7e24 2022-11-17 thomas .Ar mode
177 729a7e24 2022-11-17 thomas argument must be set to either
178 729a7e24 2022-11-17 thomas .Ic ro
179 729a7e24 2022-11-17 thomas for read-only access,
180 729a7e24 2022-11-17 thomas or
181 729a7e24 2022-11-17 thomas .Ic rw
182 729a7e24 2022-11-17 thomas for read-write access.
183 729a7e24 2022-11-17 thomas Group names may be matched by prepending a colon
184 729a7e24 2022-11-17 thomas .Pq Sq \&:
185 729a7e24 2022-11-17 thomas to
186 729a7e24 2022-11-17 thomas .Ar identity .
187 729a7e24 2022-11-17 thomas Numeric IDs are also accepted.
188 2bb0ff1b 2022-11-17 thomas .El
189 3efd8e31 2022-10-23 thomas .Sh FILES
190 3efd8e31 2022-10-23 thomas .Bl -tag -width Ds -compact
191 3efd8e31 2022-10-23 thomas .It Pa /etc/gotd.conf
192 3efd8e31 2022-10-23 thomas Location of the
193 3efd8e31 2022-10-23 thomas .Nm
194 3efd8e31 2022-10-23 thomas configuration file.
195 3efd8e31 2022-10-23 thomas .El
196 3efd8e31 2022-10-23 thomas .Sh EXAMPLES
197 3efd8e31 2022-10-23 thomas .Bd -literal -offset indent
198 3efd8e31 2022-10-23 thomas # Default unix_group and user values:
199 3efd8e31 2022-10-23 thomas unix_group _gotsh
200 3efd8e31 2022-10-23 thomas user _gotd
201 3efd8e31 2022-10-23 thomas 
202 3efd8e31 2022-10-23 thomas # This repository can be accessed via ssh://user@example.com/src
203 3efd8e31 2022-10-23 thomas repository "src" {
204 3efd8e31 2022-10-23 thomas 	path "/var/git/src.git"
205 729a7e24 2022-11-17 thomas 	permit rw flan_hacker
206 729a7e24 2022-11-17 thomas 	permit rw :developers
207 729a7e24 2022-11-17 thomas 	permit ro anonymous
208 3efd8e31 2022-10-23 thomas }
209 3efd8e31 2022-10-23 thomas 
210 3efd8e31 2022-10-23 thomas # This repository can be accessed via
211 3efd8e31 2022-10-23 thomas # ssh://user@example.com/openbsd/ports
212 3efd8e31 2022-10-23 thomas repository "openbsd/ports" {
213 3efd8e31 2022-10-23 thomas 	path "/var/git/ports.git"
214 729a7e24 2022-11-17 thomas 	permit rw :porters
215 729a7e24 2022-11-17 thomas 	permit ro anonymous
216 729a7e24 2022-11-17 thomas 	deny flan_hacker
217 3efd8e31 2022-10-23 thomas }
218 0781db0e 2023-01-06 thomas 
219 0781db0e 2023-01-06 thomas # Use a larger request timeout value:
220 77d755e8 2023-01-06 thomas connection request timeout 2h
221 0781db0e 2023-01-06 thomas 
222 0781db0e 2023-01-06 thomas # Some users are granted a higher concurrent connection limit:
223 0781db0e 2023-01-06 thomas connection {
224 0781db0e 2023-01-06 thomas 	limit user flan_hacker 16
225 0781db0e 2023-01-06 thomas 	limit user anonymous 32
226 0781db0e 2023-01-06 thomas }
227 3efd8e31 2022-10-23 thomas .Ed
228 3efd8e31 2022-10-23 thomas .Sh SEE ALSO
229 3efd8e31 2022-10-23 thomas .Xr got 1 ,
230 3efd8e31 2022-10-23 thomas .Xr gotsh 1 ,
231 3efd8e31 2022-10-23 thomas .Xr group 5 ,
232 3efd8e31 2022-10-23 thomas .Xr gotd 8