1 13b2bc37 2022-10-23 stsp .\"
  2 13b2bc37 2022-10-23 stsp .\" Copyright (c) 2022 Stefan Sperling <stsp@openbsd.org>
  3 13b2bc37 2022-10-23 stsp .\"
  4 13b2bc37 2022-10-23 stsp .\" Permission to use, copy, modify, and distribute this software for any
  5 13b2bc37 2022-10-23 stsp .\" purpose with or without fee is hereby granted, provided that the above
  6 13b2bc37 2022-10-23 stsp .\" copyright notice and this permission notice appear in all copies.
  7 13b2bc37 2022-10-23 stsp .\"
  8 13b2bc37 2022-10-23 stsp .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  9 13b2bc37 2022-10-23 stsp .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 10 13b2bc37 2022-10-23 stsp .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 11 13b2bc37 2022-10-23 stsp .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 12 13b2bc37 2022-10-23 stsp .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 13 13b2bc37 2022-10-23 stsp .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 14 13b2bc37 2022-10-23 stsp .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 15 13b2bc37 2022-10-23 stsp .\"
 16 13b2bc37 2022-10-23 stsp .Dd $Mdocdate$
 17 13b2bc37 2022-10-23 stsp .Dt GOTD.CONF 5
 18 13b2bc37 2022-10-23 stsp .Os
 19 13b2bc37 2022-10-23 stsp .Sh NAME
 20 13b2bc37 2022-10-23 stsp .Nm gotd.conf
 21 13b2bc37 2022-10-23 stsp .Nd gotd configuration file
 22 13b2bc37 2022-10-23 stsp .Sh DESCRIPTION
 23 13b2bc37 2022-10-23 stsp .Nm
 24 13b2bc37 2022-10-23 stsp is the run-time configuration file for
 25 13b2bc37 2022-10-23 stsp .Xr gotd 8 .
 26 13b2bc37 2022-10-23 stsp .Pp
 27 13b2bc37 2022-10-23 stsp The file format is line-based, with one configuration directive per line.
 28 13b2bc37 2022-10-23 stsp Any lines beginning with a
 29 13b2bc37 2022-10-23 stsp .Sq #
 30 13b2bc37 2022-10-23 stsp are treated as comments and ignored.
 31 13b2bc37 2022-10-23 stsp .Sh GLOBAL CONFIGURATION
 32 13b2bc37 2022-10-23 stsp The available global configuration directives are as follows:
 33 13b2bc37 2022-10-23 stsp .Bl -tag -width Ds
 34 13b2bc37 2022-10-23 stsp .It Ic unix_socket Ar path
 35 13b2bc37 2022-10-23 stsp Set the path to the unix socket which
 36 13b2bc37 2022-10-23 stsp .Xr gotd 8
 37 13b2bc37 2022-10-23 stsp should listen on.
 38 13b2bc37 2022-10-23 stsp If not specified, the path
 39 13b2bc37 2022-10-23 stsp .Pa /var/run/gotd.sock
 40 13b2bc37 2022-10-23 stsp will be used.
 41 13b2bc37 2022-10-23 stsp .It Ic unix_group Ar group
 42 13b2bc37 2022-10-23 stsp Set the
 43 13b2bc37 2022-10-23 stsp .Ar group ,
 44 13b2bc37 2022-10-23 stsp defined in the
 45 13b2bc37 2022-10-23 stsp .Xr group 5
 46 13b2bc37 2022-10-23 stsp file, which is allowed to access
 47 13b2bc37 2022-10-23 stsp .Xr gotd 8
 48 13b2bc37 2022-10-23 stsp via
 49 13b2bc37 2022-10-23 stsp .Xr gotsh 1 .
 50 13b2bc37 2022-10-23 stsp The
 51 13b2bc37 2022-10-23 stsp .Xr gotd 8
 52 13b2bc37 2022-10-23 stsp user must be a secondary member of this group.
 53 13b2bc37 2022-10-23 stsp If not specified, the group _gotsh will be used.
 54 13b2bc37 2022-10-23 stsp .It Ic user Ar user
 55 13b2bc37 2022-10-23 stsp Set the
 56 13b2bc37 2022-10-23 stsp .Ar user
 57 13b2bc37 2022-10-23 stsp which will run
 58 13b2bc37 2022-10-23 stsp .Xr gotd 8 .
 59 13b2bc37 2022-10-23 stsp Initially,
 60 13b2bc37 2022-10-23 stsp .Xr gotd 8
 61 eec68231 2022-12-14 stsp requires root privileges in order to create its unix socket.
 62 13b2bc37 2022-10-23 stsp Afterwards,
 63 13b2bc37 2022-10-23 stsp .Xr gotd 8
 64 13b2bc37 2022-10-23 stsp drops privileges to the specified
 65 13b2bc37 2022-10-23 stsp .Ar user .
 66 13b2bc37 2022-10-23 stsp If not specified, the user _gotd will be used.
 67 13b2bc37 2022-10-23 stsp .El
 68 13b2bc37 2022-10-23 stsp .Sh REPOSITORY CONFIGURATION
 69 13b2bc37 2022-10-23 stsp At least one repository context must exist for
 70 13b2bc37 2022-10-23 stsp .Xr gotd 8
 71 13b2bc37 2022-10-23 stsp to function.
 72 0ccf3acb 2022-11-16 stsp For each repository, access rules must be configured using the
 73 0ccf3acb 2022-11-16 stsp .Ic permit
 74 0ccf3acb 2022-11-16 stsp and
 75 0ccf3acb 2022-11-16 stsp .Ic deny
 76 0ccf3acb 2022-11-16 stsp configuration directives.
 77 0ccf3acb 2022-11-16 stsp Multiple access rules can be specified, and the last matching rule
 78 0ccf3acb 2022-11-16 stsp determines the action taken.
 79 0ccf3acb 2022-11-16 stsp If no rule matches, access to the repository is denied.
 80 13b2bc37 2022-10-23 stsp .Pp
 81 13b2bc37 2022-10-23 stsp A repository context is declared with a unique
 82 13b2bc37 2022-10-23 stsp .Ar name ,
 83 13b2bc37 2022-10-23 stsp followed by repository-specific configuration directives inside curly braces:
 84 13b2bc37 2022-10-23 stsp .Pp
 85 13b2bc37 2022-10-23 stsp .Ic repository Ar name Brq ...
 86 13b2bc37 2022-10-23 stsp .Pp
 87 13b2bc37 2022-10-23 stsp .Xr got 1
 88 13b2bc37 2022-10-23 stsp and
 89 13b2bc37 2022-10-23 stsp .Xr git 1
 90 13b2bc37 2022-10-23 stsp clients can connect to a repository by including the repository's unique
 91 13b2bc37 2022-10-23 stsp .Ar name
 92 13b2bc37 2022-10-23 stsp in the request URL.
 93 13b2bc37 2022-10-23 stsp Clients appending the string
 94 13b2bc37 2022-10-23 stsp .Dq .git
 95 13b2bc37 2022-10-23 stsp to the
 96 13b2bc37 2022-10-23 stsp .Ar name
 97 13b2bc37 2022-10-23 stsp will also be accepted.
 98 13b2bc37 2022-10-23 stsp .Pp
 99 13b2bc37 2022-10-23 stsp If desired, the
