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