commit 669a3652b2199ce4c9a73b6bb4f6c1a6a9185957 from: Stefan Sperling date: Tue Jun 25 15:01:51 2024 UTC first draft of gotsys.conf manual commit - 3524325ce33e833a8463f6c1589dff7c8684f040 commit + 669a3652b2199ce4c9a73b6bb4f6c1a6a9185957 blob - /dev/null blob + 29ef49d47f77689f73bf132c16476a2ae949c029 (mode 644) --- /dev/null +++ gotsys/gotsys.conf.5 @@ -0,0 +1,413 @@ +.\" +.\" Copyright (c) 2024 Stefan Sperling +.\" +.\" 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