100 13b2bc37 2022-10-23 stsp .Ar name
101 13b2bc37 2022-10-23 stsp may contain path-separators,
102 13b2bc37 2022-10-23 stsp .Dq / ,
103 13b2bc37 2022-10-23 stsp to expose repositories as part of a virtual client-visible directory hierarchy.
104 13b2bc37 2022-10-23 stsp .Pp
105 13b2bc37 2022-10-23 stsp The available repository configuration directives are as follows:
106 13b2bc37 2022-10-23 stsp .Bl -tag -width Ds
107 0ccf3acb 2022-11-16 stsp .It Ic deny Ar identity
108 0ccf3acb 2022-11-16 stsp Deny repository access to users with the username
109 0ccf3acb 2022-11-16 stsp .Ar identity .
110 0ccf3acb 2022-11-16 stsp Group names may be matched by prepending a colon
111 0ccf3acb 2022-11-16 stsp .Pq Sq \&:
112 0ccf3acb 2022-11-16 stsp to
113 0ccf3acb 2022-11-16 stsp .Ar identity .
114 0ccf3acb 2022-11-16 stsp Numeric IDs are also accepted.
115 13b2bc37 2022-10-23 stsp .It Ic path Ar path
116 13b2bc37 2022-10-23 stsp Set the path to the Git repository.
117 0ccf3acb 2022-11-16 stsp .It Ic permit Ar mode Ar identity
118 0ccf3acb 2022-11-16 stsp Permit repository access to users with the username
119 0ccf3acb 2022-11-16 stsp .Ar identity .
120 0ccf3acb 2022-11-16 stsp The
121 0ccf3acb 2022-11-16 stsp .Ar mode
122 0ccf3acb 2022-11-16 stsp argument must be set to either
123 0ccf3acb 2022-11-16 stsp .Ic ro
124 0ccf3acb 2022-11-16 stsp for read-only access,
125 0ccf3acb 2022-11-16 stsp or
126 0ccf3acb 2022-11-16 stsp .Ic rw
127 0ccf3acb 2022-11-16 stsp for read-write access.
128 0ccf3acb 2022-11-16 stsp Group names may be matched by prepending a colon
129 0ccf3acb 2022-11-16 stsp .Pq Sq \&:
130 0ccf3acb 2022-11-16 stsp to
131 0ccf3acb 2022-11-16 stsp .Ar identity .
132 0ccf3acb 2022-11-16 stsp Numeric IDs are also accepted.
133 4eb4de73 2022-11-14 op .El
134 13b2bc37 2022-10-23 stsp .Sh FILES
135 13b2bc37 2022-10-23 stsp .Bl -tag -width Ds -compact
136 13b2bc37 2022-10-23 stsp .It Pa /etc/gotd.conf
137 13b2bc37 2022-10-23 stsp Location of the
138 13b2bc37 2022-10-23 stsp .Nm
139 13b2bc37 2022-10-23 stsp configuration file.
140 13b2bc37 2022-10-23 stsp .El
141 13b2bc37 2022-10-23 stsp .Sh EXAMPLES
142 13b2bc37 2022-10-23 stsp .Bd -literal -offset indent
143 13b2bc37 2022-10-23 stsp # Default unix_group and user values:
144 13b2bc37 2022-10-23 stsp unix_group _gotsh
145 13b2bc37 2022-10-23 stsp user _gotd
146 13b2bc37 2022-10-23 stsp 
147 13b2bc37 2022-10-23 stsp # This repository can be accessed via ssh://user@example.com/src
148 13b2bc37 2022-10-23 stsp repository "src" {
149 13b2bc37 2022-10-23 stsp 	path "/var/git/src.git"
150 0ccf3acb 2022-11-16 stsp 	permit rw flan_hacker
151 0ccf3acb 2022-11-16 stsp 	permit rw :developers
152 0ccf3acb 2022-11-16 stsp 	permit ro anonymous
153 13b2bc37 2022-10-23 stsp }
154 13b2bc37 2022-10-23 stsp 
155 13b2bc37 2022-10-23 stsp # This repository can be accessed via
156 13b2bc37 2022-10-23 stsp # ssh://user@example.com/openbsd/ports
157 13b2bc37 2022-10-23 stsp repository "openbsd/ports" {
158 13b2bc37 2022-10-23 stsp 	path "/var/git/ports.git"
159 0ccf3acb 2022-11-16 stsp 	permit rw :porters
160 0ccf3acb 2022-11-16 stsp 	permit ro anonymous
161 0ccf3acb 2022-11-16 stsp 	deny flan_hacker
162 13b2bc37 2022-10-23 stsp }
163 13b2bc37 2022-10-23 stsp .Ed
164 13b2bc37 2022-10-23 stsp .Sh SEE ALSO
165 13b2bc37 2022-10-23 stsp .Xr got 1 ,
166 13b2bc37 2022-10-23 stsp .Xr gotsh 1 ,
167 13b2bc37 2022-10-23 stsp .Xr group 5 ,
168 13b2bc37 2022-10-23 stsp .Xr gotd 8