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 unix_socket Ar path
35 Set the path to the unix socket which
36 .Xr gotd 8
37 should listen on.
38 If not specified, the path
39 .Pa /var/run/gotd.sock
40 will be used.
41 .It Ic unix_group Ar group
42 Set the
43 .Ar group ,
44 defined in the
45 .Xr group 5
46 file, which is allowed to access
47 .Xr gotd 8
48 via
49 .Xr gotsh 1 .
50 The
51 .Xr gotd 8
52 user must be a secondary member of this group.
53 If not specified, the group _gotsh will be used.
54 .It Ic user Ar user
55 Set the
56 .Ar user
57 which will run
58 .Xr gotd 8 .
59 Initially,
60 .Xr gotd 8
61 requires root privileges in order to create its unix socket and start
62 child processes in a
63 .Xr chroot 2
64 environment.
65 Afterwards,
66 .Xr gotd 8
67 drops privileges to the specified
68 .Ar user .
69 If not specified, the user _gotd will be used.
70 .El
71 .Sh REPOSITORY CONFIGURATION
72 At least one repository context must exist for
73 .Xr gotd 8
74 to function.
75 For each repository, access rules must be configured using the
76 .Ic permit
77 and
78 .Ic deny
79 configuration directives.
80 Multiple access rules can be specified, and the last matching rule
81 determines the action taken.
82 If no rule matches, access to the repository is denied.
83 .Pp
84 A repository context is declared with a unique
85 .Ar name ,
86 followed by repository-specific configuration directives inside curly braces:
87 .Pp
88 .Ic repository Ar name Brq ...
89 .Pp
90 .Xr got 1
91 and
92 .Xr git 1
93 clients can connect to a repository by including the repository's unique
94 .Ar name
95 in the request URL.
96 Clients appending the string
97 .Dq .git
98 to the
99 .Ar name
100 will also be accepted.
101 .Pp
102 If desired, the
103 .Ar name
104 may contain path-separators,
105 .Dq / ,
106 to expose repositories as part of a virtual client-visible directory hierarchy.
107 .Pp
108 The available repository configuration directives are as follows:
109 .Bl -tag -width Ds
110 .It Ic deny Ar identity
111 Deny repository access to users with the username
112 .Ar identity .
113 Group names may be matched by prepending a colon
114 .Pq Sq \&:
115 to
116 .Ar identity .
117 Numeric IDs are also accepted.
118 .It Ic path Ar path
119 Set the path to the Git repository.
120 .It Ic permit Ar mode Ar identity
121 Permit repository access to users with the username
122 .Ar identity .
123 The
124 .Ar mode
125 argument must be set to either
126 .Ic ro
127 for read-only access,
128 or
129 .Ic rw
130 for read-write access.
131 Group names may be matched by prepending a colon
132 .Pq Sq \&:
133 to
134 .Ar identity .
135 Numeric IDs are also accepted.
136 .El
137 .Sh FILES
138 .Bl -tag -width Ds -compact
139 .It Pa /etc/gotd.conf
140 Location of the
141 .Nm
142 configuration file.
143 .El
144 .Sh EXAMPLES
145 .Bd -literal -offset indent
146 # Default unix_group and user values:
147 unix_group _gotsh
148 user _gotd
149 
150 # This repository can be accessed via ssh://user@example.com/src
151 repository "src" {
152 	path "/var/git/src.git"
153 	permit rw flan_hacker
154 	permit rw :developers
155 	permit ro anonymous
156 }
157 
158 # This repository can be accessed via
159 # ssh://user@example.com/openbsd/ports
160 repository "openbsd/ports" {
161 	path "/var/git/ports.git"
162 	permit rw :porters
163 	permit ro anonymous
164 	deny flan_hacker
165 }
166 .Ed
167 .Sh SEE ALSO
168 .Xr got 1 ,
169 .Xr gotsh 1 ,
170 .Xr group 5 ,
171 .Xr gotd 8