commit - 3524325ce33e833a8463f6c1589dff7c8684f040
commit + 669a3652b2199ce4c9a73b6bb4f6c1a6a9185957
blob - /dev/null
blob + 29ef49d47f77689f73bf132c16476a2ae949c029 (mode 644)
--- /dev/null
+++ gotsys/gotsys.conf.5
+.\"
+.\" Copyright (c) 2024 Stefan Sperling <stsp@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate$
+.Dt GOTSYS.CONF 5
+.Os
+.Sh NAME
+.Nm gotsys.conf
+.Nd gotsys configuration file
+.Sh DESCRIPTION
+.Nm
+is the run-time configuration file for
+.Xr gotsys 8 .
+.Pp
+The file format is line-based, with one configuration directive per line.
+Any lines beginning with a
+.Sq #
+are treated as comments and ignored.
+.Sh GLOBAL CONFIGURATION
+ The available global configuration directives are as follows:
+.Bl -tag -width Ds
+.It Ic group Ar name
+Declare a group with the given
+.Ar name .
+Users can then be granted membership of this group in order to manage
+repository access rules on a per-group basis.
+.It Ic user Ar name
+Declare a user which can then be granted access to specific repositories.
+.Pp
+A user must be declared with a unique
+.Ar name ,
+followed by user-specific configuration directives inside curly braces:
+.Pp
+.Ic user Ar name Brq ...
+.Pp
+The available
+.Cm user
+parameters are as follows:
+.Bl -tag -width Ds
+.It Ic group Ar group
+Make the user a member of the given
+.Ar group .
+This directive may be specified multiple times to add the user to
+multiple groups.
+All groups listed here must already have been declared with the
+.Ic group
+directive.
+.It Ic password Ar string
+Set a password for the user.
+The
+.Ar string
+argument must be an encrypted password string, as generated by OpenBSD's
+.Xr encrypt 1
+command.
+If not specified, password-based authentication will be disabled for this user.
+.It Ic allow-empty-password
+Allow this user to authenticate with an empty password.
+This must only be used for accounts which represent an anonymous user for
+public read-only repository access.
+.Xr gotsys 1
+will reject any attempts to grant write access to this user.
+.It Ic ssh-pubkey Ar type Ar key
+Allow the user to authenticate with an SSH public key.
+.Pp
+The key
+.Ar type
+argument must be
+.Ic ecdsa ,
+.Ic ecdsa-sk ,
+.Ic ed25519 ,
+.Ic ed25519-sk ,
+or
+.Ic rsa .
+The
+.Ar key
+argument is the public key which will be added to the user's
+.Xr ssh 1
+.Pa authorized_keys
+file.
+.Pp
+This directive may be specified multiple times to allow the user to
+authenticate with multiple keys.
+.Pp
+Two-factor authentication with FIDO keys can be enforced by only
+adding SSH keys of
+.Ar type
+.Ic ecdsa-sk
+or
+.Ic ed25519-sk .
+.El
+.\" Set the path to the unix socket which
+.\" .Xr gotd 8
+.\" should listen on.
+.\" If not specified, the path
+.\" .Pa /var/run/gotd.sock
+.\" will be used.
+.\" .It Ic user Ar user
+.\" Set the
+.\" .Ar user
+.\" which will run
+.\" .Xr gotd 8 .
+.\" Initially,
+.\" .Xr gotd 8
+.\" requires root privileges in order to create its unix socket.
+.\" Afterwards,
+.\" .Xr gotd 8
+.\" drops privileges to the specified
+.\" .Ar user .
+.\" If not specified, the user _gotd will be used.
+.El
+.Sh REPOSITORY CONFIGURATION
+At least one repository context must exist for
+.Xr gotsys 8
+to function.
+For each repository, access rules must be configured using the
+.Ic permit
+and
+.Ic deny
+configuration directives.
+Multiple access rules can be specified, and the last matching rule
+determines the action taken.
+If no rule matches, access to the repository is denied.
+.Pp
+A repository context is declared with a unique
+.Ar name ,
+followed by repository-specific configuration directives inside curly braces:
+.Pp
+.Ic repository Ar name Brq ...
+.Pp
+If desired, the
+.Ar name
+may contain path-separators,
+.Dq / ,
+to expose repositories as part of a virtual client-visible directory hierarchy.
+.Pp
+The available repository configuration directives are as follows:
+.Bl -tag -width Ds
+.It Ic deny Ar identity
+Deny repository access to users with the username
+.Ar identity .
+Group names may be matched by prepending a colon
+.Pq Sq \&:
+to
+.Ar identity .
+.It Ic permit Ar mode Ar identity
+Permit repository access to users with the username
+.Ar identity .
+The
+.Ar mode
+argument must be set to either
+.Ic ro
+for read-only access,
+or
+.Ic rw
+for read-write access.
+Group names may be matched by prepending a colon
+.Pq Sq \&:
+to
+.Ar identity .
+.It Ic protect Brq Ar ...
+The
+.Cm protect
+directive may be used to protect branches and tags in a repository
+from being overwritten by potentially destructive client-side commands,
+such as when
+.Cm got send -f
+and
+.Cm git push -f
+are used to change the history of a branch.
+.Pp
+To build a set of protected branches and tags, multiple
+.Ic protect
+directives may be specified per repository and
+multiple
+.Ic protect
+directive parameters may be specified within curly braces.
+.Pp
+The available
+.Cm protect
+parameters are as follows:
+.Bl -tag -width Ds
+.It Ic branch Ar name
+Protect the named branch.
+The branch may be created if it does not exist yet.
+Attempts to delete the branch or change its history will be denied.
+.Pp
+If the
+.Ar name
+does not already begin with
+.Dq refs/heads/
+it will be looked up in the
+.Dq refs/heads/
+reference namespace.
+.It Ic branch Ic namespace Ar namespace
+Protect the given reference namespace, assuming that references in
+this namespace represent branches.
+New branches may be created in the namespace.
+Attempts to change the history of branches or delete them will be denied.
+.Pp
+The
+.Ar namespace
+argument must be absolute, starting with
+.Dq refs/ .
+.It Ic tag Ic namespace Ar namespace
+Protect the given reference namespace, assuming that references in
+this namespace represent tags.
+New tags may be created in the namespace.
+Attempts to change or delete existing tags will be denied.
+.Pp
+The
+.Ar namespace
+argument must be absolute, starting with
+.Dq refs/ .
+.El
+.Pp
+The special reference namespaces
+.Dq refs/got/
+and
+.Dq refs/remotes/
+do not need to be listed in
+.Nm .
+These namespaces are always protected and even attempts to create new
+references in these namespaces will always be denied.
+.It Ic notify Brq Ar ...
+The
+.Ic notify
+directive enables notifications about new commits or tags
+added to the repository.
+.Pp
+The default content of email notifications looks similar to the output of the
+.Cm got log -d
+command.
+.Pp
+Notifications via HTTP require a HTTP or HTTPS server which is accepting
+POST requests with or without HTTP Basic authentication.
+Depending on the use case a custom server-side CGI script may be required
+for the processing of notifications.
+HTTP notifications can achieve functionality
+similar to Git's server-side post-receive hook script
+by triggering arbitrary post-commit actions via the HTTP server.
+.Pp
+The
+.Ic notify
+directive expects parameters which must be enclosed in curly braces.
+The available parameters are as follows:
+.Bl -tag -width Ds
+.It Ic branch Ar name
+Send notifications about commits to the named branch.
+The
+.Ar name
+will be looked up in the
+.Dq refs/heads/
+reference namespace.
+This directive may be specified multiple times to build a list of
+branches to send notifications for.
+If neither a
+.Ic branch
+nor a
+.Ic reference namespace
+are specified then changes to any reference will trigger notifications.
+.It Ic reference Ic namespace Ar namespace
+Send notifications about commits or tags within a reference namespace.
+This directive may be specified multiple times to build a list of
+namespaces to send notifications for.
+If neither a
+.Ic branch
+nor a
+.Ic reference namespace
+are specified then changes to any reference will trigger notifications.
+.It Ic email Ic to Ar recipient Oo Ic reply to Ar responder Oc
+Send notifications via email to the specified
+.Ar recipient .
+This directive may be specified multiple times to build a list of
+recipients to send notifications to.
+.Pp
+The
+.Ar recipient
+must be an email addresses that accepts mail.
+.Pp
+If a
+.Ar responder
+is specified via the
+.Ic reply to
+directive, the
+.Ar responder
+will be used as the Reply-to address.
+Setting the Reply-to header can be useful if replies should go to a
+mailing list instead of the
+.Ar sender ,
+for example.
+.It Ic url Ar URL Oo Ic user Ar user Ic password Ar password Oo Ic insecure Oc Oc
+Send notifications via HTTP.
+This directive may be specified multiple times to build a list of
+HTTP servers to send notifications to.
+.Pp
+The notification will be sent as a POST request to the given
+.Ar URL ,
+which must be a valid HTTP URL and begin with either
+.Dq http://
+or
+.Dq https:// .
+If HTTPS is used, sending of notifications will only succeed if
+no TLS errors occur.
+.Pp
+The optional
+.Ic user
+and
+.Ic password
+directives enable HTTP Basic authentication.
+If used, both a
+.Ar user
+and a
+.Ar password
+must be specified.
+The
+.Ar password
+must not be an empty string.
+Unless the
+.Ic insecure
+option is specified the notification target
+.Ar URL
+must be a
+.Dq https://
+URL to avoid leaking of authentication credentials.
+.Pp
+The request body contains a JSON object with a
+.Dq notifications
+property containing an array of notification objects.
+This JSON format is documented in
+.Xr gotd 8 .
+.El
+.It Ic publish
+The
+.Ic publish
+directive controls whether this repository will be published
+via a web frontend for public browsing.
+.Pp
+If not set, the repository can only be accessed via
+.Xr ssh 1 .
+The repository can still be made publicly available over SSH
+with an anonymous read-only user who uses an empty password.
+.El
+.Sh EXAMPLES
+.Bd -literal -offset indent
+group developers
+group porters
+
+user anonymous {
+ allow-empty-password
+}
+
+user flan_hacker {
+ password "$2b$08$CFWp/ZC.DQi34.iHBgRzBerTzEGB9WY9tDN1CLCbPUpGC.fmNi4Ea"
+ group developers
+}
+
+user flan_squee {
+ group porters
+ ssh-pubkey ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAQ2ZWscmMeCYLwm07gDSf0jApFJ58bMNxiErDqUrFz4
+}
+
+repository "src" {
+ publish
+
+ permit rw :developers
+ permit ro anonymous
+
+ protect branch "main"
+ protect tag namespace "refs/tags/"
+}
+
+repository "openbsd/ports" {
+ publish
+
+ permit rw :porters
+ permit ro anonymous
+ deny flan_hacker
+
+ protect {
+ branch "main"
+ tag namespace "refs/tags/"
+ }
+
+ notify {
+ branch "main"
+ reference namespace "refs/tags/"
+ email to openbsd-ports-changes@example.com
+ }
+}
+
+repository "secret" {
+ permit rw flan_hacker
+
+ protect branch "main"
+ protect tag namespace "refs/tags/"
+}
+.Ed
+.Sh SEE ALSO
+.Xr got 1 ,
+.Xr gotd 8 ,
+.Xr gotsys 8
