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